@rblabs-dev/axiom 0.0.0-stage → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodolfo Bocanegra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @rblabs-dev/axiom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Axiom is the RB Labs design system for Angular and Angular Material 3: the theme, the `--rb-*`
+tokens, self-hosted fonts and icons, kit classes, content components, the app and public shells,
+and a `/design-system` showcase page. Every RB Labs Angular frontend uses it.
+
+The specification, with every token, component and rule, is
+[docs/design-system.md](https://github.com/rodolfoBocanegra/rblabs-axiom/blob/main/docs/design-system.md).
+This README covers installing the package and wiring it into an app.
+
+## Requirements
+
+- Angular 21 or 22, with the matching `@angular/material` and `@angular/cdk`. The package also uses
+  `@angular/forms`, `@angular/router` and `@angular/platform-browser`, which every Angular CLI app
+  has.
+- SCSS global styles: `"inlineStyleLanguage": "scss"` in `angular.json` and a `src/styles.scss`.
+- Browsers with `light-dark()` and `color-mix()`: Chrome and Edge 123, Firefox 120, Safari 17.5 or
+  later.
+
+## Install
+
+```bash
+npm install @rblabs-dev/axiom @angular/material@<major> @angular/cdk@<major>
+```
+
+Inter Variable comes with the package (`@fontsource-variable/inter`). Nothing loads from a CDN.
+
+## Set up an app
+
+Run these steps from the folder that holds the app's `angular.json`.
+
+1. **npm scripts.** The package installs the `axiom` command. Add these scripts, and append the
+   checks to the app's own `lint` and `build`:
+
+   ```json
+   "lint": "<existing lint> && npm run check:style-literals",
+   "build": "ng build && npm run verify:production-assets",
+   "check:style-literals": "axiom check-style-literals",
+   "verify:production-assets": "axiom verify-production-assets",
+   "build:icon-font": "axiom build-icon-font",
+   "build:brand-assets": "axiom build-brand-assets"
+   ```
+
+   Create `style-literals.allowlist.json` containing `[]` next to `package.json`.
+
+2. **Icon font.** The kit's icons are included automatically. List the icons the app's own
+   templates use in `scripts/material-symbols-icons.txt`, one per line, then run:
+
+   ```bash
+   npm run build:icon-font
+   ```
+
+   It writes `public/fonts/material-symbols-outlined-<release>-400-subset.<hash>.woff2` and its
+   `NOTICE.txt`. `angular.json` must serve `public/` (`{ "glob": "**/*", "input": "public" }`, the
+   Angular CLI default); no other asset entry is needed.
+
+3. **Global styles.** Call the entry mixin once, at the top of `src/styles.scss`, with the subset's
+   file name (later runs of `build:icon-font` update it):
+
+   ```scss
+   @use '@rblabs-dev/axiom' as rb;
+
+   @include rb.design-system($icon-font-url: '/fonts/<subset file name>');
+   ```
+
+   Remove any other Material theme setup (`mat.core()`, `mat.define-theme()`, prebuilt themes).
+   `$scope: '.rb-scope'` applies the kit only inside that class, for an app that still has global
+   styles of its own. The module also forwards `rb.below()`, `rb.above()` and `$breakpoints`.
+
+4. **Providers.** In `app.config.ts`:
+
+   ```ts
+   import { provideRbDesignSystem } from '@rblabs-dev/axiom';
+
+   export const appConfig: ApplicationConfig = {
+     providers: [provideRouter(routes), provideRbDesignSystem()],
+   };
+   ```
+
+   It applies the stored theme before the first render and makes Material Symbols the default
+   `<mat-icon>` font. `provideRbDesignSystem({ forcedTheme: 'dark' })` keeps an app dark-only
+   while it migrates, and `legacyStorageKeys` moves a theme choice stored under an older key.
+
+5. **Showcase route.** Route `/design-system` to the showcase, lazily, so it stays out of the
+   initial bundle:
+
+   ```ts
+   {
+     path: 'design-system',
+     title: 'Design system',
+     loadComponent: () =>
+       import('@rblabs-dev/axiom/showcase').then((m) => m.DesignSystemShowcaseComponent),
+   }
+   ```
+
+6. **Favicon and document head.** Write the app's favicon from the brand template, then reference
+   it in `index.html` with the theme colors:
+
+   ```bash
+   npm run build:brand-assets -- --app <admin|auth|rover|photogrammetry>
+   ```
+
+   ```html
+   <link rel="icon" type="image/svg+xml" href="favicon.svg" />
+   <meta name="theme-color" content="#f4f7fb" media="(prefers-color-scheme: light)" />
+   <meta name="theme-color" content="#08111d" media="(prefers-color-scheme: dark)" />
+   ```
+
+7. **Build.** `npm run build` builds the app and runs `axiom verify-production-assets`.
+
+Then use the components and kit classes in templates:
+
+```ts
+import { RbPageHeaderComponent, RbPanelComponent } from '@rblabs-dev/axiom';
+```
+
+```html
+<rb-page-header eyebrow="Registry" title="Services" />
+<rb-panel title="Details">…</rb-panel>
+```
+
+Section 18 of the specification lists the full adoption, including shells, views and the evidence
+each pull request needs.
+
+## What the package contains
+
+| Import or path                         | Contents                                                                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `@rblabs-dev/axiom`                    | Content components, shells, brand components, `ThemeService`, `provideRbDesignSystem()`, `RB_BREAKPOINTS` and `RB_DESIGN_SYSTEM_VERSION` |
+| `@rblabs-dev/axiom/showcase`           | `DesignSystemShowcaseComponent`, the `/design-system` page                                                                               |
+| `@use '@rblabs-dev/axiom'` (SCSS)      | `rb.design-system()`, `rb.below()`, `rb.above()`, `$breakpoints` and `$version`; emits no CSS until the mixin is called                  |
+| `axiom` (command)                      | The four commands below                                                                                                                  |
+| `brand/`, `material-symbols-icons.txt` | Brand templates and the kit's icon inventory, read by the commands                                                                       |
+
+## The `axiom` command
+
+Each command reads the app's source root, `public/` folder and build output from `angular.json`.
+With several applications in one workspace, pass `--project <name>`. `npx axiom help` lists them.
+
+| Command                                                   | What it does                                                                                                                                                  |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `axiom build-icon-font [--output <dir>]`                  | Downloads the Material Symbols subset for the kit's and the app's icons, replaces the previous one in `public/fonts/` and updates its name in `src/**/*.scss` |
+| `axiom build-brand-assets --app <name> [--out-dir <dir>]` | Writes `public/favicon.svg`. With `--og-image <out.svg> --description <text> --domain <host>`, also writes the social preview SVG                             |
+| `axiom verify-production-assets [--scan <dir>]...`        | After a production build, fails on Google Fonts references, a missing favicon or icon font, or an icon used in `src/` that no inventory lists                 |
+| `axiom check-style-literals`                              | Fails on hex, `rgb()` or `hsl()` color literals in `src/**/*.scss` that `style-literals.allowlist.json` does not list                                         |
+
+## Versions
+
+The package follows Semantic Versioning, and the package version is the kit version that the
+showcase and `RB_DESIGN_SYSTEM_VERSION` report. Release notes are on the
+[GitHub releases](https://github.com/rodolfoBocanegra/rblabs-axiom/releases) page.
+
+## License
+
+MIT. The icon font that `axiom build-icon-font` downloads is Material Symbols (Apache License 2.0),
+and Inter Variable is licensed under the SIL Open Font License 1.1.

package/brand/favicon.template.svg

@@ -0,0 +1,21 @@
+<!--
+  Per-app favicon template (docs/design-system.md, section 12.3). Do not copy by hand: run
+  npm run build:brand-assets -- --app <admin|auth|rover|photogrammetry>
+  which fills {{appName}} and {{badgeColor}} and writes public/favicon.svg.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">RB Labs {{appName}}</title>
+  <defs>
+    <linearGradient id="brand" x1="8" y1="8" x2="56" y2="56" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#67a2ff" />
+      <stop offset="1" stop-color="#2f78ed" />
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="16" fill="#08111d" />
+  <rect x="5" y="5" width="54" height="54" rx="14" fill="url(#brand)" />
+  <g fill="none" stroke="#f6f9fd" stroke-linecap="round" stroke-linejoin="round" stroke-width="3.5">
+    <path d="M17 47V17h7.3c4.9 0 7.8 2.7 7.8 6.9s-2.9 6.8-7.8 6.8H17M24.3 30.7 34.5 47" />
+    <path d="M40 17v30M40 17h6.8c4.4 0 7.1 2.6 7.1 6.2s-2.7 5.9-7.1 5.9H40M40 29.1h7.5c4.7 0 7.7 3.2 7.7 7.1s-3 7.8-7.7 7.8H40" />
+  </g>
+  <circle cx="52" cy="52" r="9" fill="{{badgeColor}}" stroke="#08111d" stroke-width="4" />
+</svg>

package/brand/og-image.template.svg

@@ -0,0 +1,37 @@
+<!--
+  Social preview template (docs/design-system.md, section 12.4): 1200x630, always in the dark
+  palette, 64px safe margin. Do not fill by hand: run
+  npm run build:brand-assets -- --app <app> --og-image <out.svg> --description "<text>" --domain <host>
+  and export the result to public/og-image.png as the specification describes.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+  <style>
+    @font-face {
+      font-family: 'Inter Variable';
+      font-weight: 100 900;
+      src: url('{{interFontUrl}}') format('woff2');
+    }
+    text {
+      font-family: 'Inter Variable', Inter, 'Segoe UI', system-ui, sans-serif;
+    }
+  </style>
+  <defs>
+    <linearGradient id="brand" x1="8" y1="8" x2="56" y2="56" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#67a2ff" />
+      <stop offset="1" stop-color="#2f78ed" />
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="630" fill="#08111d" />
+  <svg x="64" y="64" width="160" height="160" viewBox="0 0 64 64">
+    <rect width="64" height="64" rx="16" fill="#08111d" />
+    <rect x="5" y="5" width="54" height="54" rx="14" fill="url(#brand)" />
+    <g fill="none" stroke="#f6f9fd" stroke-linecap="round" stroke-linejoin="round" stroke-width="3.5">
+      <path d="M17 47V17h7.3c4.9 0 7.8 2.7 7.8 6.9s-2.9 6.8-7.8 6.8H17M24.3 30.7 34.5 47" />
+      <path d="M40 17v30M40 17h6.8c4.4 0 7.1 2.6 7.1 6.2s-2.7 5.9-7.1 5.9H40M40 29.1h7.5c4.7 0 7.7 3.2 7.7 7.1s-3 7.8-7.7 7.8H40" />
+    </g>
+  </svg>
+  <text x="64" y="306" fill="#a3b4c9" font-size="40" font-weight="600">RB Labs</text>
+  <text x="64" y="400" fill="#f6f9fd" font-size="88" font-weight="700" letter-spacing="-1.76">{{appName}}</text>
+  <text x="64" y="462" fill="#dce7f5" font-size="32" font-weight="400">{{description}}</text>
+  <text x="64" y="566" fill="#8b9db4" font-size="28" font-weight="500">{{domain}}</text>
+</svg>

package/brand/rb-monogram.svg

@@ -0,0 +1,16 @@
+<!-- The RB monogram (docs/design-system.md, section 12.1). Colors are the fixed brand tokens. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">RB Labs</title>
+  <defs>
+    <linearGradient id="brand" x1="8" y1="8" x2="56" y2="56" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#67a2ff" />
+      <stop offset="1" stop-color="#2f78ed" />
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="16" fill="#08111d" />
+  <rect x="5" y="5" width="54" height="54" rx="14" fill="url(#brand)" />
+  <g fill="none" stroke="#f6f9fd" stroke-linecap="round" stroke-linejoin="round" stroke-width="3.5">
+    <path d="M17 47V17h7.3c4.9 0 7.8 2.7 7.8 6.9s-2.9 6.8-7.8 6.8H17M24.3 30.7 34.5 47" />
+    <path d="M40 17v30M40 17h6.8c4.4 0 7.1 2.6 7.1 6.2s-2.7 5.9-7.1 5.9H40M40 29.1h7.5c4.7 0 7.7 3.2 7.7 7.1s-3 7.8-7.7 7.8H40" />
+  </g>
+</svg>

package/cli/axiom.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// The `axiom` command apps run from their npm scripts (docs/design-system.md, section 14). Run it
+// from the folder that holds the app's angular.json; see `axiom help`.
+
+const commands = {
+  'build-icon-font': {
+    load: () => import('./build-icon-font.mjs'),
+    usage: '[--project <name>] [--output <dir>]',
+    summary: "download the Material Symbols subset into the app's public/fonts/",
+  },
+  'build-brand-assets': {
+    load: () => import('./build-brand-assets.mjs'),
+    usage:
+      '--app <admin|auth|rover|photogrammetry> [--project <name>] [--out-dir <dir>]\n' +
+      '                             [--og-image <out.svg> --description <text> --domain <host>]',
+    summary: "write the app's favicon.svg (and the og-image SVG) from the brand templates",
+  },
+  'verify-production-assets': {
+    load: () => import('./verify-production-assets.mjs'),
+    usage: '[--project <name>] [--scan <dir>]...',
+    summary: 'check the production build: favicon, icon font and icon inventory',
+  },
+  'check-style-literals': {
+    load: () => import('./check-style-literals.mjs'),
+    usage: '[--project <name>]',
+    summary: "fail on color literals in the app's own stylesheets",
+  },
+};
+
+function help() {
+  const lines = ['Usage: axiom <command> [options]', '', 'Commands:'];
+  for (const [name, command] of Object.entries(commands)) {
+    lines.push(`  ${name.padEnd(26)}${command.summary}`, `    axiom ${name} ${command.usage}`);
+  }
+  lines.push(
+    '',
+    '--project picks the application in ./angular.json; it can be left out when there is only one.',
+  );
+  return lines.join('\n');
+}
+
+const [name, ...argv] = process.argv.slice(2);
+if (!name || name === 'help' || name === '--help') {
+  console.log(help());
+} else if (!Object.hasOwn(commands, name)) {
+  console.error(`Unknown command "${name}".\n\n${help()}`);
+  process.exitCode = 1;
+} else {
+  try {
+    const { run } = await commands[name].load();
+    await run(argv);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  }
+}

package/cli/build-brand-assets.mjs

@@ -0,0 +1,115 @@
+// Produces an app's brand assets from the kit templates in this package's brand/ folder
+// (docs/design-system.md, sections 12.3 and 12.4).
+//
+//   axiom build-brand-assets --app <admin|auth|rover|photogrammetry> [--project <name>]
+//       [--out-dir <dir>]
+//       writes favicon.svg to the app's public/ folder (or <dir>): the monogram with the app's badge
+//       and the title "RB Labs <App>"
+//
+//   ... --og-image <out.svg> --description "<at most 60 characters>" --domain <host>
+//       also writes the filled social preview template to <out.svg>, for export to the app's
+//       public/og-image.png (1200x630). The SVG loads Inter from node_modules, so export it on the
+//       machine that generated it.
+//
+// The output is per-app and lives in the app; commit its public/favicon.svg and og-image.png.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { brandDir, parseOptions, relativeToCwd, resolveProject } from './project.mjs';
+
+const require = createRequire(import.meta.url);
+
+// Section 12.3. Badge colors exist only in favicons; they are not UI tokens.
+export const RB_APPS = {
+  admin: { name: 'Admin', badgeColor: '#7dd3fc' },
+  auth: { name: 'Auth', badgeColor: '#6fdcaa' },
+  rover: { name: 'Rover', badgeColor: '#c4b5fd' },
+  photogrammetry: { name: 'Photogrammetry', badgeColor: '#f2a65a' },
+};
+
+const maxDescriptionLength = 60;
+
+function escapeXml(text) {
+  return text
+    .replace(/&/gu, '&amp;')
+    .replace(/</gu, '&lt;')
+    .replace(/>/gu, '&gt;')
+    .replace(/"/gu, '&quot;');
+}
+
+// Fills {{name}} placeholders and drops the template's leading comments (the kit header and the
+// usage note), which do not belong in the generated per-app file.
+export function fillTemplate(template, values) {
+  const body = template.replace(/^(?:\s*<!--[\s\S]*?-->)+\s*/u, '');
+  const filled = body.replace(/\{\{(\w+)\}\}/gu, (placeholder, name) => {
+    if (!(name in values)) throw new Error(`No value for ${placeholder}.`);
+    return escapeXml(values[name]);
+  });
+  return filled.endsWith('\n') ? filled : `${filled}\n`;
+}
+
+function readTemplate(name) {
+  return readFileSync(path.join(brandDir, name), 'utf8');
+}
+
+// The variable Inter file the og-image template embeds, from this package's dependency.
+function interFontPath() {
+  try {
+    return require.resolve('@fontsource-variable/inter/files/inter-latin-wght-normal.woff2');
+  } catch {
+    throw new Error('Cannot find @fontsource-variable/inter; run npm install first.');
+  }
+}
+
+export function run(argv) {
+  const options = parseOptions(argv);
+  const app = RB_APPS[options.app];
+  if (!app) {
+    throw new Error(`--app must be one of: ${Object.keys(RB_APPS).join(', ')}.`);
+  }
+
+  // Validate everything before writing anything.
+  const { description, domain } = options;
+  const outDir = options['out-dir']
+    ? path.resolve(options['out-dir'])
+    : resolveProject(options.project).publicDir;
+  if (!existsSync(outDir)) throw new Error(`${relativeToCwd(outDir)} does not exist.`);
+  let interFont;
+  if (options['og-image']) {
+    if (!description || !domain) {
+      throw new Error('--og-image needs --description and --domain.');
+    }
+    if (description.length > maxDescriptionLength) {
+      throw new Error(
+        `--description has ${description.length} characters; the limit is ${maxDescriptionLength}.`,
+      );
+    }
+    interFont = interFontPath();
+  }
+
+  const faviconPath = path.join(outDir, 'favicon.svg');
+  writeFileSync(
+    faviconPath,
+    fillTemplate(readTemplate('favicon.template.svg'), {
+      appName: app.name,
+      badgeColor: app.badgeColor,
+    }),
+  );
+  console.log(`Wrote ${relativeToCwd(faviconPath)} for RB Labs ${app.name}.`);
+
+  if (!options['og-image']) return;
+  const ogPath = path.resolve(options['og-image']);
+  writeFileSync(
+    ogPath,
+    fillTemplate(readTemplate('og-image.template.svg'), {
+      appName: app.name,
+      description,
+      domain,
+      interFontUrl: pathToFileURL(interFont).href,
+    }),
+  );
+  console.log(`Wrote ${relativeToCwd(ogPath)}; export it to public/og-image.png at 1200x630.`);
+}

package/cli/build-icon-font.mjs

@@ -0,0 +1,134 @@
+// Builds an app's Material Symbols Outlined subset (docs/design-system.md, section 10).
+//
+//   axiom build-icon-font [--project <name>] [--output <dir>]        (npm run build:icon-font)
+//
+// Reads the kit's ligature inventory (material-symbols-icons.txt in this package: every icon the
+// kit's components and showcase use) and the app's own, scripts/material-symbols-icons.txt in the
+// project root, when it exists. Downloads a WOFF2 subset with exactly those icons (static instance:
+// FILL 0, wght 400, GRAD 0, opsz 24) and writes it to the app's public/fonts/ as
+// material-symbols-outlined-<release>-400-subset.<hash>.woff2, with a NOTICE.txt. The content hash
+// is part of the name because servers cache font files as immutable: adding an icon must produce a
+// new URL. The previous subset is deleted and every reference to its name in the app's .scss files
+// is updated.
+//
+// This is a developer-time step; the app never requests Google Fonts at runtime. `--output` writes
+// the font to another directory and leaves public/ and src/ untouched (useful for a trial run).
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { parseOptions, readIconInventories, relativeToCwd, resolveProject } from './project.mjs';
+
+const fontPattern = /^material-symbols-outlined-.+\.woff2$/u;
+const maxBytes = 16_000;
+// Google Fonts serves WOFF2 only to browsers it recognizes.
+const userAgent =
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+
+async function fetchSubset(names) {
+  // Google Fonts requires `icon_names` in alphabetical order.
+  const iconNames = [...names].sort().join(',');
+  const cssUrl =
+    'https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0' +
+    `&icon_names=${iconNames}&display=block`;
+  const cssResponse = await fetch(cssUrl, { headers: { 'User-Agent': userAgent } });
+  if (!cssResponse.ok)
+    throw new Error(`Google Fonts CSS request failed: HTTP ${cssResponse.status}`);
+  const css = await cssResponse.text();
+
+  const fontUrl = /src:\s*url\(([^)]+)\)\s*format\('woff2'\)/u.exec(css)?.[1];
+  if (!fontUrl) throw new Error('No WOFF2 source in the Google Fonts response.');
+  const release = /[?&]v=(v\d+)/u.exec(fontUrl)?.[1] ?? /\/(v\d+)\//u.exec(fontUrl)?.[1];
+  if (!release) throw new Error(`Cannot read the font release from ${fontUrl}`);
+
+  const fontResponse = await fetch(fontUrl, { headers: { 'User-Agent': userAgent } });
+  if (!fontResponse.ok) throw new Error(`Font download failed: HTTP ${fontResponse.status}`);
+  return { release, bytes: Buffer.from(await fontResponse.arrayBuffer()) };
+}
+
+export function contentHash(bytes) {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+}
+
+function listFiles(directory, extension) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(entryPath, extension));
+    else if (entry.name.endsWith(extension)) files.push(entryPath);
+  }
+  return files;
+}
+
+function replaceReferences(sourceDir, previousNames, nextName) {
+  const updated = [];
+  for (const file of listFiles(sourceDir, '.scss')) {
+    const text = readFileSync(file, 'utf8');
+    let next = text;
+    for (const previous of previousNames) next = next.split(previous).join(nextName);
+    if (next !== text) {
+      writeFileSync(file, next);
+      updated.push(relativeToCwd(file));
+    }
+  }
+  return updated;
+}
+
+function writeNotice(directory, release, inventories) {
+  writeFileSync(
+    path.join(directory, 'NOTICE.txt'),
+    [
+      'Material Symbols Outlined subset',
+      '',
+      'Source: https://fonts.google.com/icons',
+      `Font release: ${release}`,
+      'Subset configuration: weight 400, optical size 24, fill 0, grade 0',
+      `Icons: ${inventories.names.length}, the kit's inventory plus the app's ` +
+        '(scripts/material-symbols-icons.txt)',
+      'Built by `axiom build-icon-font` (@rblabs-dev/axiom, the RB Labs design system).',
+      '',
+      'Material Symbols are licensed under the Apache License, Version 2.0.',
+      'https://www.apache.org/licenses/LICENSE-2.0',
+      '',
+    ].join('\n'),
+  );
+}
+
+export async function run(argv) {
+  const options = parseOptions(argv);
+  const project = resolveProject(options.project);
+  const outputDir = options.output ? path.resolve(options.output) : null;
+  const inventories = readIconInventories(project);
+  const { release, bytes } = await fetchSubset(inventories.names);
+  if (bytes.length > maxBytes) {
+    throw new Error(
+      `Subset is ${bytes.length} bytes; the limit is ${maxBytes}. Remove unused icons.`,
+    );
+  }
+
+  const fileName = `material-symbols-outlined-${release}-400-subset.${contentHash(bytes)}.woff2`;
+  const targetDir = outputDir ?? path.join(project.publicDir, 'fonts');
+  mkdirSync(targetDir, { recursive: true });
+
+  const previous = outputDir
+    ? []
+    : readdirSync(targetDir).filter((name) => fontPattern.test(name) && name !== fileName);
+  writeFileSync(path.join(targetDir, fileName), bytes);
+  writeNotice(targetDir, release, inventories);
+
+  for (const name of previous) rmSync(path.join(targetDir, name));
+  const updated = outputDir ? [] : replaceReferences(project.sourceDir, previous, fileName);
+
+  console.log(
+    `Wrote ${relativeToCwd(path.join(targetDir, fileName))} (${inventories.names.length} icons, ` +
+      `${statSync(path.join(targetDir, fileName)).size} bytes).`,
+  );
+  if (previous.length > 0) console.log(`Removed ${previous.join(', ')}.`);
+  if (updated.length > 0) console.log(`Updated references in ${updated.join(', ')}.`);
+  if (!outputDir && previous.length > 0 && updated.length === 0) {
+    console.warn(
+      `No stylesheet referenced the previous subset. Point $icon-font-url at /fonts/${fileName}.`,
+    );
+  }
+}

