Architecture Overview

The Harness Design System is a shared contract between design and engineering.

Design tokens — stored as JSON — are the single source of truth. From that single source, Figma styles and production CSS/TypeScript are generated automatically.

This page explains the architecture, how tokens flow from JSON to UI, and how to use the system in code.

Repository Structure

canary/
├─ packages/
│  ├─ core-design-system/           # Design tokens → CSS & TypeScript
│  │  ├─ design-tokens/
│  │  │  ├─ core/                   # Primitive values (colors, spacing, typography)
│  │  │  ├─ mode/                   # Semantic tokens per theme (dark/, light/)
│  │  │  ├─ breakpoint/             # Layout & responsive typography
│  │  │  └─ components/             # Per-component token overrides
│  │  └─ scripts/                   # Style Dictionary build pipeline
│  │
│  └─ ui/                           # React component library (Radix + Tailwind)
│     ├─ tailwind-design-system.ts  # Tailwind config: CSS vars → utility classes
│     └─ src/components/            # All components
│
└─ apps/
   └─ portal/                       # This documentation site (Astro + Starlight)

@harnessio/core-design-system — Owns the tokens. Outputs CSS custom properties and TypeScript modules.
@harnessio/ui — Consumes the generated CSS vars through a Tailwind config that maps every token to a cn- prefixed utility class.

Token Architecture

Tokens are organized into four layers. Each layer builds on the one below it.

Layer 1: Core Primitives

Raw values with no semantic meaning. Defined in design-tokens/core/:

File	Contents
`colors_lch.json`	Full color palette in LCH — 15 color families, 14 stops each
`colors_hex.json`	HEX fallback of the same palette (for Figma export)
`dimensions.json`	Spacing scale, sizing, border-radius, shadows
`typography.json`	Font size scale, weights, letter-spacing, font families

Layer 2: Semantic Tokens (Mode)

Purpose-driven aliases that reference core primitives. Defined per-theme in design-tokens/mode/{dark,light}/. These map intent to value — bg.0 means “page-level background”, not “gray 950”.

Key concepts at this layer:

Neutral levels — bg.0–bg.3, text.1–text.4, border.1–border.3 for depth and hierarchy
Color Sets — pre-built bg + text pairs at three emphasis levels (primary, secondary, outline) verified for WCAG contrast
State Tokens — hover/selected overlays using LCH-space alpha transforms

Color System Full architecture with visual examples

Layer 3: Breakpoint & Layout

design-tokens/breakpoint/desktop.json maps composite typography tokens (heading scales with fontFamily + fontWeight + fontSize + lineHeight + letterSpacing) and layout spacing for the target viewport.

Layer 4: Component Tokens

design-tokens/components/desktop/base/*.json — per-component overrides for 26 components (button, input, badge, card, dialog, table, tabs, toast, etc.). These reference semantic tokens and add component-specific values like internal padding or icon sizing.

Glossary

Term	Definition
Design Tokens	Atomic values (colors, spacing, typography) stored as JSON. Single source of truth.
LCH / OKLCH	Perceptually uniform color model — equal numeric steps produce equal visual differences.
Display P3	Wide color gamut used by Figma to represent LCH values that fall outside sRGB.
Style Dictionary	Build tool that transforms JSON tokens into CSS custom properties and TypeScript modules.
Token Studio	Figma plugin that syncs JSON tokens ↔ Figma styles.
Semantic Tokens	Purpose-named tokens (`bg.1`, `text.danger`) that alias core primitives.
Color Sets	Coordinated bg + text + border groups at three emphasis levels (primary/secondary/outline).
`$extensions`	Token Studio modifier system for runtime LCH transforms (alpha, darken, lighten).
`cn` prefix	Namespace for all CSS custom properties and Tailwind utility classes.