From 521a78664cca6bd8e9a4777a47825fb7f3aa6558 Mon Sep 17 00:00:00 2001
From: Nathan Curtis <1165904+nathanacurtis@users.noreply.github.com>
Date: Fri, 4 Sep 2026 15:11:06 -0400
Subject: [PATCH 1/2] refactor(conventions): move spec-side conventions out of
 the platform block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`platforms.<id>` holds facts about one implementation, and two members filed
under `figma` were not. `states` names a prop and an enum value that exist in
api.yaml — a transform reading only the spec applies it, and the CSS transform
does exactly that without touching a Figma file. The prop conventions naming
which prop carries an accessible name or a value are the same shape of fact.
Compare the members that genuinely are Figma facts: `glyphs.match` names a layer
pattern, `codeOnlyProps.match` a frame, `subcomponents.scope` a page.

Adds `Conventions.specs`, a sibling of `platforms` and `primitives` rather than
a member of `platforms`. `primitives` is the precedent — it already sits outside
for the same reason — and the spec is the hub, so making `specs` a platform key
would name the hub as one of its own spokes.

    conventions/specs.yaml
    props:
      states: { disabled: { prop: isDisabled } }
      accessibility: { label: { prop: a11yLabel } }
      value: { prop: progress }

Prop conventions are objects, not bare names, so one can gain fields without a
break — the same argument that made `actions` an array of objects. That also
retires `propRoles`, a name that borrowed a word meaning something specific and
unrelated on anatomy elements.

`roleValidation` moves to `Settings.spec`, beside `roles`. It describes how
strict a run should be, which is a fact about neither the design tool nor the
target, and its on-switch was already in settings — one feature's two knobs were
split across two files.

ADRs 067 and 073 are amended in place rather than superseded, since neither has
shipped. Schema and types only; no transform or CLI code changes, so the loader
still reads the old paths until the follow-up lands.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 adr/067-anatomy-element-roles.md              | 119 ++++++++++--------
 adr/073-platform-conventions-namespace.md     |  90 ++++++++++++-
 .../schema/schema/conventions.schema.json     |  98 ++++++++++-----
 packages/schema/schema/settings.schema.json   |   8 ++
 packages/schema/tests/Conventions.test-d.ts   |  49 ++++----
 packages/schema/tests/Metadata.test-d.ts      |   1 +
 packages/schema/types/Conventions.ts          |  97 +++++++++-----
 packages/schema/types/Settings.ts             |  16 +++
 packages/schema/types/index.ts                |   3 +-
 9 files changed, 341 insertions(+), 140 deletions(-)

diff --git a/adr/067-anatomy-element-roles.md b/adr/067-anatomy-element-roles.md
index e95c0fa..7ed8c5f 100644
--- a/adr/067-anatomy-element-roles.md
+++ b/adr/067-anatomy-element-roles.md
@@ -10,7 +10,7 @@
 
 ## Context
 
-ADR 055 (`processing.states`) lets a library deterministically classify variant props as semantic state concepts (`disabled`, `checked`, `expanded`). Downstream transforms consume that classification — but only at the *prop* level. Nothing in the spec identifies *which element carries the platform behavior*, so the `react` transform has no basis for emitting a `<button>`, injecting a native `<input>`, or wiring a `<label htmlFor>`. Every interactive component scaffolds as `div` + ARIA veneer:
+ADR 055 (state classification, now `props.states` in `conventions/specs.yaml`) lets a library deterministically classify variant props as semantic state concepts (`disabled`, `checked`, `expanded`). Downstream transforms consume that classification — but only at the *prop* level. Nothing in the spec identifies *which element carries the platform behavior*, so the `react` transform has no basis for emitting a `<button>`, injecting a native `<input>`, or wiring a `<label htmlFor>`. Every interactive component scaffolds as `div` + ARIA veneer:
 
 - A button renders `<div aria-disabled>` — no `<button>`, no native `disabled`, no `onClick`, no focus or keyboard behavior
 - A checkbox renders no `<input>` at all, bridges its selected state to `aria-selected` (a listbox-option attribute, incorrect for a checkbox), and leaves its label and error-message subcomponents unassociated
@@ -64,9 +64,9 @@ Add `role?: string` alongside `type`, `detectedIn`, and `instanceOf`.
 
 ---
 
-### Option 1B: Workspace-config role map for elements, mirroring `processing.states` *(Rejected)*
+### Option 1B: Workspace-config role map for elements, mirroring the state classification *(Rejected)*
 
-A `processing.roles` block in `specs.config.yaml` mapping component/element paths to element roles.
+A `roles` block in workspace config mapping component/element paths to element roles.
 
 **Rejected because**: `states` works as workspace config because prop names (`disabled`, `state`) are library-wide conventions — one declaration covers every component. **Element** roles are per-component, per-element facts (a checkbox's `control` is a checkbox; an alert's `control` would not be). A workspace map would grow one entry per component element, duplicate the anatomy structure outside the spec, and strand the fact away from the artifact that transforms consume.
 
@@ -286,24 +286,29 @@ Without these, transforms fall back to matching prop names — the exact heurist
 
 - **Which prop supplies a value that no element represents?** A progress bar draws its progress as a filled bar, not as a text element — there is no element to annotate as the `value` part, and the number exists only as a prop
 
-**Scope discipline**: `propRoles` covers facts that live in props and nowhere else. Anything an element can carry is a part role. An earlier draft put `placeholder` here; part roles supersede it entirely, because a placeholder is always a text element in components that have one.
+**Scope discipline**: a prop convention covers facts that live in props and nowhere else. Anything an element can carry is a part role. An earlier draft put `placeholder` here; part roles supersede it entirely, because a placeholder is always a text element in components that have one.
 
-`value` is the one entry that lives in both worlds, and the precedence is explicit: **a `value` part wins where one exists; `propRoles.value` is the fallback for controls whose value has no element.** Text controls use the part; progress bars use the prop. Both are declarations, neither is a guess.
+`value` is the one entry that lives in both worlds, and the precedence is explicit: **a `value` part wins where one exists; `props.value` is the fallback for controls whose value has no element.** Text controls use the part; progress bars use the prop. Both are declarations, neither is a guess.
 
-This also makes **code-only props a first-class semantic surface** without changing what the code-only-props frame means. The frame keeps its single meaning — literal props — while `propRoles` classifies which of those props carries the accessible name or the indeterminate signal. A library can therefore author real semantic payload with one hidden layer in a frame it already has, rather than restructuring its components.
+This also makes **code-only props a first-class semantic surface** without changing what the code-only-props frame means. The frame keeps its single meaning — literal props — while the spec conventions classify which of those props carries the accessible name or the value. A library can therefore author real semantic payload with one hidden layer in a frame it already has, rather than restructuring its components.
 
-### Option 4A: Workspace config for conventions, annotations for exceptions *(Selected)*
+### Option 4A: Spec conventions for the library, annotations for exceptions *(Selected)*
 
-A `processing.propRoles` block in `specs.config.yaml`, structurally parallel to
-`processing.states`, declares the library-wide prop conventions. A component that deviates
+A `props` block in `conventions/specs.yaml` declares the library-wide prop conventions,
+beside `props.states` which answers the same shape of question. A component that deviates
 overrides it with an annotation on its component node, using the same `key:value` grammar as
 roles.
 
