[chaxus]

Summary

This is P1 of the design-guidance improvement plan: every design rule now has a stable ID and a BCP-14 level.

• Graded rules. design/DESIGN.md, INTERACTION.md, ACCEPTANCE.md, WORKFLOW_PATTERNS.md and the ranui adapter are rewritten as ID-tagged bullets, for example - **X-INPUT-6 · MUST** … _Proof: browser_. Totals: 183 MUST, 271 SHOULD, 11 MAY.

  • A rule is MUST only when breaking it causes harm a user or consumer can observe, and the rule can be judged objectively.
  • Rationale prose and tables stay, without normative wording.
  • Headings are unchanged, so existing anchors keep working.

• Proofs. Every MUST names its proof: browser, recording, unit, review, check:<verify:design rule> or test:<path>. All nine verify:design checks now back a rule. Where a test covers only part of a rule, review is added.

• bin/design-rules.ts rejects:

  • normative wording outside a graded rule, including table cells;
  • malformed tags, nested lists and detached continuation lines;
  • duplicate IDs across both indexes;
  • missing, misplaced or unknown proofs.

  It also renders the rule indexes design/RULES.md and packages/ranui/docs/adapters/RULES.md. Adapter anchors are resolved against the combined generated page. --lint <file> checks a single file.

• Wiring. sync:design and verify:docs run the new script. docs/RULES.md ships in the ranui package and the agent plugin.

File	MUST	SHOULD	MAY
DESIGN	41	152	5
INTERACTION	32	17	0
ACCEPTANCE	56	29	1
WORKFLOW_PATTERNS	23	32	0
ranui adapter	31	41	5

Review

Two independent review passes compared every file against its previous text, for lost meaning, mis-grading, inconsistent levels across files and proof fit. All 43 findings were applied. Highlights:

• restored the destructive-command scope on guard rules;
• downgraded pure polish (1px alignment, rem vs em) to SHOULD;
• made the production-shadow-query ban, focus return and hidden-content gaps MUST everywhere.

Known limits

• Imperatives such as "Use…" are not detected mechanically. Headings are exempt from the wording check because renaming them would break existing anchors.
• Guides grew by roughly 20–40% in words, and the full index is about 9,000 words. A short MUST-only entry for agents is planned in P4.

Verification

• pnpm verify:docs (includes the rule index check, the design and plugin sync checks, and check:langs)
• pnpm verify:links
• node --test bin/test/*.test.ts: 59/59, of which 11 are new rule tests
• pnpm typecheck:tooling and oxlint on bin
• pnpm -F ranui exec vitest run test/unit/docs.interface-guidance.test.ts test/unit/docs.references.test.ts: 131/131
• pnpm -F ranui verify:design: no new violations (294 known)
• Prettier on the changed files

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying ran with    Cloudflare Pages

Latest commit:	439dc08
Status:	✅  Deploy successful!
Preview URL:	https://3f4a062b.ran-4ty.pages.dev
Branch Preview URL:	https://docs-design-rule-grading.ran-4ty.pages.dev

View logs