j3w1 UI Theme Spec

Identity

What the j3w1 theme is, where it came from, and the five rules that keep a port recognisable.

True-black canvas, editor and terminal interiors (#000000), neutral near-black panels and raised layers, rose interface text and terminal/agent prose, and distinct syntax and status hues (D-041). Red marks identity, focus, selection and danger; ordinary application content and terminal prose use rose; white is reserved for document headings, exceptional highlights and contrast-critical roles. Keep 1px square borders, zero radii and one monospace family for chrome, reading and code. Darkness is the canvas; readable content is the priority.

Five rules keep an implementation recognisable:

1. Preserve the true-black base, rose application and terminal text hierarchy and restrained red identity. Use semantic colours to distinguish code, additions, warnings and information.
2. Use the role assigned to a token, never the token whose colour happens to look closest.
3. Keep content, selection, keyboard focus, diagnostics and changed text distinguishable from one another. Selection is a fill; focus is a ring.
4. Nothing is rounded, blurred, glowing or gradient-filled. Elevation is a 1px border and, for modals, a backdrop.
5. Preserve the host application’s behaviour, keyboard handling and accessibility settings. Geometry and typography limits of a host are documented deviations, not reasons to rewrite it.

Where it came from

The palette began on a Manjaro i3 workstation (j3w1/1w3j): a pywal ramp from a red wallpaper, frozen and tuned slot by slot in config/Xresources. The i3 configuration gave the rest: 1px borders, 14/−2 gaps, tabbed layouts, dunst toasts framed in #ae1914, dmenu selections in #630f0d. Its web version, j3w1/j3w1.github.io, named the roles this specification uses and wrote the first contrast contract. Both are pinned in references/sources.json. This repository is the authority: later changes in either source are proposals, not automatic updates.

What “modern” means here

Clear structure, responsive layout, strong keyboard and screen-reader support, exact states, pleasant controls. Not pill buttons, glass panels, gradients, neon glows, a Material-style redesign, or red on every surface; the site draws such misreadings as labelled non-examples.

One exception (D-014): the generated preview beside each visible CSS hex literal on the spec page. It adds no palette, role or geometry rule, and text, copying, keyboard order and no-JS access stay intact.

• A 16px circle with its theme-derived 1px boundary; alpha shows over a checkerboard of theme tokens.
• On CSS :hover it becomes a 17.4px square (fast duration, ease-out on transform and border-radius; none under reduced motion).
• Mouse and pen pointers also open a non-interactive popup with the exact value; touch and unknown pointers do not. CSS :hover alone drives both, never the hover or any-hover media features, which can report no hover despite a mouse.
• The popup follows the pointer inside the circle at an 8px gap, flips when needed and keeps an 8px viewport gutter. Tracking has no animation.
• It closes when the pointer leaves the circle, on an outside press, Escape, loss of window focus, and on page or nested scrolling unless the circle is still under the last pointer position. It never captures input, holds itself open or adds a keyboard stop; token tables and the token inspector keep the persistent information.

Profiles

• default — the approved everyday composition: true-black interiors, neutral application layers, rose application text and terminal/agent prose, red interaction accents, and semantic green, amber, blue, violet and cyan for coding and terminal content (D-041). code.syntax.* is coloured by default; code.hued.* remains the compatible semantic alias family for ports that already consume it.
• heritage-ansi — the sixteen Xresources slots and their historical assignments, exact, including those that fail the contrast floor. For archives and fidelity, never new interface text.
• extended — the earlier proposed, unapproved overlay for syntax, terminal and chart colours. D-041 updates the default directly; it does not promote this profile.

Naming

Roles are color.<group>.<role>, from a closed group list: surface, text, border, interaction, action, status, code, diagnostic, diff, terminal, chart, icon. Primitives are color.primitive.<family>.<step>, the step rising with luminance; roles alias primitives, and primitives carry provenance. A CSS custom property is the path with dashes for dots: color.interaction.focus.ring → --color-interaction-focus-ring.

Foundations

Surfaces, text ladder, borders, interaction states, focus, typography, spacing, density, elevation, motion, icons and layout, with the rules that govern each role.

Values live in tokens/; this document says what each role means and where it may be used. Every rule is normative for the default profile.

Surfaces

surface.desktop and surface.canvas are true black (#000000). Readable content sits on the canvas or on:

• default (#0d0707) for panels and cards;
• raised (#140b0b) for sticky headers, menus and popovers;
• overlay (#1c1010) for dialogs and drawers;
• accent (#3d0c0a) for the user’s own content set apart from its neighbours, such as outgoing chat messages; secondary text on it uses text.muted, never text.subtle. Red links cap its brightness: at this hue it stays at or below #3f0c0a (D-035);
• sunken (#000000) for reading and detail panes;
• input for form-control fills;
• true-black chrome and warm rose-black chrome-alt for window frames and bars.

D-041 keeps ordinary application layers warm rose-black, without a cool blue cast; surface.accent remains a bounded red message surface, not a tint for every panel.

The layers differ only slightly, so controls also carry border.control. Never tint photos, video, document content or user-defined data colours.

Text ladder

D-041 uses rose for ordinary application text and terminal/agent prose (text.default, #e99499); terminal prose and prompts use bright rose (terminal.fg, #ffa2a7) for clearer small text. White is limited to document headings, exceptional highlights and contrast-critical roles. Exact values and ratios per surface are in the token and contrast reports. Metadata and comments people need to read use text.subtle, never a decorative border or historical ANSI primitive.

Borders

Every border is 1px (border.width.default). 2px (border.width.emphasis) is only for the selected indicator bar, the sticky-header rule and the invalid border. The quote rule, which marks a block rather than bounding a control, is the one wider edge, at twice the emphasis width.

• border.divider (#482b2b) separates rows and sections.
• border.default (#482b2b) is decorative, never the only visible edge of a control.
• border.control (#c81a1a) is the edge of every form control at rest.
• border.active (#e53935) marks the focused or active control.
• border.overlay (#c81a1a) frames every floating layer.

Styles: solid by default; dashed only for focus, drop targets and read-only fields; dotted for hints; double for conflicts. Radius is 0 everywhere, including checkboxes, switches, chips, avatars, badges and tooltips.

Interaction states

Every interactive component declares which of these apply and demonstrates every applicable one, including the combinations. Precedence when several apply: disabled > loading > invalid > selected > pressed > hover; focus-visible is always drawn on top and never suppressed by another state.

Rules that apply everywhere:

1. Selection is a fill; focus is a ring. Neither borrows the other’s form. The ring must reach 3:1 on whatever it sits over: #e53935 falls below it on action.primary.bg and status.danger.fill, so the ring recolours on those fills; it meets it on interaction.selection.bg (D-027), so a selected row keeps the ordinary control ring.
2. Focus ring (D-006; component mapping clarification D-015). Controls and rows: outline: 1px dashed {color.interaction.focus.ring}; outline-offset: -2px. Focusable containers (panes, windows, dialogs, cards): outline: 2px solid {color.interaction.focus.ring-container}; outline-offset: -3px. On filled surfaces use the component’s explicit ring mapping: primary buttons and checked controls use focus.ring-contrast (the control ring in interaction.focus.ring-container, D-040) where declared; destructive buttons use their declared on-fill text role. The selection fill is the exception and takes the ordinary ring, on the measurement in rule 1. Keep the control or container geometry independently of the colour mapping. :focus:not(:focus-visible) draws nothing. Forced-colors mode uses Highlight. A host focus indicator is never removed without this replacement.
3. Never colour-only. Every state and every status carries a second channel: a glyph (✕ ! ✓ i ·), a border width, an underline pattern, or an ARIA state. Charts carry pattern fills.
4. Hover changes fills and borders, never text colour alone, and only on hover-capable pointers.
5. Disabled never uses opacity. Opacity leaks the background and breaks contrast accounting.
6. Contrast floor. Text ≥ 4.5:1 and control boundaries, rings and meaningful graphics ≥ 3:1 against the actual background of the state, measured after compositing translucent colours.
7. Motion. Durations are 80 / 120 / 150 ms at most, on opacity, transform and background only; under prefers-reduced-motion: reduce every duration is 0.01 ms, nothing slides or shimmers, and no behaviour waits on transitionend.

Actions

Four button tones:

• primary, the only filled button at rest: action.primary.bg (#7d1310) with action.primary.text (bright rose; D-041).
• secondary, an outline: border.control, text text.bright.
• tertiary, a ghost or icon button: text.default, hover interaction.hover.bg.
• destructive, an outline in action.destructive.text (#f73f35) that fills on hover with action.destructive.hover-bg (#dc282e) and #f9faf9 text. A filled variant exists for confirm dialogs.

Destructive actions also need a confirmation step or an undo; the colour is not the safeguard.

Status, diagnostics and diffs (D-001)

D-041 updates the palette while preserving the D-001 semantic roles.

Five statuses: red danger, amber warning, green success, blue info, and grey neutral. Each has text, fill, on-fill, tint and border roles, a required glyph (✕ ! ✓ i ·) and its own underline or border pattern (wavy, dashed, solid, dotted, double). Use the explicit on-fill role on a status fill, not ordinary body text. Coding and terminal roles also have violet and cyan; these distinguish syntax and named terminal colours rather than tinting ordinary application chrome. Every use follows its role and measures contrast on the actual surface.

Diagnostics:

• error: wavy #e53935 underline, #f73f35 text, #e53935 stripe, #2b0e0d line background;
• warning: wavy amber;
• info: dotted blue;
• hint: dotted text.subtle;
• unused: text.muted with a dotted underline.

Diffs:

• added: #0f1a0e line background, green gutter mark and +; word-level additions as a 2px green underline (no fill, so text contrast is untouched);
• removed: #2b0e0d background, red gutter mark and −; word-level removals underlined and struck through;
• modified: #1f1a0c background, amber gutter mark and ~;
• conflicts: a double #f73f35 border.

Always keep textual markers and existing status icons.

Code and terminal

The surface and interior roles remain distinct in scope, but D-041 makes surface.code, surface.terminal, code.bg, code.gutter-bg, terminal.bg and default ANSI 0 all true black (#000000). This replaces the earlier #0c0909 interior assignment without changing historical ANSI primitives.

Editor surfaces:

• code.current-line uses the neutral default layer;
• code.line-number uses the readable subtle tier; active numbers and the caret step up to the normal and bright text tiers;
• code.selection-bg is a subdued red selection fill;
• code.search-match-bg marks matches, with the current match inverted by code.search-current-bg and code.search-current-text;
• code.bracket-match is a 1px accent border;
• code.indent-guide is a neutral separator and code.whitespace is a decorative neutral mark.

Syntax in default is semantic: violet keywords, green strings, amber numbers/constants/attributes/escapes, blue functions, cyan types/properties, coral tags/invalid text, rose variables/operators, muted punctuation and subtle italic comments. Headings use the bright text tier. The existing code.hued.* roles resolve to the corresponding semantic syntax assignments; ports need no separate palette. Invalid text takes a wavy underline and deprecated text a line-through. Languages inherit these roles; a language-specific override needs a written reason. Selection and diff fills must be checked with the syntax foregrounds they retain.

Terminal slots:

• heritage-ansi carries the sixteen Xresources slots exactly. color.primitive.ansi.* remains byte-for-byte historical; the heritage profile explicitly restores its historical slot and background assignments.
• default uses the semantic sixteen (D-041): black, red, green, amber, blue, violet, cyan and rose, followed by their bright variants. Slots 7 and 15 both use bright rose #ffa2a7 for readable terminal text. Slot 0 is the true-black background; slots 1–15, including neutral bright black, target at least 4.5:1 on it. Slots 2 and 10 remain green so programs using ANSI additions can be read correctly.
• extended remains a proposed overlay, not an approved alternative needed to obtain coloured syntax or terminal slots.

Programs choose the slots and may emit 256-colour or true-colour values that bypass them. A theme cannot repair host dimming or independently recolour text that shares a host theme key with a background. Port guides record those limits; Claude Code’s shared word-highlight and edit-summary keys are one example. Their dedicated diff.added.shared-word and diff.removed.shared-word roles balance summary-on-black and ordinary rose-on-highlight at about 3:1. These roles apply only where a host combines those two uses; they do not replace standard diff emphasis or relax the ordinary-text contrast floor. Syntax foregrounds require separate host review.

Typography

One family: SauceCodePro NFM (Source Code Pro in the Nerd Fonts build), falling back to Source Code Pro, Cascadia Mono, Consolas, Liberation Mono, DejaVu Sans Mono and monospace. The site records size-adjust metrics for the fallbacks; no font file is distributed. Weights 400 and 700, plus italic.

Scale (size/line-height in px): ui-sm 12/16, ui-md 13/18, ui-lg 14/20, reading 15/24, code 13/19, terminal 13/19 with −0.5px letter-spacing, h1 20/28 bold, h2 16/24 bold, h3 13/18 bold in text.heading, caption 11/16 only with text.muted or lighter. D-037: display 32/40 for page heroes and metric figures and title 24/32 for page titles above h1; components keep h1–h3. Hosts keep the size the user chose; tiny UI text is a metric of the reference implementation, not a rule.

Spacing and density (D-009)

Spacing steps: 0, 1, 2, 4, 8, 12, 16, 24, 32, 48 px. compact is the default density (D-038): it applies wherever no data-density is set, in components, the site and copied bundles. Set data-density="comfortable" on any subtree to opt in to the larger mode:

Both meet the 24×24 CSS-pixel target minimum; compact needs 4px between neighbouring targets. Table rows always use the comfortable row height (a data row is content, and compact rows are harder to scan); controls inside a row follow the page density. The site’s 3px i3 gap, 14/−2 window gaps and 28px bar are window-manager geometry, not theme tokens.

Elevation and layering

No shadows, except shadow.floating (0 6px 22px rgb(0 0 0 / 55%)) on the i3 floating-window specimen. A floating layer is a 1px border.overlay on surface.raised; a modal adds surface.backdrop (rgb(0 0 0 / 65%)). Stacking: canvas 0 < raised 1 < popover 10 < drawer 20 < dialog 30 < toast 40 < skip link 1000.

A popup opened by hovering follows the pointer:

• It sits 8px from the cursor, flips to the cursor’s other side instead of crossing a viewport edge, and keeps 8px from every edge.
• It moves again on pointer move, scroll and resize.
• A popup with nothing to operate takes no pointer events; one with a control or link stays reachable and open while the pointer is inside it.
• Either kind closes when the pointer leaves both the trigger and the popup; the reachable kind waits 300 ms first, so the pointer can cross between them, and stays while keyboard focus is on its trigger or inside it.

Opened from the keyboard, the same popup anchors to its trigger: below it, or above when there is no room below. This is a placement rule only; what opens a popup and what kind it is belong to the component’s contract.

Icons

SVG line icons on a 16px grid, 1.5px stroke, stroke: currentColor, fill: none, sizes 12 / 16 / 20. No icon font is needed; Nerd Font glyphs appear only in terminal and heritage specimens. Icon-only controls carry aria-label and a tooltip. icon.decorative (#986f72) is for glyphs that mean nothing on their own.

Layout

Reading measure 72ch, content column 680px, application layout 1440px. Breakpoints 320 (reflow floor), 600, 900, 1280.

• Components use container queries.
• Sidebars collapse to drawers below 900px.
• Data tables scroll horizontally, with a sticky first column, below 600px.
• The page never scrolls horizontally at 320px.
• Right-to-left mirrors breadcrumb separators, pagination, sidebar and drawer sides, wizard progression, affixes and tree indentation.

Typography semantics (D-033)

All content titles and H1–H6 use text.heading; size, weight and spacing carry the hierarchy. Chrome and window titles use text.default or text.bright; body and long-form prose use text.default and text.prose. Bold inherits the current semantic colour, including inside headings, muted text, links and selections, and never requests white by itself. D-041 keeps ordinary application text and brighter UI labels rose, with white reserved for document headings, exceptional highlights and contrast-critical roles. Terminal and agent prose uses rose terminal.fg; the semantic hierarchy and inherited bold rule remain. Selection and on-fill roles are explicit and must be measured against their actual backgrounds. The historical D-033 migration audit is docs/rose-typography-migration.md.

Form composition and recovery

A local reference workflow preserves values through validation, review and an explicitly simulated save.

Scope

The validation and recovery pattern composes admin-form, text-field, textarea, select, checkbox, alert, button and table under proposed D-020. It is a reference composition, not an approved profile or a persistence system; the component rules still apply. Its JSON contract (spec/patterns/validation-recovery.json) records the components’ content digests, fields, fixtures, transitions and limits.

Interaction

1. Submit to validate. Errors appear together in a focused summary linking to the affected fields; every entered value is kept, including unrelated notes and choices.
2. Correct and submit again to reach review. Editing never announces errors per keystroke nor silently removes the last submitted summary. Review offers an explicit way back to editing.
3. Confirming the review enters busy: controls are disabled and a pending message is shown.
4. Only the separate Complete simulation action reaches success; a submit click alone never does.

Busy, disabled, invalid and success each mean something different. Reset clears in-memory values and errors.

The ws-07 conflict on Name and Hostname and the lowercase hostname rule (letters, digits, hyphen-separated segments) are local admin-form fixtures, not server checks; no request, account, storage or database is involved. Without JavaScript the page keeps static normal, invalid, busy and success examples.

Evidence and limits

Automated protocols cover keyboard submission, summary navigation, correction, preservation, review, busy, success, narrow layout and no-JS content; a test that exists is not a passing run (see the verification report). No manual screen-reader pass is claimed. Submit-time feedback follows the GOV.UK validation pattern.

Figma Variables bridge

A one-way, pinned Variables API bridge with explicit diffs and external ownership receipts.

Supported mapping

This independently written bridge maps sRGB colors to COLOR variables and scalar px spacing and radius to FLOAT variables.

• Aliases stay native variable aliases.
• Token paths are stable identities. Slash-separated names live in the j3w1/theme/default/v1 collection.
• Alias primitives are dependencies with empty property scopes, not newly approved application roles.
• Semantic scopes are specific to text, fills, strokes, gaps and corner radius.
• Eligibility and pending decision IDs travel with each definition.

Only the approved default profile is imported; heritage and proposed profiles are reported, never turned into extra modes. Typography, shadows, composite borders and other unsupported types are reported, not flattened. Figma does not import this JSON natively; the adapter uses the Variables Plugin API. Fonts are neither imported nor distributed: install the families the pinned typography tokens name.

Generate a pinned payload

In a verified checkout, run:

node scripts/figma-bridge.mjs --ref FULL_COMMIT_OR_RELEASE_TAG > payload.json

The default sample is color.surface.default, color.text.default, space.4 and radius.none, plus their two alias dependencies; --roles takes an explicit comma-separated list instead. The command reads Git objects at the resolved full revision, never moving branch bytes or the working tree, and records source and payload digests, the mapping version, unsupported items and excluded profiles.

Reviewed import route

Use the Figma connector’s use_figma Variables API route, in a new design draft or an existing collection whose current receipt you hold, after reading the connector’s current skill/API instructions. The adapter is exports/figma/importer.mjs; pin its download to the same reviewed delivery revision as these instructions.

1. Load the module’s function in the connector script (remove only the ES-module export keyword), then return the awaited call:

   return await importFigmaVariables(figma, {
     payload, receipt: null, documentKey, action: "dry-run"
   });

2. Pass the locally generated payload and the exact target file key as explicit inputs.

3. Inspect the returned diff. Dry-run only reads.

4. Call again with action: "apply", only for the reviewed change.

5. Keep the whole returned receipt outside the document and the repository. Every later dry-run and apply must pass that receipt and the same document key.

An exact re-import changes nothing; updates show before/after definitions. Owned variables left out of a payload are kept and reported, never silently removed. Receipts are trusted local ownership records, not importable third-party configuration.

Limits of this route:

• at most eight variables, dependencies included, per namespace; one collection; one default mode — small enough for one incremental connector operation. Larger payloads fail before anything changes;
• apply and rollback need the connector’s atomic script execution; this module is not a standalone plugin transaction manager;
• no team publishing permission or paid plan capability is assumed;
• permission, mode and API errors stay failures.

Rollback and conflicts

To undo the most recent apply, call with action: "rollback" and the current receipt.

• Existing variables get back their exact recorded values and metadata.
• New variables are removed in reverse dependency order.
• The result returns the previous receipt. Keep it for another rollback or a later import.
• A newly created collection is removed only when it holds no unrelated variables.
• Rollback refuses to remove a variable that a kept variable in any local collection still references. Check any canvas bindings you added after the import before you roll back; this adapter does not audit every canvas node.

Before any change, the adapter compares every owned ID, value, description, scope, collection identity and mode against the receipt; missing, detached or hand-edited variables stop apply and rollback. It never adopts a matching name without a receipt. Resolve a conflict deliberately in Figma or in a separate draft; never discard ownership records to force an overwrite.

Actual verification status

A real six-variable sample was imported through the connector into a new design draft, with Starter/Full access and Plugin API 1.0.0.

• Alias IDs matched. Spacing and radius matched exactly.
• Color channels matched the exact float32 form of the source channels, with no tolerance.
• An exact re-import changed no IDs.
• A separately previewed spacing addition was applied and rolled back.
• A deliberate manual edit was rejected without being overwritten; the test edit was then explicitly restored.

Private receipts stay outside public artifacts; the issue evidence records the exact candidate and source revision. Source protocols also cover detached IDs, value updates, first rollback, unrelated variables, invalid payloads and extra modes against an explicit API fixture; these are fixture results, not account-capability claims. No component kit, native port, library publication, manual design review or automatic Figma-to-token sync is claimed. D-019 remains proposed.

Accessibility

Contrast targets, focus and keyboard contracts, reduced motion, forced colours, and what an automated pass does and does not prove.

What is claimed

WCAG 2.2 criteria are measurable design targets for the theme’s roles. A green contrast report and a clean automated scan show that the specified colours and the reference markup meet them; they are not a conformance claim for any adopting application. Keyboard operation, focus management, labels, reflow and manual review stay the consumer’s job. The theme’s own limits are under Limitations.

Contrast

• Ordinary text: at least 4.5:1 against the actual background of its state, measured on resolved sRGB values after compositing translucent colours.
• Large text (18.66px bold or 24px regular and above): at least 3:1.
• Control boundaries, focus rings, meaningful icons and chart marks: at least 3:1 (WCAG 1.4.11).
• Disabled text is exempt under WCAG 1.4.3; house policy still needs 3:1 (text.disabled), below the ordinary-text floor by design.
• Never round a value into a pass. The report keeps the unrounded ratio and shows two decimals: 4.4996 reads 4.50 and fails.
• Heritage values that fail (#a3676b as text, #7d1310 anywhere as text) are flagged $deprecated in the heritage-ansi profile, never shown as ordinary passes.

exports/contrast.md lists every declared pair (the global pairs in spec/contrast.json and every component’s stateTokens and contrast[] entries) with its computed ratio. Waived pairs carry their reason; a waiver is valid only for decorative graphics that are never the only boundary of a control.

Text hierarchy

The colour roles are in spec/foundations.md, Typography semantics (D-033); D-041 uses rose application text and terminal/agent prose; white is limited to document headings, exceptional highlights and contrast-critical roles. Bold inherits its context. Selection and contrast-critical on-fill roles are checked against their actual backgrounds. Heading level is conveyed through structure, size and weight, never colour alone.

Focus

Focus is never lost and never invisible. The ring is defined once, in spec/foundations.md, Interaction states, rule 2 (D-006, D-015).

• :focus without :focus-visible draws nothing: pointer clicks stay quiet, keyboard focus stays visible.
• The state matrices render every declared combination, including selected+focus-visible and invalid+focus-visible, where rings disappear in practice.

Keyboard

Native controls keep native keyboard behaviour. Custom widgets follow the WAI-ARIA Authoring Practices pattern in their aria.apg:

• roving tabindex in toolbars, tabs, trees and listboxes;
• aria-activedescendant in comboboxes;
• focus trapping and Escape in dialogs and drawers;
• arrow keys in radio groups and menus.

Positive tabindex is banned. Every icon-only control has an accessible name. The site’s own controls (search, filters, inspector, copy) work with the keyboard, and the no-JS build keeps every normative section readable.

Motion

Motion follows spec/foundations.md, Interaction states, rule 7. Under prefers-reduced-motion: reduce:

• toasts, dialogs and drawers appear in place;
• indeterminate progress shows static stripes;
• loading glyphs do not spin;
• skeletons do not shimmer;
• tab indicators do not slide.

Forced colours and high contrast

Under forced-colors: active, rings use Highlight and selections Highlight / HighlightText. Borders survive because they are real borders, not box-shadows; pattern fills keep charts and diffs readable.

Reflow, zoom and text

Components reflow at 320 CSS pixels without horizontal page scrolling, at 200% browser zoom and at 200% text-only zoom. Rings and borders stay 1px / 2px CSS. Targets are at least 24×24 CSS pixels, with 4px spacing in compact density. Long labels wrap, or truncate with a visible affordance; the stress fixtures (English, Spanish, Chinese, Arabic with dir="rtl") exercise this.

Colour is never the only channel

Every status has a glyph; every state a border, pattern or ARIA change. Diffs keep their + − ~ markers. Charts carry pattern fills and a table fallback. The heritage-ansi terminal palette has less hue difference by design, a recorded limit.

Limitations (recorded, not hidden)

• The theme specifies colours, states and reference markup. It cannot make a host application’s own focus management, labels or reading order correct.
• The automated scan uses axe-core with the WCAG 2.x A and AA rule sets and does not test every success criterion. Manual checks (keyboard walks, screen-reader reading, zoom) need their own execution evidence; a missing protocol stays not run.
• The default semantic terminal palette targets 4.5:1 for slots 1–15 on true-black terminal.bg (D-041); ANSI 0 is the background. In heritage-ansi, slots 1, 4, 6, 8, 9, 10, 12, 13, 14 and 15 fail 4.5:1. Host dimming, non-default backgrounds and explicit true-colour output need their own measurements.
• Editors and diff viewers may preserve syntax foregrounds over selection or change fills. Check those actual pairs, not only syntax on the canvas. Claude Code reuses word-highlight backgrounds as edit-summary foregrounds; its port documents the resulting limitation separately from normal diff line contrast.
• interaction.text-selection.tint (D-036) requires the host’s compositing behavior to be known. A tint under text and the same tint painted over text have different contrast. The global pairs composite it over the canvas; Telegram’s tests cover its raised and accent surfaces. Those measurements do not certify every host, selected link or syntax span. The earlier rose-palette selection measurements are historical after D-041 and cannot be carried forward as current results.

Verification evidence and freshness

Source coverage. The coverage ledger records source facts: specified, demonstrated and test implemented. exports/coverage.json schemaVersion 1 adds testImplemented and keeps tested as a compatibility alias meaning the test file exists; component JSON and family totals use the same definitions. No coverage Boolean proves an execution or WCAG conformance.

Execution evidence. The static verification report gives per-test outcomes and per-component summaries. Evidence schemaVersion 1 records, for each result:

• the method (automated or manual), category and component;
• the states and variants it explicitly covers (empty lists mean “unspecified”, never “all”);
• browser and version, OS, viewport, profile, density and JavaScript setting;
• a run or protocol reference.

The recorded profile and density are the page’s declared data-profile and data-density when the test ends; tests that switch them say so in their scope. One browser engine never stands for another. Skipped, failed, not run and not applicable are separate outcomes, and every non-pass has a reason. Manual screen-reader and keyboard claims need protocol records. The automated suite targets Chromium; other engines stay not run.

Freshness. A claim is current only while the tested artifact’s digest and a broad source fingerprint both match. The fingerprint covers tracked contract sources, schemas, generators, site code, tests, agent guidance, CI configuration and the package lockfile, so an unrelated change can stale more evidence than strictly needed. A stale record keeps its real outcome and reference but no longer shows a current pass.

How the report is built.

1. A build first publishes a static not-run report and a subject manifest.
2. The browser reporter checks that source and specimen assets still match that subject before it publishes execution evidence.
3. Report generation writes only under dist/verification/ and checks that every specimen byte is unchanged.
4. The report’s own presentation has a separate static and browser gate; it never certifies itself.

Run timestamps and revisions live only in this post-test evidence, outside the committed exports and their digests, so no hash depends on itself.

Run it locally.

1. Build the site.
2. Run the browser suite.
3. Run npm run verification:report, then npm run verification:check, then npm run test:verification.

A local run names its local execution and digests and is never presented as hosted CI evidence.

Record a manual protocol. Pass a schema-valid evidence document to node scripts/verification-report.mjs <repo-relative-evidence.json>, carrying the real tested digests, the browser and environment, and a protocol: reference with the protocol identifier and recorded observations. Keep the protocol with the evidence; never copy private artifacts into this public repository.

Portability

How the theme travels to other applications and frameworks, what a port must reproduce, what it may declare unsupported, and how support is catalogued truthfully.

Scope of a port

A port themes only what the host documents as customisable. Editor colours, application chrome, terminal colours and plugin surfaces are separate scopes; a file that changes one does not claim the others. A port never:

• patches binaries or injects unsupported hacks (D-034 permits only the pinned, compatibility-checked Windows Windhawk styling adapter);
• overwrites a user’s whole settings file;
• replaces keybindings, credentials or unrelated preferences.

It installs under a unique name beside the host’s defaults and documents the rollback.

What every port must reproduce

1. The surface ladder: canvas, default, raised, overlay, input.
2. The text ladder: rose default, bright, prose, muted, subtle and disabled; white document headings and exceptional highlights; bold inherits color. Ordinary UI labels remain rose.
3. Focus as a ring distinct from selection as a fill, with the ring recoloured on fills.
4. Selection, inactive selection and hover as three distinguishable fills.
5. The status hues with their glyphs where the host renders glyphs.
6. Zero radii and 1px borders where the host allows geometry; otherwise a recorded deviation.
7. The monospace family by name, honouring the user’s size.

Every required role is mapped, explicitly inherited from the host, marked unsupported with a reason, or intentionally out of scope. A coverage percentage means something only with its denominator.

Fallbacks by host capability

Shared component defaults

Components whose Portability section links here follow these rules; their responsive and portability.nativeFallbacks fields carry them into the exports.

• Wrap labels and actions without changing source order.
• Use logical spacing in RTL.
• Preserve native target sizes at both densities; only bounded data regions may scroll horizontally.
• Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation.
• The host owns application data, persistence, permissions and services.

Web consumers

exports/tokens.css exposes every role as a custom property. Consume roles (--color-text-default), never primitives. A framework integration maps roles onto the framework’s theme keys and lists what it cannot express. agents/consume.md gives the reading order and the deviation report format; theme.lock.json pins the revision.

Native ports

A port lives at ports/<slug>/ with a README, port.json, mapping.json and importable artifacts under dist/. Add src/ only for real generator inputs that these sources cannot express, and evidence/ only for actual evidence; neither needs a placeholder directory. templates/port/ is a starting aid when work begins.

• capabilities.json refines each role into mapped, inherited, unsupported, out-of-scope or not-implemented, with a surface and a reason (D-018). A legacy unmapped reason stays unclassified, never guessed. One generated catalogue feeds the summaries, drill-downs and task kits; private parity records never enter it.
• Every port classifies a new role, even when only one maps it. Telegram alone maps surface.accent (outgoing bubbles; incoming stay surface.raised, timestamps on both text.muted) and interaction.text-selection.tint (Android text selection; Desktop keeps selection.bg with near-white text). Claude Code’s userMessageBackground keeps interaction.selection.bg, and Obsidian, which keeps the text colour, would suit the tint; each adoption is a separate change with its own import check (D-035, D-036).
• Statuses are experimental, verified and deprecated. Reference implementations and roadmap candidates are not statuses.
• verified needs a real import into the recorded application version, with matching evidence and a token digest equal to the current default profile. Import verification is separate from mapping state and declared status: a relevant change to the target, tokens, mappings, capabilities or artifact bytes makes evidence stale, and a failed or missing check never passes. A successful XML or JSON parse is a structural pass, not verification.
• Never hand-edit a generated hex. Fix the mapping or the approved token and regenerate.
• npm run generate writes dist/ for every port whose format has an emitter in scripts/lib/port-artifacts.mjs (warp-yaml, ghostty-config, claude-theme-json, codex-tmtheme, chatgpt-appearance, orca-theme, obsidian-theme, windows-theme and telegram-theme today). Each emitter returns the complete declared array of text or byte artifacts. Binary files are hashed and copied byte for byte; text files retain the existing line-ending convention. Unsafe or duplicate paths and missing/extra outputs fail before any port artifact is written. Obsidian emits a manifest and CSS together; Telegram emits Android text and a Desktop zip. Orca emits its app/editor and terminal data-theme plugin alongside the compatible Ghostty export; the Ghostty file alone does not configure full application appearance.
• The README downloads table links each file at the release tag; the site serves a copy at ports/<slug>/<file>.

For JetBrains, an editor scheme (.icls) and a UI theme plugin are separate capabilities; the scheme alone does not recolour toolbars or dialogs. For Notepad++, a style-theme XML, the dark-mode chrome setting and User Defined Languages are three separate mechanisms. Read the vendor documentation for the tested version before mapping.

The reference implementation

j3w1/j3w1.github.io is the flagship web implementation and the source of the observed values. Nothing is scraped at build time or synchronised in either direction. An integration there pins a release of this theme through a separate reviewed change and records its site-specific values (window-manager geometry, wallpaper gradients) as such.