@adia-ai/web-components 0.8.40 → 0.8.41

package/components/calendar-picker/calendar-picker.yaml

@@ -4,23 +4,31 @@ tag: calendar-picker-ui
 status: stable
 component: CalendarPicker
 category: input
-version: 1
+version: 2
 description: >-
-  Date picker with trigger button and popover calendar grid.
-  Form-associated input emitting ISO date string via change events;
-  supports min/max and disabled-date masks. Use for single-date input in
-  forms; for date ranges compose two pickers or use a dedicated range
-  component.
+  Date (and, per `[precision]`, date+time) picker with trigger button and
+  popover panel. Form-associated input emitting an ISO date (or, when
+  `precision` is `minute`/`second`, ISO datetime) string via change events;
+  supports min/max and disabled-date masks. Use for single-date or
+  single-datetime input in forms; for date ranges use
+  <date-range-picker-ui> instead of composing two calendar-picker
+  instances. gh#1372 (#1363 C3c) folded <datetime-picker-ui>'s surface into
+  this widened `precision` axis — see the deprecated
+  <datetime-picker-ui> alias.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # in their render() do NOT auto-import them. Consumer (or demo shell) must
 # explicitly import each composed primitive.
 composes:
-  - button-ui  # day cells + month nav (gh issue 276 wave 4)
+  - calendar-grid-ui  # popover's day-grid substrate (gh#1371, #1363 C3a) — button-ui day cells + month nav live inside it
+  - time-picker-ui    # the time pane (gh#1372) — composed only when [precision] is minute/second
+  - divider-ui        # pane separator (gh#1372) — composed only when [precision] is minute/second
+
 props:
   name:
     description: Form field name
     type: string
     default: ''
+    reflect: true
   required:
     description: Required for validation
     type: boolean
@@ -31,24 +39,59 @@ props:
     type: boolean
     default: false
     reflect: true
+  readonly:
+    description: Blocks edits; the trigger stays keyboard-focusable for screen-reader inspection but the popover does not open. #1363 C3d convergence — inherited from the shared form-element base, now with real behavior wired.
+    type: boolean
+    default: false
+    reflect: true
   format:
-    description: Display format for the selected date
+    description: Display format for the trigger text. `short`, e.g. `Jan 1, 2026` (+ ` 14:30` when `precision` is minute/second); `long`, e.g. `January 1, 2026`; `iso`, the raw ISO string.
     type: string
     default: short
     enum:
     - short
     - long
     - iso
-  label:
-    description: Label text displayed above the trigger
-    type: string
-    default: ''
   max:
-    description: Maximum selectable date in ISO format (YYYY-MM-DD)
+    description: Maximum selectable date (ISO `YYYY-MM-DD`), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second.
     type: string
     default: ''
+    reflect: true
   min:
