[thomasluizon]

Bundle 3 of #539. Docs only: no application code changed. Two files touched, DESIGN.md and the CLAUDE.md docs-registry row (plus its Brand & design pointer, which the repo requires to move in the same edit).

DESIGN.md is rewritten against two inputs: the owner-approved 2026-07-17 Today-view design freeze (spec .claude/specs/issue-539.spec.md, Decisions section) and the vault canonical note Orbit skill harvest - canonical rule set (#539). The freeze wins over every harvested rule.

Removed (the de-slop)

• The primary glow token (0 8px 28px rgba(var(--primary-rgb),0.45)) and every "pill CTAs with glow" instruction, on the PillButton primary variant, the FAB, and the identity line. Purged as a concept, not softened. The 0.45 glow alpha is gone from the primary-tint list.
• --gradient-header (both modes), the GradientTop primitive, the gradient-header usage list, and the per-scheme gradient-stop derivation rule + hand-tune entry.
• The violet-tinted canvas anchor (neutralHue 265.1322, #020618 slate-950) and the old accent #7f46f7.
• The "navy-cosmic, violet-glow character" target in the scene-sentence test.

Added

• Frozen tokens: canvas #070910, the white-alpha surface ladder resolved (#111319 card / #16181E well / #1F2128 elev-2), fg ramp #F6F7F9/#C7CBD2/#888E99/#565C67, hairlines 0.08 / 0.10 ghost / 0.16, accent #8659EA + --primary-soft #B69BF8 + --primary-dim + --primary-pressed.
• The accent split and WHY it exists: the two AA floors contradict (white-on-accent needs a dark violet, accent-as-text needs a light one), so the roles split rather than the colour compromising. Carries the three measured ratios (4.54 / 4.38 / 8.6) and states explicitly that a blanket "primary as text >= 4.5" assertion would false-fail a fill-only accent. This is exactly what the accent-AA gate asserts.
• The habit-list grouped tonal-panel treatment, the 2-levels-inline + violet-› drill-in, zero connector lines, and both fidelity carve-outs (the per-row ⋮ stays; emoji render in full colour).
• Accent rationing as an explicit closed list. Ring indicators / logo / Astra glyph as the only identity carriers.
• A base-4 spacing scale (there was none), with gap-only mechanics and one honest exemption for BUTTON_SIZES.
• A 45-75ch measure rule (~65ch), plus text-wrap balance/pretty and the <br> ban.
• The loading / empty / error triad, wired to the Satellite glyph primitive that already existed to serve it.
• A motion frequency gate and a closed list of legitimate animation purposes, plus the removal test and the delete-outranks-tuning remediation order. This is a net subtraction of motion, matching the Design restraint pass: less glow, fewer dividers, spacing + de-slop DESIGN.md + improve-ui/emil #539 direction.
• A full ## Accessibility section (perception / keyboard+focus / semantics / forms / announcements). Orbit has no a11y gate today.
• A squint test alongside the AI-slop and scene-sentence tests, and a rewritten scene-sentence target.
• ## Enforcement: which rules are gate-backed (with the concrete mechanism), which are design-reviewer judgment, and which need the live DOM. Bundle 4 implements against this table. No lint rule or hook was written here.

Harvested rules landed

86 total: 62 routed to DESIGN.md, 24 routed to DESIGN.md:a11y. Every row of both tables landed; nothing was dropped for taste.

Note the canonical note's own section headers say "46 rules" and "22 rules" (and the spec's routing tally repeats those figures), but the tables actually carry 62 and 24 rows. The headers are stale; the rows are the real set and are what shipped.

Contradictions with the freeze

None survived into my two buckets. The harvest's upstream drop pass held: the ~40 skills that attacked the de-decorated base, the ~12 that attacked the purple accent, and the ~14 that attacked Inter were all dropped before routing. Two near-misses worth recording, both already resolved upstream and encoded here consistently:

• Overshoot / bounce easing was independently proposed by 4 skills and dropped every time. It lands here as a ban plus a bundle-4 lint (local/no-overshoot-easing), and the spring rule is stated as critically-damped-by-default with no overshoot.
• OKLCH chroma matching conflicts with locked derivation rule 2 and was dropped; only the L-only contrast fix survives, which is now the documented method for reaching AA without drifting a locked hue.

Known follow-ups (not this PR)

• local/no-arbitrary-zindex is blocked: the semantic stacking scale does not exist in the theme tokens, so the gate has nothing to allowlist against. Flagged in ## Enforcement; bundle 4 must land the scale first.
• Every per-scheme byte and every AA measurement other than the purple/dark ones stated in the doc must be recomputed against the new anchors in bundle 5. An explicit recompute note says so rather than letting a pre-freeze byte be assumed still valid.
• orbit-landing-page's mirrored token block still carries the #22094f → transparent gradient header and the glow CTAs. That is a sibling-repo code change and belongs to bundle 5's paired PR.

Refs #539

🤖 Generated with Claude Code

https://claude.ai/code/session_01VPZnJcT1ZHoxUkxw7uhxY2

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
orbit-ui-mobile-web	Ignored		Jul 17, 2026 5:32am

[claude]

Code Review: PR #557

Scope: PR #557 in thomasluizon/orbit-ui-mobile
Recommendation: APPROVE

Summary

Docs-only PR (bundle 3 of #539): rewrites DESIGN.md against the 2026-07-17 owner-approved design freeze, adding ## Enforcement, ## Accessibility, ## Layout & spacing, and motion-governance sections, plus updates the CLAUDE.md docs-registry row and Brand & design pointer to match. No application code changed (confirmed against the diff: only CLAUDE.md and DESIGN.md touched). The rewrite is internally consistent, its load-bearing accessibility contrast math checks out under independent recomputation, and its file/tool references (hooks, ESLint rule, theme files) all resolve to real paths in the repo. One Medium finding: the new "Sections:" list in the At-a-glance header omits three real ## sections.

Findings

Critical

None.

High

None.

Medium

```
[MEDIUM] "At a glance" Sections list omits 3 real H2 sections

• dimension: Correctness
• location: orbit-ui-mobile/DESIGN.md:9
• issue: The newly-added "Sections:" enumeration in the At-a-glance header lists 15 names (Identity, Tokens, Type, Layout & spacing, Primitives, Buttons, Surfaces, Habit list, States, Copy, Motion, Accessibility, Bans, Working model, Enforcement) but the file actually has 18 H2 sections. Missing: "Desktop density & orientation", "Sub-screen navigation", and "Special surfaces" (which carries the Paywall and Landing-hero rules).
• risk: Root CLAUDE.md's docs registry explicitly instructs readers to "grep a doc's At a glance header before loading the whole file" -- a reader grepping this line for "paywall" or "special surfaces" guidance won't find it and may wrongly conclude DESIGN.md has no rule for that surface (it does, at lines 417-421 of the current file).
• fix: Extend the Sections bullet to include the three missing entries, e.g. "... Copy, Desktop density, Sub-screen navigation, Motion, Accessibility, Special surfaces, Bans, Working model, Enforcement."
• reference: root CLAUDE.md docs registry ("Grep a doc's At a glance header before loading the whole file")
  ```

Low / Info

• The Tokens section states "the accent-AA gate asserts it directly" (present tense) in both DESIGN.md and the CLAUDE.md Brand & design pointer, while the new ## Enforcement table correctly lists the accent-AA test as bundle-4 future work. Not blocking -- the Enforcement section's own "Prose is not enforcement" disclaimer resolves the ambiguity -- but a future pass could soften the earlier mentions to "is designed to assert" for tense consistency.

Subagents

Agent	Verdict
parity-checker	N/A -- no apps/web or apps/mobile file changed
i18n-syncer	N/A -- no i18n json or other user-facing strings changed
contract-aligner	N/A -- no shared types / endpoints / orbit-api DTO changed
security-reviewer	N/A -- no orbit-api code changed
design-reviewer	N/A -- gate is apps/* / orbit-landing-page UI files; this diff only touches the spec doc itself

Validation

Check	Result
Lint	N/A -- docs-only PR, no lintable source files changed
Type check	N/A -- no .ts/.tsx changed
Tests	N/A -- no test-relevant code changed
Build (api)	N/A -- orbit-api untouched

Deferred -- N/A dimensions & files not verdicted

• Dimensions 2 (Dead/stale code), 3 (SOLID/clean-arch), 5 (No-workaround), 6 (Type safety), 7 (No console.log): N/A -- diff contains no application source code, only Markdown prose.
• Dimension 4 (Comment policy): N/A -- local/no-comments targets code comments; Markdown prose is out of its scope.
• Dimension 8 (DESIGN.md/AI-slop): N/A per the rubric's own literal gate ("only when the diff touches apps/* UI files") -- this diff is the spec document itself, not a UI implementation.
• Dimensions 9 (Parity), 10 (i18n), 11 (Contract drift), 12 (Security), 13 (Backend hard rules): N/A -- surfaces untouched by this diff.
• Dimension 14 (FEATURES.md parity): N/A -- a design-language/spec rewrite with zero shipped behavior change; the rubric explicitly N/As "visual polish with no behavior change."
• Both changed files (CLAUDE.md, DESIGN.md) were read in full (pre- and post-diff) and given a verdict above. Nothing changed was left unverdicted.
• Spot-verified (not merely trusted): the three WCAG contrast-ratio claims in the new accent-split table (white/#8659EA = 4.54:1, #8659EA/#070910 = 4.38:1, #B69BF8/#070910 = 8.6:1, plus the light-mode 6.71:1 claim) all recompute correctly by the WCAG relative-luminance formula. Also verified every newly-referenced file path (packages/shared/src/theme/button.ts, apps/web/app/globals.css, apps/mobile/lib/theme.ts, gradient-top.tsx, habit-row.tsx, satellite-glyph.tsx, color-schemes.ts) and every hook/lint rule marked "Already shipping" in the new Enforcement table (forbid-em-dashes.mjs, forbid-hardcoded-brand-color.mjs, no-fullbleed-button.cjs) exist in the repo as claimed.

What's good

• The rewrite is unusually rigorous for a docs PR: the PR body self-discloses a stale figure in an upstream vault note (46/22 rules vs. the actual 62/24 rows) rather than silently carrying the error forward.
• The new Enforcement table is exactly the right structure for a spec this large -- it stops the doc from being "prose as aspiration" by explicitly marking what's gate-backed today, what's bundle-4 future work, what's design-reviewer judgment, and what needs a live DOM.
• Every deleted concept (--gradient-header, GradientTop, the primary-glow shadow, the 0.45 glow alpha) is called out explicitly as deleted rather than merely omitted, preventing the doc from silently going stale when a reader diffs old vs. new.
• No em dashes survive anywhere in the ~500 added lines, consistent with the doc's own em-dash ban and the forbid-em-dashes.mjs hook.
• The accent-split rationale (why --primary and --primary-soft must be two tokens) is the single most load-bearing decision in the doc, and its three cited contrast ratios are all mathematically correct -- exactly the kind of claim that's easy to eyeball wrong, and this one is right.

Recommendation

Merge as-is; the one Medium finding is a one-line fix to the At-a-glance header's Sections list and does not block. Fold it in now or in bundle 4/5 when the doc is next touched.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[claude]

Code Review: PR #557

Scope: docs(design): de-slop + enrich DESIGN.md (#539 bundle 3) — docs-only, CLAUDE.md (4 lines) + DESIGN.md (513 lines) against the 2026-07-17 owner-approved design freeze. No application code changed.
Recommendation: APPROVE (no Critical/High findings)

This is a re-review after the follow-up commit bcadbf4e ("address review findings on #557"), which folded in fixes for the prior review's Medium/Low findings. I re-verified those fixes rather than re-flagging what was already reported, and re-derived the load-bearing accessibility contrast-ratio math independently (white-on-#8659EA = 4.54:1, #8659EA-on-canvas = 4.38:1, #B69BF8-on-canvas = 8.6:1) — all correct.

Findings

Critical / High

None.

Medium

1. The "fixed" At-a-glance Sections list still doesn't match the real ## header text (DESIGN.md:9)
bcadbf4e's commit message claims the Sections line now uses "the exact ## names, so the line is actually greppable." It doesn't, for 3 of 18 entries:

• Line lists Identity & anchor — real header is ## Identity & anchor (locked)
• Line lists Habit list — real header is ## Habit list (frozen treatment)
• Line lists Special surfaces (paywall, landing hero) — real header is plain ## Special surfaces
  Root CLAUDE.md tells readers to grep this line before loading the file; a reader grepping the literal header text for (locked), (frozen treatment), or the paywall/landing-hero parenthetical won't find it. Low severity given the doc is still readable end-to-end, but worth a follow-up one-line fix since this is the second pass at the same line.

2. apps/web/app/globals.css:6 still claims design/handoff/ is the token source of truth
This PR removes every reference to design/handoff/ from DESIGN.md and CLAUDE.md, making DESIGN.md itself (+ globals.css/theme.ts) the sole authority — but globals.css:5-6 still reads ORBIT DESIGN SYSTEM — navy+violet (design/handoff canon) / Token source of truth: design/handoff/orbit/project/orbit-fig.css. That's now a direct, unresolved contradiction of this PR's own new authority model, in a file this PR didn't touch.

3. design/handoff/ (~30 vendored Figma-export files) is now fully orphaned
After this PR, nothing in the repo references it as authoritative (previously DESIGN.md itself pointed here for token/dimension canon). It wasn't deleted or marked historical, so it will silently rot as stale "shadow" documentation.

Low / Info

None outstanding — the prior review's Low finding (present-tense claims about the not-yet-built accent-AA gate) was fixed correctly in bcadbf4e.

Subagents

All N/A — diff is limited to CLAUDE.md + DESIGN.md; no parity/i18n/contract/security/design-reviewer gate fires on a spec-doc-only change.

Validation

N/A per this workflow's CI adaptation — Build / Unit Tests / SonarCloud run as separate required checks on this PR.

Recommendation

Merge as-is. The three Medium findings are docs-consistency gaps (a greppability regression that survived its own fix pass, plus a newly-orphaned directory and a newly-contradicted comment elsewhere in the repo) — none touch application behavior, security, or contracts. Worth folding into the next bundle (4/5) when DESIGN.md or globals.css is next touched.