one-kit-on-every-surface — Code, charts, controls, embeds and shell blocks are one kit on every surface, declared in the design book and held there by a gate

○PLANNED 0 of 8 issues done

ready

2

blocked

6

active

0

verify

0

done

0

cancelled

0

Problem

A survey of master 91c0b5d5658 on 2026-10-20 found each kind of rendered element made several ways. Code is highlighted only on the site (ayu themes, not design tokens); /ui and the Cockpit render plain pre. Charts are drawn by four mechanisms, and only the site's are held to a table. Copy buttons and tabs exist in two implementations each on the site and in none on /ui and the Cockpit. Shell blocks are three styles on the site and bare code on /ui. docs/DESIGN_SYSTEM.md says nothing about syntax highlighting, and no gate refuses a second way of drawing any of them.

Outcome

A reader meets one code block, one chart, one copy control, one tab control and one shell block, whichever surface they are on: the site, /ui, the Cockpit or the docs. Each is declared once in the design book with its tokens, and a gate fails the change that renders one another way, so the kit stays one as the surfaces grow.

Current state

Code: I2747 (PR #1294) gives one engine, giallo, and one token-derived palette with a highlighter-check gate, revived after the owner's decision of 2026-10-20. Charts: site/charts.js draws from the page's table; the kit chart and the /ui donut have no table; I2654 holds the site's charts to their tables. Controls: Alpine and kit.js copy and tabs on the site, none on /ui and the Cockpit, and interaction-probe drives the site only. Embeds: none found; Mermaid on the site only. Shells: terminal-run.html, the kit's term_* and plain fences on the site; code.mj-ui-mono reproduce lines on /ui.

Desired state

docs/DESIGN_SYSTEM.md carries one section per element kind, naming its mechanism, its tokens and the gate that holds it. Code goes through I2747 everywhere. Every chart is drawn from a table on its page. One copy control and one tab control, kit.js's dependency-free ones, ship to every surface, and interaction-probe drives them on /ui and the Cockpit as on the site. A surface links to another and never embeds it. One shell primitive (prompt not copied, status in words, long output folded) renders every command and its output.

Scope

• docs/DESIGN_SYSTEM.md
• share/design
• share/ui
• share/cockpit
• site/templates
• site/kit.js
• site/charts.js
• apps/majordomus-cli/src/ui
• apps/majordomus-cli/src/cockpit
• scripts/lib/ui-audit.mjs
• scripts/interaction-probe
• scripts/lib/interaction-specs
• scripts/ci/design-check
• test/cases

Out of scope

• Rustdoc's own highlighting and themes, which rustdoc owns; it stays excluded from the audit as it is today
• New chart types or new controls: this milestone makes the existing ones one kit

Acceptance criteria

• The design book has a section for code, charts, controls, embeds and shell blocks, each naming its mechanism, tokens and gate
• For each element kind a planted second implementation on any surface fails a gate that names it
• The site, /ui and the Cockpit pass every one of those gates on master, and the published site is deployed from that master

Validation

• bin/majordomus plan validate
• scripts/ci/design-check
• node scripts/ui audit

Evidence required

• one_kit_gates_case

Risks

• giallo builds Oniguruma from C on every release target (I2747): the release matrix must prove it before #1294 lands

Issues

Each one is an execution contract with its own acceptance criteria, validation command and required evidence. The wave column is the layer of the dependency graph it sits in.

The graph

flowchart LR
    I3790["I3790<br/>The design book declares one mechanism, its tokens and its gate for code, charts, controls, embeds and shell blocks"]:::blocked
    I3791["I3791<br/>A code block on /ui and the Cockpit carries the one highlighter's classes, and the audit refuses one that does not"]:::blocked
    I3792["I3792<br/>Every chart on every surface is drawn from a table on its page"]:::blocked
    I3793["I3793<br/>One copy control and one tab control ship to every surface"]:::ready
    I3794["I3794<br/>The interaction probe drives the controls of /ui and the Cockpit as it drives the site's"]:::blocked
    I3795["I3795<br/>A surface links to another surface and never embeds it"]:::ready
    I3796["I3796<br/>Every command and its output is one shell block, on every surface"]:::blocked
    I3797["I3797<br/>A command shown outside the shell block is refused by the audit"]:::blocked
    I3793 --> I3794
    I3793 --> I3796
    I3796 --> I3797
    classDef done stroke:#16a34a,fill:#dcfce7,color:#14532d,stroke-width:2px
    classDef active stroke:#2563eb,fill:#eff6ff,color:#1e3a8a,stroke-width:2px
    classDef verify stroke:#7c3aed,fill:#f5f3ff,color:#4c1d95,stroke-width:2px
    classDef ready stroke:#0891b2,fill:#ecfeff,color:#164e63,stroke-width:2px
    classDef planned stroke:#0891b2,fill:#ecfeff,color:#164e63,stroke-width:2px
    classDef blocked stroke:#b45309,fill:#fffbeb,color:#78350f,stroke-width:2px
    classDef cancelled stroke:#6b7280,fill:#f9fafb,color:#374151,stroke-width:2px
    classDef superseded stroke:#6b7280,fill:#f9fafb,color:#374151,stroke-width:2px

Canonical record: .ai/repo/project/milestones/one-kit-on-every-surface.yaml. Read it back with majordomus plan show one-kit-on-every-surface.