---
name: ADR-0007 Visual Vocabulary Locked
description: The kit's diagrams (in OPERATING-MODEL.md and OPERATING-MODEL-PATTERNS.md, rendered to diagrams/) all inherit a single warm/editorial visual vocabulary. Sets the palette, typography, shape conventions, and edge conventions that future polish batches must respect.
type: adr
---

# ADR-0007: Lock visual vocabulary for kit diagrams (warm/editorial palette)

- **Date:** 2026-05-04
- **Status:** accepted
- **Reversibility:** medium (changing breaks visual coherence across all polished diagrams; requires re-polish of A1-B4 and any subsequent batches)
- **Deciders:** kit operator
- **Scope:** kit (applies to every diagram the kit ships; deployed instances may inherit or supersede with their own ADR)

## Context

The kit ships ~31 conceptual diagrams across `OPERATING-MODEL.md` (A and B series) and `OPERATING-MODEL-PATTERNS.md` (C, D, E, F series). Across deployments + the upcoming Airtable orientation deck, these diagrams need visual coherence — readers should recognize a kit diagram from across the room, and palette/typography drift across batches makes the kit look amateur.

A polish pass through Gemini 3.1 Pro on Batch 1 (A1-A5 + B1-B4) tested two palettes: a Tailwind-default palette (v1) and a warm/editorial palette inherited from the `skills/skill-creator/eval-viewer/viewer.html` CSS variables (v2). The v2 pass produced visibly more cohesive output that read as "editorial reference material" rather than "generic SaaS." The session log for 2026-05-02 captured the v2 vocabulary as the working choice; this ADR locks it.

## Decision

Lock the warm/editorial visual vocabulary inherited from `skills/skill-creator/eval-viewer/viewer.html` as the canonical kit visual vocabulary. All future diagram polish passes inherit this vocabulary. Deployed instances that produce kit-derived diagrams inherit the vocabulary by default; instances may supersede only via their own ADR.

## Options considered

### Option A: Lock warm/editorial palette inherited from skill-creator HTML refs [CHOSEN]

- **Summary:** Cream `#faf9f5`, ink `#141413`, signature warm orange `#d97757`, sage `#788c5d`, soft blue `#6a9bcc`, amber `#f57f17`, terracotta `#a04a2e`, muted red `#c44`, deep blue `#1976d2`. Typography: Lora (serif body) + Poppins (sans headers). Mermaid uses Literata + Plus Jakarta Sans as nearest substitutes when the primary fonts are unavailable.
- **Pros:** Consistent with existing skill-creator surface; warm + editorial reads as reference material rather than marketing; tested through Gemini polish and rendered cleanly across all 9 Batch 1 diagrams.
- **Cons:** Departs from the more common Tailwind / Material palettes that some downstream consumers may default to in their own materials.

### Option B: Tailwind-default palette (per the v1 polish pass)

- **Summary:** Standard Tailwind 500-series colors (slate-500, blue-500, etc.). Typography: Inter throughout.
- **Pros:** Most-recognized palette in modern UI; Mermaid renders cleanly with default Inter; lowest design effort.
- **Cons:** Reads as generic SaaS; visually identical to thousands of other technical docs; loses the kit's editorial character.

### Option C: Defer; let each polish batch pick its own palette

- **Summary:** No locked vocabulary; each batch sets its own.
- **Pros:** Maximum flexibility per batch.
- **Cons:** Guarantees drift across batches; reader cannot recognize a kit diagram by visual signal alone; future "make it consistent" pass becomes a re-polish of every diagram.

## Rationale

Option A wins on visual character and on tested rendering. The Batch 1 polish pass produced 9 cohesive diagrams (`diagrams/polished/A1-A5 + B1-B4`) that read as a unified visual family. Option B is functional but loses the editorial signal. Option C invites guaranteed drift; the marginal cost of locking now is small while the cost of a future un-drift pass scales with the number of diagrams shipped.

The cost of locking now is low because only 9 diagrams have been polished so far (Batch 1). Future batches inherit. If the locked vocabulary later proves wrong, supersession via a new ADR re-polishes the existing 9 + restyles future ones — a contained, finite cost.

## Consequences

### Positive

- All future polish batches (Batch 2 through Batch N) start with a known palette + typography; no re-deciding per batch.
- Diagrams across the kit and across deployments visually cohere; readers recognize "this is a kit diagram" by visual signal.
- The skill-creator surface and the kit's diagrams share a vocabulary; cross-surface consistency.

### Negative

- Deployed instances that have a different brand vocabulary (e.g., the Airtable fork may need to adopt Airtable's brand colors per A3) must supersede with their own ADR + re-polish, not just override per-diagram.
- Locked palette may feel constraining when a one-off diagram wants to call out something the palette doesn't natively express (e.g., a regulatory warning that wants red-on-yellow). Mitigation: the palette includes muted red `#c44`; if a future diagram needs a brighter red, write a per-diagram exception ADR.

### Followups

- Polish Batch 2 (the 22 default-rendered diagrams in `diagrams/default/`) using this vocabulary.
- Draft H1-H4 reading aids (visual vocabulary key, layer/maturity legend, arrow-type legend, single-page summary) using this vocabulary.
- The Airtable fork must decide: inherit the kit vocabulary, or supersede with Airtable brand. If supersede, Batch 1 re-polishes in the fork.

## Reproducibility note

- **Model version:** Gemini 3.1 Pro Preview (v1 + v2 polish passes)
- **Prompt version:** v2 polish prompt (captured in `brainstorming/operating-model-polished.md` and the v2 raw response dump)
- **Tool set version:** mermaid-cli 11.14.0 for PNG rendering at 1600px width
- **Data snapshot version:** N/A (palette is symbolic, not data-derived)

## Cross-references

- Layer this decision affects: cross-cutting; affects every layer's diagrammatic representation
- Related ADRs: ADR-0008 (Mermaid + Eraser tool fit) ships alongside; together they define the kit's diagramming posture
- Session log: `sessions/2026-05-02-airtable-deck-prep-and-eraser-mcp.md` (where the v2 vocabulary was selected)
- Source HTML for palette: `skills/skill-creator/eval-viewer/viewer.html` CSS variables
- Polished output: `diagrams/polished/` (Batch 1, 9 diagrams)
- Punchlist of pending diagrams: `brainstorming/visual-assets-checklist.md`
