Make design guidance discoverable and enforce shared decisions

[morgmart]

What this does

Give Buzz design work one discoverable set of mandatory rules, with automated feedback when a change bypasses the shared system. Consolidate stewardship into the rules and design rationale, remove the separate maintaining document, and keep setup instructions separate.

This changes authoring guidance, checks and the documentation viewer—not product styling or the ongoing composer port.

Why it matters

An agent working on a product surface should not need to guess which design document applies. Root and viewer instructions now point to the same canonical policy, including the requirement that different light/dark palette steps belong in a semantic token rather than a local override.

Approved repeated patterns can also earn semantic names when both modes use the same palette step. Checks must preserve that decision, not mistake it for a violation or encourage an agent to undo it.

How it works

• Mandatory policy lives in the design-system AGENTS.md; DESIGN.md explains the reasoning. The viewer imports those documents directly and old maintaining bookmarks still show the consolidated rationale.
• Earned-name reasons sit beside default token declarations rather than in a script allowlist. Missing reasons prompt the author to preserve an approved name or ask for the decision. The check validates the record, not human approval or design quality.
• An app-wide static authoring audit checks local color overrides, selected color/type rules and direct restyling of imported system components. Exact legacy findings from the original base are retained individually; new occurrences fail. There is no automatic baseline-refresh command.
• Existing registries remain the inventory owners. Tests now check reverse coverage for semantic colors, palette entries and shared component files, alongside existing viewer specimen coverage. No parallel manifest or handwritten inventory is introduced.

The audit does not prove computed-style correctness or cover every dynamic class builder, indirect CSS override, re-exported component or named CSS color. Visual judgment remains necessary.

Verification

• Root formatting, types and design guards passed.
• 1,260 Vitest tests passed, including the new guard regression tests; 58 focused design tests also passed after final inventory edits.
• Host and standalone viewer builds passed.
• 12 standalone viewer journeys passed in Chromium and WebKit, covering document links, old bookmarks, tables, narrow/intermediate/wide layouts and theme behavior.
• Independent review found no remaining blocker and verified the 288-entry legacy baseline against the original base.
• Machine-level security hooks and repository staged-file/type/test hooks both passed through a worktree-local chain; existing global hooks were preserved.

Deferred: The full design-browser command encountered another session using its host-preview port. Standalone viewer cases ran on an isolated port, but the host/viewer integration case remains deferred. Full scan, native/cross-platform acceptance and hosted CI remain integration gates. This PR is draft for reviewing the diff, not a merge-ready claim.