@aitrien/motifspec 1.13.2 → 1.13.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Every release of MotifSpec (named brand-codex until 1.10.0), newest first. Entries before 1.10.0 keep the names they were released under. Versions follow the rules in `CONVENTIONS.md`: renaming or removing a semantic token is major, adding tokens, components or icons is minor, and changing a value or fixing a description is a patch. `npm run build` fails if the version in `package.json` has no entry here.
 
+## [1.13.3] - 2026-10-27
+
+### Changed
+- Docs: each fact now lives in one place. The README's Hugo section points to `docs/hugo.md` (which now has the stylesheet path note and the full front-matter example from `docs/templates.md`), the release process lives in `CONVENTIONS.md`, and `docs/hugo.md` points to the README's list of what the checker checks. Statements about an MCP server that doesn't exist yet are removed, as are the planned-only `mcp/README.md` and the SCSS row in `CONVENTIONS.md`, which the build has never generated. The npm install line pins whatever version is current instead of naming 1.13.0.
+- `AGENTS.md` (with `CLAUDE.md` pointing to it): where a change goes in this repo, what to run before finishing, and how releasing works, linking to the README and `CONVENTIONS.md` for everything else. Repo-only; not in the npm package.
+
 ## [1.13.2] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # MotifSpec
 
-Liam Marshall's design system: the single source of truth for aitrien.com and every project after it. Tokens are [DTCG](https://www.designtokens.org/) JSON, components are documented rules with markup to copy, and an MCP server serves both to AI coding assistants.
+Liam Marshall's design system: the single source of truth for aitrien.com and every project after it. Tokens are [DTCG](https://www.designtokens.org/) JSON, components are documented rules with markup to copy, and one checker holds every project that uses it to those rules.
 
 ## Principles
 
@@ -33,6 +33,7 @@ Liam Marshall's design system: the single source of truth for aitrien.com and ev
 
 ```
 LICENSE             MIT, for code, tokens and docs
+AGENTS.md           Instructions for AI agents changing this repo (CLAUDE.md points to it)
 CHANGELOG.md        Every release, newest first (the build fails without an entry for the current version)
 tokens/             DTCG source of truth (color, typography, space, size, radius, border, motion)
 css/components.css  Reference implementation of every component (tokens only)
@@ -44,14 +45,13 @@ docs/hugo.md        The Hugo partials and render hooks, their contexts and the f
 layouts/            Hugo partials (_partials/motifspec/) and Markdown render hooks (_markup/), mounted by the module
 docs/syntax-highlighting.md
 fonts/              Self-hosted WOFF2 (Latin subsets) and their OFL licences
-scripts/            validate, build, audit, check (the rule checker sites run) and release
+scripts/            validate, build, audit, check (the rule checker projects run), pack-check and release
 js/codex.js         Theme toggle, copy buttons, tooltip dismissal, TOC docking and active section (shared by sites and the showcase)
 js/theme-init.js    One-line <head> snippet that applies a stored theme before first paint
 js/plate.js         Contour survey generator for the backdrop and the specimen plate: draws the static contours at build time and animates them in the browser
 showcase/           Source of the system's showcase page
-mcp/                MCP server (Phase 3)
 hugo.toml, go.mod   Hugo module definition and its mounts
-dist/               Generated: tokens.css, components in codex.css, chroma.css, fonts.css, icons.svg (sprite), tokens.json (for MCP), tokens.js (ES module export), codex.js and theme-init.js (behaviour), backdrop.html, plate.html and plate.js (backdrop and specimen plate), contrast.md, showcase.html (fragment for publishing), showcase.standalone.html (open locally)
+dist/               Generated: tokens.css, components in codex.css, chroma.css, fonts.css, icons.svg (sprite), tokens.json, tokens.js (ES module export), codex.js and theme-init.js (behaviour), backdrop.html, plate.html and plate.js (backdrop and specimen plate), contrast.md, showcase.html (fragment for publishing), showcase.standalone.html (open locally)
 ```
 
 ## Commands
