| name | maia-design-system |
| description | Maia theme design system for Compass. Read this skill BEFORE creating or modifying any UI component, page layout, or styling. Covers tokens, typography, color, spacing, component standards, states, motion, and accessibility. Applies whenever working on .tsx files, CSS, or anything visual.
|
Maia Design System Skill
Read docs/DESIGN_SYSTEM.md for the full specification. This skill is an actionable summary.
Absolute Rules
- shadcn/ui exclusively with the Maia theme. No other component libraries.
- Tokens only. Use
bg-background, text-foreground, border-border, ring-ring. Never write zinc-* in components.
- Inter for UI. Geist Mono for code/numbers.
font-sans = Inter. font-mono = Geist Mono.
- Both modes designed. Dark mode switches CSS variables in
globals.css. Components never add dark: overrides.
- One spacing system.
gap-6–gap-8 sections, p-4–p-6 cards, space-y-4 forms, gap-2–gap-3 inline.
When Creating a Page
<div className="flex items-start justify-between gap-6">
<div className="space-y-1">
<h1 className="text-3xl font-semibold tracking-tight">Title</h1>
<p className="text-sm text-muted-foreground">Subtitle</p>
</div>
<div className="flex items-center gap-2">{/* actions */}</div>
</div>
Follow: Header row → Controls row → Content area. Every page, same rhythm.
When Creating a Component
- Install from shadcn:
bunx shadcn@latest add <component>
- Use
cn() from @/lib/utils for conditional classes.
- Use semantic tokens for all colors. Check the PR checklist in
docs/DESIGN_SYSTEM.md.
Type Scale Quick Reference
| Element | Classes |
|---|
| Page title | text-3xl font-semibold tracking-tight |
| Section title | text-base font-semibold |
| Card title | text-sm font-semibold |
| Body | text-sm |
| Label | text-xs font-medium |
| Muted | text-xs text-muted-foreground |
| Mono value | font-mono text-xs tabular-nums |
| Metric | text-2xl font-semibold tabular-nums |
Button Variants
Only: default, secondary, outline, ghost, destructive. One primary action per page.
Tables
Always inside a <Card>. Muted header row. Subtle hover. tabular-nums on number columns.
Motion
Use CSS variables: --motion-fast (120ms), --motion-base (180ms), --motion-slow (240ms).
Easing: --ease-standard: cubic-bezier(0.2, 0, 0, 1).
No bounce. No overshoot. No delays.
Accessibility
- Visible focus ring on every interactive element.
<label> on every input.- Keyboard nav for nav, tables, dialogs, selects, popovers.
- WCAG AA contrast in light and dark.
