@micha.bigler/ui-core-micha 3.11.1 → 3.12.0

package/work-orders/UCM-THEME-16.md

@@ -0,0 +1,80 @@
+# UCM-THEME-16: Dark-safe info box in `QrSignupManager`
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+The "Signup Access / valid until" box under a generated signup QR code stays readable in dark mode. Today it
+paints a fixed light ground, `grey.50` (`#FAFAFA`), under the theme's secondary text; in dark that is
+`#AAB5BF` on `#FAFAFA`, **2.00:1**. After this order the box takes `background.subtle`, which resolves per
+mode: light `#F4F5F6` (5.37:1 for its text), dark `#20262C` (7.32:1).
+
+## Decided (operator, 2026-10-02)
+
+- **`src/components/QrSignupManager.jsx:376`**: `bgcolor: 'grey.50'` -> `bgcolor: 'background.subtle'`.
+  **The light change is accepted**: `#FAFAFA` -> `#F4F5F6`, a 1.05:1 step, barely visible.
+- **`src/components/QrSignupManager.jsx:361`** (`bgcolor: '#ffffff'` behind the QR code itself) **stays white
+  on purpose**: a QR code needs a light quiet zone to scan. Recorded in `docs/DARK-TOKENS.md`.
+- **`src/messaging/ReadTicks.jsx:14`** (`DM_SENT_COLOR = 'grey.500'`) **stays unchanged.** It already clears
+  contrast in dark (6.07:1 on the dark paper). The candidate `text.disabled` (`#6A7178`) is the value the file's
+  own comment records as rejected, because it read too close to the "read" state. In light the tick sits at
+  2.68:1 on white. That is a pre-existing condition, softened by the icon shape (Done vs DoneAll), and not
+  part of this order.
+
+These decisions replace the register row's original question ("accept the small light change, or add a
+token"), raised by the `UCM-THEME-14` review.
+
+## Scope + non-goals
+
+In scope: the one property at `QrSignupManager.jsx:376`; `CHANGELOG.md`; a **patch** release.
+
+Non-goals: no change to `ReadTicks.jsx`, to the QR code's white ground, or to any token value.
+
+## Tier · precondition / gate
+
+- **Tier 3 · tests: one rendered-style assertion per mode for the info box; the component's existing tests.**
+  A change inside shared-core, even at one line (`AGENTS.md` -> Tiering).
+- Precondition: `UCM-THEME-14` landed (3.11.0, confirmed 2026-10-02).
+
+## Risks
+
+- The light change is the only light-output change since `UCM-THEME-14`'s regression fixture. If that fixture
+  covers this component, it needs this one entry updated, named, and nothing else.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
+
+1. In a light theme from `createAppTheme`, the info box's background resolves to `#F4F5F6`; in a dark theme to
+   `#20262C`. Assert against the theme's own `background.subtle`, not a copied hex.
+
+Run, do not write: the existing `QrSignupManager` tests and the light regression fixture.
+
+## Parity guardrail
+
+No behaviour change. One background, both modes.
+
+---
+
+# B. Implementation map, filled by the Orchestrator and ADDRESSED TO THE IMPLEMENTER
+
+*Placeholder. The Orchestrator fills the context package, the absolute working directory, the
+progress contract and the preamble block on `git pull`, per `AGENTS.md` -> "Work Order". A one-line change
+may be implemented by the Orchestrator directly; authorship then sits with it and the independent review
+carries independence. Do not dispatch while this placeholder stands.*
+
+---
+
+# C. Orchestrator only, NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this work order as your own specification: STOP at this line.**
+> Everything below describes what the Orchestrator does AFTER you finish. You do none of it: no
+> reviewers, no verification run, no register edit, no `git add`/`commit`/`push`.
+
+- Check `.claude/codex-status.md` first (newest-first). Before `git push`, run `git log origin/main..HEAD` and
+  push only if every listed commit is this order's.
+- Review: Tier 3, independent `reviewer` (all configured lenses) and `ui_reviewer`, one batch, before the
+  commit.
+- Release: verify the publish through the job log (`npm view` lags for provenance publishes). Row -> `done`
+  with the review Notiz and the version.
+
+Mini-handover: `Orchestrator: implement work-orders/UCM-THEME-16.md in ui-core-micha (main). git pull first,
+read the WO, then follow orchestrate-codex.`

