@orkestrel/scaffold 0.0.65 → 0.0.67

package/dist/host/agents/skills/enterprise-bootstrap/SKILL.md

@@ -33,7 +33,7 @@ hand-roll before building one.
 
 | Layer          | File                                                        | Holds                                                              |
 | -------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
-| Operate        | `SKILL.md`                                                  | Process, decision rules, checklist                                 |
+| Operate        | `SKILL.md`                                                  | Process, styling ladder, contrast bars, action rank, checklist     |
 | Design craft   | [frontend-design.md](references/frontend-design.md)         | Hierarchy, spacing, type, color, depth, imagery, signature, copy   |
 | Components     | [components.md](references/components.md)                   | Bootstrap markup and enterprise selection notes                    |
 | Inputs         | [inputs.md](references/inputs.md)                           | Affordance, alternates, styling rung, and states per category      |
@@ -44,8 +44,9 @@ hand-roll before building one.
 | Instruments    | [inspection.md](references/inspection.md)                   | Mechanical evidence contracts and rendered review criteria         |
 
 Take the operating rules here over a lookup example. Adapt example heading levels, action rank,
-labels, and paint to the host surface. Move illustrative inline declarations through the styling
-ladder before shipping; their presence in a lookup is not an exemption.
+labels, and paint to the host surface. Move an illustrative inline declaration through the styling
+ladder before shipping; its presence in a lookup is not an exemption. A declaration a lookup names
+as a runtime producer is the exception, and only for the property that lookup names.
 
 ---
 
@@ -57,7 +58,7 @@ ladder before shipping; their presence in a lookup is not an exemption.
 4. **Write framework-neutral markup** — semantic HTML plus Bootstrap classes. Wire behavior with the project's stack; in an SPA prefer framework-native Bootstrap wrappers over competing DOM ownership ([bootstrap-reference.md](references/bootstrap-reference.md) → JavaScript lifecycle).
 5. **Keep this folder intact** so its relative links resolve. Install or vendor it wherever the tooling looks for skills; the paths are tooling-specific, the content is not.
 6. **Use the installed Bootstrap.** Otherwise take the pinned CDN example from [bootstrap-reference.md](references/bootstrap-reference.md) → Quick start. Do not upgrade dependencies as a side effect of a visual pass.
-7. **Apply this package** to the work in its frontmatter. For a requested verdict, round, or campaign over an already rendering surface, use `orkestrel-polish-surface`; use this skill for the campaign's Bootstrap fixes.
+7. **Apply this skill** to the work in its frontmatter. For a requested verdict, round, or campaign over an already rendering surface, use `orkestrel-polish-surface`; use this skill for the campaign's Bootstrap fixes.
 
 ---
 
@@ -78,10 +79,10 @@ Read [frontend-design.md](references/frontend-design.md) before setting a direct
 visual decisions; the loop here owns their order.
 
 1. **Ground** — state the subject, audience, single job, primary action, and existing constraints. Use real content; mark fixture data as such. Start with a feature, not a navigation shell.
-2. **Plan** — record each region's narrow layout, expansion threshold, content/action parity, and overflow policy in a responsive contract. Render the primary task at 320 and 390 CSS px before expanding the shell. Settle reading order and grouping in low fidelity before paint, and hold color until the arrangement reads in grayscale (body surfaces, inherited text, weight, and spacing only). Reuse or define a compact system: **color families and surface ownership**, **type roles and scale**, **spacing and width roles**, **radius and elevation**, **a coherent signature where the brief calls for one**. Set personality once through four levers — typeface, primary color, radius family, copy register — and hold it on every screen. Record changes, not a parallel system. Take each scale's Bootstrap source, shipped steps, and gaps from [bootstrap-reference.md](references/bootstrap-reference.md) → Define the working scales.
+2. **Plan** — record each region's narrow layout, expansion threshold, content/action parity, and overflow policy in a responsive contract. Render the primary task at 320 and 390 CSS px before expanding the shell. Settle reading order and grouping in low fidelity before paint, and hold color until the arrangement reads in grayscale (body surfaces, inherited text, weight, and spacing only). Reuse or define a compact system: **color families and surface ownership**, **type roles and scale**, **spacing and width roles**, **radius and elevation**, **a coherent signature where the brief calls for one**. Set personality through these levers — typeface, primary color, radius family, and copy register — and hold each on every screen. Record changes, not a parallel system. Take each scale's Bootstrap source, shipped steps, and gaps from [bootstrap-reference.md](references/bootstrap-reference.md) → Define the working scales. State the settled layout in prose or a small wireframe before building it.
 3. **Critique the plan** — reject unclear hierarchy, invented functionality, and interchangeable styling. Follow a pinned brief; otherwise take character from the subject rather than clustered AI defaults. Do not manufacture novelty inside an established product.
-4. **Build** — implement the smallest useful flow and its data states, then refine the working feature. Use documented components and shipped utilities; map shared tokens once. Fix conflicting declarations rather than adding specificity. Extend the next feature after this one works.
-5. **Critique the render** — complete the primary flow at narrow width first; then read task, hierarchy, grouping, type, contrast, states, and signature in order. Fix the earliest failure first. Remove a needless accessory if one exists; never remove useful information to meet a quota.
+4. **Build** — implement the smallest useful flow and its data states, then refine the working feature. Use documented components and shipped utilities; map shared tokens once. Fix conflicting declarations rather than adding specificity. Revise the recorded plan when the render disproves it. Extend the next feature after this one works.
+5. **Critique the render** — complete the primary flow at narrow width first; then read task, hierarchy, grouping, type, contrast, states, and signature in order. Fix the earliest failure first, then re-read the earlier criteria against the fixed render. Remove a needless accessory if one exists; never remove useful information to meet a quota.
 
 Keep exploratory drafts private. Deliver the selected direction, the changes, and their evidence
 limits, not every discarded variation.
@@ -90,7 +91,7 @@ limits, not every discarded variation.
 snapshot. Use captures for visual claims and source to explain mechanisms; use interaction tests
 for behavior. `.agents/orchestration.md` owns this law where present. Name the coverage and any
 unverified state. Without a render-capable environment, report visual verification as open, never
