@medquantis/design-system 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 The single source of the MedQuantis visual identity: design tokens, shared CSS, self-hosted fonts and icons, brand assets, guidelines and a Claude skill. Every value is defined once, in `tokens/`, and reaches each consumer as a generated output in its native format ([ADR-0002](docs/architecture/decisions/adr-0002-central-tokens-first-design-system.md)).
 
-> Status: bootstrap. Nothing is published yet; the repository stays private until the pre-public confidentiality audit passes ([ADR-0005](docs/architecture/decisions/adr-0005-public-repo-with-confidentiality-gate.md)).
+> Status: published on npm as `@medquantis/design-system`; the repository is public behind the confidentiality gate ([ADR-0005](docs/architecture/decisions/adr-0005-public-repo-with-confidentiality-gate.md)).
 
 ## Outputs
 
@@ -17,6 +17,8 @@ The single source of the MedQuantis visual identity: design tokens, shared CSS,
 | `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) |
+| `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) |
 
@@ -106,6 +108,57 @@ echo "sha384-$(openssl dgst -sha384 -binary dist/tokens.css | openssl base64 -A)
 
 Every other shipped file (`css/*.css`, `fonts/fonts.css`, `dist/kit-contract.css`) works the same way, each with its own hash. Fonts referenced by `fonts.css` load relative to it, so serve the stylesheet and its fonts from the same release URL.
 
+## 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):
+
+```sh
+python3 <skill-dir>/scripts/design_system.py point @medquantis/design-system@1.1.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.
+
+`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:
+
+| Module | File | Carries |
+| :-- | :-- | :-- |
+| `core` | `dist/kit/core.css` | Text, canvas, surface, border, accent and status colours, the tertiary grey of footers and legal lines, the three faces with their font files, title size, spacing, radii and the card shadow |
+| `dataviz` | `dist/kit/dataviz.css` | The ordered navy and blue-grey chart series, the rest series, axis, grid and highlight |
+| `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 |
+| `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 |
+| `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:
+
+```markdown
+## MedQuantis brand
+- Anything that carries the MedQuantis brand (slides, A4 reports, web pages, app screens, charts) outside a kit render is built with the `medquantis-design-system` skill, and is not done until its validator (`validate.py --record`) reports no finding.
+- Values come from `--mq-*` tokens only; a local addition uses this project's own prefix and references `var(--mq-*)`, never a literal colour, font or shadow.
+- Documents (slides, reports, papers, the website) are navy only and show a state by mark style; the status colours belong to interactive apps alone.
+- Tools that read a DESIGN.md take the one in the pinned package (`@medquantis/design-system/DESIGN.md`), never a hand-written copy.
+```
+
+To give every session in that repository the `medquantis-design-system` plugin, local and cloud alike, commit this `.claude/settings.json` (merge the two keys into an existing file).
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "medquantis": {
+      "source": { "source": "github", "repo": "MedQuantis/design-system" }
+    }
+  },
+  "enabledPlugins": {
+    "medquantis-design-system@medquantis": true
+  }
+}
+```
+
+Tools and agents outside the kit read `dist/DESIGN.md` (exported as `@medquantis/design-system/DESIGN.md`): the same tokens and rules in Google's DESIGN.md format, generated by `make build` and checked with Google's linter.
+
 ## Specialisation rules
 
 1. Core and semantic tokens are not overridden in a consumer.
@@ -125,8 +178,11 @@ make brand        # re-outline the monogram and wordmark SVGs from the pinned Ou
 make brand-check  # prove the committed brand SVGs reproduce byte for byte (Python, not in make check)
 make skill        # regenerate the Claude skill's references, eval graders and assets
 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.
