@orkestrel/scaffold 0.0.58 → 0.0.60

package/dist/host/agents/skills/enterprise-bootstrap/references/inputs.md

@@ -0,0 +1,501 @@
+# Input affordances
+
+Pick an affordance from what the person is asked for, not from the name a schema gives the field.
+Where one category draws several ways, let the density and the list size decide.
+
+Read [The fixed state set](#the-fixed-state-set) before the catalog: every affordance handles that
+same set, and each category names only what it adds or changes. Take the data states a whole surface
+ships — ideal, empty, loading, partial, error — from
+[bootstrap-reference.md](bootstrap-reference.md) → The data states instead.
+
+## Contents
+
+- [The fixed state set](#the-fixed-state-set)
+- [Rules that cross every category](#rules-that-cross-every-category)
+- [The catalog](#the-catalog)
+- [Where Bootstrap ships no component](#where-bootstrap-ships-no-component)
+
+## The fixed state set
+
+Draw every one of these for every affordance you place. A category adds `empty` and `full` when its
+value is a set.
+
+- **rest** — no pointer, no keyboard focus, the value the field holds.
+- **hover** — pointer over the control. The chrome moves, the value does not.
+- **focus-visible** — keyboard focus carrying the ring the theme ships. Never write `outline: none`.
+- **disabled** — not editable and not submitted. Use the `disabled` attribute; the contrast bars
+  exempt it.
+- **locked** — not editable and still submitted. Use `readonly` on a control that honors it, and
+  `disabled` plus a carrier that submits the value on one that does not.
+- **invalid** — `is-invalid` on the control, a sibling `.invalid-feedback` message,
+  `aria-invalid="true"`, and the message wired to the control with `aria-describedby`.
+- **busy** — waiting on work the person cannot see: a select whose options are still loading, a
+  field checking a value against a server. Mark the region `aria-busy="true"` and show a
+  `spinner-border spinner-border-sm` in the control's own chrome. Leave the control operable unless
+  its value depends on the work.
+- **required** — state the requirement in the visible label and set the `required` attribute on the
+  control. A `text-danger` asterisk is decoration and carries `aria-hidden="true"`; the word in the
+  label is what a screen reader user gets.
+- **with help** — a `.form-text` under the control, wired with `aria-describedby` beside the error
+  message rather than in place of it.
+- **empty** — the set holds nothing. Say what an entry would be, not "nothing here".
+- **full** — the set is at its cap. State the cap and stop accepting, rather than dropping an entry
+  silently.
+
+## Rules that cross every category
+
+- **Keep a read-only field on the same affordance the edit state uses.** Take `readonly`, or
+  `disabled` plus a carrier, and neutralize the chrome with one transparent combination declared
+  once by name — the combination is a class contract, so declare it and reuse it rather than
+  retyping the utilities. Never swap to `form-control-plaintext`: it drops the horizontal padding,
+  so the read view and the edit view reflow against each other.
+- **Give a locked select `disabled` and a hidden input beside it.** A native select cannot be
+  read-only, so `disabled` stops its value submitting and the hidden input carries that value.
+- **Give a chosen filter an accent tone class, not the neutral outline.** A `btn-outline-secondary`
+  label reads as chosen in light and as muted in dark, so one markup says opposite things.
+- **Give each field one visible label**, per [bootstrap-reference.md](bootstrap-reference.md) →
+  Forms in production. Take labels, validation timing, and the error summary from that section, and
+  the affordance that carries them from [The catalog](#the-catalog).
+- **Match the control sizes in a row.** Take `form-control-sm`, `form-select-sm`, `input-group-sm`,
+  and `btn-sm` together so a dense row shares one height.
+- **Where Bootstrap ships no component, name the APG pattern the hand-roll owes** and route the
+  build-or-buy decision to [bootstrap-reference.md](bootstrap-reference.md) → When not to hand-roll.
+  Take those categories and their patterns from
+  [Where Bootstrap ships no component](#where-bootstrap-ships-no-component).
+
+## The catalog
+
+### One line of text
+
+**Default.** An `input.form-control` under its own `label.form-label`, at rung 1.
+
+```html
+<label for="account-name" class="form-label">Account name</label>
+<input type="text" class="form-control" id="account-name" aria-describedby="account-name-help" />
+<div id="account-name-help" class="form-text">The name on the invoice.</div>
+```
+
+**Alternates.** Take `.form-floating` when the row is too dense for a label line and the field is
+never empty at rest. Take `.input-group` with `.input-group-text` when a prefix, a unit, or an
+adjacent action belongs to the field; add `.has-validation` to the group so the feedback keeps the
+border radius. Inside a dense grid cell, keep `form-control` and neutralize its chrome with the
+declared transparent combination rather than dropping the control.
+
+**States.** The fixed set, and nothing more.
+
+### Text over many lines
+
+**Default.** A `textarea.form-control` with a `rows` attribute sized to the expected answer, at
+rung 1.
+
+```html
+<label for="incident-notes" class="form-label">Notes</label>
+<textarea class="form-control" id="incident-notes" rows="3"></textarea>
+```
+
+**Alternates.** Take `.form-floating` when the surrounding rows use it, and set the height with a
+stylesheet rule or a component variable rather than a `style` attribute. Draw a one-row composer that
+grows as the person types from this same control with a scripted height. Bootstrap ships no
+rich-text editor, so treat one as a hand-roll.
+
+**States.** The fixed set, plus `full` where a character cap bounds the answer. Show the remaining
+count in the `.form-text`, and keep it out of a live region unless the cap is close.
+
+### A secret
+
+**Default.** An `input[type=password].form-control` under a visible label, at rung 1.
+
+```html
+<label for="passphrase" class="form-label">Passphrase</label>
+<div class="input-group">
+	<input type="password" class="form-control" id="passphrase" autocomplete="current-password" />
+	<button type="button" class="btn btn-outline-secondary" aria-pressed="false">Show</button>
+</div>
+```
+
+**Alternates.** Take the `.input-group` reveal button whenever the value is typed rather than pasted
+from a manager, and toggle `aria-pressed` with the input `type`. Never block paste, and never mask a
+one-time code the person must read back.
+
+**States.** The fixed set. A strength or availability check runs as `busy` while it waits, not as
+`invalid`.
+
+### A number
+
+**Default.** An `input[type=number].form-control`, at rung 1. In a column of figures add
+`text-end font-monospace` so the digits align, at rung 2.
+
+```html
+<label for="unit-count" class="form-label">Units</label>
+<input type="number" class="form-control text-end font-monospace" id="unit-count" step="1" />
+```
+
+**Alternates.** Take `.input-group` with `.input-group-text` for a currency symbol or a unit, so the
+unit is chrome rather than something the person must type. Where the value is an identifier rather
+than a quantity, take the one-line-of-text category instead.
+
+**States.** The fixed set. Validate the range on blur and state the bound in the message.
+
+### A number in a bounded range
+
+**Default.** An `input.form-range`, at rung 1, and only when a minimum, a maximum, and a step are all
+fixed.
+
+```html
+<label for="threshold" class="form-label">Threshold</label>
+<div class="d-flex align-items-center gap-2">
+	<input type="range" class="form-range" id="threshold" min="0" max="100" step="5" />
+	<output for="threshold" class="font-monospace">50</output>
+</div>
+```
+
+**Alternates.** Keep a number input beside or instead of the slider when an exact value matters — a
+range paints no read-out of its own, so a lone slider hides the value it sets. A two-thumb range is a
+hand-roll: Bootstrap ships one thumb per input.
+
+**States.** The fixed set. A disabled range still shows its value, so keep the read-out visible.
+
+### A date
+
+**Default.** An `input[type=date].form-control`, at rung 1. Take the calendar, the keyboard model,
+and the locale format from the platform rather than authoring any of them.
+
+```html
+<label for="starts" class="form-label">Starts</label>
+<input type="date" class="form-control" id="starts" />
+```
+
+**Alternates.** For a period, take two native inputs — a start and an end — before reaching for a
+range picker, and validate the order on blur. Treat a calendar grid of your own as a hand-roll.
+
+**States.** The fixed set. Express an unavailable day with `min`, `max`, and a stated rule in the
+help text, because a native picker takes no per-day exclusion.
+
+### A time
+
+**Default.** An `input[type=time].form-control`, at rung 1, with `step` set to the granularity the
+value actually carries.
+
+```html
+<label for="cutoff" class="form-label">Cutoff</label>
+<input type="time" class="form-control" id="cutoff" step="900" />
+```
+
+**Alternates.** Treat segmented numeric fields as a hand-roll owing a spinbutton contract per
+segment. Where the person picks from a fixed set of slots, take the one-of-many category instead: a
+select is the lighter control.
+
+**States.** The fixed set.
+
+### A date and time
+
+**Default.** An `input[type=datetime-local].form-control`, at rung 1.
+
+```html
+<label for="window-opens" class="form-label">Window opens</label>
+<input type="datetime-local" class="form-control" id="window-opens" />
+```
+
+**Alternates.** Split into a date field and a time field when the two halves validate apart, when
+one half is optional, or when a time zone control belongs between them. Name the zone the value is
+stored in; a local datetime carries none.
+
+**States.** The fixed set.
+
+### A color
+
+**Default.** An `input.form-control-color[type=color]`, at rung 1.
+
+```html
+<label for="brand-tint" class="form-label">Brand tint</label>
+<input type="color" class="form-control form-control-color" id="brand-tint" value="#4a6fa5" />
+```
+
+**Alternates.** Pair the swatch with a text field when the value is copied, pasted, or read aloud
+between people. Keep the swatch at a 24×24px target or larger.
+
+**States.** The fixed set. A color input has no empty value, so give the field a default and say what
+it is.
+
+### One on/off answer
+
+**Default.** A `.form-check` holding one `input.form-check-input[type=checkbox]` and its
+`label.form-check-label`, at rung 1.
+
+```html
+<div class="form-check">
+	<input class="form-check-input" type="checkbox" id="send-receipt" />
+	<label class="form-check-label" for="send-receipt">Email me a receipt</label>
+</div>
+```
+
+**Alternates.** Take `.form-check.form-switch` with `role="switch"` when the change applies the
+moment it is flipped, and keep the plain checkbox when the value commits on submit. A lone box is
+one answer; a group of boxes holding a list is a different category, so read the any-of rows before
+grouping boxes.
+
+**States.** The fixed set. A switch that applies immediately is `busy` while the change is in
+flight, and reverts visibly when it fails.
+
+### One of a few
+
+**Default.** A radio group: `fieldset` and `legend` around `.form-check` rows, at rung 1.
+
+```html
+<fieldset>
+	<legend class="form-label">Billing cycle</legend>
+	<div class="form-check">
+		<input class="form-check-input" type="radio" name="cycle" id="cycle-monthly" />
+		<label class="form-check-label" for="cycle-monthly">Monthly</label>
+	</div>
+	<div class="form-check">
+		<input class="form-check-input" type="radio" name="cycle" id="cycle-annual" />
+		<label class="form-check-label" for="cycle-annual">Annual</label>
+	</div>
+</fieldset>
+```
+
+**Alternates.** Take a segmented `.btn-group` of `.btn-check` radios, at rung 2, when the choice
+sits in a toolbar or a filter bar and every option fits on one row without wrapping; give the group
+`role="radiogroup"` and one accessible name. A radio group and a segmented group draw the same
+question, and the list size decides between them. Give a chosen filter an accent tone class rather
+than `btn-outline-secondary`.
+
+**States.** The fixed set, applied to the group rather than to one option. Mark the group invalid,
+name it in the message, and keep the error under the last row.
+
+### One of many
+
+**Default.** A `select.form-select`, at rung 1.
+
+```html
+<label for="territory" class="form-label">Territory</label>
+<select class="form-select" id="territory">
+	<option value="" selected disabled>Choose a territory</option>
+	<option value="emea">EMEA</option>
+</select>
+```
+
+**Alternates.** Drop to a radio group when the whole list fits in view and the options deserve
+comparison. Move up to a searched list when the person can name the value faster than they can find
+it, or when the list outgrows one scroll of the menu.
+
+**States.** The fixed set, plus `empty` when the option list itself is empty — say why, and offer
+the action that fills it. A locked select is `disabled`, so its value stops submitting; carry it in a
+hidden input. A select whose options are loading is `busy`.
+
+### One of many with an unlisted value admitted
+
+**Default.** An `input.form-control` bound to a `<datalist>`, at rung 1. The list suggests; the
+person can still submit a value it does not hold.
+
+```html
+<label for="carrier" class="form-label">Carrier</label>
+<input class="form-control" list="carrier-options" id="carrier" />
+<datalist id="carrier-options">
+	<option value="Northwind Freight"></option>
+</datalist>
+```
+
+**Alternates.** A combobox with free text is a hand-roll; take it only when the suggestions must be
+fetched as the person types.
+
+**States.** The fixed set. Attaching `list` changes the control's computed role to `combobox`, so
+re-target every test and journey that finds this field by role.
+
+### Any of a few
+
+**Default.** `fieldset` and `legend` around `.form-check` checkbox rows sharing one name, at rung 1.
+
+```html
+<fieldset>
+	<legend class="form-label">Notify me about</legend>
+	<div class="form-check">
+		<input class="form-check-input" type="checkbox" name="notify" id="notify-billing" />
+		<label class="form-check-label" for="notify-billing">Billing</label>
+	</div>
+</fieldset>
+```
+
+**Alternates.** Take `.form-check-inline` when the options are short words and the row has space.
+Bootstrap ships no `.form-check` color class, so an accent or danger box is an authored rule over
+tokens — take it only under the exception in [inspection.md](inspection.md) → When an authored rule
+is already earned.
+
+**States.** The fixed set, plus `empty` and `full`. State a minimum or a maximum count in the help
+text and validate it on the group.
+
+### Any of many
+
+**Default.** A bounded, scrollable list of `.form-check` rows inside a bordered box, at rung 2, with
+a filter field preceding it so the person can narrow the list before choosing.
+
+```html
+<label for="regions-filter" class="form-label">Regions</label>
+<input type="search" class="form-control form-control-sm mb-2" id="regions-filter" />
+<div class="border rounded overflow-auto p-2 mh-100" role="group" aria-label="Regions">
+	<div class="form-check">
+		<input class="form-check-input" type="checkbox" name="regions" id="region-emea" />
+		<label class="form-check-label" for="region-emea">EMEA</label>
+	</div>
+</div>
+```
+
+**Alternates.** Take `select[multiple].form-select` where the platform control is acceptable to the
+audience; its multi-select gesture is unteachable in a consumer flow but familiar in an internal
+tool. A tags input is the ordered-set category. Bound the box's height from the layout that holds
+it — Bootstrap ships `mh-100` and no other maximum-height step — never from a `style` attribute.
+
+**States.** The fixed set, plus `empty` and `full`. Show the chosen count beside the list and give a
+one-action way to clear it.
+
+### A value picked from a searched list
+
+**Default.** A combobox composed from shipped classes at rung 2, with the keyboard model
+hand-rolled against the APG combobox pattern: an `input.form-control` carrying `role="combobox"`,
+`aria-expanded`, `aria-controls`, `aria-autocomplete="list"`, and `aria-activedescendant`, over a
+`ul.dropdown-menu[role=listbox]` of `.dropdown-item` buttons.
+
+```html
+<div class="input-group">
+	<input
+		class="form-control"
+		type="text"
+		role="combobox"
+		aria-expanded="false"
+		aria-controls="owner-listbox"
+		aria-autocomplete="list"
+		id="owner"
+	/>
+	<button type="button" class="btn btn-outline-secondary" aria-label="Clear">Clear</button>
+</div>
+<ul class="dropdown-menu show w-100 shadow" id="owner-listbox" role="listbox">
+	<li><button type="button" class="dropdown-item" role="option">Northwind Freight</button></li>
+</ul>
+```
+
+**Alternates.** Take the datalist in [One of many with an unlisted value
+admitted](#one-of-many-with-an-unlisted-value-admitted) when the suggestions are static and short,
+and pay for the combobox only when the list is fetched, ranked, or long enough to need one.
+
+**States.** The fixed set, plus `empty` for a search that matched nothing — draw that with
+`.dropdown-item-text`, never with an empty menu. The menu is `busy` while a query is in flight, and
+the input stays operable throughout.
+
+### Files
+
+**Default.** An `input[type=file].form-control`, at rung 1.
+
+```html
+<label for="statement" class="form-label">Statement</label>
+<input class="form-control" type="file" id="statement" accept=".csv" />
+```
+
+**Alternates.** Drive a hidden input from a button, a card, or a dropzone when the surface wants a
+larger target; keep that input in the markup as the non-drag path, because a drag-only upload
+strands keyboard and assistive-technology users. Dropzone chrome is an authored class contract over
+tokens, and it owes a visible focus state of its own.
+
+**States.** The fixed set, plus `empty` and `full`. Name the accepted types and the size cap in the
+help text before the person picks, and report a rejected file beside the input rather than in a
+toast.
+
+### An ordered set of tags
+
+**Default.** Bootstrap ships no tags input. Compose one at rung 2 from a text field that commits on
+Enter plus a row of chips, each chip a `.badge` carrying a `btn-close` with its own accessible name.
+
+```html
+<label for="tag-entry" class="form-label">Tags</label>
+<input class="form-control" type="text" id="tag-entry" aria-describedby="tag-entry-help" />
+<div id="tag-entry-help" class="form-text">Press Enter to add a tag.</div>
+<ul class="list-unstyled d-flex flex-wrap gap-2 mt-2">
+	<li>
+		<span class="badge text-bg-secondary d-inline-flex align-items-center gap-1">
+			Priority
+			<button
+				type="button"
+				class="btn-close"
+				data-bs-theme="dark"
+				aria-label="Remove Priority"
+			></button>
+		</span>
+	</li>
+</ul>
+```
+
+**Alternates.** Where the tags come from a fixed vocabulary, this is the any-of-many category and the
+list is the better control. Where order carries meaning, give the reorder a non-drag path — a move
+control per chip.
+
+**States.** The fixed set, plus `empty` and `full`. Announce an added or removed tag in a
+`role="status"` region, because the chip row is far from the field that changed it.
+
+### A rating
+
+**Default.** Bootstrap ships no rating. Draw the interactive form as a radio group at rung 2 — one
+radio per value, restyled through `.btn-check` — so the keyboard model, the name, and the submitted
+value come from the platform. Star chrome over that structure is an authored class contract at
+rung 4.
+
+```html
+<fieldset>
+	<legend class="form-label">Rating</legend>
+	<div class="btn-group" role="radiogroup">
+		<input type="radio" class="btn-check" name="rating" id="rating-1" />
+		<label class="btn btn-outline-primary" for="rating-1">1</label>
+	</div>
+</fieldset>
+```
+
+**Alternates.** Draw a read-only rating as a glyph row with one accessible name stating the value,
+per [components.md](components.md) → Status glyph marks; it is not a control. Treat a
+`role="slider"` rating as a hand-roll owing the APG slider contract, including its keyboard model.
+
+**States.** The fixed set. Keep a cleared rating reachable, and say what cleared means.
+
+### A step in a sequence
+
+**Default.** Draw a step indicator from shipped parts at rung 1 — a `nav` or `.list-group-numbered`
+whose current item carries `aria-current="step"`, with a `.progress` bar over a long sequence. A step
+indicator reports where the person is and holds no value, so it is not a field.
+
+```html
+<nav aria-label="Application progress">
+	<ol class="list-group list-group-numbered list-group-horizontal">
+		<li class="list-group-item" aria-current="step">Details</li>
+		<li class="list-group-item">Review</li>
+	</ol>
+</nav>
+```
+
+**Alternates.** Treat custom stepper chrome — connectors, dots, tick marks — as an authored class
+contract over tokens. Take the rules for the sequence itself, including validation on leaving a step
+and where the answers are held, from [bootstrap-reference.md](bootstrap-reference.md) → Wizards &
+multi-step forms.
+
+**States.** The fixed set, drawn on the controls that move between steps. The indicator holds no
+value and is not a field, so it carries its own set instead: `rest` and a current mark that survives
+every theme the surface ships. Never make position the only signal that a step failed.
+
+## Where Bootstrap ships no component
+
+Work the native-first ladder in [bootstrap-reference.md](bootstrap-reference.md) → When not to
+hand-roll before building any category in this table, and take the hand-roll only with the named
+pattern's contract in hand. Settle each row as a build-or-buy decision before it is a markup
+decision. Take the contracts for dialog, combobox, radio group, and toolbar from
+[bootstrap-reference.md](bootstrap-reference.md) → Pattern contracts.
+
+| Category                    | Pattern the hand-roll owes             |
+| --------------------------- | -------------------------------------- |
+| A date, as a calendar grid  | APG dialog plus a grid keyboard model  |
+| A time, as segmented fields | APG spinbutton, per segment            |
+| A searched list             | APG combobox                           |
+| An ordered set of tags      | APG combobox plus removable buttons    |
+| A rating, as one control    | APG slider                             |
+| A two-thumb range           | APG slider, multi-thumb                |
+| A files dropzone            | The visible input as the non-drag path |
+| A data grid or a tree       | APG grid, APG tree view                |
+
+Take skeletons from [components.md](components.md) → Placeholder (skeletons) instead; Bootstrap
+ships them, so they stay out of this table.

package/dist/host/agents/skills/enterprise-bootstrap/references/inspection.md

@@ -0,0 +1,167 @@
+# Instruments
+
+Reach for an instrument here where a capture cannot settle the claim. Run every one with its negative
+control, in the same conditions, on the real compiled cascade the page loads. Treat an instrument
+whose negative control passes as broken and refuse its reading as evidence;
+`.claude/rules/quality.md` owns that law where it is present.
+
+Take each entry's property, population, reading, negative control, and coverage as written, and hold
+every entry to these rules.
+
+- **Report the population.** A reading carries the population it walked. An empty population fails
+  the run, because an extractor that quietly matched nothing satisfies every other assertion.
+- **Draw every negative control from outside the population.** Name the membership rule first, then
+  pick a negative control the rule excludes. Reject a negative control that rule admits.
+- **Enter a negative control through the same door the surface enters.** A negative control handed
+  straight to the reading tests the reading alone, so pair it with one appended to the tree, the stylesheet,
+  or the registry the instrument walks wherever the instrument has an extraction step.
+
+## Contents
+
+- [Authored class in the shipped cascade](#authored-class-in-the-shipped-cascade)
+- [Declared class combinations](#declared-class-combinations)
+- [Style escapes](#style-escapes)
+- [Token discipline](#token-discipline)
+- [Custom rule doing a utility's job](#custom-rule-doing-a-utilitys-job)
+- [Composited contrast in both themes](#composited-contrast-in-both-themes)
+- [One glyph, one meaning](#one-glyph-one-meaning)
+- [When an authored rule is already earned](#when-an-authored-rule-is-already-earned)
+
+## Authored class in the shipped cascade
+
+- **Property.** Every class token the surface's own templates and components author has a rule in
+  the compiled CSS the page loads.
+- **Population.** The class tokens the authored markup carries, read against every stylesheet the
+  page loads: the vendor build, each skin, and the project's own.
+- **Reading.** Subtract the tokens the loaded stylesheets define from the tokens the markup carries.
+  A remainder fails the run and names each token with the file that authored it. Report the token
+  population walked, and fail a run that walked none.
+- **Negative control.** A fed control and an appended control, each of which the reading must report.
+  Feed the first — a token no stylesheet defines — straight to the reading. Append the second through
+  the extraction door: an element built in the harness carrying that undefined token on an SVG
+  `class` attribute, added to the tree the reading walks. Each sits outside the population, which is
+  authored tokens the cascade resolves.
+- **Coverage.** The fed negative control covers the subtraction. The appended negative control covers the extractor,
+  and it is what fails a reading that never leaves the root or that drops SVG tokens by reaching for
+  `className`, where the value is an `SVGAnimatedString` rather than a string. Together they prove
+  authored tokens are a subset of the cascade. The instrument says nothing about a cascade rule
+  nobody authored, a token a build step or a script adds after the read, or whether a resolved rule
+  paints what the author intended.
+
+## Declared class combinations
+
+- **Property.** Every multi-utility chrome string the surface reuses is declared once by name with
+  the invariant it holds, and the markup carries no undeclared combination.
+- **Population.** The declared combinations, each with its name and its invariant, and every
+  multi-utility string the authored markup carries.
+- **Reading.** Match each string in the markup against the declared set. An undeclared combination
+  fails and names the element that carries it.
+- **Negative control.** A fed control and an appended control, each of which the reading must refuse.
+  Feed the first — a string one utility away from a declared combination — straight to the reading.
+  Append the second through the extraction door: an element built in the harness carrying that same
+  undeclared string on an SVG `class` attribute, added to the tree the reading walks. Each sits
+  outside the declared set.
+- **Coverage.** The fed negative control covers the match against the declared set. The appended negative
+  control covers the extractor, and it is what fails a reading that never leaves the root or that drops SVG
+  tokens by reaching for `className`. Together they prove reused chrome is declared. The instrument
+  does not prove a declared invariant is true, and it does not read a single utility used alone.
+- **Never substitute a cancellation heuristic.** A rule that flags a string for its utility count, or
+  for mixing categories, refuses the legitimate transparent read chrome that keeps a read view and an
+  edit view from reflowing.
+
+## Style escapes
+
+- **Property.** The surface's own markup carries no `style` attribute and no `<style>` element.
+- **Population.** The elements of a freshly mounted, undriven tree — the surface as authored, before
+  any interaction drives it.
+- **Reading.** Collect every element carrying an inline declaration or an embedded style element and
+  report it with its markup. Any hit fails.
+- **Exemptions, declared by name.** Exempt the framework's own runtime styles and name each exemption
+  in the instrument: a Bootstrap Modal, Offcanvas, Collapse, or Dropdown writes inline styles as it
+  runs, and a conditional-visibility directive such as `v-show` emits `style="display: none"` at
+  mount. Run the reading on an undriven tree, because a reading taken after a journey drives the
+  surface reports on the framework rather than on the author.
+- **Negative control.** An element carrying an inline declaration, built in the harness rather
+  than taken from the surface, fed to the reading. It sits outside the surface's own markup and the
+  reading must report it.
+- **Coverage.** The instrument reads authored markup at mount. It does not see a style a component
+  writes after the person interacts, a rule authored in a stylesheet, or an escape inside a
+  third-party component's own markup.
+
+## Token discipline
+
+- **Property.** No authored rule carries a literal color, and every custom paint resolves through a
+  token in each color mode the product ships.
+- **Population.** The project's own authored stylesheet rules, and the resolved value of each
+  custom-painted property in each color mode.
+- **Reading.** A literal color in an authored declaration fails. For each custom paint, read the
+  resolved value once per mode; a mode that leaves it unresolved fails, and so does a pair of modes
+  that resolve it identically where the design says the modes differ.
+- **Negative control.** A rule carrying a literal color, and a paint whose token the cascade does
+  not define, both fed to the reading rather than authored into the surface. Each sits outside the
+  population of authored rules that pass, and the reading must report both.
+- **Coverage.** The instrument covers authored rules and the paints it was given. It does not judge
+  whether the chosen token is the right one, and it reads no vendor rule and no inline declaration —
+  [Style escapes](#style-escapes) covers those.
+
+## Custom rule doing a utility's job
+
+- **Property.** Every authored selector expresses something no shipped utility expresses, or records
+  the reason the utility does not fit.
+- **Population.** The selectors in the project's own stylesheets.
+- **Reading.** For each selector, name the utility that would carry the same declarations. A selector
+  a shipped utility already expresses fails unless it carries the recorded reason.
+- **Negative control.** A rule restating a shipped utility exactly — a padding declaration matching
+  a spacing step — fed to the reading rather than authored into the stylesheet. It sits outside the
+  set of authored selectors that pass, and the reading must report it.
+- **Coverage.** The instrument reads declarations, not intent. A rule that does a utility's job
+  alongside something else passes it, so a person still reads the authored stylesheet.
+
+## Composited contrast in both themes
+
+- **Property.** Every pairing the surface paints meets its bar in every theme: 4.5:1 for anything
+  information-bearing, 3:1 for textless marks and the chrome that carries state.
+- **Population.** The pairings the surface renders, read per theme on the compiled cascade, with
+  every translucent layer composited. Exempt disabled controls, per [SKILL.md](../SKILL.md) →
+  Surfaces, color, contrast.
+- **Reading.** Composite the painted layers, read the ratio, and fail anything under its bar with the
+  pairing named. Take the mechanics from [bootstrap-reference.md](bootstrap-reference.md) → Measuring
+  the bars.
+- **Negative control.** An opaque pairing and a translucent stack, each of which the reading must
+  fail. Compose the opaque pairing in the harness at a ratio known to sit under the bar. Compose the
+  stack with a translucent layer over a floor, so its composited ratio sits under the bar while its
+  top layer read alone sits above it. Each is composed in the harness rather than taken from the
+  surface, so each sits outside the rendered population.
+- **Coverage.** The opaque pairing covers the ratio arithmetic. The translucent stack covers the
+  compositing step, and it is what fails a reader that takes the top layer's declared color and skips
+  the layers under it. Together they measure what rendered, in the themes and viewports the run
+  entered. A pairing that appears only in a state the run never reached is unmeasured, so name the
+  states the run covered beside the result.
+
+## One glyph, one meaning
+
+- **Property.** Each status meaning takes one glyph, each glyph serves one meaning, and every
+  registered glyph resolves in the icon set the product actually ships.
+- **Population.** The registry of meanings and glyphs the surface uses, and the shipped icon set.
+- **Reading.** A meaning registered twice, a glyph registered against two meanings, or a glyph the
+  shipped set does not resolve fails, each named.
+- **Negative control.** A registry entry binding a second meaning to a glyph already registered,
+  plus a glyph name the shipped set lacks. Both sit outside the registered set, and the reading must
+  report both.
+- **Coverage.** The instrument proves the registry is consistent and resolvable. It does not prove
+  the markup draws the registered glyph for the meaning it carries, so pair it with a capture of the
+  states that use marks.
+
+## When an authored rule is already earned
+
+Leave rung 4 to the developer, per [SKILL.md](../SKILL.md) → When custom CSS is justified. Write an
+authored rule without asking only when every one of these holds:
+
+- an instrument here reports the vendor cascade failing a stated bar — the focus ring under 3:1, the
+  status text under 4.5:1, the shipped component with no class for the state the surface must
+  show;
+- the rule cites that reading beside it, naming the instrument, the bar, and the value read;
+- the rule restores the bar and does nothing else;
+- the rule is written over `--bs-*` tokens, so both color modes move with the theme.
+
+Treat anything wider as a proposal: name what the rule would buy, and stop.