@medquantis/design-system 1.1.0 → 1.3.0

package/README.md

@@ -11,13 +11,14 @@ The single source of the MedQuantis visual identity: design tokens, shared CSS,
 | `dist/tokens.css` | Every consumer: `--mq-*` custom properties ([ADR-0006](docs/architecture/decisions/adr-0006-mq-token-prefix.md)) |
 | `dist/tokens.json` | Scripts and pipelines that need resolved values |
 | `dist/tailwind.css` | Tailwind 4 and Nuxt UI apps (`@theme` with 50 to 950 scales); imports `tokens.css` itself |
+| `dist/themes/dark.css`, `dist/themes/dark.json` | The dark theme: the semantic roles re-valued under `.dark`, for apps, documents and slides (see Dark theme) |
 | `dist/kit-contract.css` | homemade-claude-kit renderers only, deployed as `docs/ux/tokens.css`; never loaded in an app. Carries the latin fonts as embedded data, since the renderers inline this one file |
 | `css/` | Shared `mq-` components, slide canvas and A4 print styles for build-less media (see Shared CSS) |
 | `fonts/fonts.css` | Self-hosted Outfit, Newsreader and Geist Mono (variable woff2, latin and latin-ext, relative paths); deploy the folder whole |
 | `icons/lucide.min.js` | A pinned Lucide build (version and hash in `icons/manifest.json`) |
 | `brand/` | Monogram, favicon set and wordmark: `wordmark-on-light` and `wordmark-on-navy`, live text for screen and `-print` with outlined text |
