Verdigris Design System

Verdigris Design System — Claude Code Guidelines

Project Overview

This repo (VerdigrisTech/design) is the canonical design system for all Verdigris surfaces. It contains machine-readable tokens (JSON), human-readable foundation docs (markdown), and visual rules (YAML).

Package: @verdigristech/design-tokens on GitHub Packages Consumers: Patina (app UI), www (marketing site), evaluator pipeline, AI agents, Figma Integration guide: CONSUMERS.md — canonical guide for any consumer (Tailwind, raw tokens, CSS imports, voice recipes, rules YAML, versioning).

Key Architecture

Development Commands

npm run validate            # Check token JSON for broken references and missing $type
npm run validate:rules      # Check visual-rules.yml (YAML syntax, test blocks, emdashes, convention, sidebar)
npm run validate:all        # Run both validators
npm run build               # Generate build/dist/ outputs from token source
npm run test:browser        # Cross-browser smoke tests (Playwright, chromium/webkit/firefox)
npm run test:browser:install # Install Playwright browser binaries (one-time setup)
npm run audit:cohesion      # Cross-cell brand + design cohesion audit
npm run audit:compliance         # Per-artifact compliance audit (live LLM, requires OPENAI_API_KEY)
npm run audit:compliance:smoke   # Full live pipeline against one fixture
npm run test:compliance          # Fixture self-test (no live calls)
npm run test:audit          # Self-test the auditor against fixtures

Cross-browser testing

Smoke tests live in tests/browser/ and run against a locally-built Jekyll site.

Local workflow (one-time):

bundle install                     # Jekyll + GitHub Pages deps
npm run test:browser:install       # Playwright chromium, webkit, firefox

Then for each test run:

bundle exec jekyll build           # Build _site/
npm run test:browser               # Runs on all 3 browsers; python3 -m http.server serves _site

CI runs these automatically on every PR. See .github/workflows/build.yml cross-browser-smoke job and link-check job.

Pre-Commit Checklist

Before every commit that changes tokens:

  1. npm run validate – must pass with 0 errors
  2. npm run build – regenerate outputs
  3. Commit build outputs alongside token changes
  4. If color tokens changed: npm run validate:wcag – print-stylesheet contrast must still pass

Before every commit that changes rules (visual-rules.yml):

  1. npm run validate:rules – must pass with 0 errors
  2. Every type: "constraint" rule must have a test block
  3. Every min must have a max (floors need ceilings)
  4. Every llm_eval prompt must use YES = violation convention
  5. No emdashes anywhere in the file

Before every commit that changes content (foundations, specimens, examples):

  1. npm run lint:external – no internal content in public files
  2. npm run validate:rules – checks sidebar coverage for new pages
  3. Check for AI writing artifacts (emdashes, jargon, overexplaining)
  4. Verify cross-file consistency (values in rules must match foundations and specimens)

Before every commit that changes print stylesheets or color tokens:

  1. npm run validate:wcag – must pass with 0 contrast violations
  2. WCAG AA conformance is a release blocker; deviations require explicit, accurate documentation in tokens/color/base.json token descriptions
  3. Brand teal (brand.verdigris, ~2:1 on white) is safe as text only on dark backgrounds; for any teal text on light, use brand.verdigris-on-light (~5.5:1)

Before adding a NEW CELL or making MAJOR cross-cell changes:

  1. /cohesion-audit – check the system still hangs together
  2. Address all critical findings before merge
  3. File should-fix findings under the active epic
  4. Note note findings for next quarterly review

Numerical claims must be computed, not estimated

Any contrast ratio, luminance, page-count, file-size, or token-coverage claim made in a commit message, PR description, comment, or doc must be verified by running the actual computation. PR-G round 4 caught a CRITICAL bug where the “passes 3:1 large-text contrast” framing for brand teal on white was numerically wrong (actual: 2.085:1, fails even the relaxed bar). Estimates and rough numbers in repeated artifacts harden into false facts. Use npm run validate:wcag for contrast; python3 for ad-hoc luminance; wc -l / git diff --stat for size claims.

After applying adversarial-review fixes, run another adversarial pass before commit

PR-G shipped four cumulative adversarial-review rounds; each surfaced new issue classes the previous round didn’t see. Going forward, treat fix-set application as a new state worthy of review, not a closed loop. Default cadence: at least one focused adversarial pass on the post-fix state before commit. Stop looping when N consecutive rounds find only LOW/MEDIUM nits with no CRITICAL/HIGH.

Release Process

Releases are automatic. When a PR merges to main, the auto-release.yml workflow:

  1. Determines the version bump (from PR labels or commit prefixes)
  2. Bumps package.json, rebuilds, commits, tags, creates a GitHub Release
  3. Publishes to GitHub Packages

You just merge the PR. Everything else is automated.

Versioning Rules

Bump Trigger When to use
Major PR label major or BREAKING CHANGE in commit body Breaking changes: renamed tokens, removed tokens, changed YAML rule ID paths, schema changes that break evaluator pipelines
Minor PR label minor or any feat() commit prefix New tokens, new rules, new composition cells, new foundation sections, new assets
Patch Default (no label, no feat prefix) Fixes to values, docs updates, YAML corrections, adversarial review fixes

To control the bump, either:

Pre-Merge Checklist

  1. Branch + PR – never push directly to main
  2. npm run validate:all on the branch
  3. Adversarial review before merge (at least 1 round for rules/composition changes)

Commit Message Format

type(scope): description

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Types: feat, fix, docs, refactor, chore Scopes: tokens, foundations, categories, rules, build, ci

Examples:

feat(tokens): add elevation shadow tokens from Patina audit
docs(categories): add photography guidelines
fix(rules): correct heading weight constraint from 600 to 700

Linear Integration

Glossary

File Structure Rules

Tokens (tokens/)

Foundation Docs (foundations/)

Category Guides (categories/)

Visual Rules (rules/)

Custom YAML fields

The schema accreted several fields beyond the base set as the rules system grew. Two categories:

Rules-system canonical (validator-checked, structural meaning):

Metadata helpers (informational, not validator-checked):

When adding a new field, document it here in the same PR. Validator drift starts as undocumented fields and ends as silent inheritance breaks.

Explorations (explorations/)

Graduation

The directory structure IS the maturity model. Promoting an artifact = moving it between directories and updating metadata.

Guiding principle: if an artifact has no identified ideal brand-aligned use, do NOT build a system around it. Keep it as an exploration until a real use emerges. Bias toward applying existing work to real surfaces over building elaborate exploration scaffolding.

Content Guidelines

Information Architecture

Workflow

Deviation Protocol

Any design decision that differs from Patina must be:

  1. Explicitly documented with a “Deviation from Patina” section
  2. Justified (marketing-specific need, medium constraint, etc.)
  3. Rare — Patina has 60+ battle-tested components

Justified: display font (Lato), marketing hero patterns, ad templates, physical goods Unjustified: changing brand teal, different component library, different dark mode strategy

GitHub Actions