Operational Restraint: docs site theme + M64 changelog

[indykish]

Summary

Two commits, both on this branch per direction:

1. chore(design) — apply Operational Restraint to docs.usezombie.com (M64_007 / W4 of the design-system rollout). Heritage orange chrome → cyan-mint pulse, self-hosted Commit Mono + Instrument Sans (Latin subset, all under 80KB), brand-mark wake-pulse animated inside the logo SVGs, calm Vesper-style code-block syntax, prefers-reduced-motion honoured.
2. docs(changelog) — consolidated <Update> for the Operational Restraint rollout (M64_006). 298 words, voice-matched to recent entries, tags ["What's new", "UI"] (both pre-existing in changelog.mdx).

What changed

• docs.json — colors.primary/light/dark now point at the design-system pulse tokens; fonts.heading = Commit Mono 500, fonts.body = Instrument Sans 400 (self-hosted woff2); styling.codeblocks: "dark".
• fonts/{CommitMono,InstrumentSans}-{Regular,Medium}.woff2 — 4 self-hosted faces, sourced from @fontsource Latin subset, ≤80KB each.
• tokens.css + custom.css (Mintlify auto-loads custom.css) — token transcription, font-faces, body/heading family overrides, ~68ch measure, calm Vesper-style code-block syntax theme, focus ring on --uz-pulse, reduced-motion guard.
• logo/{dark,light}.svg — pulse disc animates 2.4s ease-in-out infinite via embedded <style>; reduced-motion fallback to a static halo. Survives Mintlify's logo render path without needing a custom React component.
• changelog.mdx — new <Update> block at the top.

Verification

Local Mintlify CLI not installed; relying on the Mintlify deploy preview bot for build + render verification. Once the preview URL is live, manual checks:

• Network tab: zero requests to fonts.googleapis.com / fonts.gstatic.com
• Brand-mark pulse animates in dark + light mode
• Reduced-motion DevTools toggle: pulse becomes static halo
• Body renders in Instrument Sans, headings in Commit Mono
• Code-block syntax: no purple keywords; numbers in evidence amber
• Light mode WCAG AA on every top-level page (axe-core)
• Lighthouse Performance ≥ 90, Accessibility ≥ 95 on the preview

Spec deviations (called out)

• M64_006 spec named branch chore/m64-changelog; bundled onto this branch per direction.
• Spec asked for tags ["What's new", "Design", "App", "Website", "Docs"], but the canonical release template only enumerates UI from that family and the existing changelog.mdx has never used the others. Used ["What's new", "UI"] to satisfy the spec's own "tag re-use" invariant.
• images/changelog/m64-pulse-cap.png screenshot omitted — its capture depends on M64_005 (e2e harness with seeded 6-zombie fixture), which isn't done. Surfaced as a "What's next" pointer in the entry rather than fabricated.

Test plan

• Mintlify deploy preview renders without markdown / build errors
• Navigate every top-level guide + API reference page; visual sanity check on dark + light
• Open the changelog page; new entry appears at top, tag chips render, image-less layout looks intentional
• DevTools Network tab confirms no third-party font requests
• DevTools prefers-reduced-motion: reduce simulation: brand-mark falls back to static halo

🤖 Generated with Claude Code

Greptile Summary

This PR applies the Operational Restraint design system to the docs site (M64_007) and adds the corresponding changelog entry (M64_006). It replaces the heritage orange --z-orange palette with the cyan-mint --uz-pulse token set, introduces self-hosted Commit Mono + Instrument Sans Variable fonts via custom.css, embeds a wake-pulse SVG animation in both logo variants, and updates AGENTS.md to reflect the new token namespace.

• Token system (tokens.css + docs.json): Dark-first surfaces, borders, text, status, and radius tokens transcribed from the upstream design system; colors.primary/light/dark in docs.json now point at the pulse tokens; styling.codeblocks: \"dark\" selects Mintlify's built-in Shiki dark theme.
• Typography (custom.css): Three self-hosted font files (CommitMono-Regular, CommitMono-Medium, InstrumentSans-Variable) declared via @font-face; headings land on Commit Mono, body on Instrument Sans Variable; Mintlify's fonts config is intentionally omitted to avoid double-fetching.
• Logo animations (logo/dark.svg, logo/light.svg): Symmetrical pulse keyframes (0% and 100% share the same scale/opacity values for a seamless loop) with transform-origin: center; transform-box: fill-box; prefers-reduced-motion falls back to a static halo.

Confidence Score: 5/5

This is a docs-only visual redesign with no logic, API, or data changes — safe to merge.