package/work-orders/UCM-THEME-17.md

@@ -0,0 +1,111 @@
+# UCM-THEME-17: Decide a less compressed baseline type scale
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+The baseline's heading steps are too small to carry a hierarchy. Page title, card title and section label
+differ by 1 to 3 px, so screens rely on weight alone, and where every level is bold the levels merge. This
+order produces the **decided** type scale as a committed reference sheet that the operator freezes. A
+later implementation order puts it into `src/theme/tokens.js`. The output here is a document, no code.
+
+Operator decision (2026-10-04): treat this as a baseline finding, the way dark mode was treated
+(`UCM-THEME-13`), not as per-app overrides.
+
+## Context the operator established
+
+- **The baseline scale today** (`src/theme/tokens.js:157-168`): h1 32, h2 28, h3 24, h4 20, h5 18, h6 16,
+  subtitle1 15/600, subtitle2 13/500, body1 14, body2 13, button 14/500, caption 12, overline 11 (px).
+- **Measured on rendered screens, 2026-10-04** (computed styles in the browser):
+
+  | Screen | Page title | Card title | Section | Text |
+  |---|---|---|---|---|
+  | hram, Research | h4 20/500 | h5 18/500 | subtitle1 15/600 | 14 |
+  | jg-ferien, Dashboard | h5 18/600 | h6 16/600 | – | 14, partly 600 |
+  | kerzenziehen, Admin | h5 18/600 | – | – | 14 |
+  | survey_app site (operator screenshots) | h4 20/800 | h6 16/800 | – | – |
+  | for comparison, the MUI scale (spesix, stale local build) | h4 34 | h5 24 | – | 16 |
+
+- **Operator feedback:** survey_app editor and sites read "more harmonious" at the old MUI sizes, and on the
+  sites the section title and the question labels became indistinguishable. jg-ferien already restored its
+  own sizes (`jg-ferien` `JG-DL-7`). Six other apps accepted the baseline scale without comment.
+- **The MUI scale is the other extreme**: 34/24 px titles read heavy in a dense tool.
+
+## Inventory (stage 1, 2026-10-04)
+
+From 88 prototypes in `*/work-orders/assets/` (screen selectors hand-checked in nine: KZ-UI-1, RES-14,
+INNO-PLAN-1, JG-MEM-1, UX-10, PRIM-1, FM-8, OBS-10, KIRA-CRUD-6), the app theme overrides and the
+measurements above:
+
+| Role | Baseline today | Approved prototypes (typical) | MUI |
+|---|---|---|---|
+| Screen title | h4 20/600, fixed | 24 at 1280, 17-21 at 375 (KZ 24->17, jg 25.6->20, survey 24->21) | 34 |
+| Panel / dialog | h5 18 | 18-20 | 24 |
+| Card title | h6 16 | 15-18 | 20/500 |
+| Section label | subtitle1 15/600 | 12-13 at 600-700 | - |
+| Body | 14 | 14 (20 sheets), 15 (13 sheets) | 16 |
+
+- The approved designs had the larger title step (screen title about 1.7x body; baseline 1.43x), and step
+  the title down on mobile. Both were lost between prototype and baseline.
+- The section label sits on the wrong side of body: 15 px, one pixel under the card title.
+- jg-ferien rejected larger **body** text (`JG-DL-7`); survey_app misses **heading** steps. The two are
+  compatible.
+- Weight no longer carries hierarchy: every heading is 600 and apps override it per level (survey_app 800,
+  hram 500).
+
+## Structural decisions (operator, 2026-10-04)
+
+1. **One scale** for every app and page type; no separate reading register. Body stays the tool density.
+2. **The screen title steps down one size on narrow screens.**
+3. **Size carries the hierarchy, weight is fixed**: headings share one weight; the section label is small
+   and strong. App overrides are for font family, not for per-level weight.
+4. **The section label (subtitle1) moves below body size**, set apart by weight.
+
+The role mapping of the `THEME-1` sheet stands: h4 screen title, h5 panel/dialog, h6 card title.
+
+## Outcome
+
+**Frozen 2026-10-04** after two value rounds: candidate B, mobile screen title 23, h1 to h3 36 / 32 / 28. The
+frozen sheet is [`docs/TYPE-SCALE.md`](../docs/TYPE-SCALE.md); the implementation order is `UCM-THEME-18`.
+
+## Scope + non-goals
+
+In scope: an inventory of the type sizes the estate actually uses (app overrides, prototypes, the
+`THEME-1` reference sheet's own reasoning); an instrument showing two to three candidate scales next to
+today's baseline and the MUI default, on real screens (hram Research, a survey site, the jg-ferien dashboard,
+a kerzenziehen admin view), at 375 px and 1280 px; value rounds; a frozen sheet with provenance and the
+rejected candidates.
+
+Non-goals:
+- No code, no tests (the implementation is a separate order).
+- No change to font families. Apps keep their identity fonts.
+- No per-app decisions. App overrides that exist only to escape the compressed scale (survey_app's planned
+  revert, `JG-DL-7`) are reviewed after the freeze, not here.
+
+## Tier · precondition / gate
+
+- **Tier 2 · tests: none (document only).** It decides future shared-core content but changes none.
+- Precondition: none.
+- Gate: **the operator freezes the sheet**, with a dated section in it.
+
+## Risks
+
+- **Every adopted app moves with the baseline.** A new scale changes the look of ten-plus apps at once; the
+  instrument has to show the dense tool screens, not only reading screens.
+- **Bigger steps cost vertical space** on dense screens (hram, cockpit). The candidates must be judged
+  there, not only on the survey sites.
+- **Weight and size interact.** The fix may be partly a weight rule (fewer bold levels), not only sizes.
+
+---
+
+# B. Implementation map
+
+*Not applicable. This is an Expertenchat document order, authored in-session with the operator.*
+
+---
+
+# C. Orchestrator only, NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this: STOP.** There is no implementer for this order.
+
+Register: row -> `done` with the commit of the frozen sheet. Then the implementation order is written.

