Design Direction

The taste layer, in which a company's designers set profile, voice, patterns, rules and exemplars without writing prompts or retraining a model.

Tokens control how things look. Taste goes further: how dense a screen is, how much gets emphasised, how the copy sounds, which patterns a team prefers, and what to leave out. A Design Direction holds a company's taste as one versioned JSON package next to its design-system pack.

The goal is that designers shape generated UI without writing prompts or JSON by hand, and without retraining a model. Today the Direction schema exists (schema/direction.schema.json), with two example directions, and its rules and checkable voice settings run in the verifier. Studio edits a whole Direction, versions and publishes it, and serves the published one to products by key. The runtime applies a Direction at generation. It gives the model the profile, the voice and the rules, the preferred patterns that fit the ask, and up to two exemplars chosen by relevance. Then it checks every answer against the rules and the compiled voice before accepting it. profile.motion and custom pattern files aren't applied yet.

What a Direction contains#

Profile#

The validator currently enforces one primary action per view regardless of emphasisBudget, since the accessibility floor caps it at one on most platforms.

Copy and tone#

voice is where a content designer sets how the product sounds. Settings that can be checked mechanically compile into rules with compileVoice(direction); the rest (tone, situation guidance) steer the generator.

"voice": {
  "tone": { "formality": "neutral", "energy": "calm", "warmth": "reserved", "humor": "none" },
  "person": "you",
  "readingLevel": { "maxGrade": 8 },
  "casing": "sentence",
  "spelling": "en-GB",
  "punctuation": { "exclamation": "never", "emoji": "never" },
  "labels": { "maxWords": 4, "verbFirst": true },
  "glossary": [{ "use": "payment", "insteadOf": ["transaction", "txn"] }],
  "avoid": ["simply", "just", "oops", "invalid"],
  "situations": { "error": "Say what happened, that nothing was lost, and what to do next. Never blame the user." }
}

Hold a document to everything a Direction says, its explicit rules and its compiled voice, with directionRules:

import { directionRules } from "@polyxd/spec";

const report = await verifyDocument(doc, { registry, rules: directionRules(direction) });

Copy checks are warnings by default: they flag, and the team decides. Voice and tone are taste, and the verifier's job is to make them visible, not to overrule the people who own them.

Rules#

Rules use the same check vocabulary as patterns and journeys. The description is what a designer would say; the rule is how a machine checks it.

{
  "id": "money-moves-in-confirm",
  "description": "Money only moves from a confirmation",
  "severity": "error",
  "rule": { "check": "actionInside", "capabilities": ["transfer.confirm"], "container": ["Confirm"] }
}

Pass a Direction's rules to the verifier to hold a document to them:

import { verifyDocument } from "@polyxd/verifier";

const report = await verifyDocument(doc, { registry, rules: directionRules(direction) });

The freedom dial#

profile.freedom sets how far the generator may go beyond approved patterns:

• Strict: only approved patterns.
• Guided: new layouts are allowed, built from approved components.
• Open: anything that passes the verifier.

The runtime gives the model this setting as an instruction. When the generator has no fitting pattern, the plan is for it to flag the gap for review. That part is planned.

Precedence#

When layers disagree, higher ones win:

1. The accessibility floor. Nobody can override it.
2. The end user's accessibility needs (text size, reduced motion, contrast).
3. Company rules.
4. Company profile, voice and patterns.
5. End-user preferences (for example density), within the company's bounds.
6. Generator defaults.

The precedence engine that applies this order at generation time is planned.

Two contrasting examples#

The spec ships two deliberately different Directions in packages/spec/examples/directions/. The same request under each should produce different UIs that each comply. Both use Material 3.

The glossary entry shows how voice becomes a check. compileVoice turns { "use": "payment", "insteadOf": ["transaction", "txn"] } into:

{
  "id": "voice-glossary-payment",
  "description": "Say \"payment\", not \"transaction\" or \"txn\"",
  "severity": "warning",
  "rule": { "check": "avoidTerms", "terms": ["transaction", "txn"], "suggest": "payment" }
}

On the balance overview example, calm-finance flags "Recent transactions" with this rule, and playful-personal passes the same surface.

In Studio#

Studio is where a team's designers keep their taste. Its Direction editor edits every part of a Direction: the profile as visual choices, the voice with a sample sentence checked as you type by the verifier's copy checks, the spec's patterns preferred or ruled out and the team's own written in the pattern format, and the workspace's screens attached as exemplars. The team's rules (checks with a severity, run on every screen saved in Studio and in the verifier) are the Direction's rules, and which components generated screens may use sits beside them. Every change is checked against this schema; versions are saved with notes, compared field by field with what is published, and published for products to fetch by key (GET /api/w/<workspace>/directions/<key>); a Direction exports as a file and imports from one.

Still planned: previewing a company's typical requests under a Direction, and reviewing generated screens (approve, reject, edit, with approvals becoming exemplars and repeated corrections suggested as rules). See the roadmap.

Polyxd is an early preview. Found something unclear? It will get better with your feedback.