@chiralkit/design-system 0.1.0-alpha.0

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { ds_button as DsButton } from './ds-button.entry.js';
+export { ds_select as DsSelect } from './ds-select.entry.js';
+import './index-e-glNjK6.js';

package/dist/esm/loader.js

@@ -0,0 +1,10 @@
+import { g as globalScripts, b as bootstrapLazy } from './index-e-glNjK6.js';
+export { s as setNonce } from './index-e-glNjK6.js';
+
+const defineCustomElements = async (win, options) => {
+  if (typeof window === 'undefined') return undefined;
+  await globalScripts();
+  return bootstrapLazy([["ds-badge",[[769,"ds-badge",{"variant":[1]}]]],["ds-button",[[769,"ds-button",{"variant":[1],"size":[1],"disabled":[4],"type":[1],"href":[1]}]]],["ds-card",[[257,"ds-card"]]],["ds-checkbox",[[513,"ds-checkbox",{"checked":[4],"indeterminate":[4],"name":[1],"value":[1],"disabled":[4],"required":[4],"invalid":[4],"describedBy":[1,"described-by"],"label":[1]},null,{"checked":[{"watchChecked":0}],"indeterminate":[{"watchIndeterminate":0}]}]]],["ds-code-block",[[513,"ds-code-block",{"code":[1],"language":[1],"copied":[32]}]]],["ds-dialog",[[769,"ds-dialog",{"open":[4],"label":[1],"labelledBy":[1,"labelled-by"],"describedBy":[1,"described-by"]},null,{"open":[{"watchOpen":0}]}]]],["ds-input",[[513,"ds-input",{"value":[1],"name":[1],"type":[1],"placeholder":[1],"disabled":[4],"required":[4],"invalid":[4],"describedBy":[1,"described-by"],"label":[1],"size":[1]},null,{"value":[{"watchValue":0}]}]]],["ds-loader",[[513,"ds-loader",{"size":[1],"label":[1],"speed":[1]}]]],["ds-select",[[513,"ds-select",{"value":[1],"name":[1],"disabled":[4],"size":[1],"label":[1],"options":[1]},null,{"value":[{"watchValue":0}],"options":[{"watchOptions":0}]}]]],["ds-tabs",[[512,"ds-tabs",{"items":[1],"active":[1025],"orientation":[1],"label":[1]},null,{"items":[{"watchItems":0}]}]]],["ds-textarea",[[513,"ds-textarea",{"value":[1],"name":[1],"placeholder":[1],"disabled":[4],"required":[4],"invalid":[4],"describedBy":[1,"described-by"],"label":[1],"rows":[2],"size":[1]},null,{"value":[{"watchValue":0}]}]]],["ds-tooltip",[[772,"ds-tooltip",{"label":[1],"openDelay":[2,"open-delay"],"closeDelay":[2,"close-delay"],"placement":[1]},null,{"label":[{"watchLabel":0}]}]]]], options);
+};
+
+export { defineCustomElements };

package/dist/index.cjs.js

@@ -0,0 +1 @@
+module.exports = require('./cjs/index.cjs.js');

package/dist/index.js

@@ -0,0 +1 @@
+export * from './esm/index.js';

package/dist/layouts/app-shell.css