@@ -65,7 +65,7 @@ npm run pack:check     # the npm package has every file the README and package.j
 npm run check -- <dir>  # check a project that uses MotifSpec (see below)
 ```
 
-`scripts/check.mjs` is the one rule checker: this repo's audit runs it on `layouts/` and the component docs' markup, sites run it from their pinned module, and the MCP server's `check_styles` will call it. It checks a project's `layouts/` and `content/` against the release it comes from, and fails on:
+`scripts/check.mjs` is the one rule checker: this repo's audit runs it on `layouts/` and the component docs' markup, and projects run it from the version they pin. It checks a project's `layouts/` and `content/` against the release it comes from, and fails on:
 
 - a stylesheet anywhere in the project, or a `style` attribute
 - a raw colour, or a number with a length or time unit (zero is allowed)
@@ -73,43 +73,21 @@ npm run check -- <dir>  # check a project that uses MotifSpec (see below)
 - a `cx-` class that the stylesheet and scripts don't define, or a `cx-icon-` that isn't in `icons/manifest.json`
 - "·" used as a separator
 
-Releases are automatic. Bump `version` in `package.json` and add its `CHANGELOG.md` entry in the PR; once it is merged and CI passes on main, `.github/workflows/release.yml` tags that commit, publishes a GitHub release with the entry as its notes, and publishes that commit to npm with provenance (npm trusted publishing: no token is stored). A merge that doesn't change the version releases nothing.
+Releases are automatic; `CONVENTIONS.md` (Versioning) says how.
 
 Node 20 or later, no dependencies.
 
 ## Using it in Hugo
 
-Import the module and pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. It mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts`, and `layouts/` at `layouts`, so a site gets the component partials and the Markdown render hooks as well as the CSS and scripts:
-
-```toml
-[module]
-  [[module.imports]]
-    path = "github.com/aitrien/motifspec"
-```
-
-A page template then needs only the shell partials around its own content:
-
-```go-html-template
-<head>
-  {{ partial "motifspec/head.html" . }}
-</head>
-<body class="cx-backdrop-page">
-  {{ partial "motifspec/body-start.html" . }}
-  {{ partial "motifspec/site-header.html" . }}
-  <main id="main" tabindex="-1">…</main>
-  {{ partial "motifspec/body-end.html" . }}
-</body>
-```
-
-`docs/hugo.md` lists every partial with its context, the front matter they read, the render hooks and the Markdown they expect, and the Goldmark settings they need. Keep the stylesheet's published path one level below the site root (Hugo publishes it at `/motifspec/`): its font URLs are `../fonts/…`, which resolve to the mounted `/fonts/`.
+Import `github.com/aitrien/motifspec` as a Hugo module and pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The site then gets the CSS, scripts, fonts, component partials and Markdown render hooks; `docs/hugo.md` covers setup, every partial and the front matter they read.
 
 ## Using it from npm
 
 ```sh
-npm install @aitrien/motifspec@1.13.0
+npm install --save-exact @aitrien/motifspec
 ```
 
-Pin an exact version, as a Hugo site pins a tag: the version you install is the version the checker and (later) the MCP server hold you to. The package has the CSS, scripts, tokens, fonts, icons, component docs, Hugo templates and the checker; it leaves out the showcase.
+Pin an exact version, as a Hugo site pins a tag: the version you install is the version the checker holds you to. The package has the CSS, scripts, tokens, fonts, icons, component docs, Hugo templates and the checker; it leaves out the showcase.
 
 | Import | What it is |
 |---|---|

package/dist/codex.css

