Jason Stedwell
52 lines
2.4 KiB
Markdown
Executable File
52 lines
2.4 KiB
Markdown
Executable File
# Design System — @jason/ui-kit
|
|
|
|
The single source of truth for how every app looks and feels. Tokens live in
|
|
`src/lib/tokens.json`; TypeScript consumes it directly, the CSS theme is generated,
|
|
and the Tailwind preset exposes it as utilities. `npm run tokens:check` prevents drift.
|
|
|
|
## Color
|
|
Warm-tinted neutrals (never pure black/gray) on a warm dark base, with a single
|
|
gold brand accent. Semantic colors: success / warning / danger / info.
|
|
|
|
| Token | Dark (default) | Light | Use |
|
|
|---|---|---|---|
|
|
| `bg` | #232022 | #FAF8F4 | Page background |
|
|
| `surface` / `surface-2` | #2B282A / #333031 | #FFFFFF / #F4F0EA | Cards, raised panels |
|
|
| `border` | #3A3638 | #DED8D1 | Hairlines, inputs |
|
|
| `text` / `muted` | #F5F1EC / #A99F97 | #272326 / #665F62 | Body / secondary |
|
|
| `brand` | #DCBB4F | #79640E | Accent and action |
|
|
|
|
Every filled semantic color has a matching `*-foreground` token. Do not reuse a
|
|
background color as text without a contrast check. `ThemeProvider` supports dark,
|
|
light, and system modes; `ThemeScript` prevents a flash before hydration.
|
|
|
|
## Type
|
|
- Display / headings: **Montserrat** (600/700)
|
|
- Body / UI: **Open Sans**
|
|
- Code / data: **JetBrains Mono**
|
|
|
|
Import `@jason/ui-kit/fonts.css` to self-host the Latin variable fonts. Without it,
|
|
the declared system fallbacks remain safe. Never use Inter or Arial for headings.
|
|
|
|
## Radius, elevation, motion
|
|
- Radius scale: 6 / 10 / 14 / 20px.
|
|
- Shadows are **layered and tinted** (`shadow-sm/md/lg/glow`) — depth, not flat.
|
|
- Motion: 120/180/320ms with an ease-out curve. **No bounce/elastic easing.**
|
|
- Everything honors `prefers-reduced-motion`.
|
|
|
|
## Component rules
|
|
1. Use `cn()` for all conditional classes.
|
|
2. Variants via `class-variance-authority`, not ad-hoc conditionals.
|
|
3. Interactive primitives wrap Radix (focus traps, keyboard nav, ARIA for free).
|
|
4. Focus-visible ring on every interactive element.
|
|
5. Don't nest cards inside cards. Use semantic foreground tokens on colored fills.
|
|
6. Review every new state in the showcase in dark, light, narrow, and reduced-motion modes.
|
|
|
|
## Included
|
|
Primitives: Button, Card, FormField, Input, Select, Textarea, Label, Checkbox,
|
|
Switch, Tabs, Tooltip, Badge, Dialog, DropdownMenu, Table, Pagination, Skeleton,
|
|
Toaster, Spinner, EmptyState, StatCard.
|
|
Motion: FadeIn, Stagger/StaggerItem.
|
|
Animated: AnimatedNumber, SpotlightCard.
|
|
Blocks: AppShell, CommandPalette, Hero, FeatureGrid, Pricing.
|