Design Authority · worked example: Jennu (packs/phantom 0.2.0)

What a design authority is,
and how it changes

A design authority is a written description of an interface system that software can read. It lists the components (buttons, fields, menus), the rules (colour, type, spacing) and the fallbacks for anything not decided yet. One program builds with it; another checks whether the build matches it.

01What it contains

packs/phantom/ — the authority pack (v0.2.0, named Jennu)
├─ authority.json identity · snapshot · version
├─ artifacts.json 29 records — 6 token-sets · 1 guideline · 17 components · 5 layouts
├─ rules.json 8 — P-R1 reading-ink-pink … P-R8 state-colour-pink
├─ prohibitions.json 2 — e.g. “don’t rely on accent ink below 3:1”
├─ fallbacks.json 4 — light-only · no-script · cjk-system-fallback …
├─ precedents.json 1 — adjudications that persist across versions
├─ candidates.json 3 — ambitions with an explicit promotion bar
├─ golden.json 21 cases — ask → expected outcome (guards resolution)
├─ recipes.json 0 — compositions, once they exist
└─ verification.json 15 checks — the conformance contract

Plain JSON, no database. The pack records what the system is. Notes from a given build stay in that build’s own workspace; only recorded decisions change the pack.

One artifact record (abridged)

{ "id": "component/action-button", "kind": "component", "title": "Button — ink ring, pink hover", "aliases": ["button", "cta", "submit …"], "body": { "states": [ "default: 2px ink ring, ink label", "hover: label + ring #f2849e", "primary: ink ground, white label" ], "spec": ["44.8px tall", "0.8em/900 caps …"] }, "source": { "path": "deployed main.css · measured on elements.html" }, "compiled_from": ["redo/c"] // evidence trail }

How a consumer reads it

“a primary button”resolved →component/action-button
“a carousel with controls”undefined →candidate surfaces a bar: sources, motion policy, controls
“CJK in the wordmark”fallback →constraint recorded (no CJK stack declared)

The two-consumer loop

The packone file set, readable by software
→
Coding agentreads the pack and builds
→
Implementationthe working page
→
Verifierchecks the page itself, not the agent’s claims
→
Conformance report15 checks, 0 violations; published with hashes

02How it changes

A real revision — the redo

  • v0.1.0 initial freeze — hashed, git-tagged

    The first version described the template underneath the site: grey text, 4px corners. It flagged the site’s pink type as a problem. It passed its own checks (17 of 17) but had described the wrong thing.

  • rejected owner review of the rendered result

    Review rejected it. The site runs pink type, and an authority has to describe what is actually there.

  • v0.2.0 fresh freeze — all pack files re-hashed

    Rebuilt from the rendered site: four extraction teams, 64 screenshots. Pink type became canon. The old decision was recorded as a precedent rather than deleted, so the question stays closed. The checks were rewritten and passed: goldens 21/21, verification 15/15.

The standing rules

Small edits bump the patchWording fixes and clarifications change the patch number. Nothing is re-frozen.
Real changes bump the versionNew or changed records reset the hash record for every file in the pack.
Decisions are keptAccepted and rejected decisions are stored as precedents and are not reopened.
Ideas wait their turnNew directions become candidates with a written bar for promotion. Nothing becomes canon quietly.
Gaps are written downWhen a build cannot follow the authority, the gap is recorded instead of smoothed over.
Checks travel with the packGolden cases and the verification contract are versioned with the records and re-run against every build.

The evolution loop

Extract from evidence, freeze, build, check, decide, release. The pack only moves when a decision is recorded.