UI System
Reuse what the app already has. Don't invent a parallel UI kit.
Do
- Read
DESIGN.md / area docs for the surface you're in.
- Find the existing component/helper (button, input, dialog, progress,
relative-time, dropdown, back row, …). Copy how Settings / Projects / etc.
already do it.
- Prefer a variant on an existing primitive over a new component.
- Colors/spacing/type from existing CSS vars / tokens (including the
app's Tailwind v4 setup). No one-off hex/shadow stacks.
- Match the app's look: if the app doesn't use borders/shadows/sparkles,
neither does your feature.
Don't
- New button/input/modal implementations
- Local color palettes or decorative chrome
- Duplicate formatters (time, etc.) — use the shared ones
- New borders, backgrounds, shadows, sparkles, or badges the surrounding app
doesn't already use — match the neighboring surface exactly
- Section chrome that nowhere else uses
Working from a design
Figma file, mock, or screenshot: match it — spacing, contrast, placement —
before inventing anything.
- Pull the design context (Figma MCP if available, else the screenshot/mock).
- Map it to existing primitives and tokens before building anything new.
- Layout and structure first, then content.
- Match spacing, padding, contrast, and states exactly. Check the details —
no white-on-white, no doubled padding, correct CTA contrast.
- Optimize exported assets (SVGO for SVGs).
- Don't approximate spacing or colors the design specifies, and don't add
chrome neither the design nor the app has.
If you can't find the primitive, search harder or ask — don't quietly make one.
While still iterating on look, follow ui-only (no tsc/lint/commit yet). Once
they like it, confirm against the design with visual-verify.
1---2name: ui-system3description: Reuse existing UI primitives, CSS vars, and DESIGN.md patterns instead of inventing new buttons, colors, borders, shadows, or helpers — including when implementing a Figma file, mock, or screenshot. Use for Desktop/web/TUI UI work, redesigns, or when the user mentions shared primitives, tw4, Figma, or UI patterns.4---56# UI System78Reuse what the app already has. Don't invent a parallel UI kit.910## Do11121. Read `DESIGN.md` / area docs for the surface you're in.132. Find the existing component/helper (button, input, dialog, progress,14 relative-time, dropdown, back row, …). Copy how Settings / Projects / etc.15 already do it.163. Prefer a **variant** on an existing primitive over a new component.174. Colors/spacing/type from **existing CSS vars / tokens** (including the18 app's Tailwind v4 setup). No one-off hex/shadow stacks.195. Match the app's look: if the app doesn't use borders/shadows/sparkles,20 neither does your feature.2122## Don't2324- New button/input/modal implementations25- Local color palettes or decorative chrome26- Duplicate formatters (time, etc.) — use the shared ones27- New borders, backgrounds, shadows, sparkles, or badges the surrounding app28 doesn't already use — match the neighboring surface exactly29- Section chrome that nowhere else uses3031## Working from a design3233Figma file, mock, or screenshot: match it — spacing, contrast, placement —34before inventing anything.35361. Pull the design context (Figma MCP if available, else the screenshot/mock).372. Map it to existing primitives and tokens before building anything new.383. Layout and structure first, then content.394. Match spacing, padding, contrast, and states exactly. Check the details —40 no white-on-white, no doubled padding, correct CTA contrast.415. Optimize exported assets (SVGO for SVGs).426. Don't approximate spacing or colors the design specifies, and don't add43 chrome neither the design nor the app has.4445If you can't find the primitive, search harder or ask — don't quietly make one.4647While still iterating on look, follow `ui-only` (no tsc/lint/commit yet). Once48they like it, confirm against the design with `visual-verify`.
outthislife