@medquantis/design-system 1.1.0 → 1.3.0

package/dist/llms-full.txt

@@ -16,12 +16,13 @@ The MedQuantis brand, writing, colour, type, layout, chart, data and accessibili
 | brand.md | Name, tagline, legal line, wordmark, monogram, favicon, icons |
 | voice.md | Tone, words to prefer and avoid, languages, terminology in French, German, Italian and English |
 | writing.md | No em or en dash, titles, sentences and lists, French typography |
-| colour.md | Semantic colour tokens, the medium split, navy panels, states by mark style, status colours in apps |
+| colour.md | Semantic colour tokens, the medium split, navy panels, states by mark style, status colours in apps, the dark theme |
 | typography.md | Families, weights, roles, sizes and line heights |
 | layout.md | Media, report skeleton, widths and spacing, radius, components, tables, app patterns, print |
 | charts.md | The ordered palette, highlight on grey, sequential and diverging use, marks, legends |
 | data-patterns.md | Numbers, amounts, dates, null versus zero, confidential and illustrative data |
 | accessibility.md | WCAG 2.2 AA, contrast pairs, focus, targets, motion, structure |
+| app-patterns.md | Apps only: the app shell, and the review, decision and history patterns of dense internal tools |
 | specialising.md | Framework neutrality, the four rules, the promotion tests, the one-off log |
 
 The values themselves live in `tokens/` and reach these pages as `--mq-*` names; when a guideline and a token disagree, the token is right and the guideline is fixed. The generated specimen (`make specimen`) is the visual reference: when a rendering is in doubt, it decides.
@@ -84,6 +85,8 @@ Set it in Geist Mono at the note size, tertiary text colour (`--mq-tertiary`), w
 
 On slides the legal line appears on every slide, bottom left, small and in tertiary grey, with the slide number bottom right (owner ruling 11). Use the slide footer row `mq-slide-foot` of `css/slide.css`, never `mq-foot`, which flows from the top of a slide canvas.
 