package/cli/check-style-literals.mjs

@@ -0,0 +1,94 @@
+// Literal-color guard for an app's own stylesheets (docs/design-system.md, sections 13 and 17.6).
+// The kit's stylesheets are checked in the Axiom workspace.
+//
+//   axiom check-style-literals [--project <name>]        (npm run check:style-literals)
+//
+// Fails, naming each file and line, when a stylesheet under the app's source root (src/) uses a
+// hex, rgb()/rgba() or hsl()/hsla() color literal instead of --rb-* or --mat-sys-* tokens.
+//
+// A documented exception (section 13) goes in style-literals.allowlist.json in the project root,
+// as { "file": "src/…/x.scss", "literal": "#05080f", "reason": "docs/design-system.md 13.x …" },
+// with `file` relative to the project root. An entry that no longer matches anything fails the
+// check too, so the list cannot go stale.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { parseOptions, relativeToCwd, resolveProject } from './project.mjs';
+
+const literalPattern = /(?<![\w&-])#[0-9a-f]{3,8}(?![\w-])|\b(?:rgba?|hsla?)\([^)]*\)?/giu;
+
+// Stylesheets under `folder`, as paths relative to `rootDir` with forward slashes.
+function listStylesheets(rootDir, folder) {
+  const files = [];
+  for (const entry of readdirSync(path.join(rootDir, folder), { withFileTypes: true })) {
+    const relative = folder ? `${folder}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...listStylesheets(rootDir, relative));
+    else if (entry.isFile() && entry.name.endsWith('.scss')) files.push(relative);
+  }
+  return files;
+}
+
+// Comments may quote literals, for example to explain what a token replaced. They are blanked
+// rather than removed so line numbers stay accurate.
+function stripComments(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//gu, (comment) => comment.replace(/[^\n]/gu, ' '))
+    .replace(/(^|[^:])\/\/.*$/gmu, '$1');
+}
+
+function readAllowlist(allowlistPath) {
+  if (!existsSync(allowlistPath)) return [];
+  const entries = JSON.parse(readFileSync(allowlistPath, 'utf8'));
+  if (!Array.isArray(entries)) throw new Error('style-literals.allowlist.json must be an array.');
+  for (const entry of entries) {
+    if (!entry.file || !entry.literal || !entry.reason?.includes('docs/design-system.md')) {
+      throw new Error(
+        `style-literals.allowlist.json: ${JSON.stringify(entry)} needs "file", "literal" and a ` +
+          '"reason" that cites the docs/design-system.md section allowing it.',
+      );
+    }
+  }
+  return entries;
+}
+
+export function run(argv) {
+  const project = resolveProject(parseOptions(argv).project);
+  const allowlist = readAllowlist(project.allowlistPath);
+  const scannedFolder = path.relative(project.rootDir, project.sourceDir).split(path.sep).join('/');
+  const used = new Set();
+  const problems = [];
+
+  for (const file of listStylesheets(project.rootDir, scannedFolder)) {
+    const lines = stripComments(readFileSync(path.join(project.rootDir, file), 'utf8')).split('\n');
+
+    lines.forEach((line, index) => {
+      for (const [literal] of line.matchAll(literalPattern)) {
+        const allowed = allowlist.findIndex(
+          (entry) =>
+            entry.file === file && literal.toLowerCase().startsWith(entry.literal.toLowerCase()),
+        );
+        if (allowed >= 0) used.add(allowed);
+        else
+          problems.push(`${file}:${index + 1}: color literal \`${literal}\`; use a --rb-* token`);
+      }
+    });
+  }
+
+  allowlist.forEach((entry, index) => {
+    if (!used.has(index))
+      problems.push(`style-literals.allowlist.json: ${entry.file} no longer uses ${entry.literal}`);
+  });
+
+  if (problems.length > 0) {
+    throw new Error(
+      `Style literal check failed:\n${problems.map((p) => `  - ${p}`).join('\n')}\n` +
+        'Read colors from --rb-* or --mat-sys-* tokens. A new exception needs a section in ' +
+        'docs/design-system.md (13.4) and an entry in style-literals.allowlist.json.',
+    );
+  }
+  console.log(
+    `Style literal check passed: no color literals in ${relativeToCwd(project.sourceDir)}` +
+      (allowlist.length > 0 ? ` (${allowlist.length} documented exceptions).` : '.'),
+  );
+}