Style Guide
Visual reference for all design tokens. Colors, type scale, spacing, shadows, and radii — the constraints that every component is built from.
Grey Palette
Warm greys in OKLCH with hue ~70° (yellow-amber). Stone and warm paper feel. Used for text hierarchy, borders, backgrounds, and structural elements.
Primary Palette — Terracotta
Muted terracotta in OKLCH at hue ~22–30°. Earthy, restrained, confident — one accent color that says "craft." 500 is the base for buttons with white text. 50–100 for tinted backgrounds, 600–700 for hover/active.
Semantic Tokens
Role-based color assignments. Components use these — never raw palette values. Each token maps to a Tailwind utility class (bg-primary, text-foreground, etc.).
Type Scale
Hand-crafted scale, not a modular ratio. Each step has a paired line-height — tighter for display sizes, more generous for body text. Font: Instrument Sans.
Caption and fine print
Labels, hints, and secondary text
Body text — the default reading size
Large body or intro paragraph
Section subheading
Section heading
Page heading
Large heading
Display
Hero
Hero XL
Text Hierarchy
Three-tier color system for text. Dark for primary content, medium for secondary, light for tertiary. Only two weights: normal (400) and semibold (600).
This is primary text — headings, key content, emphasis.
This is secondary text — descriptions, supporting content.
This is tertiary text — timestamps, captions, fine print.
Typography
Composed prose specimen using the prose utility class. Shows headings, body text, lists, blockquotes, figures, and inline treatments in natural flow — evaluate the rhythm and spacing between elements, not just individual styles. Select any text to see ::selection styling.
The Foundation of Visual Systems
A design system is more than a collection of components — it's a shared language that bridges the gap between design intent and engineering execution. Every decision, from the weight of a heading to the rhythm between sections, serves the reader.
Hierarchy and Rhythm
Visual hierarchy guides the eye through content. Headings establish structure, body text carries the narrative, and emphasis marks the pivotal moments a reader shouldn't miss.
The space between elements matters as much as the elements themselves. A heading couples tightly to the paragraph it introduces — but separates clearly from the content above it. This asymmetric spacing creates the rhythm that makes content feel considered rather than mechanical.
Inline Treatments
Text within a paragraph can carry strong emphasis, subtle stress, or highlighted importance. Use inline code for technical references, ⌘K for keyboard shortcuts, and strikethrough for outdated information. Links like design token documentation use the primary color with an underline offset. Superscripts handle footnotes1 and ordinals like 2nd.
Lists
Unordered lists group related items without implying sequence:
- Tokens encode color, spacing, and typography decisions
- Components consume tokens — never hard-coded values
- Specimens render the component in every supported state
Ordered lists communicate steps or priority:
- Define the token in the theme
- Apply it via utility classes or custom properties
- Verify the specimen renders correctly
Typography exists to honor content.
Image and Caption
Figures pair an image with a descriptive caption, providing context that the image alone cannot convey.
Spacing Outside Prose
On cards, heroes, and other components, spacing is intentional and explicit rather than rhythm-based:
- Tight grouping (heading + supporting text):
gap-2(8px) - Standard grouping (heading + body + CTA):
gap-4(16px) - Section rhythm (between content blocks):
gap-8togap-12
Level Five Heading
Fifth-level headings are rare in practice but available when deep nesting is required — typically inside documentation or structured reference material.
Level Six Heading
The smallest heading level. Visually identical to semibold body text — distinguished only by its semantic role in the document outline.
| Transition | Spacing |
|---|---|
| paragraph + paragraph | 1.25em (~20px) |
| * → h1 / h2 / h3 | 1.4em (~22px) |
| * → h4 / h5 / h6 | 1.2em (~19px) |
| heading → content | 0.4em (~6px) |
| li + li | 0.375em (~6px) |
| around hr | 2em (~32px) |
Spacing Scale
Base 8px with ~25% jumps. Use for padding, margins, and gaps. Smaller values (4–16px) for tight grouping, medium (24–48px) for component spacing, large (64–128px) for section rhythm.
Shadows
Four-level elevation scale using two-part shadows (direct light + ambient occlusion). Warm-tinted to match the palette. Use sm for buttons, md for cards, lg for dropdowns, xl for modals.
Border Radius
Four values — firm and precise. sm (2px) for small elements and badges, md (4px) for inputs and buttons, lg (8px) for cards and containers, full for pills and avatars.
Transitions
Three duration tiers with a shared easing curve. fast for hover/focus micro-interactions, normal for state changes, slow for entrances and larger motions.
| Token | Value | Use case |
|---|---|---|
| duration-fast | 150ms | Button hover/active, focus rings, color changes |
| duration-normal | 250ms | Toggle switch, accordion expand, tab switch |
| duration-slow | 400ms | Modal entrance, page transitions, skeleton loading |
| ease-default | cubic-bezier(0.4, 0, 0.2, 1) | All transitions — fast start, gentle deceleration |
Layout
Content constrained to --container-max: 1200px. Container queries for responsive behavior — no viewport media queries in components.
| Token | Value | Notes |
|---|---|---|
| container-max | 1200px | Max content width, centered with mx-auto |
| @sm | 640px | Container query breakpoint |
| @md | 768px | Container query breakpoint |
| @lg | 1024px | Container query breakpoint |
| @xl | 1280px | Container query breakpoint |