@medquantis/design-system 0.0.0-stage → 1.0.0

package/guidelines/README.md

@@ -0,0 +1,310 @@
+# Guidelines
+
+The MedQuantis brand, writing, colour, type, layout, chart, data and accessibility rules. They apply to every medium: slides, A4 reports, papers, the website, newsletters and interactive apps. These files are © MedQuantis SA, all rights reserved ([LICENSE](LICENSE)); the tokens and CSS they describe are MIT.
+
+| File | Covers |
+| :-- | :-- |
+| [principles.md](principles.md) | The principles that decide the cases the other files do not cover |
+| [brand.md](brand.md) | Name, tagline, legal line, wordmark, monogram, favicon, icons |
+| [voice.md](voice.md) | Tone, words to prefer and avoid, languages, terminology in French, German, Italian and English |
+| [writing.md](writing.md) | No em or en dash, titles, sentences and lists, French typography |
+| [colour.md](colour.md) | Semantic colour tokens, the medium split, navy panels, states by mark style, status colours in apps |
+| [typography.md](typography.md) | Families, weights, roles, sizes and line heights |
+| [layout.md](layout.md) | Media, report skeleton, widths and spacing, radius, components, tables, app patterns, print |
+| [charts.md](charts.md) | The ordered palette, highlight on grey, sequential and diverging use, marks, legends |
+| [data-patterns.md](data-patterns.md) | Numbers, amounts, dates, null versus zero, confidential and illustrative data |
+| [accessibility.md](accessibility.md) | WCAG 2.2 AA, contrast pairs, focus, targets, motion, structure |
+| [specialising.md](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.
+
+## Where the legacy rules went
+
+These guidelines replace five earlier documents, which competed and partly contradicted each other: the platform brand document, the platform design-system document, the platform report design system of 2026-10-08, the platform style guide and the Paracel design document. Every rule found in them is listed below, rewritten, either as carried over (with the file that now holds it) or as dropped (with the reason). Rulings cited by number are the owner rulings of 2026-10-09 and 2026-10-10 recorded in the bootstrap plan; ADRs are in `docs/architecture/decisions/`.
+
+| Source | Rules found | Carried over | Dropped |
+| :-- | --: | --: | --: |
+| platform brand document | 17 | 13 | 4 |
+| platform design-system document | 38 | 29 | 9 |
+| platform report design system of 2026-10-08 | 132 | 119 | 13 |
+| platform style guide | 26 | 22 | 4 |
+| Paracel design document | 55 | 41 | 14 |
+| Total | 268 | 224 | 44 |
+
+### Carried over
+
+| Rule | Source | Now in | Note |
+| :-- | :-- | :-- | :-- |
+| MedQuantis is the public name on every client-facing item | platform brand document | [brand.md](brand.md) |  |
+| Paracel names the technology only, never the company | platform brand document | [brand.md](brand.md) |  |
+| MedQuantis is one word with a capital M and Q | platform brand document | [brand.md](brand.md) |  |
+| The wordmark sets Med heavier than Quantis | platform brand document | [brand.md](brand.md) | weights as amended by ruling 6 |
+| Tagline in French, German and English | platform brand document | [brand.md](brand.md) |  |
+| Legal footer: company, web address, locality | platform brand document | [brand.md](brand.md) |  |
+| A confidentiality stamp and a date on material left with a reader | platform brand document | [brand.md](brand.md) |  |
+| The wordmark alone is the logo; no icon is required | platform brand document | [brand.md](brand.md) |  |
+| The monogram (white MQ on a navy square) stands in where the wordmark does not fit: favicon, avatar, app tile | platform brand document | [brand.md](brand.md) | ruling 7 |
+| Logo letters are live text; outline them before print | platform brand document | [brand.md](brand.md) | ruling 6: two files per background |
+| Short colour and type summary: navy accent, warm off-white canvas, three families | platform brand document | [colour.md](colour.md) |  |
+| Keep terminology consistent across languages through one glossary | platform brand document | [voice.md](voice.md) |  |
+| English is the source language; other languages are overlays | platform brand document | [voice.md](voice.md) |  |
+| Principle: clinical clarity, sober and high-contrast, no decoration without meaning | platform design-system document | [principles.md](principles.md) |  |
+| Principle: numbers are the hero, set in monospace | platform design-system document | [principles.md](principles.md) | figures in tables and codes; hero figures per ruling 4 |
+| Principle: calm confidence, pale neutral surfaces, one navy accent, generous whitespace | platform design-system document | [principles.md](principles.md) |  |
+| Principle: document-grade, credible on A4 and PDF | platform design-system document | [principles.md](principles.md) |  |
+| Navy is the primary accent for emphasis and top rules | platform design-system document | [colour.md](colour.md) |  |
+| Darker navy for hover and pressed states | platform design-system document | [colour.md](colour.md) |  |
+| Pale navy fill for icon pills and chips | platform design-system document | [colour.md](colour.md) |  |
+| Warm off-white page background | platform design-system document | [colour.md](colour.md) | ruling 9 |
+| White for cards and panels | platform design-system document | [colour.md](colour.md) | ruling 9 |
+| Recessed warm grey for grouped areas | platform design-system document | [colour.md](colour.md) |  |
+| Near-black ink for primary text | platform design-system document | [colour.md](colour.md) |  |
+| Two dark navy stops for panel and hero gradients | platform design-system document | [colour.md](colour.md) |  |
+| Dark grey for secondary text | platform design-system document | [colour.md](colour.md) |  |
+| Two warm border greys for borders and hairlines | platform design-system document | [colour.md](colour.md) |  |
+| Success, warning, info and danger state colours | platform design-system document | [colour.md](colour.md) | apps only, ADR-0004; warning split by ruling 5 |
+| Outfit for titles and headings | platform design-system document | [typography.md](typography.md) | ruling 4 |
+| Newsreader for body copy, captions and italic leads | platform design-system document | [typography.md](typography.md) | ruling 10 |
+| Geist Mono for numbers, codes, tags and eyebrows, uppercase and letter-spaced | platform design-system document | [typography.md](typography.md) |  |
+| Slide canvas 1280 by 720 with wide side margins | platform design-system document | [layout.md](layout.md) |  |
+| Section label: mono, uppercase, navy, top left | platform design-system document | [layout.md](layout.md) |  |
+| Slide number bottom right | platform design-system document | [layout.md](layout.md) |  |
+| Cards: white, bordered, soft shadow | platform design-system document | [layout.md](layout.md) | radius per ruling 3 |
+| Navy panels with a gradient for hero blocks and closing cards | platform design-system document | [layout.md](layout.md) |  |
+| Icon pill: pale navy rounded square with a navy Lucide icon | platform design-system document | [brand.md](brand.md) | radius per ruling 3 |
+| Chips and tags: small mono labels | platform design-system document | [layout.md](layout.md) | square only, ruling 3 |
+| Numbered rows: navy number, heading column, body column, one line per point | platform design-system document | [layout.md](layout.md) |  |
+| No em dash or en dash in copy | platform design-system document | [writing.md](writing.md) |  |
+| Icons offline from a pinned Lucide build, never a CDN | platform design-system document | [brand.md](brand.md) |  |
+| One accent: navy carries emphasis, state colours only mean state | platform design-system document | [colour.md](colour.md) | ADR-0003, ADR-0004 |
+| Expert to expert: confident, never boastful; show, do not promise | platform style guide | [voice.md](voice.md) |  |
+| Partnership framing: we speak to you | platform style guide | [voice.md](voice.md) |  |
+| No hype and no overselling of AI; concrete numbers before adjectives | platform style guide | [voice.md](voice.md) |  |
+| No humour | platform style guide | [voice.md](voice.md) |  |
+| No em dash or en dash in copy or translated strings; hyphens in compounds are fine | platform style guide | [writing.md](writing.md) |  |
+| No technical jargon in client material (query languages, table names) | platform style guide | [voice.md](voice.md) |  |
+| No unsupported claim of ease or speed; back it with a number | platform style guide | [voice.md](voice.md) |  |
+| One number format per document | platform style guide | [data-patterns.md](data-patterns.md) |  |
+| Ranges with a plain hyphen, never an en dash | platform style guide | [data-patterns.md](data-patterns.md) |  |
+| Approximate figures stay approximate, without false precision | platform style guide | [data-patterns.md](data-patterns.md) |  |
+| Periods written with an arrow | platform style guide | [data-patterns.md](data-patterns.md) |  |
+| Million abbreviations per language | platform style guide | [data-patterns.md](data-patterns.md) | decimal point per ruling 8 |
+| Product and regulatory list names keep their capitals | platform style guide | [voice.md](voice.md) |  |
+| Titles in sentence case, with no final full stop | platform style guide | [writing.md](writing.md) |  |
+| Section labels and eyebrows uppercase, mono, letter-spaced, set by CSS | platform style guide | [typography.md](typography.md) |  |
+| Summary and agenda pages: one line per point, readable in a few seconds | platform style guide | [writing.md](writing.md) |  |
+| Body pages: short sentences, one idea per bullet | platform style guide | [writing.md](writing.md) |  |
+| Prefer verifiable wording: traced to the clause, executable, auditable, reproducible | platform style guide | [voice.md](voice.md) |  |
+| Words to avoid: AI-powered, revolutionary, seamless, easy, simply, just | platform style guide | [voice.md](voice.md) |  |
+| The regulator is not the board; the board is the client's executive management | platform style guide | [voice.md](voice.md) |  |
+| German is formal Swiss Standard German: Sie, no sharp s | platform style guide | [voice.md](voice.md) |  |
+| Never carry a dash over from a source language; restructure the sentence | platform style guide | [writing.md](writing.md) |  |
+| A report is a scrolling web page that prints cleanly on A4, not a deck | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Build pages from the shared mq- components with their markup | platform report design system of 2026-10-08 | [specialising.md](specialising.md) |  |
+| Add no colour, font, shadow or radius outside the system; combine components before inventing one | platform report design system of 2026-10-08 | [specialising.md](specialising.md) |  |
+| The generated specimen is the reference when a rendering is in doubt | platform report design system of 2026-10-08 | [specialising.md](specialising.md) |  |
+| Principle: one accent; everything else neutral or blue-grey | platform report design system of 2026-10-08 | [principles.md](principles.md) |  |
+| Principle: states read by mark style (filled, pale, outline, dashed, struck), not by hue | platform report design system of 2026-10-08 | [colour.md](colour.md) | documents; ADR-0004 |
+| Principle: three families, three roles | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Principle: one idea per block, one hero figure per column; cut content before shrinking text | platform report design system of 2026-10-08 | [principles.md](principles.md) |  |
+| Principle: the figure before the adjective, every figure traceable to its source | platform report design system of 2026-10-08 | [principles.md](principles.md) |  |
+| Principle: sober, optional motion; print shows the final state | platform report design system of 2026-10-08 | [principles.md](principles.md) |  |
+| Report skeleton: header, in-brief, sections with a head, blocks and a takeaway, footer | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Flow layout: no absolute positions, no fixed heights | platform report design system of 2026-10-08 | [layout.md](layout.md) | documents; slides keep their fixed canvas |
+| Every shared class carries the mq- prefix | platform report design system of 2026-10-08 | [specialising.md](specialising.md) |  |
+| Darker navy for link hover only | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Navy gradients for the report header, the KPI band and panels | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Pale navy for icon pills, deviating values, the highlighted row and the pale state | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Quieter pale navy for progress tracks and quiet badges | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Blue-grey family replaces the old sky blue for secondary marks | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Blue-grey 2 for projections, dashed marks and struck rows; accent point on navy | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Blue-grey 3 for previous period, reference and neutral outline; second-level text on navy | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Blue-grey 4 for a remainder or an empty part | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Warm off-white page background; white cards, figures and tables | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 9 |
+| Ink, secondary and tertiary text roles | platform report design system of 2026-10-08 | [colour.md](colour.md) | tertiary per ruling 1 |
+| Border grey for chart baselines and total rules; light grey for hairlines and card borders | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| On navy: titles, figures and icons white | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: secondary text white at 68 % opacity | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: second-level text in blue-grey 3 | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: one-off accent in blue-grey 2 | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: rules white at 16 to 18 % | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: icon-pill fill white at 12 % | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2 |
+| On navy: discreet numbers white at 40 % | platform report design system of 2026-10-08 | [colour.md](colour.md) | ruling 2: large text or non-text only |
+| One large navy block per screen; separate navy blocks with light content | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Chart palette used in order, darkest first | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| One series: navy | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Two series: reference in blue-grey 3, then current in navy | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Parts of a whole: navy, blue-grey 1, remainder fill with an outlined legend swatch | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Ranking with more than four categories: the item in the text in navy, the others in blue-grey 2 | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Never more than four series at once; group the rest as Other | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Outfit for titles, labels, table text and conclusions | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Newsreader with its true italic for prose, leads, captions, notes and quoted official text | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Geist Mono for codes, table figures, dates, eyebrows and axes, always with tabular figures | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Type roles with a screen size and a print size | platform report design system of 2026-10-08 | [typography.md](typography.md) | sizes from the font-size tokens |
+| Bold inside prose switches to Outfit at 600 | platform report design system of 2026-10-08 | [typography.md](typography.md) | ruling 4 |
+| Notes and the illustrative mention in Newsreader italic, tertiary grey | platform report design system of 2026-10-08 | [typography.md](typography.md) | ruling 1 |
+| Chart labels sized for print: SVG text shrinks with its figure | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Titles in sentence case without a final full stop | platform report design system of 2026-10-08 | [writing.md](writing.md) |  |
+| A coloured full stop is reserved for a one-word name on a navy cover | platform report design system of 2026-10-08 | [brand.md](brand.md) |  |
+| Letter spacing tightens as size grows | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Eyebrows typed in normal case and uppercased by CSS; a middle dot separates parts | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Readability floor of 11 px on screen | platform report design system of 2026-10-08 | [typography.md](typography.md) |  |
+| Page width 1040 px, reading measure 760 px, side gutter 32 px (16 px on phones) | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Gaps: 48 px between calm columns, 24 px between cards, 72 px between sections (48 px on phones), 32 px from a section head to its content | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Prose, leads, in-brief and callouts stop at the measure; figures, tables and grids take the page width | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Grids: calm columns separated by rules, two and three columns; one column on phones | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Report header: navy gradient, logo, mono kicker, white title, one-sentence tagline, metadata row | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Logo inline as SVG; the on-navy file on navy, the on-light file on light; never altered | platform report design system of 2026-10-08 | [brand.md](brand.md) | ruling 6 |
+| Section: numbered eyebrow, title, one-sentence lead, blocks, optional takeaway | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Footer: navy rule, numbered sources, legal line and date | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| A report sent outside carries a confidentiality mention and its date | platform report design system of 2026-10-08 | [brand.md](brand.md) |  |
+| Print: exact colour printing, no animation, figures and rows never split, headings never alone at a page foot | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Check every PDF page before sending it | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Phones: one column, no horizontal page scroll; only tables and charts scroll inside their frame | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| A hero figure stays short; its unit goes in the caption | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Three KPI forms: calm columns with a hero figure, ruled counters, a navy band | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Card title bar: blue-grey icon, navy title, mono note on the right | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Callouts are always navy; no coloured warning or success variant | platform report design system of 2026-10-08 | [colour.md](colour.md) | documents |
+| Tables: horizontal rules only, never zebra stripes | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Tables: mono uppercase headers with the unit on a second line | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Tables: figures in mono, right-aligned; key column in navy | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Tables: a deviating value in a pale pill; one highlighted row with a pale fill and a navy edge | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Tables: an excluded row is struck through and left out of the total | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Tables: total under a rule, key amount in navy | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Badge meanings: solid confirmed, ring approved, pale corrected, outline pending, quiet withdrawn, dashed upcoming | platform report design system of 2026-10-08 | [colour.md](colour.md) |  |
+| Badges: small radius, Outfit 500; a page using badges gives their key once | platform report design system of 2026-10-08 | [accessibility.md](accessibility.md) |  |
+| Progress bar: quiet pale track, navy fill, blue-grey 2 for a secondary value | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Stacked bar: filled, second share, remainder dashed | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Horizontal bars with the value at the bar end | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Legend beside a ring with right-aligned values and the remainder under a rule; inline legend above a chart | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Takeaway line, source note, superscript reference number | platform report design system of 2026-10-08 | [layout.md](layout.md) |  |
+| Icons: Lucide only, monochrome, inline SVG, never emoji; navy on pale, white on navy | platform report design system of 2026-10-08 | [brand.md](brand.md) |  |
+| Confidential rates or prices are masked, never invented | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Only one element in navy when the others are comparisons | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| No background grid; one baseline; no drawn vertical axis; at most three value labels | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Axis labels in Geist Mono at 11, three to five ticks; date ticks as year or month.year | platform report design system of 2026-10-08 | [charts.md](charts.md) | label colour per ruling 1 |
+| Label only the value the text discusses, in navy; leave headroom above the maximum | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Vertical bars rounded at the top only; small gaps in a monthly series | platform report design system of 2026-10-08 | [charts.md](charts.md) | radius per ruling 3 |
+| Horizontal bars thin, rounded at the end, value in mono | platform report design system of 2026-10-08 | [charts.md](charts.md) | radius per ruling 3 |
+| Ring: thick stroke, starts at the top, small gaps between arcs, no text in the centre | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Lines: main series navy and thicker; reference blue-grey 3; projection blue-grey 2 dashed; end dot with its value; no area fill, no smoothing | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Annotations: dotted marker and a short italic sentence, or a numeric note under the chart | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Legend in HTML above or beside the plot, never inside it | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Shares of a whole rounded by largest remainder so they sum to 100 | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Chart motion: bars grow, lines draw, under two seconds; nothing in print | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Tooltips: navy background, white text, Outfit title, mono values | platform report design system of 2026-10-08 | [charts.md](charts.md) | radius per ruling 3 |
+| Fix colours per series when order matters, never let a library rotate the palette | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| Thousands separated by a straight apostrophe | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) | ruling 8 |
+| Amounts: CHF, a space, the amount | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) | ruling 8: non-breaking space |
+| Cents with a decimal point; round to the franc in reports when possible | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Percentages with a non-breaking space | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) | ruling 8 as amended |
+| Negative numbers with the minus sign, not a hyphen | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Changes shown by their sign alone, without colour or arrow | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Dates as day.month.year; months as month.year | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Periods with an arrow; ranges with a hyphen or a word | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Approximations with a tilde or an approximately-equal sign | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| A table's unit in its header, not in every cell | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Never mix two thousands separators in one document | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Voice: expert to expert, no humour, no overselling, numbers before adjectives, banned words | platform report design system of 2026-10-08 | [voice.md](voice.md) |  |
+| Full sentences with a subject and a verb; distrust triads and mechanical bullets | platform report design system of 2026-10-08 | [writing.md](writing.md) |  |
+| No em or en dash and no spaced hyphen as an aside; middle dot and arrow allowed | platform report design system of 2026-10-08 | [writing.md](writing.md) |  |
+| French typography: non-breaking space before : ; ? ! and %, French quotation marks | platform report design system of 2026-10-08 | [writing.md](writing.md) |  |
+| Regulatory names and abbreviations per language (list of specialities, federal office, article numbers) | platform report design system of 2026-10-08 | [voice.md](voice.md) |  |
+| In client documents: do not judge the client's choices or estimate their internal costs; highlight only figures our work establishes | platform report design system of 2026-10-08 | [voice.md](voice.md) |  |
+| Fictitious data flagged on the page itself; anonymised insurers lettered A, B, C with A the largest | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| No sky blue, green, orange, red, pink, purple or turquoise in documents, even for a status | platform report design system of 2026-10-08 | [colour.md](colour.md) | documents; apps per ADR-0004 |
+| No background grid, zebra stripes, 3D, bar shadows, area fills, or pie with more than four parts | platform report design system of 2026-10-08 | [charts.md](charts.md) |  |
+| No blur, zoom, reflection, spotlight or looping animation | platform report design system of 2026-10-08 | [accessibility.md](accessibility.md) |  |
+| No corner above 6 px, no pill shapes | platform report design system of 2026-10-08 | [layout.md](layout.md) | ruling 3 as amended |
+| No emoji, no second icon library, no external image | platform report design system of 2026-10-08 | [brand.md](brand.md) |  |
+| No client name, no fictitious figure shown as real, no untraceable figure or legal reference | platform report design system of 2026-10-08 | [data-patterns.md](data-patterns.md) |  |
+| Principle: colour communicates and never decorates; every coloured element earns its place | Paracel design document | [principles.md](principles.md) |  |
+| Principle: three families, three roles; regulatory text in Newsreader | Paracel design document | [typography.md](typography.md) |  |
+| Principle: warm off-white background with white cards | Paracel design document | [colour.md](colour.md) |  |
+| Principle: consistent geometry on a 4 and 8 px grid, no pills | Paracel design document | [layout.md](layout.md) | radii per ruling 3 |
+| Principle: dense data with breathing room; long regulatory text gets generous line height | Paracel design document | [typography.md](typography.md) |  |
+| Recessed surface for table headers, tab backgrounds and hover | Paracel design document | [colour.md](colour.md) |  |
+| Placeholder text has its own light grey | Paracel design document | [accessibility.md](accessibility.md) | replaced: placeholders use tertiary text, the light grey failed contrast |
+| Status colours each with a light badge background | Paracel design document | [colour.md](colour.md) | apps only; light steps from the Tailwind scales |
+| Borders have a warm undertone matching the canvas | Paracel design document | [colour.md](colour.md) |  |
+| Small shadow for cards and tables, medium shadow for raised panels | Paracel design document | [layout.md](layout.md) |  |
+| Outfit for display, UI headings, UI body, buttons, badges and navigation | Paracel design document | [typography.md](typography.md) |  |
+| Geist Mono for data values, codes and percentages | Paracel design document | [typography.md](typography.md) |  |
+| App type scale: UI body, help text, labels, data values | Paracel design document | [typography.md](typography.md) | weights per ruling 4, floor 11 px |
+| Five named line heights from tight to regulatory text | Paracel design document | [typography.md](typography.md) |  |
+| All spacing on the 4 and 8 px grid from the spacing scale | Paracel design document | [layout.md](layout.md) |  |
+| No circles except status dots | Paracel design document | [layout.md](layout.md) | ruling 3: rounded-full only for circles |
+| Short transitions on interactive elements | Paracel design document | [accessibility.md](accessibility.md) |  |
+| Navigation links: secondary by default, ink on hover, accent when active | Paracel design document | [layout.md](layout.md) | navy per ADR-0003 |
+| Navigation collapses to a menu on tablets | Paracel design document | [layout.md](layout.md) |  |
+| Breadcrumb inside a light card, current page in ink | Paracel design document | [layout.md](layout.md) |  |
+| Buttons: primary, secondary, danger outline, ghost; one shape and size | Paracel design document | [layout.md](layout.md) | navy primary, ruling 3 |
+| Buttons stretch to full width on phones | Paracel design document | [layout.md](layout.md) |  |
+| Two badge tiers: quiet labels and urgent flags with an icon and a border | Paracel design document | [colour.md](colour.md) | apps only |
+| Search field: surface, border, small shadow; accent on focus | Paracel design document | [accessibility.md](accessibility.md) | focus ring tokens |
+| Empty state: centred dimmed icon, title, one-line description, mono hint | Paracel design document | [layout.md](layout.md) |  |
+| Stat cards stay still: no hover lift | Paracel design document | [layout.md](layout.md) |  |
+| Proportional bar for workflow stage distribution | Paracel design document | [charts.md](charts.md) | navy family, not status hues |
+| Underline tabs: active tab underlined in the accent | Paracel design document | [layout.md](layout.md) | navy per ADR-0003 |
+| Regulatory text block: Newsreader, generous line height, inline codes in mono on the recessed surface | Paracel design document | [typography.md](typography.md) |  |
+| Sober tables: small classification marks with a legend row instead of badges in every column | Paracel design document | [layout.md](layout.md) |  |
+| Status column: a coloured dot with a plain word, no badge | Paracel design document | [colour.md](colour.md) | apps only |
+| Flags as plain coloured words, only on rows that need attention | Paracel design document | [colour.md](colour.md) | apps only |
+| Thin progress bar beside a mono percentage | Paracel design document | [charts.md](charts.md) |  |
+| App table: recessed header, row hover, horizontal scroll under a minimum width | Paracel design document | [layout.md](layout.md) |  |
+| Breakpoints at tablet and phone widths | Paracel design document | [layout.md](layout.md) |  |
+| Touch targets at least 44 px high on mobile | Paracel design document | [accessibility.md](accessibility.md) |  |
+| Rationale: the warm canvas reads institutional, pure white reads generic | Paracel design document | [colour.md](colour.md) |  |
+| Rationale: Outfit reads cleanly from display to badge sizes | Paracel design document | [typography.md](typography.md) |  |
+| Rationale: squared corners read professional, pills read consumer | Paracel design document | [layout.md](layout.md) |  |
+| Rationale: underline tabs stay light in dense tools | Paracel design document | [layout.md](layout.md) |  |
+| Rationale: graded visual weight in tables lets the eye rest on normal rows | Paracel design document | [layout.md](layout.md) |  |
+
+### Dropped
+
+| Rule | Source | Reason |
+| :-- | :-- | :-- |
+| Audit note listing slides that still use the product name | platform brand document | Consumer-specific: a one-off audit of one deck set |
+| Light sky-blue accent for part of the wordmark on dark backgrounds | platform brand document | Superseded by ruling 2 (no sky blue) and ruling 6 (white on navy) |
+| Logo files that combine the monogram, the wordmark and a strapline | platform brand document | Superseded by deferred issue #2: no lockup in v1 |
+| Separator sign of a co-branded cover in the light-blue accent | platform brand document | Client-specific co-branding, and superseded by ruling 2 |
+| A client deck's stylesheet is the source of truth; copy its folder to start a deck | platform design-system document | Superseded by ADR-0002: this repository is the only source |
+| Light sky-blue accent for text and icons on navy | platform design-system document | Superseded by ruling 2 |
+| The lighter grey as tertiary text | platform design-system document | Superseded by ruling 1: tertiary text is the darker grey, the lighter one is decoration only |
+| Pink, purple and teal families for categorical charts | platform design-system document | Superseded by the four-series navy palette (owner, 2026-10-10) and ADR-0004 |
+| Fonts loaded from Google Fonts | platform design-system document | Superseded by ADR-0002: fonts are self-hosted, no remote request |
+| Slide title in Outfit at weight 600 | platform design-system document | Superseded by ruling 4 (weight 500) and the slide title size token |
+| Card radius up to 13 px and a thick navy top border | platform design-system document | Superseded by ruling 3 (6 px maximum); cards carry no top bar in the shared components |
+| Pill-shaped chips and light-blue borders on navy | platform design-system document | Superseded by rulings 2 and 3 |
+| Navy panel accent text in the light-blue accent | platform design-system document | Superseded by ruling 2 |
+| Thousands separated by a comma | platform style guide | Superseded by ruling 8 (straight apostrophe) |
+| The translation build fails on a dash and prints a dash count | platform style guide | Tool-specific; this repository's guideline test does the same for guidelines |
+| The English string is the translation key | platform style guide | Tool-specific (one deck pipeline); the general rule is carried as B13 |
+| Commercial phrases to prefer (recovering every franc, zero risk, success-based fee, one-off audit) | platform style guide | Offer-specific positioning; belongs to the positioning material, not the design system |
+| Copy the CSS block as is into every report | platform report design system of 2026-10-08 | Superseded by ADR-0002: load the released CSS |
+| Load fonts from Google Fonts | platform report design system of 2026-10-08 | Superseded by ADR-0002: fonts are self-hosted |
+| Provenance notes on transposed values and source file lists | platform report design system of 2026-10-08 | Obsolete: extraction notes, not rules |
+| Decimal comma in prose, percentages and millions | platform report design system of 2026-10-08 | Superseded by ruling 8 (decimal point) |
+| English percentages without a space | platform report design system of 2026-10-08 | Superseded by ruling 8 as amended (non-breaking space in every language) |
+| A 4 px radius for small items, bars and tooltips | platform report design system of 2026-10-08 | Superseded by ruling 3 (3 px) |
+| Notes, axes and legal line in the lighter grey | platform report design system of 2026-10-08 | Superseded by ruling 1 (tertiary text grey) |
+| Hero figures in Geist Mono at 600 | platform report design system of 2026-10-08 | Superseded by ruling 4: hero figures in Outfit 500 with tabular figures |
+| Header glow made of radial gradients; very light note background; translucent shading of a calculated column; white at 8 % | platform report design system of 2026-10-08 | Not encoded in v1: no token and no shared component uses them |
+| Ready-made option sets for three charting libraries | platform report design system of 2026-10-08 | Tool-specific; the skill's chart reference (increment 10) carries library settings derived from the tokens |
+| Do not follow the older colour documents and templates | platform report design system of 2026-10-08 | Obsolete: these guidelines replace them |
+| A white page background in print | platform report design system of 2026-10-08 | Superseded by ruling 9: every document page uses the canvas colour |
+| Anonymised insurers named Caisse A, Caisse B | platform report design system of 2026-10-08 | Superseded by ADR-0005 naming (Assureur A, Assureur B) |
+| Swiss red as the accent with its light and hover variants | Paracel design document | Superseded by ADR-0003: navy everywhere, red only as danger |
+| Pink, purple and teal colours and six annotation hues for regulatory text | Paracel design document | Consumer-specific: kept local in the app under its own prefix (ADR-0004) |
+| 6 px radius on every component, 4 px on badges | Paracel design document | Superseded by ruling 3 (3 and 6 px, 12 px app overlays) |
+| Fonts from Google Fonts and a font CDN | Paracel design document | Superseded by ADR-0002: self-hosted fonts |
+| Headings and buttons at weights 600 to 800 | Paracel design document | Superseded by ruling 4 |
+| Table headers at 10.5 px | Paracel design document | Superseded by the 11 px floor |
+| Extra spacing steps of 40, 56 and 64 px and a separate hover surface | Paracel design document | Superseded by the token scale (no such tokens) |
+| Product header with a red logo tile and a coloured product word | Paracel design document | Product-specific, and superseded by ADR-0003 and ruling 7 |
+| Confidence heatmap and extracted-field rows with their thresholds | Paracel design document | Product-specific; the general rule (colour never alone) is in accessibility.md |
+| Tier column in plain mono | Paracel design document | Product-specific |
+| Container width of one product and grid recipes for swatches and stat cards | Paracel design document | Product-specific layout values |
+| Copy-paste root block of custom properties | Paracel design document | Superseded by ADR-0002 and ADR-0006 (generated --mq- tokens) |
+| Machine-readable kit token section with the red accent | Paracel design document | Superseded by ADR-0006: the kit contract is generated |
+| Workflow stage colours with white text inside the bar segments | Paracel design document | Superseded by ADR-0004 (status hues for system status only) and the contrast pairs (white fails on the light series) |