-as passed. Route a requested review campaign to `orkestrel-polish-surface`.
+as passed.
 
 **Mechanical proof.** Run applicable instruments in [inspection.md](references/inspection.md) with
 their negative controls. Report population, reading, control result, and coverage. A control the
@@ -112,27 +113,41 @@ and captures are evidence, not fabricated mechanical tests or a beauty score.
 
 ### The styling ladder
 
-Reach a rung only when the preceding one cannot express the need.
+Reach a rung only when the preceding one cannot express the need. Cite a rung by its name, never by
+its position.
 
-1. **Documented component structure.** Keep required elements, nesting, modifiers, behavior, and ARIA. Use optional headers, titles, and footers only when the content needs them; a component example is not a mandate to add empty chrome.
-2. **Shipped utilities.** Compose spacing, flex, sizing, text, border, and color classes from [utilities.md](references/utilities.md). Verify extensions exist in the loaded build before authoring them.
-3. **Bootstrap extension points.** Use component `--bs-{component}-*` variables or the Sass utilities API for a recurring system gap. Declare the role once, compile where required, and verify the emitted rule.
-4. **Developer-authorized custom CSS.** Propose what Bootstrap cannot express and why. Take this rung unasked only under [inspection.md](references/inspection.md) → When an authored rule is already earned.
+1. **Component rung — documented component structure.** Keep required elements, nesting, modifiers, behavior, and ARIA. Use optional headers, titles, and footers only when the content needs them; a component example is not a mandate to add empty chrome.
+2. **Utility rung — shipped utilities.** Compose spacing, flex, sizing, text, border, and color classes from [utilities.md](references/utilities.md). Verify extensions exist in the loaded build before authoring them.
+3. **Extension rung — Bootstrap extension points.** Use component `--bs-{component}-*` variables or the Sass utilities API for a recurring system gap. Declare the role once, compile where required, and verify the emitted rule.
+4. **Authored rung — developer-authorized custom CSS.** Propose what Bootstrap cannot express and why. Take this rung unasked only under [inspection.md](references/inspection.md) → When an authored rule is already earned.
 
-Keep authored styles in the project's stylesheet and token layer, never a `style` attribute or a
-page/component `<style>` block. Do not duplicate a shipped utility. Keep raw values in declared
-primitive definitions, not component paint. These are package boundaries, not claims that inline
-CSS or custom rules cannot participate in a cascade.
+Resolve a conflict at the rung that owns it. Utilities may carry `!important`, so read the winning
+declaration in the shipped cascade and remove the conflicting class before escalating selector
+specificity. A class selector stays a class selector whatever its name.
+
+**Where an authored rule lives.** Put every authored rule in the project's stylesheet and token
+layer. A standalone HTML deliverable carries that stylesheet as one `<style>` block in `<head>` —
+tokens and declared roles, before any markup. That block is the project stylesheet.
+
+Never write a `style` attribute on authored markup, and never open a second `<style>` block beside
+a component or scoped to one. This rule fixes a location and nothing else: inline CSS and authored
+rules participate in the cascade normally, and a runtime producer named in
+[inspection.md](references/inspection.md) → Style escapes writes its own declaration.
+
+**What an authored rule may contain** is a separate rule, and the styling ladder owns it. Reach the
+authored rung only when the component, utility, and extension rungs cannot express the need. Do not
+duplicate a shipped utility, and keep raw values in declared primitive definitions rather than in
+component paint.
 
 ### Hierarchy & actions
 
-| Rank or meaning | Typical choice                                                         |
-| --------------- | ---------------------------------------------------------------------- |
-| Primary         | `btn btn-primary` — at most one dominant action per active task region |
-| Secondary       | A quieter neutral or outline variant, measured on its actual surface   |
-| Tertiary        | `btn btn-link` for an action; a real link for navigation               |
-| Destructive     | Rank first; strong `btn-danger` for the final destructive commit       |
-| Status          | Quiet badge or alert treatment; icon + color + word                    |
+| Rank or meaning | Typical choice                                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Primary         | `btn btn-primary` — at most one dominant action per active task region                                                                                             |
+| Secondary       | `btn-outline-secondary` with `--bs-btn-color: var(--bs-emphasis-color)` set once at the theme root (the stock label is 3.3:1 on the dark body), or `btn-secondary` |
+| Tertiary        | `btn btn-link` for an action; a real link for navigation                                                                                                           |
+| Destructive     | Rank first; strong `btn-danger` for the final destructive commit                                                                                                   |
+| Status          | Quiet badge or alert treatment; icon + color + word                                                                                                                |
 
 Choose rank before hue. Do not make every action solid or every destructive action dominant.
 Outline and link-style controls are allowed only when their text, boundary or state cue, and focus
@@ -146,9 +161,11 @@ not lower the required friction. Draw a textless status mark as an icon glyph, n
 
 ### Surfaces, color, contrast
 
-- **Hold the package bars:** ≥ 4.5:1 for all information-bearing text, including large text, captions, and metadata; ≥ 3:1 for meaningful textless marks and state/focus chrome. The text floor is deliberately stricter than WCAG's large-text exception. Measure every declared theme and reached state; do not generalize one reading to all surfaces.
+- **Hold these bars — this section owns them.** ≥ 4.5:1 for all information-bearing text, including large text, captions, and metadata; ≥ 3:1 for meaningful textless marks and state/focus chrome. The text floor is deliberately stricter than WCAG's large-text exception. Measure every declared theme and reached state; do not generalize one reading to all surfaces. A ratio quoted anywhere in this skill is a stock Bootstrap reading and bounds that stock theme alone — the bars are the policy, the readings are not.
 - **Inherit ordinary text.** When content owns no background, add no foreground override. Prefer `bg-body`, `bg-body-secondary`, `bg-body-tertiary`, and `bg-*-subtle` for quiet surfaces; do not automatically add a text-color utility to them. Follow [color-modes.md](references/color-modes.md) for exceptions and component-owned colors.
