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

package/src/components/charts/chartDefaults.js

@@ -9,7 +9,7 @@ export function withGridDefaults(grid) {
 
 export function withAxisDefaults(axes, label, defaults, tickFontSize) {
   const values = axes?.length ? axes : [defaults];
-  return values.map((axis) => ({
+  return values.map((axis, index) => ({
     // `defaults.scaleType` (and any other scale-defining default) must
     // survive even when the caller passes their OWN xAxis/yAxis array --
     // confirmed live in the dev harness: a caller-supplied axis with `data`
@@ -25,7 +25,17 @@ export function withAxisDefaults(axes, label, defaults, tickFontSize) {
       fontSize: tickFontSize,
       ...axis.tickLabelStyle,
     },
-    label: axis.label || label,
+    // THEME-9: the single `label` argument is the caller's ONE string for
+    // this whole axis family (xAxisLabel/yAxisLabel) -- it may only ever
+    // fall back onto ONE axis. Applying it via .map() to every entry
+    // broadcast the identical label onto every axis in a multi-axis array
+    // (measured live: hram's dual-axis chart carried the same 43-character
+    // label on both y-axes). Only the first entry -- the common single-axis
+    // case is index 0 -- gets the fallback; a caller building a genuine
+    // multi-axis array must label each entry itself (as TimeSeriesChart's
+    // own secondary-axis support already does), exactly like MUI's own
+    // default `position: 'left'` (only the first entry, MUI docs).
+    label: axis.label || (index === 0 ? label : undefined),
   }));
 }
 
@@ -100,6 +110,136 @@ export function spaceForRotatedTicks(xAxis, margin, defaultLineHeight = 1) {
   return { xAxis: spacedXAxis, margin: spacedMargin };
 }
 
+// THEME-9: MUI X-Charts' own default y-axis width is a flat 45px (ticks) +
+// 20px (label, if present) = 65px regardless of what the ticks actually say
+// -- confirmed against @mui/x-charts' own DEFAULT_AXIS_SIZE_WIDTH /
+// AXIS_LABEL_DEFAULT_HEIGHT constants and its `useChartDimensions` selector
+// (drawingArea.left = margin.left + axisSizeLeft, i.e. margin and axis size
+// are ADDITIVE, not one containing the other). That flat default is both too
+// generous for short ticks ("0%"/"50%"/"100%") and too stingy for wide ones
+// ("50.0 min"), which is exactly the measured overlap on the Accessibility
+// y-axis. Mirrors spaceForRotatedTicks' existing text-width heuristic below.
+const Y_AXIS_TICK_SIZE = 6;
+const Y_AXIS_TICK_LABEL_GAP = 2;
+const Y_AXIS_LABEL_TICK_GAP = 2;
+// A rotated (90deg) axis-label's line-box "thickness" -- what it costs in
+// WIDTH once rotated -- runs a bit past its raw font size once ascender/
+// descender room is included; matches the ~18px measured live for a 14px
+// label (14 * 1.3 ~= 18).
+const Y_AXIS_LABEL_THICKNESS_FACTOR = 1.3;
+// A small safety margin on the estimate: `spaceForRotatedTicks`'s own risk
+// note applies here too -- a too-tight cut recreates the overlap it was
+// meant to fix, and glyph-width heuristics are approximate by nature.
+const Y_AXIS_WIDTH_SAFETY_FACTOR = 1.1;
+// MUI X-Charts' ChartsYAxisImpl hardcodes the axis-label font at 14px
+// (`additionalProps.style: {...theme.typography.body1, fontSize: 14, ...}`
+// -- fontSize:14 is set AFTER the theme.typography.body1 spread, so it wins
+// regardless of what body1 actually resolves to). Matching that literal
+// constant here -- rather than reading it off `theme.typography.body1` --
+// keeps this sizing correct even if this package's body1 size ever changes;
+// coupling it to body1 was only ever coincidentally right because body1
+// happens to be 14px today.
+const MUI_AXIS_LABEL_FONT_SIZE_PX = 14;
+
+function longestFormattedTick(values, valueFormatter) {
+  return values.reduce((longest, value) => {
+    let text;
+    try {
+      text = valueFormatter ? String(valueFormatter(value, { location: 'tick' })) : String(value);
+    } catch {
+      // Some formatters require MUI's complete scale context; falling back
+      // to the raw value is conservative -- it reserves at least as much
+      // space as the unformatted number would need.
+      text = String(value);
+    }
+    return text.length > longest.length ? text : longest;
+  }, '');
+}
+
+/**
+ * Sizes a linear y-axis to its actual tick content instead of MUI's flat
+ * default. Only touches axes the caller left unsized (`axis.width == null`)
+ * and only linear/numeric ones -- a categorical axis's ticks are names, not
+ * numbers, and sizing those is not this function's job. Candidate values come
+ * from the axis' own `min`/`max` when the caller set them (as every current
+ * consumer does), falling back to the series actually plotted against this
+ * axis; if neither yields a candidate, the axis is left untouched rather than
+ * guessed at.
+ *
+ * `tickFontSize` is only the FALLBACK -- an axis' own `tickLabelStyle.fontSize`
+ * (set by `withAxisDefaults`, itself overridable per-axis by the caller) is
+ * read first, so a caller-tuned tick font is sized correctly rather than
+ * against the package-wide default. The axis LABEL's font is not a caller
+ * knob at all (`MUI_AXIS_LABEL_FONT_SIZE_PX` -- MUI hardcodes it).
+ *
+ * The series-to-axis match for the fallback deliberately mirrors MUI's own
+ * default-assignment rule, not a naive `undefined === undefined`: a series
+ * with no explicit `yAxisId` is assigned to the FIRST axis in the array
+ * (`yAxisIds[0]` in MUI's own selector), never to "no id". Matching only
+ * `undefined === undefined` left the primary axis of a real dual-axis chart
+ * (id `'primary'`, its series never set `yAxisId`) with zero matched series
+ * and therefore MUI's untouched flat default -- a silent no-op on exactly
+ * the dual-axis case this WO was measured against.
+ */
+export function sizeYAxisForContent(yAxis, series, tickFontSize) {
+  const fallbackTickFontSizePx = cssLengthToPixels(tickFontSize);
+  const defaultAxisId = yAxis[0]?.id;
+  return yAxis.map((axis) => {
+    if (axis.width != null) return axis;
+    if (axis.scaleType && axis.scaleType !== 'linear') return axis;
+
+    const tickFontSizePx = cssLengthToPixels(axis.tickLabelStyle?.fontSize) || fallbackTickFontSizePx;
+    if (tickFontSizePx === 0) return axis;
+
+    const candidates = [];
+    if (typeof axis.min === 'number') candidates.push(axis.min);
+    if (typeof axis.max === 'number') candidates.push(axis.max);
+    if (candidates.length === 0) {
+      (series || [])
+        .filter((item) => (item.yAxisId ?? defaultAxisId) === axis.id)
+        .forEach((item) => (item.data || []).forEach((value) => {
+          if (typeof value === 'number') candidates.push(value);
+        }));
+    }
+    if (candidates.length === 0) return axis;
+
+    const longestTick = longestFormattedTick(candidates, axis.valueFormatter);
+    const tickTextWidth = Math.max(
+      tickFontSizePx,
+      longestTick.length * tickFontSizePx * AVERAGE_GLYPH_WIDTH_EM,
+    );
+    const labelThickness = axis.label
+      ? Math.ceil(MUI_AXIS_LABEL_FONT_SIZE_PX * Y_AXIS_LABEL_THICKNESS_FACTOR) + Y_AXIS_LABEL_TICK_GAP
+      : 0;
+    const width = Math.ceil(
+      (tickTextWidth + Y_AXIS_TICK_SIZE + Y_AXIS_TICK_LABEL_GAP + labelThickness)
+      * Y_AXIS_WIDTH_SAFETY_FACTOR,
+    );
+
+    return { ...axis, width };
+  });
+}
+
+/**
+ * Locale-correct, unit-free tick numbers as the default -- BarChart set none
+ * at all (raw numbers straight from the domain), and a hand-rolled `Intl`
+ * compact-notation default was measured to be actively wrong: German does
+ * not compact thousands at all (`12'500` stays `12'500`) and Swahili prepends
+ * a word that is WIDER than the raw number (`elfu 12.5`) -- compact notation
+ * does not solve the width problem and worsens it in one locale. Plain
+ * grouped formatting (no `notation: 'compact'`) is safe across all four
+ * locales this package's consumers use. Ticks get a short, rounded form;
+ * tooltip/legend keep full precision -- teaching screens must not round away
+ * a meaningful difference. A caller's own `valueFormatter` always wins (this
+ * is only ever used as a default, per `withAxisDefaults`' `{...defaults,
+ * ...axis}` merge).
+ */
+export function defaultNumericTickFormatter(locale) {
+  return (value, context) => (context?.location === 'tick'
+    ? new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value)
+    : new Intl.NumberFormat(locale).format(value));
+}
+
 export function withChartSlotDefaults(slotProps, legendPosition) {
   const position = {
     ...DEFAULT_LEGEND_POSITION,

package/src/theme/themeCompleteness.js

@@ -73,8 +73,8 @@ const COMPONENT_SURFACES = [
   componentPath('MuiTooltip', 'defaultProps.slotProps.transition.timeout.enter'),
   componentPath('MuiTooltip', 'defaultProps.slotProps.transition.timeout.exit'),
   componentPath('MuiSelect', 'defaultProps.variant'),
-  componentPath('MuiSelect', 'styleOverrides.select.minHeight'),
-  componentKeyLeaf('MuiSelect', 'styleOverrides.select', '@media (any-pointer: coarse)', 'minHeight'),
+  componentPath('MuiSelect', 'styleOverrides.root.minHeight'),
+  componentKeyLeaf('MuiSelect', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
   componentPath('MuiCheckbox', 'styleOverrides.root.color'),
   componentKeyLeaf('MuiCheckbox', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
   componentKeyLeaf('MuiCheckbox', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),

package/src/theme/tokens.js

@@ -255,7 +255,7 @@ export const BASELINE_STATIC = {
     MuiSelect: {
       defaultProps: { variant: 'outlined' },
       styleOverrides: {
-        select: {
+        root: {
           minHeight: 40,
           boxSizing: 'border-box',
           '@media (any-pointer: coarse)': { minHeight: 44 },

package/tests/BarChart.test.jsx

@@ -50,9 +50,25 @@ describe('BarChart preset', () => {
     expect(chartSpy.mock.calls.at(-1)[0].colors).toEqual(['var(--application-chart-colour)']);
   });
 
-  it('requires labels for both axes', () => {
-    expect(() => render(
-      <ThemeProvider theme={createTheme()}><BarChart series={[]} xAxisLabel="Year" /></ThemeProvider>,
-    )).toThrow('BarChart requires xAxisLabel and yAxisLabel.');
+  // THEME-9: DESIGN.md #8a makes an axis title the caller's per-axis
+  // decision (categorical axes default to none) -- a hard "both required"
+  // throw made that default unachievable through this preset. Omitting a
+  // label now renders no title for that axis rather than crashing.
+  it('renders without a title on an axis whose label was omitted', () => {
+    render(
+      <ThemeProvider theme={createTheme()}><BarChart series={[{ data: [1] }]} xAxisLabel="Year" /></ThemeProvider>,
+    );
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.xAxis[0].label).toBe('Year');
+    expect(props.yAxis[0].label).toBeUndefined();
+  });
+
+  it('renders with no title on either axis when both labels are omitted', () => {
+    render(
+      <ThemeProvider theme={createTheme()}><BarChart series={[{ data: [1] }]} /></ThemeProvider>,
+    );
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.xAxis[0].label).toBeUndefined();
+    expect(props.yAxis[0].label).toBeUndefined();
   });
 });

package/tests/TimeSeriesChart.test.jsx

@@ -216,12 +216,17 @@ describe('TimeSeriesChart', () => {
     ],
   };
 
-  it('CHART-5: no custom yAxis when the shared single axis is not all-integer (today\'s real case)', () => {
+  it('CHART-5: no custom (integer-blanking) yAxis formatter when the shared single axis is not all-integer (today\'s real case)', () => {
     renderChart({ data: MIXED_DATA });
 
     const props = chartSpy.mock.calls.at(-1)[0];
     expect(props.yAxis).toHaveLength(1);
-    expect(props.yAxis[0].valueFormatter).toBeUndefined();
+    // THEME-9: BarChart now always supplies a default (locale-grouped, non-
+    // blanking) tick formatter, so this is no longer undefined -- but it
+    // must still be BarChart's generic default, not CHART-5's own
+    // integer-blanking one (which would wrongly blank the 4.5/5.2/6.1 ticks).
+    expect(typeof props.yAxis[0].valueFormatter).toBe('function');
+    expect(props.yAxis[0].valueFormatter(4.5, { location: 'tick' })).not.toBe('');
     expect(props.yAxis[0].label).toBe('Count');
   });
 
@@ -293,8 +298,13 @@ describe('TimeSeriesChart', () => {
     const props = chartSpy.mock.calls.at(-1)[0];
     const primaryAxis = props.yAxis.find((axis) => axis.id === 'primary');
     const secondaryAxis = props.yAxis.find((axis) => axis.id === 'secondary');
-    expect(typeof primaryAxis.valueFormatter).toBe('function');
-    expect(secondaryAxis.valueFormatter).toBeUndefined();
+    expect(primaryAxis.valueFormatter(2, { location: 'tick' })).toBe('2');
+    expect(primaryAxis.valueFormatter(2.5, { location: 'tick' })).toBe('');
+    // THEME-9: BarChart's own default formatter now covers the secondary
+    // axis too (a function, not undefined) -- distinguished from the
+    // integer-blanking one above by NOT blanking a non-integer tick.
+    expect(typeof secondaryAxis.valueFormatter).toBe('function');
+    expect(secondaryAxis.valueFormatter(4.5, { location: 'tick' })).not.toBe('');
   });
 
   it('CHART-5: throws when a series declares axis "secondary" without secondaryYAxisLabel', () => {
@@ -318,12 +328,15 @@ describe('TimeSeriesChart', () => {
 
   it('CHART-5: toggling the non-integer series off switches the shared axis to integer-formatted', () => {
     renderChart({ data: MIXED_DATA });
-    expect(chartSpy.mock.calls.at(-1)[0].yAxis[0].valueFormatter).toBeUndefined();
+    // THEME-9: BarChart's default formatter is present from the start now,
+    // so the CHART-5-specific signal is that a non-integer tick is NOT
+    // blanked yet -- the integer-blanking formatter isn't active.
+    expect(chartSpy.mock.calls.at(-1)[0].yAxis[0].valueFormatter(4.5, { location: 'tick' })).not.toBe('');
 
     fireEvent.click(screen.getByRole('checkbox', { name: 'Presence hours' }));
 
     const props = chartSpy.mock.calls.at(-1)[0];
-    expect(typeof props.yAxis[0].valueFormatter).toBe('function');
+    expect(props.yAxis[0].valueFormatter(4.5, { location: 'tick' })).toBe('');
   });
 
   it('CHART-5: x-axis tickLabelInterval guarantees some labels always show, evenly spread', () => {

package/tests/chartDefaults.test.js

@@ -14,6 +14,11 @@ vi.mock('@mui/x-charts/LineChart', () => ({ LineChart: lineSpy, MarkElement: 'pa
 import { BarChart } from '../src/components/charts/BarChart';
 import { LineChart } from '../src/components/charts/LineChart';
 import { TimeSeriesChart } from '../src/components/charts/TimeSeriesChart';
+import {
+  defaultNumericTickFormatter,
+  sizeYAxisForContent,
+  withAxisDefaults,
+} from '../src/components/charts/chartDefaults';
 import { createAppTheme } from '../src/theme/createAppTheme';
 
 const theme = createAppTheme({ palette: { primary: { main: '#3D5A99' } } });
@@ -206,3 +211,153 @@ describe('chart chrome defaults', () => {
     });
   });
 });
+
+// THEME-9 #2 -- `withAxisDefaults` broadcast the caller's single xAxisLabel/
+// yAxisLabel string onto EVERY entry of a multi-axis array via `.map()`.
+// Measured live: hram's dual-axis chart carried the identical 43-character
+// label on both y-axes. This is the defect that actually shipped, pinned
+// directly against the exported function rather than only through a
+// rendered BarChart (which never happens to build a multi-axis array).
+describe('withAxisDefaults label broadcast (THEME-9)', () => {
+  it('applies the single label argument only to the first axis of a multi-entry array', () => {
+    const result = withAxisDefaults(
+      [{ id: 'primary' }, { id: 'secondary' }],
+      'Shared label',
+      { scaleType: 'linear' },
+      '12px',
+    );
+    expect(result[0].label).toBe('Shared label');
+    expect(result[1].label).toBeUndefined();
+    // The exact defect: never let one string land on two axes.
+    expect(result.filter((axis) => axis.label === 'Shared label')).toHaveLength(1);
+  });
+
+  it('leaves axes that set their own label untouched, whatever position they are in', () => {
+    const result = withAxisDefaults(
+      [{ label: 'Primary' }, { label: 'Secondary' }],
+      'Fallback',
+      { scaleType: 'linear' },
+      '12px',
+    );
+    expect(result[0].label).toBe('Primary');
+    expect(result[1].label).toBe('Secondary');
+  });
+
+  it('still labels the common single-axis case unchanged', () => {
+    const result = withAxisDefaults([{ id: 'only' }], 'Cases', { scaleType: 'linear' }, '12px');
+    expect(result[0].label).toBe('Cases');
+
+    const synthesized = withAxisDefaults(undefined, 'Cases', { scaleType: 'linear' }, '12px');
+    expect(synthesized[0].label).toBe('Cases');
+  });
+});
+
+// THEME-9 #4 -- BarChart set no default tick formatter at all (raw domain
+// numbers); a hand-rolled `Intl` compact-notation default was measured to be
+// actively wrong in two of the four locales this package's consumers use:
+// German does not compact thousands at all, and Swahili prepends a word
+// ("elfu") that is WIDER than the raw number. Plain grouped formatting (no
+// `notation: 'compact'`) is pinned here against a live `Intl.NumberFormat`
+// computation rather than hardcoded locale punctuation, so the assertion
+// survives ICU data updates.
+describe('defaultNumericTickFormatter (THEME-9)', () => {
+  it.each(['de-CH', 'en', 'fr', 'sw'])('formats %s ticks the same way Intl grouping would, with no compact notation', (locale) => {
+    const formatter = defaultNumericTickFormatter(locale);
+    for (const value of [12500, 998000, 1000000000]) {
+      const expected = new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value);
+      expect(formatter(value, { location: 'tick' })).toBe(expected);
+      // The exact failure mode measured live: compact notation prepending a
+      // wider word in Swahili, or a 'K'/'M'/'B' suffix elsewhere.
+      expect(formatter(value, { location: 'tick' })).not.toMatch(/[KMB]|elfu/i);
+    }
+  });
+
+  it('keeps full precision outside the tick context (tooltip/legend) rather than rounding away a meaningful difference', () => {
+    const formatter = defaultNumericTickFormatter('en');
+    expect(formatter(12500.456, { location: 'tooltip' })).toBe('12,500.456');
+    expect(formatter(12500.456, { location: 'tick' })).toBe('12,500.5');
+  });
+});
+
+// THEME-9 #1/#3 -- MUI's own y-axis width default is a flat 45px (ticks) +
+// 20px (label) regardless of what the ticks actually say (confirmed against
+// @mui/x-charts' own DEFAULT_AXIS_SIZE_WIDTH/AXIS_LABEL_DEFAULT_HEIGHT and
+// its useChartDimensions selector, where margin and axis size are additive).
+// That is both too generous for short ticks and too stingy for wide
+// unit-suffixed ones -- the measured Accessibility-panel overlap. Margins
+// and the exact rendered overlap are verified live, not by unit test (per
+// the WO); this pins the sizing FUNCTION's own contract.
+describe('sizeYAxisForContent (THEME-9)', () => {
+  it('sizes a linear axis from its own caller-supplied min/max', () => {
+    const [axis] = sizeYAxisForContent(
+      [{ scaleType: 'linear', min: 0, max: 1, label: 'Coverage (%)' }],
+      [],
+      '12px',
+    );
+    expect(axis.width).toBeGreaterThan(0);
+  });
+
+  it('reserves more width for a longer formatted tick, all else equal', () => {
+    const [shortTick] = sizeYAxisForContent(
+      [{ scaleType: 'linear', min: 0, max: 1 }], [], '12px',
+    );
+    const [wideTick] = sizeYAxisForContent(
+      [{ scaleType: 'linear', min: 0, max: 1, valueFormatter: (v) => `${v} minutes` }],
+      [], '12px',
+    );
+    expect(wideTick.width).toBeGreaterThan(shortTick.width);
+  });
+
+  it('falls back to the plotted series when the caller sets neither min nor max', () => {
+    const [axis] = sizeYAxisForContent(
+      [{ scaleType: 'linear' }],
+      [{ data: [1, 250000] }],
+      '12px',
+    );
+    expect(axis.width).toBeGreaterThan(0);
+  });
+
+  it('leaves the axis untouched when there is nothing to measure against', () => {
+    const [axis] = sizeYAxisForContent([{ scaleType: 'linear' }], [], '12px');
+    expect(axis.width).toBeUndefined();
+  });
+
+  it('never overrides a caller-supplied width', () => {
+    const [axis] = sizeYAxisForContent(
+      [{ scaleType: 'linear', min: 0, max: 1, width: 42 }], [], '12px',
+    );
+    expect(axis.width).toBe(42);
+  });
+
+  it('leaves a categorical (band/point) axis alone -- its ticks are names, not numbers', () => {
+    const [axis] = sizeYAxisForContent(
+      [{ scaleType: 'band', data: ['a', 'b'] }], [], '12px',
+    );
+    expect(axis.width).toBeUndefined();
+  });
+
+  // Reviewer-caught regression (THEME-9): a series with no explicit
+  // `yAxisId` is NOT "assigned to no axis" -- MUI defaults it to the FIRST
+  // axis in the array (`yAxisIds[0]`), whatever that axis' id is. Matching
+  // only `undefined === undefined` left the primary axis of a genuine
+  // dual-axis chart (id set, series unmarked) with zero matched series and
+  // therefore MUI's untouched flat default -- a silent no-op on exactly the
+  // dual-axis case this WO was measured against (TimeSeriesChart's own
+  // secondary-axis feature, CHART-5).
+  it('assigns an unmarked series to the FIRST axis in a dual-axis array, matching MUI\'s own default', () => {
+    const dualAxis = [{ scaleType: 'linear', id: 'primary' }, { scaleType: 'linear', id: 'secondary' }];
+    const series = [
+      { data: [1, 2, 3] }, // no yAxisId -- MUI assigns this to 'primary'
+      { data: [400000, 500000], yAxisId: 'secondary' },
+    ];
+
+    const [primary, secondary] = sizeYAxisForContent(dualAxis, series, '12px');
+    expect(primary.width).toBeGreaterThan(0);
+    expect(secondary.width).toBeGreaterThan(0);
+    // The secondary axis' series format much wider numbers -- it must
+    // reserve more width than the primary axis, not the same (which is what
+    // "both axes silently untouched" or "both matched the same series" would
+    // produce).
+    expect(secondary.width).toBeGreaterThan(primary.width);
+  });
+});

package/tests/themeCompleteness.test.js

@@ -171,6 +171,21 @@ describe('theme completeness', () => {
       ]),
     );
   });
+
+  it('anchors the select touch target on the input root, not the inner select slot', () => {
+    // THEME-8: a min-height on styleOverrides.select lands on a display:block
+    // element with variant-dependent, top-anchored padding -- the surplus
+    // height collects entirely below the text instead of centring it. The
+    // root is already flex/align-items:center, so anchoring there is what
+    // actually centres the text. A test only checking "44px somewhere" would
+    // pass on the broken version too.
+    const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
+    const selectOverrides = theme.components.MuiSelect.styleOverrides;
+
+    expect(selectOverrides.select?.minHeight).toBeUndefined();
+    expect(selectOverrides.root.minHeight).toBe(40);
+    expect(selectOverrides.root['@media (any-pointer: coarse)'].minHeight).toBe(44);
+  });
 });
 
 describe('kit sx disjointness', () => {

package/work-orders/THEME-7.md

@@ -0,0 +1,82 @@
+# THEME-7 — Guidance: a series slot that collides with an app's own accent
+
+## Part A — Envelope
+
+**Goal.** Give consuming apps a documented answer for the case where a baseline
+`dataSeries.categorical` slot sits too close to something the app itself owns — the app's
+accent, or one of its domain identity colours. Today the baseline offers six series colours
+and no guidance for that collision, so each app rediscovers the problem on its own.
+
+**Why — a measured case, not a hypothesis.** During hram's Imara design-language work
+(hram `IMARA-2`, frozen 2026-08-13) two collisions were measured against the app's own
+values, using Lab ΔE with the operator's own rejected candidate pair as the calibration
+floor (that pair sat at ΔE 16.6 and was judged "not tellable apart"):
+
+- baseline series 1 `#3D5A99` versus hram's chosen primary `#2F4F96` → **ΔE 7.2**, the
+  tightest pair in that app's whole system; a series line beside a primary button reads as
+  the same colour.
+- baseline series 3 `#2E8F8A` versus hram's DALYs identity `#1F7A72` → **ΔE 8.3**; same
+  hue (a −28.7 vs −27.8), one lightness step apart (L 54 vs 46).
+
+hram resolved both app-side: slot 1 dropped entirely (both replacement candidates measured
+worse elsewhere — a neutral slate landed ΔE 5.0 from the shared `stale` fill, a muted green
+ΔE 15.5 from the app's own olive slot), and slot 3 replaced by a navy, which simultaneously
+restored the dark blue the first removal had taken away. The nine remaining slots plus an
+overflow grey covered the app's needs.
+
+**This is not a defect report against the baseline.** For an app whose primary is not a
+muted indigo and which has no teal domain identity, series 1 and 3 are correct and useful.
+What is missing is the *guidance*, and the observation that the baseline's own muted,
+cool-leaning character makes a collision with a tastefully chosen accent more likely rather
+than less — apps that like this palette tend to pick accents from the same region.
+
+**Scope.**
+
+1. `DESIGN.md` — a short subsection under the data-colour principle: how to check a chosen
+   accent against the series palette (measure, do not eyeball; a usable threshold with the
+   calibration above named as its provenance), and what to do when it collides — drop the
+   slot rather than nudge it, because a nudged slot stays confusable while a dropped one is
+   simply absent.
+2. The same note in the theme package's own documentation where `dataSeries.categorical` is
+   described, so it is found by someone reading the token rather than the design doc.
+3. **Decide and record**: whether the baseline should additionally *ship* anything —
+   candidates being an exported ΔE helper apps can assert with, a documented extension
+   sequence for apps needing more than six slots, or nothing at all beyond the guidance.
+   Doing nothing is a legitimate outcome and should be recorded as a decision if chosen.
+
+**Non-goals / do-not-touch.** Do **not** change the six shipped series values — hram's
+divergence is app-specific and other consumers depend on the current set. No change to the
+status palette, the completeness assertion, or any component. This is documentation plus,
+at most, one small additive export.
+
+**Tier 3** — shared-core surface, per the estate tiering table, even though the change is
+documentation-led. Independent review mandatory.
+
+**Tests to write.** None for the documentation. If item 3 lands a helper, that helper gets
+its own unit test with the two measured pairs above as fixtures — they are real values with
+known answers.
+
+**Risks.** The guidance is derived from a single app's experience; state that plainly rather
+than presenting it as a general law. The threshold in particular is calibrated on one
+operator's judgement — useful as a starting point, not as a standard, and it should say so.
+
+## Part B — Implementation map (implementer)
+
+PLACEHOLDER — Orchestrator fills this on `git pull`: context package with `path:line`
+anchors into `DESIGN.md` and the token documentation, the absolute working directory, the
+progress contract, the preamble. Not dispatchable while this stands.
+
+## Part C — Orchestrator only
+
+**STOP — addressee guard.** If you are the implementer reading this file as your own spec:
+this part is not addressed to you. It tells the Orchestrator how to invoke you; you ARE that
+invocation — do not shell out to `codex exec`. Stop reading at this line.
+
+- **Execution.** Codex first per the Tier-2/3 rule unless the status record says otherwise.
+- **Review routing.** `reviewer` mandatory (Tier 3). No `ui_reviewer` unless item 3 turns
+  into code with a visual surface, which it should not.
+- **Verification.** Scoped: the theme package's existing tests must stay green; any new
+  helper carries its own.
+- **Cross-repo.** Reference hram `IMARA-2` and its frozen sheet as the evidence source; do
+  not restate the measurements from memory when the artifact holds them.
+