package/guidelines/accessibility.md

@@ -0,0 +1,62 @@
+# Accessibility
+
+## Target
+
+WCAG 2.2 level AA for every medium: apps, the website, HTML reports, slides exported to PDF and newsletters. APCA is not normative and is not used; contrast is measured with the WCAG 2.x formula.
+
+## Colour is never alone
+
+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](charts.md));
+- a change in a figure is shown by its sign, not by a colour or an arrow alone.
+
+## Contrast pairs
+
+Every foreground and background pair the system uses is declared in `tokens/contrast-pairs.json` with its allowed use: text (4.5:1), large text (3:1), non-text (3:1, WCAG 1.4.11) or decorative (no minimum, for marks that carry no information). The token test checks every declared pair and fails on any pairing used in `css/` without a declaration; the specimen shows each pair with its ratio. A consumer that needs a new pair asks for it here rather than eyeballing it.
+
+Pairs to remember:
+
+| Pair | Ratio | Allowed for |
+| :-- | :-- | :-- |
+| Ink on canvas | 16.65:1 | Text |
+| Muted on canvas | 7.13:1 | Text |
+| Tertiary on canvas, on surface | 4.74:1, 4.95:1 | Text. Not on the recessed surface (exactly 4.50:1, not declared) |
+| Decoration grey on canvas | 3.22:1 | Non-text only, never text |
+| Navy on canvas | 13.90:1 | Text |
+| White on navy | 14.53:1 | Text |
+| On-navy accent on the lighter panel stop | 4.61:1 | Text, narrow margin |
+| On-navy discreet (white at 40 %) on navy | 3.48:1 | Large text or non-text only |
+| Warning text on surface | 4.86:1 | Text |
+| Ink on the warning fill | 5.93:1 | Text; white on the fill is forbidden (2.93:1) |
+| Blue-grey outline on canvas | 4.84:1 | Non-text |
+
+Placeholder text in inputs uses the tertiary text colour, never a lighter grey.
+
+## Focus
+
+- Every interactive element shows a visible focus ring on keyboard focus (WCAG 2.4.7 and 1.4.11): `--mq-focus-ring-width` (2 px) of `--mq-focus-ring-color` (navy, 13.90:1 on canvas) at `--mq-focus-ring-offset` (2 px) from the element.
+- On navy, the ring is white (`--mq-focus-ring-color-on-navy`, 14.53:1). `css/base.css` and `css/components.css` draw both.
+- Never remove the outline without drawing this ring. A focused input may also change its border to navy, but the ring stays.
+
+## Size and targets
+
+- No text below 11 px on screen ([typography](typography.md)).
+- Touch targets in apps are at least 44 px high on mobile (buttons, tabs, navigation links), above the 24 px minimum of WCAG 2.5.8.
+- Text reflows: pages work at 320 px wide and at 200 % zoom without horizontal page scrolling; only tables and wide charts scroll inside their frame.
+
+## Motion
+
+- Motion is optional, short and meaningful. Interactive elements may use short transitions (about 120 ms) on colour and background; documents do not animate on hover.
+- Never blur, zoom, reflections, spotlight effects or looping animation.
+- Everything respects `prefers-reduced-motion: reduce` (no animation at all) and print shows the final state.
+
+## Structure
+
+- One `h1` per page and headings in order; the eyebrow is not a heading.
+- Set the page language (`lang`) and mark passages in another language.
+- An SVG chart has `role="img"` and an accessible name and description (`<title>` and `<desc>`, or `aria-labelledby`); the figure's key values also appear in text or in a table.
+- 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.

