# Remarque — llms-full.txt

> Generated at site build time from remarque-tokens v0.33.0: AGENT_RULES.md verbatim, then a compact token table. For the short pointer see /remarque/llms.txt; for the full spec see REMARQUE.md; for every token with DTCG types see /remarque/tokens.json.

---

# Remarque — Agent Rules

**This document is the implementation contract for any agent (AI or human) building with the Remarque design system.**

Read `REMARQUE.md` first for the full system specification. This file tells you *how to build*, not *what the system is*.

---

## Prefer the Registry Over Transcribing Prose

For the Essay Module, the Broadsheet pattern, Forms and the Chrome Module (`remarque-tokens/essay`, `remarque-tokens/broadsheet`, `remarque-tokens/forms`, `remarque-tokens/chrome`), a machine-readable markup-contract registry ships alongside the spec (REMARQUE.md "The Registry"; issue #100). **Agents building a Remarque page SHOULD fetch the relevant registry item and apply its `usage.html`/CSS `content` verbatim, rather than re-typing the markup from this file's or REMARQUE.md's prose.**

- Fetch `https://williamzujkowski.github.io/remarque/registry/<name>.json` (`essay`, `broadsheet`, `forms`, `skip-link`, `breadcrumb`, `pager`, `tags`, `deck-picker`, or `palette-deck`), or read it from an installed package at `node_modules/remarque-tokens/registry/<name>.json` — same content either way.
- The known-good markup lives in `files[].content` where `type` is `"remarque:markup"`; the CSS module (if any) is in the `"remarque:css"` entry. Both are the exact, versioned, hash-pinned (`integrity`) bytes — copy them, don't re-derive them from memory.
- This exists specifically to prevent transcription bugs like #89 (a sidenote `aria-label` that drifted out of DOM order because an agent hand-copied ~80 lines of spec prose instead of applying known-good markup). Reading REMARQUE.md's prose for the *reasoning* behind a contract is still expected; reading it as the *source of the markup you type* is the failure mode the registry exists to close.
- No CLI installer ships this round — there is no `npx` command that writes these files into a project for you. Fetch the JSON, then apply the markup with your own editing tools.

---

## Build Order

Execute in this exact order. Do not skip steps. Do not reorder.

1. **Load tokens.** Import `fonts.css` then `tokens.css`, and wire Tailwind: v4 projects import `theme.css` (after `tailwindcss` and the tokens, unlayered — see Pitfall #7); v3 projects use `tailwind.config.js`. Verify fonts load correctly.

2. **Set up global typography.** Apply display, title, section, body, meta, and prose classes. Verify the type scale renders correctly at mobile and desktop widths.

3. **Build the layout shell.** Header, content container (with constrained max-widths), and footer. The shell must enforce reading widths — content should never run full-width on large screens.

4. **Implement prose styling.** Article body text, headings within prose, blockquotes, lists, inline code, links. This is the core of Remarque — get it right before touching anything else.

5. **Implement metadata components.** Mono-styled date, reading time, tags, and status labels.

6. **Build navigation and footer.** Quiet, minimal. Navigation is functional, not decorative.

7. **Only then** build supplementary UI: buttons, tags, cards (if justified), code blocks, tables.

8. **Validate readability on mobile** before adding any visual polish.

9. **Verify every page conforms** to one of the seven archetypes (Essay, Project Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery).

**Why this order matters:** Most agents build polished components first and bolt on typography later. That produces the exact aesthetic Remarque exists to prevent. Typography and prose are the foundation. Everything else is furniture.

---

## Non-Negotiable Rules

These are not guidelines. Agents must follow them literally.

### Token Tiers

- NEVER change a value in `tokens-core.css` (or its tokens' values anywhere) — core tokens are Remarque's identity; changing them means the project has forked the system
- Site personalization happens ONLY by overriding `tokens-palette.css` tokens (font slots from the approved pairings, colors, accent, `--content-reading` per the measure table) in a stylesheet loaded after the tokens
- After ANY palette change, run the audit and fix every failure before shipping — `npm run audit` inside this repo; `npx remarque-audit --palette <file> --src <dir>` in a consumer project (the npm script only exists here)
- A generated palette override (from `npx remarque-theme <light> --dark <dark>`, see REMARQUE.md "Color Providers") is regenerated, never hand-edited — if it needs to change, change the source theme slugs and re-run `remarque-theme`, don't patch the emitted CSS directly
- The DEFAULT palette in `tokens-palette.css` is bound to the upstream `remarque-light`/`remarque-dark` themes (REMARQUE.md "Color Providers" identity/serialization contract) — `node scripts/palette-golden.mjs` must stay green. Changing a default color means changing the upstream themes first (or in lockstep with the hand file), never editing `tokens-palette.css` alone to chase a design change; a value edited only on this side is drift, not personalization, and the golden gate exists to catch it

### Typography

- Body text is never smaller than `--text-body` (17px / 1.0625rem)
- Prose columns never exceed `--content-reading` (38rem default — ~71 measured characters of 17px Inter)
- Display/title text always uses `--font-display` (Newsreader)
- Body text always uses `--font-body` (Inter)
- Mono text is *only* for: metadata, code, labels, timestamps, technical accents
- Line height for body text is `--leading-body` (1.75) — never less

### Layout

- No page shows more than 3 content sections above the fold
- The first screen contains only: title, metadata, and the start of content
- Top padding before the main heading is at least `--space-9` (6rem)
- The site uses a **single centered column** layout: BaseLayout constrains all content to `content-standard` (72rem) centered. Individual pages do NOT set their own outer width constraints.
- Within the centered column, use `.content-reading` for prose-width sections (38rem default, auto-centered within the 72rem column)
- Do NOT use Tailwind's `max-w-reading` or `max-w-standard` on page sections — these only set max-width without centering. Use the CSS classes `.content-reading` / `.content-standard` instead, which include `margin-inline: auto`
- Code blocks (`<pre>`) inherit the width of their parent container — no special wrapping needed when the parent is already constrained
- Stacking order is structural, not personalization: never author a bare `z-index` number — reference `tokens-core.css`'s `--z-*` scale (`--z-base`/`--z-sticky`/`--z-dropdown`/`--z-overlay`/`--z-modal`/`--z-toast`/`--z-skip-link`). Tailwind v4 has no `--z-index-*` theme namespace, so use arbitrary values (`z-[var(--z-modal)]`) rather than bare Tailwind numbers. See REMARQUE.md "Stacking."

### Color

- Accent color is used for exactly two things: inline links and one interactive element per viewport
- Dark mode is not an inverted light mode — it must be independently tuned for readability
- Background colors use `--color-bg`, never pure white (#fff) or pure black (#000)
- State colors (`--color-error`/`--color-success`/`--color-warning`/`--color-disabled`, plus the `-subtle` banner-background companions on the first three) are for feedback moments only — form validation, status banners, disabled controls — never for decoration. The one-accent rule above still governs everything else. See REMARQUE.md "State Colors."

### Components

- No component should be visually louder than the content it contains
- Borders use `--color-border` at 1px — never thicker, never drop shadows as replacements
- `--color-border` is decorative-only (below the 3:1 non-text minimum by design). Boundaries of interactive elements (inputs, dialogs, active states) use `--color-border-bold`, which meets WCAG 1.4.11
- Border radius never exceeds `--radius-md` (0.5rem / 8px)
- Buttons are quiet: text-only or subtle bordered. Never filled/solid as default.

### Motion

- Motion is permitted *only* on: hover states, focus rings, theme transitions
- Duration is `--motion-fast` (120ms) for micro-interactions, `--motion-normal` (180ms) for transitions
- No scroll-triggered, entrance, staggered, or parallax animations. Ever.
- All motion must respect `prefers-reduced-motion` — always use the duration tokens (tokens.css zeroes them under reduced motion); never hardcode durations

### Images

- Images stay within `--content-reading` width (diagrams may use `--content-standard`)
- Images get a 1px `--color-border` border, never shadows
- Captions use `--font-mono` at `--text-meta` size
- No decorative images. Every image serves the content.

---

## Decision Protocol

When you face a design choice not explicitly covered above, apply these filters in order:

1. **Is it more readable?** → Choose that.
2. **Is it more typographically disciplined?** → Choose that.
3. **Is it quieter?** → Choose that.
4. **Is it more tokenized/reusable?** → Choose that.
5. **Does it have less visual noise?** → Choose that.

If you are still unsure, choose the option that looks more like a well-typeset book and less like a web application.

---

## Disallowed Patterns

Do not introduce any of the following unless the project owner explicitly requests them:

- Material Design visual language (elevation, ripple, FAB)
- Large decorative gradients
- Glassmorphism / frosted glass
- Card grids as primary layout
- Over-rounded corners (border-radius > 0.5rem)
- "Friendly SaaS" visual language
- Flashy or attention-seeking motion
- Dense admin/dashboard layouts
- Full-width prose on screens wider than 768px
- Hero images or banners
- Multiple CTAs on a single page
- Feature comparison grids
- Newsletter popups or modals
- Hamburger menus on desktop
- Sticky headers that consume vertical space
- Social share buttons in content areas
- Pill-shaped tag badges (use plain mono text)
- Skeleton loading screens (use a simple spinner or nothing)

---

## File Structure Convention

```
project/
├── fonts.css                 # Self-hosted @font-face declarations (import before tokens)
├── tokens.css                # Aggregator — imports the two tiers below
├── tokens-core.css           # CORE tier: type scale, spacing, widths, radius, motion, prose machinery. NEVER override
├── tokens-palette.css        # PALETTE tier: font slots, colors, accent, reading measure. Override freely, then run the audit
├── prose.css                 # .remarque-prose long-form styling (aggregated by tokens.css; own subpath for opt-out)
├── essay.css                 # Optional Essay module: sidenotes + sticky TOC rail (own subpath, NOT aggregated — import explicitly)
├── broadsheet.css            # Optional Broadsheet pattern: masthead, lead, entry list, post kicker (own subpath, NOT aggregated — import explicitly)
├── forms.css                 # Optional form control primitives: field/input/checkbox/radio/button, state-color wiring (own subpath, NOT aggregated — import explicitly)
├── deck.js                   # Optional Palette Deck module: switch/persist/restore between generated palettes, plus bindPicker() (own subpath, NOT aggregated — dependency-free ESM)
├── deck/                     # deck.css + deck.json: the prebuilt curated deck (remarque-deck --curated, 0.31); curated.json is its source list
├── print.css                 # Print stylesheet (own subpath, NOT aggregated — import explicitly)
├── theme.css                 # Tailwind v4 adapter (@theme inline) — import after tailwindcss + tokens
├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects use theme.css instead
├── public/
│   └── fonts/                # Self-hosted woff2 fonts (Inter, Newsreader, JetBrains Mono)
├── styles/
│   ├── globals.css           # @import "tailwindcss"; @import "./tokens.css"; @font-face declarations
│   ├── prose.css             # Article/essay body text styling (or use .remarque-prose from tokens.css)
│   └── components.css        # Component-specific styles (minimal)
├── components/
│   ├── Layout.{jsx,astro}    # Layout shell (header + content + footer + skip-link + theme toggle)
│   ├── Nav.{jsx,astro}       # Navigation (content pages + design system docs)
│   ├── Footer.{jsx,astro}    # Footer
│   ├── Meta.{jsx,astro}      # Metadata row component
│   └── Prose.{jsx,astro}     # Prose wrapper (<div class="remarque-prose content-reading">)
└── pages/
    ├── index                 # Landing archetype
    ├── writing/[slug]        # Essay archetype
    ├── projects/[slug]       # Project Dossier archetype
    └── notes                 # Notebook archetype
```

Three further archetypes — Reference/Docs, Changelog, Gallery — are specified in REMARQUE.md but have no reference page in this repo's demo site yet; build them per spec, they follow the same file-structure conventions as the four above (e.g. `docs/[slug]`, `changelog`, `gallery` or `browse`).

### Implementation Pitfalls (learned from reference implementation)

1. **Tailwind spacing collision:** Never map Remarque's `--space-N` values onto Tailwind's default numeric spacing keys — in v4 `@theme` that means no `--spacing-9`…`--spacing-12`, and in the v3 config no `spacing: { "5"…"12" }` overrides — or `mt-12` produces 192px instead of 48px. Both shipped artifacts namespace instead: the v3 config exposes `mt-remarque-9` etc., the reference v4 `@theme` uses `--spacing-remarque-N`. Use those, or `var(--space-N)` in arbitrary values.

2. **Prose alignment:** The essay header and prose body must BOTH sit in the same centered reading column to prevent misalignment — put `.content-reading` on both (it sets `max-width` and `margin-inline: auto`). Not Tailwind's `max-w-reading mx-auto`: it renders the same on screen, but `print.css`'s full-width reset is keyed on `.content-reading`, so a `max-w-reading` header prints indented from its body (the demo shipped exactly that until the 2026-10 design review).

3. **Dark mode specificity:** Define `[data-theme="light"]` and `[data-theme="dark"]` overrides in addition to the `:root` defaults. Without an explicit light override, users with `prefers-color-scheme: dark` cannot toggle to light mode. Since 0.24.0 (`light-dark()` + `color-scheme`, REMARQUE.md "Color Scheme & light-dark()"), the shipped default palette's own `[data-theme="light"]` override is just `color-scheme: light` — a consumer palette that still authors the older two-declaration convention needs the fuller override this rule originally describes.

4. **Self-hosted fonts:** Replace the Google Fonts CDN link with self-hosted woff2 files + `@font-face` declarations. Use `font-display: swap` and `<link rel="preload">` for performance.

5. **GitHub Pages base path:** When deploying to a subpath (e.g., `/remarque/`), all internal links must use a base URL helper (Astro: `import.meta.env.BASE_URL`). Set `base` in your framework config.

6. **String-form @import only:** Always write `@import './tokens.css';` (string form). Tailwind v4 inlines only the string form: given `@import url(./tokens.css);`, `tailwindcss` 4.3.3's `compile()` passes the line through unresolved instead of inlining the file (checked 2026-10), and in consumer builds the entire token cascade went missing from the output without a build error. Verify the built CSS contains `.remarque-prose` after changing imports.

7. **Tokens must be imported unlayered (Tailwind v4):** never `@import "remarque-tokens" layer(...)`. theme.css's `@theme inline` mappings emit same-named self-referencing declarations inside `@layer theme`; the real token values win only because unlayered declarations beat layered ones. Layering the tokens makes every mapped utility circular and invalid, with no build error.

8. **Arbitrary type-scale sizes need the `length:` hint (Tailwind v4):** write `text-[length:var(--text-meta)]`, never `text-[var(--text-meta)]`. Tailwind cannot infer a bare `var()`'s type, treats `text-[…]` as a color, and emits `color: var(--text-meta)` — the size never applies and the invalid color clobbers the element's real color utility, with no build error. `theme.css` deliberately maps no `--text-*` keys (they would collide with the unlayered `.text-meta`/`.text-body` classes). `remarque-audit` fails on the ambiguous form (`srcScans.ambiguousTextSize`). The demo site shipped 134 of these until the 2026-10 design review.

---

## Quality Checklist

Before considering any implementation complete, verify:

- [ ] Fonts load: Newsreader for display, Inter for body, JetBrains Mono for meta
- [ ] Fonts are self-hosted (no Google CDN requests in network tab)
- [ ] Body text is ≥17px on all viewports
- [ ] Prose column is ≤ `--content-reading` on desktop, and body lines measure a median of 66–72 rendered characters (REMARQUE.md "Measure Compensation" — count characters, not `ch`)
- [ ] Prose header and body are aligned (both centered with `mx-auto` or both left-aligned)
- [ ] Line height for body text is 1.75
- [ ] Dark mode is readable and independently tuned (not just inverted)
- [ ] Theme toggle works in both directions (light→dark AND dark→light)
- [ ] No page has more than 3 content sections above the fold
- [ ] Top padding before main heading is ≥6rem
- [ ] Accent color appears in ≤2 roles per viewport
- [ ] No scroll-triggered or entrance animations exist
- [ ] Every image has a 1px border and mono caption
- [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery)
- [ ] If the Essay uses sidenotes/a TOC rail (`remarque-tokens/essay`): `.remarque-sidenote-ref`/`.remarque-sidenote` alternate in strict DOM order, the rail never intrudes into `.remarque-prose`'s own measure, and the page renders correctly with `essay.css`'s `@media` block deleted (the narrow-viewport/no-JS fallback)
- [ ] If a Landing/archive page uses the Broadsheet pattern (`remarque-tokens/broadsheet`): entry numerals are generated from `data-entry-number` via `attr()` (not `counter()`), the entry list stays a `<ul>` (not `<ol>` — the numeral is `aria-hidden` and decorative), and every kicker/dateline row uses the label voice: tracked capitals (`text-transform: uppercase` + `--tracking-caps`), because the default mono face has no small caps; `font-variant-caps: all-small-caps` only on a label face that has `smcp` + `c2sc` (REMARQUE.md "Small Caps"; `remarque-audit` fails synthesized small caps)
- [ ] If a page uses a drop cap (`.remarque-prose--dropcap`, or `.remarque-lead-lede` in the Broadsheet): it comes from `remarque-tokens/dropcap` (or `prose.css`, which imports it), never a pasted copy; the page builder adds `.remarque-dropcap--short` to a two-line lead and `.no-drop-cap` to a one-line or lowercase-led one; `initial-letter` stays an integer. Sidenote markers keep their 24x24 hit area (`essay.css`).
- [ ] Site chrome uses `remarque-tokens/chrome` instead of hand-rolled copies: `.remarque-skip-link` is the first focusable element and targets `<main id="main-content" tabindex="-1">`; a breadcrumb's current page is `<span aria-current="page">`, never a link, with no separator typed into the DOM; prev/next links carry `rel="prev"`/`rel="next"` and an endpoint with nowhere to go is omitted (or plain text in numbered pagination), never a disabled-looking link; tags are plain mono links with `rel="tag"`, no border, fill or radius (REMARQUE.md "Chrome Module")
- [ ] If a page uses form controls (`remarque-tokens/forms`): checkboxes/radios are styled with `accent-color` only — never `appearance: none` plus a hand-drawn replacement; every control (input, button, checkbox/radio label) is ≥44×44px; every input collecting known personal data has a valid `autocomplete` token and paste is never blocked (WCAG 3.3.7/3.3.8); validation state lives on `.remarque-field[data-state]` AND a real `aria-invalid`/`aria-describedby` pair on the input, not `data-state` alone; every state message says what's wrong in words (the shipped glyph has empty alt text and is the non-color cue, not the message); a pending submit disables the button, changes its label and announces through `role="status"`, never a spinner or `aria-busy` on the button; disabled controls use `--color-disabled`, never a state color
- [ ] If a page uses the Palette Deck (`remarque-tokens/deck`): `data-palette` is set/cleared on the same root element as `data-theme` (they compose, never conflict); the FOUC-safe restore is a synchronous classic `<script>` physically in `<head>` (never `type="module"`, which defers); the switcher control itself is native and keyboard-operable at ≥44×44px (the `deck-picker` registry item: radio inputs in a `<fieldset>`, wired by `bindPicker()`), not a hand-rolled widget; every palette comes from `remarque-tokens/deck.css` (the prebuilt curated deck) or `remarque-deck`, never hand-authored; the picker sits in the header beside the light/dark toggle (the `remarque-deck-picker--popover` variant, `bindPicker(…, { dismissible: true })`), not only in a footer; the site's own palette stays the default (`value=""`), and a site with its own palette declares `[data-palette-swatch="default"]` swatches (or builds with `remarque-deck --default`)
- [ ] Mobile version is roomy — not a compressed desktop layout
- [ ] Mobile nav links have ≥44px touch targets (meets WCAG 2.5.8 AA; exceeds it, and meets 2.5.5 AAA)
- [ ] WCAG 2.2 AA (not 2.1): any consumer sticky/fixed chrome has `scroll-padding-top`/`-bottom` so focus is never obscured (2.4.11); inputs collecting known personal data carry a valid `autocomplete` token and never block paste (3.3.7, 3.3.8); `cd site && npx playwright test tests/a11y.spec.ts` (axe-core) passes. See REMARQUE.md "WCAG 2.2 AA Criterion Map"
- [ ] No pure white or pure black backgrounds
- [ ] `npm run audit` passes (contrast, gamut, font floors, hardcoded colors)
- [ ] Muted text placed on `--color-surface` still meets 4.5:1 (check the surface pairing, not just bg)
- [ ] All transitions use the motion duration tokens (reduced-motion support depends on it)
- [ ] Skip-to-content link present and functional
- [ ] If state colors are used (error/success/warning/disabled): only for feedback moments (validation, banners, disabled controls), never decoration; every state text color and `-subtle` companion passes `npm run audit`
- [ ] No bare `z-index` numbers anywhere in the page's CSS — every stacking layer references `tokens-core.css`'s `--z-*` scale
- [ ] OG meta tags present (og:title, og:description, og:image)
- [ ] `<html lang="en">` attribute set
- [ ] The site looks more like a book than a web app
- [ ] Tailwind spacing utilities (`mt-12`, `pt-8`) produce expected values (not overridden by `@theme`)
- [ ] Arbitrary type-scale sizes use `text-[length:var(--text-*)]` — verify a computed `font-size` on one meta element, not just the class name (Pitfall #8)

---

## Machine-Readable Output

Two tools emit structured JSON for agents/tooling instead of colored
stdout — pass `--json` and parse stdout as a single JSON document. Exit
codes are unchanged in both cases; `--json` only changes what stdout
contains (all human progress lines, including error lines normally on
stderr, are suppressed — nothing but the JSON document is written).

### `remarque-audit --json`

```
node scripts/audit.mjs --palette <file> --src <dir> --json
npx remarque-audit --palette <file> --src <dir> --json
```

```ts
{
  version: string;       // the remarque-tokens package version running the audit
  palette: string;       // the --palette path as given
  src: string;            // the --src path as given
  passed: boolean;       // true iff failures.length === 0 (warnings do not count)
  contrast: Array<{
    theme: 'light' | 'dark';
    fg: string;            // fg token name, no leading --
    bg: string;            // bg token name, no leading --
    label: string;         // human label from the CHECKS table (e.g. "primary text")
    required: number;      // minimum ratio (e.g. 4.5, 7.0, 3.0)
    actual: number | null; // computed ratio rounded to 2dp, or null if fg/bg was unresolvable
    ok: boolean;
    apcaLc?: number;       // APCA Lc (SAPC 0.0.98G), 1dp, REPORT-ONLY: never affects ok/passed; + = dark text on light, − = light on dark. Added in 0.30.0
    error?: string;        // present only when actual is null (unresolved var()/missing token)
  }>;
  gamut: Array<{
    theme: 'light' | 'dark';
    token: string;          // token name, no leading --
    value: string;          // e.g. "oklch(0.5 0.14 250)"
    ok: boolean;            // false = outside sRGB gamut (browsers will clip it)
  }>;
  srcScans: {
    fontFloor: Array<{ file: string; line: number; size: number; unit: 'rem' | 'px' }>;
    unverifiableFontSize: Array<{ file: string; line: number; snippet: string }>;
    hardcodedColors: Array<{ file: string; line: number; snippet: string }>;
    oklchLiteral: Array<{ file: string; line: number; snippet: string }>;
    ambiguousTextSize: Array<{ file: string; line: number; snippet: string }>; // Tailwind text-[var(--text-*)] (Pitfall #8)
  };
  failures: string[];      // every failure as a human-readable message, same text the non-JSON run prints
  warnings: Array<{        // palette-coherence warnings (REMARQUE.md "Palette Coherence"); added in 0.28.0, additive
    id: string;             // 'text-tier-monotonic' | 'accent-vs-fg' | 'accent-vs-error' | 'accent-vs-viz-1' | 'error-vs-success-deutan' | 'surface-step' | 'viz-cvd-normal' | 'viz-cvd-protan' | 'viz-cvd-deutan' | 'viz-cvd-tritan'
    theme: 'light' | 'dark';
    tokens: string[];       // the token names involved, no leading --
    actual: number;         // measured value (ΔE2000, or the contrast shortfall for text tiers), 2dp
    threshold: number;      // the minimum it was compared to
    message: string;        // human-readable, same text the non-JSON run prints
  }>;
  fontFeatures: Array<{    // font-feature requests the face can't render (REMARQUE.md "Small Caps"); added in 0.28.0, additive
    file: string;           // 'remarque-tokens/<module>.css' for the package's own modules, else the --src-relative path
    line: number; selector: string;
    family: string | null;  // first family of the rule's font-family (or --font-body when the rule sets none)
    inferred: boolean;      // true when the family was inferred as --font-body
    tag: string;            // OpenType feature tag, e.g. 'smcp', 'onum'
    via: string;            // the declaration that asked for it
    status: 'missing' | 'conditional' | 'unverifiable'; // only 'missing' is also a failure
  }>;
}
```

`--font-features <manifest.json>` (repeatable) adds your own faces to the check, in the shape of the package's `fonts/features.json` (`{ families: { "<family>": { figures: { style, spacing }, files: { "<file>": { features: [tags] } } } } }`). Faces missing from every manifest are reported `unverifiable` and never fail.

`warnings` never affects `passed` or the exit code in this release — only `failures` does. The warning set is expected to grow and to be promoted to failures in a later minor, so treat an unknown `id` as informational.

`contrast` and `gamut` list EVERY check performed (passing and failing);
only `srcScans` and `failures` are violation-only lists, since a source
scan that finds nothing has nothing to report per line.

### `remarque-drift --json`

```
node scripts/drift-check.mjs --css-file <path> --package-dir <dir> --json
npx remarque-drift --css-file <path> --package-dir <dir> --json
```

```ts
{
  cssFile: string;
  packageDir: string;          // resolved node_modules/remarque-tokens path
  installedVersion: string;    // version of the INSTALLED remarque-tokens being checked against
  deviationDoc: string | null; // path to DESIGN-DEVIATIONS.md / DESIGN-NOTES.md, or null if none found
  passed: boolean;             // true iff fail.length === 0
  fail: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
  warn: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string; doc: string }>;
  info: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
  summary: { fail: number; warn: number; info: number }; // counts of distinct TOKENS with an entry, not records (one token can produce two records — light + dark)
}
```

`fail`/`warn`/`info` are one record per (token, theme) mismatch — see
`scripts/drift-check.mjs`'s doc comment and REMARQUE.md's "Token Tiers"
for the FAIL/WARN/INFO classification these mirror.

### `tokens.json` / `tokens.schema.json`

`remarque-tokens/tokens.json` is always machine-readable (no flag
needed) and now ships with a published JSON Schema — see REMARQUE.md
"DTCG Conformance" for the schema's location, the `$schema` pointer, and
the documented DTCG divergences.

---

## Installing the Skills

This package ships three Claude Code skills under the npm subpath
exports `remarque-tokens/skills/remarque`, `remarque-tokens/skills/adopt`,
and `remarque-tokens/skills/new-page` (resolving to `skills/remarque/
SKILL.md`, `skills/remarque-adopt/SKILL.md`, and `skills/remarque-new-page/
SKILL.md` in the installed package). Claude Code only discovers skills
from a project's own `.claude/skills/` (or `~/.claude/skills/`), never
from `node_modules` — copy them in explicitly, one `cp` per skill:

```bash
mkdir -p .claude/skills
cp -r node_modules/remarque-tokens/skills/remarque .claude/skills/remarque
cp -r node_modules/remarque-tokens/skills/remarque-adopt .claude/skills/remarque-adopt
cp -r node_modules/remarque-tokens/skills/remarque-new-page .claude/skills/remarque-new-page
```

The copies are versioned with the installed package, not auto-updating —
re-copy all three after a MAJOR bump, or any time this file's
"Machine-Readable Output" shape changes.

- `remarque` — the build/review contract for pages on the current version (tier rules, archetypes, pitfalls #6/#7).
- `remarque-adopt` — the version-bump/migration playbook (this file's "Machine-Readable Output" section is its main dependency): verify the resolved version past the 0.x caret freeze, discover newly-required tokens from `remarque-audit --json`, solve missing values against the consumer's own backgrounds, classify `remarque-drift --json` output, report against a fixed PR-body contract.
- `remarque-new-page` — the page-building procedure, companion to (not a restatement of) the `remarque` loader skill: pick the archetype, fetch-and-verify the relevant registry item instead of transcribing its markup, wire the page per the pitfalls above, gate acceptance on `remarque-audit --json` plus the registry item's own markup-contract assertions.

---

## How to Reference This System

In prompts, issues, or agent instructions, use:

```
Build this page using the Remarque design system.
See: REMARQUE.md for specification, AGENT_RULES.md for implementation contract, tokens.css for design tokens.
```

Agents should load all three files before beginning work.

---

# Token table (remarque-tokens v0.33.0)

Core tier: immutable identity, same value in both themes. Palette tier: the sanctioned personalization surface, with a light and a dark value (dark may inherit light).

| token | tier | light | dark |
| --- | --- | --- | --- |
| --text-display | core | clamp(2.75rem, 5.5vw, 5rem) | clamp(2.75rem, 5.5vw, 5rem) |
| --text-title | core | clamp(1.875rem, 3.5vw, 3rem) | clamp(1.875rem, 3.5vw, 3rem) |
| --text-section | core | clamp(1.375rem, 2.25vw, 2rem) | clamp(1.375rem, 2.25vw, 2rem) |
| --text-body-lg | core | 1.1875rem | 1.1875rem |
| --text-body | core | 1.0625rem | 1.0625rem |
| --text-meta | core | 0.875rem | 0.875rem |
| --text-micro | core | 0.8125rem | 0.8125rem |
| --leading-display | core | 1.05 | 1.05 |
| --leading-title | core | 1.15 | 1.15 |
| --leading-section | core | 1.2 | 1.2 |
| --leading-body | core | 1.75 | 1.75 |
| --leading-meta | core | 1.5 | 1.5 |
| --tracking-display | core | -0.02em | -0.02em |
| --tracking-title | core | -0.015em | -0.015em |
| --tracking-body | core | 0em | 0em |
| --tracking-meta | core | 0.02em | 0.02em |
| --tracking-caps | core | 0.06em | 0.06em |
| --weight-regular | core | 400 | 400 |
| --weight-medium | core | 500 | 500 |
| --weight-semibold | core | 600 | 600 |
| --space-1 | core | 0.25rem | 0.25rem |
| --space-2 | core | 0.5rem | 0.5rem |
| --space-3 | core | 0.75rem | 0.75rem |
| --space-4 | core | 1rem | 1rem |
| --space-5 | core | 1.5rem | 1.5rem |
| --space-6 | core | 2rem | 2rem |
| --space-7 | core | 3rem | 3rem |
| --space-8 | core | 4rem | 4rem |
| --space-9 | core | 6rem | 6rem |
| --space-10 | core | 8rem | 8rem |
| --space-11 | core | 10rem | 10rem |
| --space-12 | core | 12rem | 12rem |
| --content-standard | core | 72rem | 72rem |
| --content-wide | core | 88rem | 88rem |
| --radius-sm | core | 0.25rem | 0.25rem |
| --radius-md | core | 0.5rem | 0.5rem |
| --radius-none | core | 0 | 0 |
| --border-width | core | 1px | 1px |
| --border-style | core | solid | solid |
| --motion-fast | core | 120ms | 120ms |
| --motion-normal | core | 180ms | 180ms |
| --motion-easing | core | ease-out | ease-out |
| --z-base | core | 0 | 0 |
| --z-sticky | core | 10 | 10 |
| --z-dropdown | core | 20 | 20 |
| --z-overlay | core | 30 | 30 |
| --z-modal | core | 40 | 40 |
| --z-toast | core | 50 | 50 |
| --z-skip-link | core | 60 | 60 |
| --font-display | palette | "Newsreader", Georgia, "Times New Roman", serif | "Newsreader", Georgia, "Times New Roman", serif |
| --font-body | palette | "Inter", ui-sans-serif, system-ui, -apple-system, sans-serif | "Inter", ui-sans-serif, system-ui, -apple-system, sans-serif |
| --font-mono | palette | "JetBrains Mono", ui-monospace, "Cascadia Code", "Fira Code", monospace | "JetBrains Mono", ui-monospace, "Cascadia Code", "Fira Code", monospace |
| --content-reading | palette | 38rem | 38rem |
| --weight-display | palette | 400 | 500 |
| --color-bg | palette | oklch(0.975 0.005 80) | oklch(0.16 0.01 80) |
| --color-bg-subtle | palette | oklch(0.955 0.005 80) | oklch(0.19 0.01 80) |
| --color-fg | palette | oklch(0.18 0.01 80) | oklch(0.90 0.005 80) |
| --color-fg-muted | palette | oklch(0.43 0.015 80) | oklch(0.70 0.01 80) |
| --color-muted | palette | oklch(0.54 0.01 80) | oklch(0.60 0.01 80) |
| --color-border | palette | oklch(0.88 0.005 80) | oklch(0.25 0.005 80) |
| --color-border-bold | palette | oklch(0.62 0.01 80) | oklch(0.50 0.01 80) |
| --color-surface | palette | oklch(0.965 0.005 80) | oklch(0.19 0.01 80) |
| --color-accent | palette | oklch(0.50 0.14 250) | oklch(0.68 0.12 250) |
| --color-accent-hover | palette | oklch(0.42 0.11 250) | oklch(0.75 0.12 250) |
| --color-accent-subtle | palette | oklch(0.95 0.02 250) | oklch(0.22 0.04 250) |
| --color-link | palette | var(--color-accent) | var(--color-accent) |
| --color-link-hover | palette | var(--color-accent-hover) | var(--color-accent-hover) |
| --color-focus-ring | palette | var(--color-accent) | var(--color-accent) |
| --color-selection-bg | palette | oklch(0.92 0.04 250) | oklch(0.30 0.06 250) |
| --color-selection-fg | palette | var(--color-fg) | oklch(0.92 0.005 80) |
| --color-code-bg | palette | oklch(0.945 0.005 80) | oklch(0.20 0.005 80) |
| --color-code-fg | palette | var(--color-fg) | oklch(0.88 0.005 80) |
| --color-syntax-keyword | palette | oklch(0.51 0.12 250) | oklch(0.61 0.11 250) |
| --color-syntax-string | palette | oklch(0.50 0.12 145) | oklch(0.60 0.11 145) |
| --color-syntax-constant | palette | oklch(0.51 0.105 85) | oklch(0.61 0.11 84) |
| --color-syntax-comment | palette | oklch(0.52 0.01 80) | oklch(0.60 0.005 80) |
| --color-syntax-function | palette | oklch(0.52 0.12 310) | oklch(0.62 0.11 310) |
| --color-syntax-type | palette | oklch(0.50 0.085 196) | oklch(0.60 0.10 195) |
| --color-syntax-punctuation | palette | oklch(0.52 0.01 80) | oklch(0.60 0.005 80) |
| --color-syntax-variable | palette | oklch(0.26 0.01 80) | oklch(0.82 0.005 80) |
| --color-syntax-link | palette | var(--color-accent) | var(--color-accent) |
| --color-error | palette | oklch(0.52 0.12 25) | oklch(0.62 0.11 26) |
| --color-error-subtle | palette | oklch(0.95 0.02 25) | oklch(0.22 0.04 25) |
| --color-success | palette | oklch(0.51 0.12 145) | oklch(0.61 0.11 145) |
| --color-success-subtle | palette | oklch(0.95 0.02 145) | oklch(0.22 0.04 145) |
| --color-warning | palette | oklch(0.52 0.105 85) | oklch(0.62 0.11 85) |
| --color-warning-subtle | palette | oklch(0.95 0.02 85) | oklch(0.22 0.04 85) |
| --color-disabled | palette | var(--color-muted) | var(--color-muted) |
| --color-viz-1 | palette | oklch(0.538 0.121 250.5) | oklch(0.708 0.129 249.5) |
| --color-viz-2 | palette | oklch(0.541 0.111 85.5) | oklch(0.712 0.13 85.3) |
| --color-viz-3 | palette | oklch(0.524 0.12 24.6) | oklch(0.724 0.129 310.2) |
| --color-viz-4 | palette | oklch(0.499 0.12 144.8) | oklch(0.725 0.129 25.4) |
| --color-viz-5 | palette | oklch(0.524 0.121 309.6) | oklch(0.696 0.129 144.9) |
| --color-viz-6 | palette | oklch(0.528 0.09 195.8) | oklch(0.697 0.119 194.8) |