Color System

Why OKLch

Verdigris uses OKLch as the canonical color space. All color tokens are defined in OKLch; other formats (HSL, hex, RGB) are generated by the build pipeline.

Why not HSL?

HSL is perceptually non-uniform — hsl(60, 100%, 50%) (yellow) appears far brighter than hsl(240, 100%, 50%) (blue) despite identical L values. This makes palette interpolation unpredictable and accessibility auditing unreliable.

OKLch fixes this:

• L (lightness) is perceptually linear — equal numeric changes produce equal visual changes
• C (chroma) controls saturation without shifting perceived brightness
• h (hue) rotates through the color wheel

This means Patina’s gradient palette (teal → purple → red → yellow) was generated by rotating the hue while keeping lightness and chroma in controlled ranges. The result is a harmonious palette that “feels” balanced across all hues.

Browser support: OKLch is supported in all evergreen browsers since 2023. The build pipeline generates HSL fallbacks for email clients and legacy contexts.

Brand Palette

The palette is a hue-rotation gradient anchored at four points:

Between each anchor, three interpolation steps create a smooth 16-color chart palette. See tokens/color/base.json for all values.

Gradient Logic

Teal (191°) → step1 (216°) → step2 (240°) → step3 (265°)
  → Purple (289°) → step1 (313°) → step2 (337°) → step3 (0°)
  → Red (24°) → step1 (41°) → step2 (58°) → step3 (75°)
  → Yellow (92°) → step1 (113°) → step2 (137°) → step3 (164°)
  → (back to Teal)

This creates a full-spectrum palette from a single generative rule — add or remove steps by interpolating between the anchors.

Palette Semantics — What the Colors Mean

The brand palette has 16 tokens but the design system must define what they mean, not just what they are. This is critical for AI agents and evaluator pipelines that select colors without human visual judgment.

The palette divides into 6 semantic regions based on content category:

Trust (Teal → Blue)

The anchor of the Verdigris brand. Bright, authoritative, technically precise. Use for technology, platform capabilities, data quality, and primary brand expression. Safe as text on dark backgrounds. NOT safe as text on white (fails WCAG AA).

See rules/visual-rules.yml -> color.palette_semantics.trust for tokens, hue ranges, and tint values.

Depth (Deep Blue → Purple)

The darkest palette region. Creates gravitas and sophistication. Works as dark section backgrounds, hero overlays, and gradient endpoints paired with teal. Too dark for text use.

See rules/visual-rules.yml -> color.palette_semantics.depth for tokens, hue ranges, and minimum opacity requirements.

Energy (Purple → Magenta)

High chroma, vibrant mid-range. Demands attention without being aggressive. Use for fault detection, real-time monitoring, anomaly indicators, and alerting.

See rules/visual-rules.yml -> color.palette_semantics.energy for tokens, hue ranges, and tint values.

Warmth (Red → Coral)

Warm tones invite human connection. The sidebar-primary color in Patina. Use for contact, CTA hover states, team sections, and customer stories.

See rules/visual-rules.yml -> color.palette_semantics.warmth for tokens, hue ranges, and tint values.

Results (Orange → Yellow)

Bright, optimistic tones (high lightness). Natural for metrics, ROI, stranded capacity recovery, and financial outcomes. Use on dark backgrounds only — high lightness means poor contrast on white.

See rules/visual-rules.yml -> color.palette_semantics.results for tokens, hue ranges, and tint values.

Growth (Yellow → Green)

Green-teal tones that close the chromatic loop back to brand teal. Natural for M&V results, capacity recovery, sustainability, and completion narratives.

See rules/visual-rules.yml -> color.palette_semantics.growth for tokens, hue ranges, and tint values.

Neutral (Breathing Room)

Body text, structural sections, form backgrounds, and breathing room between colored sections. At least 70% of page sections should use neutral backgrounds to prevent chromatic fatigue.

Taste Boundaries — Restraint Rules

The palette semantics without ceilings will produce a rainbow. The brand pillars define the boundaries:

• “Controlled color palette, no visual clutter.” (Masterful)
• “Subtle use of the brand gradient.” (Refined)
• “Every element earns its place.” (Precision)
• “Credibility through restraint. Sophisticated buyers, not impulse shoppers.”

Color is earned, not assigned by lookup table. An accent region appears because it makes the page better, not because a mapping table says it should.

Teal dominance: Teal + neutrals must comprise at least 70% of any surface’s color expression. Other palette regions are rare accents, not co-primaries. The brand IS teal.

See rules/visual-rules.yml -> color.palette_semantics for maximum regions per surface type.

Section limits (web pages):

• No more than 30% of sections should have non-neutral palette accents — the rest should breathe
• Never place two colored sections adjacent — always separate with neutral
• Accents are subtle (background tints and label colors) — NOT full-saturation backgrounds

Section Flow — Lightness Rhythm

Pages commit to a lightness direction. Alternating dark and light sections creates a strobe effect that forces the eye to re-adapt at every boundary. Content sections flow through subtle tonal shifts (white, neutral.50, neutral.100), not contrast flips.

See rules/visual-rules.yml -> color.section-flow for the machine-enforceable rules: max lightness jump, dark accent limits, hero/footer boundary exceptions.

Neutral Scale

The neutral scale is zinc-tinted (hue ~286°) rather than pure gray. This gives surfaces a subtle warmth that complements the teal brand color. Extracted from Patina’s production CSS.

Dark Mode Strategy

Both codebases use the same mechanism: CSS custom properties toggled via a .dark class on the HTML element. The semantic tokens (background, foreground, primary, etc.) swap values between light and dark.

Key dark mode choices:

• Background swaps from white to neutral.950 (near-black)
• Primary inverts from near-black to light gray — ensuring contrast in both modes
• Borders become semi-transparent white (oklch(1 0 0 / 10%)) for a subtle glass effect
• Sidebar primary stays pastel-red in both modes — brand consistency

See tokens/color/semantic-dark.json for all overrides.

WCAG Contrast

The www site darkened the brand teal from hsl(178, 86%, 42%) to hsl(178, 86%, 28%) for WCAG AA text contrast on white backgrounds (~4.9:1 ratio). This is documented as legacy.www-primary-light in the token set.

Recommendation: Use the original bright teal (brand.verdigris) for decorative/non-text use (backgrounds, illustrations, data viz). Use neutral.900 (Patina’s approach) or the darkened teal (www’s approach) for text/interactive elements where contrast matters.

Multi-Format Output

The build pipeline generates:

Known Discrepancies (www vs Patina)