package/work-orders/UCM-THEME-18.md

@@ -0,0 +1,184 @@
+# UCM-THEME-18: Ship the frozen baseline type scale
+
+# A. Envelope, authored by the Expertenchat
+
+## Goal & expected outcome
+
+`createAppTheme` produces the type scale frozen in [`docs/TYPE-SCALE.md`](../docs/TYPE-SCALE.md) (`UCM-THEME-17`,
+frozen 2026-10-04), in light and dark. The screen title (h4) steps down one size below the baseline's `sm`
+breakpoint. Released as a **minor** version (`3.12.0`), because every adopted app looks different after the bump.
+
+## Decided values (from `docs/TYPE-SCALE.md`, by variant)
+
+| Variant | Before | After |
+|---|---|---|
+| h1 / h2 / h3 | 32 / 28 / 24 | **36 / 32 / 28** |
+| h4 | 20 | **24**, and **23 below `sm`** |
+| h5 | 18 | **20** |
+| subtitle1 | 15 | **13** |
+
+Unchanged: h6, subtitle2, body1, body2, button, caption, overline; every weight (headings 600, subtitle1 600);
+every line height; `letterSpacing`. If this table and `docs/TYPE-SCALE.md` disagree, the sheet wins.
+
+## Context the operator established
+
+- **Typography lives in one block**: `src/theme/tokens.js:223-241`, built with `typeVariant` (`tokens.js:45`).
+  `createAppTheme` (`src/theme/createAppTheme.js:379-387`) spreads it unchanged and takes only `fontFamily`
+  from the app, so light and dark get the same scale from the same place.
+- **Breakpoints**: `tokens.js:250-252`, `sm: 600`. The mobile step means "below `sm`", the same line MUI's
+  `breakpoints.down('sm')` draws.
+- **`assertThemeComplete`** reads `fontSize`, `fontWeight`, `lineHeight` and `letterSpacing` per variant
+  (`src/theme/themeCompleteness.js:38`). A nested media-query key inside h4 is new to it.
+- **The light regression fixture** `tests/fixtures/light-theme-baseline.json`, checked by
+  `tests/createAppThemeLightGuard.test.js`, contains the typography and changes with this order.
+- **The kit's own screens use the variants too** (h6 about 24 times, h4 twice, h5 once in `src/`), so kit
+  screens such as the account pages change with the scale. That is intended.
+
+## Scope + non-goals
+
+In scope: the typography values above; the h4 step below `sm`; the fixture's typography entries;
+`CHANGELOG.md` naming the visible change for every adopted app; the minor release.
+
+Non-goals:
+- No app repo changes. The per-app follow-up (listed below) is written after the release, one order per app.
+- No font family, weight or line-height change; no new variant; no change to `breakpoints`.
+- No responsive step for any variant other than h4.
+
+## Tier · precondition / gate
+
+- **Tier 3 · tests: the typography values per variant and the h4 step, in light and dark; the light
+  regression fixture updated in its typography entries only; the existing `createAppTheme` and completeness
+  tests.** A change inside shared-core (`AGENTS.md` -> Tiering).
+- Precondition: `UCM-THEME-17` `done` (frozen sheet committed).
+- No prototype gate: the instrument is a decision sheet, not a screen to match.
+
+## Risks
+
+- **Every adopted app moves on its next bump.** Intended; the changelog says so in one line an app session can
+  act on.
+- **An app that overrides h4's size keeps the baseline's 23 px below `sm`**, because a theme merge keeps the
+  nested media key. survey_app sets h4 to `2.125rem` today; on mobile it would fall to 23. The per-app
+  follow-up handles it; the changelog names it.
+- **`assertThemeComplete` may misread the nested key** (as a missing or extra surface). It must neither raise
+  a finding for the baseline's own media key nor let an app's h4 override go unnoticed.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the Orchestrator's run is the gate)
+
+1. For a light and a dark theme from `createAppTheme`: each variant in the table resolves to its decided
+   `fontSize`, read from the theme, compared with the value in the table.
+2. h4 carries a media-query entry for "below `sm`" with `fontSize` 23px, and that query is derived from
+   `breakpoints.values.sm`, not typed a second time. Show the test fails if `sm` changes and the query does not.
+3. `assertThemeComplete` on the baseline returns no typography finding.
+
+Run, do not write: `tests/createAppTheme.test.js`, `tests/createAppThemeLightGuard.test.js` (with the fixture's
+typography entries updated, and only those), the completeness tests.
+
+## Parity guardrail
+
+No behaviour change; type sizes only. Palette, spacing, components and exports unchanged.
+
+## Downstream (not this order; one order per app after the release)
+
+Measured 2026-10-04 (see `docs/TYPE-SCALE.md` -> "Known consequences"):
+
+| App | What the follow-up does |
+|---|---|
+| hram | screen titles on 5 pages from h5 to h4; drop the per-level weight 500 |
+| jg-ferien | screen titles on 3 pages from h5 to h4 (`DashboardPage.jsx:187`) |
+| kerzenziehen | admin screen title from h5 to h4 |
+| spesix | 1 page title from h5 to h4; drop per-level weight overrides |
+| fitness-monitor | 1 page title from h5 to h4 |
+| survey_app | drop the 800/700 weights and the h4 `2.125rem`/400 override; decide the h3 page titles (24 -> 28); closes the held `SVA-THEME-1` typography revert |
+| all other adopted apps | bump only |
+
+webshop-guenter (own handoff scale), Kira, Cinevia and Gustav (no MUI heading variants) are unaffected.
+
+---
+
+# B. Implementation map, filled by the Orchestrator and ADDRESSED TO THE IMPLEMENTER
+
+Work from this package; open only the named files. A value the sheet lacks is `RESULT: BLOCKED <value>`.
+
+## Target working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`). Never the workspace root.
+
+## Context package
+
+- **`src/theme/tokens.js`**: `BASELINE_STATIC.typography` (l.~222-241) uses `typeVariant(size, weight, lineHeight, extra)`
+  (l.45). Change h1/h2/h3/h4/h5/subtitle1 to the table in Part A; nothing else in that block moves.
+  h4 gets the mobile step as a nested media-query key inside the variant (`extra`), `fontSize: '23px'`.
+  The query must be **derived from the breakpoint value**, not typed a second time: introduce one
+  constant for `sm` (600) in `tokens.js`, use it in `breakpoints.values.sm` (l.~251) and build the key
+  from it, in the form MUI's `breakpoints.down('sm')` produces (`@media (max-width:599.95px)`, that is
+  `sm - 0.05`). Export the constant or the key builder so the test can reference it.
+- **`src/theme/createAppTheme.js`** (l.~379-387) spreads `BASELINE_STATIC.typography` and takes only
+  `fontFamily` from the app; no change expected. Verify the nested media key survives `createTheme`
+  into `theme.typography.h4` in both light and dark (read the resolved theme, do not assume).
+- **`src/theme/themeCompleteness.js`** (`TYPOGRAPHY_SURFACES`, l.~38) reads fontSize/fontWeight/lineHeight/
+  letterSpacing per variant. Verify the baseline h4 with its media key raises no finding; change this file
+  only if it does.
+- **Light regression fixture** `tests/fixtures/light-theme-baseline.json` (checked by
+  `tests/createAppThemeLightGuard.test.js`): update ONLY the typography entries that this order changes
+  (h1-h5 and subtitle1 `fontSize`, and h4's new media key), in both of its snapshots (`baseline`, `override`).
+  Regenerate carefully: the diff of the fixture must contain nothing but those typography lines. Do not
+  re-capture the whole file blindly; check `git diff` of the fixture afterwards (use `git diff` to read it,
+  do not stage).
+- **Docs / release**: `CHANGELOG.md` entry `3.12.0 - UCM-THEME-18` (newest first, same style as the
+  existing entries): the new scale in one table-free sentence; the visible change for every adopted app;
+  that an app overriding h4's `fontSize` keeps the baseline's 23px below `sm` (survey_app sets h4
+  `2.125rem`); that headings are fixed at weight 600 and apps should not override per level.
+  `package.json` version `3.11.2` -> `3.12.0` (no lockfile in this repo).
+- Kit components: no edit expected (they use the variants).
+
+**Existing tests to follow** (style): `tests/createAppTheme.test.js`, `tests/createAppThemeDark.test.js`.
+New tests go in `tests/createAppThemeTypography.test.js`.
+
+**Pitfalls**: weights, line heights, letterSpacing, h6, subtitle2, body1/2, button, caption, overline are
+unchanged and must stay byte-identical. Do not touch `breakpoints` values or add a second source for `sm`.
+
+## Required tests, restated
+
+The three tests of Part A. Test 2 must show it can fail: derive the expected query from
+`breakpoints.values.sm` of the resolved theme (not a literal), and include an assertion that would break if
+the baseline's key were typed independently of that value (for example by building a theme with a different
+`sm` through the same constant, if the constant is the single source, or by asserting the key string equals
+the builder applied to the theme's own `sm`).
+
+## Preamble
+
+The text above is the COMPLETE spec: the committed WO file's content, not a plan to refine; there is no
+separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the app
+`MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI unless the
+spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md`: the register row and the review
+verdicts are the orchestrator's alone.** **Your tools are for editing source and test files and for running
+the tests you wrote, nothing else.** Do NOT install dependencies, touch a lockfile, run a package manager,
+or tidy up stray files; if something in the repo state blocks you, stop and report it as
+`RESULT: BLOCKED <reason>` instead of fixing it. Do NOT `git add`/`commit`/`push`: leave every change
+uncommitted in the working tree for the orchestrator's independent review. WRITE the tests the
+`Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute and pass:
+that is the ONLY test run you do (NOT the affected/full suite, NOT any review). Run them with
+`npx vitest run <your test files>`. The orchestrator re-runs the authoritative set and does the independent
+review after you finish; those are the gate.
+
+Narrate continuously: a `PLAN: <step1> | <step2> | ...` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `... done` on
+completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+# C. Orchestrator only, NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this work order as your own specification: STOP at this line.**
+> Everything below describes what the Orchestrator does AFTER you finish. You do none of it: no
+> reviewers, no verification run, no register edit, no `git add`/`commit`/`push`.
+
+- Check `.claude/codex-status.md` first (newest-first). Before `git push`, run `git log origin/main..HEAD` and
+  push only if every listed commit is this order's.
+- Review: Tier 3, independent `reviewer` (all configured lenses) and `ui_reviewer`, one batch, before the commit.
+- Release `3.12.0`: verify the publish through the job log (`npm view` lags for provenance publishes). Row ->
+  `done` with the review Notiz and the version. Then the Expertenchat writes the per-app orders above.
+
+Mini-handover: `Orchestrator: implement work-orders/UCM-THEME-18.md in ui-core-micha (main). git pull first,
+read the WO, then follow orchestrate-codex.`