@medquantis/design-system 1.0.1 → 1.2.0

package/dist/kit/dark.css

@@ -0,0 +1,47 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * MedQuantis dark module of the homemade-claude-kit design contract 2.1.0. The roles are
+ * generated from tokens/kit/ by the design-system build, resolved in the dark theme (ADR-0007),
+ * on :root only; the kit's own dark layer remaps the light roles to them on a dark slide or page
+ * and draws the dark, dark-key and dark-accent classes. Do not edit this file. kit-manifest.json
+ * lists it. For kit renderers only: the unprefixed names collide with app and Tailwind variables.
+ */
+:root {
+  --dark-ink: #f5f4f1;
+  --dark-muted: #c3cbdc;
+  --dark-tertiary: #8f98aa;
+  --dark-canvas-bg: #11161f;
+  --dark-surface: #1a2131;
+  --dark-surface-2: #141a26;
+  --dark-border: rgba(255, 255, 255, 0.14);
+  --dark-accent: #6f88c9;
+  --dark-accent-ink: #11161f;
+  --dark-success: #6fbf73;
+  --dark-warning: #e0a040;
+  --dark-danger: #ff6b6b;
+  --dark-info: #64a8f0;
+  --dark-chart-1: #9fb3e8;
+  --dark-chart-2: #6f88c9;
+  --dark-chart-3: #5d6f91;
+  --dark-chart-4: #3a4560;
+  --dark-chart-rest: #232b3d;
+  --dark-chart-axis: #6b7385;
+  --dark-chart-grid: rgba(255, 255, 255, 0.1);
+  --dark-chart-highlight: #9fb3e8;
+  --dark-slide-bg: #11161f;
+  --dark-slide-fg: #f5f4f1;
+  --dark-doc-page-bg: #11161f;
+  --dark-doc-rule: rgba(255, 255, 255, 0.14);
+  --dark-print-bg: #11161f;
+  --dark-key-base: #2f4c8f;
+  --dark-accent-text: #9fb3e8;
+  --dark-shadow: 0px 1px 2px 0px rgba(0, 0, 0, 0.4);
+  --dark-key-edge: 0px 0px 0px 1px rgba(159, 179, 232, 0.35);
+  --dark-key-fill: linear-gradient(160deg, #2f4c8f 0%, #0f2a5e 100%);
+}
+
+/*
+ * No class rule (Plan-0003 increment 04): the kit's own dark layer remaps the roles to their
+ * --dark- twins on a dark slide or page and draws .dark-key and .dark-accent from the dark roles,
+ * so a rule here would compete with it. The dark roles come from tokens/kit/, on :root only.
+ */

package/dist/kit/dataviz.css

@@ -0,0 +1,16 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * MedQuantis values for the dataviz module of the homemade-claude-kit design contract 2.1.0,
+ * generated from tokens/kit/ by the design-system build. Do not edit. kit-manifest.json lists it.
+ * For kit renderers only: the unprefixed names collide with app and Tailwind variables.
+ */
+:root {
+  --chart-1: #0a2463;
+  --chart-2: #5d6f91;
+  --chart-3: #8795b3;
+  --chart-4: #c3cbdc;
+  --chart-rest: #dde3ee;
+  --chart-axis: #8c8c8c;
+  --chart-grid: #dddbd6;
+  --chart-highlight: #0a2463;
+}

package/dist/kit/document.css

@@ -0,0 +1,104 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * MedQuantis document module of the homemade-claude-kit design contract 2.1.0. The roles are
+ * generated from tokens/kit/ by the design-system build; the class rules after them are copied
+ * from css/kit/document.css, written by hand against contract roles. Do not edit this file.
+ * kit-manifest.json lists it. For kit renderers only: the unprefixed names collide with app and
+ * Tailwind variables.
+ */
+:root {
+  --doc-page-bg: #fafaf8;
+  --doc-text-size: 16.5px;
+  --doc-rule: #dddbd6;
+}
+
+/*
+ * Class rules of the MedQuantis document module for the homemade-claude-kit renderers
+ * (com-slide-deck mode: document; Plan-0002 increment 02). Written by hand against contract roles
+ * only: core, type, space-shape, dataviz and the document roles, which tokens/kit/ maps. The
+ * build copies these rules into dist/kit/document.css after the roles. build/kit-classes.md names
+ * the MedQuantis rule each class reproduces: the A4 sheet of css/print.css (mq-page) with the
+ * body text of css/base.css (mq-doc).
+ *
+ * Cascade: com-slide-deck adds its document baseline (doc.baseline.css) after the design layer,
+ * so the rules it also writes carry one more element in their selector. The page box and the
+ * print margins stay the deck's config.yaml page: block.
+ */
+
+/* mq-page and mq-doc: the sheet on the canvas colour (owner ruling 9), Newsreader body. */
+body .doc {
+  background: var(--doc-page-bg);
+  color: var(--ink);
+  font-family: var(--font-body);
+  font-size: var(--doc-text-size);
+  font-weight: var(--font-weight-regular);
+  line-height: var(--line-height-body);
+}
+
+/* Headings in Outfit 500, never 700 (owner ruling 4, guidelines/typography.md). */
+.doc h1,
+.doc h2,
+.doc h3 {
+  margin: var(--space-lg) 0 var(--space-sm);
+  color: var(--ink);
+  font-family: var(--font-heading);
+  font-weight: var(--font-weight-bold);
+  line-height: var(--line-height-tight);
+}
+
+.doc h1 {
+  font-size: var(--title-size);
+  letter-spacing: -0.015em;
+}
+
+.doc h2 {
+  font-size: var(--font-size-lg);
+  letter-spacing: -0.01em;
+}
+
+.doc h3 {
+  font-size: var(--font-size-md);
+}
+
+.doc p {
+  margin: 0 0 var(--space-md);
+}
+
+/* A section opens with its own head; its first element keeps no top margin. */
+.doc-section > :first-child {
+  margin-top: 0;
+}
+
+/* A section that follows on the same page: a hairline rule and the space between sections. */
+body .doc-section.doc-section--flow {
+  margin-top: var(--space-xl);
+  padding-top: var(--space-lg);
+  border-top: var(--border-width) solid var(--doc-rule);
+}
+
+/* mq-eyebrow: Geist Mono 500 capitals in navy above a heading. */
+.doc-label {
+  margin: 0 0 var(--space-sm);
+  color: var(--accent);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-bold);
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+}
+
+/* A block that never splits across pages (guidelines/layout.md, Print and PDF). */
+body .doc-keep {
+  break-inside: avoid;
+  page-break-inside: avoid;
+}
+
+/* In a document the source bar flows as a footnote: the kit's base slide-frame positions it on
+   a slide canvas, which a document does not have. */
+.doc .slide-source-bar {
+  position: static;
+  color: var(--muted);
+  font-family: var(--font-body);
+  font-size: var(--font-size-sm);
+  font-style: italic;
+}

