@micha.bigler/ui-core-micha 2.38.0 → 2.39.0

package/work-orders/PRIM-1.md

@@ -0,0 +1,177 @@
+# PRIM-1 — Promote `StatTile` and `SoftChip` into the shared kit
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — shared-core.
+
+New register prefix `PRIM-*`: shared dashboard/data primitives — small presentational components that
+are neither chart (`CHART-*`) nor app chrome (`SHELL-*`).
+
+---
+
+## A. Envelope
+
+### Goal
+
+Both components already exist **twice**, built independently, and the second build in each case is an
+**inline component inside a page** rather than a file — which is why a filename search misses it:
+
+| Component | First build | Second build |
+|---|---|---|
+| `StatTile` | `hram/frontend/src/components/ResearchComponents/StatTile.jsx` (36 lines) | `fitness-monitor/frontend/src/pages/BodyHistoryPage.jsx:554-568` |
+| `SoftChip` | `hram/frontend/src/components/ResearchComponents/SoftChip.jsx` (67 lines) | `cockpit/frontend/src/cockpit/BoardView.jsx:65-73` (the lane pill) |
+
+Promote both into the kit as the single implementation. The promotion trigger is met on evidence — two
+independent builds each, and a third app in view for each.
+
+### The visual spec, and the seven decisions in it
+
+**Prototype:** [`work-orders/assets/PRIM-1-dashboard-primitives.html`](work-orders/assets/PRIM-1-dashboard-primitives.html).
+It renders the promoted spec at 375 px and 1280 px, keeps both original builds side by side as the
+record of what changed, and computes its contrast ratios in-page against the *blended* fill.
+
+The two builds diverged in seven places. All seven were decided by the operator on 2026-08-12, and the
+prototype already reflects them:
+
+| | Decision | Which app changes |
+|---|---|---|
+| StatTile value size | **`h5` — 18/600** | hram, 16 → 18 |
+| StatTile digits | **`tabular-nums`, always** — it is what makes a KPI row read as a row | fitness-monitor |
+| StatTile row behaviour | **`flex: 1` with a `minWidth` floor** — one rule covering both existing behaviours, no prop | hram, tiles now share the row |
+| StatTile `accent` | **kept** — 2 px `primary.main`; without it fitness-monitor cannot adopt | neither |
+| StatTile padding | **responsive `{xs: 1, sm: 1.5}`** | hram, was fixed |
+| SoftChip `status` typography | **`overline` — 11/600, uppercase, .4 px tracking** | hram (`passed` → `PASSED`); cockpit drops 700 → 600 |
+| SoftChip leading element + border | **dot by default, any icon via prop; border optional** | neither — both adopt unchanged |
+
+**Why `overline` rather than a new variant:** cockpit's build independently arrived at 11-with-uppercase-
+and-.4 px-tracking, which is the baseline's `overline` in all but the weight step. So the shared choice
+is what the second consumer already made, and it satisfies `THEME-4` **without a baseline change**.
+
+### Token delta list
+
+**One entry** — the rest is drawn from the baseline's own tokens, so there is nothing else to reconcile.
+
+- **`caveat` variant text: 12/500.** The baseline's nearest variant is `caption` at 12/**400**; there is
+  no 12/500. **Resolved by the operator as: keep the prototype value, do not add a baseline variant in
+  this WO.** It will surface as a `THEME-4` finding on the promoted component and must be **exempted
+  with that reason stated** — not silently flattened to 400, and not fixed by extending the baseline
+  here. Adding a variant is an app-level decision that does not belong inside a component promotion.
+
+### Scope
+
+1. **`StatTile`** as a kit component, per the decisions above. Props: `label`, `value`, `caption`,
+   `accent`, `children`, and a `minWidth` floor with a sensible default.
+2. **`SoftChip`** as a kit component. Props: `label`, `tone` (`success`/`warning`/`error`/`info`),
+   `variant` (`caveat`/`status`), `icon` (defaulting to the 6 px dot), a border toggle, and `title` for
+   the tooltip.
+3. **Colour derivation stays as authored** — fill `alpha(main, .12)`, border `alpha(main, .30)`, text and
+   dot `darken(main, .3)`, read from `theme.palette[tone]`. **Do not restate any hex.** This is the
+   property that makes the component exemplary and the reason its four tones all pass AA (measured in the
+   prototype: 7.11 / 7.33 / 7.67 / 9.20).
+4. **Keep `enterTouchDelay={0}`** on the tooltip. It is why SoftChip's `title` is reachable on a touch
+   pointer — the exact failure `AUTH-4` is blocked on elsewhere. Do not drop it as boilerplate.
+5. Exports from the package root, and the README line.
+
+### Non-goals / do not touch
+
+- **The three app adoptions.** hram, fitness-monitor and cockpit each get their own small follow-up WO.
+  This WO ships the kit component and nothing in any app.
+- **No baseline/theme change.** No new typography variant, no palette edit. See the token delta list.
+- **The other primitives in hram's `ResearchComponents/`** — `CardTitle`, `InfoPopover`,
+  `ProvisionalChip`, `FieldInfo`. `ProvisionalChip` wraps `SoftChip` and is the obvious next candidate,
+  but it has one build and is out of scope here.
+- **`SoftChip`'s `caveat` weight.** Left at 12/500 deliberately.
+- Any chart wrapper, shell component, or existing kit surface.
+
+### Risks
+
+- **Two apps' visible appearance changes when they adopt** — hram's status chips become uppercase and its
+  KPI values grow 16 → 18; cockpit's pills lose a weight step. All three are decided, not accidental, and
+  all three land in the *adoption* WOs rather than here. Worth stating in each so nobody reports them as
+  regressions.
+- **Neither `StatTile` build has a test.** The promoted component's tests are written here from scratch,
+  not ported. `SoftChip` has `SoftChip.test.jsx` in hram — read it, but do not assume it covers the
+  promoted API.
+- **`THEME-4` will flag the `caveat` 12/500.** Expected. Exempt with the reason; an unexplained exemption
+  is itself a finding by that check's own design.
+- **Version:** this is a new capability area (two new components), so a **minor** — `2.38.0` → `2.39.0`.
+
+### Required tests to WRITE
+
+- **`StatTile`**: renders label/value/caption; omits the value row when `value` is undefined; renders
+  `children`; `accent` applies the 2 px border and the default does not; the value carries
+  `tabular-nums`.
+- **`SoftChip`**: each of the four tones derives fill/border/text from `theme.palette[tone]` rather than a
+  literal (assert against the theme object, not against a hex string); `status` vs `caveat` differ in
+  radius and typography; the default leading element is the dot and a passed `icon` replaces it; the
+  border toggle works; `title` renders a tooltip and `enterTouchDelay` is 0.
+- **Do not write a contrast assertion using `getContrastRatio`** — it ignores alpha, so on a 12 % tint it
+  answers a different question and would pass while meaning nothing. The prototype computes the real
+  ratios; if a contrast test is wanted it must blend the fill first.
+
+Scope the run to these two new specs plus anything the new exports touch. Not the full suite — no
+dependency change, no theme change.
+
+### Parity guardrail
+
+Visual and API only. The promoted components must be capable of rendering **both** existing builds'
+appearances where a decision preserved them, and exactly the decided appearance where it did not. No
+behaviour, permission or data-contract surface exists here.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+---
+
+## C. Orchestrator only
+
+> **STOP — if you are the implementer reading this work order as your own specification, this section is
+> NOT addressed to you. Skip it entirely.** It tells the Orchestrator how to invoke you, how the result
+> is reviewed, and how it is committed. **You ARE that invocation — do NOT shell out to `codex exec`, do
+> NOT spawn reviewers, do NOT run tests beyond your own new ones, do NOT edit `WORK_ORDERS.md`, and do
+> NOT `git add`/`commit`/`push`.** Leave the diff in the working tree.
+
+### Execution directive
+
+Check `.claude/codex-status.md` first. **No line for the current date means use Codex.** A line recording
+`unavailable` for the current date means skip the attempt, implement directly in Claude, and name the
+record and its date — that flips authorship. If the newest confirmation is older than today, make exactly
+one probe and write the outcome back either way.
+
+### Review routing
+
+Tier 3: **independent `reviewer`** and **`ui_reviewer`**, concurrent, in one background batch, before the
+commit. **No `sec_reviewer`** — no auth, permission, money or schema surface.
+
+Ask `ui_reviewer` specifically whether the `overline` decision reads correctly at both variants, and
+whether the `caveat` exemption is stated rather than assumed.
+
+### Verification
+
+**A prototype is in scope, so the rendered side-by-side at 375 px and 1280 px is a commit gate** — see
+`AGENTS.md` → Reviews. Note the known constraint: the Browser pane composites only while displayed and
+screenshots have not been legibly obtainable in this repo. If capture fails, **declare the substitution
+in the register Notiz** and say what was inspected instead (computed styles, DOM) — an undeclared
+substitution is a skipped gate, and that fallback cannot see whether a screen reads heavy or dense.
+
+The prototype's own contrast numbers are computed at render time; re-read them rather than restating
+these.
+
+### Register + commit
+
+One row, `PRIM-1`, with the `PRIM-*` prefix documented in the register header. `done` only with both
+reviewers and their verdicts named, plus the rendered-gate evidence or its declared substitution.
+
+Publishing is a separate step from committing: **a landed commit is not a publish.** If the three
+adoption WOs are to follow, `2.39.0` must actually be on the registry first — verify against npm, not
+against a commit.
+
+### Mini-handover
+
+Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
+WO: `work-orders/PRIM-1.md`. Promotes two components whose second builds are inline in
+`fitness-monitor/BodyHistoryPage.jsx:554` and `cockpit/BoardView.jsx:65`. Seven divergences already
+decided — the table in Part A is the spec, the prototype renders it. Tier 3, both reviewers, rendered
+gate applies, minor version `2.39.0`. App adoptions are separate WOs. Follow `orchestrate-codex`.