Design tokens, typography, color system, and component patterns — the living style guide.
Design Principles
Clarity over personality. Typography is the primary design tool. Weight, scale, and spacing do the work — not decoration, shadows, or heavy UI chrome.
Technical documentation feel. Inspired by Stripe Docs, Vercel, and Linear. Sans-serif throughout, high density of useful information, minimal visual noise.
Light and legible. Warm off-white backgrounds with near-black text provide maximum contrast. The warm tint prevents sterile coldness.
Restrained, not loud. Dark amber accents feel considered. Color is used sparingly — primarily for interactive states and highlights.
Accessible by default. All foreground/background combinations meet WCAG AA contrast. Focus states are always visible. Dark mode is supported.
Color System
Built on warm off-whites and a near-black ink scale, with dark amber for interactive elements. Dark mode via @media (prefers-color-scheme: dark) and the .dark class.
Background & Surface
Token
Light value
Usage
--background
#fdfcfb
Page background
--background-subtle
#f9f7f4
Alternate section backgrounds, footer
--surface
#f2efea
Card / panel background
--surface-raised
#e8e4dc
Inline code, badge backgrounds
--surface-overlay
rgba(253,252,251,0.95)
Floating overlays, dropdowns
Text
Token
Light value
Usage
--foreground
#0c0c0b
Primary body text
--foreground-muted
#4a4a45
Secondary / metadata text
--foreground-subtle
#8c8c84
Placeholder / hint / overlines
--foreground-inverse
#fdfcfb
Text on dark backgrounds
Accent (Interactive)
Token
Light value
Usage
--accent
#7a5c1e
Link hover, focus rings, icon tints
--accent-hover
#5c4515
Deeper hover state
--accent-subtle
rgba(122,92,30,0.07)
Tinted fills, icon wrappers
--accent-muted
rgba(122,92,30,0.25)
Selection highlight, blockquote border
Borders
Token
Light value
Usage
--border
rgba(0,0,0,0.10)
Default borders, table rows
--border-strong
rgba(0,0,0,0.18)
Table headers, dividers
--border-subtle
rgba(0,0,0,0.06)
Extremely subtle separators
Dark Mode
Dark mode tokens are automatically applied via @media (prefers-color-scheme: dark). Manual override available with the .dark class on <html>. Accent color shifts to a lighter amber (#c9a96e) for visibility against dark backgrounds.
Typography
Inter-only for all text, with Geist Mono reserved for code. This matches Stripe, Vercel, Linear, and GitHub Docs — where readability and information density take precedence over personality.
Font Families
Role
Font
Variable
Usage
Sans-serif
Inter
--font-sans
All UI, headings, body text
Serif
(alias to Inter)
--font-serif
Compatibility alias only
Display
(alias to Inter)
--font-display
Compatibility alias only
Mono
Geist Mono
--font-mono
Code blocks, inline code, keyboard shortcuts
Type Scale
Token
Size
Tailwind
Usage
--text-xs
12px
text-xs
Labels, tags, overlines
--text-sm
14px
text-sm
Captions, metadata, table cells
--text-base
16px
text-base
Body text (default)
--text-lg
18px
text-lg
Lead paragraphs, blockquotes
--text-xl
20px
text-xl
h5, card titles
--text-2xl
24px
text-2xl
h3, h4
--text-3xl
30px
text-3xl
h2
--text-4xl
36px
text-4xl
h1
--text-5xl
48px
text-5xl
Hero display
--text-6xl
60px
text-6xl
Max display
Weight Usage
Weight
Tailwind
Usage
300
font-light
Subtle large display text
400
font-normal
Body text
500
font-medium
Active nav, secondary headings
600
font-semibold
Section labels, overlines
700
font-bold
All headings, card titles
Line Height
Token
Value
Usage
--leading-tight
1.2
All headings
--leading-snug
1.35
Sub-headings
--leading-normal
1.5
UI text
--leading-relaxed
1.7
Body prose (default)
--leading-loose
2.0
Spacious display contexts
Letter Spacing
Token
Value
Usage
--tracking-tight
−0.025em
Large headings
--tracking-normal
0em
Default
--tracking-wide
0.04em
Sub-labels
--tracking-wider
0.08em
Overlines, table headers
--tracking-widest
0.14em
All-caps badges
Spacing Scale
Based on a 4px base unit. All steps 1–64 defined as --space-* tokens and Tailwind utilities (e.g. p-4, mt-8).
Token
Value
--space-1
4px
--space-2
8px
--space-4
16px
--space-6
24px
--space-8
32px
--space-12
48px
--space-16
64px
--space-24
96px
--space-32
128px
Borders & Radius
Radii are minimal — the design is editorial and flat, not card-heavy or app-like.
Token
Value
Usage
--radius-sm
2px
Inline code, badges
--radius-md
3px
Cards, callouts
--radius-lg
4px
Code blocks
--radius-xl
6px
Larger panels
--radius-2xl
8px
Feature blocks
--radius-full
9999px
Pills, avatars
Shadows
Shadows are subtle and used only where elevation is semantically meaningful.
Token
Usage
--shadow-xs
Focus highlights, tight inset
--shadow-sm
Card hover, dropdown menus
--shadow-md
Modals, floating panels
--shadow-lg
Navigation drawers
--shadow-xl
Full-screen overlays
Transitions
Token
Duration
Usage
--transition-fast
150ms ease
Hover color changes
--transition-base
200ms ease
Default interactive transitions
--transition-slow
300ms ease
Panel expand / collapse
--transition-colors
150ms (multi)
color, background-color, border-color, opacity
Components
CalloutBox
Use callouts to break out critical information from the main prose flow. One callout per major section maximum; keep body text to 1–3 sentences. Do not use for decorative emphasis.
Layout Tokens
Token
Value
Usage
--max-width-prose
68ch
.prose element max-width — constrains the reading column
--max-width-narrow
52rem
Page shell container — content pages
--max-width-content
76rem
Full site container — nav, footer, index pages
Z-index Scale
Token
Value
Usage
--z-base
0
Default stacking
--z-raised
10
Slightly elevated elements
--z-dropdown
100
Dropdown menus
--z-sticky
200
Sticky navigation
--z-overlay
300
Backdrop overlays
--z-modal
400
Modal dialogs
--z-tooltip
500
Tooltips, popovers
--z-toast
600
Toast notifications
Accessibility
All interactive elements must have a visible :focus-visible state using a 2px solid var(--accent) outline with 3px offset.
A skip-to-content link is rendered at the top of every page (visually hidden until focused), targeting #main-content.
Text selection uses var(--accent-muted) background with var(--foreground) text.
@media (prefers-reduced-motion) disables all transitions and animations globally.
All foreground/background combinations are WCAG AA compliant in both light and dark modes.
Usage Rules
Always use semantic tokens, not primitive color values, in component CSS.
All text uses Inter — var(--font-sans). Never load or apply a serif for headings or body.
Code uses Geist Mono — var(--font-mono). Use it only for code, pre, kbd.
Links are near-black ink with underlines by default. On hover they shift to dark amber. Do not use blue anywhere.
Borders are transparent black overlays on the light ground — never opaque grays.
Minimal radii. Avoid large rounded corners. Max is --radius-2xl (8px).
No decorative shadows. Rely on borders and background contrast for separation.
Spacing is in multiples of 4px. Use --space-* tokens or Tailwind utilities; avoid arbitrary pixel values.
Prose stays at 68ch max. Never let reading content span the full viewport.
Dark mode is supported. Test all new components in dark mode before shipping.