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