Appearance

Design system — start here ​

Thirty-eight pages and no entry point until 2026-09-23. This index is where a screen task begins: which of the two Claude Design projects holds what you need, the asymmetric governance rule, the process for a screen that has no design yet, and the ledgers the gates read.

Read before changing or building a screen

  1. This page · 2. Screen coverage mandate (the process, incl. "a screen that does not exist yet") · 3. the screen's parity contract under design-system/parity-contracts/ · 4. Screen conformance · 5. Design drift ledger (ADR-0015) · 6. Brand and typography. Gates: check:screens · check:design-parity · check:design · check:design-prompt · check:desktop-parity; for packages/tokens/** or apps/*/src/ui/** the native builds are the gate. Pull the design fresh (DesignSync) and extract it with npm run design:spec; never implement from memory or a committed copy. Your plan must answer: which design project and which artboard round; which scenarios, statuses and interactions the artboard enumerates (every one gets a pass · gap · blocked row); and how the screen behaves with the keyboard open and above the Android system navigation (no artboard has either).

Pages ​

Design governance and the two design projects (operating-manual text) ​

Provenance — moved from CLAUDE.md on 2026-09-23 (QRS-1288)

This is the verbatim text of CLAUDE.md § "Design System & UI/UX [ENFORCED — non-negotiable]" as of commit 00c1eca, relocated here under the context-architecture programme. Sentences of the form "this said X until [date]" are corrections recorded at the time they were made; the live rule is the corrected one. Retired vocabulary inside those corrections names what was retired and is not a live claim.

Design System & UI/UX [ENFORCED — non-negotiable] ​

Design governance is ASYMMETRIC [ENFORCED — ADR-0015]. Split on a line a script can decide, not on "how small":

  • Systemic surface — packages/tokens/** + apps/*/src/ui/** → design-first, no exceptions. Pull the design, fix it there if it's wrong, then implement. These are few, change rarely, and a divergence forks both UI idioms (ADR-0011 implements components twice over one token package, so the DOM side gets no signal the RN side moved).
  • Screen composition → code-first, freely. Build it, ship it, record it. Ad-hoc UI/UX refinement during development is sanctioned, not a violation.
  • Record at the moment of divergence — one row in documentation/portal/design-system/design-drift-ledger.md in the same PR (divergence · correction · ahead · none). Reconciled at the develop → uat promotion, never by a later "periodic audit" (this repo's measured completion rate for deferred reconciliation is ~0 — see QRS-180). Gated by npm run check:design (tools/check-design-drift.js), which fails closed.
  • Pulling the design first is still recommended for screen work when a design may already exist — re-inventing one is wasted effort even when procedurally allowed (the tab bar already specified what we were asked to "improve").

⚠ THERE ARE TWO CLAUDE DESIGN PROJECTS AND THIS SECTION NAMED ONLY ONE UNTIL 2026-08-09 (QRS-451). Screens are designed in the prototype project; the design-system project is the token/component library it consumes. Check which one you need before concluding anything from what you find:

ProjecttypeHoldsPull from it for
37245d93-4fa1-42d0-b765-53a7664d5129 — "QR setu Design System"DESIGN_SYSTEM43 components (each with .jsx + .prompt.md + .card.html), 11 token files, guidelines/, and six templates/* that predate the current screen settokens · component contracts · component-level design
633dc069-6df8-4408-b625-068907c60c33 — "QR setu prototype"PROJECTThe actual screens. ⚠ Re-measured from SCREENS.md on 2026-08-15 (round 28); this cell said "19 mobile-console, 13 admin-panel, 4 customer-flow, 4 onboarding" and understated the project by five whole sections. Actual: mobile-console 30 · consumer 13 · desktop-console 16 (incl. Auth + Onboarding, round 22) · admin-panel 10 · setu-card 4 · onboarding 4 · marketplace-desktop 2 · landing 2 · vendor-journeys 3, plus SUPERSEDED ui_kits/merchant-console-v2 (15) and customer-flows (4), and an unregistered prototype/review/ + ds-revision/. Vendors the library in as _ds/qr-setu-design-system-37245d93…/any screen design

⚠ RE-MEASURED 2026-08-20 (round 30) BY list_files, NOT BY THE PROSE TABLE, AND THE ROW ABOVE IS STILL WRONG IN ONE PLACE: marketplace-desktop IS 3, NOT 2 — Discover.dc.html (round 29) joined Browse and Item. Counts by directory: mobile-console 30 · desktop-console 16 · consumer 13 · admin-panel 15 · setu-card 8 · onboarding 5 · marketplace 3 · landing 2 · vendor-journeys 3.

⚠⚠ AND THE DESKTOP CONSOLE CARRIES AN UNRESOLVED CONFLICT WITH ADR-0011 THAT IS NOT A DETAIL. SCREENS.md specifies it as "a SEPARATE route group in apps/web, DOM/React over shadcn/Radix primitives … not React Native Web and not a scaled phone screen" — i.e. a second implementation of the merchant product, 16 screens, in the idiom apps/web does not have (measured 2026-08-20 and all three halves have since gone stale: apps/web/src/ui holds 4 components, package.json carries class-variance-authority, and apps/web now has auth (tiers/merchant/features/auth/, calling signInWithOAuth / signInWithOtp / signInWithPassword)). ADR-0011 says the merchant product is ONE universal Expo codebase reaching desktop through RNW. Do not start building the DOM console as though the conflict were settled; ADR-0028's /app mount gives desktop the existing product today. Full measurement: portal design-system/desktop-journey-readiness.md. Consumer desktop does not exist in the design at all — all 13 prototype/consumer/ screens are mobile-only, so a desktop buyer can discover, browse and order but has no order-code, account, orders, chats or notifications surface. That is a design REQUEST, not a pull.

The failure this caused, so it is not repeated: an absence proves nothing until the search space is established. On 2026-08-09 a DesignSync audit of the design-system project found no Catalogue.dc.html, counted zero matching fields, and reported "the prompt was never applied, provable by absence". Every observation was true of the project examined and false of the product — the design existed, in the prototype project, and was sound. A present artifact is self-verifying; a missing one is evidence only once you have confirmed you are looking where it would be. The audit was thorough and cheap, which is exactly what made the wrong conclusion feel earned.

The design project remains the baseline source of truth for initial screen design. The approved designs live in the Claude Design projects above (accessed via the first-party DesignSync tool / /design-sync skill). The design-system project — its components/** (.jsx + .prompt.md spec + .card.html preview per component), tokens/, guidelines/, and templates/ (incl. mobile-console/MobileConsole.dc.html) — is authoritative and replicated as closely as possible. Every UI implementation begins by pulling the latest design for that screen/component from the MCP project and validating the build against it — never eyeball from memory, never trust a local copy. Local design files are a cache only and may be stale (the QR setu prototype-handoff/ .dc.html handoff predates the current design system and its per-screen Home/Profile/Settings.dc.html no longer exist upstream — do not implement from it). Visual drift from the design is a bug: a screen is not done until it matches the current MCP design (spacing, radius, type scale, color tokens, component structure, states). When the design and this repo's tokens disagree, reconcile deliberately and record it — do not silently diverge.