Doctrine
Clean 16 is the canonical design system for all ops/admin HTML surfaces
Clean 16 is the canonical design system for all ops/admin HTML surfaces
Rule
Every HTML surface that is NOT client-facing MUST use Clean 16 tokens exclusively. No hardcoded hex colors, no bespoke font stacks, no one-off palettes.
Two design systems exist in the fleet. Use the right one:
| System | Prefix | Scope | Token file | Font |
|---|---|---|---|---|
| Clean 16 | --c16- | Ops, admin, internal tools, dashboards, manifests, receipts, reconciliation, bill covers | heartwood/clean-16/tokens.css | Fira Sans |
| Dollhouse v0.2 | --v2- | Client-facing surfaces (project pages, proof chains, walkthroughs) | heartwood/dollhouse-v0.2/tokens.css | Fraunces |
Token locations
- CSS custom properties:
/Users/chadbarlow/gh/heartwood/clean-16/tokens.css(16 tokens,:root { --c16-*: ... }) - JS module (CommonJS):
/Users/chadbarlow/gh/heartwood/api/_lib/clean-16.js(exports token values for server-side HTML string building) - HTTP endpoint:
/api/woodbery-shared-css(serves aggregated CSS including Clean 16 tokens)
The 16 tokens
| Token | Value | Usage |
|---|---|---|
--c16-hw | #264b33 | Primary brand green, nav bg, buttons, badges |
--c16-gray | #7f8c8d | Muted text, labels |
--c16-light | #ecf0f1 | Light backgrounds, section headers |
--c16-red | #c0392b | Error, needs-review states |
--c16-amber | #e67e22 | Warning, auto-approvable states |
--c16-card-radius | 6px | All card/panel border-radius |
--c16-card-border | #e0e0e0 | Card and divider borders |
--c16-card-bg | #fff | Card backgrounds |
--c16-card-shadow | 0 1px 4px rgba(0,0,0,.06) | Default card elevation |
--c16-card-shadow-hover | 0 2px 8px rgba(0,0,0,.08) | Hover elevation |
--c16-card-padding | 16px | Standard card content padding |
--c16-room-gap | 16px | Gap between major sections |
--c16-section-gap | 12px | Gap between items within a section |
--c16-base-size | 13px | Body text size |
--c16-title-size | 14px | Card/section title size |
--c16-title-weight | 500 | Title font weight |
Composite recipes (not individual tokens — combinations of the 16):
- Body: bg
#fafafa, color#222, font"Fira Sans",-apple-system,sans-serif - Labels: 11px uppercase, letter-spacing
.66px, color--c16-gray, weight 500 - Nav: bg
--c16-hw, height 56px, sticky, white text 13px/500
How to use in server-side HTML generators
var c16 = require("./clean-16");
var html = '<div style="background:' + c16.cardBg + ';border:1px solid ' + c16.cardBorder + ';border-radius:' + c16.cardRadius + '">';How to use in static HTML
Link to the shared CSS endpoint or import the token file directly:
<link rel="stylesheet" href="/api/woodbery-shared-css">Then use var(--c16-hw) etc. in your CSS.
What was purged (2026-04-24)
27 files across heartwood, camber, orbit, and ora had bespoke inline styles stripped and replaced with either Clean 16 token references (heartwood JS generators) or migration comments (static HTML, camber edge functions). ~6,400 lines of CSS eliminated. Any file with / Clean 16 migration pending / needs its styles rebuilt using these tokens.
Enforcement
When reviewing any PR that introduces HTML output: 1. Check for hardcoded hex colors — reject if not from Clean 16 2. Check for inline font-family declarations — must be c16.bodyFont or var(--c16-*) equivalent 3. Check for new <style> blocks with custom palettes — reject, point to this doctrine