Contributing

Changing the theme itself. For contributors and for agents working inside this repository. The binding version is AGENTS.md at the revision you are working on — CLAUDE.md imports it. Read that; this page orients you.

If you are applying the theme to another project, you want Agent integration instead.

Contents: Reading order · What is generated · The check loop · Without a decision · With a decision · Never · Conventions · Repository map

Required reading, in order

1. README.md, then theme.json — versions, profiles, entry points.
2. spec/identity.md, spec/foundations.md, spec/accessibility.md, spec/portability.md, spec/decisions.md — what is approved, and what is only proposed.
3. The token files the profile lists, and schemas/roles.mjs for the required role set.
4. The component you are touching: spec/components/<id>.md, its <id>.demo.html, site/src/styles/components/<id>.css, and its browser spec if one exists.

Material under references/ is evidence of origin, not authority. Images never override tokens.

What is generated, and what is a source

Sources — edit these	Generated — never edit
tokens/, spec/, ports/<slug>/ inputs, schemas/*.mjs, site/, packages/ui/src/, apps/demo/, scripts/	exports/, schemas/json/, packages/ui/dist/, site/src/styles/tokens.generated.css, the README marker blocks

Edit the source, then run npm run generate. Generated files are committed and drift-checked, so a stale export fails CI.

Where meaning lives, again: literal values in tokens/, meaning and permitted use in spec/, native keys in port mappings, test facts in evidence records. A contradiction between spec and tokens is a defect to resolve, not a choice to make.

The check loop

npm run validate      # sources only: manifest, decisions, tokens, docs, spec, contrast, ports, references, private material
npm run generate      # rewrite every generated artifact
npm run check         # CI mode: generated artifacts must be current, no orphans
npm test              # node --test over the sources and exports
npm run build && npm run test:dist   # the site under /theme/, base paths, consistency
npm run test:browser  # keyboard, axe, reflow, motion, no-JS, enhancements, print

Then, for anything touching execution evidence:

npm run verification:report
npm run verification:check
npm run test:verification

Finish with all of it green — and when you report, list the checks that were not run separately from the checks that passed. Node 24, npm ci, ES modules. There is no linter; the contract tests are the style guide.

If another checkout is testing, set a free port first: $env:PW_PORT = '4174' in PowerShell, PW_PORT=4174 in a POSIX shell. Build before you test.

What you may do without a decision

• Fix generation, mapping, rendering, test and documentation defects within the existing rules.
• Tighten a schema, as long as you add no new meaning.
• Add or correct evidence.
• Add a component whose every token reference resolves to an already-approved role.

What needs a decision first

• A new colour, or a change to an approved value.
• A new role, or a renamed role.
• A change to the focus, selection or contrast rules.
• A new profile.
• Promoting anything from proposed to approved.
• Changing the licence boundaries.

Open a proposed row in spec/decisions.md with the context and the alternatives you considered. Anyone — including an agent — may open one. Only the owner changes a status. A token becomes approved only through an accepted decision referenced in its $extensions["io.github.j3w1.theme"].approval.decision.

A good decision entry states the context, the decision, and the consequences — including measured contrast where colour is involved, as D-001 and D-003 do.

Never

• Weaken a test, add a tolerance, or remove a state to get a green result.
• Add a literal colour to a stylesheet or a demo. Token variables only.
• Commit font binaries, vendor template material, credentials or private project data. The scan lives in scripts/lib/private-material.mjs; the terms it forbids are deliberately not repeated anywhere else in the repository, and that includes here.
• Link to or import from the user site outside /theme/. There is no live import from j3w1.github.io and no bidirectional synchronisation.
• Mark a port verified without a real import and matching evidence.
• Modify j3w1/j3w1.github.io or j3w1/1w3j from this repository.
• Put normative content behind JavaScript, or inside <details>, on the site.
• Use main in any URL an agent is meant to fetch. Exports embed the tag.

Conventions

Runtime	Node 24, ES modules, npm ci
Style	No linter; the contract tests are the style guide
Files	LF line endings, kebab-case ids, closed lists in schemas/
Generated output	Committed, drift-checked, no timestamps, no commit hashes
Anchors	Only from scripts/lib/anchors.mjs
Commits	Conventional — feat:, fix:, docs:, spec:, tokens:, site:, chore: — and they explain why

Specification UI

Every human-visible CSS hex literal the specification UI renders gets its generated inline colour swatch (D-014). New sections and components inherit the whole-page build transform; never hand-maintain a swatch. Explicit runtime renderers, such as the token inspector, use the same literal parser and presentation helpers. Never scan the runtime DOM for colours. Preserve source and copy text and the machine exports, and run the hex source, dist and browser gates.

Execution evidence

tested stays the compatibility alias for testImplemented, and it is never a pass. Every browser test needs an explicit verification annotation naming its component, category, states, variants and limits. Use the shared evidence fixture for actual environment metadata. Matrix presence is rendering coverage only. Run records belong in the ignored test-results/ and the published dist/verification/, never in the deterministic committed exports. Do not claim a manual keyboard or screen-reader pass without a recorded protocol and environment.

Repository map

Path	Owns
theme.json	Versions, profiles and statuses, entry points, export map, site URL and base path, licence map
tokens/	Exact values: primitives, semantic roles, non-colour foundations, profile overrides (DTCG 2025.10)
spec/	Identity, foundations, accessibility, portability, the decision log, families.json, contrast.json, and one Markdown file plus one demo fragment per component
agents/consume.md	How to apply the theme elsewhere
schemas/	zod schema factories shared by scripts and site; schemas/json/ is generated
scripts/	Validators and generators
exports/	Generated and committed: resolved tokens, usage index, CSS custom properties, contrast report, coverage ledger, per-component JSON and briefs, compact and full Markdown, llms.txt, digests
site/	The Astro source of the specification page and token tools, built to dist/ and deployed to /theme/
references/	Pinned provenance, catalogued historical implementations, excerpts, reference screenshots with provenance
ports/	Native application ports, when they exist
templates/	Starting points for a port, a component, the fresh-agent consumption task, the private parity harness
tests/	Source tests, dist/ tests, browser tests, consumption fixtures

Reporting a problem instead

You do not need to be a contributor to file a good issue. Use the issue draft composer — see Troubleshooting.

---

Next: Concepts · Verification · Components

Package and demo changes

The official package implements the canonical contract; it is not another token source. Update maintained sources and regenerate complete distributions. Consumers should use Agent integration, not this contributor workflow.

For package changes, also run the packed-consumer workflow used in CI:

npm run ui:consumers
npm run test:ui
npm run ui:report

The three-engine report is distinct from the Chromium specification suite. Release archives are consumable without npm publication; publishing to the npm registry remains an owner release action.