@adia-ai/web-components 0.5.10 → 0.5.12

package/components/color-input/color-input.a2ui.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ColorInput.json",
+  "title": "ColorInput",
+  "description": "Compact form-bearing color input — opens a popover-anchored\n`<color-picker-ui>` from an inline swatch button. §302 (v0.5.12,\nFEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f\nOption B recipe (popover + button + color-picker) into a single\nform-associated tag for inline form contexts (settings drawer \"source\ncolor\" field, swatch-row inline-edit, etc.).",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ColorInput"
+    },
+    "disabled": {
+      "description": "Disables the trigger button + suppresses popover.",
+      "type": "boolean",
+      "default": false
+    },
+    "format": {
+      "description": "Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`).",
+      "type": "string",
+      "enum": [
+        "hex",
+        "oklch"
+      ],
+      "default": "hex"
+    },
+    "name": {
+      "description": "Form field name.",
+      "type": "string",
+      "default": ""
+    },
+    "open": {
+      "description": "Reflects the popover's open state. Set programmatically to open/close the picker without a click.",
+      "type": "boolean",
+      "default": false
+    },
+    "placement": {
+      "description": "Popover placement relative to the trigger.",
+      "type": "string",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "default": "bottom-start"
+    },
+    "value": {
+      "description": "Current color as a string in the active [format].",
+      "type": "string",
+      "default": "#3b82f6"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "composes": [
+      "button-ui",
+      "popover-ui",
+      "color-picker-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.",
+        "detail": {
+          "hex": {
+            "description": "Hex form (`#rrggbb`).",
+            "type": "string"
+          },
+          "oklch": {
+            "description": "OKLCH string (`oklch(L C H)`).",
+            "type": "string"
+          },
+          "value": {
+            "description": "Color in the active [format] (hex or oklch).",
+            "type": "string"
+          }
+        }
+      },
+      "input": {
+        "description": "Fired during continuous drag of the inner picker. Bubbles from inner picker.",
+        "detail": {
+          "hex": {
+            "type": "string"
+          },
+          "oklch": {
+            "type": "string"
+          },
+          "value": {
+            "description": "Color in the active [format].",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Inline compact color input — popover-anchored picker on click.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ColorInput\",\n    \"name\": \"brand\",\n    \"value\": \"#3b82f6\"\n  }\n]",
+        "name": "color-input-basic"
+      },
+      {
+        "description": "Compact picker exposing OKLCH value form.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ColorInput\",\n    \"name\": \"accent\",\n    \"format\": \"oklch\",\n    \"value\": \"oklch(0.7 0.15 220)\"\n  }\n]",
+        "name": "color-input-oklch"
+      }
+    ],
+    "keywords": [
+      "color-input",
+      "color",
+      "input",
+      "picker",
+      "swatch",
+      "inline",
+      "compact"
+    ],
+    "name": "UIColorInput",
+    "related": [
+      "color-picker",
+      "popover",
+      "button",
+      "swatch"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Popover is open; picker visible.",
+        "attribute": "open",
+        "name": "open"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "synonyms": {
+      "color-field": [
+        "color-input"
+      ],
+      "inline-color-picker": [
+        "color-input"
+      ]
+    },
+    "tag": "color-input-ui",
+    "tokens": {
+      "--color-input-swatch-size": {
+        "description": "Diameter (em) of the inline swatch circle inside the trigger button. Default 1em."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/color-input/color-input.css

@@ -0,0 +1,47 @@
+/**
+ * <color-input-ui> — compact form-bearing color input.
+ *
+ * §302 (v0.5.12, FEEDBACK-29 re-bucket). Light-DOM composition of
+ * <popover-ui> + <button-ui> + <color-picker-ui>. The host element
+ * carries form-control sizing tokens; inner button + popover keep
+ * their own primitive styling.
+ */
+
+@scope (color-input-ui) {
+  :scope {
+    --color-input-swatch-size: 1em;
+
+    display: inline-flex;
+    vertical-align: middle;
+  }
+
+  :scope[disabled] {
+    opacity: 0.55;
+    pointer-events: none;
+  }
+
+  :scope > popover-ui {
+    display: inline-flex;
+  }
+
+  /* Inline swatch chip inside the trigger button. The button-ui owns its
+   * own padding + height; the swatch is sized in em so it tracks the
+   * button's font-size + density automatically. */
+  .color-input__swatch {
+    display: inline-block;
+    inline-size: var(--color-input-swatch-size);
+    block-size: var(--color-input-swatch-size);
+    border-radius: 50%;
+    background: var(--swatch-color, transparent);
+    border: 1px solid var(--a-ui-border, currentColor);
+    margin-inline-end: var(--a-space-2, 0.5em);
+    flex: 0 0 auto;
+  }
+
+  .color-input__value {
+    font-variant-numeric: tabular-nums;
+    font-family: var(--a-font-family-mono, monospace);
+    font-size: 0.92em;
+    color: var(--a-ui-text, currentColor);
+  }
+}

package/components/color-input/color-input.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `<color-input-ui>` — compact form-bearing color input.
+ *
+ * §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the
+ * USAGE.md §221f recipe (popover + button + color-picker) into a single
+ * form-associated tag for inline form contexts (settings drawer "source
+ * color" field, swatch-row inline-edit). Light-DOM composition; the
+ * inner picker fires `change` + `input` which this element re-emits
+ * with a flattened detail payload that always carries both hex + oklch
+ * string forms regardless of `[format]`.
+ *
+ * Hand-authored (FORM_BEARING in dts-codegen) because the rich event
+ * detail (parallel hex+oklch views) can't be expressed by the
+ * yaml `events:` shape alone.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/color-input
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+/**
+ * Output format selected by the `[format]` attribute. Drives the shape of
+ * `value` (and the matching `detail.value` field). Both `hex` and `oklch`
+ * forms are always present on the event detail regardless of `[format]`.
+ */
+export type ColorInputFormat = 'hex' | 'oklch';
+
+/**
+ * Detail payload for both `change` (commit) and `input` (continuous drag)
+ * events. `value` mirrors the current `[format]`; `hex` and `oklch` are
+ * always populated parallel views, so consumers don't need to parse the
+ * string.
+ */
+export interface ColorInputChangeEventDetail {
+  /** Format-respecting string. Equals `hex` when `[format="hex"]`; equals `oklch` when `[format="oklch"]`. */
+  value: string;
+  /** Hex form (`#rrggbb`). Gamut-mapped to sRGB. */
+  hex: string;
+  /** OKLCH string (`oklch(L C H)`, fixed precision). */
+  oklch: string;
+}
+export type ColorInputChangeEvent = CustomEvent<ColorInputChangeEventDetail>;
+export type ColorInputInputEvent = CustomEvent<ColorInputChangeEventDetail>;
+
+export class UIColorInput extends UIFormElement {
+  /** Form field name. */
+  name: string;
+  /** Current color string in the active `format`. */
+  value: string;
+  /** Output format — drives the shape of `value`. Detail always carries both `hex` and `oklch`. */
+  format: ColorInputFormat;
+  /** Disables the trigger button + suppresses the popover. */
+  disabled: boolean;
+  /** Popover placement relative to the trigger button. */
+  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+  /** Reflects the inner popover's open state. Set programmatically to open/close without a click. */
+  open: boolean;
+
+  /** Open the picker programmatically. */
+  showPicker(): void;
+  /** Close the picker programmatically. */
+  hidePicker(): void;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIColorInput, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: ColorInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: ColorInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/color-input/color-input.js

@@ -0,0 +1,26 @@
+/**
+ * `<color-input-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIColorInput } from '@adia-ai/web-components/components/color-input/class';
+ *
+ * Per ADR-0027, this module does NOT auto-import the composed primitives
+ * (`<popover-ui>`, `<button-ui>`, `<color-picker-ui>`). Consumers must
+ * register them explicitly before mounting `<color-input-ui>`:
+ *
+ *   import '@adia-ai/web-components/components/popover';
+ *   import '@adia-ai/web-components/components/button';
+ *   import '@adia-ai/web-components/components/color-picker';
+ *   import '@adia-ai/web-components/components/color-input';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIColorInput } from './class.js';
+
+defineIfFree('color-input-ui', UIColorInput);
+
+export { UIColorInput };

package/components/color-input/color-input.yaml

@@ -0,0 +1,145 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIColorInput
+tag: color-input-ui
+component: ColorInput
+category: input
+version: 1
+description: |-
+  Compact form-bearing color input — opens a popover-anchored
+  `<color-picker-ui>` from an inline swatch button. §302 (v0.5.12,
+  FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f
+  Option B recipe (popover + button + color-picker) into a single
+  form-associated tag for inline form contexts (settings drawer "source
+  color" field, swatch-row inline-edit, etc.).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. The consumer (or demo shell) explicitly imports
+# the composed primitives. This element creates `<button-ui>` +
+# `<popover-ui>` + `<color-picker-ui>` light-DOM children but assumes the
+# consumer has already imported their auto-register modules.
+composes:
+  - button-ui
+  - popover-ui
+  - color-picker-ui
+props:
+  name:
+    description: Form field name.
+    type: string
+    default: ""
+  value:
+    description: Current color as a string in the active [format].
+    type: string
+    default: "#3b82f6"
+  format:
+    description: Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`).
+    type: string
+    default: hex
+    reflect: true
+    enum:
+      - hex
+      - oklch
+  disabled:
+    description: Disables the trigger button + suppresses popover.
+    type: boolean
+    default: false
+    reflect: true
+  placement:
+    description: Popover placement relative to the trigger.
+    type: string
+    default: bottom-start
+    reflect: true
+    enum:
+      - top
+      - bottom
+      - left
+      - right
+      - top-start
+      - top-end
+      - bottom-start
+      - bottom-end
+  open:
+    description: Reflects the popover's open state. Set programmatically to open/close the picker without a click.
+    type: boolean
+    default: false
+    reflect: true
+events:
+  change:
+    description: Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.
+    detail:
+      value:
+        type: string
+        description: Color in the active [format] (hex or oklch).
+      hex:
+        type: string
+        description: Hex form (`#rrggbb`).
+      oklch:
+        type: string
+        description: OKLCH string (`oklch(L C H)`).
+  input:
+    description: Fired during continuous drag of the inner picker. Bubbles from inner picker.
+    detail:
+      value:
+        type: string
+        description: Color in the active [format].
+      hex:
+        type: string
+      oklch:
+        type: string
+slots: {}
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: open
+    description: Popover is open; picker visible.
+    attribute: open
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+traits: []
+tokens:
+  --color-input-swatch-size:
+    description: Diameter (em) of the inline swatch circle inside the trigger button. Default 1em.
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: color-input-basic
+    description: Inline compact color input — popover-anchored picker on click.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "ColorInput",
+          "name": "brand",
+          "value": "#3b82f6"
+        }
+      ]
+  - name: color-input-oklch
+    description: Compact picker exposing OKLCH value form.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "ColorInput",
+          "name": "accent",
+          "format": "oklch",
+          "value": "oklch(0.7 0.15 220)"
+        }
+      ]
+keywords:
+  - color-input
+  - color
+  - input
+  - picker
+  - swatch
+  - inline
+  - compact
+synonyms:
+  color-field:
+    - color-input
+  inline-color-picker:
+    - color-input
+related:
+  - color-picker
+  - popover
+  - button
+  - swatch

package/components/index.js

@@ -47,6 +47,7 @@ export { UIBadge } from './badge/badge.js';
 export { UIBreadcrumb } from './breadcrumb/breadcrumb.js';
 export { UICommand } from './command/command.js';
 export { UIColorPicker } from './color-picker/color-picker.js';
+export { UIColorInput } from './color-input/color-input.js';
 export { UINoodles } from './noodles/noodles.js';
 export { UITable } from './table/table.js';
 export { UITableToolbar } from './table-toolbar/table-toolbar.js';

package/components/stat/stat-ui.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<stat-ui>` — Metric/KPI display. Value + label + optional change indicator and trend.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stat
+ *
+ * HAND-AUTHORED (v0.5.12 §253 FB-30 close-out). The codegen pipeline's
+ * `isCssOnly()` check at `scripts/build/dts-codegen.mjs:186-194` looks for
+ * `${dirname}.js` — but stat ships `stat-ui.js` (irregular filename; the
+ * v0.6.0 §303 rename will normalize to `stat.js`). Pre-§303 the codegen
+ * false-positives `isCssOnly` and skips this directory entirely. Hand-author
+ * this file matching `stat.yaml` props until §303 lands.
+ *
+ * Filename mirrors the JS file (`stat-ui.js` → `stat-ui.d.ts`) so TypeScript
+ * resolves the side-effect import `import '@adia-ai/web-components/components/stat/stat-ui.js'`
+ * to a typed module. Post-§303, both files rename to `stat.{js,d.ts}` and
+ * codegen takes over.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStat extends UIElement {
+  /** Eyebrow label describing the metric. */
+  label: string;
+  /** Primary metric value (large display number / string). */
+  value: string;
+  /** Change indicator text (e.g. "+12%", "-3%"). Slotted as a badge next to value. */
+  change: string;
+  /**
+   * Trend direction or narrative subtitle. Canonical values color the change
+   * badge: `up` = success (green), `down` = danger (red), `flat`/`neutral` =
+   * muted. Any other string renders as caption-style text under the primary
+   * value (not enum-validated; yaml documents the canonical set but the type
+   * stays `string` for narrative subtitles).
+   */
+  trend: string;
+  /** Icon name displayed in the icon slot (Phosphor icon registry). */
+  icon: string;
+}

package/components/swatch/class.js

@@ -167,6 +167,14 @@ export class UISwatch extends UIElement {
     selectable:   { type: Boolean, default: false,    reflect: true },
     selected:     { type: Boolean, default: false,    reflect: true },
     autoContrast: { type: Boolean, default: false,    reflect: true },
+    // §253 (v0.5.12, FB-23 §1): label position relative to the tile.
+    // `below` (default) = current shape="block" stacked layout.
+    // `overlay` = label sits ON the tile via absolute positioning;
+    // pair with `[auto-contrast]` for OKLab-L-driven legibility.
+    // Only meaningful when shape="block"; other shapes ignore this prop.
+    // CSS-only behavior; no JS runtime delta beyond yaml-declared
+    // reflective attribute. Unblocks Tokens Studio C1.3 dogfood.
+    labelPosition: { type: String, default: 'below', reflect: true, attribute: 'label-position' },
   };
 
   static template = () => null;

package/components/swatch/swatch.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "autoContrast": {
-      "description": "When set, computes the swatch color's OKLab L and switches the label /\ndetail color between light + dark so it remains legible against the\ntile background. Only applies to shape=\"block\" (where the label sits\nON the tile). Uses a 1px canvas probe to handle any CSS color form\n(oklch / hex / hsl / named / var() references).\n",
+      "description": "When set, computes the swatch color's OKLab L and switches the label /\ndetail color between light + dark so it remains legible against the\ntile background. Active when `label-position=\"overlay\"` (where the\nlabel sits ON the tile). Uses a 1px canvas probe to handle any CSS\ncolor form (oklch / hex / hsl / named / var() references).\n",
       "type": "boolean",
       "default": false
     },
@@ -51,6 +51,15 @@
       "type": "string",
       "default": ""
     },
+    "labelPosition": {
+      "description": "§253 (v0.5.12, FB-23 §1). Position the label relative to the tile.\n`below` (default) stacks label under the tile (current shape=\"block\"\nlayout — `flex-direction: column`). `overlay` renders the label\nINSIDE the tile via absolute positioning; pair with `[auto-contrast]`\nto keep the label legible against the tile color (`data-on-light` /\n`data-on-dark` classes auto-stamped per OKLab-L probe). Only meaningful\nwhen `shape=\"block\"` (other shapes are too small for in-tile labels).\nUnblocks Tokens Studio's C1.3 dogfood migration (label-inside-the-tile\npattern; blocked 3 cycles on this design call).",
+      "type": "string",
+      "enum": [
+        "below",
+        "overlay"
+      ],
+      "default": "below"
+    },
     "selectable": {
       "description": "When set, makes the swatch keyboard-focusable + clickable. Sets role=\"button\" + tabindex=\"0\". Dispatches a \"select\" event on activation (click / Enter / Space).",
       "type": "boolean",

package/components/swatch/swatch.css

@@ -141,6 +141,38 @@
     white-space: nowrap;
   }
 
+  /* ═══════ §253 (v0.5.12, FB-23 §1): label-position="overlay" ═══════
+     Renders the label INSIDE the block tile via absolute positioning.
+     Pair with [auto-contrast] for OKLab-L-driven legibility (existing
+     `data-on-light` / `data-on-dark` classes stamp on the label per
+     the OKLab-L probe; see auto-contrast rules below).
+
+     The host becomes the positioning context (default flex-column flow
+     for the tile + detail line remains); the label is pulled out of
+     flow + absolutely positioned to overlap the tile's full bounds
+     (`top: 0; height: var(--_block-h)`). Tile is the first flex child
+     with the same height, so the absolute label aligns exactly to it.
+
+     Only meaningful when `shape="block"` (other shapes are too small
+     for in-tile labels). Unblocks Tokens Studio's C1.3 dogfood
+     migration (label-inside-the-tile pattern; blocked 3 cycles on this
+     design call). */
+  :scope[shape="block"][label-position="overlay"] {
+    position: relative;
+  }
+  :scope[shape="block"][label-position="overlay"] > [data-label] {
+    position: absolute;
+    top: 0;
+    inset-inline: 0;
+    height: var(--_block-h, var(--swatch-tile-lg));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-block-start: 0;        /* override the below-tile margin */
+    padding: var(--a-space-1) var(--a-space-2);
+    pointer-events: none;          /* don't intercept clicks on the tile */
+  }
+
   /* ═══════ Sizes ═══════
      Override the dot/square diameter (`--_size`) and the block-shape
      height (`--_block-h`) for each size preset. Line/dashed widths use

package/components/swatch/swatch.d.ts

@@ -31,9 +31,9 @@ export type SwatchSelectEvent = CustomEvent<SwatchSelectEventDetail>;
 export class UISwatch extends UIElement {
   /** When set, computes the swatch color's OKLab L and switches the label /
 detail color between light + dark so it remains legible against the
-tile background. Only applies to shape="block" (where the label sits
-ON the tile). Uses a 1px canvas probe to handle any CSS color form
-(oklch / hex / hsl / named / var() references).
+tile background. Active when `label-position="overlay"` (where the
+label sits ON the tile). Uses a 1px canvas probe to handle any CSS
+color form (oklch / hex / hsl / named / var() references).
  */
   autoContrast: boolean;
   /** Optional marker(s) rendered in the upper-right of the tile. Single value
@@ -54,6 +54,16 @@ are silently dropped.
   detail: string;
   /** Optional label rendered next to (or below, for shape="block") the swatch. Use the default slot for richer content. */
   label: string;
+  /** §253 (v0.5.12, FB-23 §1). Position the label relative to the tile.
+`below` (default) stacks label under the tile (current shape="block"
+layout — `flex-direction: column`). `overlay` renders the label
+INSIDE the tile via absolute positioning; pair with `[auto-contrast]`
+to keep the label legible against the tile color (`data-on-light` /
+`data-on-dark` classes auto-stamped per OKLab-L probe). Only meaningful
+when `shape="block"` (other shapes are too small for in-tile labels).
+Unblocks Tokens Studio's C1.3 dogfood migration (label-inside-the-tile
+pattern; blocked 3 cycles on this design call). */
+  labelPosition: 'below' | 'overlay';
   /** When set, makes the swatch keyboard-focusable + clickable. Sets role="button" + tabindex="0". Dispatches a "select" event on activation (click / Enter / Space). */
   selectable: boolean;
   /** Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed. */

package/components/swatch/swatch.yaml

@@ -80,12 +80,30 @@ props:
     description: |
       When set, computes the swatch color's OKLab L and switches the label /
       detail color between light + dark so it remains legible against the
-      tile background. Only applies to shape="block" (where the label sits
-      ON the tile). Uses a 1px canvas probe to handle any CSS color form
-      (oklch / hex / hsl / named / var() references).
+      tile background. Active when `label-position="overlay"` (where the
+      label sits ON the tile). Uses a 1px canvas probe to handle any CSS
+      color form (oklch / hex / hsl / named / var() references).
     type: boolean
     default: false
     reflect: true
+  labelPosition:
+    description: |-
+      §253 (v0.5.12, FB-23 §1). Position the label relative to the tile.
+      `below` (default) stacks label under the tile (current shape="block"
+      layout — `flex-direction: column`). `overlay` renders the label
+      INSIDE the tile via absolute positioning; pair with `[auto-contrast]`
+      to keep the label legible against the tile color (`data-on-light` /
+      `data-on-dark` classes auto-stamped per OKLab-L probe). Only meaningful
+      when `shape="block"` (other shapes are too small for in-tile labels).
+      Unblocks Tokens Studio's C1.3 dogfood migration (label-inside-the-tile
+      pattern; blocked 3 cycles on this design call).
+    type: string
+    default: below
+    reflect: true
+    attribute: label-position
+    enum:
+      - below
+      - overlay
 events:
   select:
     description: Fired when a selectable swatch is activated (click / Enter / Space). detail carries the swatch's value, color, and label.