[chaxus]

What

A review of the whole design standard, prompted by studying pbakaus/impeccable and Motionsites-AI/claude-skill. Direction: keep rules that prevent a defect a user can observe; turn taste and process into starting points an agent may depart from with a reason; fix values that had drifted between copies.

Please review manually; not for auto-merge. Two commits: the first adds lessons from impeccable, the second trims them back after evaluation and fixes drift.

Guide (design/DESIGN.md + Chinese translation, npm guide and plugin copies synced)

• MUST is only for an observable defect; SHOULD is a starting point, depart from it whenever the work is better for it, and say why.
• Modes: tools and documents spend expression on precision; a persuading page may commit to one signature idea.
• Type: leading ≥ 1.5, text a reader needs ≥ 12px, more space above a heading than below (checked on the docs site); text-wrap: balance / pretty; theme browser surfaces (selection, caret, scrollbars, tabular numerals).
• Decoration is one line: it has to do a job. (The impeccable-style refusal list was removed: a taste list limits agents more than it prevents defects.)
• Motion: never animate layout properties (was: only transform and opacity); controls don't bounce, a persuading page may spend one expressive moment.
• Modal rule added under Interaction (the adapter linked to "navigation-layer rules" that did not exist).
• Process: the written brief is for pages being built or restructured, not every edit; rank findings P0–P3; write fixes as values.

Adapter (packages/ranui/docs/adapters/DESIGN.md, rewritten)

• Corrected values: radius xs 4 · sm 8 · md 12 · lg 16 · xl 24; link blue-800 (dark #5b9dff); primary hover/active #2a2a2e/#3f3f46 (dark #d4d4d8/#b4b4bb); dark bg-elevated #18181b; added --ran-color-focus.
• Removed rules owned by CODING.md (hidden, hold what you build, pointer events, closed-root tests), orphan lines, the r-conversation section and the stale "nine rules" count.
• Kept every rule with a real bug behind it (palette transitions on theme switch, non-flipping fallbacks, undefined var(), z-index on the host, overlay shadow tier, overlay re-measure, wrapper raised only while painting).
• Process MUSTs → SHOULD. ease-spring / ease-bouncy are a host's expressive choice, never a component default.

Checks

• verify:design is unchanged from main (9 rules). The gradient-text and overshoot-easing rules added in the first commit were removed: both were taste.
• design-checklist.spec.ts: measure, leading, minimum text size and heading spacing on 11 key pages at 320px and 1280px.
• docs.design-tokens.test.ts: now also compares documented values with tokens.less / dark.less in all eight design-system pages (it only checked names, which is how gray-alpha and the focus ring drifted).

Docs site

• Public design-system and design-guides pages, all eight languages: gray-alpha, dark overrides, focus ring, spacing (24–32px between regions) and motion ranges corrected; intro points at the real sources.
• Themed ::selection and caret; inline code floors at 12px; playground copy button 12px.
• CODING.md / CLAUDE.md: dead "DESIGN.md §n" references replaced with anchors; #d9d9d9 advice corrected.

Third commit

• Reasoned exceptions: a line that breaks a static rule on purpose carries design-ok: <rule> <reason>; no reason, no exception (unit-tested).
• spacing-scale: the library names its steps as tokens (consumers retune them); elsewhere a step written as 8px is fine. Docs spacing debt drops from 51 to 35.
• From Don't Make Me Think: count how hard each choice is, not the clicks; self-evident before self-explanatory; clickable looks clickable at rest; accept input as people type it and ask only what the task needs; watch three people try the task.
• Removed: the home page kickers (they repeated their headings); overshooting easing in checkbox and r-glass; restated rules on the design-guides page in all eight languages (now an explainer that links to the guide and adapter).
• docs.interface-guidance.test.ts follows the adapter's new spacing section (it failed CI on the second commit).

Later commits

• Review fixes: restored .search__input:focus-visible (a replacement had broken it); design-ok covers only its own line and needs a worded reason; the value-drift test also checks dark values, every pair in a row, shadows and inline figures (each kind mutation-tested); shift diagnostics name SVG nodes correctly; Windows CRLF fix in a test.
• From baoyu-design (ideas only, rewritten; its methodology derives from a product system prompt): compare two or three directions in one place before committing; no invented filler content; mixed-script typography; the design skill asks for a reference and asks before adding material. CJK running text on the docs site now has 1.75 leading (was 1.65).
• The intermittent pages do not shift failure (/ranui/select/, 0.092; 2 of the last 6 runs, also on main) now reports what moved when it fails.

Verification

• pnpm verify:design (ranui, docs): 9 rules, no new violations; baselines equal main.
• pnpm verify:docs (design sync, plugin, generated docs, check:langs) and pnpm verify:links: pass.
• docs.design-tokens.test.ts: 11 passed (fails on main's pages: it caught 11 drifted values per locale).
• New typography test: 22 passed on Chromium against a docs build from the first commit; the second commit changed no CSS.
• ranui unit tests: 1763 passed (first commit).
• Third commit: ranui unit 1774 passed, SSR 77, tsc clean; docs unit 252; full docs build with anchor checks over 1316 pages; 140 docs browser tests on Chromium; home page viewed after removing the kickers.
• Not independently reviewed by a second agent.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying ran with    Cloudflare Pages

Latest commit:	490713a
Status:	✅  Deploy successful!
Preview URL:	https://5e4737a7.ran-4ty.pages.dev
Branch Preview URL:	https://feat-design-lessons.ran-4ty.pages.dev

View logs