-- **Keep supporting text readable.** Start with inherited color, spacing, and weight. Use `text-body-secondary` for a deliberate secondary tier — it clears 4.5:1 on every stock body surface in both modes — not for every caption. `text-body-tertiary` is body color at 50 % alpha and measures 3.0–4.1:1 on those surfaces: decoration or disabled only, never a caption someone reads. A third readable tier is a declared opaque token. Never quiet text with opacity, and do not carry a neutral secondary tier blindly onto a colored fill; inherit its tested foreground first, using a scoped opaque same-hue tier only when needed ([color-modes.md](references/color-modes.md) → Text tiers).
+- **Pair like with like.** Adaptive text on adaptive surfaces (`text-body*` and `text-*-emphasis` on `bg-body*` and `bg-*-subtle`); fixed text on fixed fills (`text-bg-*`, a component's own foreground, or a `data-bs-theme` scope that also carries `text-body` — a scope changes variables only, and plain text inherits the outer mode's painted color). Treat a mixed pair as unproven and measure it in each declared mode: `bg-light` with inherited text, `text-white` on `bg-body`, `text-primary` on the dark body, and a stock `btn-outline-secondary` label in dark mode each fail one stock mode, while inherited text on `bg-primary` fails light and dark alike. Replace `bg-light`, `bg-white`, and `text-dark` on adaptive surfaces because they are fixed ([color-modes.md](references/color-modes.md) → Fixed and adaptive classes).
+- **Clear a deprecated class on its deprecation, not on a contrast reading.** 5.3 deprecates `text-muted`, `navbar-light`, `navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, and `carousel-dark`. `text-muted` still resolves through the adaptive secondary color, so it pairs correctly and is a deprecation to clear; the `navbar-*`, `dropdown-menu-dark`, `btn-close-white`, and `carousel-dark` classes give way to a `data-bs-theme` scope.
+- **Keep supporting text readable.** Start with inherited color, spacing, and weight. Use `text-body-secondary` for a deliberate secondary tier — it clears 4.5:1 on every stock body surface in light and dark — not for every caption. `text-body-tertiary` is body color at 50 % alpha and measures 3.0–4.1:1 on those stock surfaces: decoration or disabled only, never a caption someone reads. Any further readable tier is a declared opaque token, measured on the surface it sits on. Never quiet text with opacity, and do not carry a neutral secondary tier blindly onto a colored fill; inherit its tested foreground first, using a scoped opaque same-hue tier only when needed ([color-modes.md](references/color-modes.md) → Text tiers).
 - **Pair intentional solid surfaces; preserve selected foregrounds.** Let the owning component set its foreground and background, or use a tested solid pair. Do not recolor ordinary children. Keep status encoded by icon and word and capture the selected state.
 - **Inside subtle fills, measure the children against that fill.** Badge, button, and caption recipes need their own readings; a page-background result does not transfer into a card or alert.
 - **Exempt disabled controls from the contrast bars**, but visibly neutralize an unavailable destructive action and explain why with `aria-describedby`; `title` may supplement, never replace, the explanation.
@@ -161,7 +178,7 @@ Take [responsive-layout.md](references/responsive-layout.md) as the layout contr
 primary task, reading order, and access to information at every width. A contained horizontal
 table can pass document-overflow checks and still fail the task; inspect both.
 
-- Choose density for the task. Start each gap one step too large, render, and step down; compress where throughput or comparison requires it, not because the default felt cramped. Keep targets ≥ 24×24 CSS px as the package floor; measure hit areas, never infer them from `btn-sm`.
+- Choose density for the task. Start each gap one step too large, render, and step down; compress where throughput or comparison requires it, not because the default felt cramped. Hold every target to the floor in [bootstrap-reference.md](references/bootstrap-reference.md) → WCAG 2.2 requirements for app UI, which owns the target dimensions.
 - Take compact controls together across a row: `btn-sm`, `form-control-sm`, `form-select-sm`, and `input-group-sm`. Do not shrink body text or targets to force one-row layouts.
 - Keep inter-group gaps larger than internal gaps. Bound forms, rails, and prose by content with a maximum width; let comparison tables use the width they need. Use percentage columns only where elements must scale together — a `col-*` login card or `col-3` sidebar changes width at every breakpoint ([bootstrap-reference.md](references/bootstrap-reference.md) → Breakpoints & layout).
 - Use `.card` where an independent group earns containment. Try spacing and type before more borders, fills, or shadows. Keep elevation tied to layering, not every available box.
@@ -181,18 +198,19 @@ table can pass document-overflow checks and still fail the task; inspect both.
 - Choose the affordance by what the person is asked for in [inputs.md](references/inputs.md), and draw its fixed state set. Keep read-only/edit geometry stable and preserve the non-drag path for uploads.
 - Give every field a visible label or `.form-floating`, never placeholder-only. Removing redundant labels on displayed data does not apply to inputs. Naming a form does not name its individual controls.
 - Keep label, control, help, and error closer to each other than to the next field group. Use extra columns for genuinely related fields or supporting explanation, not to fill a wide canvas.
-- Validate on blur, re-validate error fields on input, and re-check on submit. Keep submit enabled; never disable it merely because fields are invalid. Show a focusable error summary and linked inline feedback (`aria-describedby`, `aria-invalid`).
+- Validate on blur, re-validate error fields on input, and re-check on submit. Keep submit enabled while fields are invalid; a disabled submit hides what is wrong. While a submit is in flight, mark the control busy and refuse a second submit — that pending block is a different state, and this rule does not bar it. Show a focusable error summary and linked inline feedback (`aria-describedby`, `aria-invalid`).
 - Take validation mechanics, autosave, and multi-step rules from [bootstrap-reference.md](references/bootstrap-reference.md) → Forms in production, Wizards & multi-step forms.
 
 ### When custom CSS is justified
 
-Exhaust rungs 1–3 before proposing a custom rule. Name the unmet requirement and the smallest rule
-that would satisfy it. A desire for a signature does not waive the styling ladder.
+Exhaust the component, utility, and extension rungs before proposing a custom rule. Name the unmet
+requirement and the smallest rule that would satisfy it. A desire for a signature does not waive the
+styling ladder.
 
-Take a rule unasked only when an instrument in [inspection.md](references/inspection.md) proves a
-vendor failure, the rule cites that reading, restores the bar and nothing else, and uses theme
-tokens. Otherwise wait for developer authorization. An unavailable Sass build is not permission to
-silently invent a second CSS system.
+Wait for developer authorization. [inspection.md](references/inspection.md) → When an authored rule
+is already earned owns the one exception and every condition that opens it; read that section rather
+than judging a shorter copy here. An unavailable Sass build is not permission to silently invent a
+second CSS system.
 
 When authorized, or when that exception opens:
 
@@ -206,7 +224,7 @@ When authorized, or when that exception opens:
 ## Accessibility baseline
 
 - Give the page a skip link, landmarks, and ordered headings; visual size does not dictate heading level.
-- Name icon-only controls and keep targets ≥ 24×24 CSS px. Preserve visible labels within accessible names.
+- Name icon-only controls and hold every target to the floor in [bootstrap-reference.md](references/bootstrap-reference.md) → WCAG 2.2 requirements for app UI. Preserve visible labels within accessible names.
 - Use `aria-current` for the current navigation item, `aria-selected` for selectable tabs, and native checked state for checkboxes/radios. Do not apply one selection attribute to every widget.
 - Wire disclosures with `aria-expanded` and `aria-controls`; wire help/errors with `aria-describedby` and invalid fields with `aria-invalid`.
 - Match announcements to urgency: polite status for routine async results, alerts for urgent failures. Do not infer urgency solely from an alert's visual styling.
@@ -234,16 +252,18 @@ Progress:
 - [ ] Typeface, primary color, radius family, and copy register set once and held; arrangement read in grayscale before hue
 - [ ] Type sizes in `rem` from the scale or its generated steps; no `em` sizes, nested `.small`, or off-scale spacing
 - [ ] Components and utilities resolved in the shipped build; input affordances and states taken from their references
-- [ ] Styling ladder held; no authored inline styles, embedded style blocks, or unearned utility duplication
+- [ ] Styling ladder held; no `style` attribute, no component-scoped `<style>` block, no unearned utility duplication; a standalone HTML deliverable carries its one project stylesheet in `<head>`
 - [ ] Tokens mapped through semantics to components; literals confined to declared primitives
 - [ ] Ordinary/subtle content inherits; solid exceptions own their pair; no fixed leaf color conceals a mode failure
+- [ ] Every text/background pair is adaptive-on-adaptive or fixed-on-fixed; fixed fills carry `text-bg-*`, their component's foreground, or a `data-bs-theme` scope with `text-body` on the same element; no `bg-light`, `bg-white`, or `text-dark` on adaptive surfaces
+- [ ] Deprecated classes cleared on their deprecation: `text-muted`, `navbar-light`, `navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, `carousel-dark`
 - [ ] Secondary tier is `text-body-secondary` or a declared opaque token; no opacity or unreadable tertiary tone; secondary text on colored surfaces measured rather than assumed