+These are conventions about the **spec**, not about a platform: they name a prop that exists
+in `api.yaml`, and a transform reading only the spec can apply them. See ADR 073 for why they
+sit beside `platforms` rather than inside it.
+
 ```yaml
-config:
-  processing:
-    propRoles:
-      accessibleName: a11yLabel
+# conventions/specs.yaml
+props:
+  accessibility:
+    label:
+      prop: a11yLabel
 ```
 
 ```
@@ -327,8 +332,8 @@ indeterminate:isLooping
 - Two surfaces for one concept, so an author reading only the config can be surprised by a
   component that overrides it. The diagnostic for an unmet obligation names the resolved
   binding to make this visible
-- A second config block for a related-but-distinct concern; `states` and `propRoles` will
-  invite eventual consolidation
+- The library-wide and per-component halves of one concept live in two files, split by
+  scope. The precedence rule (annotation wins) is what keeps that legible
 
 ---
 
@@ -392,8 +397,8 @@ different places:
 | Satisfier kind | Example |
 |---|---|
 | A part role resolved to this control | a `label` element |
-| A prop binding from `propRoles` | `propRoles.accessibleName` |
-| A state classification from `processing.states` | the `checked` entry |
+| A prop convention | `props.accessibility.label` in `conventions/specs.yaml` |
+| A state classification from `props.states` | the `checked` entry |
 | An existing variant prop | a `value` prop the library already declares |
 
 - **It matches how the requirements actually work.** The most important obligation — that a
@@ -416,7 +421,7 @@ Declare edges between concepts — `checkbox` requires `label`, `disclosure` req
 
 - Simple to state, simple to implement, and easy to visualize
 - **But it can only see annotations, and the requirements are not all annotations.** An
-  icon-only button names itself through `propRoles.accessibleName`, which is a config entry
+  icon-only button names itself through `props.accessibility.label`, which is a convention
   in a different file. A graph over annotations would report that correctly-named control
   as broken, and the false positive would land on exactly the components this feature exists
   to improve
@@ -451,7 +456,7 @@ Treat every unmet obligation as an error rather than deciding severity per oblig
 - Teams adopting roles incrementally would be unable to run the transform at all until every
   component was fully annotated
 
-**Severity is therefore configurable rather than fixed.** `processing.roleValidation`
+**Severity is therefore configurable rather than fixed.** `settings.spec.roleValidation`
 accepts `'warn'` (the default) or `'error'`, letting a team escalate once its library is
 fully annotated and its CI should hold the line. Conflicts remain errors regardless of the
 setting, because they are unambiguous: two elements claiming one part, or two value-bearing
@@ -465,9 +470,11 @@ controls in one component.
 |------|--------|------|
 | `types/Anatomy.ts` | Add exported type alias `RoleConceptName` (open string; documents the naming scheme) | MINOR |
 | `types/Anatomy.ts` | Add optional field `role?: RoleConceptName` to `AnatomyElement` | MINOR |
-| `types/Config.ts` | Add optional field `propRoles?: Record<PropRoleName, string>` to `Config.processing` and `ResolvedConfig.processing` | MINOR |
+| `types/Conventions.ts` | Add `SpecsConventions` with a `props` block (`states`, `accessibility.label`, `value`), and `Conventions.specs` beside `platforms` and `primitives` | MINOR |
+| `types/Conventions.ts` | Add `PropReference` (`{ prop: string }`), so a prop convention can grow fields | MINOR |
+| `types/Conventions.ts` | Move `states` off `PlatformConventions` — it names a spec prop, not a Figma fact | MINOR |
 | `types/Config.ts` | Add exported type alias `PropRoleName` (open string: `accessibleName`, `indeterminate`, `value`) | MINOR |
-| `types/Config.ts` | Add optional field `roleValidation?: 'warn' \| 'error'` to `Config.processing` and `ResolvedConfig.processing` (default `'warn'`) | MINOR |
+| `types/Settings.ts` | Add optional field `roleValidation?: 'warn' \| 'error'` to `Settings.spec` (default `'warn'`), beside `roles` | MINOR |
 | `types/index.ts` | Export `RoleConceptName`, `PropRoleName` | MINOR |
 
 **Example — new shape** (`types/Anatomy.ts`):
@@ -608,7 +615,7 @@ that plainly removes most of the ambiguity readers have reported about what a pa
 
 ### Roles and the states config
 
-`anatomy.role` and `processing.states` are **independent authoring inputs**. Either may
+`anatomy.role` and `props.states` are **independent authoring inputs**. Either may
 exist without the other, neither supersedes the other, and the role feature must not gate
 or disable existing states behavior.
 
@@ -616,7 +623,7 @@ They answer different questions, and neither answer is derivable from the other:
 
 | Input | Answers |
 |---|---|
-| `processing.states` | *Which Figma variant prop carries this concept?* |
+| `props.states` | *Which variant prop carries this concept?* |
 | `anatomy.role` | *What mechanism is available to express it?* |
 
 A states classification with no role behaves exactly as it does today. A role with no
@@ -633,7 +640,7 @@ the two mechanisms have.
 
 **The dependency runs role → states.** A role's *wired* event handlers cannot be generated
 without a resolved state binding. A `togglebutton` that flips its own pressed state must be
-told which prop holds that state, and only `processing.states` can tell it. Several
+told which prop holds that state, and only `props.states` can tell it. Several
 concepts are therefore **inert without a states classification**, degrading to a stub
 handler and a warning rather than to generated state management. Roles depend on the states
 config; they do not replace any part of it.
@@ -663,16 +670,16 @@ discharges it**.
 
 | Obligation | Declared by | Level | Satisfied by any of |
 |---|---|---|---|
-| `name` | every control concept | required | a `label` part resolved to this control; `propRoles.accessibleName`; for `group`, a `label` part emitted as `<legend>` |
-| `value` | value-bearing controls using `collapse` (`textbox`, `password`, `searchbox`, `textarea`, `spinbutton`, `slider`) | required | a `value` part; an existing variant prop bound as the value; `propRoles.value` |
-| `checkedstate` | `checkbox`, `radio`, `switch` | expected | a `checked` classification in `processing.states` |
-| `pressedstate` | `togglebutton` | expected | a `pressed` classification in `processing.states` |
-| `expandedstate` | `disclosure` | expected | an `expanded` classification in `processing.states` |
+| `name` | every control concept | required | a `label` part resolved to this control; `props.accessibility.label`; for `group`, a `label` part emitted as `<legend>` |
+| `value` | value-bearing controls using `collapse` (`textbox`, `password`, `searchbox`, `textarea`, `spinbutton`, `slider`) | required | a `value` part; an existing variant prop bound as the value; `props.value` |
+| `checkedstate` | `checkbox`, `radio`, `switch` | expected | a `checked` classification in `props.states` |
+| `pressedstate` | `togglebutton` | expected | a `pressed` classification in `props.states` |
+| `expandedstate` | `disclosure` | expected | an `expanded` classification in `props.states` |
 | `panel` | `disclosure` | expected | a `panel` part resolved to this control |
 | `membership` | `group` | expected | a slot whose `anyOf` resolves to entries carrying control roles |
-| `progressvalue` | `progressbar` | expected | `propRoles.value`; `propRoles.indeterminate` |
+| `progressvalue` | `progressbar` | expected | `props.value`; an `indeterminate` classification in `props.states` |
 | `steppers` | `spinbutton` | optional | `increment` and `decrement` parts |
-| `statelabels` | `togglebutton`, `disclosure` | optional | a `propRoles` entry pairing a state concept to an alternate text prop |
+| `statelabels` | `togglebutton`, `disclosure` | optional | a prop convention pairing a state concept to an alternate text prop |
 
 Two properties of this table are load-bearing:
 
@@ -699,7 +706,7 @@ label" sends an author to the wrong fix when the right one is a config entry.
 warning  checkbox 'root' in components/checkbox has no name source
          satisfy with one of:
            - a `label` role on an element in this component
-           - a `processing.propRoles.accessibleName` entry
+           - a `props.accessibility.label` convention
          emitting without an accessible name
 ```
 
@@ -730,7 +737,8 @@ not listed here.
 | File | Change | Bump |
 |------|--------|------|
 | `schema/component.schema.json` | Add `role` property to the anatomy element definition | MINOR |
-| `schema/workspace.schema.json` | Add `propRoles` object to `#/definitions/Config/properties/processing/properties` | MINOR |
+| `schema/conventions.schema.json` | Add `SpecsConventions` and `PropReference`; add `specs` to `#/definitions/Conventions/properties`; remove `states` from `PlatformConventions` | MINOR |
+| `schema/settings.schema.json` | Add `roleValidation` to the `spec` block | MINOR |
 
 **Example — new property** (anatomy element definition):
 
@@ -744,20 +752,31 @@ role:
 **Example — new processing properties** (`workspace.schema.json`):
 
 ```yaml
-propRoles:
+props:
   type: object
-  additionalProperties:
-    type: string
-  description: "Library-wide prop-name conventions consumed by role emission: maps a prop-role concept (accessibleName, indeterminate, value) to the prop name that carries it. Covers facts carried by props alone — element-level facts use part roles on anatomy elements, and a matching part role always wins over a propRoles entry. Per-component deviations are annotated on the component node."
+  additionalProperties: false
+  properties:
+    states:
+      description: "Concept-keyed map classifying variant props as semantic states."
+    accessibility:
+      type: object
+      properties:
+        label:
+          $ref: "#/definitions/PropReference"
+          description: "The prop supplying an accessible name for a control with no text of its own."
+    value:
+      $ref: "#/definitions/PropReference"
+      description: "The prop supplying a control's value where no element represents it."
 ```
 
 **Config example** (`specs.config.yaml`):
 
 ```yaml
-config:
-  processing:
-    propRoles:
-      accessibleName: a11yLabel
+# conventions/specs.yaml
+props:
+  accessibility:
+    label:
+      prop: a11yLabel
 ```
 
 **Spec example** (`api.yaml` — all `role` values generated from Dev Mode annotations):
@@ -791,7 +810,7 @@ therefore additive and ignores everything it does not recognize.
 2. **Each `label` is split on newlines.** A single annotation may carry several signals.
 3. **A line of the form `key:value` is a candidate signal.** Surrounding whitespace is
    trimmed from both sides; the first colon separates them, so a value may contain colons.
-4. **Only recognized keys are consumed.** `role` is defined here; `propRoles` keys are
+4. **Only recognized keys are consumed.** `role` is defined here; prop-convention keys are
    defined by Decision 4; vocabulary ADRs may define more. An unrecognized key is ignored
    silently, which is what keeps the grammar forward-compatible.
 5. **Every other line is prose and is ignored.** This is the common case in an existing
@@ -849,7 +868,7 @@ A role's contract additions can collide with props the component already has. **
 
 The rules, which every vocabulary ADR inherits:
 
-1. **An existing prop becomes the reset signal, not a controlled value.** Where a role's concept (`checked`, `expanded`, `pressed`, `value`) is already carried by a prop the spec declares — directly or via a `processing.states` classification — that prop seeds the control's state and re-seeds it whenever the prop's value changes. **No `default*` companion prop is emitted.** The component is explicitly *not* controlled in the React sense, and the ADRs must not call it that.
+1. **An existing prop becomes the reset signal, not a controlled value.** Where a role's concept (`checked`, `expanded`, `pressed`, `value`) is already carried by a prop the spec declares — directly or via a `props.states` classification — that prop seeds the control's state and re-seeds it whenever the prop's value changes. **No `default*` companion prop is emitted.** The component is explicitly *not* controlled in the React sense, and the ADRs must not call it that.
 2. **The role still contributes the change signal.** The handler prop (`onChange`, `onExpandedChange`, `onPressedChange`) is always added, and is always optional.
 3. **Re-seeding happens during render, not in an effect.** The generated pattern is React's documented "adjust state when a prop changes" form — track the previous prop value in state and reset during render when it differs — **not** `useState` plus a `useEffect` sync. The effect form runs after paint, so it produces a visible frame of stale state and an extra committed render on every parent-driven change. The render-time form commits once, with no flicker.
 
@@ -879,7 +898,7 @@ Rules 1, 3, and 4 together are what separate a component that looks correct in a
 - **Emitted markup must satisfy the target platform's content model.** On the web this matters immediately: `<button>`, `<label>`, and `<legend>` accept phrasing content, while essentially every presentational descendant this pipeline generates is a `<div>`. A vocabulary concept that emits one of those elements must state how descendants are handled — the transform emits them as `<span>` with `display` preserved by the existing styling rather than nesting `<div>`s inside phrasing-content elements.
 - **Two roles may coexist in one rendered tree only when they are on different elements in different specs.** An announcement region containing an instance whose own spec carries a `button` role is legitimate. Two specs both claiming the same DOM position — a label component with its own `label` role, wrapped by a consumer that also emits `<label>` — is not, and vocabularies must define which side wins.
 - Absence of `role` everywhere is the safe default — transforms behave exactly as today.
-- `propRoles` has no default in `DEFAULT_CONFIG`; absence disables prop-role binding. `DEFAULT_CONFIG` requires no change. Annotation reading needs no config — there is no pattern to declare.
+- `Conventions.specs` has no default; absence means no prop conventions are declared. `settings.spec.roleValidation` defaults to `'warn'`, so absence preserves current behavior. Annotation reading needs no config — there is no pattern to declare.
 
 ---
 
@@ -888,8 +907,8 @@ Rules 1, 3, and 4 together are what separate a component that looks correct in a
 - **Symmetric**: Yes
 - **Parity check**:
   - `AnatomyElement.role` → `role` property on the anatomy element definition in `component.schema.json` (string, optional)
-  - `Config.processing.propRoles` → `#/definitions/Config/properties/processing/properties/propRoles` (object of string, optional)
-  - `Config.processing.roleValidation` → `#/definitions/Config/properties/processing/properties/roleValidation` (string enum `warn` | `error`, optional)
+  - `Conventions.specs` → `#/definitions/Conventions/properties/specs` (`SpecsConventions`, optional)
+  - `Settings.spec.roleValidation` → the `spec` block's `roleValidation` (string enum, optional)
   - `RoleConceptName` and `PropRoleName` are documentation-only (open strings), matching the `StateConceptName` precedent — no schema enums
 
 ---
