@aurodesignsystem-dev/auro-formkit 0.0.0-pr1578.0 → 0.0.0-pr1581.0

package/ai/README.md

@@ -0,0 +1,142 @@
+# Using Auro FormKit with AI
+
+This directory publishes a machine-consumable **AI implementation standard** for
+Auro FormKit. It lets a team use an AI assistant to build Auro form components in
+plain HTML/CSS/JS — on-brand and accessible — for situations where the Auro web
+components cannot be consumed directly (a framework constraint, a locked-down
+build, a non-Auro stack).
+
+> **When to use this vs. the web components.** If you can install and render
+> `<auro-input>` and friends, do that — the web components are the maintained
+> source of truth and carry behavior (masking, validation, keyboard) that plain
+> HTML cannot fully reproduce. Reach for these specs only when the components are
+> genuinely off the table.
+
+## What's here
+
+| File | Purpose |
+|---|---|
+| [`llms.txt`](./llms.txt) | Index of every component spec + the global rules. Start here. |
+| [`specs/*.spec.yaml`](./specs/) | One authoritative spec per component (API, visual recipe, behavior, gaps, examples, verify). Generated from source. |
+| [`_prompt-template.md`](./_prompt-template.md) | The instruction block that makes an AI follow a spec correctly. |
+| [`_a11y-baseline.md`](./_a11y-baseline.md) | Accessibility rules that apply to every component. |
+| `_authored/` | Hand-authored inputs the generator merges into each spec (see [Maintainers](#for-maintainers)). |
+
+Components with specs today: `checkbox`, `combobox`, `counter`, `datepicker`,
+`dropdown`, `form`, `input`, `menu`, `radio`, `select`.
+
+## Consuming the specs
+
+There are two supported models. Both keep you in sync with the components — the
+specs are regenerated from source and published on every release.
+
+### Model A — MCP server (recommended for Claude / MCP-capable tools)
+
+The `@aurodesignsystem/auro-formkit-mcp` server lets the AI discover and fetch the
+right spec on its own. No copy-pasting.
+
+**Claude Code**
+
+```sh
+claude mcp add auro-formkit -- npx -y @aurodesignsystem/auro-formkit-mcp
+```
+
+**Claude Desktop / other MCP clients** — add to the client's MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "auro-formkit": {
+      "command": "npx",
+      "args": ["-y", "@aurodesignsystem/auro-formkit-mcp"],
+      "env": { "AURO_FORMKIT_VERSION": "latest" }
+    }
+  }
+}
+```
+
+The server exposes three tools the model calls automatically:
+
+| Tool | What it does |
+|---|---|
+| `list_components` | Returns the global rules + the list of available components. |
+| `get_component_spec` | Fetches one component's spec, wrapped in the prompt template. |
+| `search_tokens` | Looks up Auro `--ds-*` design tokens by keyword. |
+
+Then just prompt: *"Build a required email field the Auro way."*
+
+### Model B — URL / @Docs (Cursor, ChatGPT, any fetch-capable agent)
+
+Point the tool at the published index:
+
+```
+https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/llms.txt
+```
+
+- **Cursor** — add that URL under Settings → Docs, then reference it: `@auro-formkit build an email input`.
+- **Any agent that can fetch URLs** — paste one line into your prompt:
+  *"Follow the Auro standard at `<llms.txt url>`; fetch the relevant spec before writing code."*
+
+## Working with a spec
+
+Once the AI has a spec, expect its output in this order (enforced by the prompt
+template): **HTML → CSS → JS → Fidelity Report → Self-check.**
+
+Two concepts drive correct output:
+
+- **Tiers** on every attribute/slot/event tell the AI what's reproducible:
+  - `core` — implemented fully (maps to a native HTML attribute).
+  - `enhanced` — implemented only if your request needs it.
+  - `wc-only` — **not reproducible in plain HTML.** The AI must report it, never fake it.
+- **Gaps** — the `gaps` section (and the Fidelity Report in the output) lists what
+  you lose versus the real component (e.g. input masking, credit-card detection,
+  the stylable dropdown panel). If your request needs a `wc-only` feature, the AI
+  will tell you and recommend using the actual web component instead.
+
+Always skim the **Fidelity Report** — it's how you learn whether the plain-HTML
+version is good enough or whether you should escalate back to `<auro-*>`.
+
+## Versioning
+
+Pin to a release for reproducible output instead of tracking `latest`:
+
+- MCP: set `AURO_FORMKIT_VERSION` (e.g. `0.3`) in the server env.
+- URL: replace `@latest` with `@0.3` in the `llms.txt` URL.
+
+This is the same discipline as pinning the npm component dependency — upgrade
+deliberately.
+
+## Limits
+
+- Specs cover the 10 components listed above. Components without a `css-only`
+  recipe (e.g. `bibtemplate`, `helptext`, `layoutElement`) are not included.
+- These specs produce a visual + structural approximation. Complex behavior marked
+  `wc-only` is intentionally out of scope — that's what the web components are for.
+- A reimplementation is bound to the design tokens available at author time; it
+  does not pick up runtime theme swaps the way the components do.
+
+## For maintainers
+
+Specs are **generated** — never edit `specs/*.yaml` or `llms.txt` by hand.
+
+**Sources (per component):**
+1. `custom-elements.json` → API (attributes, slots, events, methods).
+2. `components/<c>/demo/css-only.md` → token import, CSS recipe, golden examples, fidelity gaps.
+3. `ai/_authored/<tag>.overlay.yaml` → the judgment calls (tiers, native equivalents, behavioral rules, verify).
+
+**Regenerate:**
+
+```sh
+npm run build:ai          # analyze + generate
+# or, if custom-elements.json is already current:
+npm run build:ai:generate
+```
+
+Generation also runs inside `npm run build`, and `ai/**` ships via the package
+`files` array — so a normal release republishes the specs and the CDN serves them
+within minutes.
+
+**To improve a component's spec**, edit its overlay in `_authored/` (add native
+mappings, reclassify a tier, add an a11y rule) and regenerate. `_defaults.overlay.yaml`
+holds the rules applied to every component. The generator (`packages/build-tools/src/aiSpecGenerator.mjs`)
+logs a tier breakdown and warns when a component parses zero examples or gaps.

package/ai/_a11y-baseline.md

@@ -0,0 +1,27 @@
+# Auro accessibility baseline
+
+Rules that apply to **every** Auro FormKit component reimplemented in plain
+HTML/CSS/JS. A component spec's `behavior.a11y` section adds to these; it never
+overrides them.
+
+## Labels
+- Every control has a programmatically associated `<label>` (via `for`/`id` or by
+  wrapping the control). A `placeholder` is NOT a label.
+- To hide a label visually, keep it in the DOM with a visually-hidden class — never
+  remove it.
+- When a field is optional, indicate it in the accessible label (Auro appends
+  "(optional)" to non-`required` fields).
+
+## Help text and errors
+- Associate help text with the control via `aria-describedby`.
+- Reflect validity with `aria-invalid="true|false"` on the control.
+- Announce validation errors immediately with `role="alert"` and
+  `aria-live="assertive"`; do not require the user to move focus to hear them.
+
+## Keyboard and focus
+- Every interactive affordance (clear button, toggle, stepper) is a real,
+  focusable element in DOM order and operable with Enter/Space as appropriate.
+- Use `:focus-visible` for the focus ring, styled with Auro border/active tokens.
+
+## Motion
+- Respect `prefers-reduced-motion` for any label animation or transition.

package/ai/_authored/_defaults.overlay.yaml

@@ -0,0 +1,81 @@
+# Default overlay applied to every component before its own overlay.
+# These are the judgment calls the generator cannot derive from source.
+# A per-component overlay (auro-<tag>.overlay.yaml) deep-merges on top of this.
+
+# Tier inference (used when a per-component overlay does not set a tier):
+#   1. attribute has a nativeEquiv below -> core
+#   2. attribute name matches a wcOnlyHint  -> wc-only
+#   3. otherwise                            -> enhanced
+tierPolicy:
+  # Standard HTML attributes that map 1:1 onto a native element. These are core.
+  nativeEquiv:
+    value: value
+    type: type
+    name: name
+    required: required
+    disabled: disabled
+    readonly: "readonly (+ aria-readonly=\"true\")"
+    placeholder: placeholder
+    pattern: pattern
+    min: min
+    max: max
+    step: step
+    minLength: minlength
+    maxLength: maxlength
+    inputmode: inputmode
+    autocomplete: autocomplete
+    autocapitalize: autocapitalize
+    autocorrect: autocorrect
+    spellcheck: spellcheck
+    id: id
+    lang: lang
+    checked: checked
+    multiple: multiple
+    hideLabelVisually: "visually-hidden <label> class"
+  # Auro-specific behavior with no native analogue. These are wc-only:
+  # do not fake them, report them in the fidelity gaps.
+  wcOnlyHints:
+    - format
+    - layout
+    - shape
+    - appearance
+    - simple
+    - onDark
+    - ondark
+    - nested
+    - icon
+    - displayValue
+    - dvInputOnly
+    - activeLabel
+    - showPassword
+    - validateOnInput
+    - noValidate
+    - validity
+    - error
+    - errorMessage
+    - setCustomValidity
+
+# Accessibility rules that apply to every form field. Per-component overlays
+# append component-specific rules.
+behavior:
+  a11y:
+    - Every control MUST have a programmatically associated <label> (for/id or wrapping).
+    - Link help text via aria-describedby so it is announced after the label.
+    - Reflect invalid state with aria-invalid="true|false" on the control.
+    - Render validation errors with role="alert" aria-live="assertive" so they announce immediately.
+  keyboard:
+    - All interactive affordances are real, focusable elements in DOM order.
+
+# Machine-checkable assertions the AI output must pass. Per-component overlays add more.
+verify:
+  - "every color, size, spacing, radius, and font value uses var(--ds-*)"
+  - "each control has an associated <label>"
+  - "controls with aria-invalid=\"true\" have a role=\"alert\" message referenced by aria-describedby"
+  - "axe: label, aria-valid-attr-value, color-contrast pass"
+
+# The single rule AI most often violates.
+visual:
+  rule: >
+    NEVER hardcode a hex, px, rem, or font-family value. Every visual value MUST
+    be an Auro --ds-* token via var(--ds-token, fallback). Literal values are
+    allowed only as the second argument (fallback) of var().

package/ai/_authored/auro-checkbox.overlay.yaml

@@ -0,0 +1,22 @@
+summaryOverride: >
+  Checkbox for selecting one or more options; also composes into a checkbox-group
+  for grouped selection. Native equivalent is <input type="checkbox"> + <label>.
+
+tiers:
+  tabindex: core
+  role: enhanced
+  aria-checked: enhanced
+  aria-disabled: enhanced
+
+nativeEquiv:
+  tabindex: tabindex
+
+behavior:
+  a11y:
+    - Use a native <input type="checkbox"> with an associated <label>.
+    - Group related checkboxes in a <fieldset> with a <legend> as the group label.
+    - Reflect checked state natively; do not add aria-checked to a native checkbox.
+  keyboard:
+    - Space toggles the focused checkbox (native).
+  validation:
+    - Group-level "select at least one" is not native — script it and expose the error with role="alert".

package/ai/_authored/auro-combobox.overlay.yaml

@@ -0,0 +1,37 @@
+summaryOverride: >
+  Combobox — a text input that filters a listbox of options. The web platform has
+  no full equivalent; the closest is <input list> + <datalist>, which cannot style
+  the option panel or render rich option content.
+
+tiers:
+  value: core
+  placeholder: core
+  required: core
+  disabled: core
+  inputmode: core
+  autocomplete: core
+  availableOptions: wc-only
+  behavior: wc-only
+  checkmark: wc-only
+  matchWidth: wc-only
+  noFilter: wc-only
+  noFlip: wc-only
+  offset: wc-only
+  optionSelected: wc-only
+  persistInput: wc-only
+  placement: wc-only
+  shift: wc-only
+  triggerIcon: wc-only
+  typedValue: wc-only
+  autoPlacement: wc-only
+  fullscreenBreakpoint: wc-only
+  largeFullscreenHeadline: wc-only
+
+behavior:
+  a11y:
+    - The input has role="combobox", aria-expanded, aria-controls pointing to the listbox id, and aria-activedescendant pointing to the highlighted option.
+    - The listbox uses role="listbox" with role="option" children and aria-selected on the chosen option.
+  keyboard:
+    - Down opens/enters the list; Up/Down move the active option; Enter selects; Esc closes.
+  validation:
+    - Enforce "must select a listed option" in script; native <datalist> does not restrict input to its options.

package/ai/_authored/auro-counter.overlay.yaml

@@ -0,0 +1,23 @@
+summaryOverride: >
+  Numeric stepper with increment/decrement buttons; composes into a counter-group.
+  Native closest is <input type="number"> or a role="spinbutton" with real +/- buttons.
+
+tiers:
+  disableMax: enhanced
+  disableMin: enhanced
+  defaultSlot: wc-only
+
+nativeEquiv:
+  value: value
+  min: min
+  max: max
+  disabled: disabled
+
+behavior:
+  a11y:
+    - Use <input type="number"> with an associated <label>, or role="spinbutton" with aria-valuenow/valuemin/valuemax.
+    - The minus/plus controls are real <button>s with accessible names (see the ariaLabel.minus / ariaLabel.plus slots).
+  keyboard:
+    - Arrow Up/Down increment and decrement the value (native on number input).
+  validation:
+    - Clamp to min/max and disable the relevant button at the bounds; expose range errors with role="alert".

package/ai/_authored/auro-datepicker.overlay.yaml

@@ -0,0 +1,44 @@
+summaryOverride: >
+  Date / date-range picker — a text input plus a calendar popup. Native closest is
+  <input type="date"> (single date only; no range or blackout dates, and the
+  browser's picker cannot be styled with Auro tokens).
+
+tiers:
+  autoPlacement: wc-only
+  blackoutDates: wc-only
+  blackoutLabel: wc-only
+  calendarEndDate: wc-only
+  calendarStartDate: wc-only
+  calendarFocusDate: wc-only
+  calendarGridLabel: wc-only
+  centralDate: wc-only
+  monthFirst: wc-only
+  monthNames: wc-only
+  navLabelNextMonth: wc-only
+  navLabelPrevMonth: wc-only
+  noFlip: wc-only
+  offset: wc-only
+  placement: wc-only
+  range: wc-only
+  referenceDates: wc-only
+  shift: wc-only
+  stacked: wc-only
+  valueEnd: wc-only
+  fullscreenBreakpoint: wc-only
+  largeFullscreenHeadline: wc-only
+
+nativeEquiv:
+  value: value (on a native <input type="date">)
+  minDate: min
+  maxDate: max
+  required: required
+  disabled: disabled
+
+behavior:
+  a11y:
+    - Label the date input; the calendar popup is a dialog containing a grid (role="grid") of day cells.
+    - Provide accessible names for the previous/next month navigation and announce the selected date(s).
+  keyboard:
+    - Arrow keys move between days, PageUp/PageDown change month, Enter selects, Esc closes.
+  validation:
+    - Range selection, blackout dates, and min/max beyond a single value are scripted; native <input type="date"> only supports min/max on one date.

package/ai/_authored/auro-dropdown.overlay.yaml

@@ -0,0 +1,35 @@
+summaryOverride: >
+  Generic disclosure — a trigger that toggles a bib/panel of content. Native
+  closest is <details>/<summary> or a <button> with aria-expanded controlling a region.
+
+tiers:
+  open: enhanced
+  chevron: enhanced
+  autoPlacement: wc-only
+  desktopModal: wc-only
+  disableEventShow: wc-only
+  disableKeyboardHandling: wc-only
+  dropdownWidth: wc-only
+  focusShow: wc-only
+  isBibFullscreen: wc-only
+  hoverToggle: wc-only
+  hasTriggerContent: wc-only
+  fullscreenBreakpoint: wc-only
+  matchWidth: wc-only
+  noFlip: wc-only
+  shift: wc-only
+  noHideOnThisFocusLoss: wc-only
+  noToggle: wc-only
+  offset: wc-only
+  parentBorder: wc-only
+  placement: wc-only
+
+nativeEquiv:
+  disabled: disabled
+
+behavior:
+  a11y:
+    - The trigger is a <button> with aria-expanded and aria-controls pointing to the panel id.
+    - The panel is a region whose visibility follows aria-expanded.
+  keyboard:
+    - Enter/Space toggles the panel; Esc closes it and returns focus to the trigger.

package/ai/_authored/auro-form.overlay.yaml

@@ -0,0 +1,12 @@
+summaryOverride: >
+  Form coordinator that validates and manages child fields. Native equivalent is
+  the <form> element with native submit/reset and constraint validation.
+
+behavior:
+  a11y:
+    - Use a native <form>; group related fields in <fieldset>/<legend>; the submit control is a real <button type="submit">.
+  keyboard:
+    - Enter in a text field submits the form (native).
+  validation:
+    - Use native constraint validation (required, pattern, min/max) surfaced on submit.
+    - auro-form's cross-field coordination and aggregated validity are wc-only — validate each field and aggregate in script.

package/ai/_authored/auro-input.overlay.yaml

@@ -0,0 +1,33 @@
+# Reference overlay for auro-input. Shows every authored field the generator merges.
+# Other components can start with just `summaryOverride` and grow from here.
+
+summaryOverride: >
+  Single-line text input (types text, email, password, number) with built-in
+  validation, required/error states, and a bordered theme.
+
+# Reclassify specific attributes. Anything not listed falls back to the
+# _defaults tierPolicy (nativeEquiv -> core, wcOnlyHints -> wc-only, else enhanced).
+tiers:
+  type: core            # constrain to the natively supported subset via `enum` below
+  hideLabelVisually: core
+
+# Constrain enum-like attributes to the values reproducible in plain HTML.
+enums:
+  type: [text, email, password, number]
+
+# Override or add native mappings beyond the defaults.
+nativeEquiv:
+  hideLabelVisually: "add a visually-hidden class to the <label> (keep it in the DOM)"
+
+# Component-specific behavior appended to the _defaults behavior lists.
+behavior:
+  validation:
+    - Track a "touched" state; do NOT show errors before the field is first blurred.
+    - On invalid, swap the helpText content for the error message and set aria-invalid="true".
+  a11y:
+    - When the field is not `required`, append "(optional)" to the accessible label.
+    - For password fields, the show/hide toggle needs its own accessible name (aria-label).
+
+# Extra assertions on top of the _defaults verify list.
+verify:
+  - "type is one of text|email|password|number (other Auro types are wc-only)"

package/ai/_authored/auro-menu.overlay.yaml

@@ -0,0 +1,21 @@
+summaryOverride: >
+  Selectable option list; native closest is a <ul role="listbox"> with role="option"
+  items, or the <option>s inside a native <select>.
+
+tiers:
+  value: core
+  disabled: core
+  loading: wc-only
+  matchword: wc-only
+  nocheckmark: wc-only
+
+nativeEquiv:
+  value: value
+  disabled: disabled
+  multiselect: aria-multiselectable="true" on the listbox (or the native `multiple` attribute)
+
+behavior:
+  a11y:
+    - Use role="listbox" with role="option" children; set aria-selected on chosen options and aria-activedescendant for the highlighted one.
+  keyboard:
+    - Up/Down move the active option, Enter/Space selects, type-ahead jumps to matching options, Home/End jump to the ends.

package/ai/_authored/auro-radio.overlay.yaml

@@ -0,0 +1,19 @@
+summaryOverride: >
+  Radio button for selecting exactly one option from a set; composes into a
+  radio-group. Native equivalent is a set of <input type="radio"> sharing a name.
+
+tiers:
+  role: enhanced
+  label: enhanced
+
+nativeEquiv:
+  label: associate a <label> via for/id (label is not a native attribute)
+
+behavior:
+  a11y:
+    - Use native <input type="radio"> elements that share the same `name` to form one group.
+    - Wrap the group in a <fieldset> with a <legend> as the group label.
+  keyboard:
+    - Arrow keys move selection within the group; only the checked radio is in the tab order (native roving).
+  validation:
+    - Mark one radio in the group `required` to require a selection (native).

package/ai/_authored/auro-select.overlay.yaml

@@ -0,0 +1,37 @@
+summaryOverride: >
+  Select control (wraps auro-dropdown + auro-menu). Native equivalent is a
+  <select> with <option>/<optgroup>; the option panel cannot be styled natively.
+
+tiers:
+  multiselect: core
+  autoPlacement: wc-only
+  flexMenuWidth: wc-only
+  fluid: wc-only
+  forceDisplayValue: wc-only
+  fullscreenBreakpoint: wc-only
+  isPopoverVisible: wc-only
+  largeFullscreenHeadline: wc-only
+  matchWidth: wc-only
+  noCheckmark: wc-only
+  noFlip: wc-only
+  offset: wc-only
+  optionSelected: wc-only
+  placement: wc-only
+  shift: wc-only
+  typeaheadTimeoutMs: wc-only
+
+nativeEquiv:
+  multiselect: multiple
+  name: name
+  value: value
+  required: required
+  disabled: disabled
+
+behavior:
+  a11y:
+    - Use a native <select> with an associated <label>; group options with <optgroup label="...">.
+    - Multi-select uses the native `multiple` attribute.
+  keyboard:
+    - Type-ahead, Up/Down, and Home/End are provided natively by <select>.
+  validation:
+    - Set `required` on <select> with an empty-value first <option> to enforce a selection natively.

package/ai/_prompt-template.md

@@ -0,0 +1,33 @@
+# Role
+You implement Alaska Airlines Auro components as plain HTML/CSS/JS for a team
+that cannot use the Auro web components directly. You are given a COMPONENT SPEC
+(YAML) that is the authoritative contract. Follow it exactly; do not rely on
+prior knowledge of how the component "usually" works.
+
+# Hard rules (violating any is a failed response)
+1. TOKENS ONLY. Every color, size, spacing, radius, and font value must be an
+   Auro `--ds-*` token via `var(--ds-token, fallback)`. Never emit a bare hex,
+   px, rem, or font-family. Import the token file named in `visual.tokensImport`.
+2. ACCESSIBILITY IS NOT OPTIONAL. Implement every item in `behavior.a11y` and
+   `behavior.keyboard`.
+3. RESPECT TIERS.
+   - `core`     -> implement fully.
+   - `enhanced` -> implement only if the request needs it; otherwise omit cleanly.
+   - `wc-only`  -> DO NOT implement or fake. List it in the Fidelity Report.
+4. USE THE GOLDEN EXAMPLES (`examples`) as the structural pattern: element order,
+   class names, and ARIA attributes should match.
+5. NO INVENTED BEHAVIOR. If the spec does not define something, say so.
+
+# Output format (always, in this order)
+1. HTML — semantic markup matching the golden examples.
+2. CSS — token-based, derived from `visual.css`, including the required states.
+3. JS — only if the request needs interactivity the spec defines. Framework-agnostic
+   unless told otherwise.
+4. Fidelity Report — every relevant `gaps` / `wc-only` item, what is lost, and the
+   guidance. If the request asks for a wc-only feature, recommend the real web
+   component instead of faking it.
+5. Self-check — confirm each `verify` assertion passes, or flag which failed.
+
+# Framework target
+Generate for: {{framework — e.g. "vanilla HTML", "React", "Svelte"}}. Preserve all
+ARIA attributes and token usage regardless of framework.

package/ai/llms.txt

@@ -0,0 +1,26 @@
+# Auro FormKit — AI Implementation Standard
+
+> Reimplement Auro form components in plain HTML/CSS/JS using Auro design
+> tokens, for teams that cannot consume the web components. Specs are generated
+> from source on every release, so they never drift from the real component.
+
+## Non-negotiable rules
+- Style ONLY with Auro `--ds-*` tokens via `var(--ds-x, fallback)`; never bare hex/px.
+- Every control needs an associated `<label>` and full ARIA wiring.
+- `tier: wc-only` features are NOT reproducible in plain HTML — report, never fake.
+
+## Component specs
+- [auro-checkbox](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-checkbox.spec.yaml): Checkbox for selecting one or more options; also composes into a checkbox-group for grouped selection. Native equivalent is <input type="checkbox"> + <label>.
+- [auro-combobox](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-combobox.spec.yaml): Combobox — a text input that filters a listbox of options. The web platform has no full equivalent; the closest is <input list> + <datalist>, which cannot style the option panel or render rich option content.
+- [auro-counter](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-counter.spec.yaml): Numeric stepper with increment/decrement buttons; composes into a counter-group. Native closest is <input type="number"> or a role="spinbutton" with real +/- buttons.
+- [auro-datepicker](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-datepicker.spec.yaml): Date / date-range picker — a text input plus a calendar popup. Native closest is <input type="date"> (single date only; no range or blackout dates, and the browser's picker cannot be styled with Auro tokens).
+- [auro-dropdown](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-dropdown.spec.yaml): Generic disclosure — a trigger that toggles a bib/panel of content. Native closest is <details>/<summary> or a <button> with aria-expanded controlling a region.
+- [auro-form](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-form.spec.yaml): Form coordinator that validates and manages child fields. Native equivalent is the <form> element with native submit/reset and constraint validation.
+- [auro-input](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-input.spec.yaml): Single-line text input (types text, email, password, number) with built-in validation, required/error states, and a bordered theme.
+- [auro-menu](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-menu.spec.yaml): Selectable option list; native closest is a <ul role="listbox"> with role="option" items, or the <option>s inside a native <select>.
+- [auro-radio](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-radio.spec.yaml): Radio button for selecting exactly one option from a set; composes into a radio-group. Native equivalent is a set of <input type="radio"> sharing a name.
+- [auro-select](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/specs/auro-select.spec.yaml): Select control (wraps auro-dropdown + auro-menu). Native equivalent is a <select> with <option>/<optgroup>; the option panel cannot be styled natively.
+
+## Global contracts
+- [Prompt template](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/_prompt-template.md)
+- [Accessibility baseline](https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/ai/_a11y-baseline.md)