Design System
Spatial scales, typography, color tokens, and structural patterns extracted from shadcn/ui.
Color Tokens
Kiso uses semantic tokens that flip automatically in dark mode via CSS custom
properties. Components never use raw palette shades or dark: prefixes.
Brand Colors
primary
blue-600 / blue-400
secondary
teal-600 / teal-400
success
green-600 / green-400
info
sky-600 / sky-400
warning
amber-500 / amber-400
error
red-600 / red-400
neutral
zinc-900 / white
Every color has a -foreground companion for accessible text on that
background: bg-primary text-primary-foreground.
Surface Tokens
background
white / zinc-950
foreground
zinc-950 / zinc-50
muted
zinc-100 / zinc-800
elevated
zinc-100 / zinc-800
inverted
zinc-900 / white
border
zinc-200 / zinc-800
Typography
All body text is text-sm. Titles use font-semibold or font-medium.
Never go below text-xs (12px).
text-lg
Dialog Title — The quick brown fox
text-base
Input text on mobile — The quick brown fox
text-sm
Standard body text — The quick brown fox jumps over the lazy dog
text-xs
Labels and captions — The quick brown fox jumps over the lazy dog
Font Weights
font-semibold
Primary headings — Card, Dialog, Sheet titles
font-medium
Interactive elements — Buttons, badges, labels, alert titles
font-normal
Body text — Descriptions, content, paragraphs
Typography Hierarchy
The same title/description pattern repeats across all container components:
| Context | Title | Description |
|---|---|---|
| Card | font-semibold leading-none |
text-sm text-muted-foreground |
| Dialog / Sheet | text-lg font-semibold |
text-sm text-muted-foreground |
| Alert | font-medium tracking-tight |
text-sm text-muted-foreground |
| Empty state | text-lg font-medium tracking-tight |
text-sm text-muted-foreground |
| Form fields | text-sm font-medium |
text-sm text-muted-foreground |
Inside colored components, description uses opacity-90 instead of
text-muted-foreground.
Heights
Standard interactive height is h-9. Scale by 1 in each direction.
h-6
h-8
h-9
h-10
Spacing
Gaps
gap-2 is the default. Use larger gaps for container-level divisions.
gap-1
Tight lists — sidebar menus, accordion
gap-2
The default — most sibling elements
gap-4
Between major sections inside a container
gap-6
Top-level container divisions — Card header / content / footer
Padding
p-2
p-4
p-6
Border Radius
rounded-md
Interactive elements
rounded-lg
Medium containers
rounded-xl
Major containers
rounded-full
Pills & circles
No per-size variation. A button is rounded-md at every size.
| Value | Component type | Examples |
|---|---|---|
rounded-xl |
Major containers | Card |
rounded-lg |
Medium containers | Alert, Dialog, Empty state |
rounded-md |
Interactive elements | Button, Input, Select, Toggle |
rounded-full |
Pills & circles | Badge, Avatar, Switch |
Icon Sizing
size-3
12px
Compact
size-4
16px
Standard
size-5
20px
Larger
Default selector: [&_svg:not([class*='size-'])]:size-4 — provides a
size-4 fallback while allowing explicit overrides.
Container Patterns
These internal spacing patterns are consistent across all container components.
Card
rounded-xl border shadow-sm — py-6 gap-6 between sections, px-6 for
each section. Header uses gap-2 between title and description.
Dialog
text-lg font-semibold
text-sm text-muted-foreground
p-6, gap-4, rounded-lg
Header: gap-2
Footer: gap-2
Sheet / Drawer
font-semibold
text-sm
gap-4
Header: p-4, gap-1.5
Footer: p-4, gap-2, mt-auto
Alert
rounded-lg — title uses font-medium tracking-tight, description uses
text-sm with opacity-90 inside colored variants.
Compound Variants
Every colored component uses identical compound variant formulas. Only base classes change per component.
The Four Variant Axes
| Variant | Colored | Neutral |
|---|---|---|
| solid | bg-{color} text-{color}-foreground |
bg-inverted text-inverted-foreground |
| outline | text-{color} ring-{color}/50 |
text-foreground bg-background ring-accented |
| soft | bg-{color}/10 text-{color} |
text-foreground bg-elevated |
| subtle | bg-{color}/10 text-{color} ring-{color}/25 |
text-foreground bg-elevated ring-accented |
All Colors
Opacity Conventions
| Value | Usage |
|---|---|
/50 |
Outline ring opacity |
/25 |
Subtle ring opacity |
/10 |
Soft/subtle background tint |
opacity-90 |
Secondary/description text inside colored components |
Size Variant Reference
When Kiso adds size variants that shadcn doesn’t have, use values from the established scales.
Badge Sizes
Button Sizes
Reference Table
| Size | Padding | Font | Icon | Gap | Radius |
|---|---|---|---|---|---|
| xs | px-2 py-0.5 |
text-xs |
size-3 |
gap-1 |
(component default) |
| sm | px-2.5 py-0.5 |
text-xs |
size-3 |
gap-1 |
(component default) |
| md | px-3 py-1 |
text-xs |
size-3.5 |
gap-1.5 |
(component default) |
| lg | px-3.5 py-1 |
text-sm |
size-4 |
gap-1.5 |
(component default) |
| xl | px-4 py-1.5 |
text-sm |
size-4 |
gap-2 |
(component default) |
Not every component needs all 5 sizes. Most should match shadcn and use a single size or 2-3 variants (sm, default, lg).