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---56# Using UI Stack78Apply a structured design system to every UI component you generate. This prevents inconsistent padding, mismatched colors, and forgotten hover states.910## Design System Principles1112Follow these rules for **every** component you build:1314### Spacing — 8px Grid1516Use multiples of 8 for all spacing (padding, margin, gap):17- `4px` — tight internal padding only18- `8px` — inline gaps, icon spacing19- `16px` — standard padding, card gaps20- `24px` — section padding21- `32px` — large section gaps22- `48px / 64px` — page-level spacing2324### Color — 60-30-10 Rule2526- **60%** neutral/background27- **30%** primary brand color28- **10%** accent for CTAs and highlights29- Semantic colors: success (green), warning (amber), error (red), info (blue)30- Never use pure black (`#000`) for dark mode — use `slate-950` or similar3132### Typography — 1.25 Ratio Scale3334```35text-xs: 12px / 16px36text-sm: 14px / 20px37text-base: 16px / 24px38text-lg: 18px / 28px39text-xl: 20px / 28px40text-2xl: 24px / 32px41text-3xl: 30px / 36px42text-4xl: 36px / 40px43```4445- Headings: `font-semibold` or `font-bold`46- Body: `font-normal`, line-height 1.5–1.7547- Mono: use for code, IDs, numeric data4849### Dark Mode5051- Provide complete light/dark mappings for every color token52- Background: `white` → `slate-950`, not `black`53- Text: `slate-900` → `slate-100`54- Borders: `slate-200` → `slate-800`5556### 5-State Interactions5758Every interactive element must have:591. **Default** — base appearance602. **Hover** — subtle color shift or shadow613. **Active/Pressed** — slightly darker or scaled down624. **Focus** — visible ring (`ring-2 ring-offset-2`)635. **Disabled** — reduced opacity, `cursor-not-allowed`6465### Accessibility6667- Contrast ratio ≥ 4.5:1 for text, ≥ 3:1 for large text68- Touch targets ≥ 44×44px69- Semantic HTML (`button` not `div`, `nav`, `main`, etc.)70- Keyboard navigable — all interactions reachable via Tab/Enter/Escape71- Respect `prefers-reduced-motion` for animations7273### Animations7475- Duration: 150–300ms for micro-interactions76- Easing: `ease-out` for entrances, `ease-in` for exits77- Wrap motion in `motion-safe:` or check `prefers-reduced-motion`7879### Overlay Z-Index Scale8081```82dropdown: z-1083sticky: z-2084overlay: z-3085modal: z-4086toast: z-5087tooltip: z-6088```8990## Workflow91921. Before generating UI, check if the project has a `ui-stack` config or design tokens932. If not, apply the defaults above943. For every component, verify spacing is on the 8px grid, colors follow 60-30-10, and all 5 interaction states exist954. Test dark mode by toggling the class/attribute and confirming all tokens map correctly9697## References9899- [ui-stack.dev](https://ui-stack.dev) — interactive configurator and full docs100- [GitHub: rashoodkhan/ui-stack](https://github.com/rashoodkhan/ui-stack) — source repo
zakirkun