@@ -0,0 +1,84 @@
+.ds-app-shell {
+  --ds-app-shell-header-size: calc(var(--ds-spacing-xl, 1.5rem) * 2);
+  --ds-app-shell-primary-size: 16rem;
+  --ds-app-shell-secondary-size: 20rem;
+  --ds-app-shell-content-max: 80rem;
+  --ds-app-shell-gutter: var(--ds-spacing-lg, 1rem);
+
+  box-sizing: border-box;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--ds-app-shell-gutter);
+  padding: var(--ds-app-shell-gutter);
+}
+
+.ds-app-shell > .ds-app-shell__header,
+.ds-app-shell > .ds-app-shell__primary,
+.ds-app-shell > .ds-app-shell__main,
+.ds-app-shell > .ds-app-shell__secondary,
+.ds-app-shell > .ds-app-shell__footer {
+  box-sizing: border-box;
+  grid-column: 1;
+  min-inline-size: 0;
+}
+
+.ds-app-shell > .ds-app-shell__header {
+  min-block-size: var(--ds-app-shell-header-size);
+}
+
+.ds-app-shell > .ds-app-shell__main {
+  min-width: 0;
+}
+
+@media (min-width: 64rem) {
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):not(:has(> .ds-app-shell__primary)):not(:has(> .ds-app-shell__secondary)) {
+    grid-template-columns: minmax(0, min(var(--ds-app-shell-content-max), 100%));
+    justify-content: center;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):not(:has(> .ds-app-shell__secondary)) {
+    grid-template-columns: minmax(0, var(--ds-app-shell-primary-size)) minmax(0, 1fr);
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):not(:has(> .ds-app-shell__primary)):has(> .ds-app-shell__secondary) {
+    grid-template-columns: minmax(0, 1fr) minmax(0, var(--ds-app-shell-secondary-size));
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):has(> .ds-app-shell__secondary) {
+    grid-template-columns: minmax(0, var(--ds-app-shell-primary-size)) minmax(0, 1fr) minmax(0, var(--ds-app-shell-secondary-size));
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"] > .ds-app-shell__header,
+  .ds-app-shell[data-layout="fixed-rails"] > .ds-app-shell__footer {
+    grid-column: 1 / -1;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):not(:has(> .ds-app-shell__secondary)) > .ds-app-shell__primary,
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):has(> .ds-app-shell__secondary) > .ds-app-shell__primary {
+    grid-column: 1;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):not(:has(> .ds-app-shell__secondary)) > .ds-app-shell__main,
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):has(> .ds-app-shell__secondary) > .ds-app-shell__main {
+    grid-column: 2;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):not(:has(> .ds-app-shell__primary)):has(> .ds-app-shell__secondary) > .ds-app-shell__main {
+    grid-column: 1;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):not(:has(> .ds-app-shell__primary)):has(> .ds-app-shell__secondary) > .ds-app-shell__secondary {
+    grid-column: 2;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"]:has(> .ds-app-shell__main):has(> .ds-app-shell__primary):has(> .ds-app-shell__secondary) > .ds-app-shell__secondary {
+    grid-column: 3;
+  }
+
+  .ds-app-shell[data-layout="fixed-rails"] > .ds-app-shell__primary,
+  .ds-app-shell[data-layout="fixed-rails"] > .ds-app-shell__secondary {
+    align-self: start;
+    max-block-size: calc(100dvb - var(--ds-app-shell-header-size) - (var(--ds-app-shell-gutter) * 2));
+    overflow: auto;
+  }
+}

package/dist/tests/a11y.js

