| name | ui-finesse-workflow |
| description | Master workflow for building exceptional UIs. Use when starting UI work, building components, or when the user asks about the development process for interfaces. |
UI Finesse Workflow
You are following the UI Finesse Playbook workflow for building exceptional user interfaces.
Phase 0: Mode Detection
Before starting, determine which mode applies:
Enhancement Mode (Existing Component Library)
Detected when ANY of these are true:
components/ui/button.tsx exists (shadcn/ui pattern)@radix-ui/* packages in dependencies@headlessui/* packages in dependencies
Standalone Mode (Greenfield)
Detected when NONE of the above are present.
Phase 1: Context Gathering
ALWAYS start here before building UI.
If no design context exists, gather:
- Target audience and use cases
- Brand personality (3 words)
- Aesthetic direction and references
- Anti-references (what to avoid)
Phase 2: Foundation
Standalone Mode
- Use design tokens from
/tokens/ if present
- Follow composition patterns in
/patterns/composition.md
- Follow theme architecture in
/patterns/theming.md
Enhancement Mode
- Use the library's existing token system
- Follow extension patterns in
/patterns/extension.md
- Reference
/patterns/elevation.md for transcending defaults
Phase 3: Building
For every component:
- Consult the
frontend-design skill for aesthetic direction
- Follow
interface-guidelines skill for interaction patterns
- Reference
/docs/ for specific techniques
- Use composition over duplication
Phase 4: Refinement
After building:
- Run
design-polish skill for systematic final pass
- Run
design-review skill for accessibility verification
Phase 5: Quality Gate
Before shipping, verify:
- All checklist items from
ui-checklist.md
- No critical accessibility issues
- Passes the "AI slop test" (doesn't look generic)
Quick Reference
| Need | Resource |
|---|
| Aesthetic direction | frontend-design skill |
| Interaction patterns | interface-guidelines skill |
| Final polish | design-polish skill |
| Accessibility review | design-review skill |
| Visual techniques | /docs/ best practices |
| Extension patterns | /patterns/extension.md |
| DRY principles | /patterns/composition.md |
Anti-Patterns to Avoid
Building
- Starting without design context
- Copying styles instead of wrapping components
- Hardcoding colors/spacing instead of using tokens
Aesthetics
- Generic "AI slop" (purple gradients, glowing accents, Inter font)
- Glassmorphism everywhere
- Same-sized card grids
- Gradient text on metrics