-- [ ] Light/dark transitions, supported nested scopes, and overlay mounts tested without rebuilding the UI
+- [ ] Every declared mode transition, supported nested scopes, and overlay mounts tested without rebuilding the UI
 - [ ] Primary action clear; supporting content readable; destructive rank and friction both correct
 - [ ] Group spacing unambiguous; widths content-led; type/baseline/line length suitable
 - [ ] All data states built; first-use and filtered-empty distinct; errors recoverable; no invented progress
 - [ ] Images bounded and legible; depth serves layering; accents, tints, and shadows each earn their place; no needless accessories
-- [ ] Contrast measured in supported themes/states: ≥ 4.5:1 text, ≥ 3:1 meaningful marks and state/focus chrome
+- [ ] Contrast measured in every declared theme and reached state against the bars in § Surfaces, color, contrast
 - [ ] Keyboard, labels, announcements, targets, reduced motion, and non-drag paths checked
 - [ ] Forms retain visible labels, blur/submit validation, and summary + inline errors
 - [ ] Responsive contract recorded; primary task works at 320/390 CSS px before wide-screen enhancement

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

@@ -1,6 +1,6 @@
 # Bootstrap 5 Deep Reference — Theming, Forms, JS, Accessibility, Enterprise Patterns
 
-> Part of the `enterprise-bootstrap` package. Bootstrap **5.3.x**.
+> Part of the `enterprise-bootstrap` skill. Bootstrap **5.3.x**.
 > Component markup lookups: [components.md](components.md). Utility classes: [utilities.md](utilities.md).
 > This file holds what those do not: setup, color modes, theming/tokens, forms in
 > production, the JS lifecycle, accessibility depth, and enterprise app patterns.
@@ -49,6 +49,8 @@ Pinned CDN example (5.3.8). Prefer the installed compatible version; this is not
 
 ## Breakpoints & Layout
 
