Validation and Guardrails

Facet has two main guardrail paths:

• facet check for graph-wide quality gates.
• facet validate for individual fx objects, including AI or MCP generated authoring.

Graph and build checks

facet check tokens/app.resolver.json
facet check tokens/app.resolver.json --json

The source documents these checks:

• contrast requirements on resolved values in every mode
• switch-safety contract, where every mode resolves the same token paths
• authored-code lint for off-system utilities and fx() values
• unused or orphan token warnings
• RTL logical-property lint

check exits non-zero on violations.

Validate an authoring object

validate asks whether an fx object stays inside the token vocabulary:

facet validate tokens/app.resolver.json '{"bg":"action","px":"inset.md"}'

The same command supports arrays:

facet validate tokens/app.resolver.json '[{"bg":"action"},{"bg":"missing"}]'

Direct fx() examples from the source use token suffixes:

{ bg: "bg", fg: "ink-muted", p: "inset.md" }

Arbitrary values are explicit escape hatches:

{ p: { raw: "10px" } }

The spec says off-system values are rejected by validate and are intended to be type errors against generated token types.

Scanner diagnostics

The guide notes that scanSource(text) returns locations with 1-based line numbers, and lintAuthoringSource([{ file, text }]) reports off-system usage as { file, line, message }.

The scanner is intentionally static. It extracts examples such as:

<button className="bg-action fg-on-action radius-control px-inset-md py-inset-sm hover:bg-action-hover focus-visible:ring">
  Action
</button>

and:

const cardStyle = fx({ bg: "surface", fg: "ink", radius: "panel", p: "inset.lg" });

The design notes call out that full JSX, Vue, and Svelte parser breadth is planned production work. Non-static fx() arguments are surfaced instead of silently dropped.

Graph inspection

Use graph to inspect resolved token values and dependencies:

facet graph tokens/app.resolver.json color.action

This is useful before changing aliases, derived tokens, or a brand set because it shows how a token resolves across modes.