Using UI Stack
Apply a structured design system to every UI component you generate. This prevents inconsistent padding, mismatched colors, and forgotten hover states.
Design System Principles
Follow these rules for every component you build:
Spacing — 8px Grid
Use multiples of 8 for all spacing (padding, margin, gap):
4px — tight internal padding only8px — inline gaps, icon spacing16px — standard padding, card gaps24px — section padding32px — large section gaps48px / 64px — page-level spacing
Color — 60-30-10 Rule
- 60% neutral/background
- 30% primary brand color
- 10% accent for CTAs and highlights
- Semantic colors: success (green), warning (amber), error (red), info (blue)
- Never use pure black (
#000) for dark mode — use slate-950 or similar
Typography — 1.25 Ratio Scale
text-xs: 12px / 16px
text-sm: 14px / 20px
text-base: 16px / 24px
text-lg: 18px / 28px
text-xl: 20px / 28px
text-2xl: 24px / 32px
text-3xl: 30px / 36px
text-4xl: 36px / 40px
- Headings:
font-semibold or font-bold
- Body:
font-normal, line-height 1.5–1.75
- Mono: use for code, IDs, numeric data
Dark Mode
- Provide complete light/dark mappings for every color token
- Background:
white → slate-950, not black
- Text:
slate-900 → slate-100
- Borders:
slate-200 → slate-800
5-State Interactions
Every interactive element must have:
- Default — base appearance
- Hover — subtle color shift or shadow
- Active/Pressed — slightly darker or scaled down
- Focus — visible ring (
ring-2 ring-offset-2)
- Disabled — reduced opacity,
cursor-not-allowed
Accessibility
- Contrast ratio ≥ 4.5:1 for text, ≥ 3:1 for large text
- Touch targets ≥ 44×44px
- Semantic HTML (
button not div, nav, main, etc.)
- Keyboard navigable — all interactions reachable via Tab/Enter/Escape
- Respect
prefers-reduced-motion for animations
Animations
- Duration: 150–300ms for micro-interactions
- Easing:
ease-out for entrances, ease-in for exits
- Wrap motion in
motion-safe: or check prefers-reduced-motion
Overlay Z-Index Scale
dropdown: z-10
sticky: z-20
overlay: z-30
modal: z-40
toast: z-50
tooltip: z-60
Workflow
- Before generating UI, check if the project has a
ui-stack config or design tokens
- If not, apply the defaults above
- For every component, verify spacing is on the 8px grid, colors follow 60-30-10, and all 5 interaction states exist
- Test dark mode by toggling the class/attribute and confirming all tokens map correctly
References
1---2name: using-ui-stack3description: Enforce a configuration-driven design system when generating UI. Ensures consistent spacing, colors, typography, dark mode, interactions, and accessibility across all AI-generated components.4---5
6# Using UI Stack
7
8Apply a structured design system to every UI component you generate. This prevents inconsistent padding, mismatched colors, and forgotten hover states.
9
10## Design System Principles
11
12Follow these rules for **every** component you build:
13
14### Spacing — 8px Grid
15
16Use multiples of 8 for all spacing (padding, margin, gap):
17- `4px` — tight internal padding only
18- `8px` — inline gaps, icon spacing
19- `16px` — standard padding, card gaps
20- `24px` — section padding
21- `32px` — large section gaps
22- `48px / 64px` — page-level spacing
23
24### Color — 60-30-10 Rule
25
26- **60%** neutral/background
27- **30%** primary brand color
28- **10%** accent for CTAs and highlights
29- Semantic colors: success (green), warning (amber), error (red), info (blue)
30- Never use pure black (`#000`) for dark mode — use `slate-950` or similar
31
32### Typography — 1.25 Ratio Scale
33
34```
35text-xs: 12px / 16px
36text-sm: 14px / 20px
37text-base: 16px / 24px
38text-lg: 18px / 28px
39text-xl: 20px / 28px
40text-2xl: 24px / 32px
41text-3xl: 30px / 36px
42text-4xl: 36px / 40px
43```
44
45- Headings: `font-semibold` or `font-bold`
46- Body: `font-normal`, line-height 1.5–1.75
47- Mono: use for code, IDs, numeric data
48
49### Dark Mode
50
51- Provide complete light/dark mappings for every color token
52- Background: `white` → `slate-950`, not `black`
53- Text: `slate-900` → `slate-100`
54- Borders: `slate-200` → `slate-800`
55
56### 5-State Interactions
57
58Every interactive element must have:
591. **Default** — base appearance
602. **Hover** — subtle color shift or shadow
613. **Active/Pressed** — slightly darker or scaled down
624. **Focus** — visible ring (`ring-2 ring-offset-2`)
635. **Disabled** — reduced opacity, `cursor-not-allowed`
64
65### Accessibility
66
67- Contrast ratio ≥ 4.5:1 for text, ≥ 3:1 for large text
68- Touch targets ≥ 44×44px
69- Semantic HTML (`button` not `div`, `nav`, `main`, etc.)
70- Keyboard navigable — all interactions reachable via Tab/Enter/Escape
71- Respect `prefers-reduced-motion` for animations
72
73### Animations
74
75- Duration: 150–300ms for micro-interactions
76- Easing: `ease-out` for entrances, `ease-in` for exits
77- Wrap motion in `motion-safe:` or check `prefers-reduced-motion`
78
79### Overlay Z-Index Scale
80
81```
82dropdown: z-10
83sticky: z-20
84overlay: z-30
85modal: z-40
86toast: z-50
87tooltip: z-60
88```
89
90## Workflow
91
921. Before generating UI, check if the project has a `ui-stack` config or design tokens
932. If not, apply the defaults above
943. For every component, verify spacing is on the 8px grid, colors follow 60-30-10, and all 5 interaction states exist
954. Test dark mode by toggling the class/attribute and confirming all tokens map correctly
96
97## References
98
99- [ui-stack.dev](https://ui-stack.dev) — interactive configurator and full docs
100- [GitHub: rashoodkhan/ui-stack](https://github.com/rashoodkhan/ui-stack) — source repo
spencerpauly