package/dist/kit/guidance.md

@@ -0,0 +1,400 @@
+# MedQuantis guidance for the delivery-comms kit
+
+Generated from guidelines/ by the design-system build. Do not edit. The MedQuantis guideline sections behind each module this package provides; token names are the --mq-* names of tokens.css, which the kit roles of each module alias. The kit treats this file as informational.
+
+## core
+
+Source: guidelines/colour.md, guidelines/typography.md, guidelines/layout.md, guidelines/accessibility.md.
+
+### Colour: The medium split
+
+| 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 |
+
+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.
+
+### Colour: Accent
+
+| Token | Value | Use |
+| :-- | :-- | :-- |
+| `--mq-accent` | `#0a2463` | The single accent: key figures, links, active states, the key column of a table, top and edge rules, series 1, navy panels |
+| `--mq-accent-hover` | `#061a4d` | Hover and pressed state of a link or an accent control, nothing else |
+| `--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.
+
+### Colour: Neutrals
+
+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 |
+| :-- | :-- | :-- | :-- |
+| `--mq-ink` | `#1a1a1a` | Primary text and values | 16.65:1 on canvas |
+| `--mq-muted` | `#555555` | Secondary text, leads, captions | 7.13:1 on canvas |
+| `--mq-tertiary` | `#707070` | Tertiary text: notes, footers, axis labels, placeholders (owner ruling 1) | 4.74:1 on canvas, 4.95:1 on surface |
+| `--mq-decoration` | `#8c8c8c` | Non-text decoration only: axis lines, ticks, an icon beside its label. Never text (owner ruling 1) | 3.22:1 on canvas |
+| `--mq-canvas` | `#fafaf8` | Background of every document page: A4 report, paper, slide (owner ruling 9) | |
+| `--mq-surface` | `#ffffff` | Cards, panels, tables, figures, inputs | |
+| `--mq-surface-alt` | `#f5f4f1` | Recessed areas: table headers, tab bars, grouped areas, hover | |
+| `--mq-desk` | `#e9e8e4` | On screen only, around a page preview; never inside a document, so a printed page is never grey (owner ruling 9) | |
+| `--mq-border` | `#dddbd6` | Borders, dividers, chart baselines | decorative |
+| `--mq-border-light` | `#ebeae6` | Hairlines between rows and columns, card borders | decorative |
+| `--mq-border-strong` | `#5d6f91` | Outline of outlined and dashed state marks | 4.84:1 on canvas, non-text |
+
+Why a warm canvas: pure white reads clinical and generic; the warm off-white reads institutional while white cards still stand out on it. Tertiary text sits exactly at 4.50:1 on `--mq-surface-alt`, so put it on canvas or surface, not on the recessed grey.
+
+### Typography: Three families, three roles
+
+| Family | Token | Role |
+| :-- | :-- | :-- |
+| Outfit | `--mq-font-family-heading`, `--mq-font-family-ui` | Headings, column titles, hero figures, labels, table text, takeaways; the whole UI of apps (navigation, buttons, badges, UI body text) |
+| Newsreader | `--mq-font-family-body` | Reading text: body of documents and slides, leads, captions, notes, quoted official text, and regulatory text in apps. The only serif (owner ruling 10) |
+| Geist Mono | `--mq-font-family-mono` | Codes, figures in tables, dates in tables, eyebrows, axis labels, identifiers |
+
+Georgia and Times New Roman appear only as fallbacks. The three families are self-hosted (`fonts/fonts.css`, variable woff2 with latin and latin-ext); no page loads a font from a remote service. Newsreader ships its true italic, so leads and notes are never a slanted roman.
+
+Outfit was chosen because it reads cleanly from a display title down to an 11 px badge, with a geometric, contemporary character that stays distinct from the generic interface sans-serifs.
+
+### Layout: 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`, 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.
+
+### Accessibility: 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);
+- a change in a figure is shown by its sign, not by a colour or an arrow alone.
+
+## dataviz
+
+Source: guidelines/charts.md.
+
+### Charts: 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.
+
+### Charts: 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.
+
+### Charts: 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).
+- **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.
+
+## type
+
+Source: guidelines/typography.md.
+
+### Typography: Weights
+
+| Weight | Token | Use |
+| :-- | :-- | :-- |
+| Outfit 500 | `--mq-font-weight-heading` | Every heading, column title, hero figure, KPI value, label, button label and badge (owner ruling 4) |
+| Outfit 600 | `--mq-font-weight-emphasis` | Only a short highlighted word inside body text, as the "Med" of the wordmark. Bold inside Newsreader prose switches to Outfit 600 at about 0.94 em |
+| Outfit 400 | `--mq-font-weight-body` | App UI body text |
+| Outfit 300 | `--mq-font-weight-light` | Only the "Quantis" half of the wordmark |
+| Newsreader 400 | `--mq-font-weight-body` | Reading text, with its italic for leads and notes |
+| Geist Mono 400 and 500 | | Table figures and codes 400, eyebrows 500 |
+
+Weights 700 and 800 appear only inside the monogram files; no heading, button or table uses them.
+
+### Typography: Roles and sizes
+
+Every size is a token. The print column gives the A4 scale for reports printed from a browser; it is not yet a token (open point).
+
+| Role | Family and style | Screen token | Screen | Print (A4) |
+| :-- | :-- | :-- | :-- | :-- |
+| Hero title (`mq-display`) | Outfit 500, line height 1.04 to 1.08, letter spacing about -0.025 em | `--mq-font-size-hero-min` to `--mq-font-size-hero-max` | 34 to 56 px | 26 pt |
+| Slide title (`mq-slide-title`) | Outfit 500, line height 1.15 | `--mq-font-size-slide-title` | 36 px | |
+| Section title (`mq-title`) | Outfit 500, line height 1.15, about -0.015 em | `--mq-font-size-h2` | 32 px | 17 pt |
+| Subsection, card and column title (`mq-subtitle`, `mq-card-title`) | Outfit 500, about -0.01 em | `--mq-font-size-h3` | 20 px | 12.5 pt |
+| Lead (`mq-lead`) | Newsreader italic, muted, line height 1.5 | `--mq-font-size-lead` | 18 px | 11.5 pt |
+| Body (`mq-doc`, `mq-prose`) | Newsreader 400, line height 1.6 | `--mq-font-size-body` | 16.5 px | 10 pt |
+| Small text, figure caption | Newsreader | `--mq-font-size-small` | 15 px | 9.5 pt |
+| Label (`mq-label`) | Outfit 500, muted | `--mq-font-size-label` | 13 px | 8.5 pt |
+| Eyebrow (`mq-eyebrow`) | Geist Mono 500, capitals, letter spacing 0.16 to 0.18 em, navy | `--mq-font-size-eyebrow` | 11 px | 7.5 pt |
+| Hero figure (`mq-figure`) | Outfit 500, tabular figures, navy | `--mq-font-size-figure` | 50 px | 28 pt |
+| KPI value (`mq-kpi-value`) | Outfit 500, tabular figures | `--mq-font-size-kpi` | 30 px | 17 pt |
+| Counter value | Outfit 500, tabular figures, navy | `--mq-font-size-stat` | 24 px | 14 pt |
+| Table header | Geist Mono, capitals, small letter spacing | `--mq-font-size-table-header` | 11 px | 7 pt |
+| Table figure (`mq-num`) | Geist Mono 400, tabular figures, right-aligned | `--mq-font-size-table-cell` | 13 px | 8.5 pt |
+| Table text | Outfit 500 (first column) or Newsreader | `--mq-font-size-table-text` | 14 px | 8.5 pt |
+| Takeaway (`mq-takeaway`) | Outfit 500 | `--mq-font-size-takeaway` | 16 px | 10.5 pt |
+| Note, source, illustrative mention (`mq-note`, `mq-foot`) | Newsreader italic, tertiary | `--mq-font-size-note` | 12.5 px | 8 pt |
+| Chart axis label | Geist Mono, tertiary | `--mq-font-size-axis` | 11 px | about 8 pt on paper |
+
+Rules:
+
+- **Floor:** no text below 11 px on screen, in any medium, including table headers and badges.
+- **Letter spacing** is negative on titles and tightens as the size grows: about -0.01 em near 20 px, -0.015 em near 32 to 38 px, -0.025 em at 56 px and above. Body text keeps the font's own spacing.
+- **Figures** always use tabular figures (`font-variant-numeric: tabular-nums`, or `mq-mono`), so columns of numbers align.
+- **Eyebrows and section labels** are typed in normal case and set in capitals by CSS; a middle dot separates their parts: "02 · Amounts by year".
+
+### Typography: Line height
+
+| Context | Line height |
+| :-- | :-- |
+| Hero titles | 1.04 to 1.08 |
+| Headings, counters, stat figures | 1.15 to 1.3 |
+| Leads | 1.5 |
+| App UI text, labels, descriptions | 1.55 |
+| Reading text in documents | 1.6 |
+| Help text and longer descriptions in apps | 1.75 |
+| Regulatory text in apps (dense legal prose read under time pressure) | 2.2, and 2.0 on phones |
+
+Long regulatory text is set in Newsreader at about 15 px with that generous line height, so long German compounds stay separable line by line. Codes inside it are set in Geist Mono at 12 px on the recessed surface with the small radius. Dense tables keep tight padding; the breathing room goes to the text people read word by word.
+
+## space-shape
+
+Source: guidelines/layout.md.
+
+### Layout: Widths and spacing
+
+All spacing comes from the 4 and 8 px scale (`--mq-space-1` to `--mq-space-8`: 4, 8, 12, 16, 24, 32, 48, 72 px). No other spacing value.
+
+| Measure | Token | Value |
+| :-- | :-- | :-- |
+| Page width | `--mq-page-width` | 1040 px |
+| Reading measure: prose, leads, in-brief, callouts stop here | `--mq-page-measure` | 760 px |
+| Side gutter | `--mq-space-6` | 32 px, 16 px (`--mq-space-4`) on phones |
+| Between cards | `--mq-space-5` | 24 px |
+| Between calm columns | `--mq-space-7` | 48 px |
+| From a section head to its content | `--mq-space-6` | 32 px |
+| Between sections | `--mq-space-8` | 72 px, 48 px on phones |
+
+Figures, tables and grids take the full page width; running text never does.
+
+Grids: calm columns (three columns separated by thin rules, no boxes, one hero figure each), two-column and three-column grids of cards or figures. On phones every grid becomes one column, and a band of four tiles becomes two by two.
+
+### Layout: Radius
+
+Owner ruling 3, as amended on 2026-10-10:
+
+| Token | Value | For |
+| :-- | :-- | :-- |
+| `--mq-radius-small` | 3 px | Small items: tags, chips, badges, inputs, buttons, progress tracks, bar ends, tooltips |
+| `--mq-radius-medium` | 6 px | Cards, panels, KPI tiles, figures, icon pills, slide frames. The maximum anywhere else |
+| `--mq-radius-overlay` | 12 px | Apps only: dialogs and modals, side drawers and command palettes. Never in documents, slides, cards or website media |
+
+- No pill shapes, ever: no fully rounded buttons, tags, chips or tabs.
+- A circle is allowed only for something that is genuinely round: a status dot, a numbered marker, an avatar. In Tailwind that is `rounded-full`, and only there.
+- In `dist/tailwind.css` the steps `rounded`, `rounded-xs` and `rounded-sm` resolve to 3 px, `rounded-md` to `rounded-4xl` to 6 px, and `rounded-overlay` to 12 px, so no utility class can exceed the ruling. The shared stylelint config rejects any other radius.
+
+Squared-off corners read professional and institutional; pills read consumer.
+
+## document
+
+Source: guidelines/layout.md.
+
+### Layout: Print and PDF
+
+- `css/print.css` prints colours exactly (`print-color-adjust: exact`), so navy headers and panels do not print white, and stops all animation.
+- Every document page uses the canvas colour (owner ruling 9); the desk never reaches paper.
+- Figures, cards, panels, KPI bands, callouts, takeaways, table rows and source items never split across pages, and a heading is never left alone at the foot of a page.
+- Before sending a PDF, check it page by page.
+
+## slide-frame
+
+Source: guidelines/layout.md.
+
+### Layout: Media
+
+| 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); 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 |
+
+## dark
+
+Source: guidelines/colour.md.
+
+### Colour: 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-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 |
+
+## print
+
+Source: guidelines/layout.md.
+
+### Layout: Report skeleton
+
+1. A navy header: navy gradient, the on-navy wordmark, a mono kicker preceded by a short rule, the title in white Outfit 500, one sentence that carries the message (its first clause in white, the rest in on-navy secondary), and a row of metadata (author, scope, date) separated by on-navy rules. The header is a pattern, not yet a shared component.
+2. "In brief": three or four self-contained sentences with the figure that matters, under a 2 px navy rule.
+3. Sections. Each opens with a head (numbered eyebrow such as "02 · Amounts by year", title, one-sentence lead), then its blocks, then, when useful, one takeaway line (`mq-takeaway`).
+4. The footer (`mq-foot`): a rule, the numbered sources, then the legal line and the date (brand).
+
+A source is cited in the text with a small superscript number in Geist Mono, navy, pointing to the numbered source list.
+
+## brand
+
+Source: guidelines/brand.md.
+
+### Brand: 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.
+
+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 |
+| :-- | :-- | :-- | :-- | :-- |
+| 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 |
+
+### Brand: 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 and on every dark surface, at every size (owner rulings 6 and 14).
+
+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.
+- 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.
+
+### Brand: 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` |
+
+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.
+
+### Brand: 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.