-    description: Minimum selectable date in ISO format (YYYY-MM-DD)
+    description: Minimum selectable date (ISO `YYYY-MM-DD`), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second.
+    type: string
+    default: ''
+    reflect: true
+  precision:
+    description: Mode axis (gh#1372, #1363 C3c). `date` (default) is a date-only picker — the composed calendar-grid-ui alone. `minute`/`second` additionally compose a <time-picker-ui> pane (separated by a <divider-ui>); `value` becomes a full ISO 8601 datetime string ("YYYY-MM-DDTHH:mm" or with seconds) and `hour-cycle`/`step`/`locale` become active.
+    type: string
+    default: date
+    enum:
+    - date
+    - minute
+    - second
+    reflect: true
+  step:
+    description: Per-Arrow-keypress increment in seconds for the time pane. Active only when `precision` is minute/second. 60 = minute precision (default), 900 = 15-minute, 1 = second precision.
+    type: number
+    default: 60
+    reflect: true
+  hourcycle:
+    description: |
+      Hour cycle for the time pane. Active only when `precision` is
+      minute/second. Empty (default) derives from the document locale.
+      `h12` forces a 12-hour cycle with an AM/PM (meridiem) segment; `h23`
+      forces 24-hour cycle.
+    type: string
+    default: ''
+    enum:
+    - ''
+    - h12
+    - h23
+    reflect: true
+    attribute: hour-cycle
+  locale:
+    description: BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Active only when `precision` is minute/second. Falls back to `<html lang>` then to browser default.
     type: string
     default: ''
   open:
@@ -61,7 +104,7 @@ props:
     type: string
     default: Select date...
   value:
-    description: Selected date (ISO string)
+    description: Selected date (ISO string), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second.
     type: string
     default: ''
   placement:
@@ -80,73 +123,208 @@ props:
       - bottom-end
 events:
   change:
-    description: Fired when a date is selected
+    description: Fired when a value commits (date picked, or — when `precision` is minute/second — date picked + time edited, or Apply clicked in an explicit-commit footer).
+  input:
+    description: Fired during partial selection (date picked but time still pending, or vice versa — meaningful only when `precision` is minute/second).
+    detail:
+      value: string
+  open:
+    description: Popover opened (user clicked the trigger, pressed Enter/Space, or Apply/Cancel in a footer closed then reopened).
+    detail:
+      trigger: string
+  close:
+    description: Popover closed (without commit, or after commit).
+    detail:
+      reason: string
+  invalid:
+    description: A constraint failed (out of range, or — when `precision` is minute/second — a parse error).
+    detail:
+      value: string
+      reason: string
 slots:
-  calendar:
-    description: Popover container for the month grid
-  label:
-    description: Label element above the trigger
+  popover:
+    description: >-
+      Popover container for the calendar pane(s) (gh#1461; renamed from the
+      yaml's prior `calendar` key, which matched no real slot="…" attribute
+      — render() stamps this element as slot="popover").
   trigger:
     description: Combobox button that opens the calendar popover
+  footer:
+    description: Optional Apply/Cancel buttons for explicit-commit flows. Spans the pane(s) below the calendar (+ time, when `precision` is minute/second).
 states:
 - name: idle
   description: Default, ready for interaction.
 - name: disabled
   description: Non-interactive; dimmed.
   attribute: disabled
+- name: readonly
+  description: Read-only; trigger keyboard-focusable but popover does not open.
+  attribute: readonly
 traits: []
-tokens: {}
+tokens:
+  --calendar-picker-popover-gap:
+    description: Gap between the calendar pane and the time pane. Only visible when `precision` is minute/second.
+    default: var(--a-space-3)
+  --calendar-picker-divider:
+    description: Pane divider color. Only visible when `precision` is minute/second.
+    default: var(--md-sys-color-neutral-outline-variant)
 requiredIcons:
   - calendar
-  - caret-left
-  - caret-right
 a2ui:
   rules:
     - rule: 'Form-associated date input. Trigger button + popover calendar grid; emits ISO date string via change events.'
       reason: 'Standard date-picker contract.'
-    - rule: 'Use for single-date input. For date ranges compose two pickers or use a dedicated range component.'
+    - rule: 'Use for single-date input. For date ranges use <date-range-picker-ui> instead of composing two calendar-picker instances.'
       reason: 'Single-value scope.'
     - rule: 'min/max attributes constrain selectable range; disabled-dates accepts a function or date list.'
       reason: 'Constraint knobs.'
-anti_patterns: []
+    - rule: 'Set `precision: "minute"` or `precision: "second"` for combined date+time selection — composes a time pane alongside the calendar grid. `value` MUST then be ISO 8601 datetime ("YYYY-MM-DDTHH:mm" or with seconds) OR empty string; a date-only or time-only string fires `invalid`.'
+      reason: 'Widened mode axis (gh#1372, #1363 C3c) — folds what <datetime-picker-ui> used to be its own primitive for.'
+    - rule: '`hour-cycle`/`step`/`locale` are only meaningful when `precision` is minute/second.'
+      reason: 'Time-pane-only knobs.'
+    - rule: 'Do NOT wrap in `<field-ui label>` AND also expect a bare `label` attribute on `<calendar-picker-ui>` to render — the picker has no first-class label; use `<field-ui label="…">` (siblings all follow this convention).'
+      reason: 'Label delegates to field-ui (#1363 C3d).'
+anti_patterns:
+  - wrong: |
+      {"component": "CalendarPicker", "precision": "minute", "value": "2026-05-24"}
+    why: |
+      `value` is a date-only string but `precision` is "minute" — no time
+      component. The contract requires a full ISO 8601 datetime including
+      the `T` and time segment when `precision` isn't "date".
+    fix: |
+      {"component": "CalendarPicker", "precision": "minute", "value": "2026-05-24T00:00"}
+  - wrong: |
+      {"component": "CalendarPicker", "label": "Date"}
+    why: |
+      `label` is not a first-class prop on CalendarPicker (#1363 C3d) —
+      siblings all delegate the field label to `<field-ui label>`.
+    fix: |
+      {"component": "Field", "label": "Date", "children": ["cal"]}
 examples:
 - name: date-picker
-  description: Date and time picker form with calendar picker and time selects.
+  description: Event form with a name field and a date picker, wrapped in Field for its label per #1363 C3d (CalendarPicker has no first-class `label`).
   a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n\
     \    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"col\"\n    ]\n  },\n  {\n    \"id\"\
-    : \"col\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"name\",\n      \"cal\",\n      \"btn\"\n    ],\n\
+    : \"col\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"name\",\n      \"field\",\n      \"btn\"\n    ],\n\
     \    \"gap\": \"4\"\n  },\n  {\n    \"id\": \"name\",\n    \"component\": \"Input\",\n    \"label\": \"Event Name\"\n\
-    \  },\n  {\n    \"id\": \"cal\",\n    \"component\": \"CalendarPicker\",\n    \"label\": \"Date\"\n  },\n  {\n    \"id\"\
+    \  },\n  {\n    \"id\": \"field\",\n    \"component\": \"Field\",\n    \"label\": \"Date\",\n    \"children\": [\n      \"\
+    cal\"\n    ]\n  },\n  {\n    \"id\": \"cal\",\n    \"component\": \"CalendarPicker\"\n  },\n  {\n    \"id\"\
     : \"btn\",\n    \"component\": \"Button\",\n    \"text\": \"Schedule\",\n    \"variant\": \"primary\"\n  }\n]"
-- name: date-range-picker
-  description: Date range selection form with start/end calendar pickers, quick-pick badges, and apply button.
-  a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n\
-    \      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"\
-    title\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\"\
-    : \"Select Dates\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n\
-    \    \"children\": [\n      \"fields\"\n    ]\n  },\n  {\n    \"id\": \"fields\",\n    \"component\": \"Column\",\n  \
-    \  \"children\": [\n      \"calendars-row\",\n      \"quick-picks\"\n    ],\n    \"gap\": \"4\"\n  },\n  {\n    \"id\"\
-    : \"calendars-row\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"start-cal\",\n      \"end-cal\"\n    ],\n\
-    \    \"gap\": \"3\"\n  },\n  {\n    \"id\": \"start-cal\",\n    \"component\": \"CalendarPicker\",\n    \"label\": \"\
-    Start Date\",\n    \"name\": \"startDate\"\n  },\n  {\n    \"id\": \"end-cal\",\n    \"component\": \"CalendarPicker\"\
-    ,\n    \"label\": \"End Date\",\n    \"name\": \"endDate\"\n  },\n  {\n    \"id\": \"quick-picks\",\n    \"component\"\
-    : \"Row\",\n    \"children\": [\n      \"pick-today\",\n      \"pick-week\",\n      \"pick-month\",\n      \"pick-quarter\"\
-    \n    ],\n    \"gap\": \"2\"\n  },\n  {\n    \"id\": \"pick-today\",\n    \"component\": \"Badge\",\n    \"textContent\"\
-    : \"Today\"\n  },\n  {\n    \"id\": \"pick-week\",\n    \"component\": \"Badge\",\n    \"textContent\": \"This Week\"\n\
-    \  },\n  {\n    \"id\": \"pick-month\",\n    \"component\": \"Badge\",\n    \"textContent\": \"This Month\"\n  },\n  {\n\
-    \    \"id\": \"pick-quarter\",\n    \"component\": \"Badge\",\n    \"textContent\": \"This Quarter\"\n  },\n  {\n    \"\
-    id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"apply-btn\"\n    ]\n  },\n  {\n    \"id\"\
-    : \"apply-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Apply\",\n    \"variant\": \"primary\"\n  }\n]"
+- name: datetime-picker
+  description: Combined date+time selection via precision — the mode gh#1372 folded in from the former <datetime-picker-ui>.
+  a2ui: |
+    [
+      {
+        "id": "field",
+        "component": "Field",
+        "label": "Appointment",
+        "children": ["dt"]
+      },
+      {
+        "id": "dt",
+        "component": "CalendarPicker",
+        "name": "appointment",
+        "precision": "minute",
+        "min": "2026-01-01T00:00",
+        "max": "2026-12-31T23:59"
+      }
+    ]
+- name: constrained-date
+  description: Single-date picker constrained to a future booking window via min/max, paired with a submit button.
+  a2ui: >-
+    [
+      {
+        "id": "root",
+        "component": "Card",
+        "children": [
+          "sec"
+        ]
+      },
+      {
+        "id": "sec",
+        "component": "Section",
+        "children": [
+          "col"
+        ]
+      },
+      {
+        "id": "col",
+        "component": "Column",
+        "children": [
+          "field",
+          "btn"
+        ],
+        "gap": "4"
+      },
+      {
+        "id": "field",
+        "component": "Field",
+        "label": "Check-in date",
+        "children": [
+          "cal"
+        ]
+      },
+      {
+        "id": "cal",
+        "component": "CalendarPicker",
+        "name": "checkin",
+        "min": "2026-08-16",
+        "max": "2026-12-31"
+      },
+      {
+        "id": "btn",
+        "component": "Button",
+        "text": "Reserve",
+        "variant": "primary"
+      }
+    ]
+- name: second-precision
+  description: Log-cursor picker with second precision — gh#1372's fold of the former datetime-picker second-precision example.
+  a2ui: |
+    [
+      {
+        "id": "dt",
+        "component": "CalendarPicker",
+        "name": "log-cursor",
+        "precision": "second",
+        "step": 1,
+        "value": "2026-05-24T14:30:45"
+      }
+    ]
 keywords:
 - calendarpicker
 - calendar-picker
 - calendar
 - picker
+- datetimepicker
+- datetime-picker
+- datetime
+- date-time
+- dateandtime
+- appointment
+- schedule
+- timestamp
 synonyms:
   tags:
   - DateTimeInput
   - DatePicker
+  - DateTimePicker
+  - DatetimeInput
+  - Timestamp
+  datetime:
+  - date-time
+  - timestamp
+  - appointment
+  - schedule
+  appointment:
+  - datetime
+  - meeting
+  - schedule
 related:
 - input
 - button
 - badge
+- date-range-picker
+- time-picker
+- field
+- popover

package/components/canvas/canvas.a2ui.json

@@ -46,16 +46,17 @@
       "canvas"
     ],
     "name": "UICanvas",
+    "parts": {
+      "default": {
+        "description": "Template-owned anatomy, not a light-DOM insertion point (gh#1454). render() appends its own `<a2ui-root>` rendering surface; the runtime owns all rendered content (a2ui rule below: \"Do not place static children inside\"). No consumer content is captured or preserved."
+      }
+    },
     "related": [
       "A2uiRoot",
       "GenRoot",
       "EditorCanvas"
     ],
-    "slots": {
-      "default": {
-        "description": "Default slot — primary child content."
-      }
-    },
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/canvas/canvas.d.ts

@@ -29,9 +29,46 @@ export class UICanvas extends UIElement {
   /** Process an array of A2UI messages in order. */
   processAll(messages: unknown[]): void;
 
+  /**
+   * Transactionally replace the rendered doc — passthrough to
+   * `<a2ui-root>#replaceDoc` (spec-a2ui-surface-lifecycle.md, ADR-0061,
+   * gh#1364): an existing surface regenerates through a lifecycle bracket
+   * (old content stays visible, no blank frame) instead of reset()+replay.
+   */
+  replaceDoc(messages: unknown[]): void;
+
   /** Clear the canvas surface — discards all components. */
   reset(): void;
 
+  /**
+   * Begin a regeneration bracket — passthrough to the wrapped
+   * `<a2ui-root>`'s renderer (spec-a2ui-surface-lifecycle.md, gh#1364).
+   * Returns the generationId, or null (no-op: root not ready yet, or
+   * `surfaceId` is missing/synthetic).
+   */
+  beginSurfaceUpdate(surfaceId: string, opts?: {
+    generationId?: string;
+    reason?: 'refine' | 'revalidate' | 'regenerate';
+    mode?: 'replace' | 'patch';
+  }): string | null;
+
+  /** Apply messages to a bracketed (buffers) or live (applies immediately) surface. */
+  applyTo(surfaceId: string, messages: unknown): void;
+
+  /**
+   * Commit the in-flight generation opened by `beginSurfaceUpdate`.
+   * Returns false when there was nothing to commit or the generationId
+   * was superseded (ignored, not an error).
+   */
+  commitSurfaceUpdate(surfaceId: string, generationId?: string): Promise<boolean>;
+
+  /**
+   * Abort the in-flight generation — prior content (if any) stays visible
+   * as error-stale. Returns false when there was nothing to abort or the
+   * generationId was superseded.
+   */
+  abortSurfaceUpdate(surfaceId: string, generationId?: string, error?: Record<string, unknown>): boolean;
+
   /** Return the formatted innerHTML of the internal `<a2ui-root>`. */
   getHTML(): string;
 

package/components/canvas/canvas.js

@@ -179,11 +179,69 @@ export class UICanvas extends UIElement {
     });
   }
 
