Reference

CLI workflows

Every workflow is available both as an MCP tool and as a command. Run npm run COMMAND -- --help for the complete options supported by each one.

Portfolio & snapshots

The local registry lives at .ztothez-design-local/portfolio-registry.yaml and snapshots live under .ztothez-design-benchmarks/. Both are excluded from Git and package output.

Validate and inventory the local registry

bash

zz-design portfolio validate-registryzz-design portfolio inventory

Create a disposable snapshot

Runs no command inside the original project. Use --keep only when an isolated adapter needs the snapshot for a later local stage. Linux executable stages use Bubblewrap and fail closed when process isolation is unavailable.

bash

zz-design portfolio snapshot --project scenestart

Run an isolated baseline or cohort

Projects with a declared static fixture and product contract also run browser journeys, the consolidated quality gate, optional heuristic review, and checksummed artifact capture.

bash

zz-design portfolio baseline --project scenestart --run scenestart-baselinezz-design portfolio benchmark --cohort development --run development-001zz-design portfolio verify-unchanged --run development-001zz-design portfolio report --run development-001

Repository audit

Deterministic static analysis for coupling, component size, raw design values, mock production paths, network states, accessible names, and placeholder interactions.

Audit a repository

bash

npm run audit -- --repo PATH_TO_APPLICATION --fail-on error

Contract & brief validation

Structural validation runs before generation. A brief that leaves users, tasks, data behavior, recovery, assumptions, or acceptance evidence undefined blocks generation.

Validate a product contract

bash

npm run validate-contract -- \  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \  --project-root .

Validate a product design brief

The installed CLI provides the same report with zz-design validate-brief --brief PATH.

bash

npm run validate-brief -- \  --brief knowledge-base/design-intelligence/product-design-brief.template.yaml

Evaluate a heuristic review

bash

npm run review-heuristics -- \  --review knowledge-base/usability-evaluation/heuristic-review.template.yaml

Design, trust & information design

Three independent contract families: what the interface looks like, what it truthfully claims, and how it ranks information.

Validate a design-intelligence deliverable

bash

npm run validate-design -- \  --manifest knowledge-base/design-intelligence/design-deliverable.template.yaml

Validate interface trust and data provenance

bash

npm run validate-trust -- \  --contract knowledge-base/design-intelligence/interface-trust.template.yaml

Validate operational information design

bash

npm run validate-information -- \  --contract knowledge-base/design-intelligence/information-design.template.yaml

Comparison & human review

Omit --require-release-ready while preparing an honest incomplete review. Structural validation can pass while the release decision remains blocked by missing stages or evidence classes.

Validate an interface comparison

bash

npm run validate-comparison -- \  --methodology knowledge-base/benchmarks/interface-quality/comparison-methodology.template.yaml \  --review knowledge-base/benchmarks/interface-quality/review.template.yaml \  --require-release-ready

Compile completed reviewer sessions

The compiler hashes each source session and reports matrix completeness, counterbalancing, category scores, task metrics, and the anonymous target-versus-comparator decision. It rejects draft templates and never creates human observations.

bash

npm run compile-comparison -- \  --methodology knowledge-base/benchmarks/azure-optimizer/v2-human-review-methodology.yaml \  --base-review evidence/interface-quality/azure-v2-review/review.yaml \  --sessions evidence/interface-quality/azure-v2-review/reviewer-packet/completed-sessions \  --output evidence/interface-quality/azure-v2-review/review.completed.yaml \  --require-release-ready

Assess a disclosed maintainer review

The solo-maintainer track may authorize continued engineering when the target stages and maintainer-scored categories pass. It never changes the anonymous comparison thresholds or converts maintainer evidence into representative-user or external release evidence.

bash

npm run assess-maintainer -- \  --methodology knowledge-base/benchmarks/azure-optimizer/v2-human-review-methodology.yaml \  --review evidence/interface-quality/azure-v2-review/review.completed.yaml \  --output evidence/interface-quality/azure-v2-review/maintainer-assessment.json \  --require-engineering-ready

Evaluate the maintained system corpus

bash

npm run evaluate-corpus

Browser verification

Screenshot matching establishes only that the captured pixels and masking policy are unchanged in the current environment. It does not establish visual quality, task success, or approval of an intentional change.

Verify a running interface

bash

npm run verify-ui -- \  --url http://127.0.0.1:3000 \  --journeys knowledge-base/benchmarks/aegisops/journeys.json \  --profile responsive-overview \  --output .ztothez-design-runtime/responsive-overview

Create then compare a screenshot baseline

Only declared dynamic regions are masked.

bash

npm run verify-ui -- \  --url http://127.0.0.1:3000 \  --dynamic-selector "[data-runtime-clock]" \  --screenshot-baseline evidence/runtime/screenshots.json \  --update-screenshot-baselinenpm run verify-ui -- \  --url http://127.0.0.1:3000 \  --dynamic-selector "[data-runtime-clock]" \  --screenshot-baseline evidence/runtime/screenshots.json

Attach to Chromium over a loopback CDP endpoint

For managed environments where Playwright cannot launch Chromium directly. Only loopback origins are accepted.

bash

chromium --headless --no-sandbox --remote-debugging-address=127.0.0.1 \  --remote-debugging-port=9222 --user-data-dir=/tmp/ztothez-design-cdp about:blankZTOTHEZ_DESIGN_CHROMIUM_CDP_URL=http://127.0.0.1:9222 npm run verify-ui -- \  --url http://127.0.0.1:3000

Quality gate

One consolidated decision from contract, audit, runtime, acceptance, and human evidence. Run npm run COMMAND -- --help for the complete options supported by each workflow.

Run a complete profile quality gate

bash

npm run quality-gate -- \  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \  --repo PATH_TO_APPLICATION \  --project-root . \  --url http://127.0.0.1:3000 \  --profile responsive-overview \  --output .ztothez-design-quality-gate/responsive-overview \  --fail-on error