A warm, tech-dystopian color scheme inspired by corrupted hardware and failing systems. digitalrust.katsuricata.com
DigitalRust AGENTS.md
13 kB · 75 lines
Markdown
at main

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/<host>/, 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.