+  /**
+   * Transactionally replace the rendered doc — passthrough to
+   * `<a2ui-root>#replaceDoc` (spec-a2ui-surface-lifecycle.md, ADR-0061,
+   * gh#1364): an existing surface regenerates through a lifecycle bracket
+   * (old content stays visible, no blank frame) instead of `reset()` +
+   * re-process. Degrades to reset()+processAll on a root that predates
+   * gh#1364 (FEEDBACK-81's lazy load means an older cached module is
+   * possible).
+   */
+  replaceDoc(messages) {
+    this.#whenRoot((root) => {
+      if (typeof root.replaceDoc === 'function') {
+        root.replaceDoc(messages);
+      } else {
+        root.reset();
+        for (const msg of messages || []) root.process(msg);
+      }
+    });
+  }
+
   /** Reset the canvas. */
   reset() {
     this.#whenRoot((root) => root.reset());
   }
 
+  // ── Surface lifecycle passthroughs (spec-a2ui-surface-lifecycle.md,
+  // ADR-0061, gh#1364) — a caller that wants to bracket ITS OWN async
+  // generation call (open before the await, commit/abort after) needs the
+  // generationId back synchronously, so these skip the `#whenRoot`
+  // deferred-queue path `process`/`processAll`/`replaceDoc` use and read
+  // `this.#rootEl.renderer` directly. Each degrades to a safe no-op
+  // (null / false) when the root isn't upgraded yet or predates gh#1364 —
+  // same shape as the renderer's own missing/synthetic-surface no-ops.
+
+  /** Begin a regeneration bracket. Returns the generationId, or null (no-op). */
+  beginSurfaceUpdate(surfaceId, opts) {
+    const renderer = this.#rootEl?.renderer;
+    return typeof renderer?.beginSurfaceUpdate === 'function'
+      ? renderer.beginSurfaceUpdate(surfaceId, opts)
+      : null;
+  }
+
+  /** Apply messages to a bracketed (or live, unbracketed) surface. */
+  applyTo(surfaceId, messages) {
+    this.#rootEl?.renderer?.applyTo?.(surfaceId, messages);
+  }
+
+  /** Commit the in-flight generation. Returns false on no-op (nothing to commit / stale generationId). */
+  commitSurfaceUpdate(surfaceId, generationId) {
+    const renderer = this.#rootEl?.renderer;
+    return typeof renderer?.commitSurfaceUpdate === 'function'
+      ? renderer.commitSurfaceUpdate(surfaceId, generationId)
+      : false;
+  }
+
+  /** Abort the in-flight generation — prior content (if any) stays visible as error-stale. */
+  abortSurfaceUpdate(surfaceId, generationId, error) {
+    const renderer = this.#rootEl?.renderer;
+    return typeof renderer?.abortSurfaceUpdate === 'function'
+      ? renderer.abortSurfaceUpdate(surfaceId, generationId, error)
+      : false;
+  }
+
   /** Return formatted innerHTML of the a2ui-root. */
   getHTML() {
     return this.#rootEl?.innerHTML ?? '';
@@ -219,12 +277,23 @@ export class UICanvas extends UIElement {
   get historyLength() { return this.#history.length; }
   get historyIndex() { return this.#historyIndex; }
 
+  // Surface lifecycle (spec-a2ui-surface-lifecycle.md, ADR-0061, gh#1364):
+  // history stepping replays through <a2ui-root>#replaceDoc — a
+  // transactional per-surface regeneration bracket — instead of
+  // reset()+replay, so back()/forward() no longer flash a blank frame
+  // between versions. `replaceDoc` degrades to an ordinary process() loop
+  // on a root that predates gh#1364 (feature-detected — FEEDBACK-81's lazy
+  // <a2ui-root> load means an older cached module is possible).
   #restoreVersion() {
     const messages = this.#history[this.#historyIndex];
     this.#whenRoot((root) => {
-      root.reset();
-      if (messages) {
-        for (const msg of messages) root.process(msg);
+      if (typeof root.replaceDoc === 'function') {
+        root.replaceDoc(messages || []);
+      } else {
+        root.reset();
+        if (messages) {
+          for (const msg of messages) root.process(msg);
+        }
       }
     });
   }

package/components/canvas/canvas.yaml

@@ -32,9 +32,13 @@ props:
 events:
   canvas-interaction:
     description: Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167.
-slots:
+parts:
   default:
-    description: Default slot — primary child content.
+    description: >-
+      Template-owned anatomy, not a light-DOM insertion point (gh#1454).
+      render() appends its own `<a2ui-root>` rendering surface; the runtime
+      owns all rendered content (a2ui rule below: "Do not place static
+      children inside"). No consumer content is captured or preserved.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/card/card.a2ui.json

@@ -33,9 +33,31 @@
       "default": 1
     },
     "padding": {
-      "description": "Interior padding scale (overrides --card-padding). Accepts the named scale (none/xs/sm/md/lg/xl) or a numeric rung (\"1\"…\"16\").",
+      "description": "Interior padding scale — overrides --card-inset (the header/section/footer inset token) for the whole card. Accepts the named scale (none/xs/sm/md/lg/xl — the parametric --a-padding-* tokens, same vocabulary as block-ui's [padding]) or a literal space rung (\"0\"/\"1\"…\"10\"/\"12\"/\"16\", mapped to --a-space-N). Empty (default) defers to the ambient --card-inset (context/[size]-driven) — unchanged behavior for the many existing cards that never set this attribute.",
       "type": "string",
-      "default": "md"
+      "enum": [
+        "",
+        "none",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+        "0",
+        "1",
+        "2",
+        "3",
+        "4",
+        "5",
+        "6",
+        "7",
+        "8",
+        "9",
+        "10",
+        "12",
+        "16"
+      ],
+      "default": ""
     },
     "raw": {
       "description": "Strips background, border, and shadow. Parent owns the surface. Content structure still applies.",
@@ -103,6 +125,7 @@
       "responsive"
     ],
     "name": "UICard",
+    "parts": {},
     "related": [
       "avatar",
       "input",

package/components/card/card.class.js

@@ -31,6 +31,8 @@
  * Attributes:
  *   variant   — "default" | "outlined" | "filled" | "ghost"
  *   size      — "sm" | "md" | "lg" (controls padding + font scale)
+ *   padding   — "" | none|xs|sm|md|lg|xl | "0"…"10"|"12"|"16" (overrides
+ *               --card-inset; empty = ambient/[size]-driven, unchanged)
  *   elevation — 0-3 (shadow depth)
  *   raw       — strips all chrome (border, bg, shadow, padding)
  *   draggable — enables drag handle + cursor:grab; wires the draggable trait
@@ -43,6 +45,7 @@ export class UICard extends UIElement {
   static properties = {
     variant:   { type: String,  default: 'default', reflect: true },
     size:      { type: String,  default: '',         reflect: true },
+    padding:   { type: String,  default: '',         reflect: true },
     elevation: { type: Number,  default: 1,          reflect: true },
     raw:       { type: Boolean, default: false,       reflect: true },
     draggable: { type: Boolean, default: false,       reflect: true },

package/components/card/card.css

@@ -120,6 +120,36 @@
   :scope[elevation="2"] { --card-shadow: var(--card-shadow-2); }
   :scope[elevation="3"] { --card-shadow: var(--card-shadow-3); }
 
+  /* ═══════ Padding — token override (gh#1416) ═══════
+     Overrides --card-inset (the header/section/footer inset token) for
+     the whole card. Named scale mirrors block-ui's own [padding] contract
+     + the global [padding] attribute API (api/sizing.css) — same
+     --a-padding-{xs..xl} tokens, so <card-ui padding="md"> == [padding="md"].
+     Literal rungs are the same k-independent --a-space-N set as the
+     universal [gap]/[padding] attribute (api/sizing.css). Unset (empty)
+     keeps the ambient --card-inset (context/[size]-driven) — this section
+     only fires when an author writes the attribute explicitly, so the many
+     existing cards that never set [padding] are unaffected. */
+  :scope[padding="none"] { --card-inset: 0; }
+  :scope[padding="xs"]   { --card-inset: var(--a-padding-xs); }
+  :scope[padding="sm"]   { --card-inset: var(--a-padding-sm); }
+  :scope[padding="md"]   { --card-inset: var(--a-padding-md); }
+  :scope[padding="lg"]   { --card-inset: var(--a-padding-lg); }
+  :scope[padding="xl"]   { --card-inset: var(--a-padding-xl); }
+  :scope[padding="0"]    { --card-inset: 0; }
+  :scope[padding="1"]    { --card-inset: var(--a-space-1); }
+  :scope[padding="2"]    { --card-inset: var(--a-space-2); }
+  :scope[padding="3"]    { --card-inset: var(--a-space-3); }
+  :scope[padding="4"]    { --card-inset: var(--a-space-4); }
+  :scope[padding="5"]    { --card-inset: var(--a-space-5); }
+  :scope[padding="6"]    { --card-inset: var(--a-space-6); }
+  :scope[padding="7"]    { --card-inset: var(--a-space-7); }
+  :scope[padding="8"]    { --card-inset: var(--a-space-8); }
+  :scope[padding="9"]    { --card-inset: var(--a-space-9); }
+  :scope[padding="10"]   { --card-inset: var(--a-space-10); }
+  :scope[padding="12"]   { --card-inset: var(--a-space-12); }
+  :scope[padding="16"]   { --card-inset: var(--a-space-16); }
+
   /* ═══════ Loading ═══════ */
 
   :scope[loading] {
@@ -194,7 +224,7 @@
     align-items: center;
   }
 
-  & > header[padding] {
+  & > header[padded] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);

package/components/card/card.d.ts

@@ -17,8 +17,8 @@ export class UICard extends UIElement {
   draggable: boolean;
   /** Shadow depth 0-3 */
   elevation: 0 | 1 | 2 | 3;
-  /** Interior padding scale (overrides --card-padding). Accepts the named scale (none/xs/sm/md/lg/xl) or a numeric rung ("1"…"16"). */
-  padding: string;
+  /** Interior padding scale — overrides --card-inset (the header/section/footer inset token) for the whole card. Accepts the named scale (none/xs/sm/md/lg/xl — the parametric --a-padding-* tokens, same vocabulary as block-ui's [padding]) or a literal space rung ("0"/"1"…"10"/"12"/"16", mapped to --a-space-N). Empty (default) defers to the ambient --card-inset (context/[size]-driven) — unchanged behavior for the many existing cards that never set this attribute. */
+  padding: '' | 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '12' | '16';
   /** Strips background, border, and shadow. Parent owns the surface. Content structure still applies. */
   raw: boolean;
   /** Card scale. Controls inset, radius, gap, and font sizes. Default (empty) = md. */