+A deck that carries a classification shows it at the right of the footer, before the slide number, in the same small tertiary mono (owner ruling 17, amending ruling 11's two-cell footer). It is the label only, in the deck's language (Confidential in an English deck, Confidentiel in a French one), never the C0 to C3 code. A kit deck takes it from its `classification:` and `lang:`.
+
 Material left with a reader (a deck after a meeting, a report sent outside) also carries a confidentiality mention and its date, in the document's language:
 
 | Medium | French | German | English | Italian |
@@ -93,7 +96,7 @@ Material left with a reader (a deck after a meeting, a report sent outside) also
 
 ## Wordmark
 
-The wordmark is the logo; no icon is required next to it. "Med" is set in Outfit 600 and "Quantis" in Outfit 300, in navy (`#0a2463`) on light backgrounds and in white on navy, at every size (owner ruling 6).
+The wordmark is the logo; no icon is required next to it. "Med" is set in Outfit 600 and "Quantis" in Outfit 300, in navy (`#0a2463`) on light backgrounds and in white on navy and on every dark surface, at every size (owner rulings 6 and 14).
 
 Each background has two files in `brand/`:
 
@@ -105,6 +108,7 @@ Each background has two files in `brand/`:
 Rules:
 
 - Use the on-navy file on navy and the on-light file on light backgrounds. Never recolour, stretch, outline, shadow or rearrange the wordmark.
+- On dark (the dark theme, a dark slide or page), use the white `wordmark-on-navy` files on every dark surface: 18.13:1 on the dark canvas, 16.08:1 on the dark surface. The navy wordmark is never used on dark: it is 1.25:1 there (owner ruling 14).
 - Inline the SVG rather than linking an external image, and remove its `width` and `height` so the page sizes it. On a report header the wordmark sits at about 198 by 44 px on screen and 162 by 36 px in print.
 - A full stop in the on-navy accent (`--mq-on-navy-accent`) after a name is reserved for a one-word name on a navy cover. It is never added to the wordmark.
 
@@ -119,6 +123,8 @@ Where the wordmark does not fit (favicon, app icon, avatar, app tile), use the m
 | `brand/monogram-small.svg` | 16 px and smaller: larger letters, M 800 and Q 600 |
 | `brand/favicon/` | `favicon.svg`, `favicon.ico` (16, 32, 48), `apple-touch-icon.png` (180), `icon-192.png`, `icon-512.png` |
 
+On dark (owner ruling 14) the monogram keeps its file and takes the navy panel's edge, the 1 px light-navy outline that `--mq-shadow-panel` draws in the dark theme, since its navy square is only 1.11:1 against the dark surface; in light it has no outline. A navy brand tile or app tile on dark takes the panel gradient (`--mq-panel-start` to `--mq-panel-end`), never the lifted accent, on which white is 3.48:1. No new brand file is needed.
+
 ## No combined logo yet
 
 There is no lockup of the monogram and the wordmark in v1, and no on-navy variant of the monogram. Do not compose one locally: the combined logo is deferred until a real surface needs it ([issue #2](https://github.com/MedQuantis/design-system/issues/2)). Older lockups with a strapline under the wordmark are retired.
@@ -224,7 +230,7 @@ Use semantic tokens only. The `--mq-core-*` names hold raw values and exist so s
 | Medium | Colours allowed | How a state is shown |
 | :-- | :-- | :-- |
 | Documents: slides, A4 reports, papers, newsletters, the website | Navy, the neutrals, the blue-grey family, the chart tokens | By mark style: solid, ring, pale, outline, quiet, dashed, struck through |
-| Interactive apps | Everything documents use, plus `--mq-success`, `--mq-warning`, `--mq-danger`, `--mq-info` | Status colour for genuine system status only (errors, validation, alerts, confirmations), always with an icon or a word |
+| Interactive apps | Everything documents use, plus `--mq-success`, `--mq-warning`, `--mq-danger`, `--mq-info`, and the app categorical palette with its change types (charts) | Status colour for genuine system status only (errors, validation, alerts, confirmations), always with an icon or a word; a categorical hue for a data category only, always with a label, a sign or a word |
 
 Documents never carry green, orange, red, sky blue, pink, purple or turquoise, not even to say good or bad (ADR-0004). They never load `css/app.css`. A callout in a document is always navy; there is no warning-orange or success-green callout.
 
@@ -237,12 +243,13 @@ Documents never carry green, orange, red, sky blue, pink, purple or turquoise, n
 | `--mq-accent-pale` | `#eaeef7` | Icon pills and chips, a deviating value, the highlighted table row, the pale state |
 | `--mq-accent-pale-2` | `#f2f4f9` | Progress tracks, the quiet state, callout background |
 | `--mq-on-accent` | `#ffffff` | Text and icons on an accent fill (14.53:1) |
+| `--mq-accent-highlight` | `#0a2463` | Accent text on the pale fills (the pale KPI value, the pale badge, the callout title) and large highlighted title text: the accent itself in light, the light navy on dark (owner ruling 18) |
 
 Navy carries emphasis on its own. Status colours never replace it for emphasis, in any medium.
 
 ## Neutrals
 
-The neutrals are warm greys tuned to the warm canvas, never blue-tinted greys.
+In the light theme the neutrals are warm greys tuned to the warm canvas, never blue-tinted greys; the neutrals of the dark theme carry the navy cast of its canvas (Dark theme).
 
 | Token | Value | Use | Contrast |
 | :-- | :-- | :-- | :-- |
@@ -300,7 +307,7 @@ The first six are the `mq-badge` states (`is-solid`, `is-ring`, `is-pale`, `is-o
 | `--mq-danger` | `#d8232a` | Errors, destructive actions | 5.01:1 on surface, 4.79:1 on canvas |
 | `--mq-info` | `#1565c0` | Information | 5.75:1 on surface, 5.50:1 on canvas |
 | `--mq-warning` | `#a06400` | Warning text, icons and borders | 4.86:1 on surface, 4.65:1 on canvas |
-| `--mq-warning-fill` | `#d4850a` | Warning badge or highlight fill, always with ink text (5.93:1) | Fill only |
+| `--mq-warning-fill` | `#d4850a` | Warning badge or highlight fill, always with its text role `--mq-on-warning-fill`, ink in light (5.93:1) | Fill only |
 | `--mq-warning-tint` | `#fbf3e7` | Warning background behind ink text (15.81:1) | Fill only |
 
 The warning split (owner ruling 5): the orange `#d4850a` is a fill and never text, an icon or a border (2.81:1 on canvas). Text on it is ink; white on it is forbidden (2.93:1). On the warning tint, the text stays ink and `--mq-warning` is used only for the icon and the border (4.42:1, non-text).
@@ -312,12 +319,93 @@ Every status colour comes with an icon or a word (WCAG 1.4.1):
 - a flag is a coloured word, and only on the rows that need attention, so normal rows stay quiet;
 - light badge backgrounds come from the 50 and 100 steps of the status scales in `dist/tailwind.css`, never a hand-picked tint.
 
-The red of the old Paracel theme survives only as `--mq-danger` (ADR-0003). App-specific hues, such as the annotation colours of regulatory text, stay local in the app under its own prefix until a second consumer needs them (specialising).
+The red of the old Paracel theme survives only as `--mq-danger` (ADR-0003). The app categorical palette and the change types (`--mq-app-cat-*`, `--mq-change-*`) are data categories, never statuses; their values and rules are in charts (ADR-0008). Other app-specific hues, such as the annotation colours of regulatory text, stay local in the app under its own prefix until a second consumer needs them (specialising).
 
 ## Chart colours
 
 The chart tokens (`--mq-chart-series-1` to `--mq-chart-series-4`, `--mq-chart-rest`, `--mq-chart-axis`, `--mq-chart-baseline`) and their order are in charts.
 
+## Dark theme
+
+MedQuantis has one dark theme (ADR-0007, owner ruling 12). It re-values the semantic roles above under the `.dark` class: a role it does not name keeps its light value, and no component needs a second name. A consumer opts in by loading `themes/dark.css` of the package after `tokens.css` and setting `.dark` on `<html>` or on one slide. The design system never switches on `prefers-color-scheme` by itself.
+
+- **Apps and the website:** light and dark; the app decides how the viewer chooses, and may follow the viewer's setting by toggling `.dark`.
+- **Documents** (A4 reports, papers, PDFs): light or dark, chosen by the author per document at build time, never from the reader's screen (owner ruling 15). A dark document stays dark in its PDF; light stays the default for anything likely to be printed on paper.
+- **Slides:** a whole deck, or a single slide carrying `.dark`.
+
+Every ratio below is the WCAG 2.x contrast with the dark values, on the dark canvas `#11161f` and surface `#1a2131`; the token test checks every declared pair in both themes.
+
+| Token | Dark value | Use | Contrast |
+| :-- | :-- | :-- | :-- |
+| `--mq-canvas` | `#11161f`, a near-black with a navy cast | Background of every dark page and slide | Background |
+| `--mq-surface` | `#1a2131` | Cards, panels, tables, figures, inputs | Background |
+| `--mq-surface-alt` | `#141a26` | Recessed areas: table headers, grouped areas | Background |
+| `--mq-desk` | `#0b0f16` | On screen only, around a dark page preview | Background |
+| `--mq-border` | white at 14 % | Borders, dividers | Decorative |
+| `--mq-border-light` | white at 10 % | Hairlines, card borders | Decorative |
+| `--mq-border-strong` | `#8795b3` | Outline of outlined and dashed state marks | 6.03:1 on canvas, 5.35:1 on surface, non-text |
+| `--mq-ink` | `#f5f4f1`, warm white | Primary text and values | 16.48:1 on canvas, 14.62:1 on surface |
+| `--mq-muted` | `#c3cbdc` | Secondary text, leads, captions | 11.13:1 on canvas, 9.88:1 on surface |
+| `--mq-tertiary` | `#8f98aa` | Tertiary text: notes, footers, axis labels | 6.25:1 on canvas, 5.54:1 on surface |
+| `--mq-decoration` | `#6b7385` | Non-text decoration only, never text | 3.81:1 on canvas, 3.38:1 on surface, non-text |
+| `--mq-accent` | `#6f88c9`, the lifted navy | Links, labels, key figures, active states | 5.22:1 on canvas, 4.63:1 on surface, 5.01:1 on the recessed surface |
+| `--mq-accent-hover` | `#8aa0d6` | Hover and pressed state of a link or an accent control | 6.98:1 on canvas |
+| `--mq-accent-pale` | the lifted navy at 18 % | Icon pills and chips, the highlighted row, the pale state | Fill |
+| `--mq-accent-pale-2` | the lifted navy at 10 % | Progress tracks, the quiet state, callout background | Fill |
+| `--mq-accent-highlight` | `#9fb3e8`, the light navy | Large highlighted title text, and accent text on the pale fills: the pale KPI value, the pale badge and the callout title (owner ruling 18) | 8.71:1 on canvas, 7.73:1 on surface, 5.97:1 on the pale fill, 6.77:1 on the quiet pale fill |
+| `--mq-on-accent` | `#11161f` | Text and icons on an accent fill, never white (white 3.48:1 on the accent) | 5.22:1 on the accent |
+| `--mq-focus-ring-color` | `#9fb3e8`, the light navy | Focus ring on dark backgrounds | 8.71:1 on canvas |
+| `--mq-panel-start` | `#2f4c8f` | Light end of the navy panel gradient | Background, white 8.23:1 on the panel start |
+| `--mq-panel-end` | `#0f2a5e` | Dark end of the navy panel gradient | Background |
+| `--mq-shadow-panel` | a 1 px outline, light navy at 35 %, no glow (owner ruling 13) | Navy panels, the report header and the navy KPI tile on dark | Edge of a panel |
+| `--mq-shadow-edge` | the same 1 px outline, light navy at 35 %; none in light | The monogram (`mq-monogram`), the navy KPI tile and a navy brand or app tile, which draw no shadow in light (owner ruling 14) | Edge of a navy mark |
+| `--mq-shadow-live` | a 3 px ring of the dark success green `#6fbf73` at 17 %; in light the success green at 17 % | Apps only: the halo of a live dot, the row in force on a timeline (app patterns) | Decorative |
+| `--mq-shadow-small` | black at 40 %, 1 px down with a 2 px blur | Cards, figures and tables on dark, where the light 5 % shadow does not show | Elevation |
+| `--mq-shadow-medium` | black at 50 %, 3 px down with a 12 px blur | A slide or page previewed on the dark desk, raised panels and menus | Elevation |
+
+Accent text on the pale fills reads `--mq-accent-highlight` in both themes (owner ruling 18): in light it is the accent itself, while on dark the lifted navy would be only 3.57:1 on the pale fill and 4.05:1 on the quiet pale fill. The fills are measured laid over the canvas and over the surface, the worse result counting. The callout tab keeps `--mq-accent` on the quiet pale fill as a non-text mark.
+
+The retired `--mq-dim` and `--mq-accent-on-dark` follow the roles they alias on dark too: `#8f98aa` (tertiary) and `#b2c2ed` (the on-navy accent).
+
+**The navy panel on dark.** Navy itself fails on a dark canvas (`#0a2463` is 1.25:1 on `#11161f`), so on dark the brand shows as the lifted navy, the light navy and the panel gradient, with no new hue (ADR-0003). Navy panels, the report header and the navy KPI tile keep the 160 degree gradient between `--mq-panel-start` and `--mq-panel-end`, with the dark values above, and draw `--mq-shadow-panel`: a 1 px light-navy outline, never a glow (owner ruling 13). A navy tile on dark takes the panel gradient, never the lifted accent. Contrast on navy is still checked against the panel start, the lighter stop.
+
+The on-navy tier on the dark panel (owner ruling 19): two roles take dark values, the others keep their light values and are checked again on the lighter dark panel start.
+
+| Token | Dark value | Contrast | Allowed for |
+| :-- | :-- | :-- | :-- |
+| `--mq-on-navy-title` | `#ffffff`, unchanged | 8.23:1 on the panel start | Text |
+| `--mq-on-navy-secondary` | white at 68 %, unchanged | 4.80:1 on the panel start | Text |
+| `--mq-on-navy-second-level` | `#c3cbdc`, unchanged | 5.05:1 on the panel start | Text |
+| `--mq-on-navy-accent` | `#b2c2ed`, a lighter navy tint | 4.64:1 on the panel start | Text, narrow margin |
+| `--mq-on-navy-discreet` | white at 50 % | 3.37:1 on the panel start | Large text or non-text only |
+| `--mq-on-navy-rule`, `--mq-on-navy-rule-strong`, `--mq-on-navy-pill` | white at 16, 18 and 12 %, unchanged | Decorative | Decorative only |
+
+Light keeps `#8795b3` (4.61:1) and white at 40 % (3.44:1) for those two roles; on the dark panel start they would fall to 2.74:1 and 2.71:1.
+
+**The light navy is a navy tint.** `#9fb3e8` (`--mq-accent-highlight`, `--mq-focus-ring-color`, dark series 1) is not the retired sky blue: its LCH hue 280.4 (chroma 29.2) sits in the navy family with the lifted navy `#6f88c9` (hue 282.8), against navy 293.7 and sky blue 269.9 (chroma 36.1). Sky blue stays retired in both themes (owner ruling 2).
+
+Status colours on dark, apps only (ADR-0004, owner ruling 16), each still with an icon or a word; `--mq-warning-fill` keeps its value and stays a fill:
+
+- `--mq-success` `#6fbf73`: 8.09:1 on canvas, 7.18:1 on surface.
+- `--mq-warning` `#e0a040`: 8.00:1 on canvas, 7.10:1 on surface.
+- `--mq-danger` `#ff6b6b`: 6.53:1 on canvas, 5.80:1 on surface.
+- `--mq-info` `#64a8f0`: 7.25:1 on canvas, 6.43:1 on surface.
+- `--mq-warning-fill` `#d4850a`, unchanged: a fill, never text.
+- `--mq-warning-tint`, the warning fill at 16 %: ink 11.63:1 on the warning tint.
+- `--mq-on-warning-fill` `#11161f`, text on `--mq-warning-fill`: 6.18:1 on the warning fill, where the warm white ink 2.67:1 on the warning fill would fail.
+
+Chart colours on dark (owner ruling 16): the four series run in reverse order, the lightest first, under the same rules as light (charts): series 4 for context bars, the remainder drawn with a series 4 outline. Each dark series meets or beats its light counterpart against its canvas.
+
+| Token | Dark value | Contrast |
+| :-- | :-- | :-- |
+| `--mq-chart-series-1` | `#9fb3e8` | 8.71:1 on canvas |
+| `--mq-chart-series-2` | `#6f88c9` | 5.22:1 on canvas |
+| `--mq-chart-series-3` | `#5d6f91` | 3.58:1 on canvas |
+| `--mq-chart-series-4` | `#3a4560` | 1.90:1 on canvas, context bars only |
+| `--mq-chart-rest` | `#232b3d` | 1.28:1 on canvas, with a series 4 outline |
+| `--mq-chart-axis` | `#6b7385` | 3.81:1 on canvas, non-text |
+| `--mq-chart-baseline` | white at 10 % | Decorative |
+
 # Typography
 
 ## Three families, three roles
@@ -401,7 +489,7 @@ Apps use the same families and weights at UI sizes: UI body Outfit 400 at 14 px,
 
 | Medium | Canvas | Layout |
 | :-- | :-- | :-- |
-| Slide | 1280 by 720 px (`--mq-slide-width`, `--mq-slide-height`, `css/slide.css`) | Fixed canvas, 72 px side margins (`--mq-space-8`), section label top left, title under it, and a footer row (`mq-slide-foot`) with the legal line bottom left and the slide number bottom right, both in tertiary mono (owner ruling 11) |
+| Slide | 1280 by 720 px (`--mq-slide-width`, `--mq-slide-height`, `css/slide.css`) | Fixed canvas, 72 px side margins (`--mq-space-8`), section label top left, title under it, and a footer row (`mq-slide-foot`) with the legal line bottom left and the slide number bottom right, both in tertiary mono (owner ruling 11); a classified deck adds its classification label at the right of the footer, before the slide number (owner ruling 17) |
 | Screen report or paper | A page that scrolls, centred, `--mq-page-width` (1040 px) wide | Flow layout: no absolute positions, no fixed heights. It is not a deck: no slide canvas inside a report |
 | A4 print | 210 by 297 mm (`--mq-a4-width`, `--mq-a4-height`, `css/print.css`) | One `mq-page` per sheet on the canvas colour; on screen the pages sit on the desk |
 
@@ -450,7 +538,7 @@ Squared-off corners read professional and institutional; pills read consumer.
 
 ## Elevation and navy blocks
 
-- Cards, figures and tables: `--mq-shadow-small`. Raised panels, menus and a page or slide previewed on the desk: `--mq-shadow-medium`. Navy panels: `--mq-shadow-panel`. No shadow in print and none on chart marks.
+- Cards, figures and tables: `--mq-shadow-small`. Raised panels, menus and a page or slide previewed on the desk: `--mq-shadow-medium`. Navy panels: `--mq-shadow-panel`, which on dark is a 1 px light-navy outline and never a glow (owner ruling 13). No shadow in print and none on chart marks.
 - One large navy block per screen, slide or page area. In a report, keep the header, a navy KPI band and a navy panel apart with light content.
 
 ## Document components
@@ -464,7 +552,7 @@ Squared-off corners read professional and institutional; pills read consumer.
 | Takeaway | `mq-takeaway` | The one sentence to remember, under a navy tab, Outfit 500 |
 | Numbered rows | (pattern) | A navy circle with the number, a heading column, a body column: one line per point |
 | Footer | `mq-foot` | Sources and legal line in tertiary italic, in reports and papers; never inside a slide |
-| Slide footer | `mq-slide-foot` | On every slide (owner ruling 11): the legal line bottom left, the slide number bottom right, small, tertiary, Geist Mono: `<footer class="mq-slide-foot"><p>MedQuantis SA · CH-1095 Lutry · medquantis.ch</p><p class="mq-slide-number">03</p></footer>` |
+| Slide footer | `mq-slide-foot` | On every slide (owner ruling 11): the legal line bottom left, the slide number bottom right, small, tertiary, Geist Mono. A classified deck shows its classification at the right of the footer, before the slide number: the label in the deck's language, never the C0 to C3 code (owner ruling 17). Without a classification: `<footer class="mq-slide-foot"><p>MedQuantis SA · CH-1095 Lutry · medquantis.ch</p><p class="mq-slide-number">03</p></footer>` |
 
 ## Tables
 
@@ -508,7 +596,7 @@ One column, a 16 px gutter, and no horizontal scrolling of the page. Only tables
 
 # Charts
 
-Charts use the navy and blue-grey family only, in every medium. Status colours never colour a chart series, not even in an app; a chart that shows system status labels it in words.
+Charts use the navy and blue-grey family, in every medium. An interactive app may also use the app categorical palette, for a chart of more categories than the ordered palette carries and for data categories such as change types; documents never do (ADR-0008). Status colours never colour a chart series, not even in an app; a chart that shows system status labels it in words.
 
 ## The ordered palette
 
@@ -543,6 +631,38 @@ Rules:
 | Ranking with more than four items | Highlight on grey, below |
 | Workflow stages in an app | Series 1 to 4 with the stage name as a label or legend, never status hues, never white text on series 3 or 4 |
 
+## App categorical palette (apps only)
+
+Six hues for interactive apps whose charts or lists show more categories than the four ordered series can carry, and three change types built on them (owner rulings 20 and 21, ADR-0008). They are light only until their dark values are ruled, and they never appear in documents, which keep the ordered palette.
+
+| Token | Value | Contrast on surface | Allowed for |
+| :-- | :-- | :-- | :-- |
+| `--mq-app-cat-green` | `#1c7e3f` | 5.12:1 | Marks, fills and text |
+| `--mq-app-cat-orange` | `#d78000` | 3.01:1 | Marks and fills only |
+| `--mq-app-cat-orange-text` | `#a35f00` | 5.01:1 | Text in the orange hue: counts and labels |
+| `--mq-app-cat-vermillion` | `#cf2a00` | 5.27:1 | Marks, fills and text |
+| `--mq-app-cat-blue` | `#3a8ff5` | 3.27:1 | Marks and fills only |
+| `--mq-app-cat-violet` | `#5a2fbe` | 8.12:1 | Marks, fills and text |
+| `--mq-app-cat-teal` | `#178a91` | 4.13:1 | Marks and fills only |
+
+| Change type | Token | Reads |
+| :-- | :-- | :-- |
+| Added | `--mq-change-added` | The green |
+| Modified | `--mq-change-modified`; its text `--mq-change-modified-text` | The orange; the orange text |
+| Removed | `--mq-change-removed` | The vermillion |
+
+Between the six hues and navy series 1, the smallest CIEDE2000 distance is 17.4 under normal vision, 11.9 under protanopia, 12.9 under deuteranopia and 8.4 under tritanopia (green and teal); the token test holds those floors.
+
+Rules:
+
+- A one-series chart stays navy (`--mq-chart-series-1`). Up to four series, the ordered palette applies in apps too; the categorical hues are for charts of five or more categories and for data categories.
+- Fix each hue to its category across every view of the app; never let a charting library rotate through the palette.
+- No series uses a status token. The vermillion is a data category ("removed from the list"), not an error: `--mq-danger` stays for errors. The green, the orange, the orange text and the vermillion sit CIEDE2000 3.3, 2.2, 2.8 and 7.9 from `--mq-success`, `--mq-warning-fill`, `--mq-warning` and `--mq-danger`, so code tells them apart by token name and the screen by the word or sign each carries, never by hue.
+- Marks sit on the surface (`--mq-surface`), where every hue meets 3:1 and needs no outline. On the canvas the orange falls to 2.88:1, and on the recessed surface the orange and the blue fall below 3:1, so a chart in these hues sits in a white card.
+- Text in a hue meets 4.5:1: the green, the vermillion and the violet may be text, orange text reads `--mq-app-cat-orange-text`, and the blue and the teal are never text.
+- Never colour alone: the green and the vermillion have almost the same lightness, so in greyscale they cannot be told apart. Every mark carries a direct label or a legend entry, and a change type its sign (+, −) or its word; label the green and the teal directly where they touch.
+- A change type keeps its hue wherever a change is listed (badge, dot, filter, count) and keeps its mark style on top: an added value with +, a removed value struck through.
+
 ## Highlight on grey
 
 To point at one item among many (a ranking, one insurer among peers), draw the item the text discusses in series 1 and every other item in series 3. When the context should recede further, such as a reference period behind the current one, use series 4. Label the highlighted item directly; the others need a label or an outline because series 3 and 4 are below 3:1.
@@ -663,7 +783,8 @@ Colour never carries meaning on its own (WCAG 1.4.1):
 - documents show states by mark style (solid, ring, pale, outline, quiet, dashed, struck through) and a page that uses these marks gives their key once, in a legend or a note;
 - apps pair every status colour with an icon or a word;
 - charts label the marks that use series 3 or 4, or give them an outline, since those colours are below 3:1 on the page (charts);
-- a change in a figure is shown by its sign, not by a colour or an arrow alone.
+- a change in a figure is shown by its sign, not by a colour or an arrow alone;
+- in apps, a mark in the app categorical palette carries a direct label, a legend entry, a sign or a word, since two of its hues share their lightness (charts).
 
 ## Contrast pairs
 
@@ -713,6 +834,288 @@ Placeholder text in inputs uses the tertiary text colour, never a lighter grey.
 - Icons that carry meaning have a label; decorative icons are hidden (`aria-hidden="true"`).
 - PDFs exported from HTML are tagged and carry an outline (Playwright `tagged` and `outline`); the specimen test exports one.
 
+# App patterns
+
+Patterns for dense interactive apps (internal review and operations tools) built on the tokens. They describe anatomy, states and the tokens each part reads; the framework components that draw them belong to the app (specialising). Every pattern here is for the app medium only.
+
+## App shell
+
+One frame for every screen of the app: a left sidebar, then a main panel that stacks an optional environment banner, a navbar, a toolbar and the content. The content scrolls inside the panel; the sidebar, banner, navbar and toolbar stay in place.
+
+**Sidebar.** On the surface (`--mq-surface`) with a `--mq-border-light` hairline on its right edge, `--mq-sidebar-width` wide.
+
+- Brand block at the top: the wordmark, and under it the product name in muted Outfit 500 at the label size. The block keeps one height expanded or collapsed, so the toggle below it never moves.
+- Navigation in groups. A group opens with an eyebrow in tertiary text; the first group may have none. Each link carries a Lucide icon in `--mq-decoration`, its label in muted Outfit 500, and an optional count at the right in Geist Mono, tertiary. Hover: ink on `--mq-surface-alt`. The current page (`aria-current="page"`): navy text and icon on `--mq-accent-pale`, its count navy.
+- A count shows only when it is above zero. A count that asks for the person's action (what waits for them) is a filled badge, `--mq-on-accent` on `--mq-accent`, Geist Mono 600, with the small radius: never a pill. Every other count stays plain text.
+- The signed-in person at the foot, in a block on the canvas with a `--mq-border-light` border and the medium radius: a round avatar with initials (`--mq-on-accent` on `--mq-accent`), the name, the roles as small mono chips (a role not held is struck through in tertiary), and the session line in muted text, such as "Session open · expires after 8 h of inactivity". Sign-out opens from the name.
+- A toggle on the sidebar's edge collapses and expands it. It carries `aria-expanded` and an accessible name that says the action (expand the navigation, collapse the navigation).
+
+**Rail.** The collapsed sidebar, `--mq-sidebar-rail-width` wide. The monogram replaces the wordmark; links become icons alone, centred in 40 by 36 px targets, each label moving to the link's tooltip and accessible name; groups are separated by a hairline instead of their eyebrow; the person shows as the avatar alone. The only count kept is the action badge, at the icon's top right.
+
+**Environment banner.** Above the navbar on every environment except production, an unknown environment included, never on production. One line of ink text at the label size, Outfit 500, on `--mq-warning-tint`, with a `--mq-warning-fill` bottom border and a `--mq-warning` icon, as a `status` region. It is genuine system status, so it takes the warning colours (colour).
+
+**Navbar.** On the surface with a hairline below: a screen icon (a white Lucide icon on a 32 px navy tile with the medium radius), the page title as the page's `h1` in Outfit 500 at the h3 size, and a one-line subtitle in muted text at the label size. Global actions, such as search, sit at the right.
+
+**Toolbar.** On the canvas with a hairline below: the screen's filters in one row that wraps, a flexible gap, then right-aligned controls. Each screen fills it; a screen without filters leaves it out.
+
+**Spacing.** Side padding `--mq-space-6`, `--mq-space-4` on phones, plus the device's safe-area inset.
+
+| State | What changes |
+| :-- | :-- |
+| Expanded | The full sidebar |
+| Rail | As above; the app may start on the rail and keep the person's choice |
+| Drawer, below 768 px | The sidebar leaves the layout. A menu button at the left of the navbar opens it in full over the content, with `--mq-shadow-medium`; it closes on a link, on Escape and on a tap outside. The edge toggle is hidden |
+| Phone, below 480 px | The navbar's subtitle and screen icon are hidden |
+| Service unavailable | The shell stays. Counts are hidden, never shown as 0, since a count that could not be measured is missing, not zero (data patterns); the content shows the error state |
+| Not production | The environment banner shows |
+
+The drawer slides in within 200 ms and appears at once under `prefers-reduced-motion`.
+
+Stays in the app: the routes and their grouping, the count values and which count asks for action, the session and its timeout, the environment and where it comes from, and the search.
+
+## Sign-in, access refused and error pages
+
+Three ways the app answers a person it cannot serve yet. None of them ever falls back to a framework's default page.
+
+**Sign-in page.** The only page served without a session, so it carries no app bundle: a self-contained page built from `tokens.css` and `fonts.css` alone, on the canvas, centred both ways.
+
+- The wordmark above one card: the surface, a `--mq-border-light` border, the medium radius, `--mq-shadow-small`, `--mq-space-6` padding, at most 420 px wide. The wordmark is not a link, since nothing behind it is reachable yet.
+- In the card, in order: an eyebrow in tertiary mono ("Restricted access"), the product name as the `h1`, one muted sentence on what the tool is for, an optional notice, then the one action: a full-width primary button with a sign-in icon ("Sign in with MedQuantis"), and under it a muted hint at the label size naming the account to use and the role the app asks for.
+- The legal line under the card, in tertiary Geist Mono (brand).
+- One action only: no second link, no password reset, no sign-up, which belong to the identity provider.
+
+| Arrival | Notice above the button |
+| :-- | :-- |
+| First visit | None |
+| After the session expired | An info notice as a `status` region: an `--mq-info` icon and border, the sentence in ink, such as "Your session expired. Sign in to pick up where you left off." |
+| After sign-out | A success notice the same way with `--mq-success`, such as "You are signed out." |
+
+After sign-in the person lands on the page they asked for, never on a default home.
+
+**Access refused page.** For a signed-in person whose account lacks the role the app needs. It replaces the shell, since every page behind it would refuse again: a navbar with the monogram and the product name only (no sidebar, no link into the app), then one card at most 560 px wide.
+
+- A navy icon pill (`--mq-accent-pale`, the medium radius) with a lock icon, the title as the `h1` ("Access refused"), a lead sentence in Outfit 500 naming the missing role in bold, and one muted sentence explaining it.
+- A key-value block on the canvas with a `--mq-border-light` border and the medium radius: the signed-in account (avatar, name, address in mono), then the role asked for as a struck-through role chip, beside "Not assigned to this account" in `--mq-danger` with an icon.
+- How to get the role, in muted text: who assigns it, and that the person signs in again once it is assigned.
+- One primary action, "Switch account": it signs out of the app and of the identity provider, then opens the sign-in page in its signed-out state, and a note under the button says so. Never a redirect back into the app, which would loop.
+
+**Error states inside the shell.** When a screen cannot show its content, the shell stays (sidebar, and the navbar with the screen's own title) and one card takes the content area: centred, at most 560 px wide, on the surface with `--mq-shadow-small`, its text centred. In order: a 40 px icon tile with the medium radius, a status word in Geist Mono capitals at the eyebrow size, the title as an `h2` at the h3 size, one muted sentence no wider than 50 characters, and the actions.
+
+| State | Icon tile | Status word | Body and actions |
+| :-- | :-- | :-- | :-- |
+| Not found (404) | `--mq-decoration` icon on `--mq-surface-alt` | "Not found", tertiary | What was not found and why that may be, the address asked for in tertiary mono, and a primary action back to the list |
+| Service unavailable (503) | `--mq-warning` icon on `--mq-warning-tint` | "Unavailable", `--mq-warning` | That the service does not answer for now, and a primary "Retry". While it retries, the button is disabled with a turning icon; if the service is still down, a muted line under it gives the time of the last attempt ("Still unavailable at the last attempt, at 14:32") in a polite live region. The sidebar's counts are hidden (app shell, above) |
+| Unexpected error (500) | `--mq-danger` icon on `--mq-surface-alt` | "Error", `--mq-danger` | That the request failed and what to do if it happens again; the request ID as selectable mono text in a bordered row labelled `X-Request-Id`, with a "Copy" button that confirms once ("Copied"); a secondary action back to the list |
+
+The status word and the icon carry each state together with its colour, never the colour alone (accessibility). Under `prefers-reduced-motion` the icon does not turn and the button reads "Retrying".
+
+Stays in the app: the sign-in address and its return path, the role name and who assigns it, the request ID value, and the wording of each state.
+
+## Overview: queue boxes and coverage cards
+
+The overview lands a person on what waits for them, then shows how much of each area is covered, in one grammar for every area.
+
+**Queue boxes.** A row of boxes, one per queue, three across and one column on phones. Each box is a link to its list: the surface, a `--mq-border-light` border, the medium radius and `--mq-shadow-small`, `--mq-space-4` padding; on hover the border turns `--mq-border-strong`. In order:
+
+- the queue's name in Outfit 600, with its total at the right in navy Outfit 500 at the figure size, in tabular figures;
+- optionally one line per area, its name in ink and its count in navy at the right;
+- the age line in tertiary text at the note size: "Oldest waiting for 3 days", the duration in ink.
+
+| State | Shows |
+| :-- | :-- |
+| Zero | The box stays in place, quiet: the total in tertiary, no area lines, and the age line reads "Nothing waits" |
+| The person's own queue, above zero | A navy border and the pale navy fill (`--mq-accent-pale`); the same box at zero is quiet like the others |
+| Overdue | The age turns `--mq-warning` and takes a warning icon, so the state never rests on colour alone. The threshold belongs to the app |
+| Loading | The box keeps its size with skeleton bars on `--mq-surface-alt`; their shimmer stops under `prefers-reduced-motion` |
+
+**Coverage cards.** One card per area, three across, one column below 1100 px; the same card as a queue box but not a link itself. In order:
+
+- the area's title in Outfit 600, with an "Open →" link at the right in navy;
+- the scope in Geist Mono capitals at the eyebrow size, tertiary: what is counted and over which editions ("Coverage of 1'248 texts · every edition served");
+- a segmented bar, 12 px high, its ends rounded with the small radius, never a pill, with 2 px gaps between segments (charts, distribution bar);
+- the legend under it: per segment a 10 px swatch with the small radius, the label (a link when the segment opens a list), the count in Geist Mono, muted, and the percentage in Geist Mono, tertiary, both right-aligned;
+- optionally one take-away line in muted text at the note size.
+
+Rules for the bar:
+
+- The segments take the ordered palette in order, `--mq-chart-series-1` to `--mq-chart-series-4`, and what is left (not yet detected, not yet extracted) takes the remainder fill `--mq-chart-rest`, with a series 4 outline in the bar and the swatch. Five segments therefore need no new hue. A status colour never colours a segment: a segment that needs attention says so in its label.
+- A segment below 1 % keeps a 2 px minimum width in the bar, and its legend line reads "< 1 %"; every other percentage is rounded with the largest-remainder method (data patterns).
+- A segment that opens a list is a link in both the bar and the legend, with the same accessible name; one that opens nothing is plain text, never a dead link.
+- The bar has an accessible name that states the scope; the legend carries every value in text.
+- One edition or every edition served: the scope line says which; the card does not change shape.
+
+Stays in the app: the segment keys, their counts and labels, which segments link where, the overdue threshold, and the queues themselves.
+
+## Review table: filters, condition tile, status pill, code chips
+
+The list behind every review screen: a filter toolbar, then a table whose rows carry a condition tile, a status pill and code chips. It extends the app table of layout, Tables.
+
+**Filters**, in the shell's toolbar (app shell, above):
+
+- **Select with its label inside**: 32 px high, the surface, a `--mq-border` border, the small radius; the label in muted text, the value in ink Outfit 500. Each option ends with its count, and an option whose count is zero is muted but still listed.
+- **Segmented control** for a filter in two steps: a track on `--mq-surface-alt` with a `--mq-border` border and the medium radius, its segments with the small radius, each with its count in Geist Mono, tertiary. The selected segment is navy Outfit 500 on the surface with `--mq-shadow-small`; an empty segment is tertiary. A 1 px `--mq-border-strong` rule, 16 px high, separates the two steps. It is a radio group: arrow keys move, and the selection is announced.
+- **Clear filters**: a ghost text button that appears once any filter differs from its default, and puts every filter back.
+
+**Table.** The app table wrapper: the surface, a `--mq-border-light` border, the medium radius, `--mq-shadow-small`, scrolling sideways inside itself below its minimum width. Header row on `--mq-surface-alt`, never a navy band; cells with `--mq-space-3` padding and a `--mq-border-light` hairline between rows; text at the table text size.
+
+| State | Shows |
+| :-- | :-- |
+| Loading | Skeleton rows of the same height, bars on `--mq-surface-alt`; the shimmer stops under `prefers-reduced-motion` |
+| Sorted | The sorted header is underlined and carries `aria-sort`; the sort reads in the header's accessible name |
+| Hover | The row on `--mq-surface-alt` |
+| Keyboard | Rows are reachable with the keyboard (Arrow or J and K keys move, Enter opens); the focused row shows the focus ring, and moving never opens |
+| Selected (the open item) | `--mq-accent-pale`, with a 3 px navy edge (`--mq-stroke-tab`) on its first cell |
+| Waiting for you | The quiet pale fill `--mq-accent-pale-2`, on that row only, so the others stay quiet |
+| Empty | The app empty state (layout, App patterns) in the table's place: "No open item", or, under filters, "No item matches these filters" with a clear-filters action |
+
+**Condition tile.** A short code that identifies a review condition (R1, R2): a navy square (`--mq-on-accent` on `--mq-accent`), the medium radius, the code in Geist Mono 600, 30 px in the list and 32 px in a dialog header, followed by the condition's name in Outfit 600. A tooltip on the tile gives what raised it. It is an identifier, not a state, so every tile is the same navy.
+
+**Status pill.** The item's step, a word in Outfit 500 at the label size with the small radius (never a pill shape despite its name), and under it a detail line in tertiary text at the note size (who, since when). The four states differ by mark style, and each carries its word:
+
+| State | Mark |
+| :-- | :-- |
+| To decide | Outline: `--mq-border-strong` border, muted text on the surface |
+| Confirmation required | The warning mark: `--mq-warning` text and a `--mq-warning-fill` border on `--mq-warning-tint`, since it asks the person to act |
+| Under review by a colleague | Pale: navy text and border on `--mq-accent-pale`; the detail line names the colleague |
+| Under review by you | Pale, plus a 2 px `--mq-accent-pale` ring around it, and its row takes the waiting-for-you fill |
+
+**Code chip.** A mono code with its name: the code in Geist Mono at the note size on `--mq-surface-alt` with the small radius, then the name in ink. A name too long for its cell is cut with an ellipsis and given in full in a tooltip and the accessible name; a code without a name shows the code alone, never an empty name.
+
+| Variant | Mark |
+| :-- | :-- |
+| Plain | As above |
+| Key code (the one the row is about) | `--mq-accent-pale` with navy text |
+| Added | A leading "+" and the code in `--mq-change-added`, with a 1 px ring of the same colour |
+| Removed | Struck through, the code in `--mq-change-removed` |
+
+The change colours are apps only and never carry the change alone: the "+" and the strike say it in every theme and in greyscale (charts, App categorical palette).
+
+Stays in the app: the conditions and their codes, the wording of each state, the sort keys, the keyboard shortcuts beyond Arrow and Enter, and which code is the key code.
+
+## Decision modal
+
+A large dialog where one decision is taken: context on the left, process on the right, actions at the foot. Its proportions and pane heights stay fixed from item to item, so nothing jumps while a person works through a list.
+
+**Frame.** On the surface with the overlay radius (`--mq-radius-overlay`) and `--mq-shadow-medium`, inset `--mq-space-5` from the viewport plus the safe-area insets, at most 1320 px wide. Escape closes it, focus stays inside while it is open and returns to the row it came from. Below 768 px it fills the screen with no radius, and its panes stack and scroll as one.
+
+**Header**, with a hairline below:
+
+- at the left, the condition tile (32 px) and the condition's name as the dialog title in Outfit 500 at the h3 size; under it the subject (the product) and an edition badge in the outline mark ("Edition 01.10.2026");
+- in the centre, the progress line at a fixed width;
+- at the right, the position in mono ("3 / 12"), previous and next buttons, and close.
+
+**Progress line.** Three steps (detected, review, decided): a 22 px circle and a label each, joined by 1.5 px lines.
+
+| Step | Mark |
+| :-- | :-- |
+| Done | `--mq-accent-pale` circle with a navy ring and a tick; the line after it navy |
+| Current | A navy circle with its number in `--mq-on-accent` and a 3 px `--mq-accent-pale` ring; the label in navy Outfit 600 |
+| To come | A `--mq-border-strong` ring on the surface, the label tertiary; the line after it `--mq-border` |
+| Optional review | The circle dashed, with "optional" in its detail line |
+| Required review | The detail line in `--mq-warning` with a warning icon: "required: your confirmation" |
+
+Labels keep one line, cut with an ellipsis and given in full in a tooltip. Where the header is too narrow for title, line and navigation side by side, the line takes its own row under the title.
+
+**Left pane: context**, on the canvas, a hairline on its right edge:
+
+- "The problem": a card with a fixed height of four lines, what the condition means for this item;
+- underline tabs (layout, App patterns): the source text (limitation-text marks) and the decision history with its count (history timeline). The chosen tab stays chosen from item to item.
+
+**Right pane: process**, on the surface, in numbered steps (a 22 px navy circle with the number in `--mq-on-accent`, then the step's name in Outfit 500):
+
+1. **Evidence**: one row per code in play, the code chip (review table, above), its name, and its source tag; a reason or quote an agent gave sits under its row in Newsreader italic, muted. The list has a fixed height and scrolls inside.
+2. **Decision**: the choice cards, then the form fields.
+3. **Result**: what is served today and what will be served after.
+
+**Source tags**, one mark style per source (colour, States by mark style), each with its word:
+
+| Source | Mark |
+| :-- | :-- |
+| Attached by the regulator | Solid |
+| Printed in the text | Pale, like the printed-code mark in the text |
+| Proposed by the agent | Dashed: not yet confirmed |
+| Candidate from the title | Outline |
+| Close code | Quiet |
+| Removed by the regulator | Struck through |
+
+**Choice cards.** A radio group of cards, one per answer: a `--mq-border-light` border and the small radius; the title in Outfit 500, one muted line of explanation, and at the right the codes the answer would serve, or "no code" in tertiary italic. Hover on `--mq-surface-alt`; selected: a navy border on `--mq-accent-pale-2`; invalid: a `--mq-danger` border with the error in words under the group. A card that restates what is served today says so in its explanation.
+
+**Result card.** A dashed `--mq-border-strong` border with the medium radius, two rows labelled in Geist Mono capitals, "Today" and "After": the code chips of each, an added code with its "+", a removed one struck through, both in the change-type colours, and "unchanged" in tertiary when nothing moves. Its height is fixed; long names are cut with a tooltip.
+
+**Held decision card.** While a colleague's review is pending it replaces the decision form: `--mq-warning-tint` with a `--mq-warning-fill` border and the medium radius, its title ("Decision to review") in `--mq-warning`, then rows of label and value: the held answer, its reason, the comment, who asked and when. The reviewer sees approve and send back, where send back asks for a comment; the person who asked sees withdraw. Everyone else sees it read-only.
+
+**Alerts**, above the form, each with an icon and a sentence:
+
+- a refused write: a `--mq-danger` border, what was refused and why; the form keeps what the person entered;
+- a stale write: an `--mq-info` border, "Decided meanwhile by a colleague, at 14:20"; the item reloads with that decision at the top of its history;
+- after a decision: a notice that the change reaches the public site after the next refresh.
+
+**Footer** on the canvas with a hairline above: facts at the left (muted label, ink value), actions at the right, secondary first and the primary last, such as "Confirm and go to next". An action the person cannot take is disabled with its reason shown in words beside it ("Role required: Maintainer"), never refused after a click on an enabled button.
+
+**Closed item.** It opens in its last state, read-only: no form, the result card showing what is served, and only navigation and close in the footer.
+
+Stays in the app: the choices and what each serves, which actions are allowed and why not, the wording of refusals and alerts, the sources and the data.
+
+## Limitation-text marks
+
+How a verbatim source text shows the passages a decision rests on. The text stays the official text: a mark adds a background or an underline, and never changes a word, its case or its order.
+
+**Text box.** Newsreader at a reading size (about 16.5 px) with a loose line height (about 2.2), so a mark never touches the line above it; on the canvas with a `--mq-border-light` border, the medium radius, and `--mq-space-3` by `--mq-space-4` padding. A long text scrolls inside its box (in the decision modal, inside its tab), never the page.
+
+| Mark | Look | Means |
+| :-- | :-- | :-- |
+| Printed code | Geist Mono, navy text on `--mq-accent-pale`, the small radius | A code the text itself prints |
+| Accepted quote | `--mq-accent-pale-2` with a 2 px navy underline | A passage accepted as evidence for a decision |
+| Contested printed code | The printed mark with a 2 px `--mq-warning` underline | The printed code this item calls into question |
+| Quote pointed at | The accepted quote on `--mq-accent-pale` | While the person points at that quote elsewhere, such as its evidence row |
+
+The contested mark differs from the printed one by its underline, not by colour alone, and the legend names it.
+
+**Legend.** Under the box at the note size in muted text: a swatch for each mark this item uses (the contested mark only where the item has one), then, in tertiary, the editions the text belongs to in mono ("Binding in editions 01.03.2024 to 01.10.2026").
+
+**Quoting a passage.** The text is plain text, so it can be selected with a pointer or the keyboard; the selection shows on `--mq-accent-pale`. When the selection could prove a decision, a popover opens beside it (the surface, a `--mq-border` border, the medium radius, `--mq-shadow-medium`): an eyebrow, "Quote as evidence for", then one small button per code that still needs a quote, its code in mono and its name. When nothing needs a quote, no popover opens. Once quoted, the passage takes the accepted-quote mark, and the decision form lists it as a quote row: a 3 px navy left edge (`--mq-stroke-tab`) on `--mq-accent-pale-2`, the passage in Newsreader italic, and a remove action.
+
+| State | Shows |
+| :-- | :-- |
+| Printed, quoted, contested | The marks above, each in the legend |
+| Selection in progress | The selection on `--mq-accent-pale`; the popover only when a code needs a quote |
+| Long text | It scrolls inside its box; the legend stays under it |
+
+Stays in the app: the passages and where they fall in the text, which codes need a quote, matching a quote to the text, and the popover's actions.
+
+## History timeline
+
+The decisions on one item, newest first: who did what, with which values, and which row is in force now. It is read on every item and later as an audit view.
+
+**Filters** above it: a row of toggle buttons, "All" then one per source, each with its count in Geist Mono, tertiary; a `--mq-border` border with the small radius, never a pill. A filter that is on is navy (`--mq-on-accent` on `--mq-accent`), its count in `--mq-accent-pale`, and carries `aria-pressed`.
+
+**Rows.** A vertical list joined by a 1 px `--mq-border` line through the dots. Each row is one line that opens to its details:
+
+- the dot, by origin: a person's decision a filled navy dot, an agent's a dashed `--mq-border-strong` ring, the system's a plain ring, a publication a small square in `--mq-decoration`;
+- the date in Geist Mono, muted;
+- the source as an icon with its name (in a narrow pane the icon alone, its name in the tooltip and the accessible name);
+- the event as a chip with the small radius, one mark style per outcome: accepted or applied in the ring mark (navy border and text), rejected dashed, a person's decision pale (`--mq-accent-pale`), a publication quiet (`--mq-surface-alt`);
+- the person, muted; a person the app cannot name reads "Unknown identity" in tertiary italic, never an empty cell or an internal identifier;
+- the values in Geist Mono at the right, or "none" in tertiary italic;
+- the in-force column, then a chevron that turns when the row opens.
+
+Hover on `--mq-surface-alt`. A row opens with a click or Enter: its details sit under it, aligned with the event, in tertiary text at the note size: the reason code in mono, the note, and the run that produced it as a mono link.
+
+**The row in force.** Exactly one row is live: its in-force column shows a 10 px `--mq-success` dot with the live halo (`--mq-shadow-live`), its name ("in force") in the tooltip and the accessible name. Superseded rows leave the column empty.
+
+**Key.** Under the list, after a hairline: each event mark and each dot with its meaning, in tertiary text at the note size, so no mark is read by colour alone.
+
+| State | Shows |
+| :-- | :-- |
+| Collapsed, expanded | One line; the line with its details under it |
+| Live, superseded | The live dot with its halo; an empty column |
+| Filter on, off | The navy toggle; the outlined toggle. "All" turns the others off |
+| Loading | Skeleton rows of the same height; the shimmer stops under `prefers-reduced-motion` |
+| Empty | "No decision yet" in muted text, in the list's place |
+| Unknown person | "Unknown identity", tertiary italic |
+
+Stays in the app: the event types and their wording, the sources, the data, and which row is in force.
+
 # Specialising the design system
 
 The design system is the single source of the MedQuantis visual identity (ADR-0002). A consumer uses it as released and adds only what it alone needs.
@@ -756,7 +1159,7 @@ Every local one-off (a component or a token a consumer adds under its own prefix
 
 # Tokens
 
-Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the semantic names; the `--mq-core-*` names exist so semantic tokens can point at them. A deprecated token names its replacement.
+Every token of release 1.3.0, generated from dist/tokens.json. Consumers use the semantic names; the `--mq-core-*` names exist so semantic tokens can point at them. A deprecated token names its replacement.
 
 ## Semantic tokens
 
@@ -773,6 +1176,7 @@ Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the
 | `--mq-accent-hover` | `#061a4d` | Hover state of accent-coloured controls. |
 | `--mq-accent-pale` | `#eaeef7` | Pale accent fill for a highlighted row, tag or state. |
 | `--mq-accent-pale-2` | `#f2f4f9` | Quieter pale accent fill. |
+| `--mq-accent-highlight` | `#0a2463` | Large highlighted title text; the accent itself in light, the light navy in dark (ADR-0007). |
 | `--mq-on-accent` | `#ffffff` | Text and icons on an accent fill, 14.53:1 on navy. |
 | `--mq-ink` | `#1a1a1a` | Primary text. |
 | `--mq-muted` | `#555555` | Secondary text. |
@@ -799,10 +1203,22 @@ Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the
 | `--mq-warning` | `#a06400` | Owner ruling 5, 2026-10-09: warning text, icons and borders; apps only (ADR-0004). |
 | `--mq-danger` | `#d8232a` | Apps only: errors and destructive actions, always with an icon or a word (ADR-0003, ADR-0004). |
 | `--mq-info` | `#1565c0` | Apps only: information, always with an icon or a word (ADR-0004). |
+| `--mq-on-warning-fill` | `#1a1a1a` | Text on the warning fill: ink in light (5.93:1), near-black in dark (6.18:1), where warm white on the fill is 2.67:1 (ADR-0007, amends owner ruling 5). |
 | `--mq-warning-fill` | `#d4850a` | Owner ruling 5, 2026-10-09: warning badge and highlight fill, always with ink text; white on it is forbidden (2.93:1). |
 | `--mq-warning-tint` | `#fbf3e7` | Owner ruling 5, 2026-10-09: warning tint behind ink text; warning strong only for icons and borders on it. |
 | `--mq-dim` | `#707070` | Deprecated: Use --mq-tertiary for text or --mq-decoration for non-text decoration. |
 | `--mq-accent-on-dark` | `#8795b3` | Deprecated: Use --mq-on-navy-title for titles and rules, --mq-on-navy-accent for the one-off accent. |
+| `--mq-app-cat-green` | `#1c7e3f` | App categorical hue: a many-category app chart or a data category, never a status and never in documents; text in it meets 4.5:1 (ADR-0008). |
+| `--mq-app-cat-orange` | `#d78000` | App categorical hue for marks and fills on the surface only (3.01:1); text in this hue reads app-cat-orange-text (ADR-0008). |
+| `--mq-app-cat-orange-text` | `#a35f00` | Text in the app categorical orange (counts, labels), 5.01:1 on the surface (ADR-0008). |
+| `--mq-app-cat-vermillion` | `#cf2a00` | App categorical hue: a data category, never the danger status, which stays for errors (ADR-0008). |
+| `--mq-app-cat-blue` | `#3a8ff5` | App categorical hue for marks and fills on the surface only (3.27:1), never text (ADR-0008). |
+| `--mq-app-cat-violet` | `#5a2fbe` | App categorical hue: marks, fills and text (ADR-0008). |
+| `--mq-app-cat-teal` | `#178a91` | App categorical hue for marks and fills on the surface only (4.13:1), never text (ADR-0008). |
+| `--mq-change-added` | `#1c7e3f` | Change type added, in apps only, always with its sign or its word: marks, fills and text (ADR-0008). |
+| `--mq-change-modified` | `#d78000` | Change type modified, in apps only, always with its word: marks and fills; its text reads change-modified-text (ADR-0008). |
+| `--mq-change-modified-text` | `#a35f00` | Text of the change type modified (counts, labels), in apps only (ADR-0008). |
+| `--mq-change-removed` | `#cf2a00` | Change type removed, in apps only, always with its sign or its word; a data category, never the danger status (ADR-0008). |
 | `--mq-focus-ring-color` | `#0a2463` | Focus ring on light backgrounds: 2 px navy with an offset, 13.90:1 on canvas (research note 0001, section 7). |
 | `--mq-focus-ring-color-on-navy` | `#ffffff` | Focus ring on navy backgrounds, 14.53:1. |
 | `--mq-focus-ring-width` | `2px` | Focus ring width (WCAG 2.4.7 and 1.4.11). |
@@ -824,12 +1240,16 @@ Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the
 | `--mq-shadow-small` | `0px 1px 2px 0px rgba(0, 0, 0, 0.05)` | Cards (increment 07 component need). |
 | `--mq-shadow-medium` | `0px 3px 12px 0px rgba(0, 0, 0, 0.07)` | A slide or page previewed on the desk, never in print (increment 07 component need). |
 | `--mq-shadow-panel` | `0px 14px 36px 0px rgba(10, 36, 99, 0.24)` | Navy panels (increment 07 component need). |
+| `--mq-shadow-edge` | `0px 0px 0px 0px rgba(0, 0, 0, 0)` | The navy panel's edge for a navy mark that has no panel shadow: the monogram, a navy KPI tile, a navy brand or app tile. None in light; on dark the panel's 1 px light-navy outline (owner rulings 13 and 14). |
+| `--mq-shadow-live` | `0px 0px 0px 3px rgba(46, 125, 50, 0.17)` | Apps only: the halo around a live status dot, the row in force on a timeline; built on the success colour, so never in documents (ADR-0004). |
 | `--mq-slide-width` | `1280px` | Slide canvas width (increment 07 component need). |
 | `--mq-slide-height` | `720px` | Slide canvas height (increment 07 component need). |
 | `--mq-page-width` | `1040px` | Content width of a screen document (increment 07 component need). |
 | `--mq-page-measure` | `760px` | Longest line of running text (increment 07 component need). |
 | `--mq-a4-width` | `793.7px` | A4 sheet width (increment 07 component need). |
 | `--mq-a4-height` | `1122.52px` | A4 sheet height (increment 07 component need). |
+| `--mq-sidebar-width` | `248px` | Apps only: the expanded app sidebar. |
+| `--mq-sidebar-rail-width` | `64px` | Apps only: the app sidebar collapsed to an icon rail. |
 | `--mq-font-family-heading` | `Outfit, system-ui, -apple-system, 'Segoe UI', sans-serif` | Headings, column titles and hero figures (Owner ruling 4, 2026-10-09, Owner ruling 10, 2026-10-09). |
 | `--mq-font-family-body` | `Newsreader, Georgia, 'Times New Roman', serif` | Body text of documents and slides, regulatory text in apps (Owner ruling 10, 2026-10-09). |
 | `--mq-font-family-ui` | `Outfit, system-ui, -apple-system, 'Segoe UI', sans-serif` | Labels and app UI (Owner ruling 10, 2026-10-09). |
@@ -896,6 +1316,13 @@ Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the
 | `--mq-core-amber-tint` | `#fbf3e7` | Owner ruling 5, 2026-10-09: warning tint, the warning fill at 10 % on white; warning strong on it is 4.42:1, so text on the tint stays ink. |
 | `--mq-core-red` | `#d8232a` | Swiss red, kept only as the danger status colour (ADR-0003, ADR-0004). |
 | `--mq-core-blue` | `#1565c0` | Info hue for interactive apps (ADR-0004). |
+| `--mq-core-app-green` | `#1c7e3f` | App categorical green, a data category in interactive apps only, never the success status (ADR-0008). |
+| `--mq-core-app-orange` | `#d78000` | App categorical orange, marks and fills only, 3.01:1 on white (ADR-0008). |
+| `--mq-core-app-orange-dark` | `#a35f00` | Darker app categorical orange for text in that hue, 5.01:1 on white (ADR-0008). |
+| `--mq-core-app-vermillion` | `#cf2a00` | App categorical vermillion, a data category, never the danger status (ADR-0008). |
+| `--mq-core-app-blue` | `#3a8ff5` | App categorical blue, marks and fills only, 3.27:1 on white (ADR-0008). |
+| `--mq-core-app-violet` | `#5a2fbe` | App categorical violet (ADR-0008). |
+| `--mq-core-app-teal` | `#178a91` | App categorical teal, marks and fills only, 4.13:1 on white (ADR-0008). |
 | `--mq-core-font-family-outfit` | `Outfit, system-ui, -apple-system, 'Segoe UI', sans-serif` | Outfit, the sans for headings, labels and app UI (Owner ruling 10, 2026-10-09). |
 | `--mq-core-font-family-newsreader` | `Newsreader, Georgia, 'Times New Roman', serif` | Newsreader, the only serif; Georgia and Times New Roman are fallbacks only (Owner ruling 10, 2026-10-09). |
 | `--mq-core-font-family-geist-mono` | `'Geist Mono', ui-monospace, 'SF Mono', Menlo, monospace` | Geist Mono for figures and codes (Owner ruling 10, 2026-10-09). |
@@ -927,6 +1354,10 @@ Every token of release 1.1.0, generated from dist/tokens.json. Consumers use the
 | `--mq-core-shadow-small` | `0px 1px 2px 0px rgba(0, 0, 0, 0.05)` | Small elevation for cards (increment 07 component need, Report design system, 2026-10-08). |
 | `--mq-core-shadow-medium` | `0px 3px 12px 0px rgba(0, 0, 0, 0.07)` | Medium elevation for a slide or page shown on the desk (increment 07 component need, Report design system, 2026-10-08). |
 | `--mq-core-shadow-panel` | `0px 14px 36px 0px rgba(10, 36, 99, 0.24)` | Navy-tinted elevation for navy panels (increment 07 component need, Report design system, 2026-10-08). |
+| `--mq-core-shadow-none` | `0px 0px 0px 0px rgba(0, 0, 0, 0)` | No shadow: a transparent layer of zero size, for a role that draws an edge in one theme only (owner ruling 14). |
+| `--mq-core-shadow-live` | `0px 0px 0px 3px rgba(46, 125, 50, 0.17)` | A 3 px ring of the success green at 17 %, the halo of a live mark in apps (ADR-0004, #38 component need). |
+| `--mq-core-size-64` | `64px` | App sidebar collapsed to an icon rail, 64 px (#38 component need: the Maintainer app shell). |
+| `--mq-core-size-248` | `248px` | App sidebar width, 248 px (#38 component need: the Maintainer app shell). |
 | `--mq-core-size-720` | `720px` | Slide canvas height, 720 px (increment 07 component need: the 1280 by 720 slide canvas). |
 | `--mq-core-size-760` | `760px` | Reading measure, 760 px (increment 07 component need, Report design system, 2026-10-08). |
 | `--mq-core-size-1040` | `1040px` | Content width of a screen document, 1040 px (increment 07 component need, Report design system, 2026-10-08). |