@@ -940,7 +959,7 @@ Once `control` carries `role: checkbox`, the state concepts have a *destination*
 | Consumer | Impact | Action required |
 |----------|--------|-----------------|
 | `specs-from-figma` | Populates roles during generation | Read `node.annotations` on component nodes and their layers in both runtimes; parse the annotation grammar; apply the variant resolution and key-stability rules. Layer names are not read or modified |
-| `specs-cli` | Transforms gain a deterministic role signal and prop-role bindings | Read `anatomy.<element>.role`; resolve `processing.propRoles` with per-component annotation overrides; emission semantics per role are defined in the vocabulary ADRs. No merge step — roles arrive already generated |
+| `specs-cli` | Transforms gain a deterministic role signal and prop-role bindings | Read `anatomy.<element>.role`; resolve `Conventions.specs.props` with per-component annotation overrides; emission semantics per role are defined in the vocabulary ADRs. No merge step — roles arrive already generated |
 | `specs-plugin-2` | Plugin-driven generation applies the same layer-name detection; may surface roles in UI | Recompile; apply the same detection; optionally display role classification per element |
 
 ---
@@ -949,7 +968,7 @@ Once `control` carries `role: checkbox`, the state concepts have a *destination*
 
 **Version bump**: MINOR
 
-**Justification**: All changes are additive optional fields (`role` on `AnatomyElement`; `propRoles` and `roleValidation` on `Config.processing`) plus two new exported aliases. `roleValidation` defaults to `'warn'`, so absence preserves current behavior. Per constitution III: "MINOR for additive types or new optional fields."
+**Justification**: The additions are optional fields — `role` on `AnatomyElement`, `Conventions.specs`, and `roleValidation` on `Settings.spec` — plus new exported types. `states` moves from `PlatformConventions` to `Conventions.specs.props`, which is a relocation within an unshipped surface rather than a break to a published one. `roleValidation` defaults to `'warn'`, so absence preserves current behavior. Per constitution III: "MINOR for additive types or new optional fields."
 
 ---
 
@@ -970,7 +989,7 @@ The vocabulary ADRs describe emission; this section fixes the *shape* the implem
    **One qualification, since an earlier draft overstated this**: part resolution rule 2 consults the layout tree, which lives in `variants.yaml`. That is a *read* inside the role index, not a merge, and it applies only to the non-value-bearing case. The rest of role resolution is `api.yaml` only. The role index is therefore a pure function of anatomy **plus the layout tree it is handed**, not of anatomy alone, and the index's signature should say so rather than pretending otherwise.
 2. **Tag selection — one expression.** The React emitter's entire tag decision today is a single ternary: text elements become `span`, everything else becomes `div`. A role-to-tag lookup replaces exactly that expression, with the current ternary as the fallback when no role is present.
 3. **Element attribute assembly — one enabling refactor.** Attribute assembly exists only for the root element; non-root elements inline their class and `data-element` into string templates at three separate emission sites. Generalizing the root's attribute assembler into a per-element one — and routing those three sites through it — is contained in one file and is the prerequisite for any per-element role attribute. **This refactor should land before any vocabulary, as its own change.**
-4. **Contract augmentation — one merge site.** Role-implied props enter the contract as a pure function of anatomy, the role table, and `propRoles`, merged at the single site where prop entries are assembled — structurally identical to how states already inject omitted-prop knowledge there.
+4. **Contract augmentation — one merge site.** Role-implied props enter the contract as a pure function of anatomy, the role table, and the spec's prop conventions, merged at the single site where prop entries are assembled — structurally identical to how states already inject omitted-prop knowledge there.
 5. **A role index pre-pass — one pure function.** Both vocabularies need to know, before rendering begins, which element carries which role, what generated id each has, and which elements pair with which. One pre-pass over merged anatomy serves disclosure pairing, label/control wiring, and the one-control validation.
 
 **The places that will resist isolation** — named so implementation can plan against them:
@@ -993,7 +1012,7 @@ The vocabulary ADRs describe emission; this section fixes the *shape* the implem
 - The generated/authored boundary stays crisp: `api.yaml` is reproducible from Figma data alone, and authored facts live on their own surface with its own diff history
 - The code-only-props frame keeps a single meaning: literal props
 - Vocabulary ADRs can grow the recognized concept set without schema bumps — unrecognized roles are inert
-- `processing.states`, `processing.propRoles`, and `anatomy.role` compose: states classify the state props, `propRoles` classify the name and value props, roles locate the platform behavior. All three are required for emission-quality transforms
+- `props.states`, `props.accessibility`/`props.value`, and `anatomy.role` compose: the state conventions classify the state props, the prop conventions classify the name and value props, and roles locate the platform behavior. All three are required for emission-quality transforms — and all three describe the spec, which is why the first two moved out of the platform block
 - A future warning surface becomes possible: a `checked` state concept configured with no control role present, or a control role with no resolvable accessible name
 - The annotation delimiter becomes a reserved character in layer names for libraries that opt in — resolvable per-library via the pattern, but a real constraint to communicate
 - A per-component authored surface enters the workspace — the first of its kind for spec-level facts, and a forcing function for the authored-hub model's file conventions
diff --git a/adr/073-platform-conventions-namespace.md b/adr/073-platform-conventions-namespace.md
index aaa43df..869bba6 100644
--- a/adr/073-platform-conventions-namespace.md
+++ b/adr/073-platform-conventions-namespace.md
@@ -3,7 +3,7 @@
 **Branch**: `073-platform-conventions-namespace`
 **Created**: 2026-08-30
 **Status**: DRAFT
-**Summary**: A platform-keyed `conventions.platforms` map replaces `conventions.figma`, making Figma one implementation among `react`, `swiftui` and the rest.
+**Summary**: A platform-keyed `conventions.platforms` map replaces `conventions.figma`, with a `conventions.specs` sibling for the conventions that describe the spec rather than any platform.
 **Deciders**: Nathan Curtis (author)
 **Supersedes**: *(none)*
 
@@ -249,6 +249,84 @@ Considered when the keys looked like a mix of platforms (`web`) and finer target
 
 ---
 
+## Decision 4 — Where conventions that describe the spec itself live
+
+`platforms.<id>` holds conventions about one implementation. Two members filed under
+`figma` do not describe Figma:
+
+- `states` names a **spec** prop and a **spec** enum value — `state`, `Hover`. A transform
+  reading only `api.yaml` can apply the classification, and the CSS transform does exactly
+  that without ever touching a Figma file.
+- the prop conventions that name which prop carries an accessible name or a value are the
+  same shape of fact.
+
+Compare the members that genuinely are Figma facts: `glyphs.match` names a Figma layer
+pattern, `codeOnlyProps.match` a Figma frame, `subcomponents.scope` a Figma page. Those are
+about the design tool. `states` is not, and filing it under `figma` said it was.
+
+### Option 4A: A `specs` sibling of `platforms` and `primitives` *(Selected)*
+
+```yaml
+# conventions/specs.yaml
+props:
+  states:
+    disabled:
+      prop: isDisabled
+  accessibility:
+    label:
+      prop: a11yLabel
+```
+
+- **`primitives` is the precedent.** It already sits outside `platforms` for exactly this
+  reason — a component's props are the same whichever platform renders it, so the table is
+  stated once. Spec conventions are the same kind of exception, and reuse a shape the file
+  set already has
+- The spec is the hub, not a platform. Every convention edge has the spec on one side, so
+  making `specs` a `platforms` key would name the hub as though it were a spoke
+- It gives library-wide semantics a home. The per-component equivalent is an annotation and
+  lands in the spec itself (`anatomy.<element>.role`, `.actions`); the split is now by
+  **scope**, with a stated precedence — the annotation wins — rather than by accident
+- It leaves room for the obvious next inhabitant: an element-key convention, so a library can
+  declare "an element keyed `label` is the label part" once instead of annotating it on two
+  hundred components
+
+**Cons / Trade-offs**:
+
+- A third top-level key in `Conventions`, so a reader must learn that not everything is
+  platform-scoped. `primitives` already required that
+- A library-wide element convention is a blunt instrument: it applies with no per-component
+  opt-in, so a mistake has library-wide blast radius. That is a reason to design the escape
+  hatch when the convention is added, not a reason to withhold the file
+
+---
+
+### Option 4B: Leave them under `platforms.figma` *(Rejected)*
+
+**Rejected because**: it states something untrue. Nothing about `state: Hover` is a Figma
+fact once the spec carries it, and a reader looking for "how does this library express
+disabled" would not think to open a file named for the design tool. The misfiling is also
+what made the naming go wrong downstream — the prop conventions were called `propRoles`,
+borrowing a word that means something specific and unrelated on anatomy elements.
+
+---
+
+### Option 4C: A `specs` key inside `platforms` *(Rejected)*
+
+**Rejected because**: it would make the hub one of its own spokes. `platforms.<id>` is
+documented as an implementation id, and `specs` is what every implementation is converted to
+or from. The type would still typecheck and the meaning would be wrong.
+
+---
+
+### Option 4D: A fourth artifact beside `conventions/`, `settings/`, `pipeline/` *(Rejected)*
+
+**Rejected because**: these are conventions by the definition this ADR already settled —
+declarations a library makes once about how it expresses itself. Splitting them into a new
+artifact would separate `states` from the file set it belongs to, for a distinction the
+`specs` key already draws.
+
+---
+
 ## Decision
 
 ### Type changes (`types/`)
@@ -260,6 +338,9 @@ Considered when the keys looked like a mix of platforms (`web`) and finer target
 | `Conventions.ts` | Same change to `ResolvedConventions` | MINOR |
 | `Conventions.ts` | `DEFAULT_CONVENTIONS` no longer carries a `figma` key; defaults move inside a declared platform entry | MINOR |
 | `Conventions.ts` | Doc comment widened from "facts about the Figma library" to facts about every library the pipeline reads or writes | PATCH |
+| `Conventions.ts` | Added `SpecsConventions` and `Conventions.specs?`, a sibling of `platforms` and `primitives` — conventions describing the spec rather than a platform (Decision 4) | MINOR |
+| `Conventions.ts` | Added `PropReference` (`{ prop: string }`), so a prop convention can grow fields without a break | MINOR |
+| `Conventions.ts` | `states` moved from `PlatformConventions` to `Conventions.specs.props.states` — it names a spec prop and a spec enum value, not a Figma fact | MINOR |
 
 **Example — new shape** (`types/Conventions.ts`):
 
@@ -273,6 +354,13 @@ Conventions:
 
 # After
 Conventions:
+  # conventions about the spec itself — not about any platform (Decision 4)
+  specs?:
+    props?:
+      states?: {...}
+      accessibility?:
+        label?: { prop: string }
+      value?: { prop: string }
   platforms?:
     <platformId>:
       # encoding — how this platform expresses what the spec models
