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

1. •Use design tokens from /tokens/ if present
2. •Follow composition patterns in /patterns/composition.md
3. •Follow theme architecture in /patterns/theming.md

Enhancement Mode

1. •Use the library's existing token system
2. •Follow extension patterns in /patterns/extension.md
3. •Reference /patterns/elevation.md for transcending defaults

Phase 3: Building

For every component:

1. •Consult the frontend-design skill for aesthetic direction
2. •Follow interface-guidelines skill for interaction patterns
3. •Reference /docs/ for specific techniques
4. •Use composition over duplication

Phase 4: Refinement

After building:

1. •Run design-polish skill for systematic final pass
2. •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

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