+
 `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.
 
 `make build` installs the npm dependencies from `package-lock.json` (`npm ci --ignore-scripts`) when the lockfile changes, then regenerates `dist/` from `tokens/` with Style Dictionary. `make check` is the single local entry point and mirrors CI, which installs the same tools from `mise.toml` and runs the same target. Locally the deny-list scan warns when `MQ_DENYLIST` is unset; point it at a copy of the deny-list (or `tests/fixtures/denylist.txt` for a dry run) to run the full check.

package/css/app.css

@@ -1,3 +1,4 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
 /*
  * MedQuantis status badges for interactive apps only (ADR-0004). Documents never load this
  * file. A status badge always carries a word or an icon, never colour alone (WCAG 1.4.1).

package/css/base.css

@@ -1,3 +1,4 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
 /*
  * MedQuantis typography roles for documents, slides and pages (build-less media).
  * Tokens only: load dist/tokens.css (and fonts/fonts.css) first. Every selector sits in :where()
@@ -12,7 +13,7 @@
     font-family: var(--mq-font-family-body);
     font-size: var(--mq-font-size-body);
     font-weight: var(--mq-font-weight-body);
-    line-height: 1.55;
+    line-height: var(--mq-font-line-height-body);
     text-rendering: optimizeLegibility;
     -webkit-font-smoothing: antialiased;
   }
@@ -50,7 +51,7 @@
 
   :where(.mq-title) {
     font-size: var(--mq-font-size-h2);
-    line-height: 1.15;
+    line-height: var(--mq-font-line-height-tight);
     letter-spacing: -0.01em;
   }
 

package/css/components.css

@@ -1,3 +1,4 @@
+/*! @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.
@@ -34,7 +35,7 @@
     color: var(--mq-muted);
     font-family: var(--mq-font-family-body);
     font-size: var(--mq-font-size-small);
-    line-height: 1.55;
+    line-height: var(--mq-font-line-height-body);
   }
 
   /* Navy panel */
@@ -73,7 +74,7 @@
     color: var(--mq-on-navy-second-level);
     font-family: var(--mq-font-family-body);
     font-size: var(--mq-font-size-small);
-    line-height: 1.55;
+    line-height: var(--mq-font-line-height-body);
   }
 
   :where(.mq-panel-rule) {

package/css/kit/document.css

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

@@ -0,0 +1,81 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * Class rules of the MedQuantis print module for the homemade-claude-kit renderers (the
+ * com-release-note report; Plan-0002 increment 02). Written by hand against contract roles only.
+ * The report inlines the core, dataviz, type, space-shape and print modules (render_pdf.py
+ * REPORT_MODULES, kit #149). The sizes are the A4 print column of guidelines/typography.md, which
+ * is not yet a token, and the weight is the heading weight 500 (owner ruling 4); the template's
+ * own bold text and chips read --font-weight-bold and --radius-pill from the design. The build
+ * copies these rules into dist/kit/print.css after the roles.
+ * build/kit-classes.md names the MedQuantis rule each class reproduces: css/print.css (mq-page)
+ * and the typography roles of css/base.css.
+ *
+ * Cascade: the report template's own rules come before the design layer, so these rules, of
+ * the same specificity, replace them. The page box is --print-page-size and --print-margin.
+ */
+
+/* mq-page: the A4 sheet on the canvas colour (owner ruling 9), ink text. */
+.report {
+  background: var(--print-bg);
+  color: var(--ink);
+}
+
+/* mq-eyebrow: Geist Mono 500 capitals in navy, 7.5 pt in print. */
+.report-kicker {
+  color: var(--accent);
+  font-family: var(--font-mono);
+  font-size: 7.5pt;
+  font-weight: 500;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+}
+
+/* mq-display: the document title in Outfit 500, 26 pt in print. */
+.report-title {
+  color: var(--ink);
+  font-family: var(--font-heading);
+  font-size: 26pt;
+  font-weight: 500;
+  line-height: 1.08;
+  letter-spacing: -0.025em;
+}
+
+/* mq-lead: Newsreader italic in the secondary text colour, 11.5 pt in print. */
+.report-framing {
+  color: var(--muted);
+  font-family: var(--font-body);
+  font-size: 11.5pt;
+  font-style: italic;
+  line-height: 1.5;
+}
+
+/* The space between sections (guidelines/layout.md, Widths and spacing). */
+.section {
+  margin-top: var(--space-lg);
+}
+
+/* A section label: Outfit 500 capitals, 12.5 pt, under a 2 px navy rule like "In brief"
+   (guidelines/layout.md, Report skeleton). */
+.section-label {
+  padding-bottom: var(--space-sm);
+  border-bottom: 2px solid var(--accent);
+  color: var(--ink);
+  font-family: var(--font-heading);
+  font-size: 12.5pt;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+}
+
+/* A section that leads a fresh page (guidelines/layout.md, Print and PDF). */
+.section--page-break {
+  break-before: page;
+  page-break-before: always;
+}
+
+/* Documents are navy only (ADR-0004, guidelines/colour.md): the breaking-changes label reads by
+   its words and a navy rule, never by a status hue. --print-breaking is the navy accent, and the
+   kit's template washes the breaking-changes panel with it too. */
+.section--breaking .section-label {
+  border-bottom-color: var(--print-breaking);
+  color: var(--print-breaking);
+}

package/css/kit/slide-frame.css

@@ -0,0 +1,99 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
+/*
+ * Class rules of the MedQuantis slide-frame module for the homemade-claude-kit renderers
+ * (Plan-0002 increment 02). Written by hand against contract roles only: core, type, space-shape,
+ * dataviz and the slide-frame roles, which tokens/kit/ maps. The build copies these rules into
+ * dist/kit/slide-frame.css after the roles. build/kit-classes.md names the MedQuantis rule each
+ * class reproduces: css/slide.css, with the legal line bottom left and the slide number bottom
+ * 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.
+ * The footer row and the source line use --tertiary, the tertiary grey of owner ruling 1.
+ */
+
+/* mq-slide: the canvas, body text in Newsreader. The kit's render.py drops the shadow in the PDF. */
+.slide {
+  border-radius: 0;
+  box-shadow: var(--shadow);
+  font-family: var(--font-body);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-body);
+}
+
+/* mq-slide-label: mono capitals in navy, 48 px from the top, at the side margin. */
+.slide-label {
+  top: var(--space-xl);
+  left: var(--slide-padding);
+  margin: 0;
+  font-weight: var(--font-weight-bold);
+  letter-spacing: 0.18em;
+}
+
+/* mq-slide-foot: one row, the legal line at the left and the number at the right, 24 px above
+   the bottom edge, at the side margins. */
+.slide-footer {
+  right: var(--slide-padding);
+  bottom: calc(var(--space-md) + var(--space-sm));
+  left: var(--slide-padding);
+  height: auto;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: calc(var(--space-md) + var(--space-sm));
+  color: var(--tertiary);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  line-height: var(--line-height-tight);
+}
+
+/* MedQuantis slides carry no logo in the footer row (owner ruling 11, guidelines/layout.md). */
+.slide-logo {
+  display: none;
+}
+
+.slide-legal {
+  margin: 0;
+}
+
+/* mq-slide-number: the eyebrow size, tabular figures. */
+.slide-number {
+  font-size: var(--font-size-xs);
+  font-variant-numeric: tabular-nums;
+}
+
+/* A cited source on a slide: the note style of guidelines/typography.md, above the footer row. */
+.slide .slide-source-bar {
+  right: var(--slide-padding);
+  bottom: calc(var(--space-md) + var(--space-sm) + var(--space-lg));
+  left: var(--slide-padding);
+  color: var(--tertiary);
+  font-family: var(--font-body);
+  font-size: var(--font-size-sm);
+  font-style: italic;
+}
+
+/* The controls hint above the deck: a hint in Geist Mono, as in an empty state (guidelines/layout.md, App patterns). */
+body .controls-hint {
+  color: var(--muted);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-xs);
+  letter-spacing: 0.04em;
+}
+
+body .controls-hint kbd {
+  border-color: var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--surface);
+  color: var(--ink);
+  font-family: var(--font-mono);
+}
+
+/* Presentation mode: the slide alone on an ink surround, without the desk shadow. */
+html body.presenting {
+  background: var(--ink);
+}
+
+html body.presenting .slide.active {
+  box-shadow: none;
+}

package/css/print.css

@@ -1,3 +1,4 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
 /*
  * MedQuantis A4 print: one .mq-page per sheet (named page mq-a4), colours printed exactly,
  * motion stopped. On screen the pages sit on the desk; the desk never reaches paper

package/css/slide.css

@@ -1,3 +1,4 @@
+/*! @medquantis/design-system | © 2026 MedQuantis SA | MIT License, see LICENSE */
 /*
  * MedQuantis slide canvas: 1280 x 720, section label, title, body area, and a footer row with
  * the legal line at the left and the slide number at the right (owner ruling 11).
@@ -46,7 +47,7 @@
     font-family: var(--mq-font-family-heading);
     font-size: var(--mq-font-size-slide-title);
     font-weight: var(--mq-font-weight-heading);
-    line-height: 1.15;
+    line-height: var(--mq-font-line-height-tight);
     letter-spacing: -0.01em;
     text-wrap: balance;
   }