@orkestrel/scaffold 0.0.59 → 0.0.61

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

@@ -24,7 +24,7 @@
 
 - Typography: `.h1`–`.h6`, `.display-1`–`.display-6`, `.lead`, `.small`
 - Images: `.img-fluid`, `.img-thumbnail`, `.figure`
-- Tables: `.table` + variants — see [Tables](#tables)
+- Tables: `.table` plus its `.table-*` tone classes — see [Tables](#tables)
 - Figures: `.figure`, `.figure-img`, `.figure-caption`
 
 ### Form Components
@@ -86,7 +86,7 @@ Full form patterns and validation JS: [bootstrap-reference.md](bootstrap-referen
 </div>
 ```
 
-Variants: `.accordion-flush` (edge-to-edge, no outer borders); omit `data-bs-parent` to allow multiple items open.
+Modifier classes: `.accordion-flush` (edge-to-edge, no outer borders); omit `data-bs-parent` to allow multiple items open.
 
 ### Alerts
 
@@ -188,7 +188,7 @@ The current page is `aria-current="page"` and not a link. Use breadcrumbs only f
 
 Icon-only buttons need `aria-label` and a ≥24×24 px target (WCAG 2.2) — `btn-sm` icon clusters in toolbars are the common violation; pad rather than shrink.
 
-Choose the variant by contrast rather than by taste ([SKILL.md](../SKILL.md) → Hierarchy & actions).
+Choose the `btn-*` class by contrast rather than by taste ([SKILL.md](../SKILL.md) → Hierarchy & actions).
 
 ### Button Group
 
@@ -525,7 +525,7 @@ Bootstrap's modal enforces focus, adds `role="dialog"`/`aria-modal="true"`, clos
 <ul class="nav nav-underline">
 	…
 </ul>
-<!-- 5.3: understated bottom-border variant -->
+<!-- 5.3: understated bottom-border style -->
 <ul class="nav nav-pills nav-fill">
 	…
 </ul>
@@ -625,7 +625,7 @@ Real switchable tab panels (JS-driven — buttons, not scroll anchors):
 </div>
 ```
 
-**Responsive offcanvas** — the canonical sidebar-that-becomes-a-drawer: replace `.offcanvas` with `.offcanvas-{sm|md|lg|xl|xxl}`. Content renders **inline above** that breakpoint and as an **offcanvas below** it. Close buttons inside a responsive offcanvas need an explicit `data-bs-target`. Always set `aria-labelledby` (it is conceptually a dialog; `role="dialog"` is added by JS). Width/height via `--bs-offcanvas-width` (400px) / `--bs-offcanvas-height` (30vh). Full app-shell pattern: [bootstrap-reference.md](bootstrap-reference.md) → App shell.
+**Responsive offcanvas** — the canonical sidebar-that-becomes-a-drawer: replace `.offcanvas` with `.offcanvas-{sm|md|lg|xl|xxl}`. Content renders **inline above** that breakpoint and as an **offcanvas below** it. Close buttons inside a responsive offcanvas need an explicit `data-bs-target`. Always set `aria-labelledby` (it is conceptually a dialog; `role="dialog"` is added by JS). Width/height through `--bs-offcanvas-width` (400px) / `--bs-offcanvas-height` (30vh). Full app-shell pattern: [bootstrap-reference.md](bootstrap-reference.md) → App shell.
 
 ### Pagination
 
@@ -802,7 +802,7 @@ Popovers are **opt-in**: they do nothing until initialized in JS (see [JavaScrip
 </div>
 ```
 
-Gotcha: the spied element must be a scroll container (height/overflow, or focusable via `tabindex="0"`), and heading IDs must match the nav `href`s exactly. Scrollspy highlights position in one long page — it is not a substitute for real tabs.
+Gotcha: the spied element must be a scroll container (height/overflow, or focusable through `tabindex="0"`), and heading IDs must match the nav `href`s exactly. Scrollspy highlights position in one long page — it is not a substitute for real tabs.
 
 ### Spinners
 
@@ -858,13 +858,13 @@ Modifiers (combine freely):
 .table-active             /* highlight a row/cell */
 .table-group-divider      /* thicker rule between <tbody> groups */
 .caption-top              /* caption above the table */
-.table-primary … .table-dark   /* variants, on table/tr/td */
+.table-primary … .table-dark   /* tone classes, on table/tr/td */
 .align-middle             /* vertical alignment, on table/tr/td */
 ```
 
 - **Responsive:** wrap in `.table-responsive{-sm|-md|-lg|-xl|-xxl}` for horizontal scroll. Caveat: the wrapper clips overflowing content — dropdown menus inside a responsive table get cut off.
-- **Dark tables:** `data-bs-theme="dark"` on the `<table>` (the `.table-dark` variant approach is superseded).
-- **Theming:** variants set CSS variables, not fixed colors — `--bs-table-bg`, `--bs-table-color`, `--bs-table-striped-bg`, `--bs-table-hover-bg`, `--bs-table-active-bg`, `--bs-table-border-color`. `--bs-table-bg` is transparent by default so striping/hover layer through.
+- **Dark tables:** `data-bs-theme="dark"` on the `<table>` (the `.table-dark` class approach is superseded).
+- **Theming:** the `.table-*` tone classes set CSS variables, not fixed colors — `--bs-table-bg`, `--bs-table-color`, `--bs-table-striped-bg`, `--bs-table-hover-bg`, `--bs-table-active-bg`, `--bs-table-border-color`. `--bs-table-bg` is transparent by default so striping/hover layer through.
 - **Sticky headers are NOT built in.** Bootstrap ships no sticky-header feature; the pattern needs a few lines of custom CSS. That, plus selection columns, `aria-sort` sorting, bulk-action bars, and responsive strategies: [bootstrap-reference.md](bootstrap-reference.md) → Dense data tables.
 
 ### Toasts
@@ -881,7 +881,7 @@ Modifiers (combine freely):
 
 <div class="toast align-items-center text-bg-primary border-0" role="status" aria-live="polite">
 	<div class="d-flex">
-		<div class="toast-body">Color variant</div>
+		<div class="toast-body">Color tone</div>
 		<button
 			type="button"
 			class="btn-close me-2 m-auto"
@@ -899,7 +899,7 @@ Modifiers (combine freely):
 </div>
 ```
 
-Toasts are **opt-in** — hidden until `.show()` is called (or shown via a trigger). Keep the container in the DOM before showing so the live region announces. Use `role="status"`/`aria-live="polite"` for confirmations; reserve `role="alert"`/`assertive` for urgent messages. Errors requiring action are never toasts — see [bootstrap-reference.md](bootstrap-reference.md) → Feedback discipline.
+Toasts are **opt-in** — hidden until `.show()` is called (or shown through a trigger). Keep the container in the DOM before showing so the live region announces. Use `role="status"`/`aria-live="polite"` for confirmations; reserve `role="alert"`/`assertive` for urgent messages. Errors requiring action are never toasts — see [bootstrap-reference.md](bootstrap-reference.md) → Feedback discipline.
 
 ### Tooltip (Requires Popper.js)
 
@@ -926,7 +926,7 @@ Toasts are **opt-in** — hidden until `.show()` is called (or shown via a trigg
 </button>
 ```
 
-Tooltips are **opt-in** (JS init required, below). Only attach to focusable elements so keyboard users can trigger them; never put essential information _only_ in a tooltip, and never report form errors via tooltip. `data-bs-html` with untrusted content is an XSS vector.
+Tooltips are **opt-in** (JS init required, below). Only attach to focusable elements so keyboard users can trigger them; never put essential information _only_ in a tooltip, and never report form errors through a tooltip. `data-bs-html` with untrusted content is an XSS vector.
 
 ## JavaScript Initialization
 
@@ -949,7 +949,7 @@ const myToast = bootstrap.Toast.getOrCreateInstance('#myToast')
 myToast.show()
 ```
 
-Constructors accept elements or CSS selector strings. Full lifecycle — `getInstance`, `dispose()` on unmount, event pairs (`show.bs.*` / `shown.bs.*`), async behavior, and why SPAs should prefer framework wrappers: [bootstrap-reference.md](bootstrap-reference.md) → JavaScript lifecycle.
+Constructors accept elements or CSS selector strings. Full lifecycle — `getInstance`, `dispose()` on unmount, event pairs (`show.bs.*` / `shown.bs.*`), async behavior, and why an SPA prefers a framework wrapper: [bootstrap-reference.md](bootstrap-reference.md) → JavaScript lifecycle.
 
 ## Icons
 
@@ -1005,7 +1005,7 @@ The textless mark that survives both themes — dots, ticks, rings, pulses — i
 A selected row, pill, or filter chip repaints everything inside it — marks included. These traps stay invisible until the selected state is captured in both themes:
 
 - **A mark on an active fill of the same family disappears.** `.active` on a `list-group-item`, `nav-pill`, or `page-item` sets the item's own color, and a `text-bg-primary`-family mark inside it inherits or loses to that fill — present in the markup, gone on screen. Carry no tone class inside the fill ([SKILL.md](../SKILL.md) → Surfaces, color, contrast). Verify by capturing the selected row, not by reading the class list.
-- **`btn-check` filter labels invert in dark.** A `btn-outline-secondary` label reads as "chosen" in light and as "muted" in dark, because the checked fill and the surface swap relative weight. Give chosen filters an accent variant (a real theme color) rather than the neutral outline, so "chosen" reads the same way in both modes.
+- **`btn-check` filter labels invert in dark.** A `btn-outline-secondary` label reads as "chosen" in light and as "muted" in dark, because the checked fill and the surface swap relative weight. Give chosen filters an accent tone class (a real theme color) rather than the neutral outline, so "chosen" reads the same way in both modes.
 
 Exactly one item in a selection carries `aria-current` — the visual fill and the announced state must be the same item.
 
@@ -1017,5 +1017,5 @@ Exactly one item in a selection carries `aria-current` — the visual fill and t
 
 ### Theming
 
-- Components consume CSS variables — favor `text-bg-*`, `*-subtle`, and `data-bs-theme` over one-off colors; the deprecated `*-dark` component variants (`navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, `carousel-dark`) all map to `data-bs-theme="dark"`.
+- Components consume CSS variables — favor `text-bg-*`, `*-subtle`, and `data-bs-theme` over one-off colors; the deprecated `*-dark` component classes (`navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, `carousel-dark`) all map to `data-bs-theme="dark"`.
 - To restyle a component, override its `--bs-{component}-*` variables in your own scope instead of writing high-specificity rules — see [bootstrap-reference.md](bootstrap-reference.md) → Theming & design tokens.

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.