Toolbox Web · Harness Documentation
How the Harness Was Built
View componentsThe rules, checks and harness that keep nxtg-react-components consistent, so people and agents can change it without drift. Everything below comes from the files in its harness/ folder.
From Toolbox’s app code to one package
Toolbox’s main branch is where the components were proven. They’re extracted into nxtg-react-components, which every product takes its UI from, with the rules that keep it on design beside it.
Toolbox’s app code
nxtg-react-components
ikon, ikon-dark, Toolbox presetFor people
- Storybook 10
- a11y checks on every story
- Visual Baseline
- the visual reference
- decisions.md
- why each rule exists
For agents
- AGENTS.md
- the MUST rules
- features.json
- tasks and their checks
- pnpm harness
- the task lifecycle
Who does what
Scripts check the rules. Agents do the work and review it. People write the tasks and decide what ships.
How new components get in
Three ways in, all by hand today. Whatever the source, it becomes a task before any code changes.
The gap: nothing watches the products for new needs. Every one of the 25 tasks started because someone wrote it down.
What we’d automate next
Gap radar
Read each consumer’s gap register and draft the task, so a workaround in a product turns into a proposal here.
Visual regression
Screenshot every story and compare, so rendering drift like the Switch/Toggle fails CI the way token drift already does.
Release on passing
Bump the version when a release-worthy task passes, so a merge can’t skip publishing. RELEASE-002 exists because one did.
Written, required, tested
Each rule is written for people, required of agents and checked by a script.
- Lot Audit is the default look:
#319E83green, Saira + JetBrains Mono,#FDFDFDsurfaces,#e4e4e5hairlines, a dark theme. - Ships as
ikon/ikon-dark; Toolbox is an optional preset.
- Use semantic token and variant names.
- Never encode a product brand into a reusable component.
ikon--nui-color-accent is #319e83ikon-dark covers the same tokensA changed token turns CI red.
Four layers, softest to hardest
- HD-001 … HD-014. Design: HD-009 baseline, HD-010 additions, HD-011 to HD-013 anatomy.
- Each records why, and when to revisit.
- Semantic names, no product brands, no app logic in the core.
- Keep native props, refs, a11y and focus.
- Visible changes come with a story; behavior changes with tests.
visual-style-contract.test.tslocks the theme tokens.- Per-component tests lock anatomy and variants.
- Storybook runs a11y checks on every story.
- One task at a time, allowed paths, an independent checker, and only
verifymarks a task passing.
A task, from next to passing
Every task goes through the same six steps.
Picks the next task.
Enforces: One task at a time.
Waiting in the list.
What “passing” leaves behind
Verify doesn’t just flip a status. It records what ran and fingerprints every file the task touched, so a later change can’t hide behind an old pass.
Measure Modal against the Toolbox dialog
- status
- passing
- run record
.harness/runs/2026-08-27T21-30-25-410Z-MODAL-001.json- commit
8cfbd54- command
pnpm check, exit 0, 12.3s
pnpm harness:check compares every fingerprint on every run. A mismatch reports the evidence as stale, and the task has to be verified again. That’s what RELEASE-002 fixed after a version bump skipped the flow.
What’s in harness/
Versioned in Git, so any session picks up where the last one stopped.
The task list, and the source of truth.
- 25 tasks, all passing. Each has its behavior, acceptance criteria, the commands that verify it, the paths it may touch, its status history and its evidence.
- Only
pnpm harness verifycan set a task to passing.
The toggle
The Lot Audit and Smart Marketing toggles differ. The contract test covers tokens, not rendering.
| What could drift | Checked today | By |
|---|---|---|
| Theme tokens | ● covered | visual-style-contract.test.ts |
| Locked anatomy and variants | ● covered | per-component contract tests |
| Rendering, like the Switch/Toggle | ○ not covered | no test yet |
| Visual regression | ○ no runner yet | see docs/harness/quality.md |