using-ui-stack

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 only
• 8px — inline gaps, icon spacing
• 16px — standard padding, card gaps
• 24px — section padding
• 32px — large section gaps
• 48px / 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:

1. Default — base appearance
2. Hover — subtle color shift or shadow
3. Active/Pressed — slightly darker or scaled down
4. Focus — visible ring (ring-2 ring-offset-2)
5. 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

1. Before generating UI, check if the project has a ui-stack config or design tokens
2. If not, apply the defaults above
3. For every component, verify spacing is on the 8px grid, colors follow 60-30-10, and all 5 interaction states exist
4. Test dark mode by toggling the class/attribute and confirming all tokens map correctly

References

• ui-stack.dev — interactive configurator and full docs
• GitHub: rashoodkhan/ui-stack — source repo