+Stock 5.3.8 values: breakpoints `sm` 576 · `md` 768 · `lg` 992 · `xl` 1200 · `xxl` 1400 px (`min-width`; `xs` has no infix); `.container` maxima 540 · 720 · 960 · 1140 · 1320 px; gutter and container padding 1.5 rem (296 px of content at 320 px). Only `d`, `flex`, `justify-content`, `align-*`, `order`, `float`, `gap`, spacing, text alignment, and `object-fit` utilities ship breakpoint infixes. Generate a missing responsive role only where a `$utilities` entry owns the property, per [Utilities API](#utilities-api). Full inventory and recipes: [responsive-layout.md](responsive-layout.md) → Bootstrap's responsive surface.
+
 Start with the feature's content and narrow layout, then choose its container and breakpoints.
 Take the region contract, content parity, and test matrix from [responsive-layout.md](responsive-layout.md).
 Use fluid columns for content that needs to scale together; keep rails, forms, and reading measures
@@ -143,7 +145,7 @@ states, and resolve aliases at the scope where they must change. Take the constr
 
 Reuse the installed theme and its scales first. Declare new values only for a role the feature
 needs; refine one shared definition instead of accumulating per-component exceptions. Every
-system below has a Bootstrap source, a utility, and a known gap; extend the source, never the
+system in the following table has a Bootstrap source, a utility, and a known gap; extend the source, never the
 markup.
 
 | System         | Sass source                                                 | Utility                                       | Stock steps (default root)                       | Gap                                                                              |
@@ -164,8 +166,8 @@ markup.
   dark text shades in real components, then fill the gaps. Use HSL when it helps tune related
   shades; keep the project's existing format. Review fixed shade pairs in each theme rather than
   generating a new `lighten`, `darken`, or `color-mix` result at each use site. Stock ramps and
-  triads are tint/shade mixes with a fixed hue; override the nine shade variables and six triad
-  variables per brand hue, and the nine greys as one temperature-matched set
+  triads are tint/shade mixes with a fixed hue; override the shade variables and triad
+  variables per brand hue, and the greys as one temperature-matched set
   ([color-modes.md](color-modes.md) → Extend the theme).
 - **Type:** display/body/utility roles, finite `rem` sizes, working weights, and line-height per
   role. Roles may share a font. RFS scales sizes above 1.25 rem down below a 1200 px viewport
@@ -175,7 +177,7 @@ markup.
 - **Space and size:** internal, group, panel, and section gaps; control sizes; reading/form widths;
   rail width. Start with Bootstrap's shipped scale. Add a missing step through the utilities API
   only where the adjacent steps cannot express the intended relationship. Button sizes already
-  scale padding faster than font (4/8 px at 14 px, 6/12 at 16, 8/16 at 20); use the three shipped
+  scale padding faster than font (4/8 px at 14 px, 6/12 at 16, 8/16 at 20); use the shipped
   sizes rather than deriving one with `em` padding.
 - **Radius and elevation:** a small consistent family, assigned to real component/layer roles.
   Set `$border-radius` once and let components inherit it; do not hand-mix `rounded-*` per
@@ -189,13 +191,13 @@ that boundary; [frontend-design.md](frontend-design.md) owns the visual choices.
 
 ### Elevation and depth
 
-Three shipped steps — `--bs-box-shadow-sm` (`0 .125rem .25rem` at .075), `--bs-box-shadow`
-(`0 .5rem 1rem` at .15), `--bs-box-shadow-lg` (`0 1rem 3rem` at .175) — plus
+Bootstrap ships `--bs-box-shadow-sm` (`0 .125rem .25rem` at .075), `--bs-box-shadow`
+(`0 .5rem 1rem` at .15), and `--bs-box-shadow-lg` (`0 1rem 3rem` at .175), plus
 `--bs-box-shadow-inset`. Assign by z-position: `sm` for raised cards and controls, base for
 floating menus and a dragged item, `lg` for dialogs. Stock dropdowns, popovers, toasts, and
 modals all sit on `--bs-box-shadow` (modal: `-sm` below 576 px), which puts a blocking dialog at
-dropdown elevation. Lift it at rung 3, in the project stylesheet after Bootstrap's so the rule
-wins the `sm`-up media rule:
+dropdown elevation. Lift it at the extension rung, in the project stylesheet after Bootstrap's so
+the rule wins the `sm`-up media rule:
 
 ```css
 .modal {
@@ -210,10 +212,10 @@ and every consumer follows.
 `$enable-shadows: true` (off by default) paints light-from-above on controls: buttons take
 `inset 0 1px 0 rgba(#fff, .15), 0 1px 1px rgba(#000, .075)` (lit top edge, tight cast shadow),
 inputs `inset 0 1px 2px rgba(#000, .075)` (recessed), and an active button `inset 0 3px 5px`
-(pressed). Enable it when the direction wants tactile controls, and verify both modes; the alphas
+(pressed). Enable it when the direction wants tactile controls, and verify every declared theme; the alphas
 are fixed white and black. Without the flag the `box-shadow` mixin emits nothing, so
-`--bs-btn-box-shadow` and `--bs-box-shadow-inset` have no consumer and a rung-3 override does
-nothing; the recipe is then a proposed rule.
+`--bs-btn-box-shadow` and `--bs-box-shadow-inset` have no consumer and an extension-rung override
+does nothing; the recipe is then a proposed rule.
 
 Flat depth: a `bg-body` panel on `bg-body-tertiary` reads raised and `bg-body-secondary` inside
 `bg-body` reads inset, both mode-adaptive with no shadow. A hard offset shadow is a `$box-shadow`
@@ -233,6 +235,8 @@ Then `rounded-circle border border-3 ring-body`.
 
 ### The CSS-variables-only path (no Sass build)
 
+When the deliverable is one self-contained HTML file, the project stylesheet is a single `<style>` block in `<head>` — tokens, declared role utilities, and extension-rung variable overrides, in that order — loaded after the Bootstrap `<link>` so equal-specificity rules win by source order. It is still one stylesheet: no `style` attribute on authored markup and no second `<style>` block beside a component ([SKILL.md](../SKILL.md) → The styling ladder owns that placement rule).
+
 Use native components and adaptive utilities before adding overrides. For a recurring component
 surface role, use its local variable rather than repainting the whole component. This optional
 project-defined class changes the card background without assigning a foreground:
@@ -302,10 +306,18 @@ $utilities: map-merge(
 
 Remove with `map-remove($utilities, "width")` or set the key to `null`. This is the sanctioned answer when the shipped scale is missing a step (for example, a `vh-50` the design truly needs).
 
+**`responsive: true` reaches a utility family and nothing else.** It adds breakpoint infixes to one
+entry in the `$utilities` map, so it generates `w-md-auto` from the `width` entry and `ls-lg-tight`
+from an added `letter-spacing` entry. A component threshold (`navbar-expand-*`, `offcanvas-*`,
+`table-responsive-*`, `modal-fullscreen-*-down`), a grid class, and a helper (`visually-hidden`,
+`stretched-link`, `ratio`, `vstack`) are not `$utilities` entries, so the key cannot reach them —
+change the component's own breakpoint class instead, and never write a responsive helper name the
+map cannot produce. Read the generated selector out of the compiled output before using it.
+
 ### Layout and type extensions
 
 These are **project-generated classes**, not stock Bootstrap utilities. Use the existing project
-roles when present. Otherwise add only the needed entries; the values below are illustrative role
+roles when present. Otherwise add only the needed entries; the values in the following block are illustrative role
 definitions, not universal sizes.
 
 Scale steps go in the map-override slot (after `variables-dark`, before `maps`). Keys `0`–`5`
@@ -393,7 +405,7 @@ Use `w-100 measure-form` for a bounded form, `measure-prose` for a reading colum
 sibling, `max-block-lg-table` only for a warranted wide-screen bounded table scroller, `figures-tabular` for comparable
 quantities, `ls-tight` on `display-*` and `fs-1`, and `ls-wide` with `text-uppercase` labels (`em`
 is correct for tracking: it follows the element's own size). Verify those selectors in the
-compiled output before using the examples below. The font must support tabular figures. A `ch`
+compiled output before using those classes. The font must support tabular figures. A `ch`
 measure is a starting width, not a character-count proof.
 
 Without a Sass build, take an existing equivalent; otherwise propose the smallest stylesheet rule
@@ -432,7 +444,8 @@ under [SKILL.md](../SKILL.md) → When custom CSS is justified. Never ship an un
 
 - Validate a field **on blur** — after the user leaves it — never on every keystroke, and never before the user has reached the field. Exception: live feedback that _helps_ while typing (password strength, username availability, character counts).
 - After a field enters an error state, re-validate as the user types so they see the fix land.
-- Always re-check everything on submit. Keep the submit button **enabled** — a disabled submit hides _what is_ wrong; a validating submit shows it.
+- Always re-check everything on submit. Keep the submit button **enabled** while fields are invalid — a disabled submit hides _what is_ wrong; a validating submit shows it.
+- **Separate invalid from pending.** While a submit is in flight, mark the button busy — `aria-busy="true"`, a `spinner-border spinner-border-sm` inside it, its label held so the geometry does not move — and refuse a second submit from the handler. Blocking a duplicate submit of a form that already validated is a pending state; the preceding rule bars only the disable that stands in for validation. Clear the busy state on both the resolved and the failed path, and put the failure in the error summary.
 - On failed submit of a long form, render an **error summary** at the top (focus it; link each item to its field) _and_ inline messages at each field — never summary-only, never inline-only.
 - Error style = color + icon + text, stating what is wrong and how to fix it. Wire message to field with `aria-describedby`, mark the field `aria-invalid="true"`. Never report errors through a hover tooltip.
 
@@ -522,7 +535,7 @@ el.addEventListener('hidden.bs.modal', () => {
 })
 ```
 
-- **Framework reality check:** Bootstrap's JS and a virtual-DOM framework both mutating the same nodes causes bugs (stuck dropdowns, ghost backdrops). In React/Vue/Angular apps, prefer the framework-native implementations (React Bootstrap, BootstrapVueNext, ng-bootstrap) which reuse Bootstrap's CSS but own the DOM. Use raw `bootstrap.*` JS in SPAs only for leaf widgets you fully control, and dispose them on unmount.
+- **In a virtual-DOM app, take the framework-native implementation** — React Bootstrap, BootstrapVueNext, ng-bootstrap — which reuses Bootstrap's CSS and owns the DOM. Use raw `bootstrap.*` JS there only for a leaf widget the component fully controls, and dispose it on unmount. Bootstrap's JS and the framework mutating the same nodes produces stuck dropdowns and ghost backdrops.
 
 ### Popper
 
@@ -541,26 +554,26 @@ Hold the baseline in [SKILL.md](../SKILL.md) → Accessibility baseline. Its Boo
 
 **Measuring the bars:**
 
-- Hold the bars from [SKILL.md](../SKILL.md) → Surfaces, color, contrast: **≥ 4.5:1** for everything information-bearing, **≥ 3:1** for textless marks and state chrome. WCAG 2.2 permits 3:1 for large text; this package does not — size grants no lower tier.
+- Hold the bars from [SKILL.md](../SKILL.md) → Surfaces, color, contrast, which owns them. WCAG 2.2 permits 3:1 for large text; this skill does not — size grants no lower tier.
 - Measure each declared theme from the compiled cascade, never from token names. A light-theme result does not establish a dark-theme result, and a skin's values are its own.
 - Focus rings and hover fills are UI graphics: they are in scope for the 3:1 bar.
 - Disabled controls are exempt from the bars by the spec. That exemption covers legibility, not meaning — see [Destructive actions](#destructive-actions) for the one disabled state that still has to change color.
 
-**The instrument.** Bootstrap paints in translucent layers: a card header and footer are a 3% tint of the body color over the card's own background. A reader that stops at the first painted ancestor and drops its alpha treats that tint as full-strength paint, and is then wrong in **both** directions — it green-lights a pairing nobody can read, and it red-flags one that reads fine. Use a reader that:
+**The instrument.** Refuse a reading from a reader that stops at the first painted ancestor and drops its alpha. Bootstrap paints in translucent layers — a card header and footer are a 3% tint of the body color over the card's own background — so a flattening reader passes an unreadable pairing and fails a readable one. Use a reader that:
 
 - collects every painted layer from the element upward to the first opaque one, then composites them top over bottom (Porter-Duff `over`) onto that opaque base;
 - composites a translucent foreground over that result before taking the ratio, rather than reading the declared color;
-- measures each declared theme in the same run, since a theme swap re-points the tokens under every layer;
+- measures each declared theme in the same run, because a theme swap re-points the tokens under every layer;
 - carries a negative control drawn from outside the population it covers — a pairing known to fail — and voids the run if that negative control passes.
 
 Include ancestor opacity in the painted stack. For images, gradients, masks, or blend modes the
 reader does not support, use a suitable rendered-background measurement or leave the pairing open;
 never flatten a variable background to its average color. Name reached states beside every result.
-Wire the reader into the suite once it has settled a question.
+Wire the reader into the suite after it has settled a question.
 
-### WCAG 2.2 deltas that bite dense app UI
+### WCAG 2.2 requirements for app UI
 
-- **Target size ≥ 24×24 CSS px (2.5.8, AA).** Icon buttons, row actions, close buttons, sort carets, checkbox hit-areas. A smaller visual target passes if a 24px spacing circle around it stays undisturbed — so in tight `table-sm` toolbars, pad the hit area rather than enlarging the glyph.
+- **Target size (2.5.8, AA) — this section owns the skill's target dimensions.** Hold every applicable target at ≥ 24×24 CSS px: icon buttons, row actions, close buttons, sort carets, checkbox hit-areas, and color swatches. A smaller visual target passes only where a 24px spacing circle around it stays undisturbed — so in tight `table-sm` toolbars, pad the hit area rather than enlarging the glyph. Prefer 44×44 CSS px for a primary mobile control. Measure the rendered hit area; never infer it from a size class such as `btn-sm`. Enlarge the button or its associated label, not the icon's surrounding decoration.
 - **Focus not obscured (2.4.11, AA).** Sticky headers/footers/action bars and toast overlays must not bury the focused element. Reserve space with `scroll-margin-top` on focusables (or `scroll-padding-top` on the scroll container) equal to the sticky chrome height.
 - **Dragging alternatives (2.5.7, AA).** Any drag (row reorder, kanban, slider, resize) needs a non-drag single-pointer path: move up/down buttons, numeric input, click-to-place.
 - **Accessible authentication (3.3.8, AA).** Never block paste in password/OTP fields; support password managers; no puzzle as the only way in.
@@ -585,7 +598,7 @@ Browsers handle focus on full page loads; in an SPA **you** do:
 - On route change, move focus to the new view's `h1` (or the `<main>` with `tabindex="-1"`) so SR users hear where they landed.
 - On failed submit, focus the error summary. On a compact destructive confirm, focus the safe action; in a scrolling or structured dialog, focus a static heading at the start when an action would scroll its context away.
 - After deleting a row, move focus to a sensible neighbor (next row / the table region), never let it fall to `<body>`.
-- Anything focused programmatically under sticky chrome needs the `scroll-margin-top` offset (2.4.11 above).
+- Anything focused programmatically under sticky chrome needs the `scroll-margin-top` offset (Focus not obscured, 2.4.11, under [WCAG 2.2 requirements for app UI](#wcag-22-requirements-for-app-ui)).
 
 ### Reduced motion
 
@@ -667,7 +680,7 @@ The Bootstrap implementation — a responsive offcanvas that renders inline abov
 
 ### Dense data tables
 
-**Semantics first — table vs grid.** Default to a static `<table>`: links and buttons inside cells ride the natural tab order and screen readers get real table navigation free. Reserve `role="grid"` for _editable, cell-interactive_ spreadsheet-like UIs — grid means you now own roving tabindex and full arrow-key cell navigation. Never bolt `role="grid"` onto a read-only table because it "looks like a data grid": semantics follow interaction, not appearance.
+**Semantics first — table vs grid.** Default to a static `<table>`: links and buttons inside cells ride the natural tab order and screen readers get real table navigation free. Reserve `role="grid"` for _editable, cell-interactive_ spreadsheet-like UIs — a grid hands roving tabindex and full arrow-key cell navigation to the implementation. Never bolt `role="grid"` onto a read-only table because it "looks like a data grid": semantics follow interaction, not appearance.
 
 **Craft rules:**
 
@@ -678,7 +691,7 @@ The Bootstrap implementation — a responsive offcanvas that renders inline abov
   independent column comparison or sorting. Keep key comparison columns explicit. Quiet repeated
   labels and row actions before increasing density.
 - **Density:** `table-sm` for compact; offer density as a user toggle (comfortable/compact) driven by one token or wrapper class, not per-cell tweaks. Do not shrink font below readability to fake density.
-- **Sticky header** when the table meaningfully scrolls (roughly a viewport / ~15+ rows). Not built into Bootstrap — the pattern:
+- **Sticky header** when the table scrolls its own header out of view. Not built into Bootstrap — the pattern:
 
 ```html
 <div
@@ -710,7 +723,7 @@ Keep sticky header cells on an **opaque, mode-aware surface** such as `bg-body-s
 </th>
 ```
 
-- **Row actions:** 1–3 high-frequency actions inline; the rest behind a per-row kebab (dropdown). Hover-only reveal fails touch and keyboard — keep at least the overflow trigger always visible and ≥24px.
+- **Row actions:** keep the high-frequency actions inline and put the rest behind a per-row kebab (dropdown). Hover-only reveal fails touch and keyboard — keep at least the overflow trigger always visible and at the floor in [WCAG 2.2 requirements for app UI](#wcag-22-requirements-for-app-ui).
 - **Selection & bulk actions:** header checkbox with indeterminate state for partial selection; per-row checkboxes with `aria-label` naming the row ("Select INV-1042"). When selection > 0, swap the toolbar's content in place for a contextual bar — "3 selected", the batch actions, and a clear-selection escape — never push the layout down (layout-shifting chrome is an anti-pattern). Announce the count through a polite live region.
 - **Pagination vs scrolling:** paginate when users need position, totals, deep links, and "go to page N" — most enterprise CRUD. Virtualize (windowed rendering) for long uniform lists where scrolling is natural. True infinite scroll is for exploratory feeds only — never where users need a footer or a findable end.
 - **Responsive, by task:** use a compact record list for record work, a locally scrollable semantic table for essential comparison, or priority columns with an operable detail path. Preserve identity, decision fields, and actions. Choose expansion from available container width, not `md` by habit. Keep one state model across variants; take the contract from [Keep the task intact](responsive-layout.md#keep-the-task-intact).
@@ -718,7 +731,7 @@ Keep sticky header cells on an **opaque, mode-aware surface** such as `bg-body-s
 
 ### Filter & search bars
 
-- One toolbar above the table: search input first (`role="search"` on the form), then the 2–4 highest-value filters as `form-select`/segmented controls, overflow filters behind a "Filters" button (offcanvas on mobile, dropdown/collapse on desktop).
+- One toolbar above the table: search input first (`role="search"` on the form), then the highest-value filters as `form-select`/segmented controls, overflow filters behind a "Filters" button (offcanvas on mobile, dropdown/collapse on desktop). Promote a filter to the toolbar because the task reaches for it, not to fill the row.
 - **Active filters must be visible and dismissible** — chips/badges with an ✕ and a "Clear all" — users must see _why_ the list is short. A filtered-empty state repeats the escape hatch.
 - Debounce live search; show result counts ("128 results") so feedback is immediate; filter state belongs in the URL when views are shareable.
 - At the base, give search a full row; stack or wrap actions and filters without shrinking labels or targets. Expand with `col-12 col-md`, `col-md-auto`, or `d-grid d-sm-flex` when they fit. Reserve a horizontal scroller for a documented spatial interaction, not an ordinary toolbar. Keep active filters and the clear path outside any disclosed extras.
@@ -729,7 +742,7 @@ Keep sticky header cells on an **opaque, mode-aware surface** such as `bg-body-s
   ⟨total⟩", where the wizard fills in its own runtime position and total); `list-group-numbered` or
   a simple nav renders it honestly.
 - Validate per step before advancing; never let a step advance carrying invalid data.
-- Back never loses data. Persist partial state (save-and-resume) for anything beyond ~3 steps or that crosses sessions.
+- Back never loses data. Persist partial state (save-and-resume) for a long sequence or one that crosses sessions.
 - Never re-ask what a previous step collected (Redundant Entry, 3.3.7) — carry it forward or offer "same as above".
 - Review step: a review summary with per-section edit links, then one clearly-named commit action ("Create account", not "Submit").
 
@@ -764,7 +777,7 @@ Blocking errors are never toasts. Keep the acting verb consistent across the flo
 
 Match friction to reversibility × blast radius:
 
-1. **Undo** (soft-delete + toast with Undo) for reversible, low-stakes, frequent actions — least friction, best experience. Prefer making actions undoable over interrupting them.
+1. **Undo** (soft-delete + toast with Undo) for reversible, low-stakes, frequent actions. Prefer making actions undoable over interrupting them.
 2. **Confirm dialog** for irreversible-but-scoped operations. Restate the specific consequence ("This permanently deletes 3 invoices"), verb-labeled buttons ("Delete invoices" / "Cancel" — never Yes/No), destructive action visually separated from safe; `alertdialog` semantics; focus lands on the safe action for a compact confirmation, or a static top heading when focusing an action would scroll the consequences out of view.
 3. **Type-to-confirm** (type the entity name) only for high-blast-radius irreversible operations — delete an org, drop a dataset.
 
@@ -791,7 +804,7 @@ Do not type-gate a single-row delete; do not one-tap a tenant wipe. Confirm only
 ## Performance
 
 - **Keep one CSS system.** Extend the installed Bootstrap theme; do not add a competing framework or a parallel palette to restyle the surface.
-- **Compressed, the full build is cheap; incomplete builds are not.** Trimming through a Sass-subset build (import only the parts used — see [Theming](#theming--design-tokens)) is the sanctioned diet. Aggressive purge tools are the risky one: Bootstrap adds classes **at runtime** (`show`, `showing`, `fade`, `collapsing`, `modal-open`, `modal-backdrop`, `offcanvas-backdrop`, tooltip/popover generated markup) — purging without safelisting them ships UIs whose modals silently stop rendering. If you purge, safelist every JS-toggled class and test every overlay.
+- **Ship the full compressed build, or trim it with a Sass-subset build** that imports only the parts used (see [Theming](#theming--design-tokens)). Do not reach for a CSS purge tool first. Bootstrap adds classes **at runtime** — `show`, `showing`, `fade`, `collapsing`, `modal-open`, `modal-backdrop`, `offcanvas-backdrop`, and tooltip/popover generated markup — so a purge without a safelist ships a UI whose modals stop rendering. Where the project purges anyway, safelist every JS-toggled class and drive every overlay before shipping.
 - **Icons:** Bootstrap Icons is a separate package — prefer inline SVG or an SVG sprite (crisp, styleable through `currentColor`, no font flash) over the icon font; load only the icons used.
 - **JS:** the bundle is small, but only load it where behavior exists; per-component ESM imports (`bootstrap/js/dist/modal`) trim further in bundlers.
 - **Fonts:** reuse the existing families and load only needed weights/scripts. Add a display face only for a distinct role; use `font-display: swap` and test fallback wrapping. Keep the data face legible before and after fonts load.
@@ -800,9 +813,9 @@ Do not type-gate a single-row delete; do not one-tap a tenant wipe. Confirm only
 
 Bootstrap has **no** combobox/autocomplete, date picker, multi-select tags input, data grid, or tree view. The boundary rule:
 
-- **Reach for native first:** `<input type="date">`, `<datalist>` for light autocomplete, `<select multiple>` where acceptable. Native widgets bring keyboard and AT behavior free.
-- **Reach for an established accessible library second** when the product genuinely needs the richer widget (combobox with async search, spreadsheet grid, drag-reorder tree). Budget for auditing it against the APG contract.
-- **Hand-roll last**, only with the APG contract in hand ([Accessibility](#accessibility) → Pattern contracts) and budget for the _keyboard_ half, which is most of the work.
+- **Use native controls:** `<input type="date">`, `<datalist>` for light autocomplete, and `<select multiple>` where suitable.
+- **Use an established accessible library** when native controls cannot meet the product's widget requirements; audit it against the APG contract.
+- **Implement a custom widget** only when native controls and an established accessible library cannot satisfy the requirements; read [Accessibility](#accessibility) → Pattern contracts and cover the required keyboard behavior.
 - Never fake it: a `.dropdown-menu` posing as a select, a `<div>` grid with click handlers, or a scroll-anchor "wizard" each break keyboard and AT users in ways a demo never shows.
 
 ## Common Layout Patterns
@@ -839,3 +852,20 @@ Bootstrap has **no** combobox/autocomplete, date picker, multi-select tags input
 <div class="d-none d-md-block">Hidden on mobile, visible md+</div>
 <div class="d-md-none">Visible only below md</div>
 ```
+
+`d-none` removes the element from layout and the accessibility tree, which is what makes a dual presentation legal: only the active view exposes its controls. It is not a content strategy — anything hidden at the base must remain reachable through an operable path ([responsive-layout.md](responsive-layout.md) → Keep the task intact). A generated responsive role, for a utility-map property with no shipped infix:
+
+```scss
+$utilities: map-merge(
+	$utilities,
+	(
+		'width': map-merge(
+				map-get($utilities, 'width'),
+				(
+					responsive: true,
+				)
+			),
+	)
+);
+// generates w-md-auto, w-lg-50, … alongside the stock w-*
+```