yannikzz/ui-contract/ui-contract-glossary

UI contract — vocabulary

This skill decides which document a thing belongs in. It produces no artifacts of its own.

Any unit that would explain one of the terms below explains it by calling this one instead. A definition restated in a consuming unit reads perfectly well and costs nothing until the two drift — and then nothing is comparing them. Terms may be used freely; what belongs here is what a term means, and which artifact owns the thing it names.

Nothing mechanical enforces that. Six of the ten ui-contract units currently wire to this one; the four that do not (setup, baseline, enforce, audit) have not been checked against the rule, so a blanket assertion would be guarding violations nobody has measured.

What the artifacts own

Two dimensions, not one. Owns says what content belongs there; Kind says whether the thing can be thrown away and rebuilt. Getting the second one wrong is how a rehearsal gets treated as an authority, and how an asset gets written into somebody's product without asking.

For what a decision record may and may not contain, call the Skill tool with "decision-record".

The wireframe is a projection layer

Saying "low-fidelity reference implementation" describes its fidelity. That is not the thing you need in order to know when it should be rebuilt, and without it the wireframe gets treated as a station on a chain — something you arrive at, deliver, and leave behind.

The wireframe is the projection layer over layout.md, design.md and their decision

records. It can be rebuilt at any time, and is rebuilt whenever any connected source changes.

The only required input is `layout.md`. design.md and the decision records are optional inputs: connected, they get projected too; absent, the projection still stands.

So the grey projection is complete, not half-finished. Grey is not a style choice and not a placeholder — it is what a projection of a complete source looks like when an optional source is not connected yet. This matters at exactly one moment: when the user is asked to sign off on the structural spec, what they are looking at is a finished thing, not a preview.

The asset layer is a conduit, not a source. The wireframe reads the allowlist through it so that no second allowlist comes into existence — that is the whole reason for the dependency, and it does not make the asset layer an input to the projection. This holds only under one constraint, and the constraint is the load-bearing one:

The asset layer must contain nothing that has no clause behind it in `layout.md`.

If that ever stops being true, "the projection projects layout.md" stops being true with it, and rebuildability goes with that.

The one cut

"Does this change when the brand skin changes?" Changes → design.md. Doesn't → layout.md.

There is exactly one cut. Do not invent a second dimension to resolve a hard case — take the hard case back to this question. The same value living in two places is a drift source.

One consequence people miss: design.md holds rules, the token file holds values. design.md must not contain color values or size values; it writes "see the token file". This is the same shape as layout.md holding no visual values at all — the cut hasn't moved, there is just one more hop.

Zero overlap, but don't claim absolute zero

Aim for zero overlap. Do not claim it. There are usually one or two genuine coupling points — a spacing value that determines how many grid columns fit, say; change one and you must revisit the other.

Handle those by marking them explicitly on both sides:

⚠ Changing this requires revisiting §X of the other spec — this is the only place the two specs are coupled.

Naming a coupling is far safer than declaring zero overlap and letting it drift silently.

Do not copy someone else's information architecture

This is the most important thing here. These skills teach a method, not any product's answers. The region tree, the page archetypes, the slot enumeration, the nav segments — every project answers those for itself.

If any of these thoughts show up, you are already contaminating the user's product:

Reference material is for seeing what a finished shape looks like, never for copying a specific tree.

Two different things are both called "exam"

Keep these apart; they are unrelated jobs with different owners.

Never call the first one a health check. It was called that once, and the two concepts blurred immediately.

Canonical term renderings

The skill bodies are in English; deliverables follow the user's language — for that discipline, call the Skill tool with "deliverable-language". This table is the UI-specific half: it pins the rendering so the same concept doesn't get translated differently on every run.

When producing deliverables in a language not listed here, pick one rendering per concept, write the choices into a glossary section of layout.md, and stay consistent.

Completion criteria owned here