docs(design-sync): correct conventions header drift after the token port

.design-sync/NOTES.md

@@ -46,7 +46,36 @@ repo defects — re-flag to the design agent instead of restructuring CSS:
 
 ## Known render warns
 
-- None — 10/10 render clean, no thin/blank/variantsIdentical flags.
+- Renders themselves stay clean: 10/10, no thin/blank/variantsIdentical flags
+ (re-confirmed 2026-07-30).
+- `[TOKENS_MISSING]` 7 CSS custom properties — triaged 2026-07-30, all seven
+ are **expected in the bundle**, so the warn line itself is known. Four are
+ benign by construction (runtime-set or scan artifacts); three are undefined
+ references in repo code that the bundle merely carries along (tracked as
+ `#141` in `docs/outstanding-issues.md`, not a sync defect):
+ - `--mobile-composer-reserve` — set at runtime by
+ `clinical-dashboard/mobile-composer-reserve.ts` and always read through a
+ `var(…, 0rem)` fallback. Never in a static stylesheet. Do not "fix".
+ - `--x` — Tailwind v4 scans the whole repo, found the literal string
+ `bg-[color:var(--x)]` in `docs/redesign/03-decision-log.md` prose, and
+ emitted a class for it. An artifact of documenting a class name; nothing
+ renders it.
+ - `--med-accent`, `--med-accent-border` — also runtime-set, not defects.
+ `medicationAccentStyle()` in
+ `clinical-dashboard/medication-record-page.tsx:88-94` assigns both, and
+ that style object is applied to the ancestor that contains every
+ referenced class (`:393`). A stylesheet-only missing-token scan cannot
+ see React `style` assignments; do not "fix" these.
+ - `--clinical-accent-strong`
+ (`clinical-dashboard/answer-status.tsx:252`) — genuinely undefined
+ production reference, no stylesheet or React `style` definition and no
+ fallback, so the declaration is dropped at parse time. Same defect
+ family as the dead `--text-4xs` classes repaired on 2026-07-30.
+ - `--primary-hover`, `--success-hover` —
+ `favourites-page-mockups/favourites-library-redesign-page.tsx`, which is
+ gate-exempt design scratch. Lowest priority.
+- If a future sync sees a **different** var in the `[TOKENS_MISSING]` warn, that
+ one is new — look at it before recording it.
 
 ## Re-sync risks
 
@@ -64,3 +93,17 @@ repo defects — re-flag to the design agent instead of restructuring CSS:
  components, but prop renames need preview edits.
 - The `prompt-for-codex-medical-knowledge-base` import specifier in previews is
  the package.json `name`; if the repo is renamed, update previews + config.
+- `conventions.md` drifts silently when the token set moves. The 2026-07-30
+ re-sync caught two dead claims after the Clinical Sky port: a `-solid` /
+ `-solid-contrast` pair claimed for every status family when only `danger`
+ has one, and `controlBase` listed as module-private when
+ `ui-primitives.tsx:34` exports it. Re-validate every enumerated token/class/
+ icon against `ds-bundle/_ds_bundle.css` (definitions only — match
+ `--name\s*:`, not bare `var(--name)`, or referenced-but-undefined vars read
+ as defined) and the bundle's export list on every re-sync. A helper lives at
+ `.design-sync/.cache/validate-conventions.mjs` (gitignored, cheap to rewrite).
+- The driver reports the token port as `changed: []` with `sourceKeys`
+ unchanged: `sourceKeys` track the authored preview + preview-affecting config,
+ NOT component source. A component-source or token change surfaces instead as
+ render churn (`canary`/`[SPOT_CHECK]`) plus `styling: true`. Grade the
+ spot-check sheets — the churn is real even though nothing is listed "changed".

.design-sync/conventions.md

@@ -17,8 +17,11 @@ arbitrary-value form — never hardcoded colours:
 - Borders: `border-[color:var(--border)]`, `--border-strong`, `--border-lux`
 - Accent (primary action colour): `--clinical-accent`, `--clinical-accent-hover`, `--clinical-accent-active`, `--clinical-accent-soft`, `--clinical-accent-border`, `--clinical-accent-contrast`
 - Command (primary buttons): `--command`, `--command-hover`, `--command-contrast`
-- Status: `--danger-text/-bg/-border/-solid/-solid-contrast`, plus the same
- families for `success`, `warning`, `info` (e.g. `--success-text`)
+- Status: `success`, `warning`, `info` and `danger` each define
+ `-text`, `-bg`, `-border`, `-soft` (e.g. `--success-text`, `--warning-soft`).
+ The solid pair `--danger-solid` / `--danger-solid-contrast` exists for
+ `danger` only — there is no `--success-solid`, `--warning-solid` or
+ `--info-solid`. For a filled non-danger status use `-bg` + `-text`.
 - Elevation: the `--e0` … `--e4` ladder — `shadow-[var(--e2)]`, `hover:shadow-[var(--e3)]`.
  `--e0` flush · `--e1` resting hairline · `--e2` cards/popovers · `--e3` hover/lifted chrome ·
  `--e4` modals/sheets/drawers. The role names are aliases onto tiers:
@@ -42,13 +45,15 @@ re-deriving surfaces: `panel`, `panelSubtle`, `raisedCard`, `sourceCard`,
 `navPill`, `metadataPill`, `subtleStatusPill`, `shellChip`, `fieldLabel`,
 `fieldControl`, `fieldControlWithIcon`, `fieldControlPlain`, `fieldIcon`,
 `eyebrowText`, `textMuted`, `proseMeasure`, `codeText`, `iconTilePremium`,
-`clinicalDivider`, `tableCard`, `tableCardHeader`, plus the chat/search
-composer and tone recipes documented in
+`clinicalDivider`, `tableCard`, `tableCardHeader`, `controlBase` (the shared
+control shell the button recipes build on — prefer `primaryControl` /
+`floatingControl` / `toolbarButton` unless composing a new control), plus the
+chat/search composer and tone recipes documented in
 `docs/redesign/09-ui-primitives-recipes.md`. Join with the exported `cn(...)`
 helper.
 
 Module-private helpers (`insetCard`, `iconTile`, `compactMetadataRow`,
-`toneWarningQuiet`, `controlBase`, `statusDotBase`, `chatComposerShellDelta`)
+`toneWarningQuiet`, `statusDotBase`, `chatComposerShellDelta`)
 power components inside `ui-primitives.tsx` and are **not** part of the import
 surface — use the exported components (`LoadingPanel`, `PanelHeading`,
 `SourceProvenance`, `SourceStatusBadge`, …) or the exported recipes above.