--- # GENERATED from apps/web/app/globals.css by apps/web/scripts/sync-design-exports.mjs. # Edit the CSS or lib/design-mediums.ts, then run pnpm design:sync in apps/web. name: "gatlas-design" description: "The router for Gatlas design: anything Gatlas shows a reader. Use when building or changing a surface in apps/web (dashboard pages, artifacts, shared /s/ pages, marketing and auth pages, the help center, guides, blog and legal pages), a transactional email, the Open Graph or X card a gatlas.ai link unfurls into, or text with no CSS such as a Slack message or MCP tool output; when choosing a token, sizing type or a control, styling a table or chart, writing shipped copy, or reviewing a UI diff. Loads apps/web/content/design.md, apps/web/content/copy.md and the medium's file in apps/web/content/mediums/. For a deck of slides, a board deck included, use gatlas-deck; for a document on A4 (a white paper, spec sheet, one-pager or board report, on screen or as PDF) use gatlas-document; for a social post, carousel or social or ad banner use gatlas-social. Print signage has no medium yet: ask the owner first." colors: accent: { light: "#f2f2f2", dark: "#1a1a1a" } accent-foreground: { light: "#171717", dark: "#ededed" } background: { light: "#ffffff", dark: "#000000" } background-200: { light: "#fafafa", dark: "#0a0a0a" } border: { light: "#00000014", dark: "#ffffff24" } border-illustration: { light: "#1717170f", dark: "#ededed0f" } border-strong: { light: "#00000070", dark: "#ffffff8a" } border-subtle: { light: "#0000001a", dark: "#ffffff21" } card: { light: "#ffffff", dark: "#0a0a0a" } card-foreground: { light: "#171717", dark: "#ededed" } chart-1: { light: "#171717", dark: "#ededed" } chart-2: { light: "#4d4d4d", dark: "#a0a0a0" } chart-3: { light: "#7d7d7d", dark: "#7d7d7d" } destructive: { light: "#d60020", dark: "#ff5e63" } destructive-foreground: { light: "#ffffff", dark: "#000000" } error-100: { light: "#ffeef0", dark: "#330a11" } foreground: { light: "#171717", dark: "#ededed" } illustration: { light: "#17171720", dark: "#ededed20" } info: { light: "#0064e2", dark: "#50a8ff" } info-100: { light: "#f0f7ff", dark: "#06193a" } ink: { light: "#171717", dark: "#ededed" } input: { light: "#00000014", dark: "#ffffff24" } muted: { light: "#f2f2f2", dark: "#1a1a1a" } muted-foreground: { light: "#4d4d4d", dark: "#a0a0a0" } paper: { light: "#ffffff", dark: "#000000" } petrol: { light: "#043f4a", dark: "#ededed" } petrol-100: { light: "#ebf6f8", dark: "#ffffff17" } popover: { light: "#ffffff", dark: "#0a0a0a" } popover-foreground: { light: "#171717", dark: "#ededed" } primary: { light: "#171717", dark: "#ededed" } primary-foreground: { light: "#ffffff", dark: "#000000" } ring: { light: "#0070f7", dark: "#50a8ff" } secondary: { light: "#f2f2f2", dark: "#1a1a1a" } secondary-foreground: { light: "#171717", dark: "#ededed" } sidebar: { light: "#fafafa", dark: "#0a0a0a" } sidebar-accent: { light: "#f2f2f2", dark: "#1a1a1a" } sidebar-accent-foreground: { light: "#171717", dark: "#ededed" } sidebar-border: { light: "#00000014", dark: "#ffffff24" } sidebar-foreground: { light: "#171717", dark: "#ededed" } sidebar-primary: { light: "#171717", dark: "#ededed" } sidebar-primary-foreground: { light: "#ffffff", dark: "#000000" } sidebar-ring: { light: "#0070f7", dark: "#50a8ff" } success: { light: "#107d32", dark: "#00ca52" } success-100: { light: "#ecfdec", dark: "#00250a" } warning: { light: "#a64f00", dark: "#ff9900" } warning-100: { light: "#fff6e1", dark: "#291800" } series: chart-1: { light: "#171717", dark: "#ededed" } chart-2: { light: "#0070f7", dark: "#0071f6" } chart-3: { light: "#f22782", dark: "#f12b82" } chart-4: { light: "#9f00f4", dark: "#9440d5" } chart-5: { light: "#ffb200", dark: "#ffb200" } chart-6: { light: "#28a948", dark: "#00ab3e" } chart-7: { light: "#8f8f8f", dark: "#8f8f8f" } chart-8: { light: "#fc0035", dark: "#f13242" } typography: display: { family: "Geist", size: "48px", weight: 450, weightStatic: 500, lineHeight: "56px", tracking: "-0.06em" } page-title: { family: "Geist", size: "40px", weight: 450, weightStatic: 500, lineHeight: "48px", tracking: "-0.06em" } title: { family: "Geist", size: "32px", weight: 450, weightStatic: 500, lineHeight: "40px", tracking: "-0.06em" } section: { family: "Geist", size: "24px", weight: 450, weightStatic: 500, lineHeight: "32px", tracking: "-0.04em" } subsection: { family: "Geist", size: "20px", weight: 450, weightStatic: 500, lineHeight: "26px", tracking: "0em" } lede: { family: "Geist", size: "18px", weight: 400, weightStatic: 400, lineHeight: "28px", tracking: "0em" } body: { family: "Geist", size: "16px", weight: 400, weightStatic: 400, lineHeight: "24px", tracking: "0em" } compact: { family: "Geist", size: "14px", weight: 400, weightStatic: 400, lineHeight: "20px", tracking: "0em" } label: { family: "Geist", size: "13px", weight: 400, weightStatic: 400, lineHeight: "16px", tracking: "0em" } metadata: { family: "Geist", size: "13px", weight: 400, weightStatic: 400, lineHeight: "16px", tracking: "0em" } spacing: gap-copy: "16px" gap-group: "24px" gap-section: "32px" gap-tight: "4px" space-0-5: "2px" space-1: "4px" space-1-5: "6px" space-12: "48px" space-2: "8px" space-3: "12px" space-4: "16px" space-6: "24px" space-8: "32px" rounded: radius-control: "6px" radius-overlay: "12px" radius-pill: "9999px" --- # Gatlas design ## §0 What this document is Gatlas's design system has three layers. This document is the second. 1. **Mechanism**: `apps/web/app/globals.css` and `apps/web/components/ui/*`. Tokens, primitives, ladders. Makes the right thing the default. 2. **Judgment**: this file, the copy doctrine in [`content/copy.md`](https://www.gatlas.ai/copy.md), one file per medium in `content/mediums/`, and one page per component in `content/design/.mdx`, rendered at the gated `/design/`. This file holds the rules CSS cannot hold, and the reasons behind the ones it can; the pages hold each component's examples, API, states and best practices. 3. **Enforcement**: the contract tests under `apps/web/lib/*.test.ts`, plus the four gates. See §13. Four rules this document obeys about itself, so that it stays true rather than becoming a period piece: **Values live in code, not here.** Name a role (`title`, `label`, `control-md`) and point at the file that owns its number. Every value is code-owned. A number in this prose is a decision record, never a value to copy: a ratification (the display ceiling in §5, a row in §8), a measurement (a contrast ratio, a call-site count) or a score (a ratchet's baseline in §13). When the code and a number here disagree, the code is right and this document is stale. **The names are test-pinned.** `apps/web/lib/design-tokens.test.ts` asserts, in both directions, that every custom property named here is declared in `globals.css` and that every token the `/design` preview draws is named here. Rename a token and this document fails CI. Its honest limit: it catches a rename, never a value that moved while the prose quoted the old one. That limit is why the first rule exists. **`/design` is the rendered counterpart.** Before you invent anything, open it. It draws every token in both themes and every primitive at every rung. It is operator-gated (`canPreviewDesignSystem` in `apps/web/lib/design-preview.ts`): local development, or a super-admin. **Use role names, not rung names.** `globals.css` emits ten role-named type utilities. Say `text-section`, never `text-2xl`. The rung is Tailwind's namespace; the role is ours, and a role can change size without a rename. This document also takes the marks of [`copy.md`](https://www.gatlas.ai/copy.md) §7, the em dash ban this one inherits in §1 among them. If you find an em dash or a middle dot here, it is a bug. ## §1 Inherited doctrine The base document is Vercel's brand guidelines (the `vercel-brand-guidelines` skill, served at `https://vercel.com/design.md`). It is authoritative for everything this document does not speak to. **This document is a diff.** It never restates a rule in order to agree with it, and its shortness is the point: if a passage here could be deleted without changing what ships, delete it. Adopted whole, by section name: *Frame the reader's job*, *Choose the composition*, *Typography and rhythm*, *Color, surfaces, and boundaries*, *Data and evidence*, *Motion and delight*, *Media and icons*, *Inspect and revise privately*, *Reject generated-design reflexes*. Nine things do not transfer, because the base document is *report* doctrine and Gatlas is an application: 1. **The authorship shell.** Vercel's wordmark header and triangle footer are their marks. Gatlas has its own shell (sidebar and header in the product, `Header`/`Footer` on marketing) and never renders another company's mark as authorship. 2. **The `vbg-` namespace.** Vercel prefixes because their stylesheet is loaded into documents they do not own. Ours publishes the canonical names, so markup written against it pastes into `apps/web` unchanged. The *stylesheet* does transfer, and this item used to say it did not: the argument was that our document is consumed inside the codebase, and that stopped being true the day an agent in another repository needed the values. `https://www.gatlas.ai/gatlas-brand.css` now serves them, **generated from `globals.css` per request**, cached at the edge for an hour (a stale copy may be served for up to a day while it revalidates), and never hand-authored. The rule this item was really protecting is unchanged and still absolute: never introduce a parallel token layer. A second *authored* layer is one; a derived artifact that cannot disagree with its source is not. §11 says what it emits. 3. **A visible `` on every table.** The transferable requirement is an accessible *name*. `sr-only` satisfies it; a visible caption above a dashboard ledger is chrome. 4. **"No visible theme switcher" as doctrine.** Gatlas has no switcher today, but not for this reason. See §9. 5. **Direct labels over legends, absolutely.** True at report width. An artifact chart occupying one grid cell has no lane for a direct label, so it keys its series in a legend whose swatch is drawn from the same fill or stroke as the mark. 6. **The reading measure applied to everything.** It governs prose. Tables, forms, the SQL editor and ledger columns are lookup surfaces and take the width their content needs. 7. **A literal twelve-column grid.** Inside a fixed-sidebar shell the outer grid is the shell. Alignment is still required; the column count is not. 8. **"One continuous canvas" as an absolute.** A UI with selection, hover and per-row failure needs boundaries that a report does not. The bar for earning one is in [`mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) §5, Boundaries, and it is high. 9. **"A title does not name the genre."** Right for a report. Wrong for a route title, where the genre *is* the nav label the user clicked. ## §2 Priority order When requirements compete, protect them in this order. 1. **Correctness and safety of the data shown.** Never let a failed lookup, an empty read or a truncated page render as a plausible value. A missing figure renders as the empty-value placeholder (§8), never as zero; a partial result says it is partial; a count on a card and the row count at its destination come from one predicate or the page says why they differ. This clause is first because it is this repository's recurring bug class rather than a general principle, and because a finance product that renders a confident wrong number has failed at design, not only at engineering. 2. **The token and component API.** Never hand-patch what the system can own. §3 says what to do instead. 3. **The user's task, legible at the density this product runs at.** Density is a real constraint here, not a failure of restraint. See [`mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) §5, Density. 4. **Gatlas identity: type, restraint, the monochrome field.** 5. **A composition specific to this surface** rather than a template or a model default. 6. **Polish**: responsive behavior, interaction detail, motion. ## §3 Integration Styling decisions move **up** into tokens and primitives, never **out** into call sites. A value that appears twice at a call site is a token that has not been declared yet. Triage every styling need before writing it: - **A token or primitive already covers it.** Use it. If a call site is currently hand-patching it, migrate the call site in the same change. - **One nearly covers it.** Extend the primitive (a new rung, a new variant), then migrate. Deepening an existing module beats adding a shallow one. - **Nothing covers it.** Build the primitive first, then purge the hand patches it replaces. **A purge that runs before its component exists is a find-and-replace the next author undoes.** Order matters more than speed here. Do not add a styling dependency. Charts are hand-drawn SVG (`components/artifacts/artifact-grid.tsx` explains why); icons are `lucide-react`; there is no second icon set and no chart library. Motion has two permitted sources: `tw-animate-css` for CSS, and the `motion` library, which some marketing components already import; a third is a decision, not a default. The one rendering library is `vgpu`, scoped to the ocean ground (§8, row 15). `components/ui/*` is generated shadcn. Extend by `className` or by wrapping. When a change has to go inside a generated file, say so in the commit: `shadcn add` would silently overwrite it. ## §4 The three passes **Frame.** What is the user's task on this surface, or the reader's question? What is the strongest supported answer, what evidence earns it, and what would change it? For a product surface, also: what states can this data be in, and what does each look like ([`mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) §6)? **Compose.** Geometry before components. Map the material to a visual variable before choosing a primitive. Run the squint test (at a glance, is the dominant object obvious and the reading path stable?) and the text-mask test (with the words blurred, does the hierarchy still communicate identity, emphasis, grouping and progression?). If every block has equal weight, redesign before coding. **Inspect.** In order: 1. Does the surface obey §2, clause 1? Find the failure paths, the five states of [`mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) §6, and open each. 2. Does anything hand-patch a value the token layer owns? Route it through §3. 3. Type roles consistent, peers equal, baselines aligned, every gap owned by one parent. 4. Keyboard: tab order, visible focus, no trap, every action reachable. Screen reader: landmarks, one `h1`, accessible names. 5. Both themes, and reflow to a narrow screen without horizontal overflow. 6. Restraint: can any surface, border, badge, icon, color or paragraph be removed without losing meaning? Remove it. 7. The four gates: lint, type-check, test, build. All four, every time; the exact commands are in the repository's `AGENTS.md`. There is no browser test suite. Step 5 and the visual half of step 4 are **manual**, and a change that skips them has not been verified. ## §5 The visual system Every rule here points at a name. The values live in `globals.css`. **Type roles.** Ten, emitted as `text-display`, `text-page-title`, `text-title`, `text-section`, `text-subsection`, `text-lede`, `text-body`, `text-compact`, `text-label`, `text-metadata`. Use `display` only for a single page-defining statement where scale is earned; `page-title` for a route's title on marketing and on the reading routes (the target state: the marketing, legal and blog routes that still set `display` move to `page-title` in the marketing phase, GAT-450); `title` for a major section turn, and for a dashboard route's title, one step down because the dashboard runs dense (§8 row 25); `section` and `subsection` for nested structure; `lede` for one orientation passage; `body` for reading; `compact` for dense prose; `label` for a compact name, a table cell, a list row; `metadata` for a caption, an eyebrow, subordinate evidence context. `label` and `metadata` share a value today and are free to stop: they are two roles, not two spellings, and the density knob is deliberately two edits. **The display ceiling is 48px.** Nothing in the product is larger, bar the home hero's claim, its `h1`, which §8 row 26 ratifies, and the link-preview card's claim (row 13). The rungs above it are clamped rather than deleted so a responsive class is inert instead of wrong. **The tracking ramp is a step function of size**, and it keys off the rung name, not the resolved value. Its boundaries: at or above 30px, the tightest step; at 24px, one step looser; at 16 to 20px, looser again, and only in a heading role; at or below 14px, none. Never apply a `tracking-*` utility at a size the ramp already governs, and never apply positive tracking anywhere. **Prose sits at 60 to 68 characters per line.** Rewrite before shrinking, and never narrow a lookup surface to reach it (§1, item 6). **One control ladder.** `--control-h-sm` through `--control-h-xl`, plus `--control-h-touch`, the enlarged target the narrow-viewport bump applies to the rungs that can take it (§10), with `--control-text`, `--control-text-micro`, `--control-leading`, `--control-pad-sm` through `--control-pad-xl` and `--control-gap`. Every control primitive consumes it; none re-derives its own number. The heights alias the raw metrics `--ds-size-small`, `--ds-size-medium`, `--ds-size-large` and `--ds-size-touch`. `--control-text-micro` is barred from form controls. **Radius.** Controls take `--radius-control`; overlay surfaces (menus, popovers, modals) take `--radius-overlay`; `--radius-pill` is the marketing pill, on the terms §8 row 5 sets. All three deliberately bypass the `--radius` ladder, which is dead (§10). In-page surfaces are square: tables, stat tiles, disclosures, wells and empty states draw their edge with no radius, and the `Table` primitive draws its own frame so no call site authors one (`lib/design-tables.test.ts`). The Entities page briefly took the overlay radius on its table and tiles (#334) and was the one rounded table in the product; that ended in GAT-179. Rounding in-page surfaces is the radius phase (§9), one reviewed change, never a per-page choice. Never author a numeric radius. **The values are Geist's.** Every hue is a step of Geist's scales, imported unchanged from `https://vercel.com/geist/colors` into `app/geist-colors.css` by `scripts/sync-geist-colors.mjs`, in Vercel's three layers: sRGB hex, `lab()` where supported, P3 `oklch()` on wide-gamut screens. Never edit that file; rerun the script. The tokens that are step references point at the step Geist gives their job: `--muted-foreground`, every status ink (`--info`, `--success`, `--warning`, `--destructive`) and tint (`--info-100`, `--success-100`, `--warning-100`, `--error-100`), `--ring` and `--sidebar-ring`, and the chart ladder after its first rung. 900 and 1000 are for text and icons, so every status ink is a 900 step; 700 and 800 for solid fills; 100 to 300 for backgrounds, so every status tint is a 100 step. The other neutral grounds, surfaces, actions and lines are not step references either: `--secondary`, `--accent`, `--muted`, `--border`, `--input`, the rest of the sidebar set, the tokens beside them in the theme blocks, and the `.auth-panel` grounds are literal `oklch()` values with zero chroma, so a change to Geist's grays does not reach them. Apart from petrol, every literal value in `globals.css` is achromatic wherever it sits, in a token, a gradient or a mask, and `lib/design-color.test.ts` holds that line by reading every literal in the file. Call sites read the meaning tokens, never a step, and the steps are not Tailwind classes. Petrol is the one hue outside Geist. **Ink and paper come from one place per theme.** `--ink` holds the ink and `--paper` the paper. In light, `--ink` is `#171717`, the ink the logo in `brand/marks` is drawn in: the product owner ruled on October 2, 2026 that the logo's ink wins, so it is a literal and a Geist resync never moves it. `--paper` is white. The dark theme declares its own pair, `#ededed` on black, inside `@media not print`, so paper always takes the light pair. Every ink token reads `var(--ink)` in every theme: `--foreground`, `--primary`, `--card-foreground`, `--popover-foreground`, `--secondary-foreground`, `--accent-foreground`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-accent-foreground`, and `--chart-1` both app-wide and as slot one of the artifact palette. Every paper token reads `var(--paper)`: `--background`, `--card` and `--popover` in light, and the foregrounds set on an ink or status fill, `--primary-foreground`, `--sidebar-primary-foreground` and `--destructive-foreground`. The generated marks and `brand/tokens.json` take their ink and paper from the same pair through `lib/design-model.ts`, and `lib/design-model.test.ts` fails when a token, a mark or the export drifts from it, or when a theme block types an ink or paper value anywhere but `--ink` and `--paper`. Call sites read the meaning tokens, never `--ink` or `--paper`. **Where color is allowed.** Gatlas is ink on paper. This list is closed: color appears in the six places in the table and nowhere else, and each place has one job. If what you are about to color is not in the table, it is ink. | Color | Tokens | Allowed for | Never | |---|---|---|---| | Ink and paper | `--foreground`, `--background`, `--background-200`, `--muted-foreground`, the alpha scale | everything not listed below: the logo, every button and control, links, headings, text and numbers, borders, surfaces, illustrations, and a chart with one series | | | Accent, petrol | `--petrol`, `--petrol-100` | a small glyph or dot at the accent sites listed below, on a light ground | the logo, a button or any control, a link, text or a number, a heading, a border or rule, a surface or section ground, a gradient, a shadow, an illustration, a chart, a status, a dark ground | | Status | `--info`, `--success`, `--warning`, `--destructive`, with `--destructive-foreground` and the tint rungs `--info-100`, `--success-100`, `--warning-100`, `--error-100` | state, always beside a word or a glyph | decoration, a favorable figure, a recommended row | | Focus | `--ring` | keyboard focus | anything else | | Series | `--chart-1` to `--chart-3` app-wide, a monochrome ramp of three inks; under `.artifact-canvas` and `.artifact-palette`, `--chart-1` to `--chart-8` are ink, then Geist steps (§8, row 4) | telling two or more series apart | a chart with one series (Charts, below) | | Third-party marks | none: the vendor's own file under `public/connectors/`, drawn as published | a connector's logo in its vendor's colors, inside a tile: a link-preview card's tile, for a connector that card names (on a blog recap card, one its post names in `card.connectors`) (§8 row 13), and the `SourceIcon` tile the product already draws on a white ground | a Gatlas mark, text, a surface, a border, a recolored or tinted logo, a logo for a connector the surface does not name, on a link-preview card a logo too small to read at the size the card draws it (`LOGOS_ILLEGIBLE_ON_A_CARD`), a logo outside its tile | **The accent sites.** Petrol appears at exactly these. `lib/design-color.test.ts` fails on any other file under `app/`, `components/`, `emails/` and `lib/` that names petrol, bar the three that name it as content and draw nothing (`NAMES_PETROL`: the `/brand` page, the `/design` swatch registry, and `lib/design-exports.ts`, which holds the list below). It reads petrol in every form a file would carry it: a class or `var()`, the custom property, the token read by name (`tokenHex("petrol")` or any quoted token name), and petrol's own hexes in any case and its `oklch()`, read from `brand/tokens.json`. `tokenHex` itself refuses petrol, so no renderer without CSS can draw it: - The MCP note's dot, `McpNote`, in `components/dashboard/page-header.tsx`: `bg-petrol`. - The check glyph beside each benefit on `/contact`, in `app/(marketing)/contact/page.tsx`: `text-petrol`. - The included-feature check in the `/pricing` comparator, in `app/(marketing)/pricing/sections/comparator.tsx`: `text-petrol` on `bg-petrol-100`. - The `/design/color` page's accent example, in `components/design-examples/color/accent.tsx`: `bg-petrol`, `text-petrol` and `bg-petrol-100`, the three sites above. **An accent is a mark, never a color for a thing.** It takes one of these forms and no other: a glyph's color (`text-petrol`, `fill-petrol` or `stroke-petrol` on an icon or a check), a dot (`bg-petrol` on an element no larger than a glyph), or `bg-petrol-100` directly behind that glyph. It never carries meaning its neighboring text does not already state, so it is `aria-hidden` or sits beside its label. Petrol is not `--accent`: that token, despite its name, is the gray hover fill (§11, Action), and it never carries a hue. **No hue on a dark ground.** In the dark theme `--petrol` resolves to the foreground and `--petrol-100` to an alpha of it, so every accent site turns ink by itself. Deep petrol does not read on black, and any petrol light enough to read there is turquoise, which is not the color chosen. Never author a dark-theme petrol, a `dark:` variant that adds a hue, or a lighter petrol. **No accent on paper or in a feed.** Petrol never appears in a deck, a document (on paper or on the web) or a social image or link preview, and no accent site may be added in one: those mediums are monochrome, as the explainer deck already is (decision 9 of the mediums spec, 2026-10-01). `lib/design-color.test.ts` holds both halves: no site in the list above belongs to one of them, and no file under `docs/collateral/` but a PDF names petrol, read by the same detector as the code. **Before you add color, answer in order.** 1. Is it a state: error, warning, success, info? A status token, beside a word or a glyph. 2. Is it keyboard focus? `--ring`. 3. Does it tell two or more chart series apart? The series slots. 4. Is it one of the accent sites above? Petrol, in one of the accent forms. 5. Is it another company's logo, for a connector the surface names, inside its tile? The vendor's colors, as the vendor publishes them. 6. Anything else is ink. There is no seventh answer. A new accent site, a new chromatic token or any other new place for a hue is one pull request that changes this section, §8 row 22 and `ACCENT_SITES` in `lib/design-exports.ts` together (the list above is generated from it), and the product owner approves it. Third-party marks entered the table that way on 2026-10-05, adapted to what they are: a vendor's logo is that vendor's content, not a Gatlas hue, so it reads no token and adds no accent site, and its ratification is the card's own row, §8 row 13, rather than row 22. The product owner approved it with the D1 card design (GAT-515). `SourceIcon` had drawn the same marks in the product on a white tile since the rebrand; the row names that use rather than inventing it. Two surfaces sit outside this table because they cannot read tokens at all, each ratified by name: email templates (§8 row 23) and the two syntax-highlighting themes (§8 row 24). Nothing else carries chroma: never author a raw Tailwind hue class (`text-emerald-600`, `shadow-indigo-900/15`), a hex, an `oklch()` outside `globals.css`, or a tinted shadow or gradient; the test holds raw hue classes at zero. **The accent and the series palette are kept apart**: no chart slot reads `--petrol`, and the series teal is not the accent. The teal the product carried until 2026-09-24 was the palette's first slot promoted to a "brand" for one dot, which is how a product ends up with a color nobody chose. Do not color a figure because it is favorable, a row because it is recommended, or a bar because it is longest. Every use of color to carry meaning pairs with a non-color cue. **Ground and surfaces.** `--background` is the page; `--background-200` is the second ground a step off it (table header grounds, card footers, inset wells, empty-state grounds). In light it is a recess, `#fafafa` below the white page. In dark it is a lift, `#0a0a0a` above the black page, because nothing renders below black: a value under the page rounds to the page's own `#000000` and draws no step, which is what the dark value did until GAT-514. `--card` and `--popover` are the raised surfaces, with `--card-foreground` and `--popover-foreground`. `--muted` is the hover and selection fill only, with `--muted-foreground` for receding text. The sidebar carries its own set: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`. Actions read `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground`, over `--foreground`. **Boundaries.** `--border` is the default edge, `--border-subtle` an interior rule, `--border-strong` a hover step, and a field's edge on hover (§8, row 30); `--input` is a field edge. The raw alpha scale they come from is `--gray-alpha-100`, `--gray-alpha-200`, `--gray-alpha-300` and `--gray-alpha-500`, and it is also where hover and press fills come from. Illustrations paint with `--illustration` and `--border-illustration`, both an alpha of the raw `--foreground` so they flip with the theme on their own. They read `--foreground` and never its `@theme` mirror `--color-foreground`, which is emitted once on `:root` and would hand a nested dark wrapper the light theme's ink. **Charts.** The app-wide ladder is `--chart-1` through `--chart-3`: three inks, ink end first, that cycle at three. Series past the third lap it and lean on stroke weight and dash. The artifact surface, and `/usage` through `.artifact-palette`, are the documented exception (§8, row 4). **One series draws in ink, everywhere**, the artifact surface included: color exists to tell series apart, and one series has nothing to tell apart. On the artifact surface slot one is ink, so this needs no special case, and the first series keeps its color when a second arrives. **Mono.** Geist Mono only for code, commands, paths, raw tokens, timestamps and short operational identifiers: a schema name, a key prefix, a connection label. Set only the identifier, never its sentence or its whole table. `.z-mono` carries slashed zero with tabular figures, because disambiguating zero from the letter O is the entire reason an identifier is in mono. Financial figures are Geist Sans with tabular figures, not mono: use `.numeric`, or nothing, since `globals.css` sets tabular figures once on `table`. **Weight.** Regular for body, medium for controls and labels, `--font-weight-title` for headings. Emphasis is scarce. Never author a numeric `font-weight`. **Punctuation.** The marks are [`copy.md`](https://www.gatlas.ai/copy.md) §7's, in shipped text, in agent-facing text and in this file. What is this file's is the layout a metadata row takes without a middle dot, which is Gatlas's own ban: a middle dot between two facts declines to say how they relate, and it reads as a bullet once the row wraps. So separate a metadata row's spans with space (`gap`) and let the type roles tell them apart; where two facts must share one string, a comma. The middle dot is held by a ratchet (§13). ## §6 Product surfaces Moved to [`content/mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) on 2026-10-01, with the share audience beside it. Its parts keep their names there, so a citation of "§6, Stale" still lands: density, boundaries, the artifact card's side inset, the shell contract, and sheets and dialogs are in its §5; the five states and tables in its §6; focus and keyboard traversal in its §11. ## §7 Marketing surfaces Moved to [`content/mediums/marketing.md`](https://www.gatlas.ai/mediums/marketing.md) on 2026-10-01. What marketing changes and the three things it changes are in its §1; the hero, the type roles and their two exceptions (one ratified), and third-party marks in its §5; decoration and figures in its §6. ## §8 Ratified divergences A divergence from the base document enters this table **in the same pull request that creates it**, or it is drift. Rows 23, 24, 25, 28 and 29 began as unratified deviations found in review rather than decisions taken; that is the failure mode this rule exists to stop. A row leaves the table when its condition stops holding, not when someone stops liking it. The artifact masthead serif was row 1 until 2026-09-29, when it was retired and artifact titles took the dashboard's route title (row 25). The Medium column names the medium a row governs by its id in `lib/design-mediums.ts`, or `all` when the row holds in every medium. | # | Medium | Divergence | Argument | Condition that keeps it honest | Pinned by | Date | |---|---|---|---|---|---|---| | 2 | all | Em dash as the empty-value placeholder | The base document's ban is a prose rule. A dash meaning "no value" in a ledger is a data convention, and it is how §2 clause 1 renders a missing figure without inventing a zero. | Table cells and detail rows only. Still banned in shipped prose, including this file. | `formatMeasure` in `lib/artifacts/render-model/format.ts` | 2026-09-03 | | 3 | dashboard | Pulsing in-progress dot | Directly against the base document's ban on pulsing status indicators. Motion carries in-progress state **so that** color stays reserved for success, warning and error. | Every pulse `aria-hidden` beside a text label; the reduced-motion block ships with it; no pulse in a static legend. A legend explains a marker and is never itself in progress, so its key is the static form of the dot. | The reduced-motion block in `globals.css`; `lib/design-tokens.test.ts` fails any pulsing dot that is not `aria-hidden` | 2026-09-03 | | 4 | dashboard, share, document, deck | Artifact charts use a categorical palette of Geist steps as the primary series signal | Not a divergence from the color rule, which permits color "when it is needed to distinguish series". It is a divergence from Vercel's own implementation of that rule, which cycles grays. The rest of the product stays monochrome; artifacts are the customer-facing surface where series identity is the question. The slots are ink, then Geist's steps as published, chosen by the product owner on 2026-09-24: `--ink`, then `--blue-700`, `--pink-700`, `--purple-700`, `--amber-700`, `--green-700`, `--gray-700` and `--red-700`, the 700 steps being Geist's step for solid fills. Ink first means a one-series chart draws in ink and its series keeps that color when a second arrives. | Scoped to `.artifact-canvas` so nothing else changes color, plus `.artifact-palette`, which carries the same declaration and nothing else, on the owner-only `/usage` page (GAT-224), whose charts distinguish tool categories. A use outside those two is a new row. Each slot is a reference, never a copied value, so dark mode and P3 come from the theme's ink and from Geist. **Measured limits, accepted with relief:** in light, amber-700 is 1.7:1 and green-700 2.9:1 on the chart surface, under the 3:1 floor for a graphic; green and red (slots six and eight) collapse for deuteranopes, so they are never adjacent and only meet in a chart of eight series. The relief is that color is never the only cue: every series carries stroke weight and dash for line and area, a hatch pattern past the eighth slot, a legend whose swatch is drawn from the same fill or stroke as its mark, and a labeled readout; on `/usage` a text label beside every bar. No slot is the accent. | `lib/artifacts/render-model/chart.test.ts` (`chartRung`, `chartLap`, `chartHatchId`, `chartHatchPairs`); `lib/usage-analytics.test.ts` (the category-to-slot map); `lib/design-color.test.ts` (the eight references, ink first, no slot reads `--petrol`) | 2026-09-04, widened to `/usage` 2026-09-23, Geist 700 steps 2026-09-24 | | 5 | marketing | Pill radius on marketing in-page CTAs **and the masthead's two actions** | Marketing persuades a stranger; the product does not. The header exclusion was the original form of that line and it drew the boundary at the wrong place: the masthead is marketing chrome, read by the same stranger, and its log-in and sign-up are the site's two standing CTAs. Widened on the product owner's decision, 2026-09-22. | Opt-in per call site, never a `Button` default, never in the product, and never on a control that does something other than send a stranger further into the site. In-page CTAs keep the largest control rung; the masthead's pair takes the rung the bar sets (36px in the bar, 40px in the phone sheet), since the pill class only ever overrides radius and horizontal pad. | `BUTTON_PILL` in `components/ui/button-sizes.ts`; `lib/button-contract.test.ts` | 2026-09-03, widened 2026-09-22 | | 6 | dashboard | A denser default control rung than Geist's single desktop size | Stated as a choice, not a correction toward the authority. Gatlas's dashboard packs a filter row where the base document sets one control in prose. | One ladder, one number per rung; the narrow-viewport bump restores a target on every rung that can grow in both axes, and the four dense rungs opt out by name (§10). | `--control-h-md` in `globals.css`; `lib/button-contract.test.ts`; the bump's exclusion list in `lib/design-tokens.test.ts` | 2026-09-03 | | 7 | all | `--radius-control` and `--radius-overlay` bypass the `--radius` ladder | The ladder is dead (§10) and cannot be repaired as a side effect of an unrelated change. These give controls and overlays a real radius meanwhile. | Interim by construction. Both retire when the ladder is activated, and that activation is its own reviewed change. | The `@theme inline` block in `globals.css` | 2026-09-03 | | 8 | all | Dark `--card`, `--popover` and `--sidebar` sit on the second ground, `--background-200`, rather than the page ground | Vercel's dark cards do sit a rung above ground, and against a pure black page a card that shares the page's value is not a card. The rung renders: `#0a0a0a`, the dark background-100 of Geist's HSL layer (`0 0% 4%`), one step above the `#000000` page. | Light and dark declare the same set of names, so neither theme can grow a token the other lacks. | `lib/design-tokens.test.ts` (the declared value); `lib/design-model.test.ts` (the rendered `#0a0a0a`) | 2026-09-04, rendered 2026-10-03 (GAT-514) | | 9 | all | Status tints derived as an alpha of the edge color, not from the tint rungs | Interim. The tint rungs are declared and correct; migrating the call sites is a separate change with its own review. | The tint rungs stay declared and drawn on `/design` so the debt is visible. Any *new* tinted surface takes the rung. | The `-100` rungs in `globals.css`, drawn by `lib/design-preview.ts` | 2026-09-04 | | 10 | all | `--text-label` as a rung Tailwind does not have | Geist publishes a label role at a size Tailwind's scale skips, and the alternative (retuning the smallest stock rung) would enlarge the densest surface in the product. | New label work takes the role. Migrating the existing dense chrome is its own ticket, and the count is the score (§13). | `lib/design-tokens.test.ts` | 2026-09-03 | | 11 | dashboard | `--control-text` at the label size on the product surface, comfortable opted in | Geist pairs its control with body copy of the same size. Gatlas's dashboard body is smaller, so Geist's control renders larger than the text beside it and the widest type in a filter row is a button. This treats the symptom; the cause is the unmigrated body ladder. | **Reverts** when the body migration lands, together with the `[data-control-density="comfortable"]` block. Filed as GAT-77. Without that ticket this line is drift. | `lib/design-tokens.test.ts` (exactly two declarations, ever) | 2026-09-04 | | 12 | marketing, reading | A dithered texture on the auth panel and the hero ground | The base document hard-rejects textures. This one exists to solve a contrast problem, not to decorate: the auth panel's ground was very nearly invisible against the page in light and exactly invisible in dark, so the texture *is* the value step. The texture itself is zero new bytes, no client boundary and no motion; the live layer over it is row 15. | `/login`, `/signup`, `/forgot-password`, `/reset-password`, the hero's claim block, and the guide series cover on `/docs/guides` only. Static, read as a luminance mask so it never lands on type. On the hero it runs edge to edge under an opaque claim panel that the live layer in row 15 shares. On the auth panel it now runs the full height of the column, because that panel carries no content at all: the evidence block and the per-page quotation came off on 2026-09-22. They were the reason for a fade that cleared the bottom 560px, and they were also the composition [`mediums/marketing.md`](https://www.gatlas.ai/mediums/marketing.md) §6 rules out: row counts on a dithered, moving ground, where "a decorated number reads as a rendered number". The words moved to the surfaces that persuade; the panel is a decorative ground beside a form column that carries every one of them. On the guide cover it is static only (no live layer), clears under the series label and title, and fills in under a schematic that carries no figures and sits on its own card. | The `.auth-panel` and `.ocean-ground` blocks in `globals.css`; `lib/design-tokens.test.ts` | 2026-09-04, widened 2026-09-08, cleared and widened again 2026-09-22 | | 13 | link-preview | The OG and Twitter card renders outside the CSS token layer, on resolved hexes and raw font binaries, a changelog entry's card draws a panel of tiles that carries vendor logos in their own colors, the root card draws the explainer deck's plate 1.1, and a blog post's card draws another of the deck's plates or, for a release recap, the changelog's tiles | Satori reads neither CSS custom properties nor `next/font`, so the social card is the one surface that cannot be routed through `globals.css`. It reads each color by token name from `brand/tokens.json`, the export generated from `globals.css`, so it renders in the product's own ink rather than in a second, drifting palette, and the card is what a stranger sees before the site does. A changelog entry's card (the D1 design, GAT-515) shows what the entry is about: the wordmark top left, the section, date and headline bottom left, and on the right, from x 712, tiles in `background-200` that bleed off the card's edges, chosen by `cardVisual` in `lib/changelog.ts` from the entry's title or its `card` frontmatter. A tile carries only what [`mediums/social.md`](https://www.gatlas.ai/mediums/social.md) §5, Imagery, allows: the logos of the connectors the entry names, the Gatlas mark, MCP tool names in Geist Mono, or a schematic with no figures and no names (a chart, the company tree, a table, a message, a help page, a setup link, a read-only connection, an ownership handover). Connector logos keep their vendor's colors because a recolored logo is no longer the vendor's mark, and `SourceIcon` already draws them that way in the product; the product owner chose it over an all-ink variant on 2026-10-05. The root card is the same system without tiles: the wordmark top left, the claim bottom left, and on the right the explainer deck's plate 1.1, the layer on top (company tools, one Gatlas layer, the people and agents who read it), bleeding off the right edge, its lid in the illustration tone and its crease in ink. The deck's own code draws it, so the card and the deck that carries the same title show one drawing; the product owner chose it on 2026-10-05 over figures of vendor logos, which say what Gatlas connects to rather than what it is. A blog post's card (GAT-491) takes the same plates for the blog's long form: the changelog card's layout under the section Blog, and one plate the post names, so each post shows the drawing of its own argument; the product owner chose it on 2026-10-05 over the changelog's schematics, which made a post read as a changelog entry. A post that recaps releases is the exception (GAT-531): a recap is a summary of changelog entries, so its card may carry the changelog's own tiles instead of a plate, as the recap collage, which the product owner chose on 2026-10-05 over a plate and over a wall of the quarter's logos. | `app/opengraph-image.tsx`, a changelog entry's card, `app/(marketing)/changelog/[slug]/og.png/` (GAT-487, GAT-515), a blog post's card, `app/(marketing)/blog/[slug]/og.png/route.tsx` (GAT-491), which draws through the changelog card's `cardElement`, and the two routes that draw the mark for a browser, `app/apple-icon.tsx` and `app/favicon.ico/route.tsx`. No hex is typed in them: every color is `tokenHex()` of a named token, and the tile's corner and gaps are `lengthPx()` of `radius-overlay` and the spacing band. The cards' type is the export's too: `typeRole()` gives each headline the `display` role's static weight and tracking, and the fonts are the static `Geist-400.ttf`, `Geist-500.ttf` and `GeistMono-400.ttf` in `app/og-assets/`, the `weightStatic` of `label` and `display` and the mono cut for tool names, which `design:sync` copies from `brand/fonts/`, the static cuts of the pinned `geist` package; nothing imports the package at runtime. Vendor colors only inside a tile, only for a connector the card names (on a blog recap card, a connector the post names in its `card.connectors`, one to three logo tiles, which `postFrontmatter` in `lib/blog.ts` checks against the catalog and `LOGOS_ILLEGIBLE_ON_A_CARD`), only from the vendor's own file under `public/connectors/`, and only when the logo reads at the card's size: `LOGOS_ILLEGIBLE_ON_A_CARD` in `lib/connectors.ts` names the ones that do not, as measured, and the card draws their names. The root card's figure is `app/og-assets/root-figure.svg`, and a blog post's is `app/og-assets/plate-.svg`, the plate its frontmatter's `card.figure` names from `PLATES` in `lib/card-figures.ts`, never 1.1; all are written by `docs/collateral/explainer-deck-2026-09/card-figures.py` with `build-deck.py`'s own functions and never drawn by hand, and their colors are token-name placeholders that `paintFigure` in `lib/card-figures.ts` resolves with `tokenHex()`. Plate 1.1 is the one figure the root card carries; neither the root card nor a blog post's plate card carries a vendor logo; a blog recap card carries the logos its `card.connectors` names. No texture and no positive tracking. The claim sets at the 64px [`mediums/social.md`](https://www.gatlas.ai/mediums/social.md) §5 allows, or at 80px when `claimSize` in `lib/root-card.ts` finds it sets in two lines or fewer at 80px in its column; nothing else on a card exceeds the display ceiling. | `lib/design-literals.test.ts` (no color outside the export, no positive `letterSpacing`); `lib/card-figures.test.ts` (every placeholder a token, no external reference, every figure painted, regenerating reproduces the files, plate 1.1 never a plate, the claim's size); `lib/blog-card.test.ts` (the plate enum rejects 1.1 and an unknown plate, a recap with a plate, an unknown connector or tool and an illegible logo rejected, each post's plate, a recap's collage, the default card, the metadata, the root card on a failure); `lib/card-headline.test.ts` (word positions within 1px of Chromium's, the line breaks unchanged); `lib/changelog.test.ts` (every entry resolves a visual, a pinned sample of the mapping, every New connector entry a logo file, an unknown connector or tool fails the build); `lib/connector-logos.test.ts` (every logo measured at the card's size); `app/og-assets/README.md` | 2026-09-05, read from the export 2026-10-01, type from the export 2026-10-02, the D1 tiles and vendor colors 2026-10-05, the root card's deck figure 2026-10-05 (owner approved), a blog post's deck plate 2026-10-05 (owner approved, GAT-491), the blog recap collage and its vendor colors 2026-10-05 (owner approved, GAT-531) | | 14 | marketing | Motion on the example conversation's published artifact, and a scoped block for the conversation | [`mediums/marketing.md`](https://www.gatlas.ai/mediums/marketing.md) §6 gives a chart nothing. The conversation's final frame is the product's own artifact renderer, and its bars draw in once the way a chart conventionally arrives, as a re-enactment of publishing rather than an ornament on a figure. The block exists because the draw rule targets the renderer's own SVG, which no call-site utility can reach. | `/product/mcp-server` only, as that page's one figure, never on the home page and never on the ocean's ground; moved there from the home hero on 2026-09-15 when the hero became typographic. The draw runs once per pass, the loop restarts only while the box is on screen, and the reduced-motion path renders the finished chart with no motion at all. A visitor without script gets the finished transcript through a noscript style, so no reader depends on the motion. | The `.example-conversation` block in `globals.css`; `lib/landing-evidence.test.ts` | 2026-09-08, moved 2026-09-15 | | 15 | marketing | A WebGPU render loop over the dithered ground | The base document permits one bounded moment of craft on a surface that carries no figures, and [`mediums/marketing.md`](https://www.gatlas.ai/mediums/marketing.md) §6 names the hero and the auth panel as those surfaces. This is that moment. It reverses a 2026-09-04 rejection on new evidence: the static treatment it needed now exists and is paid for, the library is Vercel's own, and the port is monochrome, so no color rule moves. | Mounts only behind the nine gates listed in `components/landing/ocean-ground.tsx`, in that order; the mount gates fall back to the static ground and the two runtime gates stop the loop. Paints only `--foreground` on the surface's own ground. Never under a figure. Loads by dynamic import after idle so no route's first paint pays for it. | `lib/design-tokens.test.ts` scans the component for every gate by name and `next.config.ts` for the loader rule | 2026-09-08 | | 17 | all | `gb-note` and `gb-status` carry a shape partner the base document does not specify | §12 says every color-carried meaning has a text or shape partner, and both primitives shipped carrying tone in color alone: a note's tone was one border color, a status's was its ink and edge, and `gb-status-dot` was the same mark at the same radius in every rung. With the hue removed, three notes meaning three different things were three copies of one note. That is what a reader who cannot separate the hues gets every time, not an edge case. | A glyph on the note and a shape on the status dot, both driven by the tone attribute the layer already publishes, so no call site changes and no new name enters §11. The neutral default takes neither, because the absence of a mark is what neutral means. `/design` draws every tone beside itself with the hue removed, so a regression is visible rather than argued. | `app/primitives.css`; the hue-removed pair in `app/(dashboard)/design/primitives.tsx` | 2026-09-11 | | 18 | dashboard, share, document, deck | A desk-and-sheet surface for document artifacts, as a scoped block in `globals.css` | A document is what a board member prints. The base document's one continuous canvas is right for a screen and wrong for paper, where the page is the unit the reader holds, and drawing the sheets on screen as they will print is the whole promise of the format. The sheet's edge is earned under [`mediums/dashboard.md`](https://www.gatlas.ai/mediums/dashboard.md) §5, Boundaries: it is the boundary between one printed page and the next. | `.artifact-desk`, `.artifact-sheet` and `.artifact-frame` only, under the artifact surface, reading `--background-200`, `--background`, `--card`, `--border`, `--space-12`, `--space-6`, `--gray-alpha-100` and `--space-4` and nothing else. Every dimension is a custom property the renderer sets from `SHEET_PX` in `lib/artifacts/render-model/layout.ts`, with the A4 portrait defaults declared in the block, so the stylesheet restates no number the row model owns and `describe_artifact`'s row height and the drawn rows agree by construction. No shadow and no radius: paper has neither. In dark the desk lifts to `--gray-alpha-100` and the sheet takes the page ground, so the paper keeps an edge (row 8 makes `--card` the lifted second ground there); the deck stage takes the same pair. Chrome is the supported print-to-PDF path; Safari honors neither the page size nor its margins. Below 640px the sheets reflow to a stack and each card keeps its paper height; print keeps exact A4, on the product owner's decision of 2026-09-30. The `.artifact-frame` block puts every format's masthead on its surface's edges: it caps a dashboard's whole frame at the surface's width, a document's masthead at the sheet plus the desk's inset (`--frame-w`, set by the renderer from `SHEET_PX`, with the A4 portrait default declared in the block like the desk's), and a deck's masthead at the stage's width, `--deck-stage-w`, declared once for the stage and the masthead. | `lib/artifacts/surface-css.test.ts` (the inset, the phone reflow, the dark desk and the frame); `lib/artifacts/render-model/layout.test.ts` (`gridGeometry`, the `minRows` pin); `lib/artifacts/artifact-grid.render.test.ts` (the document lane, `frameStyle`) | 2026-09-15, widened 2026-09-30 | | 19 | deck | Deck slides are drawn on the fixed canvas the deck skill uses and scaled to fit the stage, so every type role on a slide renders below its floor whenever the stage is narrower than the canvas | §12 says never to shrink type below its floor to make density fit, and a scaled slide does exactly that. The canvas is kept at the skill's size so a slide reads on screen at the proportions its print has and one grid holds on screen, on paper and in the skill. Accepted by the product owner on the Phase 2 spec rather than found in review. The alternative, a smaller canvas on the same twelve-by-nine grid, is a two-number change in one row of `SHEET_PX` if this is ever reversed. | Slides only, inside `.artifact-deck`; the scale is one CSS expression on `.artifact-deck__canvas` and nothing else in the product scales type. Paper is unaffected: print resets the scale and each slide is its own page at canvas size. Hover readouts and keyboard stops keep working at any scale because they are markup, not pixels. | The `deck` row of `SHEET_PX` in `lib/artifacts/render-model/layout.ts`; `lib/design-tokens.test.ts` scans `components/artifacts/deck-stage.tsx` | 2026-09-15 | | 21 | reading | A guide's figures break out of the reading measure its prose holds, as a scoped block in `globals.css` | §1 item 6 keeps the measure off lookup surfaces, and a guide interleaves both in one MDX column: the raw-to-view tables are a lookup surface narrowed to 68ch they would scroll. The alternative, a width class on every figure, makes the measure an author's job on every post. | `.guide-body` only, one child selector reading `--measure` and nothing else; prose children take the measure and a `figure` takes the column. | The `.guide-body` block in `globals.css` | 2026-09-22 | | 22 | dashboard, marketing | Petrol as the one accent: a small glyph or dot at the sites §5 lists, on a light ground | The base document permits chroma for status, focus and series only. A product that is ink everywhere still needs a way to make a mark findable: the MCP note on the pages built over MCP, an included feature. Petrol was chosen on 2026-09-24 in place of the teal the product had carried, which was the artifact palette's first slot promoted for one dot. It is deep enough to read as ink at a glance and sits apart from every status hue, so it never reads as a state. It is an accent, not a brand color: the logo and every control stay ink, on the product owner's decision the same day. | The sites and forms in §5 and nowhere else. Never the logo, a button or control, text, a border, a surface, a chart or a status. Light ground only: the dark theme resolves it to ink, because deep petrol measures 1.8:1 on black and a lifted petrol turns turquoise; print takes the light value. A new site follows §5's recipe for one. | `lib/design-color.test.ts` (the sites, the forms, ink on dark, no chart slot, the logo and button stay ink); `--petrol`, `--petrol-100` in `globals.css` | 2026-09-23, petrol as the accent 2026-09-24 | | 23 | email | Email templates author every size as a literal, and every color as a resolved hex | An email client resolves no CSS custom property, so a template that read the token layer would render unstyled in most inboxes. The same argument row 13 makes for the social card, which had been ratified while the email lane, a bigger surface, had not. | `emails/` only. Colors come from `EMAIL_COLORS` in `emails/_layout.tsx`, which reads each by token name from `brand/tokens.json`, so no template types a hex and the palette is the product's. Exempted by name in `design-callsites.test.ts` from the arbitrary size and radius rules only, so the exemption is enumerable rather than implicit; every other call-site rule, the copy lint and the petrol test read the emails. The literals are held to the export: no hex, no named color, every `tokenHex()` a light-mode meaning token, every size and line height a type role's, every weight regular or medium, every template wrapped in `_layout.tsx`. | `CANNOT_READ_TOKENS` in `lib/design-callsites.test.ts`; `lib/design-literals.test.ts` | 2026-09-24, colors from the export 2026-10-01 | | 24 | dashboard, reading | The two syntax-highlighting themes carry a real palette | A syntax theme IS a palette: CodeMirror and the docs code block take color objects, and highlighting in one hue highlights nothing. This is the same permission §5 gives chart series, applied to a surface nobody had written down. | `components/sql-workspace/sql-editor.tsx` and `components/docs/code-block.tsx` only, with the `.docs-code` block in `globals.css`, which flips the docs block's highlighting to its dark theme under `.dark` by reading the variables the highlighter writes and nothing else. Neither paints product chrome; both sit inside a surface that reads tokens normally. | `CANNOT_READ_TOKENS` in `lib/design-callsites.test.ts` | 2026-09-24, the `.docs-code` block entered 2026-10-02 | | 25 | dashboard, share | Dashboard route titles take the title role, 32px, one step below page-title | The dashboard runs dense (row 6), and at the page-title size a route's title outweighed the table and controls it heads. The product had drawn these titles at 20px since the Geist foundation, with no row to say so; §5 then moved them to page-title at 40px. The product owner chose the step between on 2026-09-30, after seeing all three on a real page. | Every route title under `app/(dashboard)`, plus the artifact and component mastheads, through `PageTitle` only. The shared artifact page and its failure pages draw `PageTitle` too, so a shared artifact reads at the size its author saw. Marketing and reading route titles take page-title (§5). | The `PageTitle` pin in `lib/design-tokens.test.ts` | 2026-09-30 | | 26 | marketing | The home hero's claim, its `h1`, sets at 64px, above the display ceiling | The ceiling exists so nothing in the product outshouts its data, and the hero's claim carries none: the marketing section that is now [`mediums/marketing.md`](https://www.gatlas.ai/mediums/marketing.md) §5 named it as the one place a display scale above the ladder could enter this table, the day it was first used. The product owner decided on 2026-10-01 that it enters (decision 7 of the mediums spec). The size is 64px because Geist publishes a 64px heading rung. When this row was written the social card set its claim at 64px too; since 2026-10-05 a card claim that sets in two lines at 80px may take 80px ([`mediums/social.md`](https://www.gatlas.ai/mediums/social.md) §5, row 13), a rule for a feed image read at half size that leaves the hero at 64px. | The `h1` of `components/hero-section-7.tsx` alone, at the breakpoint where it takes `display` today; never the `MCP_CLAIM` line above it, which sets at `metadata`. Every other route title on marketing takes `page-title`, the target state the marketing phase (GAT-450) reaches. The tracking ramp's tightest step applies, as at every size at or above 30px. Ratified ahead of its use: the marketing phase (GAT-450) declares the token and applies it, and until then the hero renders at the ceiling. | Nothing yet: the marketing phase (GAT-450) pins it in `lib/design-marketing.test.ts` | 2026-10-01, the card's size separated from the hero's 2026-10-05 | | 27 | deck | Deck titles, eyebrows, item heads, legend items, captions and figure labels are short noun phrases, not statements | The base document and [`content/copy.md`](https://www.gatlas.ai/copy.md) ask for a title that states its claim. The product owner ruled otherwise for decks on 2026-10-01, after reviewing the explainer and vision decks; [`mediums/deck.md`](https://www.gatlas.ai/mediums/deck.md) §7 holds the rule and its examples. | Deck sheets only, authored and artifact. A page, a document or a post states its claim. | Review: the collateral block of `docs/pr-review-bar.md` (2.9) | 2026-10-01 | | 28 | dashboard, share | An artifact tab panel draws its own focus ring, as a scoped rule in `globals.css` | §12 asks for visible focus on every focusable element. Radix makes each tab panel a tab stop, and the generated `TabsContent` removes its outline, so the panel took focus and changed no pixels. The ring cannot go into the generated component without an edit `shadcn add` would overwrite (§3), so it hangs on the renderer's own hook. The product owner ratified it on 2026-10-02. | `[data-artifact-tabpanel]:focus-visible` only, set by `components/artifacts/tabs-block.tsx`, reading `--ring` and nothing else. The ring is drawn inside the box, because the panel sits in a scroll box that clips anything painted outside it. | `lib/design-tokens.test.ts` (the ring and its inset); `lib/artifacts/artifact-grid.render.test.ts` (every panel carries the hook) | 2026-10-02 | | 29 | marketing | The `/brand` page draws the palette and the marks as content: hex literals, raw palette classes and literal white and black grounds | The page's subject is the brand's values. A swatch labeled with its own hex has to be that hex, and the mark is shown on a fixed white and a fixed black ground whatever the theme, because that is what a reader of a brand page checks. Reading tokens would make the page show whatever the theme resolves, which is the one thing it exists not to do. The product owner ratified it on 2026-10-02. | `app/(marketing)/brand/` only, excused by name from the hex, raw palette and literal monochrome rules and from no other rule; it names petrol as content and draws no accent site. | `CANNOT_READ_TOKENS` in `lib/design-callsites.test.ts`; `NAMES_PETROL` in `lib/design-color.test.ts` | 2026-10-02, exempt since 2026-09-24 | | 30 | all | Hairlines below WCAG 1.4.11's 3:1: the decorative edges (`--border`, `--border-subtle`) and a field's edge at rest (`--input`, and the `ring-foreground/10` hairline the generated input, textarea and native select draw) | 1.4.11 asks 3:1 only of the boundary a user needs to find a component. A card's edge, a table rule or a separator identifies no control, so it stays a hairline. A field is such a component, and three things identify it, each clearing the bar: a visible label, a `--border-strong` edge on hover, and the focus ring. Its resting edge stays Geist's own hairline, as Geist's inputs keep theirs. Raising `--input` to 3:1 at rest takes alpha 0.42 in light and 0.35 in dark, and draws every form and filter row in outlines Geist does not have. Recommended over that stricter edge from renders of both (GAT-505). | Every field is named by text on screen: a `