@@ -0,0 +1,55 @@
+import { AxePuppeteer } from "@axe-core/puppeteer";
+/**
+ * Run axe-core against the given e2e page and fail loudly on any
+ * WCAG 2.1 A or AA violation. Best-practice rules are surfaced as
+ * warnings but do not fail the test — they belong to code review.
+ *
+ * Every ui-component test file MUST call this at least once per
+ * meaningful rendered state (default, disabled, error, open, …).
+ *
+ * @example
+ * const page = await newE2EPage({ html: `<ds-button>Click</ds-button>` });
+ * await expectA11y(page);
+ */
+export async function expectA11y(page, opts) {
+    // Stencil's newE2EPage() test fixture renders the given HTML fragment
+    // into a bare document that never gets a `lang` attribute on <html> —
+    // that's an artifact of the test harness, not something any DS
+    // component controls (a real consuming app always sets its own
+    // document lang). Without this, every component test would fail axe's
+    // `html-has-lang` (wcag2a) rule regardless of the component under
+    // test, masking real component-level violations in the noise. Set it
+    // here so the analysis reflects the component's own a11y, matching
+    // how it is actually consumed.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // Same reasoning for `document-title` (wcag2a): the bare test fixture
+    // has no <title>, which a real consuming page always provides.
+    await page.evaluate(() => {
+        if (!document.documentElement.lang) {
+            document.documentElement.lang = 'en';
+        }
+        if (!document.title) {
+            document.title = 'a11y test fixture';
+        }
+    });
+    // Stencil's E2EPage wraps a puppeteer Page; the AxePuppeteer
+    // constructor accepts the underlying page instance.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const results = await new AxePuppeteer(page)
+        .withTags(['wcag2a', 'wcag2aa'])
+        .disableRules(opts?.skip ?? [])
+        .analyze();
+    if (results.violations.length > 0) {
+        const summary = results.violations
+            .map((v) => `- [${v.impact ?? '?'}] ${v.id}: ${v.help} (${v.nodes.length} node(s))`)
+            .join('\n');
+        const label = opts?.label ? ` [${opts.label}]` : '';
+        throw new Error(`axe found ${results.violations.length} violation(s)${label}:\n${summary}\n\nFull results: ${JSON.stringify(results.violations, null, 2)}`);
+    }
+    // Surface best-practice warnings without failing.
+    const bp = results.incomplete?.filter((r) => r.tags?.includes('best-practice')) ?? [];
+    if (bp.length > 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`axe best-practice notes${opts?.label ? ` [${opts.label}]` : ''}: ${bp.map((r) => r.id).join(', ')}`);
+    }
+}

package/dist/types/Users/alex/projects/MyGitHub/chiralkit/packages/design-system/.stencil/tests/a11y.d.ts

@@ -0,0 +1,17 @@
+import type { E2EPage } from '@stencil/core/testing';
+/**
+ * Run axe-core against the given e2e page and fail loudly on any
+ * WCAG 2.1 A or AA violation. Best-practice rules are surfaced as
+ * warnings but do not fail the test — they belong to code review.
+ *
+ * Every ui-component test file MUST call this at least once per
+ * meaningful rendered state (default, disabled, error, open, …).
+ *
+ * @example
+ * const page = await newE2EPage({ html: `<ds-button>Click</ds-button>` });
+ * await expectA11y(page);
+ */
+export declare function expectA11y(page: E2EPage, opts?: {
+    skip?: string[];
+    label?: string;
+}): Promise<void>;

package/dist/types/components/ds-badge/ds-badge.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ## 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.
+ */
+export declare class DsBadge {
+    variant: "neutral" | "ui-component" | "recipe" | "agent" | "config";
+    render(): any;
+}

package/dist/types/components/ds-button/ds-button.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ## 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.
+ */
+export declare class DsButton {
+    variant: "primary" | "secondary" | "ghost";
+    size: "md" | "lg";
+    disabled: boolean;
+    type: "button" | "submit" | "reset";
+    href?: string;
+    render(): any;
+}

package/dist/types/components/ds-card/ds-card.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ## 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.
+ */
+export declare class DsCard {
+    render(): any;
+}

package/dist/types/components/ds-checkbox/ds-checkbox.d.ts

@@ -0,0 +1,94 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * ## 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.
+ */
+export declare class DsCheckbox {
+    private inputEl?;
+    checked: boolean;
+    indeterminate: boolean;
+    name?: string;
+    value?: string;
+    disabled: boolean;
+    required: boolean;
+    invalid: boolean;
+    describedBy?: string;
+    label?: string;
+    dsChange: EventEmitter<boolean>;
+    watchChecked(newValue: boolean): void;
+    watchIndeterminate(newValue: boolean): void;
+    componentDidLoad(): void;
+    componentDidUpdate(): void;
+    private syncNativeState;
+    private onChange;
+    render(): any;
+}

package/dist/types/components/ds-code-block/ds-code-block.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ## 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`.
+ */
+export declare class DsCodeBlock {
+    code: string;
+    language: string;
+    copied: boolean;
+    private timer?;
+    disconnectedCallback(): void;
+    private onCopy;
+    render(): any;
+}