| name | design-system-ui |
| description | Use this skill when creating components, implementing Figma designs, cleaning inconsistent styling, adding or reviewing tokens, spacing, typography, or component variants. Do not use for backend work, feature scoping, or visual QA that requires a live preview instead of design-system decisions. |
design-system-ui
Design tokens, spacing, typography, component variants. The source of truth for visual consistency across the project.
Purpose
Maintain a coherent design system: reuse tokens aggressively, propose new ones only when nothing existing fits, and ensure every component follows the established patterns.
When to use this
- Creating new components
- Implementing from Figma
- Cleaning up inconsistent styling
- Reviewing token additions proposed by figma-lovable-handoff
When NOT to use this
- Do not use for backend work, feature scoping, or visual QA that requires a live preview instead of design-system decisions.
Process
0. Read the UI rule reference first
Before UI work or review, read rules/ui.md and apply the project’s responsive, accessibility, component-state, and design-token expectations.
1. Check existing tokens first
grep -r 'colors\|spacing\|fontSize' tailwind.config.*
Map the design's values against what exists. Reuse aggressively. A new token should only be added when no existing token is close enough.
2. Component variant audit
For any new component: does a similar component already exist? Could this be a variant rather than a new component? Check the existing component library before building from scratch.
3. Token addition requires approval
New colors, spacing values, or typography scales must be proposed and approved before adding. Include a justification: what existing token doesn't work and why.
4. Naming conventions
Tokens use semantic names (not raw values):
- Colors:
background, surface, accent, muted — not blue-500
- Spacing:
space-1 through space-8 or xs/sm/md/lg/xl
- Typography:
text-sm, text-base, text-lg — not 14px
Output format
# Design system review — [component/feature]
## Tokens reused: [list]
## New tokens proposed: [list with justification]
## Component variants: [new vs variant of existing]
## Consistency issues found: [list]
Hard rules
- Never add tokens without approval
- Never use raw hex values when a semantic token exists
- Never create a new component when a variant of an existing one would work
- Reuse first, propose second, create last
Connects to
figma-lovable-handoff — produces token maps this skill evaluatesresponsive-ui — spacing tokens must work across breakpointsaccessibility-ui — color tokens must meet contrast requirements
Common failure modes
Token sprawl — Every design adds 3 new colors. Three months later you have 60 colors and no system. Push back on additions.
Raw values in components — text-[14px] instead of text-sm. Kills consistency when you later change the scale.
Spacing improvisation — Padding and gaps chosen by eye (mt-[13px], gap-[7px]) instead of from the spacing scale. Individually invisible; in aggregate the UI reads as subtly misaligned. Snap every spacing value to the scale (space-2, gap-4) and propose a new step only if nothing fits.
