Developer guide

How to use this design system in a real project. Two files do 90% of the work: tokens.css gives you every design value as a CSS custom property, and shared.css gives you the doc-site layout utilities. Start there.

File structure

Getting started

1. Import tokens.css

   This gives you every design token as a CSS custom property on :root. It's the only file you need to ship to production — it has no dependencies and no doc-site-specific styles.
2. Set the body background and font

   Use --s-canvas for the page background and --font-body for base font-family. Never use #fff — the warm cream is the brand.
3. Add the paper grain

   Copy the body::before grain layer from shared.css. It's an SVG turbulence filter inlined as a data URI — no external asset needed. Don't skip it.
4. Load the Google Fonts

   Bricolage Grotesque (opsz variable, wght 400–700), Onest (wght 400–700), JetBrains Mono (wght 400–600). All three are required. The system looks wrong with system fonts in any of these roles.
5. Copy component styles as needed

   Each component page has a <style> block with the component CSS — copy it into your project. Don't import shared.css into production (it contains doc-site-only styles like .ds-preview, .ds-code, etc.).

<!-- 1. Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,400;12..96,500;12..96,600;12..96,700&family=Onest:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">

<!-- 2. Tokens -->
<link rel="stylesheet" href="path/to/tokens.css">

<!-- 3. Base body styles -->
<style>
body {
  background: var(--s-canvas);
  color: var(--ink);
  font-family: var(--font-body);
  font-size: 15px;
  -webkit-font-smoothing: antialiased;
}

/* 4. Paper grain — copy from shared.css */
body::before {
  content: "";
  position: fixed; inset: 0;
  pointer-events: none;
  z-index: var(--z-grain);
  opacity: .3;
  background-image: url("data:image/svg+xml;utf8,…");
  mix-blend-mode: multiply;
}
</style>

CSS architecture

/* Token-first — correct */
.card {
  background: var(--s-paper);
  border-radius: var(--r-lg);
  box-shadow: var(--shadow-lg);
  padding: var(--sp-6);   /* 24px */
  border: 1px solid var(--ink-line);
}

/* Raw values — never do this */
.card {
  background: #FBF8F0;    /* ← magic number */
  border-radius: 24px;     /* ← untracked */
  padding: 24px;           /* ← not on the grid */
}

Dark mode

/* Toggle dark mode */
document.documentElement.dataset.theme =
  document.documentElement.dataset.theme === 'dark'
    ? ''
    : 'dark';

/* Or: respect OS preference */
@media (prefers-color-scheme: dark) {
  :root { /* same overrides as [data-theme="dark"] */ }
}

Responsive approach

/* Mobile-first: base is mobile */
.composer {
  max-width: 100%;
  border-radius: var(--r-lg);  /* 24px — slightly tighter on small screens */
}

@media (min-width: 720px) {
  .composer {
    max-width: 420px;
    border-radius: var(--r-xl);  /* 28px on larger screens */
  }
}

Performance: transition discipline

/* Correct — explicit properties */
.btn {
  transition:
    background var(--d-fast) var(--ease-out),
    color       var(--d-fast) var(--ease-out),
    transform   var(--d-fast) var(--ease-out),
    box-shadow  var(--d-fast) var(--ease-out);
}

/* Wrong — catches everything, including layout properties */
.btn { transition: all 140ms ease; }

Hover transform guard

/* Press state — always active */
.card:active { transform: scale(0.97); }

/* Hover state — only for pointer devices */
@media (hover: hover) and (pointer: fine) {
  .card:hover {
    transform: translateY(-4px);
    box-shadow: var(--shadow-lg);
  }
}

Accessibility checklist

• Every interactive element is reachable by keyboard (Tab, Shift+Tab)
• Focus ring is visible on all interactive elements (:focus-visible rule applied)
• All buttons have text labels (or aria-label for icon-only)
• Color is not the sole carrier of information (e.g., error has both coral color and error text)
• All animations respect prefers-reduced-motion
• Touch targets are at least 44×44px
• Modals and sheets trap focus and return it on close
• Images and decorative elements have aria-hidden="true" or alt=""
• Dynamic content updates use role="status" or role="alert" as appropriate
• WCAG AA contrast met for all body text and interactive elements

Token quick-reference