Skip to content
Quarry Docs

Guide: Design system ("Quarried")

“Quarried” is Quarry’s design system — warm-serious editorial. This guide covers how to use it: tokens, type, color, and components. The values are owned by design tokens (ADR 0003) and consumed through Tailwind v4 (ADR 0007).

The token contract

Section titled “The token contract”

The single source of truth is packages/ui/tokens/tokens.json. A build step (pnpm tokens, packages/ui/src/build-tokens.ts) generates two projections from it — tokens.css (CSS custom properties, the code side) and figma.tokens.json (a Tokens Studio file the design side pulls, below) — so design and code resolve to identical values.

  • Primitives = raw scales (color ramps, type sizes, spacing steps).
  • Semantic tokens = intent-named tokens that reference primitives (color-surface, color-text, color-accent, space-*, radius-*).
  • Section rhythm = --space-section (space.section in tokens.json), the single vertical padding for full-width page bands (.section, ToolsSection, the 404). Adjacent sections stack to exactly 2× this value — never hand-roll a section’s padding-block.
  • Application code uses semantic tokens, never raw hex/px.
  • tokens.css and figma.tokens.json are generated — never hand-edit them. CI fails if either is stale.

To change a value: edit tokens.json → pnpm tokens → commit the regenerated files. The Figma side follows from the same source — see below.

Syncing tokens to Figma (Tokens Studio)

Section titled “Syncing tokens to Figma (Tokens Studio)”

Figma consumes the tokens; it is not a second source of truth. pnpm tokens emits packages/ui/tokens/figma.tokens.json — the same tokens in the Tokens Studio single-file format (one core set) — and CI fails if it drifts from tokens.json. The Tokens Studio Figma plugin pulls that file from Git and applies it as Figma Variables. This works on a Figma Pro seat — no Enterprise Variables API.

One-time setup (per file):

  1. Install the Tokens Studio plugin in the Figma file.
  2. Create a GitHub fine-grained PAT with read-only access to this repo (Contents: Read) — pull-only sync needs nothing more.
  3. In the plugin: Settings → Sync providers → Add → GitHub, then set Personal Access Token to your PAT, Repository quarry-design-group/quarry.team, Branch main, File path packages/ui/tokens/figma.tokens.json.
  4. Pull — the core set loads. Then Styles & Variables → Export to Figma → Variables creates/updates the Variable collection from the tokens.

On every token change thereafter: values change in tokens.json, CI regenerates figma.tokens.json, and a designer clicks Pull → Export to Figma to refresh the Variables — never hand-editing variables in Figma.

What maps, and what doesn’t. Colors, spacing, radii, and sizes become first-class Figma Variables. space.section (a clamp()), the font stacks, and the easing curves have no native Figma variable type, so they import as string variables or are skipped — they live on the code side only. Light/dark is a CSS semantic-alias concern, not primitive Variables, so a single-mode collection is correct (multi-mode would need Tokens Studio Pro).

Typography

Section titled “Typography”
  • Display: Fraunces — for headings and expressive editorial moments. Carries the “serious editorial” tone.
  • Text: Hanken Grotesk — body and UI copy; clean, readable.
  • Labels / mono: JetBrains Mono — labels, metadata, code, and small technical accents.

Use the type scale from the tokens; respect heading hierarchy (a11y depends on correct heading order). Load fonts without layout shift (NFR: CLS ≤ 0.1).

Color

Section titled “Color”
  • Quarry Blue #0C53C7 — the primary brand color.
  • Stone — the neutral ramp (surfaces, text, borders) that gives the system its warm-serious base.
  • Ember — the accent, used sparingly for emphasis/CTA.
  • Discipline (categorical) — one hue per discipline (strategy, design, engineering, ecommerce, data, app), each with a -tint (pale chip background) and -ink (AA-darkened text on that tint) pair, used by the discipline tags.

Always reference colors via semantic tokens (color-surface, color-text, color-accent, …), not raw hex. All foreground/background pairings must meet WCAG 2.2 AA contrast — verify when introducing a new combination.

Components

Section titled “Components”
  • Components live as .astro components (in apps/web), structured markup styled with Tailwind utilities that resolve to tokens.
  • Reuse existing components before creating new ones; new components should compose tokens, not introduce new raw values.
  • CtaBand is the one closing call-to-action band (blue panel, display title, optional sub, primary CTA). Backbone pages end with it — don’t hand-roll page-local CTA sections.
  • A constrained subset is available inside MDX for editorial content (callouts, figures, pull quotes) — see the content authoring guide.
  • Respect prefers-reduced-motion; keep interactivity to genuine islands (ADR 0002).

Rules of thumb

Section titled “Rules of thumb”
  • Tokens are the vocabulary; Tailwind is the grammar. Express layout/state with utilities; pull every constant from tokens.
  • No raw hex or magic spacing in components or MDX — if a value is missing, add it to tokens.json.
  • Don’t fork the palette in a Tailwind config — Tailwind reads the tokens.
  • Accessibility is part of the design, not a later pass: contrast, focus states, semantics, reduced motion.
  • When in doubt, the Figma file and tokens.json are the same contract — they should never disagree.