@@ -2,7 +2,7 @@
 @font-face { font-family: "JetBrains Mono"; src: url("../fonts/jetbrains-mono-latin-wght.woff2") format("woff2"); font-weight: 100 800; font-style: normal; font-display: swap; }
 @font-face { font-family: "Yarndings 12"; src: url("../fonts/yarndings-12-latin.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: block; }
 
-/* MotifSpec 1.13.2 — generated from tokens/*.json. Do not edit.
+/* MotifSpec 1.13.3 — generated from tokens/*.json. Do not edit.
    Themes: semantic colours use light-dark(); color-scheme follows the system unless
    <html data-theme="light|dark"> pins it. --cx-primitive-* are for this file only. */
 :root {

package/dist/tokens.css

@@ -1,4 +1,4 @@
-/* MotifSpec 1.13.2 — generated from tokens/*.json. Do not edit.
+/* MotifSpec 1.13.3 — generated from tokens/*.json. Do not edit.
    Themes: semantic colours use light-dark(); color-scheme follows the system unless
    <html data-theme="light|dark"> pins it. --cx-primitive-* are for this file only. */
 :root {

package/dist/tokens.js

@@ -1,5 +1,5 @@
 // Generated by npm run build. Do not edit.
-export const version = "1.13.2";
+export const version = "1.13.3";
 export const changelog = "https://github.com/Aitrien/motifspec/blob/main/CHANGELOG.md";
 export const tokens = [
   {

package/dist/tokens.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.13.2",
+  "version": "1.13.3",
   "changelog": "https://github.com/Aitrien/motifspec/blob/main/CHANGELOG.md",
   "tokens": [
     {

package/docs/components/_template.md

@@ -21,7 +21,7 @@ One sentence: what it is for.
 ## Markup
 
 ```html preview
-<!-- Minimal markup. The dashboard renders this block as a live preview, and the MCP server returns it as the pattern to copy. -->
+<!-- Minimal markup: the pattern to copy. -->
 ```
 
 ## Do

package/docs/hugo.md

@@ -18,7 +18,7 @@ The module ships the components as Hugo partials and the Markdown render hooks t
     block = true                              # {caption="…"} on tables, {file="…"} on code, {width="prose"} on figures
 ```
 
-Pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The module mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts` and `layouts/` at `layouts`.
+Pin a release with `hugo mod get github.com/aitrien/motifspec@vX.Y.Z`. The module mounts `dist/` at `assets/motifspec`, `fonts/` at `static/fonts` and `layouts/` at `layouts`. Hugo publishes the stylesheet at `/motifspec/`; keep it one level below the site root, because its font URLs are `../fonts/…`.
 
 ## The page shell
 
@@ -76,6 +76,18 @@ Every partial below is called as `partial "motifspec/<name>.html" <context>`.
 
 ## Front matter the partials read
 
+```yaml
+title: Interactive WebGL globe
+accession: LM-W-001
+date: 2026-03-14
+summary: A React app that renders live routes on a 3D globe.
+role: Sole engineer
+stack: [React, WebGL, Vite]
+status: live        # live | building | archived
+tags: [react, webgl, a11y]
+hero: { src: hero.png, alt: "…", caption: "…" }
+```
+
 | Field | Used by | Notes |
 |---|---|---|
 | `summary` | cards, rows | The lede and the card or row summary. |
@@ -113,7 +125,7 @@ const motifspec = mounts.split(/\n(?=\{)/).map((m) => JSON.parse(m)).find((m) =>
 execFileSync('node', [join(motifspec.dir, 'scripts', 'check.mjs'), '.'], { stdio: 'inherit' });
 ```
 
-It checks `layouts/` and `content/` and fails on stylesheets, style attributes, raw colours and units, primitive, unknown or deprecated tokens, classes and icons MotifSpec doesn't define, and "·" separators. In GitHub Actions each problem is also an annotation on the pull request; `--json` prints the problems as JSON. In CI, give the step the same `HUGO_CACHEDIR` and `HUGO_MODULE_PROXY` as the build, because `hugo config mounts` downloads the module if it isn't cached.
+It checks `layouts/` and `content/` for what the README's Commands section lists. In GitHub Actions each problem is also an annotation on the pull request; `--json` prints the problems as JSON. In CI, give the step the same `HUGO_CACHEDIR` and `HUGO_MODULE_PROXY` as the build, because `hugo config mounts` downloads the module if it isn't cached.
 
 ## Overriding
 

package/docs/templates.md

@@ -16,15 +16,6 @@ Content hierarchy for the six page types. Every template sits on the backdrop (`
 - Work: `LM-W-001` onward. Writing: `LM-P-001` onward. Zero-padded, never reused, stored in front matter as `accession`.
 - They appear on cards, post rows, post meta lines and case-study labels.
 
-## Hugo front matter
+## Front matter
 
-```yaml
-title: Interactive WebGL globe
-accession: LM-W-001
-date: 2026-03-14
-summary: A React app that renders live routes on a 3D globe.
-role: Sole engineer
-stack: [React, WebGL, Vite]
-status: live        # live | building | archived
-tags: [react, webgl, a11y]
-```
+The fields each template reads are in `docs/hugo.md` (Front matter the partials read).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitrien/motifspec",
-  "version": "1.13.2",
+  "version": "1.13.3",
   "description": "Liam Marshall's design system: DTCG tokens, component rules, generated CSS, Hugo templates and a rule checker.",
   "keywords": [
     "design-system",

package/scripts/check.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The MotifSpec rule checker: one implementation for this repo's templates (npm run audit), for sites that use
-// MotifSpec (their CI runs this file from the pinned module) and for the MCP server's check_styles tool.
+// MotifSpec (their CI runs this file from the pinned module) and for any tool that imports checkText.
 //
 //   node scripts/check.mjs [project-root]                 check a consuming project's layouts/ and content/
 //   node scripts/check.mjs [project-root] --dirs src,app  check other folders instead (a non-Hugo project)