The changes are scoped to CSS tokens, font files, SVG logos, Mintlify config, and a changelog entry. All issues from the previous review round are resolved. Remaining findings are comment-accuracy nits that do not affect rendered output or runtime behaviour.

No files require special attention — the two minor observations in tokens.css and custom.css are documentation/comment consistency issues that will not affect the deployed site.

Important Files Changed

Filename	Overview
tokens.css	New design-token file transcribing the upstream token set; complete for surfaces/borders/text/status/radii/type-scale. Missing --ff-mono/--ff-sans font-family tokens referenced in AGENTS.md.
custom.css	New Mintlify override sheet; handles font-faces (variable Instrument Sans, two Commit Mono weights), typography, inline code, code-block chrome, focus ring, cover-grid, and reduced-motion. Header comment overstates the --uz-pulse constraint relative to AGENTS.md.
docs.json	Color tokens updated from heritage orange to cyan-mint pulse; styling.codeblocks: "dark" added. No fonts key present — consistent with the custom.css comment that Mintlify's font injection is intentionally bypassed.
logo/dark.svg	Pulse-ring circle added with transform-origin: center; transform-box: fill-box; keyframes are symmetrical (0% and 100% both at scale(1) opacity:0.55) so the loop is seamless; reduced-motion fallback to static halo is present.
logo/light.svg	Identical animation approach to dark.svg with light-mode pulse colour (#14B8A6); all animation concerns from the previous review round appear resolved.
changelog.mdx	New <Update> entry added at the top for the Operational Restraint design system rollout with tags ["What's new", "UI"].
AGENTS.md	Design-system color and token guidance updated from heritage --z-orange palette to new --uz-pulse / --uz-bg / --uz-surface token family; grep command updated to match new token prefix.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[tokens.css] -->|"@import"| B[custom.css]
    A -->|pulse/bg/surface values| C[docs.json]
    B -->|font-family headings| D["CommitMono-Regular/Medium.woff2"]
    B -->|font-family body| E["InstrumentSans-Variable.woff2"]
    B -->|focus-visible outline| F["--uz-pulse / --uz-pulse-glow"]
    C -->|"codeblocks: dark"| G[Mintlify Shiki dark theme]
    H["logo/dark.svg"] -->|embedded style| I[uz-wake-pulse keyframes]
    J["logo/light.svg"] -->|embedded style| I
    I -->|"prefers-reduced-motion"| K[static halo fallback]
    B -->|global reduced-motion| L["animation-duration: 0.01ms !important"]

Loading

Comments Outside Diff (1)

1. fonts/InstrumentSans-Medium.woff2, line 1 (link)

   Duplicate woff2 — Medium weight is identical to Regular

   InstrumentSans-Regular.woff2 and InstrumentSans-Medium.woff2 share the same git blob SHA (78557c7) and the same MD5 (d4be1b605ba7e3dbf6525cacf758be0d). Both @font-face declarations in custom.css (weight 400 and weight 500) will resolve to the same physical font, so nothing in the UI that requests font-weight: 500 will actually render heavier. The Medium woff2 needs to be replaced with the real Medium subset.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: fonts/InstrumentSans-Medium.woff2
   Line: 1
   
   Comment:
   **Duplicate woff2 — Medium weight is identical to Regular**
   
   `InstrumentSans-Regular.woff2` and `InstrumentSans-Medium.woff2` share the same git blob SHA (`78557c7`) and the same MD5 (`d4be1b605ba7e3dbf6525cacf758be0d`). Both `@font-face` declarations in `custom.css` (weight 400 and weight 500) will resolve to the same physical font, so nothing in the UI that requests `font-weight: 500` will actually render heavier. The Medium woff2 needs to be replaced with the real Medium subset.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
custom.css:14-15
**`--uz-pulse` used for the focus ring contradicts the file's own "exactly once" constraint**

The header comment asserts `--pulse` appears "EXACTLY ONCE on the docs site: the brand-mark logo in the top nav. Any other use is a violation." The `:focus-visible` rule on line 128 then uses `--uz-pulse` and `--uz-pulse-glow`, which violates the stated constraint. `AGENTS.md` is the authoritative source and explicitly permits focus rings, so the file-level comment is the stale artefact — but an auditor or future contributor reading the comment and then this file will see an apparent policy breach. Update the header comment to match `AGENTS.md`: the pulse appears on live signals, focus rings, and the brand-mark.

### Issue 2 of 2
tokens.css:52-60
**`--ff-mono` and `--ff-sans` font-family tokens missing from `tokens.css`**

`AGENTS.md` names `--ff-mono` (Commit Mono) and `--ff-sans` (Instrument Sans Variable) as canonical token identifiers for the typography system. Neither is defined in `tokens.css`; `custom.css` instead hardcodes the full font stacks inline. A future contributor following `AGENTS.md` will look for `--ff-mono` as a CSS custom property, not find it, and either duplicate the stack or break the token invariant. Adding the two properties to the type-scale block keeps the tokens file the single source of truth for all design values.

_{Reviews (3): Last reviewed commit: "fix(design): cover-grid dot pattern live..." | Re-trigger Greptile}

Context used:

• Context used - AGENTS.md (source)

[indykish]

Addressed in 8516736.

P1 (all fixed):

• docs: UseZombie v0.3.0 documentation site (M13_002) #1 (Issue 2 + 3) transform-origin — switched to center in both logo/dark.svg and logo/light.svg. With transform-box: fill-box, center resolves to the circle's actual midpoint so the ring scales concentrically.
• fix: replace Mintlify branding and add real API reference #2 (Issue 4 + 5) loop-boundary opacity flash — keyframe 100% now matches 0% (opacity: 0.55, scale(1)); the loop is seamless.
• fix: docs polish — external link check, OpenAPI card, navbar #3 (Issue 6) .cover-grid::before escapes container — added position: relative to .cover-grid so the pseudo-element anchors correctly.
• fix: update logo SVGs and add favicon.ico #4 (Issue 1) duplicate Instrument Sans woff2 — good catch. The "Medium" file was a byte-for-byte copy of Regular, so font-weight: 500 rendered identically. Replaced both static files with InstrumentSans-Variable.woff2 (the @fontsource wght-axis variant, 30KB) and a single @font-face { font-weight: 400 700 } declaration in custom.css. One download covers every weight, and the bug can't recur because there's no second file to drift.

P2 (fixed):

• docs: changelog + M27 scoring & replay updates #5 (Issue 7) stale AGENTS.md color guidance — rewrote the "Design system colors" section. Heritage --z-orange palette is gone; section now documents --pulse / --bg / --surface-1 / semantic status tokens and names Commit Mono + Instrument Sans Variable. The sync-source comment now greps for the new token names.
• docs(index): pivot statement and April 11 pre-release notice #6 (Issue 8) fonts double-registered — fair point. Dropped the fonts block from docs.json; custom.css's @font-face declarations are now the single source of truth. Eliminates the double-fetch risk and keeps the font story in one file.

P2 (intentional, not changed):

• docs: reflect v2 pivot — agent hosting, credential firewall #7 (Issue 9) "May 9, 2026" label — intentional, not a slip. Today is May 9, 2026 in the authoring timezone (IST); committer timestamps land May 8 in UTC, which is what greptile's clock saw. Aligning to the deploy day rather than the UTC commit day.

Thanks for the review — all eight code issues had real teeth, especially the duplicate-Medium-woff2 catch.

[indykish]

Two follow-up pushes:

3acf05c — addresses the new P1 (custom.css:156 cover-grid dot opacity).

Good catch. The dot pattern was on .cover-grid at opacity: 1 and the ::before was overlaying via background: inherit; opacity: 0.08, which made the dots fully visible (the comment about an 8% tint was wrong because the parent rendered the same pattern at full opacity beneath it). Moved the radial-gradient exclusively to ::before so the dots render once at the intended 0.08 opacity. Parent only owns the positioning context now.

0e9a6aa — self-review pass (separate from the greptile thread).

Three issues I found while auditing the PR myself before requesting review:

• html font-size override redefining the rem unit. :where(html, body) { font-size: 0.9375rem } made html's font-size 15px, which silently rescaled every Mintlify rule expressed in rem (~6% smaller). Moved the rule to :where(body) so inheritance still flows to children but the rem base stays at the browser default.
• .token.* Prism overrides were dead CSS. Mintlify renders syntax via Shiki, which emits inline style="--shiki-…" attributes — Prism's .token.keyword class never appears in the output. Deleted the block. Code-block syntax now comes from Mintlify's built-in dark theme via styling.codeblocks: "dark" in docs.json; the chrome rules (font, surface, border, radius) remain.
• Heading letter-spacing was flat across h1–h6. DESIGN_SYSTEM.md §Type scale specifies a tightening curve (display-xl -0.025em → heading flat). Split into per-level rules.

Also trimmed the changelog "What's next" line — the prior wording made an aspirational claim about M64_005 work that hasn't started, which violates the AGENTS.md "Changelog claim challenge" rule.