@wallarm-org/claude-design 0.0.0-stage → 4.9.0

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# Wallarm Design System for Claude Design
 
-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.
+Install [Wallarm Design System](https://github.com/wallarm/design-system) in Claude Design from
+one prompt. Paste the prompt from the [Claude Design guide](https://wallarm.github.io/design-system/ai/claude-design)
+into a Claude Design chat; Claude runs:
+
+```bash
+npx -y @wallarm-org/claude-design@latest export
+```
+
+The command writes `wallarm-design-system/` and never prompts:
+
+| Path | Contents |
+| --- | --- |
+| `project/` | The system to publish as a Design System artifact: runtime bundle, tokens, CSS, fonts, component guides and previews. Its index lists no asset groups until `index` adds them |
+| `assets/`, `assets.json` | The icon and logo SVGs for the system's galleries, uploaded as assets (not files), and their manifest (group, name, path, sha256, size, type, in gallery order) |
+| `SETUP.md` | Claude's steps: publish the system, install it on a canvas, add and check the sampler |
+| `UPDATE.md` | Claude's steps to update an installed system to this release (also written alone by `update`) |
+| `wallarm-sampler.dc.html` | The sampler artboard, linked to the canvas's `ds/wallarm-design-system/` copy |
+| `files.json` | Each written file with its sha256 |
+| `removed.json` | With `--existing`: the paths an update drops |
+
+Options: `--dir <folder>` (default `wallarm-design-system`), `--overwrite` (required when the
+folder has files), `--existing <file>` (a JSON array of the artifact's current paths; writes
+`removed.json`), `--index <file>` (the artifact's current `project/design-system.json`; the
+written index keeps its keys and takes only the release's `title`, `namespace`, `libraries`,
+`editing`, `groups`, `assetGroups` and `lastChange`, as `publish-plan.ts` does), `--json` (prints `{ ok, exitCode, data | error }`). Exit codes: `0` done,
+`1` error, `2` usage, `3` done with a manual step (remove the paths in `removed.json`).
+`--overwrite` replaces `project/`, `assets/`, `assets.json` and `upload.json`, and keeps only
+the sha256 keys of `blobs.json`.
+
+After the SVGs are uploaded, `index` writes the galleries into the exported index:
+
+```bash
+npx -y @wallarm-org/claude-design@latest index [--blobs wallarm-design-system/blobs.json] [--index current-index.json] [--json]
+```
+
+`blobs.json` maps each SVG's path (anything ending in `assets/Icons/activity.svg`) or sha256 to
+its 32-hex blob id or upload url (`…/_blob/<id>`); `index` rewrites it keyed by sha256. `--index` reuses the blob id of every SVG whose sha256 the system's current
+index already has, so an update uploads only new and changed SVGs. Exit `0`: it wrote `groups`
+and `assetGroups` (`{name, blob, size, type, sha256}` per file) into `project/design-system.json`.
+Exit `3`: it wrote the local paths still to upload, one per unique sha256, to `upload.json` and left the
+index alone.
+
+To update an installed system, Claude runs `update` and follows the `UPDATE.md` it writes:
+
+```bash
+npx -y @wallarm-org/claude-design@latest update [--dir wallarm-design-system] [--json]
+```
+
+It writes `<dir>/UPDATE.md` (replacing an older one), deletes `blobs.json` and `upload.json` (their
+ids may belong to another artifact) and exits `0`. It doesn't touch the artifact: `UPDATE.md` has
+Claude save the system's file list, run `export --overwrite --existing` pinned to the same version,
+publish the files, upload only new SVGs with `index --index` (which also merges the release into
+the index read right before publishing), then remove dropped files and reinstall.
+
+The package version is the design-system version it was built from.
+
+## Maintainers
+
+This package also builds the export. It reads the design-system sources, `scripts/metadata/`
+and `dist/` from `../design-system` (`DESIGN_SYSTEM_DIR` in `src/config.ts`); the
+`@wallarm-org/design-system` package is not affected. Each stable release publishes this package
+from `deploy-site.yml` (job `claude-design`): it runs `export`, sets the version to the tag and
+runs `pnpm publish`, whose `prepack` (`src/pack.ts`) packs `.claude-design/` into `dist/` with
+the rendered `content/SETUP.md` and `content/UPDATE.md` and the canvas sampler. Wallarm's own artifact is synced by hand
+with the [`claude-design-sync`](../../.claude/skills/claude-design-sync/SKILL.md) skill; the
+designer guide is `apps/website/docs/ai/claude-design.mdx`. What Storybook does not show, and
+so Claude Design cannot learn: [CLAUDE_DESIGN_GAP.md](./CLAUDE_DESIGN_GAP.md).
+
+### Folders
+
+All under `src/`. Outside it: `bin/claude-design.js` (the npm CLI, plain Node ESM) and `content/SETUP.md`, `content/UPDATE.md` (the guide templates).
+
+| Folder | Does |
+| --- | --- |
+| `bundle/` | Rslib IIFE bundle (`WallarmDS` namespace, SWC React Compiler targeting React 18) |
+| `css/` | Tailwind CSS for the canvas: the author layout kit (`safelist.ts`), wrapper-tolerant structural selectors (`wrapper-css.ts`) and the generated `components/UTILITIES.md` class list |
+| `tokens/` | Design tokens |
+| `docs/` | Component guides, prop types and the project README (embeds `design-system/src/guidelines/rules.md`) |
+| `previews/` | Story previews |
+| `sampler/` | The canonical screen `sampler.dc.html`, checked against the built CSS, tokens and exports, and shipped at the project root |
+| `assets/` | Icons, fonts and the cover |
+| `harness/` | React 18 tests that mount the built bundle and previews |
+| `config.ts` | Artifact identity, namespace, budgets |
+| `pack.ts` | `prepack`: `.claude-design/` → `dist/` for npm (SVGs moved to `dist/assets/` with `assets.json`, rendered `SETUP.md` and `UPDATE.md`, canvas sampler) |
+| `build.ts`, `verify.ts` | Builder and repeatability check |
+
+### Commands
+
+`export`, `bundle`, `verify` and `test:export` need a built design system. Through turbo it is built first:
+run them from the repo root as `pnpm turbo run <script> --filter=@wallarm-org/claude-design`.
+After a `pnpm build`, `pnpm --filter @wallarm-org/claude-design run <script>` (or `pnpm run
+<script>` in this folder) runs the script alone.
+
+- `export` writes `.claude-design/project/`, `file-hashes.json` and `summary.json` (git-ignored). Fails over budget.
+- `prepack` (also run by `pnpm pack` / `pnpm publish`) packs the export into `dist/`; run `export` first. Smoke test: `pnpm pack`, then `npx -y --package=<tgz> claude-design export --dir <tmp>`.
+- `test:export` runs the producer unit tests and the React 18 harness (through turbo it runs `export` first).
+- `verify` builds twice and compares every output file.
+- `bundle` runs `rslib build` on `rslib.config.ts`: only `bundle.js`, unwrapped, into `.claude-design/rslib/`, for inspecting it (`RSDOCTOR=true` works). `export` builds through the same config.
+- `typecheck` type-checks the exporter.
+- `plan`, `check`, `fetch` build the publish diff against the remote artifact. Call `fetch` as `pnpm run fetch`: plain `pnpm fetch` is a pnpm built-in.
+
+The export is not part of the root `pnpm build`.
+
+### Which tests need a build
+
+The harness tests (`src/harness/*.harness.test.ts`) and `src/build.test.ts` read the built
+project: run `export` first. The other `*.test.ts` files test the producers against the
+design-system sources and `dist/`.
+
+### Budgets
+
+Set in `src/config.ts`, enforced by `src/build.ts`: bundle `bundleBudgetBytes` (5.7 MB), CSS
+`cssCapBytes` (2 MB), whole project 256 MiB.

package/bin/claude-design.js

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+// `export` copies the packaged Claude Design export (../dist) into a folder for Claude to
+// publish; `index` writes the asset groups into its index once the SVGs are uploaded; `update`
+// writes UPDATE.md, the steps to update an installed system to this release.
+// Never prompts. Exit codes: 0 done, 1 error, 2 usage, 3 done with manual steps.
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const SOURCE = fileURLToPath(new URL('../dist/', import.meta.url));
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const USAGE = [
+  'Usage: npx -y @wallarm-org/claude-design@latest export [--dir wallarm-design-system] [--overwrite] [--existing current-files.json] [--index current-index.json] [--json]',
+  '       npx -y @wallarm-org/claude-design@latest index [--dir wallarm-design-system] [--blobs <dir>/blobs.json] [--index current-index.json] [--json]',
+  '       npx -y @wallarm-org/claude-design@latest update [--dir wallarm-design-system] [--json]',
+].join('\n');
+// Files the Design System page writes itself; an update never removes them.
+const PAGE_PATHS = ['project/manifest.json', 'project/api/'];
+// Index keys a release owns; every other key stays as the Design System page wrote it.
+// Mirrors REPLACED in src/publish-plan.ts.
+const RELEASE_KEYS = [
+  'title',
+  'namespace',
+  'libraries',
+  'editing',
+  'groups',
+  'assetGroups',
+  'lastChange',
+];
+const INDEX = 'project/design-system.json';
+// What `export` writes beside project/; --overwrite replaces it. blobs.json stays: `index` keys
+// it by sha256, so an id never attaches to a changed SVG. `update` deletes it: its ids belong to
+// the artifact the folder was exported for, which may not be the one being updated.
+const OWNED = ['project', 'assets', 'assets.json', 'upload.json'];
+// An uploaded asset's blob id, alone or at the end of its `/_blob/<id>` url.
+const BLOB_ID = /^[0-9a-f]{32}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+// A blobs.json key: a sha256, or a path ending in `assets/<group>/<name>` (any prefix).
+const assetPath = key => /(?:^|\/)(assets\/[^/]+\/[^/]+)$/.exec(key.split('\\').join('/'))?.[1];
+const listed = items =>
+  items.length > 10
+    ? `${items.slice(0, 10).join(', ')} and ${items.length - 10} more`
+    : items.join(', ');
+const blobId = value =>
+  typeof value === 'string' ? (/\/_blob\/([^/?#]+)/.exec(value)?.[1] ?? value) : undefined;
+
+class Failure extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+const filesUnder = dir =>
+  readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter(file => file.isFile())
+    .map(file => relative(dir, join(file.parentPath, file.name)).split('\\').join('/'))
+    .sort();
+
+const readJson = (file, what) => {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Failure(`Could not read ${file} (${error.message}). Save ${what} there.`, 2);
+  }
+};
+
+/** The system's current index, as saved or wrapped in a `content` string. */
+const readIndex = file => {
+  let remote = readJson(file, `the system's ${INDEX} as JSON`);
+  if (typeof remote?.content === 'string') remote = JSON.parse(remote.content);
+  if (!remote || typeof remote !== 'object' || Array.isArray(remote))
+    throw new Failure(`${file} must be the system's ${INDEX}, a JSON object.`, 2);
+  return remote;
+};
+
+/** The system's current index with this release's keys. */
+const mergeIndex = (file, packed) => {
+  const merged = { ...readIndex(file) };
+  for (const key of RELEASE_KEYS) merged[key] = packed[key];
+  return merged;
+};
+
+const readPaths = file => {
+  const value = readJson(file, "the system's file paths as a JSON array");
+  if (!Array.isArray(value) || !value.every(path => typeof path === 'string'))
+    throw new Failure(
+      `${file} must be a JSON array of the system's file paths, such as ["project/tokens.css"].`,
+      2,
+    );
+  return value;
+};
+
+/**
+ * Adds every SVG in assets.json to the index's asset groups with its blob id: from blobs.json
+ * (asset path or sha256 to id or `/_blob/<id>` url) or, for unchanged bytes, from the current
+ * index. Rewrites blobs.json keyed by sha256.
+ */
+function writeAssetIndex(values, cwd) {
+  const out = resolve(cwd, values.dir);
+  const shown = relative(cwd, out) || '.';
+  if (!existsSync(join(out, 'assets.json')))
+    throw new Failure(
+      `${join(shown, 'assets.json')} is missing. Run the export first (same --dir).`,
+      2,
+    );
+  const assets = readJson(join(out, 'assets.json'), 'the export');
+  const blobsFile = resolve(cwd, values.blobs ?? join(out, 'blobs.json'));
+  const blobs = existsSync(blobsFile) ? readJson(blobsFile, 'a JSON object') : {};
+  if (!blobs || typeof blobs !== 'object' || Array.isArray(blobs))
+    throw new Failure(
+      `${blobsFile} must be a JSON object of asset path or sha256 to blob id, such as {"assets/Icons/activity.svg": "<id>"}.`,
+      2,
+    );
+
+  // Blob ids by sha256: the person's current index first, then this release's uploads.
+  const ids = new Map();
+  if (values.index)
+    for (const group of Object.values(readIndex(resolve(cwd, values.index)).assetGroups ?? {}))
+      for (const file of Object.values(group?.files ?? {}))
+        if (typeof file?.sha256 === 'string' && BLOB_ID.test(file.blob ?? ''))
+          ids.set(file.sha256, file.blob);
+  const reused = new Set(ids.keys());
+  const shaOf = new Map(assets.map(a => [a.path, a.sha256]));
+  const saved = {};
+  const kept = {};
+  const invalid = [];
+  for (const [key, value] of Object.entries(blobs)) {
+    const sha = SHA256.test(key) ? key : shaOf.get(assetPath(key));
+    const id = blobId(value);
+    if (sha && BLOB_ID.test(id ?? '')) {
+      ids.set(sha, id);
+      saved[sha] = id;
+    } else {
+      invalid.push(key);
+      kept[key] = value;
+    }
+  }
+  if (existsSync(blobsFile))
+    writeFileSync(blobsFile, `${JSON.stringify({ ...saved, ...kept }, null, 2)}\n`);
+  // One path per missing sha256: identical SVGs share an upload.
+  const missing = [
+    ...new Map(
+      assets
+        .filter(a => !ids.has(a.sha256))
+        .map(a => [a.sha256, join(shown, a.path)])
+        .reverse(),
+    ).values(),
+  ].reverse();
+
+  if (missing.length) {
+    writeFileSync(join(out, 'upload.json'), `${JSON.stringify(missing, null, 2)}\n`);
+    const lines = [
+      `${missing.length} of ${assets.length} assets have no blob id yet; ${join(shown, INDEX)} is unchanged.`,
+    ];
+    if (invalid.length)
+      lines.push(
+        `These ${invalid.length} blobs.json entries match no asset or hold no 32-character blob id or /_blob/<id> url: ${listed(invalid)}.`,
+      );
+    lines.push(
+      `Upload the files listed in ${join(shown, 'upload.json')} to the system as assets, add each one's path (as listed) and returned url to ${relative(cwd, blobsFile)}, then run this command again.`,
+    );
+    return { exitCode: 3, lines, data: { assets: assets.length, missing, invalid } };
+  }
+
+  rmSync(join(out, 'upload.json'), { force: true });
+  const groups = [...new Set(assets.map(a => a.group))];
+  const assetGroups = Object.fromEntries(
+    groups.map(group => {
+      const own = assets.filter(a => a.group === group);
+      return [
+        group,
+        {
+          name: group,
+          order: own.map(a => a.name),
+          files: Object.fromEntries(
+            own.map(({ name, size, type, sha256 }) => [
+              name,
+              { name, blob: ids.get(sha256), size, type, sha256 },
+            ]),
+          ),
+        },
+      ];
+    }),
+  );
+  const packed = JSON.parse(readFileSync(join(SOURCE, INDEX), 'utf8'));
+  // With --index, the index read right before publishing: the page's keys stay current.
+  const index = values.index
+    ? mergeIndex(resolve(cwd, values.index), packed)
+    : readJson(join(out, INDEX), 'the export');
+  index.createdOnFiles ??= packed.createdOnFiles;
+  writeFileSync(
+    join(out, INDEX),
+    `${JSON.stringify({ ...index, groups, assetGroups }, null, 2)}\n`,
+  );
+  const reusedCount = assets.filter(a => reused.has(a.sha256) && !(a.sha256 in saved)).length;
+  return {
+    exitCode: 0,
+    lines: [
+      `Wrote ${assets.length} assets in ${groups.join(', ')} to ${join(shown, INDEX)}${reusedCount ? ` (${reusedCount} unchanged since the current index)` : ''}. Publish it last.`,
+    ],
+    data: { assets: assets.length, groups, reused: reusedCount, missing: [], invalid: [] },
+  };
+}
+
+/** Writes <dir>/UPDATE.md for this release and deletes blobs.json and upload.json: an update starts with nothing uploaded. */
+function writeUpdateGuide(values, cwd) {
+  const guide = join(SOURCE, 'UPDATE.md');
+  if (!existsSync(guide))
+    throw new Failure(
+      `This @wallarm-org/claude-design ${version} has no UPDATE.md. Run the command again with @latest, or report it at https://github.com/wallarm/design-system/issues.`,
+      1,
+    );
+  const out = resolve(cwd, values.dir);
+  mkdirSync(out, { recursive: true });
+  cpSync(guide, join(out, 'UPDATE.md'));
+  for (const file of ['blobs.json', 'upload.json']) rmSync(join(out, file), { force: true });
+  const file = join(relative(cwd, out) || '.', 'UPDATE.md');
+  return {
+    exitCode: 0,
+    lines: [`Read ${file} and follow it to update the system to Wallarm Design System ${version}.`],
+    data: { version, dir: out, file: join(out, 'UPDATE.md') },
+  };
+}
+
+function run(argv, cwd) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        dir: { type: 'string', default: 'wallarm-design-system' },
+        overwrite: { type: 'boolean', default: false },
+        existing: { type: 'string' },
+        index: { type: 'string' },
+        blobs: { type: 'string' },
+        json: { type: 'boolean', default: false },
+      },
+    });
+  } catch (error) {
+    throw new Failure(`${error.message}\n${USAGE}`, 2);
+  }
+  const { values, positionals } = parsed;
+  if (positionals.length === 1 && positionals[0] === 'index') return writeAssetIndex(values, cwd);
+  if (positionals.length === 1 && positionals[0] === 'update') return writeUpdateGuide(values, cwd);
+  if (positionals.length !== 1 || positionals[0] !== 'export')
+    throw new Failure(`Unknown command ${positionals.join(' ') || '(none)'}.\n${USAGE}`, 2);
+  if (!existsSync(join(SOURCE, 'project/design-system.json')))
+    throw new Failure(
+      `This @wallarm-org/claude-design ${version} has no packaged export. Run the command again with @latest, or report it at https://github.com/wallarm/design-system/issues.`,
+      1,
+    );
+
+  const out = resolve(cwd, values.dir);
+  if (existsSync(out) && readdirSync(out).length > 0 && !values.overwrite)
+    throw new Failure(
+      `${out} already has files. Pass --overwrite to replace the export in it, or choose another --dir.`,
+      2,
+    );
+  const existing = values.existing ? readPaths(resolve(cwd, values.existing)) : undefined;
+  const packed = JSON.parse(readFileSync(join(SOURCE, INDEX), 'utf8'));
+  const index = values.index ? mergeIndex(resolve(cwd, values.index), packed) : undefined;
+
+  for (const path of OWNED) rmSync(join(out, path), { recursive: true, force: true });
+  // Path keys `index` hasn't turned into sha256 keys may name changed SVGs: drop them.
+  const blobsFile = join(out, 'blobs.json');
+  if (existsSync(blobsFile)) {
+    let blobs;
+    try {
+      blobs = JSON.parse(readFileSync(blobsFile, 'utf8'));
+    } catch {}
+    const bySha = Object.entries(blobs ?? {}).filter(([key]) => SHA256.test(key));
+    writeFileSync(blobsFile, `${JSON.stringify(Object.fromEntries(bySha), null, 2)}\n`);
+  }
+  cpSync(SOURCE, out, { recursive: true });
+  if (index) writeFileSync(join(out, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+  const written = filesUnder(SOURCE);
+  const hashes = Object.fromEntries(
+    written.map(path => [
+      path,
+      createHash('sha256')
+        .update(readFileSync(join(out, path)))
+        .digest('hex'),
+    ]),
+  );
+  writeFileSync(join(out, 'files.json'), `${JSON.stringify(hashes, null, 2)}\n`);
+
+  const exported = new Set(written);
+  const removed = (existing ?? [])
+    .filter(path => path.startsWith('project/') && !exported.has(path))
+    .filter(path => !PAGE_PATHS.some(page => path === page || path.startsWith(page)))
+    .sort();
+  if (existing) writeFileSync(join(out, 'removed.json'), `${JSON.stringify(removed, null, 2)}\n`);
+  else rmSync(join(out, 'removed.json'), { force: true });
+
+  const shown = relative(cwd, out) || '.';
+  const projectFiles = written.filter(path => path.startsWith('project/')).length;
+  const assets = written.filter(path => path.startsWith('assets/')).length;
+  const lines = [
+    `Exported Wallarm Design System ${version}: ${projectFiles} files in ${join(shown, 'project')} and ${assets} icons and logos in ${join(shown, 'assets')}.`,
+  ];
+  if (removed.length)
+    lines.push(
+      `Remove the ${removed.length} files the system has and this release doesn't: they're listed in ${join(shown, 'removed.json')}.`,
+    );
+  lines.push(
+    existing
+      ? `Carry on with ${join(shown, 'UPDATE.md')} from step 3; it points into ${join(shown, 'SETUP.md')}.`
+      : values.index
+        ? `Carry on where you were: run the index command with --index, then publish ${join(shown, INDEX)}.`
+        : `Read ${join(shown, 'SETUP.md')} and follow it. It publishes the system, installs it on a canvas and checks it.`,
+  );
+  return {
+    exitCode: removed.length ? 3 : 0,
+    lines,
+    data: { version, dir: out, files: projectFiles, assets, removed },
+  };
+}
+
+const json = process.argv.includes('--json');
+try {
+  const { exitCode, lines, data } = run(process.argv.slice(2), process.cwd());
+  process.stdout.write(
+    json ? `${JSON.stringify({ ok: true, exitCode, data })}\n` : `${lines.join('\n')}\n`,
+  );
+  process.exitCode = exitCode;
+} catch (error) {
+  const exitCode = error instanceof Failure ? error.exitCode : 1;
+  const message =
+    error instanceof Failure
+      ? error.message
+      : `The export failed: ${error.message}. Show this output to the person.`;
+  if (json) process.stdout.write(`${JSON.stringify({ ok: false, exitCode, error: message })}\n`);
+  else process.stderr.write(`${message}\n`);
+  process.exitCode = exitCode;
+}

package/dist/SETUP.md

@@ -0,0 +1,130 @@
+# Install Wallarm Design System 4.9.0 in Claude Design
+
+This guide ships with Wallarm Design System 4.9.0. Work through the steps in order and run each check before moving on.
+
+The export wrote `wallarm-design-system/`:
+
+| Path | Contents | Publish it |
+| --- | --- | --- |
+| `project/` | The design system: 373 files | Yes: every file, unchanged |
+| `assets/` | The icon and logo galleries: 583 SVG files in Logos (1), Icons (582) | As assets, in step 1 |
+| `assets.json` | Each SVG's group, name, path and sha256 | No |
+| `SETUP.md` | This guide | No |
+| `UPDATE.md` | The update guide, for a later release | No |
+| `wallarm-sampler.dc.html` | The sampler artboard, for step 4 | To the canvas, in step 4 |
+| `files.json` | Every file the export wrote, with its sha256 | No |
+| `removed.json` | Paths an update drops. Written only with `--existing` | No |
+| `blobs.json` | You write it in step 1: each SVG's path and the url its upload returned. The `index` command rewrites it keyed by sha256. The `update` command deletes it | No |
+
+If the person already has a Wallarm Design System artifact and gave you its link, don't install a new one: [update it](#update-to-a-new-release).
+
+## 1. Publish the system
+
+Create a new **Design System** artifact titled `Wallarm Design System`, with the description "Wallarm's product UI: React components, light and dark tokens, Geist fonts and icons, generated from wallarm/design-system". Then, in this order:
+
+1. **Files.** Publish the files of `wallarm-design-system/project/` to it, each at its path under `project/` (for example `project/tokens.css`), except `project/design-system.json`. Don't add, rename, edit or skip a file.
+   - Send `project/components/index.d.ts` with the content type `text/plain`; the artifact refuses it otherwise. Every other file's type follows its extension.
+   - A publish takes at most 255 files, so send the files in batches of up to 200.
+2. **Icons and logos.** The galleries are asset uploads, not files: never publish anything from `wallarm-design-system/assets/` as a file under `project/`.
+   1. Run `npx -y @wallarm-org/claude-design@4.9.0 index --blobs wallarm-design-system/blobs.json`. It exits 3 and lists in `wallarm-design-system/upload.json` the local paths of the SVGs to upload (identical SVGs share one upload).
+   2. Upload them in the order listed: the Artifact tool's publish with the system's `url`, `asset: true` and `file_paths` set to the next 25 paths from `upload.json`, copied as they are. With `upload_asset`, if that is the tool you have, send at most 10 per call. The first install takes about 24 calls. If an upload is refused, show the person the error and stop.
+   3. After each call, add one entry per uploaded file to `wallarm-design-system/blobs.json`, a JSON object: the path as `upload.json` lists it, mapped to the `url` the result gives for that file, for example `{"wallarm-design-system/assets/Icons/activity.svg": "https://…/_blob/<id>"}`. Copy the url, not the asset's `id`. If the result has no url but gives each file's sha256 and id (as `upload_asset` does), key the entry by that sha256 instead.
+   4. Run the `index` command again. It rewrites `blobs.json` keyed by sha256; keep its entries and add new ones after them. Exit 3: upload the paths it lists now and run it again. Exit 0: it wrote the asset groups into `project/design-system.json`.
+3. **Index.** Publish `project/design-system.json` last, alone, after the `index` command exited 0. It is the system's index; it carries the marker a new system needs.
+
+In artboards, icons are still `WallarmDS.Icons.<Name>` and the logo `WallarmDS.Logo`, from `components/bundle.js`; the galleries show them on the system's page.
+
+Check: every `project/` path in `wallarm-design-system/files.json` (373 files) is in the artifact, its title is `Wallarm Design System`, and `project/design-system.json` has a `lastChange.note` that starts with `v4.9.0:`. The Artifact tool's `list` with the system's `url` and `scope: "assets"` shows at least 580 assets. The system's page shows the asset groups Logos (1), Icons (582), with every icon drawn (no broken image). The page may add `project/manifest.json` and files under `project/api/`; they don't count. Give the person the artifact's link: they need it to install the system on other canvases and to update it.
+
+If a publish is refused for a reason this step doesn't cover, show the person the error and stop. Don't edit or rename files to get past it.
+
+## 2. Create a canvas and install the system
+
+Create a Design canvas and install the system on it from the link in step 1.
+
+The canvas copies the system into one folder under `project/ds/`. This guide expects `project/ds/wallarm-design-system/`. Check that the canvas has:
+
+- `project/ds/wallarm-design-system/tokens.css`
+- `project/ds/wallarm-design-system/tokens.json`
+- `project/ds/wallarm-design-system/components/bundle.css`
+- `project/ds/wallarm-design-system/components/bundle.js`
+- `project/ds/wallarm-design-system/components/index.d.ts`
+
+If the folder has another name, use that name in place of `wallarm-design-system` from here on, and in step 4.
+
+If `index.d.ts` is missing, copy `project/components/index.d.ts` from the system to `project/ds/wallarm-design-system/components/index.d.ts` unchanged. The props panel reads it; without it no prop gets a control.
+
+## 3. Read the canvas rules
+
+Read `wallarm-design-system/project/README.md`, at least "Rules", "Layout on a canvas", "Consuming this system", "From a Storybook story to an artboard". They give the `WallarmDS` namespace, how to mount a component with `x-import`, how to pass props through `renderVals()` holes, the spacing scale and the dark theme. Follow them on every artboard you draw.
+
+The README's paths, its load order and its `sampler.dc.html` are relative to the system, not to a canvas. An artboard sits in the canvas's `project/` folder, so start every new artboard's `<head>` with these lines, in this order, and add no other link lines for the system:
+
+```html
+<script src="./support.js"></script>
+<link rel="stylesheet" href="ds/wallarm-design-system/tokens.css">
+<link rel="stylesheet" href="ds/wallarm-design-system/components/bundle.css">
+<script src="ds/wallarm-design-system/components/bundle.js"></script>
+```
+
+When the README says to start a screen from the sampler, start from `project/wallarm-sampler.dc.html` on the canvas (step 4), not from the system's `sampler.dc.html`. Icons are `WallarmDS.Icons.<Name>` and the logo is `WallarmDS.Logo`; on a canvas, use them, not the gallery SVGs.
+
+## 4. Add the sampler
+
+`wallarm-design-system/wallarm-sampler.dc.html` is a Users settings screen built only from the system. It is also the install test. Put it on the canvas exactly as it is: don't retype, reformat or rename it, and don't add link lines or scripts; it has them. Its links point at `ds/wallarm-design-system/`. Only if step 2 found a different folder, replace `ds/wallarm-design-system/` with `ds/<that folder>/` in its three link lines and change nothing else.
+
+A canvas keeps its files under `project/`. Its index is `project/canvas.json`, and each artboard is a `.dc.html` file in `project/`.
+
+1. Publish the file to the canvas at `project/wallarm-sampler.dc.html`:
+   - If the Artifact tool takes `files` as a map, map `project/wallarm-sampler.dc.html` to the local file `wallarm-design-system/wallarm-sampler.dc.html`.
+   - If it takes a list of absolute paths, first copy the file unchanged into the canvas's `project/` folder: `cp wallarm-design-system/wallarm-sampler.dc.html /mnt/user-data/outputs/artifacts/<canvas id>/project/wallarm-sampler.dc.html`, then publish that path.
+2. Merge this key into `boards` in `project/canvas.json`. `boards` is keyed by artboard file name, relative to `project/`; `x` and `y` place the board on an empty canvas.
+
+   ```json
+   {"wallarm-sampler.dc.html":{"x":0,"y":0,"w":1440,"h":900,"title":"Wallarm sampler","expand":"fill"}}
+   ```
+
+   If the canvas has other boards, set `x` to the largest `x + w` among them plus 80. If `boards` already has `"wallarm-sampler.dc.html"`, keep its `x` and `y` and replace the rest.
+3. Append `"wallarm-sampler.dc.html"` to `order` in `project/canvas.json` unless it is already there. Keep every other key and entry as it is.
+
+Check: read `project/wallarm-sampler.dc.html` back from the canvas; it matches the export's copy. `project/canvas.json` has `"wallarm-sampler.dc.html"` in `boards` and exactly once in `order`. A board titled `Wallarm sampler` shows on the canvas.
+
+## 5. Check the sampler
+
+If you can't see the canvas or its console, ask the person to check each item and tell you what they see.
+
+- The console has no `[WallarmDS]` warning and no error. A `[WallarmDS] class "…" has no CSS` warning means a class is missing from `components/bundle.css`.
+- Every part renders: the top header with the Wallarm logo, the navigation rail (Home, Security, Settings), the `Users` page header with its `Create user` button, the toolbar with the search field and the `All` / `Active` / `Invited` / `Deactivated` tabs, the users table with five rows (status badges, roles, last active, an actions menu on each row), and the `Ana Ruiz` drawer on the right with its `API tokens` section and the `No API tokens yet` empty state.
+- The text is in Geist, not the system font.
+- Nothing is cut off at the bottom of the board and nothing spills out of the table or drawer. If the bottom is cut off, raise the board's `h` in `project/canvas.json` until it fits.
+- Type `zzz` in the search field: the table shows `No results found` with a `Reset filters` button. Click it and the five rows come back.
+- Open a row's actions menu: `Edit user` and `Delete user` show. Press Escape to close it.
+- Select the `Create user` button: the props panel shows its props with controls (for example `variant` as a dropdown).
+
+The sampler is light only. For a dark artboard, set `theme="dark"` on its `WallarmDS.Root`, as the README says.
+
+When every check passes, tell the person the Wallarm Design System is ready, give them the system link, and wait for their design request.
+
+## Update to a new release
+
+To update a system the person already has, run `npx -y @wallarm-org/claude-design@latest update` and follow the `wallarm-design-system/UPDATE.md` it writes.
+
+## When something looks wrong
+
+| You see | Do this |
+| --- | --- |
+| The publish is refused for `index.d.ts` | Send `project/components/index.d.ts` as `text/plain`. |
+| The publish is refused for too many files | Send smaller batches, as step 1 says. |
+| The `index` command exits 3 | Upload the paths in `upload.json`, add their urls to `blobs.json` and run it again. An entry it names as invalid has a key that matches no SVG or a value that isn't a 32-character blob id or `/_blob/<id>` url: copy it again from `upload.json` and the upload result. |
+| Publishing `project/design-system.json` is refused as stale | The system's page saved a newer index. Save the version the refusal hands back as `current-index.json` (copy it; don't retype it), run `npx -y @wallarm-org/claude-design@4.9.0 index --blobs wallarm-design-system/blobs.json --index current-index.json`, and publish the index again. Nothing needs uploading again. |
+| The gallery is empty or shows broken images | `project/design-system.json` was published before the `index` command exited 0, or with a wrong url. Fix `blobs.json`, run `index` again and publish the index again. |
+| No sampler board shows | The file isn't at `project/wallarm-sampler.dc.html`, or `project/canvas.json` has no `"wallarm-sampler.dc.html"` in `boards` or `order`. |
+| Components render unstyled | The link lines don't reach `project/ds/wallarm-design-system/`. The artboard must sit directly in `project/`, and the folder name must match step 2. |
+| `WallarmDS is not defined` | `components/bundle.js` isn't loaded: same cause as above. |
+| Nothing renders and the console is empty | The sampler was changed. Publish the export's copy again, as step 4 says. |
+| A `[WallarmDS] class "…" has no CSS` warning | The class doesn't exist on the canvas. Use one from `components/UTILITIES.md`; numeric utilities are in px (`p-16` is 16px). |
+| A prop has no control | `project/ds/wallarm-design-system/components/index.d.ts` is missing. Copy it as step 2 says. |
+| Text shows in the system font | The fonts in `project/fonts/` weren't published or installed. Check step 1's file check and step 2. |
+| The export command fails or can't reach npm | Show the person its output and stop. |
+
+Never edit a file in the system artifact or under `project/ds/wallarm-design-system/` on a canvas to make a check pass. If a check still fails, tell the person which check, what you saw and the version (4.9.0). Problems go to https://github.com/wallarm/design-system/issues.