@chiralkit/design-system 0.1.0-alpha.0

package/dist/types/components.d.ts

@@ -0,0 +1,3068 @@
+/* eslint-disable */
+/* tslint:disable */
+/**
+ * This is an autogenerated file created by the Stencil compiler.
+ * It contains typing information for all components that exist in this project.
+ */
+import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
+import { DsSelectOption } from "./components/ds-select/ds-select";
+import { DsTabItem } from "./components/ds-tabs/ds-tabs";
+export { DsSelectOption } from "./components/ds-select/ds-select";
+export { DsTabItem } from "./components/ds-tabs/ds-tabs";
+export namespace Components {
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — non-interactive text label.
+     * **Keyboard interactions:**
+     * - Tab: N/A — the badge is not focusable and does not appear in tab order.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none — renders a plain `<span>` around a `<slot />`. The
+     *   `variant` prop is a purely visual axis and MUST NOT be the sole carrier
+     *   of information (color/style alone fails WCAG 1.4.1 Use of Color); the
+     *   textual content inside the slot must convey the same meaning.
+     * - State attributes: none.
+     * - Labeling strategy: visible text via `<slot />`. Consumers place the
+     *   readable label directly inside the tag.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — non-interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable. If a consumer wraps
+     *   `ds-badge` in an interactive element (e.g. `<button>`, `<a>`), that
+     *   wrapper owns the focus indicator via the DS `--ds-color-focus` token
+     *   and its own `:focus-visible` rule.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor` from the host page and
+     *   the variant-specific style; not verified in isolation here. Consumers
+     *   are responsible for confirming ≥ 4.5:1 (WCAG 1.4.3) against the surface
+     *   the badge is placed on.
+     * - Non-text: no state-conveying icons or borders that need the 3:1
+     *   non-text contrast threshold.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text as inline content within its
+     *   surrounding context (no role means AT reads it as plain text). The
+     *   `variant` value is not announced — that is intentional; the label text
+     *   is the source of truth for meaning.
+     * - State change: N/A — no dynamic state owned by this component.
+     */
+    interface DsBadge {
+        /**
+          * @default "neutral"
+         */
+        "variant": | "neutral"
+    | "ui-component"
+    | "recipe"
+    | "agent"
+    | "config";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (satisfied natively by the underlying `<button>` element). When `href` is
+     * set, the component renders `<a href>` instead — a link, not a button — and
+     * that surface follows native `<a>` semantics rather than the Button pattern.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the internal `<button>` or `<a>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Enter: activates (fires click on `<button>`, navigates on `<a>`).
+     * - Space: activates the `<button>` variant only (native behavior); on the
+     *   `<a>` variant Space scrolls the page as usual.
+     * - Escape: N/A — no dismissible state owned by this component.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` / `<a href>` supplies
+     *   the implicit `button` / `link` role.
+     * - State attributes: `disabled` (native attribute on `<button>`, not
+     *   `aria-disabled`). The `<a>` variant does not accept `disabled` — a
+     *   disabled navigation is a spec smell (see spec §"Button vs Link"); if a
+     *   link needs a disabled state, model it as a `<button>` action instead.
+     * - Labeling strategy: visible text via `<slot />`. Consumers MUST place
+     *   readable text (or a labeled icon) inside the tag. An empty slot leaves
+     *   the button/link without an accessible name and fails
+     *   `button-name` / `link-name` axe rules. Icon-only usage is out of contract
+     *   for `ds-button`; use a future `ds-icon-button` with a required
+     *   `aria-label` prop when that lands.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the element (native click behavior; the
+     *   component does not move focus on its own).
+     * - On close/deactivate: N/A.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied via `:focus-visible` — replaces the browser
+     *   default so both `<button>` and `<a>` variants use the same DS ring
+     *   (spec universal rule 3, WCAG 1.4.11 non-text contrast ≥ 3:1).
+     * **Motion:**
+     * - Animations: 150ms `background-color` ease-in-out transition on
+     *   `primary`/`secondary` variants (hover).
+     * - Reduced-motion behavior: N/A — 150ms is below the spec's 200ms threshold
+     *   for `prefers-reduced-motion` handling, and the transition animates color
+     *   only (no motion of position, scale, or opacity).
+     * **Contrast:**
+     * - Text: `primary` and `secondary` variants pair `--ds-color-{primary,secondary}`
+     *   with `--ds-color-text-on-{primary,secondary}` — the token pairs are
+     *   authored to meet WCAG 2.1 AA (≥ 4.5:1). The `ghost` variant inherits
+     *   `color: inherit` and pins `opacity: 0.85`, so its effective contrast
+     *   depends on the consumer's surface — verify per site.
+     * - Non-text (border on `ghost`): 1px `currentColor`; contrast tracks the
+     *   text color 1:1, subject to the same host-page caveat.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text followed by "button" (or "link"
+     *   for the `href` variant), plus "dimmed" / "unavailable" when `disabled`
+     *   is set (browser/AT dependent wording).
+     * - State change: N/A — this component does not own toggle state. A pressed
+     *   toggle needs `aria-pressed`, which is out of scope here; model that as
+     *   a distinct component or extend the API deliberately per the spec.
+     */
+    interface DsButton {
+        /**
+          * @default false
+         */
+        "disabled": boolean;
+        "href"?: string;
+        /**
+          * @default "md"
+         */
+        "size": "md" | "lg";
+        /**
+          * @default "button"
+         */
+        "type": "button" | "submit" | "reset";
+        /**
+          * @default "primary"
+         */
+        "variant": "primary" | "secondary" | "ghost";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — a container surface with no interactive
+     * behavior of its own. If a consumer nests interactive elements
+     * inside (button, link, form field), those elements satisfy their
+     * own a11y bucket independently.
+     * **Keyboard interactions:**
+     * - Tab / Shift+Tab: N/A — the card itself is not focusable. Any
+     *   interactive descendant carries its own tab semantics.
+     * - Enter / Space / Arrow / Escape / Printable: N/A.
+     * **ARIA:**
+     * - Roles used: none. `<ds-card>` is a purely visual grouping and
+     *   deliberately does not carry `role="region"` — that would demand
+     *   a labelledby target, which would only be correct in a subset of
+     *   uses. Consumers that need a labeled landmark should render a
+     *   `<section aria-labelledby>` around the card.
+     * - State attributes: none.
+     * - Labeling strategy: none applied by the component; consumer's
+     *   heading structure inside the slot supplies the accessible name
+     *   when needed.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - Focus indicator: N/A — the card itself is not focusable.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; the card does
+     *   not impose a text color, so contrast is the consumer theme's
+     *   responsibility.
+     * - Non-text (border, subtle background tint): both derived from
+     *   `color-mix(in oklch, currentColor N%, transparent)`, matching
+     *   the pattern used by `ds-input` and `ds-select`. WCAG 1.4.11
+     *   (3:1 non-text contrast) is met in themes where the surface has
+     *   enough delta against the page background; the component does
+     *   not override the consumer's palette to force it.
+     * **Screen reader announcement:**
+     * - Rendered state: no announcement of the card itself. AT
+     *   navigates to the slotted content directly, using whatever
+     *   heading and landmark structure the consumer places inside.
+     * - State change: N/A.
+     */
+    interface DsCard {
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<input type="checkbox">`; the browser already implements the
+     * checkbox role and its state semantics. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
+     * Note: `ds-checkbox` intentionally does NOT reach for the WAI-ARIA
+     * APG "tri-state checkbox" pattern (indeterminate + on + off) as a
+     * scratch-built ARIA widget. The native input already exposes the
+     * `indeterminate` DOM property and browsers report it to AT
+     * correctly; the `indeterminate` prop here forwards to that DOM
+     * property so the native mechanism carries the semantics.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input type="checkbox">`.
+     * - Space: toggles the checked state (native behavior).
+     * - Enter: no native effect on a checkbox (unlike button). Form
+     *   submission triggered by Enter comes from the enclosing form's
+     *   default submit button, not from the checkbox itself.
+     * **ARIA:**
+     * - Roles used: none explicit — the native checkbox supplies the
+     *   implicit `checkbox` role.
+     * - State attributes: `checked` (DOM property, kept in sync via
+     *   componentDidRender because Stencil does not JSX-forward the
+     *   attribute cleanly for controlled use), `disabled` (native
+     *   attribute, not `aria-disabled`), `aria-invalid` (from the
+     *   `invalid` prop), `aria-required` (from the `required` prop),
+     *   `aria-describedby` (from the `describedBy` prop).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal checkbox. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input`.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On toggle: focus remains on the native checkbox.
+     * - Focus indicator: browser default `:focus-visible` ring, kept on
+     *   purpose until the DS ships a themed focus utility using
+     *   `--ds-color-focus`. Not overridden by `ds-checkbox.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: N/A — the checkbox itself renders no text (labels are
+     *   supplied by the consumer via `label` prop or wrapping <label>).
+     * - Non-text (the box and its check glyph): browser default rendering
+     *   is kept on purpose (no `appearance: none` override); this
+     *   preserves the OS/browser accessibility rendering that AT and
+     *   forced-color modes rely on. A themed override is a future
+     *   decision once the DS commits to a checkbox visual language that
+     *   still passes 3:1 non-text contrast in every theme.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "checkbox", followed by "checked"
+     *   / "not checked" / "mixed" per the current DOM state.
+     * - State change: on toggle, AT announces the new state (native
+     *   behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `checked` is the source of truth for controlled use. Reading
+     *   `event.detail` from `dsChange` gives the new state; the internal
+     *   input is kept in sync via a Watch + a re-sync in componentDidRender.
+     * - `indeterminate` is a visual/AT state, not a value — it is NOT
+     *   submitted with a form and clears on the next user toggle.
+     */
+    interface DsCheckbox {
+        /**
+          * @default false
+         */
+        "checked": boolean;
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * @default false
+         */
+        "indeterminate": boolean;
+        /**
+          * @default false
+         */
+        "invalid": boolean;
+        "label"?: string;
+        "name"?: string;
+        /**
+          * @default false
+         */
+        "required": boolean;
+        "value"?: string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (for the internal copy control; the code readout itself is static text).
+     * **Keyboard interactions:**
+     * - Tab: moves focus into the internal copy `<button>`; the code readout
+     *   (`<pre><code>`) is not focusable itself, but its container is
+     *   horizontally scrollable and remains reachable via the browser's caret
+     *   browsing / find-in-page path.
+     * - Enter: activates the copy button (writes `code` to the clipboard).
+     * - Space: activates the copy button (native `<button>` behavior).
+     * - Escape: N/A — the "Copied" state auto-clears after 1.4s; no dismissible
+     *   modal state.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` supplies the implicit
+     *   `button` role; `<pre>` and `<code>` supply their semantic roles.
+     * - State attributes: none. The `copied` flag lives only in the button's
+     *   accessible name (see below); it is intentionally not surfaced via
+     *   `aria-pressed` because it is not a toggle — it is a transient
+     *   post-action confirmation.
+     * - Labeling strategy: `aria-label` on the copy button — "Copy code" in the
+     *   resting state, "Copied" while the confirmation is visible. This is
+     *   authoritative because the button carries both an icon and the words
+     *   "Copy" / "Copied", and mixed icon+text needs an explicit accessible
+     *   name to avoid AT reading the SVG as a separate node.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the copy button (clipboard write is
+     *   synchronous from the user's perspective; no focus is moved).
+     * - On close/deactivate: N/A — no popup or overlay to close.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied to `.ds-code-block__copy:focus-visible`. The
+     *   readout itself is not focusable and has no focus indicator by design.
+     * **Motion:**
+     * - Animations: 120ms `color` / `border-color` ease transition on the copy
+     *   button (hover/focus).
+     * - Reduced-motion behavior: N/A — 120ms is below the spec's 200ms
+     *   threshold, and the transition animates color only.
+     * **Contrast:**
+     * - Text (code readout): inherits `color: currentColor`; contrast depends
+     *   on the host page's text color vs. the block's tinted background
+     *   (`color-mix(currentColor 4%, transparent)`). Verify per site.
+     * - Text (copy button): `color-mix(in oklch, currentColor 70%, transparent)`
+     *   at rest, `currentColor` on hover. The 70%-mixed resting color can drop
+     *   below 4.5:1 on low-contrast surfaces — audit per usage site, and lean
+     *   on the hover/focus states (both restore full `currentColor`) as the
+     *   accessible fallback.
+     * - Non-text (button border, language tag border-bottom): both use
+     *   `color-mix(currentColor <15|12>%, transparent)` — decorative separators,
+     *   they do not convey state, so the 3:1 non-text contrast rule does not
+     *   apply. Focus and hover borders shift up to 30% for clearer edges.
+     * **Screen reader announcement:**
+     * - Rendered state: announces "Copy code, button" (the `aria-label`), then
+     *   the code content when the user navigates into the `<pre><code>` block
+     *   (usually announced as a code block on VoiceOver).
+     * - State change: after clicking Copy, the button's `aria-label` flips to
+     *   "Copied"; AT will announce this on the next focus or re-read of the
+     *   button, but NOT proactively — there is no `aria-live` region. This is
+     *   deliberate per spec §"What we explicitly do NOT do" (avoid live-region
+     *   overuse), and the trade-off is that a screen-reader-only user does not
+     *   get an unsolicited confirmation. If a future review decides that
+     *   confirmation must be audible, add a visually-hidden
+     *   `aria-live="polite"` element whose text toggles on `copied`.
+     */
+    interface DsCodeBlock {
+        "code": string;
+        /**
+          * @default "bash"
+         */
+        "language": string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** state-machine
+     * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+     * This component wraps the **native `<dialog>` element** rather than
+     * scratch-building the APG pattern on top of a `<div role="dialog">`.
+     * `<dialog>` opened via `showModal()` gives us — from the browser,
+     * verified by the platform, not by us:
+     * - Focus trap: Tab / Shift+Tab cycle only through focusable
+     *   descendants (including slotted light-DOM descendants; the flattened
+     *   accessibility tree is what the trap operates on).
+     * - Escape: closes the dialog and returns focus to the previously
+     *   focused element (native, not implemented here).
+     * - Inert background: everything outside the dialog is inert while it
+     *   is open — no mouse, no keyboard, not part of the a11y tree.
+     * - Return focus: on close, focus returns to whatever element had it
+     *   before `showModal()` — native, not implemented here.
+     * - Initial focus: browser auto-focuses the first `autofocus` element
+     *   inside, or the first focusable if none — native.
+     * - `role="dialog"` and `aria-modal="true"` semantics: implicit on
+     *   `<dialog>`, no ARIA needed from us.
+     * This is the deliberate answer to the a11y spec §D warning about
+     * scratch-building Tier 2 components: the native element removes the
+     * "compiles, axe passes, screen-reader user gets trapped" failure
+     * mode by delegating the state machine to the platform.
+     * **Keyboard interactions (all handled by the native element unless
+     * noted otherwise):**
+     * - Tab: cycles focus within the dialog's focusable descendants
+     *   (native focus trap).
+     * - Shift+Tab: reverse cycle (native).
+     * - Escape: closes the dialog and fires the `close` event (native).
+     *   Consumers who need to prevent dismissal on Escape (destructive
+     *   flows: e.g. an unsaved-changes guard) must call
+     *   `event.preventDefault()` inside their own `keydown` listener on
+     *   the dialog before it reaches the browser — that is an escape
+     *   hatch, not a default we impose.
+     * - Enter / Space: no special dialog behavior; forwarded to
+     *   whatever descendant has focus (a button will activate).
+     * - Home / End / Arrow keys: no special dialog behavior; forwarded
+     *   to descendants.
+     * - Printable characters: forwarded to descendants (e.g. typing
+     *   inside a slotted `<ds-input>`).
+     * **ARIA attributes and value triggers:**
+     * - Implicit `role="dialog"` on the native `<dialog>`.
+     * - Implicit `aria-modal="true"` when opened via `showModal()`
+     *   (which is what this component always uses; `show()` — the
+     *   non-modal form — is intentionally not exposed in v1).
+     * - `aria-label` set from the `label` prop onto the `<dialog>`.
+     *   Consumers who prefer an in-content title can pass a
+     *   `labelledBy` prop instead, whose value is the id of a heading
+     *   element they render inside the slot — `aria-labelledby`
+     *   resolves that id through the flattened tree.
+     * - `aria-describedby` from the `describedBy` prop, resolving a
+     *   light-DOM id of a descriptive block (e.g. the dialog body copy
+     *   when the label is short).
+     * **Focus lifecycle:**
+     * - Opening: `showModal()` moves focus to the first `autofocus`
+     *   element inside, or the first focusable if none. Consumers who
+     *   want a specific initial focus target should mark that element
+     *   with `autofocus`.
+     * - While open: focus is trapped within the flattened tree of the
+     *   `<dialog>`; Tab / Shift+Tab cycle through slotted descendants.
+     *   Focus cannot escape into the inert background.
+     * - Closing: `close()` (either from Escape, from a form-submit with
+     *   `method="dialog"`, from a light-dismiss backdrop click handler
+     *   the consumer wires up, or from `open=false`) returns focus to
+     *   the element that had it immediately before `showModal()` was
+     *   called. The `dsClose` event fires after focus has been restored.
+     * **ARIA labelling contract (choose one):**
+     * - **`label`** (string) — sets `aria-label` on the dialog. Simplest
+     *   for short titles.
+     * - **`labelledBy`** (id) — sets `aria-labelledby` to reference a
+     *   heading rendered inside the slot. Preferred when the dialog has
+     *   a visible title so the accessible name matches the visible name.
+     * If both are omitted, axe reports `dialog-name` — the dialog has no
+     * accessible name. The a11y test for this component asserts that at
+     * least one of the two is provided.
+     * **Motion:**
+     * - Animations: none applied by the component. Consumers who want an
+     *   entrance transition can style `::backdrop` and `dialog[open]`
+     *   with their own animation, gated on `@media
+     *   (prefers-reduced-motion: no-preference)`.
+     * - Reduced-motion behavior: N/A — no animation to collapse. If a
+     *   consumer adds one, they own the reduced-motion fallback.
+     * **Contrast:**
+     * - Text: inherits `color: inherit`; consumer theme owns contrast.
+     * - Non-text: subtle bordered surface via
+     *   `color-mix(in oklch, currentColor N%, transparent)` matching
+     *   `ds-card`. Backdrop is a semi-transparent black by default.
+     * **Screen reader announcement:**
+     * - Rendered state (closed): dialog is not in the a11y tree.
+     * - Opened: AT announces "dialog" plus the accessible name from
+     *   `label` / `labelledBy`, then reads the content following focus
+     *   (or the descriptive block referenced by `describedBy` first,
+     *   depending on AT).
+     * - State change: on close, AT returns to the element that regained
+     *   focus (the trigger); no `aria-live` announcement is added.
+     * **Consumer contract:**
+     * - Set `open` to true to show; set to false to close. The component
+     *   syncs the DOM state via `showModal()` / `close()` in a Watch.
+     * - Listen to `dsClose` to know when the dialog was dismissed (by
+     *   Escape, by `open=false`, or by a form submit with
+     *   `method="dialog"`). Listen to `dsOpen` for the mirror event.
+     * - The default backdrop is opaque and NOT click-to-dismiss. Consumers
+     *   who want light-dismiss can add a click listener on the dialog
+     *   that closes when the click target is the dialog itself (not a
+     *   descendant): `if (e.target === dialog) dialog.close()`.
+     * - Put focus targets (form fields, primary action button) inside
+     *   the slot. Use `autofocus` on the element that should receive
+     *   focus first.
+     * **Pending manual verification (see commit message TODO):**
+     * - VoiceOver on macOS: confirm the dialog announces its accessible
+     *   name + "dialog" on open, focus lands on the correct element,
+     *   Escape closes and focus returns to the trigger.
+     * - Chromium high-contrast / forced-colors: confirm the surface
+     *   still reads as a bordered container with the native ::backdrop
+     *   dim.
+     */
+    interface DsDialog {
+        "describedBy"?: string;
+        "label"?: string;
+        "labelledBy"?: string;
+        /**
+          * @default false
+         */
+        "open": boolean;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native `<input>`;
+     * there is no WAI-ARIA APG pattern for a plain text input because the
+     * browser already implements it natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Printable characters: insert at the caret position (native).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native); for
+     *   `type="number"` Up/Down step the numeric value (native).
+     * - Enter: on `type="search"` may submit the enclosing form (native);
+     *   no custom handling.
+     * - Escape: no native meaning for a text input.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<input>` supplies its
+     *   implicit role (`textbox`, `searchbox`, etc. depending on `type`).
+     * - State attributes: `disabled` (native attribute, not `aria-disabled`),
+     *   `aria-invalid` (from the `invalid` prop), `aria-required` (from the
+     *   `required` prop), `aria-describedby` (from the `describedBy` prop,
+     *   expected to reference a light-DOM node id — typically a hint or
+     *   error message rendered by the consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto the
+     *   internal `<input>`. This is the **canonical, recommended** mode —
+     *   explicit and independent of DOM structure. Consumers MUST pass
+     *   `label` (or otherwise give the field an accessible name) — an
+     *   `<input>` with no accessible name is a WCAG failure (axe rule
+     *   `label`). Wrapping the host in a light-DOM `<label>` (e.g.
+     *   `<label>Email <ds-input></ds-input></label>`) also produces an
+     *   accessible name in Chromium via flattened-tree resolution — the
+     *   same secondary mode documented on `ds-select`, verified in this
+     *   component's e2e tests. Setting `aria-label` directly on the
+     *   `<ds-input>` host does NOT work: shadow-DOM attribute forwarding
+     *   would be required — use the `label` prop instead.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<input>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is kept
+     *   on purpose — a themed focus ring using `--ds-color-focus` is a
+     *   future decision once the DS ships a shared focus utility. Not
+     *   overridden by `ds-input.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends on
+     *   the consumer's theme, not verified in isolation here.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-select` — inherits whatever contrast the host page
+     *   sets. WCAG 1.4.11 (3:1 non-text) is the consumer's responsibility
+     *   in themes that override the surface.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the accessible
+     *   name, followed by the browser/AT's role announcement for the
+     *   input type ("edit text", "search text", "password", "phone
+     *   number", "email"…). When `required=true` the announcement
+     *   includes "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native input behavior); no `aria-live` added, per the
+     *   spec's guidance against live-region overuse.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label. It disappears on focus in
+     *   most browsers and is not reliably announced by every AT — always
+     *   pair with `label`.
+     * - For `type="password"` in a real form, pair with a light-DOM
+     *   `<input type="hidden">` or a form-associated ancestor that gives
+     *   the browser's password manager an `autocomplete` hint. This
+     *   component intentionally does not expose `autocomplete` in v1;
+     *   consumers that need it can render a native `<input>` for that
+     *   field until the prop is added.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     */
+    interface DsInput {
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * @default false
+         */
+        "invalid": boolean;
+        "label"?: string;
+        "name"?: string;
+        "placeholder"?: string;
+        /**
+          * @default false
+         */
+        "required": boolean;
+        /**
+          * @default "md"
+         */
+        "size": "md" | "lg";
+        /**
+          * @default "text"
+         */
+        "type": | "text"
+    | "email"
+    | "password"
+    | "search"
+    | "tel"
+    | "url"
+    | "number";
+        "value"?: string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** static-display (indeterminate progress indicator)
+     * **APG pattern:** N/A — the loader is a passive presence indicator, not a
+     * `progressbar` (no measurable value). Uses `role="status"` per WAI-ARIA
+     * live-region semantics for indeterminate loading states.
+     * **Keyboard interactions:**
+     * - Tab: N/A — not focusable.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: `role="status"` on the host — an implicit polite live
+     *   region ARIA lists as valid for "advisory information" including
+     *   in-progress operations. The inner `<svg>` is decorative and carries
+     *   `aria-hidden="true"` + `focusable="false"` so it never becomes a
+     *   parallel target for screen readers.
+     * - State attributes: none. The loader has no state changes to announce
+     *   beyond its own presence; the polite live region on mount is the
+     *   announcement.
+     * - Labeling strategy: `aria-label` from the `label` prop (default
+     *   "Loading"). Consumers pass a more specific string when the context
+     *   warrants ("Loading ceremonies", "Signing in", …).
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — not interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable.
+     * **Motion:**
+     * - Animations: two mirrored halves of the logo path oscillate
+     *   symmetrically around the visual center, meeting at the ring midpoint
+     *   and separating again. Cycle 1.4s by default (`speed="normal"`);
+     *   `speed="slow"` = 2.2s, `speed="fast"` = 0.9s.
+     * - Reduced-motion behavior: `@media (prefers-reduced-motion: reduce)`
+     *   collapses both halves to a static rendering with a slow opacity
+     *   pulse (2s ease-in-out). No rotation, no lateral movement.
+     * **Contrast:**
+     * - Text: N/A — the visible surface is the SVG stroke, not text.
+     * - Non-text: stroke inherits `currentColor` from the host. Consumers are
+     *   responsible for confirming the stroke against its background meets
+     *   the ≥ 3:1 non-text contrast threshold (WCAG 1.4.11) where the loader
+     *   conveys state (e.g. distinguishing "still loading" from "idle").
+     * **Screen reader announcement:**
+     * - Rendered state: the polite live region announces the label
+     *   (e.g. "Loading") when the loader mounts.
+     * - State change: N/A — the loader itself has no state that changes.
+     *   Consumers unmount the loader when the awaited work completes; that
+     *   removal is silent, which is the intended behavior (the arriving
+     *   content is the announcement).
+     */
+    interface DsLoader {
+        /**
+          * @default "Loading"
+         */
+        "label": string;
+        /**
+          * @default "md"
+         */
+        "size": "sm" | "md" | "lg";
+        /**
+          * @default "normal"
+         */
+        "speed": "slow" | "normal" | "fast";
+    }
+    interface DsSelect {
+        /**
+          * @default false
+         */
+        "disabled": boolean;
+        "label"?: string;
+        "name"?: string;
+        /**
+          * Options rendered inside the internal shadow `<select>`. Accepts either: - a JSON string (SSR-friendly — server-rendered HTML can only set   string attributes, and Stencil does not JSON-parse array attributes),   e.g. `options='[{"value":"en","label":"EN"}]'` - an array property set from client-side JS,   e.g. `el.options = [{ value: 'en', label: 'EN' }]`  Malformed JSON fails safe to an empty list rather than throwing, so the component still renders a visible (if empty) select.
+          * @default "[]"
+         */
+        "options": string | ReadonlyArray<DsSelectOption>;
+        /**
+          * @default "md"
+         */
+        "size": "md" | "lg";
+        "value"?: string;
+    }
+    interface DsTabs {
+        "active"?: string;
+        /**
+          * @default "[]"
+         */
+        "items": string | ReadonlyArray<DsTabItem>;
+        "label"?: string;
+        /**
+          * @default "horizontal"
+         */
+        "orientation": "horizontal" | "vertical";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<textarea>`; there is no WAI-ARIA APG pattern for a plain
+     * multi-line text field because the browser already implements it
+     * natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<textarea>`; Tab inside the
+     *   textarea inserts a tab character only when the browser is
+     *   configured to do so (default behavior: Tab moves focus out).
+     * - Printable characters: insert at the caret position (native).
+     * - Enter: inserts a newline within the value (native), does not
+     *   submit the enclosing form (unlike a single-line input).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native).
+     * - Escape: no native meaning for a text area.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<textarea>` supplies
+     *   the implicit `textbox` role with multiline behavior.
+     * - State attributes: `disabled` (native attribute, not
+     *   `aria-disabled`), `aria-invalid` (from the `invalid` prop),
+     *   `aria-required` (from the `required` prop), `aria-describedby`
+     *   (from the `describedBy` prop, expected to reference a light-DOM
+     *   node id — typically a hint or error message rendered by the
+     *   consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal `<textarea>`. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input` and `ds-select`,
+     *   verified in this component's e2e tests. Setting `aria-label`
+     *   directly on the `<ds-textarea>` host does NOT work: shadow-DOM
+     *   attribute forwarding would be required — use the `label` prop.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<textarea>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is
+     *   kept on purpose — a themed focus ring using `--ds-color-focus`
+     *   is a future decision once the DS ships a shared focus utility.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends
+     *   on the consumer's theme, not verified in isolation.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-input`.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "edit text, multiline" (browser/AT
+     *   wording varies). When `required=true` the announcement includes
+     *   "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label — always pair with `label`.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     * - `rows` sets the initial visible line count. Vertical resize is
+     *   left to the native default (`resize: vertical`) so users can
+     *   grow the field for long entries; the consumer's CSS can pin it
+     *   with `resize: none` when a fixed height matters.
+     */
+    interface DsTextarea {
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * @default false
+         */
+        "invalid": boolean;
+        "label"?: string;
+        "name"?: string;
+        "placeholder"?: string;
+        /**
+          * @default false
+         */
+        "required": boolean;
+        /**
+          * @default 3
+         */
+        "rows": number;
+        /**
+          * @default "md"
+         */
+        "size": "md" | "lg";
+        "value"?: string;
+    }
+    interface DsTooltip {
+        /**
+          * @default 100
+         */
+        "closeDelay": number;
+        "label": string;
+        /**
+          * @default 250
+         */
+        "openDelay": number;
+        /**
+          * @default "bottom"
+         */
+        "placement": "top" | "bottom";
+    }
+}
+export interface DsCheckboxCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsCheckboxElement;
+}
+export interface DsDialogCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsDialogElement;
+}
+export interface DsInputCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsInputElement;
+}
+export interface DsSelectCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsSelectElement;
+}
+export interface DsTabsCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsTabsElement;
+}
+export interface DsTextareaCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsTextareaElement;
+}
+declare global {
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — non-interactive text label.
+     * **Keyboard interactions:**
+     * - Tab: N/A — the badge is not focusable and does not appear in tab order.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none — renders a plain `<span>` around a `<slot />`. The
+     *   `variant` prop is a purely visual axis and MUST NOT be the sole carrier
+     *   of information (color/style alone fails WCAG 1.4.1 Use of Color); the
+     *   textual content inside the slot must convey the same meaning.
+     * - State attributes: none.
+     * - Labeling strategy: visible text via `<slot />`. Consumers place the
+     *   readable label directly inside the tag.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — non-interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable. If a consumer wraps
+     *   `ds-badge` in an interactive element (e.g. `<button>`, `<a>`), that
+     *   wrapper owns the focus indicator via the DS `--ds-color-focus` token
+     *   and its own `:focus-visible` rule.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor` from the host page and
+     *   the variant-specific style; not verified in isolation here. Consumers
+     *   are responsible for confirming ≥ 4.5:1 (WCAG 1.4.3) against the surface
+     *   the badge is placed on.
+     * - Non-text: no state-conveying icons or borders that need the 3:1
+     *   non-text contrast threshold.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text as inline content within its
+     *   surrounding context (no role means AT reads it as plain text). The
+     *   `variant` value is not announced — that is intentional; the label text
+     *   is the source of truth for meaning.
+     * - State change: N/A — no dynamic state owned by this component.
+     */
+    interface HTMLDsBadgeElement extends Components.DsBadge, HTMLStencilElement {
+    }
+    var HTMLDsBadgeElement: {
+        prototype: HTMLDsBadgeElement;
+        new (): HTMLDsBadgeElement;
+    };
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (satisfied natively by the underlying `<button>` element). When `href` is
+     * set, the component renders `<a href>` instead — a link, not a button — and
+     * that surface follows native `<a>` semantics rather than the Button pattern.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the internal `<button>` or `<a>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Enter: activates (fires click on `<button>`, navigates on `<a>`).
+     * - Space: activates the `<button>` variant only (native behavior); on the
+     *   `<a>` variant Space scrolls the page as usual.
+     * - Escape: N/A — no dismissible state owned by this component.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` / `<a href>` supplies
+     *   the implicit `button` / `link` role.
+     * - State attributes: `disabled` (native attribute on `<button>`, not
+     *   `aria-disabled`). The `<a>` variant does not accept `disabled` — a
+     *   disabled navigation is a spec smell (see spec §"Button vs Link"); if a
+     *   link needs a disabled state, model it as a `<button>` action instead.
+     * - Labeling strategy: visible text via `<slot />`. Consumers MUST place
+     *   readable text (or a labeled icon) inside the tag. An empty slot leaves
+     *   the button/link without an accessible name and fails
+     *   `button-name` / `link-name` axe rules. Icon-only usage is out of contract
+     *   for `ds-button`; use a future `ds-icon-button` with a required
+     *   `aria-label` prop when that lands.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the element (native click behavior; the
+     *   component does not move focus on its own).
+     * - On close/deactivate: N/A.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied via `:focus-visible` — replaces the browser
+     *   default so both `<button>` and `<a>` variants use the same DS ring
+     *   (spec universal rule 3, WCAG 1.4.11 non-text contrast ≥ 3:1).
+     * **Motion:**
+     * - Animations: 150ms `background-color` ease-in-out transition on
+     *   `primary`/`secondary` variants (hover).
+     * - Reduced-motion behavior: N/A — 150ms is below the spec's 200ms threshold
+     *   for `prefers-reduced-motion` handling, and the transition animates color
+     *   only (no motion of position, scale, or opacity).
+     * **Contrast:**
+     * - Text: `primary` and `secondary` variants pair `--ds-color-{primary,secondary}`
+     *   with `--ds-color-text-on-{primary,secondary}` — the token pairs are
+     *   authored to meet WCAG 2.1 AA (≥ 4.5:1). The `ghost` variant inherits
+     *   `color: inherit` and pins `opacity: 0.85`, so its effective contrast
+     *   depends on the consumer's surface — verify per site.
+     * - Non-text (border on `ghost`): 1px `currentColor`; contrast tracks the
+     *   text color 1:1, subject to the same host-page caveat.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text followed by "button" (or "link"
+     *   for the `href` variant), plus "dimmed" / "unavailable" when `disabled`
+     *   is set (browser/AT dependent wording).
+     * - State change: N/A — this component does not own toggle state. A pressed
+     *   toggle needs `aria-pressed`, which is out of scope here; model that as
+     *   a distinct component or extend the API deliberately per the spec.
+     */
+    interface HTMLDsButtonElement extends Components.DsButton, HTMLStencilElement {
+    }
+    var HTMLDsButtonElement: {
+        prototype: HTMLDsButtonElement;
+        new (): HTMLDsButtonElement;
+    };
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — a container surface with no interactive
+     * behavior of its own. If a consumer nests interactive elements
+     * inside (button, link, form field), those elements satisfy their
+     * own a11y bucket independently.
+     * **Keyboard interactions:**
+     * - Tab / Shift+Tab: N/A — the card itself is not focusable. Any
+     *   interactive descendant carries its own tab semantics.
+     * - Enter / Space / Arrow / Escape / Printable: N/A.
+     * **ARIA:**
+     * - Roles used: none. `<ds-card>` is a purely visual grouping and
+     *   deliberately does not carry `role="region"` — that would demand
+     *   a labelledby target, which would only be correct in a subset of
+     *   uses. Consumers that need a labeled landmark should render a
+     *   `<section aria-labelledby>` around the card.
+     * - State attributes: none.
+     * - Labeling strategy: none applied by the component; consumer's
+     *   heading structure inside the slot supplies the accessible name
+     *   when needed.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - Focus indicator: N/A — the card itself is not focusable.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; the card does
+     *   not impose a text color, so contrast is the consumer theme's
+     *   responsibility.
+     * - Non-text (border, subtle background tint): both derived from
+     *   `color-mix(in oklch, currentColor N%, transparent)`, matching
+     *   the pattern used by `ds-input` and `ds-select`. WCAG 1.4.11
+     *   (3:1 non-text contrast) is met in themes where the surface has
+     *   enough delta against the page background; the component does
+     *   not override the consumer's palette to force it.
+     * **Screen reader announcement:**
+     * - Rendered state: no announcement of the card itself. AT
+     *   navigates to the slotted content directly, using whatever
+     *   heading and landmark structure the consumer places inside.
+     * - State change: N/A.
+     */
+    interface HTMLDsCardElement extends Components.DsCard, HTMLStencilElement {
+    }
+    var HTMLDsCardElement: {
+        prototype: HTMLDsCardElement;
+        new (): HTMLDsCardElement;
+    };
+    interface HTMLDsCheckboxElementEventMap {
+        "dsChange": boolean;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<input type="checkbox">`; the browser already implements the
+     * checkbox role and its state semantics. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
+     * Note: `ds-checkbox` intentionally does NOT reach for the WAI-ARIA
+     * APG "tri-state checkbox" pattern (indeterminate + on + off) as a
+     * scratch-built ARIA widget. The native input already exposes the
+     * `indeterminate` DOM property and browsers report it to AT
+     * correctly; the `indeterminate` prop here forwards to that DOM
+     * property so the native mechanism carries the semantics.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input type="checkbox">`.
+     * - Space: toggles the checked state (native behavior).
+     * - Enter: no native effect on a checkbox (unlike button). Form
+     *   submission triggered by Enter comes from the enclosing form's
+     *   default submit button, not from the checkbox itself.
+     * **ARIA:**
+     * - Roles used: none explicit — the native checkbox supplies the
+     *   implicit `checkbox` role.
+     * - State attributes: `checked` (DOM property, kept in sync via
+     *   componentDidRender because Stencil does not JSX-forward the
+     *   attribute cleanly for controlled use), `disabled` (native
+     *   attribute, not `aria-disabled`), `aria-invalid` (from the
+     *   `invalid` prop), `aria-required` (from the `required` prop),
+     *   `aria-describedby` (from the `describedBy` prop).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal checkbox. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input`.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On toggle: focus remains on the native checkbox.
+     * - Focus indicator: browser default `:focus-visible` ring, kept on
+     *   purpose until the DS ships a themed focus utility using
+     *   `--ds-color-focus`. Not overridden by `ds-checkbox.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: N/A — the checkbox itself renders no text (labels are
+     *   supplied by the consumer via `label` prop or wrapping <label>).
+     * - Non-text (the box and its check glyph): browser default rendering
+     *   is kept on purpose (no `appearance: none` override); this
+     *   preserves the OS/browser accessibility rendering that AT and
+     *   forced-color modes rely on. A themed override is a future
+     *   decision once the DS commits to a checkbox visual language that
+     *   still passes 3:1 non-text contrast in every theme.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "checkbox", followed by "checked"
+     *   / "not checked" / "mixed" per the current DOM state.
+     * - State change: on toggle, AT announces the new state (native
+     *   behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `checked` is the source of truth for controlled use. Reading
+     *   `event.detail` from `dsChange` gives the new state; the internal
+     *   input is kept in sync via a Watch + a re-sync in componentDidRender.
+     * - `indeterminate` is a visual/AT state, not a value — it is NOT
+     *   submitted with a form and clears on the next user toggle.
+     */
+    interface HTMLDsCheckboxElement extends Components.DsCheckbox, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsCheckboxElementEventMap>(type: K, listener: (this: HTMLDsCheckboxElement, ev: DsCheckboxCustomEvent<HTMLDsCheckboxElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsCheckboxElementEventMap>(type: K, listener: (this: HTMLDsCheckboxElement, ev: DsCheckboxCustomEvent<HTMLDsCheckboxElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsCheckboxElement: {
+        prototype: HTMLDsCheckboxElement;
+        new (): HTMLDsCheckboxElement;
+    };
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (for the internal copy control; the code readout itself is static text).
+     * **Keyboard interactions:**
+     * - Tab: moves focus into the internal copy `<button>`; the code readout
+     *   (`<pre><code>`) is not focusable itself, but its container is
+     *   horizontally scrollable and remains reachable via the browser's caret
+     *   browsing / find-in-page path.
+     * - Enter: activates the copy button (writes `code` to the clipboard).
+     * - Space: activates the copy button (native `<button>` behavior).
+     * - Escape: N/A — the "Copied" state auto-clears after 1.4s; no dismissible
+     *   modal state.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` supplies the implicit
+     *   `button` role; `<pre>` and `<code>` supply their semantic roles.
+     * - State attributes: none. The `copied` flag lives only in the button's
+     *   accessible name (see below); it is intentionally not surfaced via
+     *   `aria-pressed` because it is not a toggle — it is a transient
+     *   post-action confirmation.
+     * - Labeling strategy: `aria-label` on the copy button — "Copy code" in the
+     *   resting state, "Copied" while the confirmation is visible. This is
+     *   authoritative because the button carries both an icon and the words
+     *   "Copy" / "Copied", and mixed icon+text needs an explicit accessible
+     *   name to avoid AT reading the SVG as a separate node.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the copy button (clipboard write is
+     *   synchronous from the user's perspective; no focus is moved).
+     * - On close/deactivate: N/A — no popup or overlay to close.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied to `.ds-code-block__copy:focus-visible`. The
+     *   readout itself is not focusable and has no focus indicator by design.
+     * **Motion:**
+     * - Animations: 120ms `color` / `border-color` ease transition on the copy
+     *   button (hover/focus).
+     * - Reduced-motion behavior: N/A — 120ms is below the spec's 200ms
+     *   threshold, and the transition animates color only.
+     * **Contrast:**
+     * - Text (code readout): inherits `color: currentColor`; contrast depends
+     *   on the host page's text color vs. the block's tinted background
+     *   (`color-mix(currentColor 4%, transparent)`). Verify per site.
+     * - Text (copy button): `color-mix(in oklch, currentColor 70%, transparent)`
+     *   at rest, `currentColor` on hover. The 70%-mixed resting color can drop
+     *   below 4.5:1 on low-contrast surfaces — audit per usage site, and lean
+     *   on the hover/focus states (both restore full `currentColor`) as the
+     *   accessible fallback.
+     * - Non-text (button border, language tag border-bottom): both use
+     *   `color-mix(currentColor <15|12>%, transparent)` — decorative separators,
+     *   they do not convey state, so the 3:1 non-text contrast rule does not
+     *   apply. Focus and hover borders shift up to 30% for clearer edges.
+     * **Screen reader announcement:**
+     * - Rendered state: announces "Copy code, button" (the `aria-label`), then
+     *   the code content when the user navigates into the `<pre><code>` block
+     *   (usually announced as a code block on VoiceOver).
+     * - State change: after clicking Copy, the button's `aria-label` flips to
+     *   "Copied"; AT will announce this on the next focus or re-read of the
+     *   button, but NOT proactively — there is no `aria-live` region. This is
+     *   deliberate per spec §"What we explicitly do NOT do" (avoid live-region
+     *   overuse), and the trade-off is that a screen-reader-only user does not
+     *   get an unsolicited confirmation. If a future review decides that
+     *   confirmation must be audible, add a visually-hidden
+     *   `aria-live="polite"` element whose text toggles on `copied`.
+     */
+    interface HTMLDsCodeBlockElement extends Components.DsCodeBlock, HTMLStencilElement {
+    }
+    var HTMLDsCodeBlockElement: {
+        prototype: HTMLDsCodeBlockElement;
+        new (): HTMLDsCodeBlockElement;
+    };
+    interface HTMLDsDialogElementEventMap {
+        "dsOpen": void;
+        "dsClose": void;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** state-machine
+     * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+     * This component wraps the **native `<dialog>` element** rather than
+     * scratch-building the APG pattern on top of a `<div role="dialog">`.
+     * `<dialog>` opened via `showModal()` gives us — from the browser,
+     * verified by the platform, not by us:
+     * - Focus trap: Tab / Shift+Tab cycle only through focusable
+     *   descendants (including slotted light-DOM descendants; the flattened
+     *   accessibility tree is what the trap operates on).
+     * - Escape: closes the dialog and returns focus to the previously
+     *   focused element (native, not implemented here).
+     * - Inert background: everything outside the dialog is inert while it
+     *   is open — no mouse, no keyboard, not part of the a11y tree.
+     * - Return focus: on close, focus returns to whatever element had it
+     *   before `showModal()` — native, not implemented here.
+     * - Initial focus: browser auto-focuses the first `autofocus` element
+     *   inside, or the first focusable if none — native.
+     * - `role="dialog"` and `aria-modal="true"` semantics: implicit on
+     *   `<dialog>`, no ARIA needed from us.
+     * This is the deliberate answer to the a11y spec §D warning about
+     * scratch-building Tier 2 components: the native element removes the
+     * "compiles, axe passes, screen-reader user gets trapped" failure
+     * mode by delegating the state machine to the platform.
+     * **Keyboard interactions (all handled by the native element unless
+     * noted otherwise):**
+     * - Tab: cycles focus within the dialog's focusable descendants
+     *   (native focus trap).
+     * - Shift+Tab: reverse cycle (native).
+     * - Escape: closes the dialog and fires the `close` event (native).
+     *   Consumers who need to prevent dismissal on Escape (destructive
+     *   flows: e.g. an unsaved-changes guard) must call
+     *   `event.preventDefault()` inside their own `keydown` listener on
+     *   the dialog before it reaches the browser — that is an escape
+     *   hatch, not a default we impose.
+     * - Enter / Space: no special dialog behavior; forwarded to
+     *   whatever descendant has focus (a button will activate).
+     * - Home / End / Arrow keys: no special dialog behavior; forwarded
+     *   to descendants.
+     * - Printable characters: forwarded to descendants (e.g. typing
+     *   inside a slotted `<ds-input>`).
+     * **ARIA attributes and value triggers:**
+     * - Implicit `role="dialog"` on the native `<dialog>`.
+     * - Implicit `aria-modal="true"` when opened via `showModal()`
+     *   (which is what this component always uses; `show()` — the
+     *   non-modal form — is intentionally not exposed in v1).
+     * - `aria-label` set from the `label` prop onto the `<dialog>`.
+     *   Consumers who prefer an in-content title can pass a
+     *   `labelledBy` prop instead, whose value is the id of a heading
+     *   element they render inside the slot — `aria-labelledby`
+     *   resolves that id through the flattened tree.
+     * - `aria-describedby` from the `describedBy` prop, resolving a
+     *   light-DOM id of a descriptive block (e.g. the dialog body copy
+     *   when the label is short).
+     * **Focus lifecycle:**
+     * - Opening: `showModal()` moves focus to the first `autofocus`
+     *   element inside, or the first focusable if none. Consumers who
+     *   want a specific initial focus target should mark that element
+     *   with `autofocus`.
+     * - While open: focus is trapped within the flattened tree of the
+     *   `<dialog>`; Tab / Shift+Tab cycle through slotted descendants.
+     *   Focus cannot escape into the inert background.
+     * - Closing: `close()` (either from Escape, from a form-submit with
+     *   `method="dialog"`, from a light-dismiss backdrop click handler
+     *   the consumer wires up, or from `open=false`) returns focus to
+     *   the element that had it immediately before `showModal()` was
+     *   called. The `dsClose` event fires after focus has been restored.
+     * **ARIA labelling contract (choose one):**
+     * - **`label`** (string) — sets `aria-label` on the dialog. Simplest
+     *   for short titles.
+     * - **`labelledBy`** (id) — sets `aria-labelledby` to reference a
+     *   heading rendered inside the slot. Preferred when the dialog has
+     *   a visible title so the accessible name matches the visible name.
+     * If both are omitted, axe reports `dialog-name` — the dialog has no
+     * accessible name. The a11y test for this component asserts that at
+     * least one of the two is provided.
+     * **Motion:**
+     * - Animations: none applied by the component. Consumers who want an
+     *   entrance transition can style `::backdrop` and `dialog[open]`
+     *   with their own animation, gated on `@media
+     *   (prefers-reduced-motion: no-preference)`.
+     * - Reduced-motion behavior: N/A — no animation to collapse. If a
+     *   consumer adds one, they own the reduced-motion fallback.
+     * **Contrast:**
+     * - Text: inherits `color: inherit`; consumer theme owns contrast.
+     * - Non-text: subtle bordered surface via
+     *   `color-mix(in oklch, currentColor N%, transparent)` matching
+     *   `ds-card`. Backdrop is a semi-transparent black by default.
+     * **Screen reader announcement:**
+     * - Rendered state (closed): dialog is not in the a11y tree.
+     * - Opened: AT announces "dialog" plus the accessible name from
+     *   `label` / `labelledBy`, then reads the content following focus
+     *   (or the descriptive block referenced by `describedBy` first,
+     *   depending on AT).
+     * - State change: on close, AT returns to the element that regained
+     *   focus (the trigger); no `aria-live` announcement is added.
+     * **Consumer contract:**
+     * - Set `open` to true to show; set to false to close. The component
+     *   syncs the DOM state via `showModal()` / `close()` in a Watch.
+     * - Listen to `dsClose` to know when the dialog was dismissed (by
+     *   Escape, by `open=false`, or by a form submit with
+     *   `method="dialog"`). Listen to `dsOpen` for the mirror event.
+     * - The default backdrop is opaque and NOT click-to-dismiss. Consumers
+     *   who want light-dismiss can add a click listener on the dialog
+     *   that closes when the click target is the dialog itself (not a
+     *   descendant): `if (e.target === dialog) dialog.close()`.
+     * - Put focus targets (form fields, primary action button) inside
+     *   the slot. Use `autofocus` on the element that should receive
+     *   focus first.
+     * **Pending manual verification (see commit message TODO):**
+     * - VoiceOver on macOS: confirm the dialog announces its accessible
+     *   name + "dialog" on open, focus lands on the correct element,
+     *   Escape closes and focus returns to the trigger.
+     * - Chromium high-contrast / forced-colors: confirm the surface
+     *   still reads as a bordered container with the native ::backdrop
+     *   dim.
+     */
+    interface HTMLDsDialogElement extends Components.DsDialog, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsDialogElementEventMap>(type: K, listener: (this: HTMLDsDialogElement, ev: DsDialogCustomEvent<HTMLDsDialogElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsDialogElementEventMap>(type: K, listener: (this: HTMLDsDialogElement, ev: DsDialogCustomEvent<HTMLDsDialogElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsDialogElement: {
+        prototype: HTMLDsDialogElement;
+        new (): HTMLDsDialogElement;
+    };
+    interface HTMLDsInputElementEventMap {
+        "dsInput": string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native `<input>`;
+     * there is no WAI-ARIA APG pattern for a plain text input because the
+     * browser already implements it natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Printable characters: insert at the caret position (native).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native); for
+     *   `type="number"` Up/Down step the numeric value (native).
+     * - Enter: on `type="search"` may submit the enclosing form (native);
+     *   no custom handling.
+     * - Escape: no native meaning for a text input.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<input>` supplies its
+     *   implicit role (`textbox`, `searchbox`, etc. depending on `type`).
+     * - State attributes: `disabled` (native attribute, not `aria-disabled`),
+     *   `aria-invalid` (from the `invalid` prop), `aria-required` (from the
+     *   `required` prop), `aria-describedby` (from the `describedBy` prop,
+     *   expected to reference a light-DOM node id — typically a hint or
+     *   error message rendered by the consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto the
+     *   internal `<input>`. This is the **canonical, recommended** mode —
+     *   explicit and independent of DOM structure. Consumers MUST pass
+     *   `label` (or otherwise give the field an accessible name) — an
+     *   `<input>` with no accessible name is a WCAG failure (axe rule
+     *   `label`). Wrapping the host in a light-DOM `<label>` (e.g.
+     *   `<label>Email <ds-input></ds-input></label>`) also produces an
+     *   accessible name in Chromium via flattened-tree resolution — the
+     *   same secondary mode documented on `ds-select`, verified in this
+     *   component's e2e tests. Setting `aria-label` directly on the
+     *   `<ds-input>` host does NOT work: shadow-DOM attribute forwarding
+     *   would be required — use the `label` prop instead.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<input>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is kept
+     *   on purpose — a themed focus ring using `--ds-color-focus` is a
+     *   future decision once the DS ships a shared focus utility. Not
+     *   overridden by `ds-input.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends on
+     *   the consumer's theme, not verified in isolation here.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-select` — inherits whatever contrast the host page
+     *   sets. WCAG 1.4.11 (3:1 non-text) is the consumer's responsibility
+     *   in themes that override the surface.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the accessible
+     *   name, followed by the browser/AT's role announcement for the
+     *   input type ("edit text", "search text", "password", "phone
+     *   number", "email"…). When `required=true` the announcement
+     *   includes "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native input behavior); no `aria-live` added, per the
+     *   spec's guidance against live-region overuse.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label. It disappears on focus in
+     *   most browsers and is not reliably announced by every AT — always
+     *   pair with `label`.
+     * - For `type="password"` in a real form, pair with a light-DOM
+     *   `<input type="hidden">` or a form-associated ancestor that gives
+     *   the browser's password manager an `autocomplete` hint. This
+     *   component intentionally does not expose `autocomplete` in v1;
+     *   consumers that need it can render a native `<input>` for that
+     *   field until the prop is added.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     */
+    interface HTMLDsInputElement extends Components.DsInput, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsInputElementEventMap>(type: K, listener: (this: HTMLDsInputElement, ev: DsInputCustomEvent<HTMLDsInputElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsInputElementEventMap>(type: K, listener: (this: HTMLDsInputElement, ev: DsInputCustomEvent<HTMLDsInputElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsInputElement: {
+        prototype: HTMLDsInputElement;
+        new (): HTMLDsInputElement;
+    };
+    /**
+     * ## Accessibility
+     * **Category:** static-display (indeterminate progress indicator)
+     * **APG pattern:** N/A — the loader is a passive presence indicator, not a
+     * `progressbar` (no measurable value). Uses `role="status"` per WAI-ARIA
+     * live-region semantics for indeterminate loading states.
+     * **Keyboard interactions:**
+     * - Tab: N/A — not focusable.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: `role="status"` on the host — an implicit polite live
+     *   region ARIA lists as valid for "advisory information" including
+     *   in-progress operations. The inner `<svg>` is decorative and carries
+     *   `aria-hidden="true"` + `focusable="false"` so it never becomes a
+     *   parallel target for screen readers.
+     * - State attributes: none. The loader has no state changes to announce
+     *   beyond its own presence; the polite live region on mount is the
+     *   announcement.
+     * - Labeling strategy: `aria-label` from the `label` prop (default
+     *   "Loading"). Consumers pass a more specific string when the context
+     *   warrants ("Loading ceremonies", "Signing in", …).
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — not interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable.
+     * **Motion:**
+     * - Animations: two mirrored halves of the logo path oscillate
+     *   symmetrically around the visual center, meeting at the ring midpoint
+     *   and separating again. Cycle 1.4s by default (`speed="normal"`);
+     *   `speed="slow"` = 2.2s, `speed="fast"` = 0.9s.
+     * - Reduced-motion behavior: `@media (prefers-reduced-motion: reduce)`
+     *   collapses both halves to a static rendering with a slow opacity
+     *   pulse (2s ease-in-out). No rotation, no lateral movement.
+     * **Contrast:**
+     * - Text: N/A — the visible surface is the SVG stroke, not text.
+     * - Non-text: stroke inherits `currentColor` from the host. Consumers are
+     *   responsible for confirming the stroke against its background meets
+     *   the ≥ 3:1 non-text contrast threshold (WCAG 1.4.11) where the loader
+     *   conveys state (e.g. distinguishing "still loading" from "idle").
+     * **Screen reader announcement:**
+     * - Rendered state: the polite live region announces the label
+     *   (e.g. "Loading") when the loader mounts.
+     * - State change: N/A — the loader itself has no state that changes.
+     *   Consumers unmount the loader when the awaited work completes; that
+     *   removal is silent, which is the intended behavior (the arriving
+     *   content is the announcement).
+     */
+    interface HTMLDsLoaderElement extends Components.DsLoader, HTMLStencilElement {
+    }
+    var HTMLDsLoaderElement: {
+        prototype: HTMLDsLoaderElement;
+        new (): HTMLDsLoaderElement;
+    };
+    interface HTMLDsSelectElementEventMap {
+        "dsChange": string;
+    }
+    interface HTMLDsSelectElement extends Components.DsSelect, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsSelectElementEventMap>(type: K, listener: (this: HTMLDsSelectElement, ev: DsSelectCustomEvent<HTMLDsSelectElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsSelectElementEventMap>(type: K, listener: (this: HTMLDsSelectElement, ev: DsSelectCustomEvent<HTMLDsSelectElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsSelectElement: {
+        prototype: HTMLDsSelectElement;
+        new (): HTMLDsSelectElement;
+    };
+    interface HTMLDsTabsElementEventMap {
+        "dsChange": string;
+    }
+    interface HTMLDsTabsElement extends Components.DsTabs, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsTabsElementEventMap>(type: K, listener: (this: HTMLDsTabsElement, ev: DsTabsCustomEvent<HTMLDsTabsElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsTabsElementEventMap>(type: K, listener: (this: HTMLDsTabsElement, ev: DsTabsCustomEvent<HTMLDsTabsElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsTabsElement: {
+        prototype: HTMLDsTabsElement;
+        new (): HTMLDsTabsElement;
+    };
+    interface HTMLDsTextareaElementEventMap {
+        "dsInput": string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<textarea>`; there is no WAI-ARIA APG pattern for a plain
+     * multi-line text field because the browser already implements it
+     * natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<textarea>`; Tab inside the
+     *   textarea inserts a tab character only when the browser is
+     *   configured to do so (default behavior: Tab moves focus out).
+     * - Printable characters: insert at the caret position (native).
+     * - Enter: inserts a newline within the value (native), does not
+     *   submit the enclosing form (unlike a single-line input).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native).
+     * - Escape: no native meaning for a text area.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<textarea>` supplies
+     *   the implicit `textbox` role with multiline behavior.
+     * - State attributes: `disabled` (native attribute, not
+     *   `aria-disabled`), `aria-invalid` (from the `invalid` prop),
+     *   `aria-required` (from the `required` prop), `aria-describedby`
+     *   (from the `describedBy` prop, expected to reference a light-DOM
+     *   node id — typically a hint or error message rendered by the
+     *   consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal `<textarea>`. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input` and `ds-select`,
+     *   verified in this component's e2e tests. Setting `aria-label`
+     *   directly on the `<ds-textarea>` host does NOT work: shadow-DOM
+     *   attribute forwarding would be required — use the `label` prop.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<textarea>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is
+     *   kept on purpose — a themed focus ring using `--ds-color-focus`
+     *   is a future decision once the DS ships a shared focus utility.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends
+     *   on the consumer's theme, not verified in isolation.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-input`.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "edit text, multiline" (browser/AT
+     *   wording varies). When `required=true` the announcement includes
+     *   "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label — always pair with `label`.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     * - `rows` sets the initial visible line count. Vertical resize is
+     *   left to the native default (`resize: vertical`) so users can
+     *   grow the field for long entries; the consumer's CSS can pin it
+     *   with `resize: none` when a fixed height matters.
+     */
+    interface HTMLDsTextareaElement extends Components.DsTextarea, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsTextareaElementEventMap>(type: K, listener: (this: HTMLDsTextareaElement, ev: DsTextareaCustomEvent<HTMLDsTextareaElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsTextareaElementEventMap>(type: K, listener: (this: HTMLDsTextareaElement, ev: DsTextareaCustomEvent<HTMLDsTextareaElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsTextareaElement: {
+        prototype: HTMLDsTextareaElement;
+        new (): HTMLDsTextareaElement;
+    };
+    interface HTMLDsTooltipElement extends Components.DsTooltip, HTMLStencilElement {
+    }
+    var HTMLDsTooltipElement: {
+        prototype: HTMLDsTooltipElement;
+        new (): HTMLDsTooltipElement;
+    };
+    interface HTMLElementTagNameMap {
+        "ds-badge": HTMLDsBadgeElement;
+        "ds-button": HTMLDsButtonElement;
+        "ds-card": HTMLDsCardElement;
+        "ds-checkbox": HTMLDsCheckboxElement;
+        "ds-code-block": HTMLDsCodeBlockElement;
+        "ds-dialog": HTMLDsDialogElement;
+        "ds-input": HTMLDsInputElement;
+        "ds-loader": HTMLDsLoaderElement;
+        "ds-select": HTMLDsSelectElement;
+        "ds-tabs": HTMLDsTabsElement;
+        "ds-textarea": HTMLDsTextareaElement;
+        "ds-tooltip": HTMLDsTooltipElement;
+    }
+}
+declare namespace LocalJSX {
+    type OneOf<K extends string, PropT, AttrT = PropT> = { [P in K]: PropT } & { [P in `attr:${K}` | `prop:${K}`]?: never } | { [P in `attr:${K}`]: AttrT } & { [P in K | `prop:${K}`]?: never } | { [P in `prop:${K}`]: PropT } & { [P in K | `attr:${K}`]?: never };
+
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — non-interactive text label.
+     * **Keyboard interactions:**
+     * - Tab: N/A — the badge is not focusable and does not appear in tab order.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none — renders a plain `<span>` around a `<slot />`. The
+     *   `variant` prop is a purely visual axis and MUST NOT be the sole carrier
+     *   of information (color/style alone fails WCAG 1.4.1 Use of Color); the
+     *   textual content inside the slot must convey the same meaning.
+     * - State attributes: none.
+     * - Labeling strategy: visible text via `<slot />`. Consumers place the
+     *   readable label directly inside the tag.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — non-interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable. If a consumer wraps
+     *   `ds-badge` in an interactive element (e.g. `<button>`, `<a>`), that
+     *   wrapper owns the focus indicator via the DS `--ds-color-focus` token
+     *   and its own `:focus-visible` rule.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor` from the host page and
+     *   the variant-specific style; not verified in isolation here. Consumers
+     *   are responsible for confirming ≥ 4.5:1 (WCAG 1.4.3) against the surface
+     *   the badge is placed on.
+     * - Non-text: no state-conveying icons or borders that need the 3:1
+     *   non-text contrast threshold.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text as inline content within its
+     *   surrounding context (no role means AT reads it as plain text). The
+     *   `variant` value is not announced — that is intentional; the label text
+     *   is the source of truth for meaning.
+     * - State change: N/A — no dynamic state owned by this component.
+     */
+    interface DsBadge {
+        /**
+          * @default "neutral"
+         */
+        "variant"?: | "neutral"
+    | "ui-component"
+    | "recipe"
+    | "agent"
+    | "config";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (satisfied natively by the underlying `<button>` element). When `href` is
+     * set, the component renders `<a href>` instead — a link, not a button — and
+     * that surface follows native `<a>` semantics rather than the Button pattern.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the internal `<button>` or `<a>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Enter: activates (fires click on `<button>`, navigates on `<a>`).
+     * - Space: activates the `<button>` variant only (native behavior); on the
+     *   `<a>` variant Space scrolls the page as usual.
+     * - Escape: N/A — no dismissible state owned by this component.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` / `<a href>` supplies
+     *   the implicit `button` / `link` role.
+     * - State attributes: `disabled` (native attribute on `<button>`, not
+     *   `aria-disabled`). The `<a>` variant does not accept `disabled` — a
+     *   disabled navigation is a spec smell (see spec §"Button vs Link"); if a
+     *   link needs a disabled state, model it as a `<button>` action instead.
+     * - Labeling strategy: visible text via `<slot />`. Consumers MUST place
+     *   readable text (or a labeled icon) inside the tag. An empty slot leaves
+     *   the button/link without an accessible name and fails
+     *   `button-name` / `link-name` axe rules. Icon-only usage is out of contract
+     *   for `ds-button`; use a future `ds-icon-button` with a required
+     *   `aria-label` prop when that lands.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the element (native click behavior; the
+     *   component does not move focus on its own).
+     * - On close/deactivate: N/A.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied via `:focus-visible` — replaces the browser
+     *   default so both `<button>` and `<a>` variants use the same DS ring
+     *   (spec universal rule 3, WCAG 1.4.11 non-text contrast ≥ 3:1).
+     * **Motion:**
+     * - Animations: 150ms `background-color` ease-in-out transition on
+     *   `primary`/`secondary` variants (hover).
+     * - Reduced-motion behavior: N/A — 150ms is below the spec's 200ms threshold
+     *   for `prefers-reduced-motion` handling, and the transition animates color
+     *   only (no motion of position, scale, or opacity).
+     * **Contrast:**
+     * - Text: `primary` and `secondary` variants pair `--ds-color-{primary,secondary}`
+     *   with `--ds-color-text-on-{primary,secondary}` — the token pairs are
+     *   authored to meet WCAG 2.1 AA (≥ 4.5:1). The `ghost` variant inherits
+     *   `color: inherit` and pins `opacity: 0.85`, so its effective contrast
+     *   depends on the consumer's surface — verify per site.
+     * - Non-text (border on `ghost`): 1px `currentColor`; contrast tracks the
+     *   text color 1:1, subject to the same host-page caveat.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the slot text followed by "button" (or "link"
+     *   for the `href` variant), plus "dimmed" / "unavailable" when `disabled`
+     *   is set (browser/AT dependent wording).
+     * - State change: N/A — this component does not own toggle state. A pressed
+     *   toggle needs `aria-pressed`, which is out of scope here; model that as
+     *   a distinct component or extend the API deliberately per the spec.
+     */
+    interface DsButton {
+        /**
+          * @default false
+         */
+        "disabled"?: boolean;
+        "href"?: string;
+        /**
+          * @default "md"
+         */
+        "size"?: "md" | "lg";
+        /**
+          * @default "button"
+         */
+        "type"?: "button" | "submit" | "reset";
+        /**
+          * @default "primary"
+         */
+        "variant"?: "primary" | "secondary" | "ghost";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** static-display
+     * **APG pattern:** N/A — a container surface with no interactive
+     * behavior of its own. If a consumer nests interactive elements
+     * inside (button, link, form field), those elements satisfy their
+     * own a11y bucket independently.
+     * **Keyboard interactions:**
+     * - Tab / Shift+Tab: N/A — the card itself is not focusable. Any
+     *   interactive descendant carries its own tab semantics.
+     * - Enter / Space / Arrow / Escape / Printable: N/A.
+     * **ARIA:**
+     * - Roles used: none. `<ds-card>` is a purely visual grouping and
+     *   deliberately does not carry `role="region"` — that would demand
+     *   a labelledby target, which would only be correct in a subset of
+     *   uses. Consumers that need a labeled landmark should render a
+     *   `<section aria-labelledby>` around the card.
+     * - State attributes: none.
+     * - Labeling strategy: none applied by the component; consumer's
+     *   heading structure inside the slot supplies the accessible name
+     *   when needed.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - Focus indicator: N/A — the card itself is not focusable.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; the card does
+     *   not impose a text color, so contrast is the consumer theme's
+     *   responsibility.
+     * - Non-text (border, subtle background tint): both derived from
+     *   `color-mix(in oklch, currentColor N%, transparent)`, matching
+     *   the pattern used by `ds-input` and `ds-select`. WCAG 1.4.11
+     *   (3:1 non-text contrast) is met in themes where the surface has
+     *   enough delta against the page background; the component does
+     *   not override the consumer's palette to force it.
+     * **Screen reader announcement:**
+     * - Rendered state: no announcement of the card itself. AT
+     *   navigates to the slotted content directly, using whatever
+     *   heading and landmark structure the consumer places inside.
+     * - State change: N/A.
+     */
+    interface DsCard {
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<input type="checkbox">`; the browser already implements the
+     * checkbox role and its state semantics. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
+     * Note: `ds-checkbox` intentionally does NOT reach for the WAI-ARIA
+     * APG "tri-state checkbox" pattern (indeterminate + on + off) as a
+     * scratch-built ARIA widget. The native input already exposes the
+     * `indeterminate` DOM property and browsers report it to AT
+     * correctly; the `indeterminate` prop here forwards to that DOM
+     * property so the native mechanism carries the semantics.
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input type="checkbox">`.
+     * - Space: toggles the checked state (native behavior).
+     * - Enter: no native effect on a checkbox (unlike button). Form
+     *   submission triggered by Enter comes from the enclosing form's
+     *   default submit button, not from the checkbox itself.
+     * **ARIA:**
+     * - Roles used: none explicit — the native checkbox supplies the
+     *   implicit `checkbox` role.
+     * - State attributes: `checked` (DOM property, kept in sync via
+     *   componentDidRender because Stencil does not JSX-forward the
+     *   attribute cleanly for controlled use), `disabled` (native
+     *   attribute, not `aria-disabled`), `aria-invalid` (from the
+     *   `invalid` prop), `aria-required` (from the `required` prop),
+     *   `aria-describedby` (from the `describedBy` prop).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal checkbox. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input`.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On toggle: focus remains on the native checkbox.
+     * - Focus indicator: browser default `:focus-visible` ring, kept on
+     *   purpose until the DS ships a themed focus utility using
+     *   `--ds-color-focus`. Not overridden by `ds-checkbox.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A.
+     * **Contrast:**
+     * - Text: N/A — the checkbox itself renders no text (labels are
+     *   supplied by the consumer via `label` prop or wrapping <label>).
+     * - Non-text (the box and its check glyph): browser default rendering
+     *   is kept on purpose (no `appearance: none` override); this
+     *   preserves the OS/browser accessibility rendering that AT and
+     *   forced-color modes rely on. A themed override is a future
+     *   decision once the DS commits to a checkbox visual language that
+     *   still passes 3:1 non-text contrast in every theme.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "checkbox", followed by "checked"
+     *   / "not checked" / "mixed" per the current DOM state.
+     * - State change: on toggle, AT announces the new state (native
+     *   behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `checked` is the source of truth for controlled use. Reading
+     *   `event.detail` from `dsChange` gives the new state; the internal
+     *   input is kept in sync via a Watch + a re-sync in componentDidRender.
+     * - `indeterminate` is a visual/AT state, not a value — it is NOT
+     *   submitted with a form and clears on the next user toggle.
+     */
+    interface DsCheckbox {
+        /**
+          * @default false
+         */
+        "checked"?: boolean;
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * @default false
+         */
+        "indeterminate"?: boolean;
+        /**
+          * @default false
+         */
+        "invalid"?: boolean;
+        "label"?: string;
+        "name"?: string;
+        "onDsChange"?: (event: DsCheckboxCustomEvent<boolean>) => void;
+        /**
+          * @default false
+         */
+        "required"?: boolean;
+        "value"?: string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** interactive-display
+     * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+     * (for the internal copy control; the code readout itself is static text).
+     * **Keyboard interactions:**
+     * - Tab: moves focus into the internal copy `<button>`; the code readout
+     *   (`<pre><code>`) is not focusable itself, but its container is
+     *   horizontally scrollable and remains reachable via the browser's caret
+     *   browsing / find-in-page path.
+     * - Enter: activates the copy button (writes `code` to the clipboard).
+     * - Space: activates the copy button (native `<button>` behavior).
+     * - Escape: N/A — the "Copied" state auto-clears after 1.4s; no dismissible
+     *   modal state.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<button>` supplies the implicit
+     *   `button` role; `<pre>` and `<code>` supply their semantic roles.
+     * - State attributes: none. The `copied` flag lives only in the button's
+     *   accessible name (see below); it is intentionally not surfaced via
+     *   `aria-pressed` because it is not a toggle — it is a transient
+     *   post-action confirmation.
+     * - Labeling strategy: `aria-label` on the copy button — "Copy code" in the
+     *   resting state, "Copied" while the confirmation is visible. This is
+     *   authoritative because the button carries both an icon and the words
+     *   "Copy" / "Copied", and mixed icon+text needs an explicit accessible
+     *   name to avoid AT reading the SVG as a separate node.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate: focus stays on the copy button (clipboard write is
+     *   synchronous from the user's perspective; no focus is moved).
+     * - On close/deactivate: N/A — no popup or overlay to close.
+     * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+     *   `outline-offset`, applied to `.ds-code-block__copy:focus-visible`. The
+     *   readout itself is not focusable and has no focus indicator by design.
+     * **Motion:**
+     * - Animations: 120ms `color` / `border-color` ease transition on the copy
+     *   button (hover/focus).
+     * - Reduced-motion behavior: N/A — 120ms is below the spec's 200ms
+     *   threshold, and the transition animates color only.
+     * **Contrast:**
+     * - Text (code readout): inherits `color: currentColor`; contrast depends
+     *   on the host page's text color vs. the block's tinted background
+     *   (`color-mix(currentColor 4%, transparent)`). Verify per site.
+     * - Text (copy button): `color-mix(in oklch, currentColor 70%, transparent)`
+     *   at rest, `currentColor` on hover. The 70%-mixed resting color can drop
+     *   below 4.5:1 on low-contrast surfaces — audit per usage site, and lean
+     *   on the hover/focus states (both restore full `currentColor`) as the
+     *   accessible fallback.
+     * - Non-text (button border, language tag border-bottom): both use
+     *   `color-mix(currentColor <15|12>%, transparent)` — decorative separators,
+     *   they do not convey state, so the 3:1 non-text contrast rule does not
+     *   apply. Focus and hover borders shift up to 30% for clearer edges.
+     * **Screen reader announcement:**
+     * - Rendered state: announces "Copy code, button" (the `aria-label`), then
+     *   the code content when the user navigates into the `<pre><code>` block
+     *   (usually announced as a code block on VoiceOver).
+     * - State change: after clicking Copy, the button's `aria-label` flips to
+     *   "Copied"; AT will announce this on the next focus or re-read of the
+     *   button, but NOT proactively — there is no `aria-live` region. This is
+     *   deliberate per spec §"What we explicitly do NOT do" (avoid live-region
+     *   overuse), and the trade-off is that a screen-reader-only user does not
+     *   get an unsolicited confirmation. If a future review decides that
+     *   confirmation must be audible, add a visually-hidden
+     *   `aria-live="polite"` element whose text toggles on `copied`.
+     */
+    interface DsCodeBlock {
+        "code": string;
+        /**
+          * @default "bash"
+         */
+        "language"?: string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** state-machine
+     * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+     * This component wraps the **native `<dialog>` element** rather than
+     * scratch-building the APG pattern on top of a `<div role="dialog">`.
+     * `<dialog>` opened via `showModal()` gives us — from the browser,
+     * verified by the platform, not by us:
+     * - Focus trap: Tab / Shift+Tab cycle only through focusable
+     *   descendants (including slotted light-DOM descendants; the flattened
+     *   accessibility tree is what the trap operates on).
+     * - Escape: closes the dialog and returns focus to the previously
+     *   focused element (native, not implemented here).
+     * - Inert background: everything outside the dialog is inert while it
+     *   is open — no mouse, no keyboard, not part of the a11y tree.
+     * - Return focus: on close, focus returns to whatever element had it
+     *   before `showModal()` — native, not implemented here.
+     * - Initial focus: browser auto-focuses the first `autofocus` element
+     *   inside, or the first focusable if none — native.
+     * - `role="dialog"` and `aria-modal="true"` semantics: implicit on
+     *   `<dialog>`, no ARIA needed from us.
+     * This is the deliberate answer to the a11y spec §D warning about
+     * scratch-building Tier 2 components: the native element removes the
+     * "compiles, axe passes, screen-reader user gets trapped" failure
+     * mode by delegating the state machine to the platform.
+     * **Keyboard interactions (all handled by the native element unless
+     * noted otherwise):**
+     * - Tab: cycles focus within the dialog's focusable descendants
+     *   (native focus trap).
+     * - Shift+Tab: reverse cycle (native).
+     * - Escape: closes the dialog and fires the `close` event (native).
+     *   Consumers who need to prevent dismissal on Escape (destructive
+     *   flows: e.g. an unsaved-changes guard) must call
+     *   `event.preventDefault()` inside their own `keydown` listener on
+     *   the dialog before it reaches the browser — that is an escape
+     *   hatch, not a default we impose.
+     * - Enter / Space: no special dialog behavior; forwarded to
+     *   whatever descendant has focus (a button will activate).
+     * - Home / End / Arrow keys: no special dialog behavior; forwarded
+     *   to descendants.
+     * - Printable characters: forwarded to descendants (e.g. typing
+     *   inside a slotted `<ds-input>`).
+     * **ARIA attributes and value triggers:**
+     * - Implicit `role="dialog"` on the native `<dialog>`.
+     * - Implicit `aria-modal="true"` when opened via `showModal()`
+     *   (which is what this component always uses; `show()` — the
+     *   non-modal form — is intentionally not exposed in v1).
+     * - `aria-label` set from the `label` prop onto the `<dialog>`.
+     *   Consumers who prefer an in-content title can pass a
+     *   `labelledBy` prop instead, whose value is the id of a heading
+     *   element they render inside the slot — `aria-labelledby`
+     *   resolves that id through the flattened tree.
+     * - `aria-describedby` from the `describedBy` prop, resolving a
+     *   light-DOM id of a descriptive block (e.g. the dialog body copy
+     *   when the label is short).
+     * **Focus lifecycle:**
+     * - Opening: `showModal()` moves focus to the first `autofocus`
+     *   element inside, or the first focusable if none. Consumers who
+     *   want a specific initial focus target should mark that element
+     *   with `autofocus`.
+     * - While open: focus is trapped within the flattened tree of the
+     *   `<dialog>`; Tab / Shift+Tab cycle through slotted descendants.
+     *   Focus cannot escape into the inert background.
+     * - Closing: `close()` (either from Escape, from a form-submit with
+     *   `method="dialog"`, from a light-dismiss backdrop click handler
+     *   the consumer wires up, or from `open=false`) returns focus to
+     *   the element that had it immediately before `showModal()` was
+     *   called. The `dsClose` event fires after focus has been restored.
+     * **ARIA labelling contract (choose one):**
+     * - **`label`** (string) — sets `aria-label` on the dialog. Simplest
+     *   for short titles.
+     * - **`labelledBy`** (id) — sets `aria-labelledby` to reference a
+     *   heading rendered inside the slot. Preferred when the dialog has
+     *   a visible title so the accessible name matches the visible name.
+     * If both are omitted, axe reports `dialog-name` — the dialog has no
+     * accessible name. The a11y test for this component asserts that at
+     * least one of the two is provided.
+     * **Motion:**
+     * - Animations: none applied by the component. Consumers who want an
+     *   entrance transition can style `::backdrop` and `dialog[open]`
+     *   with their own animation, gated on `@media
+     *   (prefers-reduced-motion: no-preference)`.
+     * - Reduced-motion behavior: N/A — no animation to collapse. If a
+     *   consumer adds one, they own the reduced-motion fallback.
+     * **Contrast:**
+     * - Text: inherits `color: inherit`; consumer theme owns contrast.
+     * - Non-text: subtle bordered surface via
+     *   `color-mix(in oklch, currentColor N%, transparent)` matching
+     *   `ds-card`. Backdrop is a semi-transparent black by default.
+     * **Screen reader announcement:**
+     * - Rendered state (closed): dialog is not in the a11y tree.
+     * - Opened: AT announces "dialog" plus the accessible name from
+     *   `label` / `labelledBy`, then reads the content following focus
+     *   (or the descriptive block referenced by `describedBy` first,
+     *   depending on AT).
+     * - State change: on close, AT returns to the element that regained
+     *   focus (the trigger); no `aria-live` announcement is added.
+     * **Consumer contract:**
+     * - Set `open` to true to show; set to false to close. The component
+     *   syncs the DOM state via `showModal()` / `close()` in a Watch.
+     * - Listen to `dsClose` to know when the dialog was dismissed (by
+     *   Escape, by `open=false`, or by a form submit with
+     *   `method="dialog"`). Listen to `dsOpen` for the mirror event.
+     * - The default backdrop is opaque and NOT click-to-dismiss. Consumers
+     *   who want light-dismiss can add a click listener on the dialog
+     *   that closes when the click target is the dialog itself (not a
+     *   descendant): `if (e.target === dialog) dialog.close()`.
+     * - Put focus targets (form fields, primary action button) inside
+     *   the slot. Use `autofocus` on the element that should receive
+     *   focus first.
+     * **Pending manual verification (see commit message TODO):**
+     * - VoiceOver on macOS: confirm the dialog announces its accessible
+     *   name + "dialog" on open, focus lands on the correct element,
+     *   Escape closes and focus returns to the trigger.
+     * - Chromium high-contrast / forced-colors: confirm the surface
+     *   still reads as a bordered container with the native ::backdrop
+     *   dim.
+     */
+    interface DsDialog {
+        "describedBy"?: string;
+        "label"?: string;
+        "labelledBy"?: string;
+        "onDsClose"?: (event: DsDialogCustomEvent<void>) => void;
+        "onDsOpen"?: (event: DsDialogCustomEvent<void>) => void;
+        /**
+          * @default false
+         */
+        "open"?: boolean;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native `<input>`;
+     * there is no WAI-ARIA APG pattern for a plain text input because the
+     * browser already implements it natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<input>` (shadow DOM does not
+     *   interrupt tab order).
+     * - Printable characters: insert at the caret position (native).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native); for
+     *   `type="number"` Up/Down step the numeric value (native).
+     * - Enter: on `type="search"` may submit the enclosing form (native);
+     *   no custom handling.
+     * - Escape: no native meaning for a text input.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<input>` supplies its
+     *   implicit role (`textbox`, `searchbox`, etc. depending on `type`).
+     * - State attributes: `disabled` (native attribute, not `aria-disabled`),
+     *   `aria-invalid` (from the `invalid` prop), `aria-required` (from the
+     *   `required` prop), `aria-describedby` (from the `describedBy` prop,
+     *   expected to reference a light-DOM node id — typically a hint or
+     *   error message rendered by the consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto the
+     *   internal `<input>`. This is the **canonical, recommended** mode —
+     *   explicit and independent of DOM structure. Consumers MUST pass
+     *   `label` (or otherwise give the field an accessible name) — an
+     *   `<input>` with no accessible name is a WCAG failure (axe rule
+     *   `label`). Wrapping the host in a light-DOM `<label>` (e.g.
+     *   `<label>Email <ds-input></ds-input></label>`) also produces an
+     *   accessible name in Chromium via flattened-tree resolution — the
+     *   same secondary mode documented on `ds-select`, verified in this
+     *   component's e2e tests. Setting `aria-label` directly on the
+     *   `<ds-input>` host does NOT work: shadow-DOM attribute forwarding
+     *   would be required — use the `label` prop instead.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<input>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is kept
+     *   on purpose — a themed focus ring using `--ds-color-focus` is a
+     *   future decision once the DS ships a shared focus utility. Not
+     *   overridden by `ds-input.css`.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends on
+     *   the consumer's theme, not verified in isolation here.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-select` — inherits whatever contrast the host page
+     *   sets. WCAG 1.4.11 (3:1 non-text) is the consumer's responsibility
+     *   in themes that override the surface.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the accessible
+     *   name, followed by the browser/AT's role announcement for the
+     *   input type ("edit text", "search text", "password", "phone
+     *   number", "email"…). When `required=true` the announcement
+     *   includes "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native input behavior); no `aria-live` added, per the
+     *   spec's guidance against live-region overuse.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label. It disappears on focus in
+     *   most browsers and is not reliably announced by every AT — always
+     *   pair with `label`.
+     * - For `type="password"` in a real form, pair with a light-DOM
+     *   `<input type="hidden">` or a form-associated ancestor that gives
+     *   the browser's password manager an `autocomplete` hint. This
+     *   component intentionally does not expose `autocomplete` in v1;
+     *   consumers that need it can render a native `<input>` for that
+     *   field until the prop is added.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     */
+    interface DsInput {
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * @default false
+         */
+        "invalid"?: boolean;
+        "label"?: string;
+        "name"?: string;
+        "onDsInput"?: (event: DsInputCustomEvent<string>) => void;
+        "placeholder"?: string;
+        /**
+          * @default false
+         */
+        "required"?: boolean;
+        /**
+          * @default "md"
+         */
+        "size"?: "md" | "lg";
+        /**
+          * @default "text"
+         */
+        "type"?: | "text"
+    | "email"
+    | "password"
+    | "search"
+    | "tel"
+    | "url"
+    | "number";
+        "value"?: string;
+    }
+    /**
+     * ## Accessibility
+     * **Category:** static-display (indeterminate progress indicator)
+     * **APG pattern:** N/A — the loader is a passive presence indicator, not a
+     * `progressbar` (no measurable value). Uses `role="status"` per WAI-ARIA
+     * live-region semantics for indeterminate loading states.
+     * **Keyboard interactions:**
+     * - Tab: N/A — not focusable.
+     * - Enter: N/A.
+     * - Escape: N/A.
+     * - Arrow keys: N/A.
+     * - Printable characters: N/A.
+     * **ARIA:**
+     * - Roles used: `role="status"` on the host — an implicit polite live
+     *   region ARIA lists as valid for "advisory information" including
+     *   in-progress operations. The inner `<svg>` is decorative and carries
+     *   `aria-hidden="true"` + `focusable="false"` so it never becomes a
+     *   parallel target for screen readers.
+     * - State attributes: none. The loader has no state changes to announce
+     *   beyond its own presence; the polite live region on mount is the
+     *   announcement.
+     * - Labeling strategy: `aria-label` from the `label` prop (default
+     *   "Loading"). Consumers pass a more specific string when the context
+     *   warrants ("Loading ceremonies", "Signing in", …).
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On activate/open: N/A — not interactive.
+     * - On close/deactivate: N/A.
+     * - Focus indicator: N/A — the host is not focusable.
+     * **Motion:**
+     * - Animations: two mirrored halves of the logo path oscillate
+     *   symmetrically around the visual center, meeting at the ring midpoint
+     *   and separating again. Cycle 1.4s by default (`speed="normal"`);
+     *   `speed="slow"` = 2.2s, `speed="fast"` = 0.9s.
+     * - Reduced-motion behavior: `@media (prefers-reduced-motion: reduce)`
+     *   collapses both halves to a static rendering with a slow opacity
+     *   pulse (2s ease-in-out). No rotation, no lateral movement.
+     * **Contrast:**
+     * - Text: N/A — the visible surface is the SVG stroke, not text.
+     * - Non-text: stroke inherits `currentColor` from the host. Consumers are
+     *   responsible for confirming the stroke against its background meets
+     *   the ≥ 3:1 non-text contrast threshold (WCAG 1.4.11) where the loader
+     *   conveys state (e.g. distinguishing "still loading" from "idle").
+     * **Screen reader announcement:**
+     * - Rendered state: the polite live region announces the label
+     *   (e.g. "Loading") when the loader mounts.
+     * - State change: N/A — the loader itself has no state that changes.
+     *   Consumers unmount the loader when the awaited work completes; that
+     *   removal is silent, which is the intended behavior (the arriving
+     *   content is the announcement).
+     */
+    interface DsLoader {
+        /**
+          * @default "Loading"
+         */
+        "label"?: string;
+        /**
+          * @default "md"
+         */
+        "size"?: "sm" | "md" | "lg";
+        /**
+          * @default "normal"
+         */
+        "speed"?: "slow" | "normal" | "fast";
+    }
+    interface DsSelect {
+        /**
+          * @default false
+         */
+        "disabled"?: boolean;
+        "label"?: string;
+        "name"?: string;
+        "onDsChange"?: (event: DsSelectCustomEvent<string>) => void;
+        /**
+          * Options rendered inside the internal shadow `<select>`. Accepts either: - a JSON string (SSR-friendly — server-rendered HTML can only set   string attributes, and Stencil does not JSON-parse array attributes),   e.g. `options='[{"value":"en","label":"EN"}]'` - an array property set from client-side JS,   e.g. `el.options = [{ value: 'en', label: 'EN' }]`  Malformed JSON fails safe to an empty list rather than throwing, so the component still renders a visible (if empty) select.
+          * @default "[]"
+         */
+        "options"?: string | ReadonlyArray<DsSelectOption>;
+        /**
+          * @default "md"
+         */
+        "size"?: "md" | "lg";
+        "value"?: string;
+    }
+    interface DsTabs {
+        "active"?: string;
+        /**
+          * @default "[]"
+         */
+        "items"?: string | ReadonlyArray<DsTabItem>;
+        "label"?: string;
+        "onDsChange"?: (event: DsTabsCustomEvent<string>) => void;
+        /**
+          * @default "horizontal"
+         */
+        "orientation"?: "horizontal" | "vertical";
+    }
+    /**
+     * ## Accessibility
+     * **Category:** form-field
+     * **APG pattern:** N/A — native element. This wraps a native
+     * `<textarea>`; there is no WAI-ARIA APG pattern for a plain
+     * multi-line text field because the browser already implements it
+     * natively. Reference:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+     * **Keyboard interactions:**
+     * - Tab: moves focus to the native `<textarea>`; Tab inside the
+     *   textarea inserts a tab character only when the browser is
+     *   configured to do so (default behavior: Tab moves focus out).
+     * - Printable characters: insert at the caret position (native).
+     * - Enter: inserts a newline within the value (native), does not
+     *   submit the enclosing form (unlike a single-line input).
+     * - Backspace / Delete: native editing.
+     * - Arrow keys: move the caret within the value (native).
+     * - Escape: no native meaning for a text area.
+     * **ARIA:**
+     * - Roles used: none explicit — the native `<textarea>` supplies
+     *   the implicit `textbox` role with multiline behavior.
+     * - State attributes: `disabled` (native attribute, not
+     *   `aria-disabled`), `aria-invalid` (from the `invalid` prop),
+     *   `aria-required` (from the `required` prop), `aria-describedby`
+     *   (from the `describedBy` prop, expected to reference a light-DOM
+     *   node id — typically a hint or error message rendered by the
+     *   consumer alongside the field).
+     * - Labeling strategy: `aria-label` set from the `label` prop onto
+     *   the internal `<textarea>`. This is the **canonical, recommended**
+     *   mode. Wrapping the host in a light-DOM `<label>` also produces
+     *   an accessible name in Chromium via flattened-tree resolution —
+     *   same secondary mode documented on `ds-input` and `ds-select`,
+     *   verified in this component's e2e tests. Setting `aria-label`
+     *   directly on the `<ds-textarea>` host does NOT work: shadow-DOM
+     *   attribute forwarding would be required — use the `label` prop.
+     * **Focus:**
+     * - On mount: nothing auto-focuses.
+     * - On value change: focus remains on the native `<textarea>`.
+     * - Focus indicator: the browser default `:focus-visible` ring is
+     *   kept on purpose — a themed focus ring using `--ds-color-focus`
+     *   is a future decision once the DS ships a shared focus utility.
+     * **Motion:**
+     * - Animations: none.
+     * - Reduced-motion behavior: N/A — no animation to collapse.
+     * **Contrast:**
+     * - Text: inherits `color: inherit` / `currentColor`; ratio depends
+     *   on the consumer's theme, not verified in isolation.
+     * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+     *   matching `ds-input`.
+     * **Screen reader announcement:**
+     * - Rendered state: announces the `label` prop text as the
+     *   accessible name, followed by "edit text, multiline" (browser/AT
+     *   wording varies). When `required=true` the announcement includes
+     *   "required"; when `invalid=true` it includes "invalid".
+     * - State change: on value edit, AT typically echoes the typed
+     *   character (native behavior); no `aria-live` added.
+     * **Consumer contract:**
+     * - `placeholder` is a hint, not a label — always pair with `label`.
+     * - When `invalid=true`, pair with a `describedBy` id that points at
+     *   a visible error message; `aria-invalid` alone gives the AT the
+     *   status but not the reason.
+     * - `rows` sets the initial visible line count. Vertical resize is
+     *   left to the native default (`resize: vertical`) so users can
+     *   grow the field for long entries; the consumer's CSS can pin it
+     *   with `resize: none` when a fixed height matters.
+     */
+    interface DsTextarea {
+        "describedBy"?: string;
+        /**
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * @default false
+         */
+        "invalid"?: boolean;
+        "label"?: string;
+        "name"?: string;
+        "onDsInput"?: (event: DsTextareaCustomEvent<string>) => void;
+        "placeholder"?: string;
+        /**
+          * @default false
+         */
+        "required"?: boolean;
+        /**
+          * @default 3
+         */
+        "rows"?: number;
+        /**
+          * @default "md"
+         */
+        "size"?: "md" | "lg";
+        "value"?: string;
+    }
+    interface DsTooltip {
+        /**
+          * @default 100
+         */
+        "closeDelay"?: number;
+        "label": string;
+        /**
+          * @default 250
+         */
+        "openDelay"?: number;
+        /**
+          * @default "bottom"
+         */
+        "placement"?: "top" | "bottom";
+    }
+
+    interface DsBadgeAttributes {
+        "variant": | "neutral"
+    | "ui-component"
+    | "recipe"
+    | "agent"
+    | "config";
+    }
+    interface DsButtonAttributes {
+        "variant": "primary" | "secondary" | "ghost";
+        "size": "md" | "lg";
+        "disabled": boolean;
+        "type": "button" | "submit" | "reset";
+        "href": string;
+    }
+    interface DsCheckboxAttributes {
+        "checked": boolean;
+        "indeterminate": boolean;
+        "name": string;
+        "value": string;
+        "disabled": boolean;
+        "required": boolean;
+        "invalid": boolean;
+        "describedBy": string;
+        "label": string;
+    }
+    interface DsCodeBlockAttributes {
+        "code": string;
+        "language": string;
+    }
+    interface DsDialogAttributes {
+        "open": boolean;
+        "label": string;
+        "labelledBy": string;
+        "describedBy": string;
+    }
+    interface DsInputAttributes {
+        "value": string;
+        "name": string;
+        "type": | "text"
+    | "email"
+    | "password"
+    | "search"
+    | "tel"
+    | "url"
+    | "number";
+        "placeholder": string;
+        "disabled": boolean;
+        "required": boolean;
+        "invalid": boolean;
+        "describedBy": string;
+        "label": string;
+        "size": "md" | "lg";
+    }
+    interface DsLoaderAttributes {
+        "size": "sm" | "md" | "lg";
+        "label": string;
+        "speed": "slow" | "normal" | "fast";
+    }
+    interface DsSelectAttributes {
+        "value": string;
+        "name": string;
+        "disabled": boolean;
+        "size": "md" | "lg";
+        "label": string;
+        "options": string | ReadonlyArray<DsSelectOption>;
+    }
+    interface DsTabsAttributes {
+        "items": string | ReadonlyArray<DsTabItem>;
+        "active": string;
+        "orientation": "horizontal" | "vertical";
+        "label": string;
+    }
+    interface DsTextareaAttributes {
+        "value": string;
+        "name": string;
+        "placeholder": string;
+        "disabled": boolean;
+        "required": boolean;
+        "invalid": boolean;
+        "describedBy": string;
+        "label": string;
+        "rows": number;
+        "size": "md" | "lg";
+    }
+    interface DsTooltipAttributes {
+        "label": string;
+        "openDelay": number;
+        "closeDelay": number;
+        "placement": "top" | "bottom";
+    }
+
+    interface IntrinsicElements {
+        "ds-badge": Omit<DsBadge, keyof DsBadgeAttributes> & { [K in keyof DsBadge & keyof DsBadgeAttributes]?: DsBadge[K] } & { [K in keyof DsBadge & keyof DsBadgeAttributes as `attr:${K}`]?: DsBadgeAttributes[K] } & { [K in keyof DsBadge & keyof DsBadgeAttributes as `prop:${K}`]?: DsBadge[K] };
+        "ds-button": Omit<DsButton, keyof DsButtonAttributes> & { [K in keyof DsButton & keyof DsButtonAttributes]?: DsButton[K] } & { [K in keyof DsButton & keyof DsButtonAttributes as `attr:${K}`]?: DsButtonAttributes[K] } & { [K in keyof DsButton & keyof DsButtonAttributes as `prop:${K}`]?: DsButton[K] };
+        "ds-card": DsCard;
+        "ds-checkbox": Omit<DsCheckbox, keyof DsCheckboxAttributes> & { [K in keyof DsCheckbox & keyof DsCheckboxAttributes]?: DsCheckbox[K] } & { [K in keyof DsCheckbox & keyof DsCheckboxAttributes as `attr:${K}`]?: DsCheckboxAttributes[K] } & { [K in keyof DsCheckbox & keyof DsCheckboxAttributes as `prop:${K}`]?: DsCheckbox[K] };
+        "ds-code-block": Omit<DsCodeBlock, keyof DsCodeBlockAttributes> & { [K in keyof DsCodeBlock & keyof DsCodeBlockAttributes]?: DsCodeBlock[K] } & { [K in keyof DsCodeBlock & keyof DsCodeBlockAttributes as `attr:${K}`]?: DsCodeBlockAttributes[K] } & { [K in keyof DsCodeBlock & keyof DsCodeBlockAttributes as `prop:${K}`]?: DsCodeBlock[K] } & OneOf<"code", DsCodeBlock["code"], DsCodeBlockAttributes["code"]>;
+        "ds-dialog": Omit<DsDialog, keyof DsDialogAttributes> & { [K in keyof DsDialog & keyof DsDialogAttributes]?: DsDialog[K] } & { [K in keyof DsDialog & keyof DsDialogAttributes as `attr:${K}`]?: DsDialogAttributes[K] } & { [K in keyof DsDialog & keyof DsDialogAttributes as `prop:${K}`]?: DsDialog[K] };
+        "ds-input": Omit<DsInput, keyof DsInputAttributes> & { [K in keyof DsInput & keyof DsInputAttributes]?: DsInput[K] } & { [K in keyof DsInput & keyof DsInputAttributes as `attr:${K}`]?: DsInputAttributes[K] } & { [K in keyof DsInput & keyof DsInputAttributes as `prop:${K}`]?: DsInput[K] };
+        "ds-loader": Omit<DsLoader, keyof DsLoaderAttributes> & { [K in keyof DsLoader & keyof DsLoaderAttributes]?: DsLoader[K] } & { [K in keyof DsLoader & keyof DsLoaderAttributes as `attr:${K}`]?: DsLoaderAttributes[K] } & { [K in keyof DsLoader & keyof DsLoaderAttributes as `prop:${K}`]?: DsLoader[K] };
+        "ds-select": Omit<DsSelect, keyof DsSelectAttributes> & { [K in keyof DsSelect & keyof DsSelectAttributes]?: DsSelect[K] } & { [K in keyof DsSelect & keyof DsSelectAttributes as `attr:${K}`]?: DsSelectAttributes[K] } & { [K in keyof DsSelect & keyof DsSelectAttributes as `prop:${K}`]?: DsSelect[K] };
+        "ds-tabs": Omit<DsTabs, keyof DsTabsAttributes> & { [K in keyof DsTabs & keyof DsTabsAttributes]?: DsTabs[K] } & { [K in keyof DsTabs & keyof DsTabsAttributes as `attr:${K}`]?: DsTabsAttributes[K] } & { [K in keyof DsTabs & keyof DsTabsAttributes as `prop:${K}`]?: DsTabs[K] };
+        "ds-textarea": Omit<DsTextarea, keyof DsTextareaAttributes> & { [K in keyof DsTextarea & keyof DsTextareaAttributes]?: DsTextarea[K] } & { [K in keyof DsTextarea & keyof DsTextareaAttributes as `attr:${K}`]?: DsTextareaAttributes[K] } & { [K in keyof DsTextarea & keyof DsTextareaAttributes as `prop:${K}`]?: DsTextarea[K] };
+        "ds-tooltip": Omit<DsTooltip, keyof DsTooltipAttributes> & { [K in keyof DsTooltip & keyof DsTooltipAttributes]?: DsTooltip[K] } & { [K in keyof DsTooltip & keyof DsTooltipAttributes as `attr:${K}`]?: DsTooltipAttributes[K] } & { [K in keyof DsTooltip & keyof DsTooltipAttributes as `prop:${K}`]?: DsTooltip[K] } & OneOf<"label", DsTooltip["label"], DsTooltipAttributes["label"]>;
+    }
+}
+export { LocalJSX as JSX };
+declare module "@stencil/core" {
+    export namespace JSX {
+        interface IntrinsicElements {
+            /**
+             * ## Accessibility
+             * **Category:** static-display
+             * **APG pattern:** N/A — non-interactive text label.
+             * **Keyboard interactions:**
+             * - Tab: N/A — the badge is not focusable and does not appear in tab order.
+             * - Enter: N/A.
+             * - Escape: N/A.
+             * - Arrow keys: N/A.
+             * - Printable characters: N/A.
+             * **ARIA:**
+             * - Roles used: none — renders a plain `<span>` around a `<slot />`. The
+             *   `variant` prop is a purely visual axis and MUST NOT be the sole carrier
+             *   of information (color/style alone fails WCAG 1.4.1 Use of Color); the
+             *   textual content inside the slot must convey the same meaning.
+             * - State attributes: none.
+             * - Labeling strategy: visible text via `<slot />`. Consumers place the
+             *   readable label directly inside the tag.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On activate/open: N/A — non-interactive.
+             * - On close/deactivate: N/A.
+             * - Focus indicator: N/A — the host is not focusable. If a consumer wraps
+             *   `ds-badge` in an interactive element (e.g. `<button>`, `<a>`), that
+             *   wrapper owns the focus indicator via the DS `--ds-color-focus` token
+             *   and its own `:focus-visible` rule.
+             * **Motion:**
+             * - Animations: none.
+             * - Reduced-motion behavior: N/A.
+             * **Contrast:**
+             * - Text: inherits `color: inherit` / `currentColor` from the host page and
+             *   the variant-specific style; not verified in isolation here. Consumers
+             *   are responsible for confirming ≥ 4.5:1 (WCAG 1.4.3) against the surface
+             *   the badge is placed on.
+             * - Non-text: no state-conveying icons or borders that need the 3:1
+             *   non-text contrast threshold.
+             * **Screen reader announcement:**
+             * - Rendered state: announces the slot text as inline content within its
+             *   surrounding context (no role means AT reads it as plain text). The
+             *   `variant` value is not announced — that is intentional; the label text
+             *   is the source of truth for meaning.
+             * - State change: N/A — no dynamic state owned by this component.
+             */
+            "ds-badge": LocalJSX.IntrinsicElements["ds-badge"] & JSXBase.HTMLAttributes<HTMLDsBadgeElement>;
+            /**
+             * ## Accessibility
+             * **Category:** interactive-display
+             * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+             * (satisfied natively by the underlying `<button>` element). When `href` is
+             * set, the component renders `<a href>` instead — a link, not a button — and
+             * that surface follows native `<a>` semantics rather than the Button pattern.
+             * **Keyboard interactions:**
+             * - Tab: moves focus to the internal `<button>` or `<a>` (shadow DOM does not
+             *   interrupt tab order).
+             * - Enter: activates (fires click on `<button>`, navigates on `<a>`).
+             * - Space: activates the `<button>` variant only (native behavior); on the
+             *   `<a>` variant Space scrolls the page as usual.
+             * - Escape: N/A — no dismissible state owned by this component.
+             * - Arrow keys: N/A.
+             * - Printable characters: N/A.
+             * **ARIA:**
+             * - Roles used: none explicit — the native `<button>` / `<a href>` supplies
+             *   the implicit `button` / `link` role.
+             * - State attributes: `disabled` (native attribute on `<button>`, not
+             *   `aria-disabled`). The `<a>` variant does not accept `disabled` — a
+             *   disabled navigation is a spec smell (see spec §"Button vs Link"); if a
+             *   link needs a disabled state, model it as a `<button>` action instead.
+             * - Labeling strategy: visible text via `<slot />`. Consumers MUST place
+             *   readable text (or a labeled icon) inside the tag. An empty slot leaves
+             *   the button/link without an accessible name and fails
+             *   `button-name` / `link-name` axe rules. Icon-only usage is out of contract
+             *   for `ds-button`; use a future `ds-icon-button` with a required
+             *   `aria-label` prop when that lands.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On activate: focus stays on the element (native click behavior; the
+             *   component does not move focus on its own).
+             * - On close/deactivate: N/A.
+             * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+             *   `outline-offset`, applied via `:focus-visible` — replaces the browser
+             *   default so both `<button>` and `<a>` variants use the same DS ring
+             *   (spec universal rule 3, WCAG 1.4.11 non-text contrast ≥ 3:1).
+             * **Motion:**
+             * - Animations: 150ms `background-color` ease-in-out transition on
+             *   `primary`/`secondary` variants (hover).
+             * - Reduced-motion behavior: N/A — 150ms is below the spec's 200ms threshold
+             *   for `prefers-reduced-motion` handling, and the transition animates color
+             *   only (no motion of position, scale, or opacity).
+             * **Contrast:**
+             * - Text: `primary` and `secondary` variants pair `--ds-color-{primary,secondary}`
+             *   with `--ds-color-text-on-{primary,secondary}` — the token pairs are
+             *   authored to meet WCAG 2.1 AA (≥ 4.5:1). The `ghost` variant inherits
+             *   `color: inherit` and pins `opacity: 0.85`, so its effective contrast
+             *   depends on the consumer's surface — verify per site.
+             * - Non-text (border on `ghost`): 1px `currentColor`; contrast tracks the
+             *   text color 1:1, subject to the same host-page caveat.
+             * **Screen reader announcement:**
+             * - Rendered state: announces the slot text followed by "button" (or "link"
+             *   for the `href` variant), plus "dimmed" / "unavailable" when `disabled`
+             *   is set (browser/AT dependent wording).
+             * - State change: N/A — this component does not own toggle state. A pressed
+             *   toggle needs `aria-pressed`, which is out of scope here; model that as
+             *   a distinct component or extend the API deliberately per the spec.
+             */
+            "ds-button": LocalJSX.IntrinsicElements["ds-button"] & JSXBase.HTMLAttributes<HTMLDsButtonElement>;
+            /**
+             * ## Accessibility
+             * **Category:** static-display
+             * **APG pattern:** N/A — a container surface with no interactive
+             * behavior of its own. If a consumer nests interactive elements
+             * inside (button, link, form field), those elements satisfy their
+             * own a11y bucket independently.
+             * **Keyboard interactions:**
+             * - Tab / Shift+Tab: N/A — the card itself is not focusable. Any
+             *   interactive descendant carries its own tab semantics.
+             * - Enter / Space / Arrow / Escape / Printable: N/A.
+             * **ARIA:**
+             * - Roles used: none. `<ds-card>` is a purely visual grouping and
+             *   deliberately does not carry `role="region"` — that would demand
+             *   a labelledby target, which would only be correct in a subset of
+             *   uses. Consumers that need a labeled landmark should render a
+             *   `<section aria-labelledby>` around the card.
+             * - State attributes: none.
+             * - Labeling strategy: none applied by the component; consumer's
+             *   heading structure inside the slot supplies the accessible name
+             *   when needed.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - Focus indicator: N/A — the card itself is not focusable.
+             * **Motion:**
+             * - Animations: none.
+             * - Reduced-motion behavior: N/A.
+             * **Contrast:**
+             * - Text: inherits `color: inherit` / `currentColor`; the card does
+             *   not impose a text color, so contrast is the consumer theme's
+             *   responsibility.
+             * - Non-text (border, subtle background tint): both derived from
+             *   `color-mix(in oklch, currentColor N%, transparent)`, matching
+             *   the pattern used by `ds-input` and `ds-select`. WCAG 1.4.11
+             *   (3:1 non-text contrast) is met in themes where the surface has
+             *   enough delta against the page background; the component does
+             *   not override the consumer's palette to force it.
+             * **Screen reader announcement:**
+             * - Rendered state: no announcement of the card itself. AT
+             *   navigates to the slotted content directly, using whatever
+             *   heading and landmark structure the consumer places inside.
+             * - State change: N/A.
+             */
+            "ds-card": LocalJSX.IntrinsicElements["ds-card"] & JSXBase.HTMLAttributes<HTMLDsCardElement>;
+            /**
+             * ## Accessibility
+             * **Category:** form-field
+             * **APG pattern:** N/A — native element. This wraps a native
+             * `<input type="checkbox">`; the browser already implements the
+             * checkbox role and its state semantics. Reference:
+             * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
+             * Note: `ds-checkbox` intentionally does NOT reach for the WAI-ARIA
+             * APG "tri-state checkbox" pattern (indeterminate + on + off) as a
+             * scratch-built ARIA widget. The native input already exposes the
+             * `indeterminate` DOM property and browsers report it to AT
+             * correctly; the `indeterminate` prop here forwards to that DOM
+             * property so the native mechanism carries the semantics.
+             * **Keyboard interactions:**
+             * - Tab: moves focus to the native `<input type="checkbox">`.
+             * - Space: toggles the checked state (native behavior).
+             * - Enter: no native effect on a checkbox (unlike button). Form
+             *   submission triggered by Enter comes from the enclosing form's
+             *   default submit button, not from the checkbox itself.
+             * **ARIA:**
+             * - Roles used: none explicit — the native checkbox supplies the
+             *   implicit `checkbox` role.
+             * - State attributes: `checked` (DOM property, kept in sync via
+             *   componentDidRender because Stencil does not JSX-forward the
+             *   attribute cleanly for controlled use), `disabled` (native
+             *   attribute, not `aria-disabled`), `aria-invalid` (from the
+             *   `invalid` prop), `aria-required` (from the `required` prop),
+             *   `aria-describedby` (from the `describedBy` prop).
+             * - Labeling strategy: `aria-label` set from the `label` prop onto
+             *   the internal checkbox. This is the **canonical, recommended**
+             *   mode. Wrapping the host in a light-DOM `<label>` also produces
+             *   an accessible name in Chromium via flattened-tree resolution —
+             *   same secondary mode documented on `ds-input`.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On toggle: focus remains on the native checkbox.
+             * - Focus indicator: browser default `:focus-visible` ring, kept on
+             *   purpose until the DS ships a themed focus utility using
+             *   `--ds-color-focus`. Not overridden by `ds-checkbox.css`.
+             * **Motion:**
+             * - Animations: none.
+             * - Reduced-motion behavior: N/A.
+             * **Contrast:**
+             * - Text: N/A — the checkbox itself renders no text (labels are
+             *   supplied by the consumer via `label` prop or wrapping <label>).
+             * - Non-text (the box and its check glyph): browser default rendering
+             *   is kept on purpose (no `appearance: none` override); this
+             *   preserves the OS/browser accessibility rendering that AT and
+             *   forced-color modes rely on. A themed override is a future
+             *   decision once the DS commits to a checkbox visual language that
+             *   still passes 3:1 non-text contrast in every theme.
+             * **Screen reader announcement:**
+             * - Rendered state: announces the `label` prop text as the
+             *   accessible name, followed by "checkbox", followed by "checked"
+             *   / "not checked" / "mixed" per the current DOM state.
+             * - State change: on toggle, AT announces the new state (native
+             *   behavior); no `aria-live` added.
+             * **Consumer contract:**
+             * - `checked` is the source of truth for controlled use. Reading
+             *   `event.detail` from `dsChange` gives the new state; the internal
+             *   input is kept in sync via a Watch + a re-sync in componentDidRender.
+             * - `indeterminate` is a visual/AT state, not a value — it is NOT
+             *   submitted with a form and clears on the next user toggle.
+             */
+            "ds-checkbox": LocalJSX.IntrinsicElements["ds-checkbox"] & JSXBase.HTMLAttributes<HTMLDsCheckboxElement>;
+            /**
+             * ## Accessibility
+             * **Category:** interactive-display
+             * **APG pattern:** Button — https://www.w3.org/WAI/ARIA/apg/patterns/button/
+             * (for the internal copy control; the code readout itself is static text).
+             * **Keyboard interactions:**
+             * - Tab: moves focus into the internal copy `<button>`; the code readout
+             *   (`<pre><code>`) is not focusable itself, but its container is
+             *   horizontally scrollable and remains reachable via the browser's caret
+             *   browsing / find-in-page path.
+             * - Enter: activates the copy button (writes `code` to the clipboard).
+             * - Space: activates the copy button (native `<button>` behavior).
+             * - Escape: N/A — the "Copied" state auto-clears after 1.4s; no dismissible
+             *   modal state.
+             * - Arrow keys: N/A.
+             * - Printable characters: N/A.
+             * **ARIA:**
+             * - Roles used: none explicit — the native `<button>` supplies the implicit
+             *   `button` role; `<pre>` and `<code>` supply their semantic roles.
+             * - State attributes: none. The `copied` flag lives only in the button's
+             *   accessible name (see below); it is intentionally not surfaced via
+             *   `aria-pressed` because it is not a toggle — it is a transient
+             *   post-action confirmation.
+             * - Labeling strategy: `aria-label` on the copy button — "Copy code" in the
+             *   resting state, "Copied" while the confirmation is visible. This is
+             *   authoritative because the button carries both an icon and the words
+             *   "Copy" / "Copied", and mixed icon+text needs an explicit accessible
+             *   name to avoid AT reading the SVG as a separate node.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On activate: focus stays on the copy button (clipboard write is
+             *   synchronous from the user's perspective; no focus is moved).
+             * - On close/deactivate: N/A — no popup or overlay to close.
+             * - Focus indicator: 2px `outline` in `var(--ds-color-focus)` with 2px
+             *   `outline-offset`, applied to `.ds-code-block__copy:focus-visible`. The
+             *   readout itself is not focusable and has no focus indicator by design.
+             * **Motion:**
+             * - Animations: 120ms `color` / `border-color` ease transition on the copy
+             *   button (hover/focus).
+             * - Reduced-motion behavior: N/A — 120ms is below the spec's 200ms
+             *   threshold, and the transition animates color only.
+             * **Contrast:**
+             * - Text (code readout): inherits `color: currentColor`; contrast depends
+             *   on the host page's text color vs. the block's tinted background
+             *   (`color-mix(currentColor 4%, transparent)`). Verify per site.
+             * - Text (copy button): `color-mix(in oklch, currentColor 70%, transparent)`
+             *   at rest, `currentColor` on hover. The 70%-mixed resting color can drop
+             *   below 4.5:1 on low-contrast surfaces — audit per usage site, and lean
+             *   on the hover/focus states (both restore full `currentColor`) as the
+             *   accessible fallback.
+             * - Non-text (button border, language tag border-bottom): both use
+             *   `color-mix(currentColor <15|12>%, transparent)` — decorative separators,
+             *   they do not convey state, so the 3:1 non-text contrast rule does not
+             *   apply. Focus and hover borders shift up to 30% for clearer edges.
+             * **Screen reader announcement:**
+             * - Rendered state: announces "Copy code, button" (the `aria-label`), then
+             *   the code content when the user navigates into the `<pre><code>` block
+             *   (usually announced as a code block on VoiceOver).
+             * - State change: after clicking Copy, the button's `aria-label` flips to
+             *   "Copied"; AT will announce this on the next focus or re-read of the
+             *   button, but NOT proactively — there is no `aria-live` region. This is
+             *   deliberate per spec §"What we explicitly do NOT do" (avoid live-region
+             *   overuse), and the trade-off is that a screen-reader-only user does not
+             *   get an unsolicited confirmation. If a future review decides that
+             *   confirmation must be audible, add a visually-hidden
+             *   `aria-live="polite"` element whose text toggles on `copied`.
+             */
+            "ds-code-block": LocalJSX.IntrinsicElements["ds-code-block"] & JSXBase.HTMLAttributes<HTMLDsCodeBlockElement>;
+            /**
+             * ## Accessibility
+             * **Category:** state-machine
+             * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+             * This component wraps the **native `<dialog>` element** rather than
+             * scratch-building the APG pattern on top of a `<div role="dialog">`.
+             * `<dialog>` opened via `showModal()` gives us — from the browser,
+             * verified by the platform, not by us:
+             * - Focus trap: Tab / Shift+Tab cycle only through focusable
+             *   descendants (including slotted light-DOM descendants; the flattened
+             *   accessibility tree is what the trap operates on).
+             * - Escape: closes the dialog and returns focus to the previously
+             *   focused element (native, not implemented here).
+             * - Inert background: everything outside the dialog is inert while it
+             *   is open — no mouse, no keyboard, not part of the a11y tree.
+             * - Return focus: on close, focus returns to whatever element had it
+             *   before `showModal()` — native, not implemented here.
+             * - Initial focus: browser auto-focuses the first `autofocus` element
+             *   inside, or the first focusable if none — native.
+             * - `role="dialog"` and `aria-modal="true"` semantics: implicit on
+             *   `<dialog>`, no ARIA needed from us.
+             * This is the deliberate answer to the a11y spec §D warning about
+             * scratch-building Tier 2 components: the native element removes the
+             * "compiles, axe passes, screen-reader user gets trapped" failure
+             * mode by delegating the state machine to the platform.
+             * **Keyboard interactions (all handled by the native element unless
+             * noted otherwise):**
+             * - Tab: cycles focus within the dialog's focusable descendants
+             *   (native focus trap).
+             * - Shift+Tab: reverse cycle (native).
+             * - Escape: closes the dialog and fires the `close` event (native).
+             *   Consumers who need to prevent dismissal on Escape (destructive
+             *   flows: e.g. an unsaved-changes guard) must call
+             *   `event.preventDefault()` inside their own `keydown` listener on
+             *   the dialog before it reaches the browser — that is an escape
+             *   hatch, not a default we impose.
+             * - Enter / Space: no special dialog behavior; forwarded to
+             *   whatever descendant has focus (a button will activate).
+             * - Home / End / Arrow keys: no special dialog behavior; forwarded
+             *   to descendants.
+             * - Printable characters: forwarded to descendants (e.g. typing
+             *   inside a slotted `<ds-input>`).
+             * **ARIA attributes and value triggers:**
+             * - Implicit `role="dialog"` on the native `<dialog>`.
+             * - Implicit `aria-modal="true"` when opened via `showModal()`
+             *   (which is what this component always uses; `show()` — the
+             *   non-modal form — is intentionally not exposed in v1).
+             * - `aria-label` set from the `label` prop onto the `<dialog>`.
+             *   Consumers who prefer an in-content title can pass a
+             *   `labelledBy` prop instead, whose value is the id of a heading
+             *   element they render inside the slot — `aria-labelledby`
+             *   resolves that id through the flattened tree.
+             * - `aria-describedby` from the `describedBy` prop, resolving a
+             *   light-DOM id of a descriptive block (e.g. the dialog body copy
+             *   when the label is short).
+             * **Focus lifecycle:**
+             * - Opening: `showModal()` moves focus to the first `autofocus`
+             *   element inside, or the first focusable if none. Consumers who
+             *   want a specific initial focus target should mark that element
+             *   with `autofocus`.
+             * - While open: focus is trapped within the flattened tree of the
+             *   `<dialog>`; Tab / Shift+Tab cycle through slotted descendants.
+             *   Focus cannot escape into the inert background.
+             * - Closing: `close()` (either from Escape, from a form-submit with
+             *   `method="dialog"`, from a light-dismiss backdrop click handler
+             *   the consumer wires up, or from `open=false`) returns focus to
+             *   the element that had it immediately before `showModal()` was
+             *   called. The `dsClose` event fires after focus has been restored.
+             * **ARIA labelling contract (choose one):**
+             * - **`label`** (string) — sets `aria-label` on the dialog. Simplest
+             *   for short titles.
+             * - **`labelledBy`** (id) — sets `aria-labelledby` to reference a
+             *   heading rendered inside the slot. Preferred when the dialog has
+             *   a visible title so the accessible name matches the visible name.
+             * If both are omitted, axe reports `dialog-name` — the dialog has no
+             * accessible name. The a11y test for this component asserts that at
+             * least one of the two is provided.
+             * **Motion:**
+             * - Animations: none applied by the component. Consumers who want an
+             *   entrance transition can style `::backdrop` and `dialog[open]`
+             *   with their own animation, gated on `@media
+             *   (prefers-reduced-motion: no-preference)`.
+             * - Reduced-motion behavior: N/A — no animation to collapse. If a
+             *   consumer adds one, they own the reduced-motion fallback.
+             * **Contrast:**
+             * - Text: inherits `color: inherit`; consumer theme owns contrast.
+             * - Non-text: subtle bordered surface via
+             *   `color-mix(in oklch, currentColor N%, transparent)` matching
+             *   `ds-card`. Backdrop is a semi-transparent black by default.
+             * **Screen reader announcement:**
+             * - Rendered state (closed): dialog is not in the a11y tree.
+             * - Opened: AT announces "dialog" plus the accessible name from
+             *   `label` / `labelledBy`, then reads the content following focus
+             *   (or the descriptive block referenced by `describedBy` first,
+             *   depending on AT).
+             * - State change: on close, AT returns to the element that regained
+             *   focus (the trigger); no `aria-live` announcement is added.
+             * **Consumer contract:**
+             * - Set `open` to true to show; set to false to close. The component
+             *   syncs the DOM state via `showModal()` / `close()` in a Watch.
+             * - Listen to `dsClose` to know when the dialog was dismissed (by
+             *   Escape, by `open=false`, or by a form submit with
+             *   `method="dialog"`). Listen to `dsOpen` for the mirror event.
+             * - The default backdrop is opaque and NOT click-to-dismiss. Consumers
+             *   who want light-dismiss can add a click listener on the dialog
+             *   that closes when the click target is the dialog itself (not a
+             *   descendant): `if (e.target === dialog) dialog.close()`.
+             * - Put focus targets (form fields, primary action button) inside
+             *   the slot. Use `autofocus` on the element that should receive
+             *   focus first.
+             * **Pending manual verification (see commit message TODO):**
+             * - VoiceOver on macOS: confirm the dialog announces its accessible
+             *   name + "dialog" on open, focus lands on the correct element,
+             *   Escape closes and focus returns to the trigger.
+             * - Chromium high-contrast / forced-colors: confirm the surface
+             *   still reads as a bordered container with the native ::backdrop
+             *   dim.
+             */
+            "ds-dialog": LocalJSX.IntrinsicElements["ds-dialog"] & JSXBase.HTMLAttributes<HTMLDsDialogElement>;
+            /**
+             * ## Accessibility
+             * **Category:** form-field
+             * **APG pattern:** N/A — native element. This wraps a native `<input>`;
+             * there is no WAI-ARIA APG pattern for a plain text input because the
+             * browser already implements it natively. Reference:
+             * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+             * **Keyboard interactions:**
+             * - Tab: moves focus to the native `<input>` (shadow DOM does not
+             *   interrupt tab order).
+             * - Printable characters: insert at the caret position (native).
+             * - Backspace / Delete: native editing.
+             * - Arrow keys: move the caret within the value (native); for
+             *   `type="number"` Up/Down step the numeric value (native).
+             * - Enter: on `type="search"` may submit the enclosing form (native);
+             *   no custom handling.
+             * - Escape: no native meaning for a text input.
+             * **ARIA:**
+             * - Roles used: none explicit — the native `<input>` supplies its
+             *   implicit role (`textbox`, `searchbox`, etc. depending on `type`).
+             * - State attributes: `disabled` (native attribute, not `aria-disabled`),
+             *   `aria-invalid` (from the `invalid` prop), `aria-required` (from the
+             *   `required` prop), `aria-describedby` (from the `describedBy` prop,
+             *   expected to reference a light-DOM node id — typically a hint or
+             *   error message rendered by the consumer alongside the field).
+             * - Labeling strategy: `aria-label` set from the `label` prop onto the
+             *   internal `<input>`. This is the **canonical, recommended** mode —
+             *   explicit and independent of DOM structure. Consumers MUST pass
+             *   `label` (or otherwise give the field an accessible name) — an
+             *   `<input>` with no accessible name is a WCAG failure (axe rule
+             *   `label`). Wrapping the host in a light-DOM `<label>` (e.g.
+             *   `<label>Email <ds-input></ds-input></label>`) also produces an
+             *   accessible name in Chromium via flattened-tree resolution — the
+             *   same secondary mode documented on `ds-select`, verified in this
+             *   component's e2e tests. Setting `aria-label` directly on the
+             *   `<ds-input>` host does NOT work: shadow-DOM attribute forwarding
+             *   would be required — use the `label` prop instead.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On value change: focus remains on the native `<input>`.
+             * - Focus indicator: the browser default `:focus-visible` ring is kept
+             *   on purpose — a themed focus ring using `--ds-color-focus` is a
+             *   future decision once the DS ships a shared focus utility. Not
+             *   overridden by `ds-input.css`.
+             * **Motion:**
+             * - Animations: none.
+             * - Reduced-motion behavior: N/A — no animation to collapse.
+             * **Contrast:**
+             * - Text: inherits `color: inherit` / `currentColor`; ratio depends on
+             *   the consumer's theme, not verified in isolation here.
+             * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+             *   matching `ds-select` — inherits whatever contrast the host page
+             *   sets. WCAG 1.4.11 (3:1 non-text) is the consumer's responsibility
+             *   in themes that override the surface.
+             * **Screen reader announcement:**
+             * - Rendered state: announces the `label` prop text as the accessible
+             *   name, followed by the browser/AT's role announcement for the
+             *   input type ("edit text", "search text", "password", "phone
+             *   number", "email"…). When `required=true` the announcement
+             *   includes "required"; when `invalid=true` it includes "invalid".
+             * - State change: on value edit, AT typically echoes the typed
+             *   character (native input behavior); no `aria-live` added, per the
+             *   spec's guidance against live-region overuse.
+             * **Consumer contract:**
+             * - `placeholder` is a hint, not a label. It disappears on focus in
+             *   most browsers and is not reliably announced by every AT — always
+             *   pair with `label`.
+             * - For `type="password"` in a real form, pair with a light-DOM
+             *   `<input type="hidden">` or a form-associated ancestor that gives
+             *   the browser's password manager an `autocomplete` hint. This
+             *   component intentionally does not expose `autocomplete` in v1;
+             *   consumers that need it can render a native `<input>` for that
+             *   field until the prop is added.
+             * - When `invalid=true`, pair with a `describedBy` id that points at
+             *   a visible error message; `aria-invalid` alone gives the AT the
+             *   status but not the reason.
+             */
+            "ds-input": LocalJSX.IntrinsicElements["ds-input"] & JSXBase.HTMLAttributes<HTMLDsInputElement>;
+            /**
+             * ## Accessibility
+             * **Category:** static-display (indeterminate progress indicator)
+             * **APG pattern:** N/A — the loader is a passive presence indicator, not a
+             * `progressbar` (no measurable value). Uses `role="status"` per WAI-ARIA
+             * live-region semantics for indeterminate loading states.
+             * **Keyboard interactions:**
+             * - Tab: N/A — not focusable.
+             * - Enter: N/A.
+             * - Escape: N/A.
+             * - Arrow keys: N/A.
+             * - Printable characters: N/A.
+             * **ARIA:**
+             * - Roles used: `role="status"` on the host — an implicit polite live
+             *   region ARIA lists as valid for "advisory information" including
+             *   in-progress operations. The inner `<svg>` is decorative and carries
+             *   `aria-hidden="true"` + `focusable="false"` so it never becomes a
+             *   parallel target for screen readers.
+             * - State attributes: none. The loader has no state changes to announce
+             *   beyond its own presence; the polite live region on mount is the
+             *   announcement.
+             * - Labeling strategy: `aria-label` from the `label` prop (default
+             *   "Loading"). Consumers pass a more specific string when the context
+             *   warrants ("Loading ceremonies", "Signing in", …).
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On activate/open: N/A — not interactive.
+             * - On close/deactivate: N/A.
+             * - Focus indicator: N/A — the host is not focusable.
+             * **Motion:**
+             * - Animations: two mirrored halves of the logo path oscillate
+             *   symmetrically around the visual center, meeting at the ring midpoint
+             *   and separating again. Cycle 1.4s by default (`speed="normal"`);
+             *   `speed="slow"` = 2.2s, `speed="fast"` = 0.9s.
+             * - Reduced-motion behavior: `@media (prefers-reduced-motion: reduce)`
+             *   collapses both halves to a static rendering with a slow opacity
+             *   pulse (2s ease-in-out). No rotation, no lateral movement.
+             * **Contrast:**
+             * - Text: N/A — the visible surface is the SVG stroke, not text.
+             * - Non-text: stroke inherits `currentColor` from the host. Consumers are
+             *   responsible for confirming the stroke against its background meets
+             *   the ≥ 3:1 non-text contrast threshold (WCAG 1.4.11) where the loader
+             *   conveys state (e.g. distinguishing "still loading" from "idle").
+             * **Screen reader announcement:**
+             * - Rendered state: the polite live region announces the label
+             *   (e.g. "Loading") when the loader mounts.
+             * - State change: N/A — the loader itself has no state that changes.
+             *   Consumers unmount the loader when the awaited work completes; that
+             *   removal is silent, which is the intended behavior (the arriving
+             *   content is the announcement).
+             */
+            "ds-loader": LocalJSX.IntrinsicElements["ds-loader"] & JSXBase.HTMLAttributes<HTMLDsLoaderElement>;
+            "ds-select": LocalJSX.IntrinsicElements["ds-select"] & JSXBase.HTMLAttributes<HTMLDsSelectElement>;
+            "ds-tabs": LocalJSX.IntrinsicElements["ds-tabs"] & JSXBase.HTMLAttributes<HTMLDsTabsElement>;
+            /**
+             * ## Accessibility
+             * **Category:** form-field
+             * **APG pattern:** N/A — native element. This wraps a native
+             * `<textarea>`; there is no WAI-ARIA APG pattern for a plain
+             * multi-line text field because the browser already implements it
+             * natively. Reference:
+             * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+             * **Keyboard interactions:**
+             * - Tab: moves focus to the native `<textarea>`; Tab inside the
+             *   textarea inserts a tab character only when the browser is
+             *   configured to do so (default behavior: Tab moves focus out).
+             * - Printable characters: insert at the caret position (native).
+             * - Enter: inserts a newline within the value (native), does not
+             *   submit the enclosing form (unlike a single-line input).
+             * - Backspace / Delete: native editing.
+             * - Arrow keys: move the caret within the value (native).
+             * - Escape: no native meaning for a text area.
+             * **ARIA:**
+             * - Roles used: none explicit — the native `<textarea>` supplies
+             *   the implicit `textbox` role with multiline behavior.
+             * - State attributes: `disabled` (native attribute, not
+             *   `aria-disabled`), `aria-invalid` (from the `invalid` prop),
+             *   `aria-required` (from the `required` prop), `aria-describedby`
+             *   (from the `describedBy` prop, expected to reference a light-DOM
+             *   node id — typically a hint or error message rendered by the
+             *   consumer alongside the field).
+             * - Labeling strategy: `aria-label` set from the `label` prop onto
+             *   the internal `<textarea>`. This is the **canonical, recommended**
+             *   mode. Wrapping the host in a light-DOM `<label>` also produces
+             *   an accessible name in Chromium via flattened-tree resolution —
+             *   same secondary mode documented on `ds-input` and `ds-select`,
+             *   verified in this component's e2e tests. Setting `aria-label`
+             *   directly on the `<ds-textarea>` host does NOT work: shadow-DOM
+             *   attribute forwarding would be required — use the `label` prop.
+             * **Focus:**
+             * - On mount: nothing auto-focuses.
+             * - On value change: focus remains on the native `<textarea>`.
+             * - Focus indicator: the browser default `:focus-visible` ring is
+             *   kept on purpose — a themed focus ring using `--ds-color-focus`
+             *   is a future decision once the DS ships a shared focus utility.
+             * **Motion:**
+             * - Animations: none.
+             * - Reduced-motion behavior: N/A — no animation to collapse.
+             * **Contrast:**
+             * - Text: inherits `color: inherit` / `currentColor`; ratio depends
+             *   on the consumer's theme, not verified in isolation.
+             * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+             *   matching `ds-input`.
+             * **Screen reader announcement:**
+             * - Rendered state: announces the `label` prop text as the
+             *   accessible name, followed by "edit text, multiline" (browser/AT
+             *   wording varies). When `required=true` the announcement includes
+             *   "required"; when `invalid=true` it includes "invalid".
+             * - State change: on value edit, AT typically echoes the typed
+             *   character (native behavior); no `aria-live` added.
+             * **Consumer contract:**
+             * - `placeholder` is a hint, not a label — always pair with `label`.
+             * - When `invalid=true`, pair with a `describedBy` id that points at
+             *   a visible error message; `aria-invalid` alone gives the AT the
+             *   status but not the reason.
+             * - `rows` sets the initial visible line count. Vertical resize is
+             *   left to the native default (`resize: vertical`) so users can
+             *   grow the field for long entries; the consumer's CSS can pin it
+             *   with `resize: none` when a fixed height matters.
+             */
+            "ds-textarea": LocalJSX.IntrinsicElements["ds-textarea"] & JSXBase.HTMLAttributes<HTMLDsTextareaElement>;
+            "ds-tooltip": LocalJSX.IntrinsicElements["ds-tooltip"] & JSXBase.HTMLAttributes<HTMLDsTooltipElement>;
+        }
+    }
+}