package/guidelines/brand.md

@@ -0,0 +1,75 @@
+# Brand
+
+## Name
+
+- **MedQuantis** is the company and the public brand. It is the name on every slide, report, paper, page and email a reader outside the company sees.
+- It is written as one word with a capital M and a capital Q: MedQuantis. Never Medquantis, MEDQUANTIS in running text, or Med Quantis.
+- **Paracel** names the technology (the engine and its data), never the company. Use it only when the sentence is about the technology itself; to a client, the company that speaks is MedQuantis.
+
+## Tagline
+
+| Language | Tagline |
+| :-- | :-- |
+| French | L'IA suisse au service des systèmes de santé |
+| German | Schweizer KI für das Gesundheitswesen |
+| English | Swiss AI for healthcare systems |
+| Italian | Not yet defined, owner to provide |
+
+The French line is the reference; the German and English lines are its approved translations. Do not write an Italian tagline until the owner provides one.
+
+## Legal line
+
+The footer of every document sent outside carries the legal line and the date of the document:
+
+`MedQuantis SA · CH-1095 Lutry · medquantis.ch`
+
+Set it in Geist Mono at the note size, tertiary text colour (`--mq-tertiary`), with the date at the right end of the same line.
+
+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.
+
+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 |
+| :-- | :-- | :-- | :-- | :-- |
+| Presentation | Présentation confidentielle | Präsentation vertraulich | Confidential presentation | Not yet defined, owner to provide |
+| Report | Rapport confidentiel | Vertraulicher Bericht (proposed, owner to confirm) | Confidential report (proposed, owner to confirm) | Not yet defined, owner to provide |
+
+## 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).
+
+Each background has two files in `brand/`:
+
+| File | Use |
+| :-- | :-- |
+| `wordmark-on-light.svg`, `wordmark-on-navy.svg` | Live text. Inline the SVG in a page that loads `fonts/fonts.css`, so the letters render in Outfit and stay selectable. |
+| `wordmark-on-light-print.svg`, `wordmark-on-navy-print.svg` | Outlined letters. Use for images (`<img>` cannot load web fonts), documents, PDFs, email and anything sent to a printer. |
+
+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.
+- 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.
+
+## Monogram and favicon
+
+Where the wordmark does not fit (favicon, app icon, avatar, app tile), use the monogram: a white M and Q on a navy (`#0a2463`) square with rounded corners of 8/64 of its side, M in Outfit 700 and Q in Outfit 400, centred on the cap height (owner ruling 7). The letters are outlined in every file.
+
+| File | Use |
+| :-- | :-- |
+| `brand/monogram.svg` | The monogram with its rounded corners |
+| `brand/monogram-square.svg` | For platforms that round icons themselves |
+| `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` |
+
+## 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.
+
+## Icons
+
+- Lucide only, from the pinned build in `icons/` (version and hash in `icons/manifest.json`). No second icon library, and never an emoji in place of an icon.
+- Icons are offline: the pinned build or an inline SVG, never a CDN or any remote request.
+- Monochrome, stroke 2, round caps and joins, colour inherited from the text. Navy on a pale navy pill (`--mq-accent-pale`), white on a navy panel inside a translucent pill (`--mq-on-navy-pill`), blue-grey (`--mq-border-strong`) in a card title bar.
+- The icon pill is a small square with the 6 px radius (`--mq-radius-medium`), never a circle or a pill shape.
+- An icon that carries meaning has a text label or an accessible name; a decorative icon is hidden from assistive technology.