-| `guidelines/` | Brand, voice, colour, typography, chart, data and accessibility rules |
-| `kit-manifest.json`, `dist/kit/` | The homemade-claude-kit delivery-comms renderers (contract 2.0.0): the manifest declares nine modules, each a file in `dist/kit/` (see Using it from the delivery-comms kit) |
+| `guidelines/` | Brand, voice, colour, typography, chart, data and accessibility rules, and the app patterns of dense internal tools |
+| `kit-manifest.json`, `dist/kit/` | The homemade-claude-kit delivery-comms renderers (contract 2.1.0): the manifest declares ten modules, each a file in `dist/kit/` (see Using it from the delivery-comms kit) |
 | `dist/DESIGN.md` | Tools and agents outside the kit: the tokens as [Google DESIGN.md](https://github.com/google-labs-code/design.md) front matter, then the guidelines as prose |
 | `dist/llms.txt`, `dist/llms-full.txt` | The guidelines and the token list for language models ([llmstxt.org](https://llmstxt.org/) format), generated from `guidelines/` and the tokens |
 | `plugins/medquantis-design-system/` | The Claude skill, as a Claude Code plugin and as a zip for claude.ai (see Claude skill) |
@@ -59,6 +60,7 @@ Every `mq-` component is `trial` until a consumer uses it in production; it beco
 | Distribution bar | `mq-distribution`, `mq-segment` | `css/components.css` | trial |
 | Legend | `mq-legend` (`is-column`, `mq-legend-value`), `mq-swatch` | `css/components.css` | trial |
 | Takeaway | `mq-takeaway` | `css/components.css` | trial |
+| Monogram | `mq-monogram` | `css/components.css` | trial |
 | Footer | `mq-foot` | `css/components.css` | trial |
 | Slide canvas | `mq-slide` (`mq-slide-label`, `-title`, `-body`, `-foot`, `-number`) | `css/slide.css` | trial |
 | A4 page and desk | `mq-page`, `mq-desk`, `mq-no-print` | `css/print.css` | trial |
@@ -66,9 +68,27 @@ Every `mq-` component is `trial` until a consumer uses it in production; it beco
 
 Consumers lint their own CSS with the same rules: `export { default } from "@medquantis/design-system/stylelint";` in their `stylelint.config.mjs`. It rejects literal colours, fonts and shadows, `!important`, unknown custom properties, any radius other than the three `--mq-radius-*` tokens (so no pill shape can be drawn), and a local `--app-*`, `--site-*`, `--viz-*` or `--deck-*` property set to a literal instead of a `var(--mq-*)` reference (a `calc()` that scales tokens by a plain number is allowed). The config loads two stylelint plugins that the package does not install for you, so a consumer that lints adds them as its own dev dependencies, at the versions this release is tested with: `npm install --save-dev --save-exact stylelint@17.16.0 stylelint-declaration-strict-value@1.12.1 stylelint-value-no-unknown-custom-properties@6.1.1`.
 
+## Dark theme
+
+MedQuantis has one dark theme ([ADR-0007](docs/architecture/decisions/adr-0007-medquantis-has-a-dark-theme.md)). It re-values the semantic `--mq-*` roles under the `.dark` class and ships in its own files: `dist/themes/dark.css` (exported as `@medquantis/design-system/themes/dark.css`) and its resolved values in `dist/themes/dark.json`. `tokens.css` keeps the light values only, and a role the theme does not name keeps its light value, so the `mq-` components and the Tailwind utilities, which all read `var(--mq-*)`, turn dark with no second class name. The values and every contrast pair are in [guidelines/colour.md](guidelines/colour.md), Dark theme.
+
+- **Opt in:** load `themes/dark.css` after `tokens.css` (or after `tailwind.css`, which imports it), then set `.dark` on `<html>` for a whole page, or on one slide. The design system never switches on `prefers-color-scheme` by itself.
+- **Apps:** the app decides how the viewer chooses, and may follow the viewer's setting by toggling `.dark`. A Tailwind 4 app declares the class as its dark variant, since Tailwind's `dark:` follows `prefers-color-scheme` by default; Nuxt UI 4 already declares it, so a Nuxt UI app adds only the theme file.
+
+```css
+@import "tailwindcss";
+@import "@medquantis/design-system/tailwind.css";
+@import "@medquantis/design-system/themes/dark.css";
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+- **Documents and decks** (A4 reports, papers, PDFs, slides): light or dark is the author's choice, set at build time by putting `.dark` in the page, never taken from the reader's screen. A dark document stays dark in its PDF; light stays the default for anything likely to be printed on paper. Through the kit, see Using it from the delivery-comms kit.
+
+`.dark` is a generic class name: a page that loads `themes/dark.css` and already uses `.dark` for something else gets the theme there too.
+
 ## Specimen
 
-The specimen is the visual reference of the design system: every colour token with its contrast pairings and their allowed use, the type scale, the radii and shadows, every `mq-` component, a 1280 x 720 slide, an A4 page, the brand files and the app status layer. `make specimen` generates it into `dist/specimen/index.html` from `dist/tokens.json`, `css/` and the fictitious data in `examples/`; open that file in a browser. The folder holds its own copies of the CSS, fonts and brand files, so it works offline and requests nothing outside itself. It is never edited by hand and never committed. `make build` does not build it, so the package outputs stay free of it.
+The specimen is the visual reference of the design system: every colour token with its contrast pairings and their allowed use, the type scale, the radii and shadows, every `mq-` component, a 1280 x 720 slide, an A4 page, the brand files and the app status layer. `make specimen` generates it into `dist/specimen/index.html` from `dist/tokens.json`, `css/` and the fictitious data in `examples/`, and the same page in the dark theme into `dist/specimen/dark.html` from `dist/themes/dark.json`; open either file in a browser. The folder holds its own copies of the CSS, fonts and brand files, so it works offline and requests nothing outside itself. It is never edited by hand and never committed. `make build` does not build it, so the package outputs stay free of it.
 
 `make test` runs the unit tests, then Playwright and axe on the specimen: WCAG 2.2 AA with no serious or critical violation, no request outside the folder, a tagged PDF export, and screenshot baselines of each part of the page (header, every section, footer) and of the focus ring in `tests/e2e/specimen.spec.mjs-snapshots/`. The browser is Playwright's own Chromium headless shell, whose build is pinned by the exact `@playwright/test` version; `make browsers` installs it locally and CI installs the same build, so the baselines compare like with like. After a deliberate visual change, regenerate the baselines with `node_modules/.bin/playwright test --update-snapshots` and review the new images in the PR. When the CI job fails, it uploads Playwright's `test-results/` (actual, expected and diff images) as the `playwright-test-results` artifact, kept for 7 days.
 
@@ -110,15 +130,17 @@ Every other shipped file (`css/*.css`, `fonts/fonts.css`, `dist/kit-contract.css
 
 ## Using it from the delivery-comms kit
 
-The homemade-claude-kit renders decks (`com-slide-deck`), artefact views (`com-artefact-viz`) and release notes (`com-release-note`) with the design system a project pins. A project pins this package once, with the kit's `ux-design-system` skill, at an exact version (1.1.0 is the first release with the kit modules):
+The homemade-claude-kit renders decks (`com-slide-deck`), artefact views (`com-artefact-viz`) and release notes (`com-release-note`) with the design system a project pins. A project pins this package once, with the kit's `ux-design-system` skill, at an exact version (1.1.0 is the first release with the kit modules; 1.2.0 adds the `dark` module and the classification cell):
 
 ```sh
-python3 <skill-dir>/scripts/design_system.py point @medquantis/design-system@1.1.0
+python3 <skill-dir>/scripts/design_system.py point @medquantis/design-system@1.2.0
 ```
 
-In the kit's words this is `ux-design-system point @medquantis/design-system@1.1.0`. It writes the pin to `docs/ux/package.json`, checks the package's `kit-manifest.json` through the kit resolver and prints the Dependabot entry (`directory: "/docs/ux"`) that turns later releases into pull requests. Change the pin only with `point`, never by hand, and never add a `docs/ux/tokens.css`. Each render writes `<output>.provenance.json`, which names the module each value came from.
+In the kit's words this is `ux-design-system point @medquantis/design-system@1.2.0`. It writes the pin to `docs/ux/package.json`, checks the package's `kit-manifest.json` through the kit resolver and prints the Dependabot entry (`directory: "/docs/ux"`) that turns later releases into pull requests. Change the pin only with `point`, never by hand, and never add a `docs/ux/tokens.css`. Each render writes `<output>.provenance.json`, which names the module each value came from.
 
-`kit-manifest.json`, at the top of the package, declares all nine modules of the contract, so the kit's base theme fills none of them:
+The kit modules of 1.2.0 need delivery-comms 2.1.0 or later: the manifest declares contract 2.1.0 and the `dark` module, and a 2.0 kit refuses the unknown `dark` module. A project on a 2.0 kit updates the kit before it points at 1.2.0, or stays on 1.1.0.
+
+`kit-manifest.json`, at the top of the package, declares all ten modules of the contract, so the kit's base theme fills none of them:
 
 | Module | File | Carries |
 | :-- | :-- | :-- |
@@ -127,12 +149,15 @@ In the kit's words this is `ux-design-system point @medquantis/design-system@1.1
 | `type` | `dist/kit/type.css` | The type scale, the body and tight line heights, weights 400 and 500 |
 | `space-shape` | `dist/kit/space-shape.css` | The smallest and largest spacing steps, the small radius, the 6 px maximum radius (no pill shapes) and the hairline stroke |
 | `document` | `dist/kit/document.css` | The A4 document: page colour, text size, rules, and the MedQuantis rules for the kit's document classes |
-| `slide-frame` | `dist/kit/slide-frame.css` | The 1280 by 720 slide: canvas, padding, section label, and the footer row with the legal line and slide number |
+| `slide-frame` | `dist/kit/slide-frame.css` | The 1280 by 720 slide: canvas, padding, section label, and the footer row with the legal line, the classification cell and the slide number |
+| `dark` | `dist/kit/dark.css` | The dark twin of every colour role (`--dark-<role>`), with the MedQuantis dark values, and the key element on dark: the navy panel gradient with its 1 px light-navy outline, never a glow |
 | `print` | `dist/kit/print.css` | The release-note report: page size, margins, and breaking changes in navy, never a status hue |
-| `brand` | `dist/kit/brand.css` | The wordmarks on light and on navy, the monogram and the legal line |
+| `brand` | `dist/kit/brand.css` | The outlined (`-print`) wordmarks on light and on navy, since kit pages and PDFs cannot load the web font into an image; the monogram and the legal line |
 | `guidance` | `dist/kit/guidance.md` | The rules from `guidelines/` that the kit's skills read before writing a page |
 
-The kit lines a consumer repository adds to its `AGENTS.md` (or `CLAUDE.md`) are the kit's own: copy the [AGENTS.md block of `ux-design-system`](https://github.com/VictorHueni/homemade-claude-kit/blob/release/2.0/plugins/delivery-comms/skills/ux-design-system/references/agents-md-block.md) as it stands at the kit version you use, rather than a copy kept here. Below it, add the MedQuantis lines:
+A kit deck turns dark per slide, with `dark` on the slide's root (`<div class="slide dark">`), or whole, with `theme: dark` in its `config.yaml`, which also serves a `mode: document`; the kit draws the key element (`dark-key`) and the highlighted text (`dark-accent`) from the `dark` roles. `classification:` in `config.yaml` prints the deck's classification at the right of the footer, before the slide number, in the small tertiary mono of the legal line: the label only, in the deck's language (`lang:`), never a code ([guidelines/brand.md](guidelines/brand.md)).
+
+The kit lines a consumer repository adds to its `AGENTS.md` (or `CLAUDE.md`) are the kit's own: copy the [AGENTS.md block of `ux-design-system`](https://github.com/VictorHueni/homemade-claude-kit/blob/main/plugins/delivery-comms/skills/ux-design-system/references/agents-md-block.md) as it stands at the kit version you use, rather than a copy kept here. Below it, add the MedQuantis lines:
 
 ```markdown
 ## MedQuantis brand
@@ -181,7 +206,7 @@ make skill-zip    # zip the skill for claude.ai into dist/
 make kit-check    # run the homemade-claude-kit resolver and renderers on the packed package (needs KIT_DIR)
 ```
 
-`make kit-check` packs the package as npm would publish it, unpacks it into a fresh temporary folder and runs the kit resolver (`plugins/delivery-comms/shared/design_source.py provenance`) on it, through the kit's own mise environment, expecting all nine modules from this package. It then renders the fictitious fixtures of `tests/fixtures/kit-render/` with the kit's own renderers (a deck, an A4 document and a release-note report) and requires `PASS: no findings` from the kit validator `check_render.py` on each; `KIT_CHECK_OUT=<folder>` keeps a copy of the three pages. `KIT_DIR` names a local homemade-claude-kit checkout, for example `KIT_DIR=../homemade-claude-kit make kit-check`; without it the target prints a skip message and exits 0. It is a separate gate, not part of `make check`, because CI has no kit checkout. `kit-manifest.json` is a build output at the repository root (gitignored), because the kit reads the manifest only at the top of the package.
+`make kit-check` packs the package as npm would publish it, unpacks it into a fresh temporary folder and runs the kit resolver (`plugins/delivery-comms/shared/design_source.py provenance`) on it, through the kit's own mise environment, expecting all ten modules from this package. It then renders the fictitious fixtures of `tests/fixtures/kit-render/` with the kit's own renderers (a deck, an A4 document and a release-note report) and requires `PASS: no findings` from the kit validator `check_render.py` on each; `KIT_CHECK_OUT=<folder>` keeps a copy of the three pages. `KIT_DIR` names a local homemade-claude-kit checkout, for example `KIT_DIR=../homemade-claude-kit make kit-check`; without it the target prints a skip message and exits 0. It is a separate gate, not part of `make check`, because CI has no kit checkout. `kit-manifest.json` is a build output at the repository root (gitignored), because the kit reads the manifest only at the top of the package.
 
 `fonts/` and `icons/` are committed copies of exact-pinned packages because they ship in the npm package; a unit test fails when they drift, so a Dependabot bump of a font or of Lucide needs `make assets` in the same PR. The screen wordmarks use live text, which renders in Outfit only where the page loads `fonts.css` (inline SVG); in an `<img>` use the `-print` variant.
 

package/css/app.css

@@ -53,6 +53,6 @@
   :where(.mq-status.is-warning.is-filled) {
     border-color: transparent;
     background-color: var(--mq-warning-fill);
-    color: var(--mq-ink);
+    color: var(--mq-on-warning-fill);
   }
 }

package/css/components.css

@@ -1,7 +1,7 @@
 /*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
 /*
  * MedQuantis document components: cards, navy panel, KPI tiles, table, badges, callout,
- * progress and distribution bars, legend, takeaway and footer.
+ * progress and distribution bars, legend, takeaway, monogram and footer.
  * Documents are navy-only (ADR-0004): states read by mark style (solid, ring, pale, outline,
  * quiet, dashed), never by a status hue. Status badges live in app.css.
  * Text on a navy or tinted background names it in a mq-bg comment, so the contrast test can
@@ -150,6 +150,7 @@
   :where(.mq-kpi.is-navy) {
     border-color: transparent;
     background: linear-gradient(160deg, var(--mq-panel-start), var(--mq-panel-end));
+    box-shadow: var(--mq-shadow-edge);
   }
 
   :where(.mq-kpi.is-navy .mq-kpi-label, .mq-kpi.is-navy .mq-kpi-caption) {
@@ -174,7 +175,7 @@
 
   :where(.mq-kpi.is-pale .mq-kpi-value) {
     /* mq-bg: --mq-accent-pale */
-    color: var(--mq-accent);
+    color: var(--mq-accent-highlight);
   }
 
   /* Table */
@@ -223,6 +224,11 @@
     background-color: var(--mq-accent-pale);
   }
 
+  :where(.mq-table tr.is-highlight > .is-key) {
+    /* mq-bg: --mq-accent-pale */
+    color: var(--mq-accent-highlight);
+  }
+
   :where(.mq-table tr.is-total > td) {
     border-top: var(--mq-stroke-strong) solid var(--mq-accent);
     border-bottom: 0;
@@ -258,7 +264,7 @@
 
   :where(.mq-badge.is-pale) {
     background-color: var(--mq-accent-pale);
-    color: var(--mq-accent);
+    color: var(--mq-accent-highlight);
   }
 
   :where(.mq-badge.is-outline) {
@@ -292,7 +298,7 @@
   :where(.mq-callout-title) {
     /* mq-bg: --mq-accent-pale-2 */
     margin: 0 0 var(--mq-space-1);
-    color: var(--mq-accent);
+    color: var(--mq-accent-highlight);
     font-family: var(--mq-font-family-mono);
     font-size: var(--mq-font-size-eyebrow);
     letter-spacing: 0.14em;
@@ -456,6 +462,16 @@
     line-height: 1.4;
   }
 
+  /* Monogram: the brand file at 48 px, where its corners of 8/64 of the side are the 6 px
+     radius, so the panel's edge it takes on dark follows them (owner ruling 14). */
+  :where(.mq-monogram) {
+    display: block;
+    width: var(--mq-space-7);
+    height: var(--mq-space-7);
+    border-radius: var(--mq-radius-medium);
+    box-shadow: var(--mq-shadow-edge);
+  }
+
   /* Footer: sources, legal line, illustrative-data note */
   :where(.mq-foot) {
     margin: var(--mq-space-6) 0 0;

package/css/kit/dark.css

@@ -0,0 +1,6 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * 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/css/kit/slide-frame.css

@@ -8,8 +8,9 @@
  * right (owner ruling 11, guidelines/brand.md).
  *
  * Cascade: the kit inlines its base slide-frame.css before this module, so these rules restyle
- * it; com-slide-deck adds its baseline (controls hint, presentation mode) after the design layer,
- * so the rules for those classes carry one more element in their selector.
+ * it; com-slide-deck adds its baseline (controls hint, presentation mode) and the classification
+ * cell after the design layer, so the rules for those classes carry one more element in their
+ * selector.
  * The footer row and the source line use --tertiary, the tertiary grey of owner ruling 1.
  */
 
@@ -56,6 +57,18 @@
   margin: 0;
 }
 
+/* The deck's classification (owner ruling 17): at the right of the footer row, before the number,
+   in the legal line's small tertiary mono, the label as written in the deck's language. The kit's
+   cell rule (margin-left: auto, capitals) comes after the design layer, so this one carries the
+   footer in its selector. */
+.slide-footer .slide-classification {
+  margin-left: auto;
+  color: var(--tertiary);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  text-transform: none;
+}
+
 /* mq-slide-number: the eyebrow size, tabular figures. */
 .slide-number {
   font-size: var(--font-size-xs);