diff --git a/packages/schema/schema/conventions.schema.json b/packages/schema/schema/conventions.schema.json
index a7e83c5..84ca2d7 100644
--- a/packages/schema/schema/conventions.schema.json
+++ b/packages/schema/schema/conventions.schema.json
@@ -14,7 +14,7 @@
         },
         "value": {
           "type": "string",
-          "description": "Figma variant value that activates this concept (e.g. 'hover', 'pressed'). Omit for boolean props — defaults to 'true'."
+          "description": "Figma variant value that activates this concept (e.g. 'hover', 'pressed'). Omit for boolean props \u2014 defaults to 'true'."
         },
         "contract": {
           "type": "string",
@@ -32,7 +32,7 @@
     },
     "PlatformConventions": {
       "type": "object",
-      "description": "Facts about one platform's library — how it is authored (encoding members) and what it calls things (vocabulary members). One permissive shape for every platform, including figma. Also the root of a single config/conventions/<platform>.yaml file, so one file validates standalone. (ADR-073, ADR-078)",
+      "description": "Facts about one platform's library \u2014 how it is authored (encoding members) and what it calls things (vocabulary members). One permissive shape for every platform, including figma. Also the root of a single config/conventions/<platform>.yaml file, so one file validates standalone. (ADR-073, ADR-078)",
       "properties": {
         "naming": {
           "type": "string",
@@ -42,7 +42,7 @@
             "TITLE"
           ],
           "default": "NONE",
-          "description": "Naming convention this platform uses for layer and component property names — the reversal target for settings.spec.keys."
+          "description": "Naming convention this platform uses for layer and component property names \u2014 the reversal target for settings.spec.keys."
         },
         "glyphs": {
           "type": "object",
@@ -150,7 +150,7 @@
             "backgroundImage": {
               "type": "boolean",
               "default": false,
-              "description": "Encoding. This platform expresses images as container fills, emitted as Styles.backgroundImage — always passed styling, never a primitive trigger. (ADR-077)"
+              "description": "Encoding. This platform expresses images as container fills, emitted as Styles.backgroundImage \u2014 always passed styling, never a primitive trigger. (ADR-077)"
             },
             "match": {
               "type": "string",
@@ -165,7 +165,7 @@
             },
             "component": {
               "type": "string",
-              "description": "Vocabulary. The same component's name on this platform (e.g. 'DsImage') — the translation target for a match declared by whichever platform produced the spec. Not validated against it; an unmatched component is inert. (ADR-077)"
+              "description": "Vocabulary. The same component's name on this platform (e.g. 'DsImage') \u2014 the translation target for a match declared by whichever platform produced the spec. Not validated against it; an unmatched component is inert. (ADR-077)"
             }
           },
           "additionalProperties": false
@@ -180,43 +180,21 @@
           "default": false,
           "description": "The library authors numeric props as Figma TEXT props whose values parse as numbers, to be emitted as NumberProp."
         },
-        "states": {
-          "type": "object",
-          "description": "Concept-keyed map classifying Figma variant props as semantic states.",
-          "additionalProperties": {
-            "$ref": "#/definitions/VariantStateEntry"
-          }
-        },
         "stylesProp": {
           "type": "string",
-          "description": "Prop that receives styling no promotion mapped, for every promoted component on this platform (e.g. sx, style, modifier). A name only — what is placed in it is the generator's decision. Absence means unmapped styling is dropped. (ADR-076)"
+          "description": "Prop that receives styling no promotion mapped, for every promoted component on this platform (e.g. sx, style, modifier). A name only \u2014 what is placed in it is the generator's decision. Absence means unmapped styling is dropped. (ADR-076)"
         },
         "defaultFillWidth": {
           "type": "number",
           "exclusiveMinimum": 0,
           "description": "Width in pixels of the container this platform places a component in when the component's root resizes to fill its parent. Applies only when the root's layoutSizingHorizontal is FILL; fixed and hugging roots are unaffected. Absence means the platform declares no width and the rendering tool uses its own fallback. (ADR-081)"
-        },
-        "propRoles": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          },
-          "description": "Library-wide prop-name conventions consumed by role emission: maps a prop-role concept (accessibleName, indeterminate, value) to the prop name carrying it. Covers facts carried by props alone — element-level facts use part roles on anatomy elements, and a matching part role always wins. Per-component deviations are annotated on the component node."
-        },
-        "roleValidation": {
-          "type": "string",
-          "enum": [
-            "warn",
-            "error"
-          ],
-          "description": "Severity for unmet required role obligations, such as a control with no accessible-name source (ADR-066). 'warn' emits a diagnostic and continues; 'error' fails the transform. Defaults to 'warn'. Conflicts are errors regardless of this setting."
         }
       },
       "additionalProperties": false
     },
     "Conventions": {
       "type": "object",
-      "description": "Facts about the libraries a spec was generated from and is generated for, keyed by platform. Figma is one key among react, web-components, swiftui — keys name implementations, not platform families. Absence of platforms means nothing is declared. (ADR-073)",
+      "description": "Facts about the libraries a spec was generated from and is generated for, keyed by platform. Figma is one key among react, web-components, swiftui \u2014 keys name implementations, not platform families. Absence of platforms means nothing is declared. (ADR-073)",
       "properties": {
         "platforms": {
           "type": "object",
@@ -231,13 +209,17 @@
           "additionalProperties": {
             "$ref": "#/definitions/PrimitiveEntry"
           }
+        },
+        "specs": {
+          "$ref": "#/definitions/SpecsConventions",
+          "description": "Conventions about the spec itself, loaded from conventions/specs.yaml."
         }
       },
       "additionalProperties": false
     },
     "MetadataConventions": {
       "type": "object",
-      "description": "The conventions a spec records in its metadata: the one platform entry that produced it. Same shape as Conventions and the same PlatformConventions definition, so a platform entry validates identically wherever it appears — but absence means something different. Here a missing platform did not produce this spec. (ADR-079)",
+      "description": "The conventions a spec records in its metadata: the one platform entry that produced it. Same shape as Conventions and the same PlatformConventions definition, so a platform entry validates identically wherever it appears \u2014 but absence means something different. Here a missing platform did not produce this spec. (ADR-079)",
       "properties": {
         "platforms": {
           "type": "object",
@@ -256,11 +238,11 @@
     },
     "PrimitiveRule": {
       "type": "object",
-      "description": "One rule turning something a captured layer carries into props on the component it promotes to. `source` names what is read — a Styles member, a dotted path into typography, or content. The honoured set is closed per PrimitiveKind and documented rather than enumerated here, so the validation surface does not track the Styles key set. Exactly one of prop and values is given. (ADR-075)",
+      "description": "One rule turning something a captured layer carries into props on the component it promotes to. `source` names what is read \u2014 a Styles member, a dotted path into typography, or content. The honoured set is closed per PrimitiveKind and documented rather than enumerated here, so the validation surface does not track the Styles key set. Exactly one of prop and values is given. (ADR-075)",
       "properties": {
         "source": {
           "type": "string",
-          "description": "What is read from the captured layer — a Styles member, a dotted path into typography (e.g. typography.fontStyle), or content."
+          "description": "What is read from the captured layer \u2014 a Styles member, a dotted path into typography (e.g. typography.fontStyle), or content."
         },
         "prop": {
           "type": "string",
@@ -320,7 +302,57 @@
         "glyph",
         "container"
       ],
-      "description": "The spec element types that can be promoted to a design system component — a strict subset of ElementType. An image is deliberately absent: it is a paint on an element that is already something else, so it is bound through images.component. (ADR-074)"
+      "description": "The spec element types that can be promoted to a design system component \u2014 a strict subset of ElementType. An image is deliberately absent: it is a paint on an element that is already something else, so it is bound through images.component. (ADR-074)"
+    },
+    "PropReference": {
+      "type": "object",
+      "required": [
+        "prop"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "prop": {
+          "type": "string",
+          "description": "The prop carrying this concept."
+        }
+      },
+      "description": "A prop named by a convention. An object rather than a bare name so it can grow properties of its own without a breaking change."
+    },
+    "SpecsConventions": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Conventions about the spec itself rather than about any platform. A sibling of `platforms` for the same reason `primitives` is: `states` names a prop and an enum value that exist in api.yaml, and a transform reading only the spec can apply it. Library-wide; the per-component equivalent is an annotation, and the annotation wins.",
+      "properties": {
+        "props": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What this library's props mean.",
+          "properties": {
+            "states": {
+              "type": "object",
+              "description": "Concept-keyed map classifying Figma variant props as semantic states.",
+              "additionalProperties": {
+                "$ref": "#/definitions/VariantStateEntry"
+              }
+            },
+            "accessibility": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Props carrying accessibility semantics no element expresses.",
+              "properties": {
+                "label": {
+                  "$ref": "#/definitions/PropReference",
+                  "description": "The prop supplying an accessible name for a control with no text of its own. A resolving `label` part role wins over it."
+                }
+              }
+            },
+            "value": {
+              "$ref": "#/definitions/PropReference",
+              "description": "The prop supplying a control's value where no element represents it. A resolving `value` part role wins over it."
+            }
+          }
+        }
+      }
     }
   }
 }
diff --git a/packages/schema/schema/settings.schema.json b/packages/schema/schema/settings.schema.json
index 2c23e4c..366fca3 100644
--- a/packages/schema/schema/settings.schema.json
+++ b/packages/schema/schema/settings.schema.json
@@ -190,6 +190,14 @@
             "roles": {
               "type": "boolean",
               "description": "Read Figma Dev Mode annotations and emit anatomy.<element>.role (ADR-067). The on-switch for the role feature: when false, annotations are not read and no role is emitted. Defaults to false."
+            },
+            "roleValidation": {
+              "type": "string",
+              "enum": [
+                "warn",
+                "error"
+              ],
+              "description": "Severity for unmet required role obligations, such as a control with no accessible-name source (ADR-067). A setting rather than a convention: it describes how strict a run should be. 'warn' emits a diagnostic and continues; 'error' fails the transform. Defaults to 'warn'. Conflicts are errors regardless."
             }
           },
           "additionalProperties": false
diff --git a/packages/schema/tests/Conventions.test-d.ts b/packages/schema/tests/Conventions.test-d.ts
index 473b4db..f16fd29 100644
--- a/packages/schema/tests/Conventions.test-d.ts
+++ b/packages/schema/tests/Conventions.test-d.ts
@@ -8,7 +8,7 @@ import type {
   ResolvedConventions,
   MetadataConventions,
   PlatformConventions,
-  PropRoleName,
+  SpecsConventions,
   PrimitiveKind,
   PrimitiveEntry,
   PrimitiveRule,
@@ -35,7 +35,6 @@ const figmaEncoding: Conventions = {
       images: { backgroundImage: true, match: 'DS Image', sourceProps: ['imageSource'] },
       slotConstraints: true,
       inferNumberProps: true,
-      states: { hover: { prop: 'state', value: 'hover' } },
       defaultFillWidth: 375,
     },
   },