package/guidelines/charts.md

@@ -0,0 +1,84 @@
+# 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.
+
+## The ordered palette
+
+Four categorical series plus a remainder fill (owner, 2026-10-10), always used in this order, darkest first:
+
+| Order | Token | Value | Contrast on canvas | Typical role |
+| :-- | :-- | :-- | :-- | :-- |
+| 1 | `--mq-chart-series-1` | `#0a2463` | 13.90:1 | The main series, the current period, the value the text discusses |
+| 2 | `--mq-chart-series-2` | `#5d6f91` | 4.84:1 | The second share of a whole |
+| 3 | `--mq-chart-series-3` | `#8795b3` | 2.88:1 | Other values, projections, "upcoming" dashed marks, struck values |
+| 4 | `--mq-chart-series-4` | `#c3cbdc` | 1.56:1 | Previous period, reference, neutral outline |
+| Remainder | `--mq-chart-rest` | `#dde3ee` | | What is left, empty or not yet: never a categorical series |
+
+The pairs between the four series stay at least CIEDE2000 10 apart under normal vision and under protan, deutan, tritan and achromatic simulation; the remainder fill is too close to series 4, so it is drawn with a series 4 outline.
+
+**Series 3 and 4 are below 3:1 against the page** (WCAG 1.4.11). A chart that uses them must not rely on their colour alone: label those marks directly, give them a separating outline or stroke, or add a pattern. Series 1 and 2 meet 3:1 on their own.
+
+Rules:
+
+- Never more than four series at once. Group the rest as "Other" in the remainder fill.
+- Fix colours per series when the order means something (reference before current); never let a charting library rotate through its palette.
+- Only one element is navy when the others are there for comparison.
+
+## Common cases
+
+| Case | Colours |
+| :-- | :-- |
+| One series | Series 1 |
+| Two series: reference or previous period, then current | Series 4, then series 1 |
+| Parts of a whole | Series 1, series 2, remainder fill; in the legend the remainder swatch is outlined |
+| States of an amount (paid, approved, claimed, not yet claimed) | Series 1, series 3, series 4 with its outline, and the upcoming part dashed in series 3; or the document mark styles of [colour](colour.md) |
+| 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 |
+
+## 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.
+
+## Sequential and diverging use
+
+There are no sequential or diverging ramp tokens yet.
+
+- **Sequential:** for an ordered quantity (low to high), use the existing tokens as a light-to-dark ramp of up to five steps: `--mq-chart-rest`, `--mq-chart-series-4`, `--mq-chart-series-3`, `--mq-chart-series-2`, `--mq-chart-series-1`. Their lightness falls monotonically. Do not interpolate new values by hand; if a chart needs more steps, bin the data into five classes or ask for a ramp token.
+- **Diverging:** documents have a single hue, so there is no second hue for the opposite side, and status colours are not allowed in charts. Until a diverging ramp is ruled, show the magnitude with the sequential ramp and the direction with the sign of the value and a mark style (filled for above the reference, outlined or dashed for below), with the reference line drawn as the baseline. This is an open point for the owner.
+
+## Marks
+
+- **Grid and axes:** no background grid. One baseline in `--mq-chart-baseline`, 1 px. No drawn vertical axis: at most three value labels on the left, without lines. Axis lines and ticks, where drawn, use `--mq-chart-axis` (non-text).
+- **Axis labels:** Geist Mono at `--mq-font-size-axis`, in tertiary text (`--mq-tertiary`), three to five ticks. Dates as `2024` or `10.2026` ([data patterns](data-patterns.md)).
+- **Value labels:** write only the value the text discusses (the peak, the latest value), in navy; leave about 18 % headroom above the tallest mark for it.
+- **Vertical bars:** rounded at the top with the small radius (3 px), square at the base, with a narrow gap between bars of a monthly series.
+- **Horizontal bars:** about 8 px thick, the far end rounded with the small radius, the value in Geist Mono at the end of the bar.
+- **Ring:** for parts of a whole, a thick stroke starting at the top, small gaps between arcs, no text in the centre, the legend beside it. Never a pie of more than four parts.
+- **Lines:** the main series in series 1 at 2 px with round caps; a reference in series 4 at 1.5 px; a projection in series 3 at 1.5 px dashed; an end dot in navy with its value above it. No area fill under a line and no smoothing.
+- **Annotations:** a dotted vertical marker in series 3 with a short sentence in Newsreader italic, muted; or a numeric note under the chart (the number in navy, then a sentence).
+- **Progress bar** (`mq-progress`): a quiet pale track (`--mq-accent-pale-2`), a navy fill, the value in Geist Mono beside it; a secondary value in series 3.
+- **Distribution bar** (`mq-distribution`, `mq-segment`): segments in palette order, the remainder dashed or in the remainder fill.
+- **Tooltips**, where a library draws them: navy background, white text, title in Outfit, values in Geist Mono, the small radius.
+
+Never: background grids, zebra bands, 3D, shadows on marks, area fills under lines, pies of more than four parts.
+
+## Ring construction
+
+Build a ring in SVG from one circle per part, so the arcs need no path arithmetic:
+
+1. Every circle has the same centre and radius, `fill="none"`, `pathLength="100"` (so lengths are percentages) and a thick stroke; wrap them in a group with `transform="rotate(-90 cx cy)"` so the first arc starts at the top.
+2. Check that the values sum to 100 before drawing.
+3. Each arc is drawn with `stroke-dasharray="L G"`, where the arc length L is its value minus the gap (1 unit) and G is 100 minus L. The arc is therefore one unit shorter than its value on purpose: that unit is the gap between arcs.
+4. Each arc starts where the previous ones end: `stroke-dashoffset` is minus the running total of the previous values (0, then minus the first value, and so on).
+5. The parts take series 1, 2, 3 in order. The remainder is two circles with the same dash: a `--mq-chart-series-4` arc 2 px wider, then a `--mq-chart-rest` arc over it, so the series 4 edge shows as its outline.
+6. Set the stroke colour with `style="stroke: var(--mq-chart-series-1)"`, never a literal value. No text in the centre; the legend sits beside the ring (`mq-legend is-column`).
+
+## Legends
+
+The legend is HTML (`mq-legend`, `mq-legend-item`, `mq-swatch`) placed above or beside the plot, never inside it. Beside a ring, use `mq-legend is-column`: the items in a column, each value in `mq-legend-value` at the right edge in Geist Mono, and the remainder item (`is-rest`) separated by a rule. Above a bar or line chart, use the plain `mq-legend`, one inline row. Swatches: `is-1` to `is-4`, `is-rest`, `is-outline` and `is-dashed`.
+
+## Size and motion
+
+- An SVG chart takes the full width of its figure, and its text sizes are in viewBox units. Because the SVG shrinks with its figure in print, size the labels for the printed width: they should read about 8 pt on paper.
+- On phones a wide chart keeps a minimum width and scrolls inside its frame.
+- Motion is optional and carries meaning: bars grow from the base, a line draws, an arc sweeps, all within two seconds. It stops under `prefers-reduced-motion` and never runs in print.