| name | ui-ux-design |
| description | Project-aware expert-role for frontend UI/UX design and implementation. Reads project docs first, enforces design systems, responsive bounds, accessibility, and visual testing constraints. |
| argument-hint | Describe the component, page, or interaction to build or review |
ui-ux-design
Produces a project-aware, expert-level frontend implementation by reading the repository's project docs first, then applying a rigorous component-driven methodology.
This skill is reusable across any frontend framework (React, Vue, Svelte, plain HTML/CSS) or styling solution (Tailwind, CSS Modules, Styled Components).
It should not assume a specific component library (like Material UI) or styling engine until the project docs confirm them.
Required Project Inputs
| Document | Why it matters |
|---|
docs/project-docs/development/ui-ux.md | Defines the design system, color palette, typography, accessibility (a11y) targets, and responsive breakpoints. |
docs/project-docs/foundation/prd.md | Clarifies the target audience and expected user flows. |
docs/project-docs/foundation/architecture.md | Defines where state management lives versus pure presentation components. |
docs/project-docs/development/testing.md | Defines how the UI should be validated (e.g., unit tests, visual regression, e2e). |
If the repository lacks the UI docs needed for styling or layout, call that out and create or update the missing docs instead of inventing arbitrary colors or padding values.
When to Use
Use this skill when building or reviewing one of these boundary types:
| Boundary type | Typical artifacts |
|---|
| Presentation Component | Buttons, inputs, cards, typography components. |
| Layout / Page | Grid structures, responsive containers, navigation shells. |
| Interaction / Animation | Modals, dropdowns, transitions, hover states. |
| State-Connected Component | Forms, data tables, fetching wrappers. |
Procedure
Step 1 — Extract Design Constraints
Extract from ui-ux.md:
- CSS variables, Tailwind config, or design token values.
- Responsive breakpoints (e.g., mobile-first vs desktop-first).
- Required a11y standards (e.g., WCAG AA).
Step 2 — Separate State from Presentation
Extract from architecture.md:
- Identify if this component is "dumb" (presentation only) or "smart" (data fetching/stateful).
- Do not mix complex global state logic into a simple presentational button.
Step 3 — Design for Edge Cases
Before writing HTML/CSS, define:
- Empty states (what if the data array is empty?)
- Loading states (skeletons vs spinners).
- Error states (inline validation vs toast notifications).
- Overflow states (what if the text is 100 characters long?).
Step 4 — Implement with Accessibility (A11y)
Ensure the implementation includes:
- Proper semantic HTML (
<button> instead of <div onClick>).
- ARIA labels where semantics fall short.
- Keyboard navigation support (focus states).
- Sufficient color contrast.
Step 5 — Verify Responsive Behavior
Write the code to adapt gracefully across the breakpoints defined in ui-ux.md. Ensure touch targets are large enough on mobile.
Step 6 — Define Verification Requirements
Use testing.md to decide how this will be validated.
Examples:
- Component tests (e.g., React Testing Library) asserting ARIA roles.
- Storybook stories for visual isolation.
Quality Check
- Does it use hardcoded hex colors or arbitrary pixel values instead of the design system tokens?
- Is it accessible via keyboard only?
- Does it break layout on mobile screens?
- Are loading and error states handled gracefully?
- Is state managed at the correct architectural layer?
Anti-Pattern
- Inventing new colors, fonts, padding, and any other relevant values that aren't in
ui-ux.md.
- Writing
<div onClick={...}> instead of semantic interactive elements.
- Ignoring loading/error states in asynchronous components.
- Coupling global state management (like Redux or Zustand) directly into low-level UI components.
Output Contract
When using this skill, the output should include:
- the project docs consulted (specifically the design system tokens)
- the component API (props/inputs)
- the implementation code (separated by state vs presentation if applicable)
- the edge cases handled (loading, empty, error, overflow)
- accessibility and responsive verification steps
Neutral Prompt Shape
@agent use ui-ux-design on [Target Theme/Tokens] focusing on [Specific Branding/Accessibility Goal].
Example Prompt
- "Implement this presentational card component using the project design tokens."
- "Review this stateful component for accessibility and responsive layout issues."