@@ -55,7 +54,7 @@ const codePlatforms: Conventions = {
 };
 
 // The shape is deliberately permissive — a code platform may declare an encoding member
-const permissive: PlatformConventions = { states: { hover: { prop: 'state' } }, stylesProp: 'sx' };
+const permissive: PlatformConventions = { inferNumberProps: true, stylesProp: 'sx' };
 
 // Figma may take a vocabulary member — the reason it is not special-cased
 const figmaVocabulary: PlatformConventions = { images: { match: 'DS Image' } };
@@ -188,31 +187,36 @@ const noProp: VariantStateEntry = { value: 'pressed' };
 // @ts-expect-error — contract is a closed set
 const badContract: VariantStateEntry = { prop: 'focused', contract: 'inherit' };
 
-// ─── Role signal conventions (ADR-066) ────────────────────────────────────────
+// ─── Spec-side conventions (ADR-073 amendment) ────────────────────────────────
 
-// propRoles maps prop-role concepts to library prop names
-const rolePropConventions: PlatformConventions = {
-  propRoles: { accessibleName: 'a11yLabel', indeterminate: 'indeterminate', value: 'progress' },
+// props.states classifies variant props as semantic states
+const specStates: SpecsConventions = {
+  props: { states: { disabled: { prop: 'disabled' }, hover: { prop: 'state', value: 'Hover' } } },
 };
 
-// roleValidation escalates unmet required obligations
-const roleValidationError: PlatformConventions = { roleValidation: 'error' };
-
-// Both compose with states — the pair ADR-066 is designed around
-const rolesWithStates: PlatformConventions = {
-  states: { disabled: { prop: 'disabled' } },
-  propRoles: { accessibleName: 'a11yLabel' },
-  roleValidation: 'warn',
+// props.accessibility.label names the prop carrying an accessible name
+const specAccessibility: SpecsConventions = {
+  props: { accessibility: { label: { prop: 'accessibilityLabel' } } },
 };
 
-// PropRoleName is an open string — the vocabulary grows without a schema bump
-const propRoleAlias: PropRoleName = 'accessibleName';
+// props.value names the prop carrying a value no element represents
+const specValue: SpecsConventions = { props: { value: { prop: 'progress' } } };
+
+// All three compose, and every block is optional
+const specAll: SpecsConventions = {
+  props: {
+    states: { disabled: { prop: 'disabled' } },
+    accessibility: { label: { prop: 'accessibilityLabel' } },
+    value: { prop: 'progress' },
+  },
+};
+const specNone: SpecsConventions = {};
 
-// @ts-expect-error — roleValidation is a closed two-value union
-const badRoleValidation: PlatformConventions = { roleValidation: 'silent' };
+// @ts-expect-error — a prop reference is an object, so it can grow fields later
+const specBareString: SpecsConventions = { props: { accessibility: { label: 'accessibilityLabel' } } };
 
-// @ts-expect-error — propRoles values name a prop; they are not entry objects
-const propRolesAsObject: PlatformConventions = { propRoles: { accessibleName: { prop: 'a11yLabel' } } };
+// @ts-expect-error — states no longer live on a platform
+const platformStates: PlatformConventions = { states: { disabled: { prop: 'disabled' } } };
 
 
 export {
@@ -222,6 +226,5 @@ export {
   width, stringWidth, platformMayBeAbsent, naming, constraints, numbers, scope, sourceProps,
   platformStyles, resolvedEntry, underResolved, meta,
   metaWithoutPlatforms, defaults, defaultedPlatform, booleanState, enumState, noProp, badContract,
-  rolePropConventions, roleValidationError, rolesWithStates, propRoleAlias, badRoleValidation,
-  propRolesAsObject,
+  specStates, specAccessibility, specValue, specAll, specNone, specBareString, platformStates,
 };
diff --git a/packages/schema/tests/Metadata.test-d.ts b/packages/schema/tests/Metadata.test-d.ts
index 87408cd..adb86c6 100644
--- a/packages/schema/tests/Metadata.test-d.ts
+++ b/packages/schema/tests/Metadata.test-d.ts
@@ -29,6 +29,7 @@ const baseSettings: Metadata['settings'] = {
     collapsePrimitiveWrapper: false,
     promotePrimitives: false,
     roles: false,
+    roleValidation: 'warn',
     invalidVariants: false,
     invalidCombinations: true,
     emptyVariants: false,
diff --git a/packages/schema/types/Conventions.ts b/packages/schema/types/Conventions.ts
index 3a2175e..ff26253 100644
--- a/packages/schema/types/Conventions.ts
+++ b/packages/schema/types/Conventions.ts
@@ -12,26 +12,7 @@ import type { PropConfigurations } from './PropConfigurations.js';
  * @since 0.24.0
  */
 
-/**
- * Names a library-wide prop convention that role emission consumes (ADR-067).
- *
- * An open string, keyed camelCase because it is a config key and is never
- * emitted into a spec (matching the `states` concept-key precedent).
- *
- * Covers facts carried by props and nowhere else — anything an element can carry
- * is a part role on that element instead, and a matching part role always wins
- * over a `propRoles` entry.
- *
- * Recognized concepts:
- * - `accessibleName` — the prop supplying an accessible name for controls with no
- *   text descendant (typically a code-only accessibility-label prop)
- * - `indeterminate` — a boolean prop forcing an indeterminate presentation
- * - `value` — the prop supplying a control's value where no element represents it
- *   (a progress bar draws its value; a text input has a `value` element)
- *
- * @since 0.32.0
- */
-export type PropRoleName = string;
+
 
 export interface VariantStateEntry {
   /** Figma variant prop name (e.g. `state`, `isDisabled`, `focused`). */
@@ -238,12 +219,6 @@ export interface PlatformConventions {
   slotConstraints?: boolean;
   /** This platform authors numeric props as Figma `TEXT` props whose default and examples parse as valid numbers, to be emitted as NumberProp rather than StringProp. Optional; defaults to false. */
   inferNumberProps?: boolean;
-  /** Concept-keyed map classifying Figma variant props as semantic states. Key = concept name (e.g. `hover`, `disabled`). Optional; absence means all variant props emit as data-* attribute selectors. @since 0.24.0 */
-  states?: Record<string, VariantStateEntry>;
-  /** Library-wide prop-name conventions consumed by role emission: maps a prop-role concept (`accessibleName`, `indeterminate`, `value`) to the prop name carrying it. Covers facts carried by props alone — element-level facts use part roles on anatomy elements, and a matching part role always wins. Per-component deviations are annotated on the component node. Optional; absence disables prop-role binding (ADR-067). @since 0.32.0 */
-  propRoles?: Record<PropRoleName, string>;
-  /** Severity for unmet required role obligations, e.g. a control with no accessible-name source (ADR-067). `warn` emits a diagnostic and continues; `error` fails the transform. Optional; defaults to `warn`, so absence preserves current behavior. Conflicts — two elements claiming one part, two value-bearing controls — are errors regardless. @since 0.32.0 */
-  roleValidation?: 'warn' | 'error';
   /**
    * Prop that receives styling no promotion mapped, for every promoted component on this
    * platform (e.g. `sx`, `style`, `modifier`). A **name only** — what is placed in it is
@@ -292,6 +267,63 @@ export interface PlatformConventions {
  *
  * @since 0.31.0
  */
+/**
+ * A prop named by a convention.
+ *
+ * An object rather than a bare prop name so a convention can grow properties of
+ * its own — pairing a label with the state that selects it, for instance — without
+ * a breaking change. `VariantStateEntry` already has this shape; this is the same
+ * idea for conventions that name a prop and nothing else yet.
+ *
+ * @since 0.32.0
+ */
+export interface PropReference {
+  /** The prop carrying this concept. */
+  prop: string;
+}
+
+/**
+ * Conventions about the **spec itself** (ADR-073 amendment).
+ *
+ * A sibling of `platforms` rather than a member of it, for the same reason
+ * `primitives` is: these are not facts about a platform. `states` names a prop and
+ * an enum value that exist in `api.yaml`; a transform reading only the spec can
+ * apply it and never touches Figma. Filing them under `figma` said they described
+ * the design tool, which they do not.
+ *
+ * Scope is library-wide. The per-component equivalent is an annotation, which
+ * lands in the spec itself — `anatomy.<element>.role` and `.actions`. Where both
+ * describe the same thing, the annotation wins: the specific over the general.
+ *
+ * @since 0.32.0
+ */
+export interface SpecsConventions {
+  /** What this library's props mean. */
+  props?: {
+    /**
+     * Concept-keyed map classifying variant props as semantic states. Key = concept
+     * name (e.g. `hover`, `disabled`). Absence means all variant props emit as
+     * `data-*` attribute selectors and all props are retained in contracts.
+     */
+    states?: Record<string, VariantStateEntry>;
+    /** Props carrying accessibility semantics no element expresses. */
+    accessibility?: {
+      /**
+       * The prop supplying an accessible name for a control with no text of its
+       * own — an icon-only button, typically. Where a `label` part role resolves,
+       * that wins: an element that carries the name is preferred to a prop.
+       */
+      label?: PropReference;
+    };
+    /**
+     * The prop supplying a control's value where no element represents it — a
+     * progress bar draws its progress rather than writing it. Where a `value` part
+     * role resolves, that wins.
+     */
+    value?: PropReference;
+  };
+}
+
 export interface Conventions {
   /** Platform-keyed conventions. The key is a free-form implementation id (`figma`, `react`, `swiftui`). */
   platforms?: Record<string, PlatformConventions>;
@@ -305,6 +337,11 @@ export interface Conventions {
    * @since 0.31.0
    */
   primitives?: Record<string, PrimitiveEntry>;
+  /**
+   * Conventions about the spec itself, rather than about any platform.
+   * Loaded from `conventions/specs.yaml`. @since 0.32.0
+   */
+  specs?: SpecsConventions;
 }
 
 /**
@@ -358,12 +395,6 @@ export interface ResolvedPlatformConventions {
   slotConstraints: boolean;
   /** Numeric props are authored as Figma `TEXT` props. */
   inferNumberProps: boolean;
-  /** Concept-keyed map classifying Figma variant props as semantic states. Optional; absence means no state convention. */
-  states?: Record<string, VariantStateEntry>;
-  /** Library-wide prop-name conventions consumed by role emission. Optional; absence disables prop-role binding. */
-  propRoles?: Record<PropRoleName, string>;
-  /** Severity for unmet required role obligations. Optional; absence means `warn`. */
-  roleValidation?: 'warn' | 'error';
   /** Prop that receives styling no promotion mapped. Optional; absence means unmapped styling is dropped. */
   stylesProp?: string;
   /** Width of the container a fill-width root is placed in. Optional; no default — absence means the tool falls back to its own value. */
@@ -380,6 +411,8 @@ export interface ResolvedPlatformConventions {
  */
 export interface ResolvedConventions {
   platforms?: Record<string, ResolvedPlatformConventions>;
+  /** Conventions about the spec itself. Optional; absence means none are declared. @since 0.32.0 */
+  specs?: SpecsConventions;
   /** Component-keyed promotion entries. Optional; absence means nothing is promoted. @since 0.31.0 */
   primitives?: Record<string, PrimitiveEntry>;
 }
diff --git a/packages/schema/types/Settings.ts b/packages/schema/types/Settings.ts
index 0a95116..000980a 100644
--- a/packages/schema/types/Settings.ts
+++ b/packages/schema/types/Settings.ts
@@ -69,6 +69,19 @@ export interface Settings {
      * @since 0.32.0
      */
     roles?: boolean;
+    /**
+     * Severity for unmet required role obligations — most commonly a control with
+     * no source for its accessible name (ADR-067).
+     *
+     * A setting rather than a convention: it describes how strict a run should be,
+     * which is a fact about neither the design tool nor the target. It sits beside
+     * `roles` because it tunes the same feature — with `roles` off there is nothing
+     * to validate. `warn` emits a diagnostic and continues; `error` fails the
+     * transform. Optional; defaults to `warn`. Conflicts — two elements claiming one
+     * part, two value-bearing controls — are errors regardless.
+     * @since 0.32.0
+     */
+    roleValidation?: 'warn' | 'error';
     /**
      * Token reference serialization profile. Optional; defaults to TOKEN.
      * `FIGMA_SYNTAX_WEB`, `FIGMA_SYNTAX_IOS`, and `FIGMA_SYNTAX_ANDROID` emit the
@@ -179,6 +192,8 @@ export interface ResolvedSettings {
     promotePrimitives: boolean;
     /** Dev Mode annotations are read and emitted as `anatomy.<element>.role`. */
     roles: boolean;
+    /** Severity for unmet required role obligations. */
+    roleValidation: 'warn' | 'error';
     /** Include invalid variants. */
     invalidVariants: boolean;
     /** Include invalid combinations. */
@@ -235,6 +250,7 @@ export const DEFAULT_SETTINGS: ResolvedSettings = {
     collapsePrimitiveWrapper: false,
     promotePrimitives: false,
     roles: false,
+    roleValidation: 'warn',
     invalidVariants: false,
     invalidCombinations: true,
     emptyVariants: false,
diff --git a/packages/schema/types/index.ts b/packages/schema/types/index.ts
index a2b0827..580d27b 100644
--- a/packages/schema/types/index.ts
+++ b/packages/schema/types/index.ts
@@ -34,7 +34,8 @@ export type {
   PrimitiveEntry,
   PrimitiveRule,
   VariantStateEntry,
-  PropRoleName,
+  SpecsConventions,
+  PropReference,
 } from './Conventions.js';
 export { DEFAULT_CONVENTIONS } from './Conventions.js';
 export type { Settings, ResolvedSettings, ColorFormat, SourceEntry } from './Settings.js';

From 8e4730b4d990cf307d9140f0b30489862610f924 Mon Sep 17 00:00:00 2001
From: Nathan Curtis <1165904+nathanacurtis@users.noreply.github.com>
Date: Fri, 4 Sep 2026 16:10:34 -0400
Subject: [PATCH 2/2] refactor(conventions): drop the props wrapper, and keep
 the state vocabulary closed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three revisions to the spec-conventions shape.

The `props` wrapper is gone. Everything the file holds describes props, so the
group earned nothing and read badly against the leaf it contained —
`props.states.disabled.prop` says "prop" twice. A grouping level is worth adding
when a second kind arrives, not before.

`indeterminate` is no longer folded into the state concepts. Those are a governed
vocabulary: each resolves to a canonical selector, and `indeterminate` there means
a checkbox's mixed state. A progress bar with no known value is a different fact
wearing the same word — it suppresses aria-valuenow and has no selector at all.
Widening a governed vocabulary to absorb a prop binding is what the governance
exists to prevent. It is modelled as `value.indeterminate` instead, a property of
the value, which is what it is: the prop that says this value is unknown.

`conventions/primitives.yaml` becomes `conventions/figma.primitives.yaml`. Its
`source` keys name Figma style properties and its `values` keys name Figma tokens,
so the file is Figma-scoped even though the components it produces are not. That
is the same test Decision 4 applies to every conventions file, and leaving it
unqualified said it was scope-free. Recorded as ADR 073 Decision 5, which reverses
part of Decision 2's reasoning — that reasoning held for the table's output and was
over-applied to the file.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 adr/067-anatomy-element-roles.md              | 72 ++++++++--------
 adr/073-platform-conventions-namespace.md     | 84 ++++++++++++++++---
 .../schema/schema/conventions.schema.json     | 55 +++++++-----
 packages/schema/tests/Conventions.test-d.ts   | 34 ++++----
 packages/schema/types/Conventions.ts          | 71 +++++++++++-----
 packages/schema/types/index.ts                |  1 +
 6 files changed, 208 insertions(+), 109 deletions(-)

diff --git a/adr/067-anatomy-element-roles.md b/adr/067-anatomy-element-roles.md
index 7ed8c5f..117ee11 100644
--- a/adr/067-anatomy-element-roles.md
+++ b/adr/067-anatomy-element-roles.md
@@ -10,7 +10,7 @@
 
 ## Context
 
-ADR 055 (state classification, now `props.states` in `conventions/specs.yaml`) lets a library deterministically classify variant props as semantic state concepts (`disabled`, `checked`, `expanded`). Downstream transforms consume that classification — but only at the *prop* level. Nothing in the spec identifies *which element carries the platform behavior*, so the `react` transform has no basis for emitting a `<button>`, injecting a native `<input>`, or wiring a `<label htmlFor>`. Every interactive component scaffolds as `div` + ARIA veneer:
+ADR 055 (state classification, now `states` in `conventions/specs.yaml`) lets a library deterministically classify variant props as semantic state concepts (`disabled`, `checked`, `expanded`). Downstream transforms consume that classification — but only at the *prop* level. Nothing in the spec identifies *which element carries the platform behavior*, so the `react` transform has no basis for emitting a `<button>`, injecting a native `<input>`, or wiring a `<label htmlFor>`. Every interactive component scaffolds as `div` + ARIA veneer:
 
 - A button renders `<div aria-disabled>` — no `<button>`, no native `disabled`, no `onClick`, no focus or keyboard behavior
 - A checkbox renders no `<input>` at all, bridges its selected state to `aria-selected` (a listbox-option attribute, incorrect for a checkbox), and leaves its label and error-message subcomponents unassociated
@@ -288,14 +288,14 @@ Without these, transforms fall back to matching prop names — the exact heurist
 
 **Scope discipline**: a prop convention covers facts that live in props and nowhere else. Anything an element can carry is a part role. An earlier draft put `placeholder` here; part roles supersede it entirely, because a placeholder is always a text element in components that have one.
 
-`value` is the one entry that lives in both worlds, and the precedence is explicit: **a `value` part wins where one exists; `props.value` is the fallback for controls whose value has no element.** Text controls use the part; progress bars use the prop. Both are declarations, neither is a guess.
+`value` is the one entry that lives in both worlds, and the precedence is explicit: **a `value` part wins where one exists; `value.prop` is the fallback for controls whose value has no element.** Text controls use the part; progress bars use the prop. Both are declarations, neither is a guess.
 
 This also makes **code-only props a first-class semantic surface** without changing what the code-only-props frame means. The frame keeps its single meaning — literal props — while the spec conventions classify which of those props carries the accessible name or the value. A library can therefore author real semantic payload with one hidden layer in a frame it already has, rather than restructuring its components.
 
 ### Option 4A: Spec conventions for the library, annotations for exceptions *(Selected)*
 
 A `props` block in `conventions/specs.yaml` declares the library-wide prop conventions,
-beside `props.states` which answers the same shape of question. A component that deviates
+beside `states` which answers the same shape of question. A component that deviates
 overrides it with an annotation on its component node, using the same `key:value` grammar as
 roles.
 
@@ -305,10 +305,9 @@ sit beside `platforms` rather than inside it.
 
 ```yaml
 # conventions/specs.yaml
-props:
-  accessibility:
-    label:
-      prop: a11yLabel
+accessibility:
+  label:
+    prop: a11yLabel
 ```
 
 ```
@@ -397,8 +396,8 @@ different places:
 | Satisfier kind | Example |
 |---|---|
 | A part role resolved to this control | a `label` element |
-| A prop convention | `props.accessibility.label` in `conventions/specs.yaml` |
-| A state classification from `props.states` | the `checked` entry |
+| A prop convention | `accessibility.label` in `conventions/specs.yaml` |
+| A state classification from `states` | the `checked` entry |
 | An existing variant prop | a `value` prop the library already declares |
 
 - **It matches how the requirements actually work.** The most important obligation — that a
@@ -421,7 +420,7 @@ Declare edges between concepts — `checkbox` requires `label`, `disclosure` req
 
 - Simple to state, simple to implement, and easy to visualize
 - **But it can only see annotations, and the requirements are not all annotations.** An
-  icon-only button names itself through `props.accessibility.label`, which is a convention
+  icon-only button names itself through `accessibility.label`, which is a convention
   in a different file. A graph over annotations would report that correctly-named control
   as broken, and the false positive would land on exactly the components this feature exists
   to improve
@@ -615,7 +614,7 @@ that plainly removes most of the ambiguity readers have reported about what a pa
 
 ### Roles and the states config
 
-`anatomy.role` and `props.states` are **independent authoring inputs**. Either may
+`anatomy.role` and `states` are **independent authoring inputs**. Either may
 exist without the other, neither supersedes the other, and the role feature must not gate
 or disable existing states behavior.
 
@@ -623,7 +622,7 @@ They answer different questions, and neither answer is derivable from the other:
 
 | Input | Answers |
 |---|---|
-| `props.states` | *Which variant prop carries this concept?* |
+| `states` | *Which variant prop carries this concept?* |
 | `anatomy.role` | *What mechanism is available to express it?* |
 
 A states classification with no role behaves exactly as it does today. A role with no
@@ -640,7 +639,7 @@ the two mechanisms have.
 
 **The dependency runs role → states.** A role's *wired* event handlers cannot be generated
 without a resolved state binding. A `togglebutton` that flips its own pressed state must be
-told which prop holds that state, and only `props.states` can tell it. Several
+told which prop holds that state, and only `states` can tell it. Several
 concepts are therefore **inert without a states classification**, degrading to a stub
 handler and a warning rather than to generated state management. Roles depend on the states
 config; they do not replace any part of it.
@@ -670,14 +669,14 @@ discharges it**.
 
 | Obligation | Declared by | Level | Satisfied by any of |
 |---|---|---|---|
-| `name` | every control concept | required | a `label` part resolved to this control; `props.accessibility.label`; for `group`, a `label` part emitted as `<legend>` |
-| `value` | value-bearing controls using `collapse` (`textbox`, `password`, `searchbox`, `textarea`, `spinbutton`, `slider`) | required | a `value` part; an existing variant prop bound as the value; `props.value` |
-| `checkedstate` | `checkbox`, `radio`, `switch` | expected | a `checked` classification in `props.states` |
-| `pressedstate` | `togglebutton` | expected | a `pressed` classification in `props.states` |
-| `expandedstate` | `disclosure` | expected | an `expanded` classification in `props.states` |
+| `name` | every control concept | required | a `label` part resolved to this control; `accessibility.label`; for `group`, a `label` part emitted as `<legend>` |
+| `value` | value-bearing controls using `collapse` (`textbox`, `password`, `searchbox`, `textarea`, `spinbutton`, `slider`) | required | a `value` part; an existing variant prop bound as the value; `value.prop` |
+| `checkedstate` | `checkbox`, `radio`, `switch` | expected | a `checked` classification in `states` |
+| `pressedstate` | `togglebutton` | expected | a `pressed` classification in `states` |
+| `expandedstate` | `disclosure` | expected | an `expanded` classification in `states` |
 | `panel` | `disclosure` | expected | a `panel` part resolved to this control |
 | `membership` | `group` | expected | a slot whose `anyOf` resolves to entries carrying control roles |
-| `progressvalue` | `progressbar` | expected | `props.value`; an `indeterminate` classification in `props.states` |
+| `progressvalue` | `progressbar` | expected | `value.prop`; `value.indeterminate` |
 | `steppers` | `spinbutton` | optional | `increment` and `decrement` parts |
 | `statelabels` | `togglebutton`, `disclosure` | optional | a prop convention pairing a state concept to an alternate text prop |
 
@@ -706,7 +705,7 @@ label" sends an author to the wrong fix when the right one is a config entry.
 warning  checkbox 'root' in components/checkbox has no name source
          satisfy with one of:
            - a `label` role on an element in this component
-           - a `props.accessibility.label` convention
+           - an `accessibility.label` convention
          emitting without an accessible name
 ```
 
@@ -749,34 +748,29 @@ role:
   # not in required[] — optional field
 ```
 
-**Example — new processing properties** (`workspace.schema.json`):
+**Example — the spec conventions block** (`conventions.schema.json`):
 
 ```yaml
-props:
+states:
+  description: "Concept-keyed map classifying variant props as semantic states."
+accessibility:
   type: object
-  additionalProperties: false
   properties:
-    states:
-      description: "Concept-keyed map classifying variant props as semantic states."
-    accessibility:
-      type: object
-      properties:
-        label:
-          $ref: "#/definitions/PropReference"
-          description: "The prop supplying an accessible name for a control with no text of its own."
-    value:
+    label:
       $ref: "#/definitions/PropReference"
-      description: "The prop supplying a control's value where no element represents it."
+      description: "The prop supplying an accessible name for a control with no text of its own."
+value:
+  $ref: "#/definitions/ValueConvention"
+  description: "The prop carrying a control's value, and the prop that says that value is unknown."
 ```
 
 **Config example** (`specs.config.yaml`):
 
 ```yaml
 # conventions/specs.yaml
-props:
-  accessibility:
-    label:
-      prop: a11yLabel
+accessibility:
+  label:
+    prop: a11yLabel
 ```
 
 **Spec example** (`api.yaml` — all `role` values generated from Dev Mode annotations):
@@ -868,7 +862,7 @@ A role's contract additions can collide with props the component already has. **
 
 The rules, which every vocabulary ADR inherits:
 
-1. **An existing prop becomes the reset signal, not a controlled value.** Where a role's concept (`checked`, `expanded`, `pressed`, `value`) is already carried by a prop the spec declares — directly or via a `props.states` classification — that prop seeds the control's state and re-seeds it whenever the prop's value changes. **No `default*` companion prop is emitted.** The component is explicitly *not* controlled in the React sense, and the ADRs must not call it that.
+1. **An existing prop becomes the reset signal, not a controlled value.** Where a role's concept (`checked`, `expanded`, `pressed`, `value`) is already carried by a prop the spec declares — directly or via a `states` classification — that prop seeds the control's state and re-seeds it whenever the prop's value changes. **No `default*` companion prop is emitted.** The component is explicitly *not* controlled in the React sense, and the ADRs must not call it that.
 2. **The role still contributes the change signal.** The handler prop (`onChange`, `onExpandedChange`, `onPressedChange`) is always added, and is always optional.
 3. **Re-seeding happens during render, not in an effect.** The generated pattern is React's documented "adjust state when a prop changes" form — track the previous prop value in state and reset during render when it differs — **not** `useState` plus a `useEffect` sync. The effect form runs after paint, so it produces a visible frame of stale state and an extra committed render on every parent-driven change. The render-time form commits once, with no flicker.
 
@@ -1012,7 +1006,7 @@ The vocabulary ADRs describe emission; this section fixes the *shape* the implem
 - The generated/authored boundary stays crisp: `api.yaml` is reproducible from Figma data alone, and authored facts live on their own surface with its own diff history
 - The code-only-props frame keeps a single meaning: literal props
 - Vocabulary ADRs can grow the recognized concept set without schema bumps — unrecognized roles are inert
-- `props.states`, `props.accessibility`/`props.value`, and `anatomy.role` compose: the state conventions classify the state props, the prop conventions classify the name and value props, and roles locate the platform behavior. All three are required for emission-quality transforms — and all three describe the spec, which is why the first two moved out of the platform block
+- `states`, `accessibility` / `value`, and `anatomy.role` compose: the state conventions classify the state props, the prop conventions classify the name and value props, and roles locate the platform behavior. All three are required for emission-quality transforms — and all three describe the spec, which is why the first two moved out of the platform block
 - A future warning surface becomes possible: a `checked` state concept configured with no control role present, or a control role with no resolvable accessible name
 - The annotation delimiter becomes a reserved character in layer names for libraries that opt in — resolvable per-library via the pattern, but a real constraint to communicate
 - A per-component authored surface enters the workspace — the first of its kind for spec-level facts, and a forcing function for the authored-hub model's file conventions
diff --git a/adr/073-platform-conventions-namespace.md b/adr/073-platform-conventions-namespace.md
index 869bba6..a4e15eb 100644
--- a/adr/073-platform-conventions-namespace.md
+++ b/adr/073-platform-conventions-namespace.md
@@ -268,15 +268,22 @@ about the design tool. `states` is not, and filing it under `figma` said it was.
 
 ```yaml
 # conventions/specs.yaml
-props:
-  states:
-    disabled:
-      prop: isDisabled
-  accessibility:
-    label:
-      prop: a11yLabel
+states:
+  disabled:
+    prop: isDisabled
+accessibility:
+  label:
+    prop: a11yLabel
+value:
+  prop: progress
+  indeterminate: isLooping
 ```
 
+No `props` wrapper. Everything the file holds today describes props, so the group
+earns nothing and reads badly against the leaf it contains — `props.states.disabled.prop`
+says "prop" twice. A grouping level is worth adding when a second kind arrives, not
+before.
+
 - **`primitives` is the precedent.** It already sits outside `platforms` for exactly this
   reason — a component's props are the same whichever platform renders it, so the table is
   stated once. Spec conventions are the same kind of exception, and reuse a shape the file
@@ -327,6 +334,56 @@ artifact would separate `states` from the file set it belongs to, for a distinct
 
 ---
 
+## Decision 5 — Whether `primitives.yaml` should be `figma.primitives.yaml`
+
+Decision 2 put `primitives` outside `platforms` on the grounds that it is
+platform-neutral: a component's props are the same whichever platform renders it. That
+is true of the **result** and not of the **inputs**, which the table is mostly made of:
+
+```yaml
+deIcon:
+  map:
+    - source: fillColor                       # a Figma style property
+      values: { "DS Color/Icon/Primary": { color: Primary } }   # a Figma token name
+    - source: width                           # a Figma style property
+```
+
+`source` names Figma style properties; the keys under `values` are Figma token names. A
+SwiftUI capture would need a different table with different sources. So the file is
+Figma-scoped in a way `specs.yaml` is not, and this is exactly the test Decision 4
+applies — does it name facts about the design tool, or facts about the spec?
+
+### Option 5A: Rename to `figma.primitives.yaml` *(Selected)*
+
+- **It passes the Decision 4 test**, which is the test this ADR now applies to every
+  conventions file. Leaving it unqualified says it is scope-free, and it is not
+- Establishes `<scope>.<concern>.yaml` as the pattern for a scoped file that is not a
+  whole platform block, leaving room for `figma.<other>.yaml` without another debate
+- `specs.yaml` stays unqualified and correct — it *is* the whole of the spec's conventions
+
+**Cons / Trade-offs**:
+
+- Reverses the reading in Decision 2. That reasoning stands for the *output* of the
+  table and was over-applied to the file as a whole
+- A reserved basename changes, so `PRIMITIVES_FILE` and any workspace carrying the file
+  must move together. Cheap now, less cheap later
+
+### Option 5B: Leave it `primitives.yaml` *(Rejected)*
+
+**Rejected because**: it makes the conventions directory two things at once — files named
+for a platform, and one named for a concern — with nothing distinguishing which is which.
+A reader has to know that `figma.yaml` is scoped and `primitives.yaml` is also scoped but
+does not say so.
+
+### Option 5C: Move it under `platforms.figma.primitives` *(Rejected)*
+
+**Rejected because**: it would grow the platform block with a component-keyed table, and
+the promotion result genuinely is platform-neutral — a captured layer becomes the same
+component whichever target renders it later. The file is Figma-scoped; its contents are
+not wholly so. A qualified filename says that; nesting it inside the platform block
+overstates it.
+
+
 ## Decision
 
 ### Type changes (`types/`)
@@ -339,8 +396,10 @@ artifact would separate `states` from the file set it belongs to, for a distinct
 | `Conventions.ts` | `DEFAULT_CONVENTIONS` no longer carries a `figma` key; defaults move inside a declared platform entry | MINOR |
 | `Conventions.ts` | Doc comment widened from "facts about the Figma library" to facts about every library the pipeline reads or writes | PATCH |
 | `Conventions.ts` | Added `SpecsConventions` and `Conventions.specs?`, a sibling of `platforms` and `primitives` — conventions describing the spec rather than a platform (Decision 4) | MINOR |
+| *(no type change)* | `conventions/primitives.yaml` is renamed `conventions/figma.primitives.yaml` — a reserved-basename change, not a type change (Decision 5) | PATCH |
 | `Conventions.ts` | Added `PropReference` (`{ prop: string }`), so a prop convention can grow fields without a break | MINOR |
-| `Conventions.ts` | `states` moved from `PlatformConventions` to `Conventions.specs.props.states` — it names a spec prop and a spec enum value, not a Figma fact | MINOR |
+| `Conventions.ts` | Added `ValueConvention` (`{ prop, indeterminate? }`) — the indeterminate binding is a property of the value, not a state concept | MINOR |
+| `Conventions.ts` | `states` moved from `PlatformConventions` to `Conventions.specs.states` — it names a spec prop and a spec enum value, not a Figma fact. Its concept vocabulary is unchanged | MINOR |
 
 **Example — new shape** (`types/Conventions.ts`):
 
@@ -356,11 +415,10 @@ Conventions:
 Conventions:
   # conventions about the spec itself — not about any platform (Decision 4)
   specs?:
-    props?:
-      states?: {...}
-      accessibility?:
-        label?: { prop: string }
-      value?: { prop: string }
+    states?: {...}
+    accessibility?:
+      label?: { prop: string }
+    value?: { prop: string, indeterminate?: string }
   platforms?:
     <platformId>:
       # encoding — how this platform expresses what the spec models
diff --git a/packages/schema/schema/conventions.schema.json b/packages/schema/schema/conventions.schema.json
index 84ca2d7..b3218c3 100644
--- a/packages/schema/schema/conventions.schema.json
+++ b/packages/schema/schema/conventions.schema.json
@@ -323,34 +323,45 @@
       "additionalProperties": false,
       "description": "Conventions about the spec itself rather than about any platform. A sibling of `platforms` for the same reason `primitives` is: `states` names a prop and an enum value that exist in api.yaml, and a transform reading only the spec can apply it. Library-wide; the per-component equivalent is an annotation, and the annotation wins.",
       "properties": {
-        "props": {
+        "states": {
+          "type": "object",
+          "description": "Concept-keyed map classifying Figma variant props as semantic states.",
+          "additionalProperties": {
+            "$ref": "#/definitions/VariantStateEntry"
+          }
+        },
+        "accessibility": {
           "type": "object",
           "additionalProperties": false,
-          "description": "What this library's props mean.",
+          "description": "Props carrying accessibility semantics no element expresses.",
           "properties": {
-            "states": {
-              "type": "object",
-              "description": "Concept-keyed map classifying Figma variant props as semantic states.",
-              "additionalProperties": {
-                "$ref": "#/definitions/VariantStateEntry"
-              }
-            },
-            "accessibility": {
-              "type": "object",
-              "additionalProperties": false,
-              "description": "Props carrying accessibility semantics no element expresses.",
-              "properties": {
-                "label": {
-                  "$ref": "#/definitions/PropReference",
-                  "description": "The prop supplying an accessible name for a control with no text of its own. A resolving `label` part role wins over it."
-                }
-              }
-            },
-            "value": {
+            "label": {
               "$ref": "#/definitions/PropReference",
-              "description": "The prop supplying a control's value where no element represents it. A resolving `value` part role wins over it."
+              "description": "The prop supplying an accessible name for a control with no text of its own. A resolving `label` part role wins over it."
             }
           }
+        },
+        "value": {
+          "$ref": "#/definitions/ValueConvention",
+          "description": "The prop supplying a control's value where no element represents it. A resolving `value` part role wins over it."
+        }
+      }
+    },
+    "ValueConvention": {
+      "type": "object",
+      "required": [
+        "prop"
+      ],
+      "additionalProperties": false,
+      "description": "The props describing a control's value. `indeterminate` sits here rather than among the state concepts: those are a governed vocabulary where `indeterminate` means a checkbox's mixed state, and a progress bar with no known value is a different fact wearing the same word.",
+      "properties": {
+        "prop": {
+          "type": "string",
+          "description": "The prop carrying the value."
+        },
+        "indeterminate": {
+          "type": "string",
+          "description": "A boolean prop that forces the indeterminate presentation regardless of the value."
         }
       }
     }
diff --git a/packages/schema/tests/Conventions.test-d.ts b/packages/schema/tests/Conventions.test-d.ts
index f16fd29..761608c 100644
--- a/packages/schema/tests/Conventions.test-d.ts
+++ b/packages/schema/tests/Conventions.test-d.ts
@@ -189,31 +189,36 @@ const badContract: VariantStateEntry = { prop: 'focused', contract: 'inherit' };
 
 // ─── Spec-side conventions (ADR-073 amendment) ────────────────────────────────
 
-// props.states classifies variant props as semantic states
+// states classifies variant props as semantic states — unchanged vocabulary
 const specStates: SpecsConventions = {
-  props: { states: { disabled: { prop: 'disabled' }, hover: { prop: 'state', value: 'Hover' } } },
+  states: { disabled: { prop: 'disabled' }, hover: { prop: 'state', value: 'Hover' } },
 };
 
-// props.accessibility.label names the prop carrying an accessible name
+// accessibility.label names the prop carrying an accessible name
 const specAccessibility: SpecsConventions = {
-  props: { accessibility: { label: { prop: 'accessibilityLabel' } } },
+  accessibility: { label: { prop: 'accessibilityLabel' } },
 };
 
-// props.value names the prop carrying a value no element represents
-const specValue: SpecsConventions = { props: { value: { prop: 'progress' } } };
+// value names the prop carrying a value no element represents, and the prop that
+// says that value is unknown — a property OF the value, not a state concept
+const specValue: SpecsConventions = { value: { prop: 'progress', indeterminate: 'isLooping' } };
 
-// All three compose, and every block is optional
+// indeterminate is optional; a value with a known number needs nothing else
+const specValueOnly: SpecsConventions = { value: { prop: 'progress' } };
+
+// Every block is optional and they compose
 const specAll: SpecsConventions = {
-  props: {
-    states: { disabled: { prop: 'disabled' } },
-    accessibility: { label: { prop: 'accessibilityLabel' } },
-    value: { prop: 'progress' },
-  },
+  states: { disabled: { prop: 'disabled' } },
+  accessibility: { label: { prop: 'accessibilityLabel' } },
+  value: { prop: 'progress' },
 };
 const specNone: SpecsConventions = {};
 
 // @ts-expect-error — a prop reference is an object, so it can grow fields later
-const specBareString: SpecsConventions = { props: { accessibility: { label: 'accessibilityLabel' } } };
+const specBareString: SpecsConventions = { accessibility: { label: 'accessibilityLabel' } };
+
+// @ts-expect-error — a value convention requires the prop it names
+const specValueNoProp: SpecsConventions = { value: { indeterminate: 'isLooping' } };
 
 // @ts-expect-error — states no longer live on a platform
 const platformStates: PlatformConventions = { states: { disabled: { prop: 'disabled' } } };
@@ -226,5 +231,6 @@ export {
   width, stringWidth, platformMayBeAbsent, naming, constraints, numbers, scope, sourceProps,
   platformStyles, resolvedEntry, underResolved, meta,
   metaWithoutPlatforms, defaults, defaultedPlatform, booleanState, enumState, noProp, badContract,
-  specStates, specAccessibility, specValue, specAll, specNone, specBareString, platformStates,
+  specStates, specAccessibility, specValue, specValueOnly, specAll, specNone, specBareString,
+  specValueNoProp, platformStates,
 };
diff --git a/packages/schema/types/Conventions.ts b/packages/schema/types/Conventions.ts
index ff26253..3404de4 100644
--- a/packages/schema/types/Conventions.ts
+++ b/packages/schema/types/Conventions.ts
@@ -298,30 +298,59 @@ export interface PropReference {
  * @since 0.32.0
  */
 export interface SpecsConventions {
-  /** What this library's props mean. */
-  props?: {
-    /**
-     * Concept-keyed map classifying variant props as semantic states. Key = concept
-     * name (e.g. `hover`, `disabled`). Absence means all variant props emit as
-     * `data-*` attribute selectors and all props are retained in contracts.
-     */
-    states?: Record<string, VariantStateEntry>;
-    /** Props carrying accessibility semantics no element expresses. */
-    accessibility?: {
-      /**
-       * The prop supplying an accessible name for a control with no text of its
-       * own — an icon-only button, typically. Where a `label` part role resolves,
-       * that wins: an element that carries the name is preferred to a prop.
-       */
-      label?: PropReference;
-    };
+  /**
+   * Concept-keyed map classifying variant props as semantic states.
+   *
+   * Unchanged from where it previously sat, including its concept vocabulary: the
+   * concepts are governed, each resolving to a canonical selector, and that
+   * governance is why nothing else is folded in here. Absence means all variant
+   * props emit as `data-*` attribute selectors and all props are retained in
+   * contracts.
+   */
+  states?: Record<string, VariantStateEntry>;
+  /** Props carrying accessibility semantics no element expresses. */
+  accessibility?: {
     /**
-     * The prop supplying a control's value where no element represents it — a
-     * progress bar draws its progress rather than writing it. Where a `value` part
-     * role resolves, that wins.
+     * The prop supplying an accessible name for a control with no text of its own —
+     * an icon-only button, typically. Where a `label` part role resolves, that wins:
+     * an element carrying the name is preferred to a prop.
      */
-    value?: PropReference;
+    label?: PropReference;
   };
+  /**
+   * The prop supplying a control's value where no element represents it — a progress
+   * bar draws its progress rather than writing it. Where a `value` part role
+   * resolves, that wins.
+   */
+  value?: ValueConvention;
+}
+
+/**
+ * The props describing a control's value.
+ *
+ * `indeterminate` sits here rather than among the state concepts because those are a
+ * governed vocabulary: each resolves to a canonical selector, and `indeterminate`
+ * there means a checkbox's mixed state (`:indeterminate`, `aria-checked="mixed"`).
+ * A progress bar with no known value is a different fact wearing the same word — it
+ * suppresses `aria-valuenow` and has no selector at all. Folding them would widen a
+ * governed vocabulary to absorb a prop binding, which is what the governance exists
+ * to prevent.
+ *
+ * Modelling it as a property *of* the value is what it actually is: the prop that
+ * says this value is unknown.
+ *
+ * @since 0.32.0
+ */
+export interface ValueConvention {
+  /** The prop carrying the value. */
+  prop: string;
+  /**
+   * A boolean prop that forces the indeterminate presentation regardless of the
+   * value. Resolution order: this true suppresses the value; otherwise a resolved
+   * `prop` produces the determinate form; otherwise the indeterminate form is
+   * emitted with a warning.
+   */
+  indeterminate?: string;
 }
 
 export interface Conventions {
diff --git a/packages/schema/types/index.ts b/packages/schema/types/index.ts
index 580d27b..92b7a3a 100644
--- a/packages/schema/types/index.ts
+++ b/packages/schema/types/index.ts
@@ -36,6 +36,7 @@ export type {
   VariantStateEntry,
   SpecsConventions,
   PropReference,
+  ValueConvention,
 } from './Conventions.js';
 export { DEFAULT_CONVENTIONS } from './Conventions.js';
 export type { Settings, ResolvedSettings, ColorFormat, SourceEntry } from './Settings.js';