Verdigris Design System

Canonical design tokens, guidelines, and visual rules for all Verdigris surfaces — web, sales collateral, ads, and physical goods.

This repo replaces the legacy design.verdigris.co styleguide.

Quick Start

npm install @verdigristech/design-tokens

Use in CSS (OKLch — recommended)

@import '@verdigristech/design-tokens/css/oklch';

.hero { color: var(--color-brand-verdigris); }

Use in CSS (HSL — legacy)

@import '@verdigristech/design-tokens/css/hsl';

Use in Tailwind

// tailwind.config.js
import designPreset from '@verdigristech/design-tokens/tailwind';

export default {
  presets: [designPreset],
  // ...
};

Use hex values (email, print, Figma)

import { hexColors } from '@verdigristech/design-tokens';
// hexColors['color.brand.verdigris'] → '#0fc8c3'

What's Inside

tokens/           Machine-readable tokens (W3C DTCG JSON format)
  color/          Brand palette, semantic light/dark mappings
  typography/     Font families, scale, weights
  spacing/        4px grid, layout tokens
  motion/         Duration, easing
  elevation/      Shadows, z-index (Phase 2)

foundations/      Human-readable docs with rationale
  color.md        Palette, OKLch rationale, WCAG, dark mode
  typography.md   Scale, font evaluation (Inter+Lato vs alternatives)
  spacing.md      Grid, radius, breakpoints
  motion.md       Animation philosophy, specs, reduced-motion
  accessibility.md WCAG AA requirements
  dark-mode.md    Strategy, Patina hue shift
  elevation.md    Shadow + z-index systems (Phase 2)

categories/       Medium-specific guides (Phase 2-3)
examples/         Annotated good/bad visual examples
rules/            Machine-enforceable visual rules (YAML)
build/            Token build pipeline + generated outputs

Building

npm install
npm run build      # generates build/dist/ with all formats
npm run validate   # checks token JSON for broken references

Output Formats

Format	File	Consumer
OKLch CSS vars	css/oklch.css	Patina, modern browsers
HSL CSS vars	css/hsl.css	www site (until migrated)
Hex JSON	hex/colors.json	Email, print, Figma
Tailwind preset	tailwind/preset.js	Both codebases

Source of Truth

Patina is the reference implementation. When this repo makes design decisions, Patina's existing implementation is the default. The www site converges toward Patina, not the other way around.

Deviations from Patina are documented in the relevant foundation docs with explicit rationale.

Architecture

OKLch is the canonical color space. The build pipeline reads token JSON and generates all other formats:

tokens/color/base.json (OKLch)
  ↓ build/config.ts
  ├── css/oklch.css     (for Patina, modern browsers)
  ├── css/hsl.css       (for www, legacy)
  ├── hex/colors.json   (for email, print, Figma)
  └── tailwind/preset.js (for both codebases)

Relationship to brand_rules.yml

This repo is the canonical source for all visual tokens. The migration from brand_rules.yml is complete:

1. Phase 1 (done): Design repo established as canonical source.
2. Phase 2 (done): Evaluator loads visual rules from @verdigristech/design-tokens/rules/visual-rules.yml.
3. Phase 3 (done): Design section removed from brand_rules.yml. It now retains only vocabulary/tone/terminology.

For Designers

New to this repo? Here's where to start:

• Browse foundations/ — read the rationale behind color, typography, spacing, and motion decisions
• Go to categories/ — each subfolder is a medium (photography, illustration, ads, etc.). See categories/README.md for what goes where and how to add assets
• Use categories/_guide-template.md to create a new category guide
• Check examples/ for annotated good/bad visual references

You don't need to run any code to contribute guidelines or assets — just add markdown and images via PR. See CONTRIBUTING.md for the full process.

Contributing

See CONTRIBUTING.md.

AI Agents

See AGENTS.md for instructions on using this repo as context for AI-generated design work.