# AGENTS.md Digital Rust is a colour scheme, not an app. The deliverables are the palette itself: this SvelteKit static site (prerendered to `build/`), terminal/editor port files in `static/ports/`, and the two canonical spec documents at the repo root. There is no test suite and no CI; verification is visual plus the commands below. ## Commands - `pnpm install` — package manager is **pnpm**; never commit a `package-lock.json`. - `pnpm dev` / `pnpm build` / `pnpm preview` — output is fully static in `build/`. - `pnpm check` — svelte-check + tsc. `pnpm lint` — prettier + eslint. Run both before committing. - `pnpm contrast` — measures every declared colour pair in both modes against its WCAG floor, from `palette.ts` and from every port file. It prints the recorded deviations rather than failing, so read its output; a new deviation is a design decision, not a surprise. ## Palette changes (the critical workflow) `src/lib/palette.ts` is the site's single source of truth for hex values. It generates `src/lib/generated/tokens.css` (a vite plugin regenerates it on dev/build; the file is gitignored — never edit it directly) and feeds the Shiki theme in `src/lib/theme/digital-rust-theme.ts` and every palette-driven component. Outside the site, hexes are still duplicated by hand. When you add or change a colour/token, also update: - `Digital Rust Syntax Highlighting Specification.md` — canonical syntax/palette spec - `Digital Rust UI Specification.md` — canonical UI spec - `DESIGN.md` — YAML front matter holds the design-token copy - `static/ports/` — each port file hardcodes hexes in its own format. `pnpm contrast` reads the text pairs out of every port file and measures them, so run it after touching one. Ghostty, Konsole and Ptyxis carry a Safe Mode variant, and the OpenCode theme holds both modes in one file; VS Code and the KDE Plasma scheme are dark-only. Firefox and Thunderbird each carry one manifest per mode under `static/ports//`, and the check reads the colour pairs out of both manifests of each. - `static/ports/agentskill.zip` — a binary archive, so grep cannot see the hexes inside: `assets/tokens.css`, `SKILL.md` and `references/` carry their own palette copies, and `SKILL.md` holds the licence field and the `based-on:` spec version. It mirrors the installed skill at `~/.agents/skills/digitalrust`; update that first, then rebuild the zip. - `.impeccable/design.json` — design-system metadata generated by the impeccable skill. Refresh it with the skill; do not hand-edit it. Names (Ghost Pixel, Event Horizon, ...) are stable identifiers — never rename one without updating the spec, site copy, and all ports. ## Spec pages render from markdown `/spec` renders `Digital Rust Syntax Highlighting Specification.md` at build time (`src/lib/spec/render-spec.ts`). The markdown is canonical; edit the .md, not the page. Gotchas: - The build throws if the marker sections vanish: the spec must keep an H1 followed by a lede paragraph and an `## Overview` section, because the meta bar and live-demo component are spliced in after them. - Palette tables are recognised by a `Hex Code` first header cell and get card grids generated above them. Keep that column first. - Both spec .md files are served as downloads via prerendered `+server.ts` routes under `/spec/`. - The two spec .md files, DESIGN.md, PRODUCT.md, AGENTS.md and README.md are in `.prettierignore` on purpose. `pnpm format` must not reflow them. - The site's version badge and terminal fingerprint come from the `- **vX.Y.Z**` line in the syntax spec's version history. `vite.config.ts` inlines it when the config loads, so restart `pnpm dev` after editing that line; the /spec meta bar's Last Updated and the terminal's `updated:` line are the build date. Removing the version line fails the build. ## Releases `.tangled/workflows/release.yml` runs on an annotated `v*` tag push and is a gate, not a publisher. It checks that the tag is annotated, that the version agrees across the tag, the syntax specification and `package.json`, and that `scripts/make-archives.py` can build the release files. It uploads nothing. Publishing is a browser upload of `.release/dist` to the tag page, because a Tangled release artifact is an `org.tangled.repo.artifact` record in the repository account on its knot, written through an atproto OAuth flow a spindle cannot perform. Do not add a publishing step that writes `sh.tangled.repo.artifact` to the user PDS: the Tangled 1.0 indexer does not read it, so the tag page shows no artifacts and nothing reports an error. There is no build step in CI on purpose: the deliverables are files the tag already holds, and a `pnpm install` would put the run near the five minute microvm timeout. `RELEASE.md` covers the steps. The version must agree across the tag, the syntax specification's version history and `package.json`; `make-archives.py` refuses to build when they disagree, because the site's version badge reads the specification. Re-cut a failed release by fixing `main` first, then deleting the tag locally and remotely: a tag always runs the workflow from its own commit. ## Licence Repo-authored work is dual-licensed (CC-BY-4.0+ OR Apache-2.0+). Keep the root `LICENSE`, the port licence files (`static/ports/vscode/LICENSE.md`, `static/ports/digitalrustpi/LICENSE`, `static/ports/firefox/LICENSE`, `static/ports/thunderbird/LICENSE`), the README/footer wording and every `license` field or metadata block in sync. New code files (`.ts`, `.js`) start with the two-line SPDX header; markup, styles, JSON, markdown and port theme files do not. ## Hard constraints (from DESIGN.md/PRODUCT.md — enforced by review, not tooling) - Two modes. The dark theme is the base; Safe Mode is the light projection and the accessibility option. Both use one palette and one set of role names. - The rust ramp *is* the neutral scale (no separate grays). - Never use default black `#000` in backgrounds/shadows — darkest allowed is Event Horizon `#110402`. Never use pure white `#FFFFFF` in Safe Mode — lightest allowed is Ghost Pixel `#F7EAE8`. - No blur shadows: shadows are offset solids in Bad Sector. No border radius above 6px. - WCAG 2.1 AA contrast is required; `--amber-alert-text` (`#CB6353`) exists specifically as the AA-compliant text variant of Amber Alert (`#BF5747`) — use it for text on base/elevated surfaces, not the raw colour. - Two walls, and they are not the same colour. `--dr-border-color` is the wall on a *control* (button, input, checkbox, toggle, slider, tab, scrollbar thumb): a control identifies itself by its wall, so the wall clears 3:1 and it moves with the mode — Rouge Signal `#C76C5E` on dark, Dark Packet `#691B0F` in Safe Mode. `--dr-border-color-container` is the wall on a *container* (card, panel, code block, toast) and is Dark Packet in both modes, because content identifies a container and WCAG 1.4.11 does not apply to it. `--dr-border` (the 2px shorthand) and `--dr-border-thick` (4px, page chrome) both use the container wall. The bottom six ramp stops, Bad Sector to Kernel Panic, span 2.04:1 end to end, so no pair drawn from them can reach 3:1: a compliant dark control wall is a warm mid-tone by necessity, and this is why it looks the way it does. - Never give a *disabled* control the control wall: disabled controls take `--dr-surface-highlight` as both fill and border, so they read as switched off and they stay outside the contrast floor. - Diagnostic priority: errors (Amber Alert) outrank keywords; don't rebalance syntax colours decoratively. - `prefers-reduced-motion` must suppress all animation. ## Gotchas - Safe Mode is implemented on the site, and the dark theme meets the same floors: `pnpm contrast` reports no deviation on any control, state, focus ring, scrollbar thumb, text role, syntax role, terminal slot or port pair in either mode. The recorded deviations are container walls and the optional rainbow-bracket magenta. `palette.ts` holds one role table with a dark and a safe column, and `toTokensCss()` emits the dark block, the `[data-scheme='safe-mode']` block, and the `prefers-color-scheme: light` block from it. Add a role by adding a row, never by writing a second block by hand. - The ANSI map is a role table too: `ansiSlots` maps each of the 16 slots to a palette name for display, and the `dr-term-*` rows give the slots their values. Both must agree with the spec's ANSI tables. A slot that carries the paper colour of its mode (slot 0 on dark, 7 and 15 in Safe Mode) is a fill and is excluded from the text floor by the check. Slot 8 is the dim ink, which is a desaturated tone rather than a darker one, because a dimmer colour cannot clear 4.5:1 in either mode. - The agent skill at `~/.agents/skills/digitalrust` mirrors `static/ports/agentskill.zip`: update the installed skill first, then rebuild the zip. Its `assets/tokens.css` is a copy of `src/lib/generated/tokens.css`, and `references/safe-mode.md` holds the projection rule and the mode tables. The skill and the specs must agree; `SKILL.md` carries a "Reading the specifications" note for any passage that lags. - The Firefox port is two add-ons, one `manifest.json` per mode, at `manifest_version` 3. Only the dark theme declares `strict_min_version` 156, because its header gradient needs `backgrounds_area`; Safe Mode needs nothing newer than the classic colour set, so it declares no floor and the accessibility add-on installs on older Firefox. AMO signs the add-on, so the repository ships the manifest and never an XPI. A theme version belongs to the add-on and not to the specification, so `make-archives.py` checks only the shape: a version AMO accepts, `theme.colors`, and a gecko id that no other manifest claims. `static/ports/firefox/README.md` holds the colour map and the keys Firefox 157 stopped painting (`tab_loading`, `sidebar_highlight`, the URL bar dropdown, the new tab search box) — they still paint on 156, so do not delete them. - The Thunderbird port is two add-ons, one `manifest.json` per mode, at `manifest_version` 3 with `strict_min_version` 128.0. The addons.thunderbird.net upload validator rejects an MV3 theme below 128.0, and the theme guide does not state that floor, so do not lower it. Thunderbird does not sign add-ons, so a gecko `id` is mandatory, and each id is claimed by one manifest only. In Thunderbird `sidebar` is a *tree* (the folder pane and the message list), and `sidebar_highlight_border` exists only there; it reads `--dr-border-color` because the hover wall measures 2.84:1 on Bad Sector, under the 3:1 state floor. There is no new tab page, so `ntp_*` and `bookmark_text` are absent, and the port ships no image files, so it carries no `additional_backgrounds` header shade. `static/ports/thunderbird/README.md` holds the colour map and the reason for each omission. - Components read role tokens, never raw palette names. A raw `var(--ghost-pixel)` in a component is a bug, because the named colours do not change between modes. `src/lib/theme/digital-rust-theme.ts` builds both Shiki themes from the same role table, so the two modes cannot drift. - A machined track carries an invariant role of its own: `--dr-machined-track` (Bad Sector) for a toggle, `--dr-machined-rail` (Event Horizon) for a slider, and `--dr-machined-fill` for the thumb. Never give a track `--dr-surface-highlight` or `--dr-surface-base`; those lighten in Safe Mode and a Ghost Pixel thumb then disappears. - Mode selection: `src/app.html` applies a saved mode before the first paint. The same two literals live in `src/lib/scheme.ts`. Change both together. - Kit 3 uses `#lib/*` (package.json imports), not `$lib`. Import TS modules with a `.js` suffix: `import { color } from '#lib/palette.js'`. - The site's version badge, `/spec` meta bar, and terminal fingerprint come from the *first* `- **vX.Y.Z**` line in the syntax spec's version history. The badge follows the spec, not the code. - `trailingSlash = 'always'` gives every route a directory URL (`/spec/`, `/ui/`, `/playground/`) that works on any static server. `static/spec.html` and `static/ui.html` are meta-refresh stubs for old bookmarks — keep them. - Component styles in `.svelte` files are scoped; styles for `{@html}` content (the spec body) must live in `src/lib/styles/spec.css`, which loads only on `/spec`. - `.impeccable/` is committed state for the local impeccable skill. Leave it to the skill; do not edit it by hand. - The repo's public mirror is Tangled (`tangled.org/katsuricata.com/DigitalRust`). New ports need a file in `static/ports/` and a link in the port list in `src/routes/+page.svelte`. - EditorConfig: tabs, size 4. Prettier enforces it for everything outside `.prettierignore`.