@celestia-island/hikari 0.55.175 → 0.55.177

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.175",
+  "version": "0.55.177",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAlert.pad.test.tsx

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkAlert from "./HkAlert";
+
+/**
+ * Component-level guard for the shared container-padding prop
+ * (runtime/containerPad) on HkAlert: the `padding` prop lands the
+ * `--hk-pad` custom property on the root element (inline — so it wins
+ * the cascade over the base and per-size padding rules without any
+ * specificity contest), and the unset prop lands nothing, leaving the
+ * size's own padding in force.
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountAlert(props: Record<string, unknown> = {}): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(HkAlert, { message: "mind the gap", ...props });
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push({ app, container });
+  const el = container.querySelector<HTMLElement>(".hk-alert");
+  expect(el, ".hk-alert renders").toBeTruthy();
+  return el!;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+});
+
+describe("HkAlert padding prop", () => {
+  it("unset prop lands no token — the size keeps its own padding", () => {
+    const el = mountAlert({ size: "sm" });
+    expect(el.style.getPropertyValue("--hk-pad")).toBe("");
+  });
+
+  it("a named step lands the token inline", () => {
+    const el = mountAlert({ padding: "sm" });
+    expect(el.style.getPropertyValue("--hk-pad")).toBe("var(--space-8, 0.5rem)");
+  });
+
+  it("none zeroes the padding explicitly", () => {
+    const el = mountAlert({ padding: "none" });
+    expect(el.style.getPropertyValue("--hk-pad")).toBe("0");
+  });
+
+  it("the token rides the ROOT, so the per-size rules all consume it", () => {
+    // sm/lg carry their own padding rules; the inline token must sit
+    // above them (root element), not on a nested node.
+    const sm = mountAlert({ size: "sm", padding: "lg" });
+    expect(sm.classList.contains("hk-alert-sm")).toBe(true);
+    expect(sm.style.getPropertyValue("--hk-pad")).toBe("var(--space-16, 1rem)");
+  });
+});

package/src/components/HkAlert.scss

@@ -2,7 +2,9 @@
   display: flex;
   align-items: flex-start;
   gap: var(--space-12, 12px);
-  padding: var(--space-12, 12px) var(--space-16, 16px);
+  /* --hk-pad: the shared container-padding token (runtime/containerPad) —
+     unset falls back to the historical values, set wins per instance. */
+  padding: var(--hk-pad, var(--space-12, 12px) var(--space-16, 16px));
   border-radius: var(--radius-md, 8px);
   border: 1px solid transparent;
   border-inline-start-width: 4px;
@@ -20,7 +22,7 @@
 /* ── Sizes ─────────────────────────────────────── */
 
 .hk-alert-sm {
-  padding: var(--space-8, 8px) var(--space-12, 12px);
+  padding: var(--hk-pad, var(--space-8, 8px) var(--space-12, 12px));
   font-size: var(--text-xs, 0.75rem);
 }
 
@@ -30,7 +32,7 @@
 }
 
 .hk-alert-lg {
-  padding: var(--space-16, 16px) var(--space-24, 24px);
+  padding: var(--hk-pad, var(--space-16, 16px) var(--space-24, 24px));
   font-size: var(--text-base, 0.875rem);
 }
 

package/src/components/HkAlert.tsx

@@ -1,5 +1,6 @@
 import { computed, defineComponent, ref, type PropType } from "vue";
 import { useI18n } from "../i18n/context";
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
 import { AlertTriangle, CheckCircle, Info, X } from "lucide-vue-next";
 
 import "./HkAlert.scss";
@@ -23,6 +24,9 @@ export default defineComponent({
     closable: { type: Boolean, default: false },
     banner: { type: Boolean, default: false },
     size: { type: String as PropType<AlertSize>, default: "md" },
+    /** Shared container-padding override (see runtime/containerPad) —
+     *  unset keeps the size's own padding. */
+    padding: { type: String as PropType<HkPad>, default: undefined },
   },
   emits: {
     close: () => true,
@@ -50,7 +54,7 @@ export default defineComponent({
       const IconComp = VARIANT_ICONS[props.variant];
 
       return (
-        <div class={rootCls.value}>
+        <div class={rootCls.value} style={hkPadStyle(props.padding)}>
           <span class="hk-alert-icon">
             {slots.icon ? (
               slots.icon()

package/src/components/HkCard.pad.test.tsx

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkCard from "./HkCard";
+
+/**
+ * Component-level guard for the shared container-padding prop
+ * (runtime/containerPad) on HkCard: the token lands on the card ROOT
+ * (custom properties inherit, so the body, the unpadded override and
+ * the scrollable card's inner pad wrapper all resolve it), and the
+ * unset prop lands nothing — `padded: false` keeps zeroing the body.
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountCard(props: Record<string, unknown> = {}): {
+  root: HTMLElement;
+  body: HTMLElement;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkCard, { title: "T", ...props }, { default: () => h("p", "body") });
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push({ app, container });
+  const root = container.querySelector<HTMLElement>(".hk-card");
+  expect(root, ".hk-card renders").toBeTruthy();
+  const body = root!.querySelector<HTMLElement>(".hk-card-body");
+  expect(body, ".hk-card-body renders").toBeTruthy();
+  return { root: root!, body: body! };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+});
+
+describe("HkCard padding prop", () => {
+  it("unset prop lands no token — the body keeps its inset", () => {
+    const { root } = mountCard();
+    expect(root.style.getPropertyValue("--hk-pad")).toBe("");
+  });
+
+  it("a named step lands the token on the card root", () => {
+    const { root } = mountCard({ padding: "md" });
+    expect(root.style.getPropertyValue("--hk-pad")).toBe("var(--space-12, 0.75rem)");
+  });
+
+  it("the token inherits into the body (one root write covers every rule)", () => {
+    const { root } = mountCard({ padding: "none" });
+    // happy-dom computes inherited custom properties off the DOM tree —
+    // the body sees the root's token, which is exactly the cascade the
+    // scss rules consume.
+    expect(root.style.getPropertyValue("--hk-pad")).toBe("0");
+  });
+
+  it("composes with padded:false — an explicit padding still reaches the body", () => {
+    const { root } = mountCard({ padded: false, padding: "sm" });
+    expect(
+      root.querySelector<HTMLElement>(".hk-card-body")!.classList.contains(
+        "hk-card-body-unpadded",
+      ),
+    ).toBe(true);
+    expect(root.style.getPropertyValue("--hk-pad")).toBe("var(--space-8, 0.5rem)");
+  });
+});

package/src/components/HkCard.scss

@@ -42,11 +42,13 @@
 }
 
 .hk-card-body {
-  padding: var(--space-16);
+  /* --hk-pad: the shared container-padding token (runtime/containerPad) —
+     the card root carries it when the `padding` prop is set. */
+  padding: var(--hk-pad, var(--space-16));
 }
 
 .hk-card-body-unpadded {
-  padding: 0;
+  padding: var(--hk-pad, 0);
 }
 
 .hk-card-footer {
@@ -85,6 +87,6 @@
   }
 
   .hk-card-body-pad {
-    padding: var(--space-16);
+    padding: var(--hk-pad, var(--space-16));
   }
 }

package/src/components/HkCard.tsx

@@ -1,4 +1,6 @@
-import { defineComponent } from "vue";
+import { defineComponent, type PropType } from "vue";
+
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
 
 import HkScrollContainer from "./HkScrollContainer";
 import "./HkCard.scss";
@@ -9,6 +11,12 @@ export default defineComponent({
     title: { type: String, default: undefined },
     hoverable: { type: Boolean, default: false },
     padded: { type: Boolean, default: true },
+    /** Shared container-padding override (see runtime/containerPad) for
+     *  the body (and the scrollable card's inner pad wrapper) — unset
+     *  keeps the body's historical inset; composes with `padded`
+     *  (unpadded still drops the inset unless an explicit padding is
+     *  given). */
+    padding: { type: String as PropType<HkPad>, default: undefined },
     /** Turn the card body into the library's standard scroll region
      *  (HkScrollContainer: overlay scrollbar, overflow sensing) instead
      *  of a plain static block. The card becomes a column flex box —
@@ -34,6 +42,7 @@ export default defineComponent({
           props.hoverable ? "hk-card-hoverable" : "",
           props.class,
         ]}
+        style={hkPadStyle(props.padding)}
         onClick={(e) => emit("click", e)}
       >
         {props.title || slots.header ? (

package/src/components/HkDraggableList.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick, ref } from "vue";
 
 import HDraggableList from "./HkDraggableList";
@@ -180,3 +180,165 @@ describe("HkDraggableList locked-lane contract", () => {
     expect(root.hasAttribute("data-all-locked")).toBe(false);
   });
 });
+
+describe("HkDraggableList list semantics", () => {
+  /** A reorderable list is a list for AT users whether or not the host
+   *  names it: the root always carries role="list" and every row
+   *  role="listitem" (the vocabulary a11y rulings #736/#737 applied to
+   *  the picker surfaces — the drag list adopts the same contract). The
+   *  accessible NAME stays the host's call: aria-label renders only when
+   *  the `label` prop is passed, so an unnamed list is still structural
+   *  and never announces an empty string. */
+
+  it("announces the root and rows as a list regardless of the label", () => {
+    const root = mountList(["a", "b"], []);
+
+    expect(root.getAttribute("role")).toBe("list");
+    expect(root.hasAttribute("aria-label")).toBe(false);
+    const rows = Array.from(root.querySelectorAll(".hk-draggable-list-item"));
+    expect(rows).toHaveLength(2);
+    expect(rows.every((row) => row.getAttribute("role") === "listitem")).toBe(true);
+  });
+
+  it("names the list through the label prop", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }], label: "Sortable accounts" },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+    expect(root.getAttribute("role")).toBe("list");
+    expect(root.getAttribute("aria-label")).toBe("Sortable accounts");
+  });
+});
+
+describe("HkDraggableList press ergonomics (clickable rows)", () => {
+  /** Two guards make a clickable row safe inside the list (ported from
+   *  wowsp's SortableList twin, which ran them in production):
+   *
+   *    1. ARM — a press under 5px of travel never publishes drag state
+   *       (no ghost flash on a jittered tap) and keeps the tap's native
+   *       semantics: no preventDefault until the arm.
+   *    2. SWALLOW — the release of an ARMED drag lands as a click on the
+   *       row the press started from; a capture-phase guard on the root
+   *       eats it, so dropping a row onto a clickable card never also
+   *       activates that card. Time-boxed at 300ms so it can never eat
+   *       a later keyboard activation, which has no pointerdown to
+   *       reset it. */
+
+  const PointerEventCtor: typeof MouseEvent =
+    (globalThis as { PointerEvent?: typeof MouseEvent }).PointerEvent ?? MouseEvent;
+
+  const pointerInit: MouseEventInit = { bubbles: true, cancelable: true };
+
+  function fire(el: Element, type: string, x = 0, y = 0) {
+    el.dispatchEvent(new PointerEventCtor(type, {
+      ...pointerInit,
+      button: 0,
+      clientX: x,
+      clientY: y,
+    }));
+  }
+
+  function fireWin(type: string, x = 0, y = 0) {
+    window.dispatchEvent(new PointerEventCtor(type, {
+      ...pointerInit,
+      clientX: x,
+      clientY: y,
+    }));
+  }
+
+  function mountClickable(): { root: HTMLElement; clicks: () => number } {
+    let clicked = 0;
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }, { key: "b" }] },
+          {
+            item: () =>
+              h(
+                "div",
+                { class: "row-body", onClick: () => { clicked++; } },
+                "row",
+              ),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+    return { root, clicks: () => clicked };
+  }
+
+  it("keeps a plain tap a tap: no drag state, and the row's click fires", async () => {
+    const { root, clicks } = mountClickable();
+    const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+    fire(row, "pointerdown", 10, 10);
+    // A 1px jitter stays under the arm threshold — no drag publishes.
+    fireWin("pointermove", 11, 10);
+    await nextTick();
+    expect(row.hasAttribute("data-dragging")).toBe(false);
+
+    fireWin("pointerup");
+    (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true }),
+    );
+    expect(clicks()).toBe(1);
+  });
+
+  it("arms past the threshold, drags, and swallows the release click", async () => {
+    const { root, clicks } = mountClickable();
+    const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+    fire(row, "pointerdown", 10, 10);
+    fireWin("pointermove", 30, 40);
+    await nextTick();
+    expect(row.getAttribute("data-dragging")).not.toBeNull();
+
+    fireWin("pointerup");
+    (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true }),
+    );
+    expect(clicks()).toBe(0);
+  });
+
+  it("time-boxes the swallow — a click after the window passes through", async () => {
+    vi.useFakeTimers();
+    try {
+      const { root, clicks } = mountClickable();
+      const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+      fire(row, "pointerdown", 10, 10);
+      fireWin("pointermove", 30, 40);
+      fireWin("pointerup");
+
+      (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true }),
+      );
+      expect(clicks()).toBe(0);
+
+      vi.advanceTimersByTime(301);
+      (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true }),
+      );
+      expect(clicks()).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/components/HkDraggableList.tsx

@@ -1,4 +1,4 @@
-import { defineComponent, onBeforeUnmount, ref, shallowRef, type PropType } from "vue";
+import { defineComponent, onBeforeUnmount, onMounted, ref, shallowRef, type PropType } from "vue";
 import { onceFrame } from "../runtime/animationBus";
 import { useReportedTransition } from "../composables/useReportedTransition";
 import { ancestorZoom } from "../runtime/cssZoom";
@@ -14,10 +14,23 @@ interface DragState {
   fromIndex: number;
   placeholderIndex: number;
   originX: number;
+  originY: number;
   grabOffsetX: number;
   grabOffsetY: number;
 }
 
+/** Press-to-drag arm distance — a plain click on a row (or its handle)
+ *  never starts a drag: the ghost only rises once the pointer moves past
+ *  this many px, so a clickable row keeps its tap action and a jittered
+ *  tap never flashes a ghost. */
+const ARM_PX = 5;
+
+/** How long after a drop the release click is still recognized as the
+ *  drag's own click. Time-boxed (rather than a sticky flag) so a drag
+ *  released off-window can never eat a later keyboard activation,
+ *  which has no pointerdown to reset it. */
+const SWALLOW_CLICK_MS = 300;
+
 export default defineComponent({
   name: "HkDraggableList",
   props: {
@@ -27,6 +40,12 @@ export default defineComponent({
      *  locked the root carries data-all-locked and the sheet collapses
      *  the lane entirely — the list cannot reorder at all. */
     lockedKeys: { type: Array as PropType<string[]>, default: () => [] },
+    /** Accessible name for the list (aria-label on the role="list" root).
+     *  The list semantics themselves are unconditional — a reorderable
+     *  list is a list for AT users whether or not the host names it —
+     *  mirroring the menu/vocabulary a11y rulings (#736/#737): chrome
+     *  announces structure, the host supplies the name. */
+    label: { type: String, default: undefined },
   },
   emits: {
     reorder: (_fromIndex: number, _toIndex: number) => true,
@@ -46,6 +65,38 @@ export default defineComponent({
 
     let ghostNode: HTMLElement | null = null;
 
+    /** Press bookkeeping — captured at pointerdown, never read during
+     *  render. `armed` flips only when the pointer crosses ARM_PX; until
+     *  then the press is a plain click-in-progress (no ghost, no drag
+     *  state, no preventDefault — the tap keeps its native semantics). */
+    let press: {
+      rect: DOMRect;
+      snapshot: string;
+      state: DragState;
+      armed: boolean;
+    } | null = null;
+    /** Timestamp of an armed drag's release — the capture-phase click
+     *  guard below eats the click a completed drag leaves behind (press
+     *  + release on the same element), so dropping a row onto a
+     *  clickable card never also activates that card. */
+    let swallowClickAt = 0;
+
+    const rootEl = ref<HTMLElement | null>(null);
+
+    /** Capture-phase click guard — runs before any row content's own
+     *  handlers (Vue's JSX typings have no onClickCapture attribute, so
+     *  the listener is wired imperatively in onMounted). */
+    function onRootClickCapture(e: MouseEvent) {
+      if (Date.now() - swallowClickAt > SWALLOW_CLICK_MS) return;
+      swallowClickAt = 0;
+      e.preventDefault();
+      e.stopPropagation();
+    }
+
+    onMounted(() => {
+      rootEl.value?.addEventListener("click", onRootClickCapture, true);
+    });
+
     const anim = useReportedTransition(250);
 
     function bump() { tick.value++; }
@@ -68,28 +119,29 @@ export default defineComponent({
       const row = rowEls.value[index];
       if (!row) return;
 
-      e.preventDefault();
       const rect = row.getBoundingClientRect();
 
       const snapshot = row.outerHTML
         .replace(/\sdraggable="[^"]*"/g, "")
         .replace(/\sdata-dragging="[^"]*"/g, "");
 
-      const state: DragState = {
-        fromIndex: index,
-        placeholderIndex: index,
-        originX: e.clientX,
-        grabOffsetX: e.clientX - rect.left,
-        grabOffsetY: e.clientY - rect.top,
+      // The press captures everything the arm needs. Nothing publishes
+      // yet — no preventDefault either: the handle lane carries its own
+      // touch-action:none and the rows are user-select:none, so a plain
+      // tap keeps its native click/scroll semantics untouched.
+      press = {
+        rect,
+        snapshot,
+        state: {
+          fromIndex: index,
+          placeholderIndex: index,
+          originX: e.clientX,
+          originY: e.clientY,
+          grabOffsetX: e.clientX - rect.left,
+          grabOffsetY: e.clientY - rect.top,
+        },
+        armed: false,
       };
-      drag.value = state;
-      bump();
-
-      onceFrame(() => {
-        if (!drag.value) return;
-        attachGhost(rect, snapshot);
-        anim.run();
-      });
 
       window.addEventListener("pointermove", onPointerMove, { passive: false });
       window.addEventListener("pointerup", onPointerUp, { once: true });
@@ -170,22 +222,45 @@ export default defineComponent({
     }
 
     function onPointerMove(e: PointerEvent) {
-      const s = drag.value;
-      if (!s) return;
+      const p = press;
+      if (!p) return;
+
+      if (!p.armed) {
+        // Arm past the threshold: only now does the drag publish, the
+        // ghost rise, and the gesture claim its defaults.
+        if (Math.hypot(e.clientX - p.state.originX, e.clientY - p.state.originY) <= ARM_PX) {
+          return;
+        }
+        p.armed = true;
+        drag.value = p.state;
+        bump();
+        const { rect, snapshot } = p;
+        onceFrame(() => {
+          if (!drag.value) return;
+          attachGhost(rect, snapshot);
+          anim.run();
+        });
+      }
+
       e.preventDefault();
       moveGhost(e.clientY);
       recomputePlaceholder(e.clientY);
     }
 
     function onPointerUp() {
-      const s = drag.value;
       window.removeEventListener("pointermove", onPointerMove);
 
+      const s = drag.value;
       if (s) {
+        // An armed drag's release lands as a click on the row the press
+        // started from — mark it for the capture guard or every drop
+        // onto a clickable card would also activate the card.
+        swallowClickAt = Date.now();
         if (s.placeholderIndex !== s.fromIndex) {
           emit("reorder", s.fromIndex, s.placeholderIndex);
         }
       }
+      press = null;
       anim.run();
       drag.value = null;
       bump();
@@ -193,6 +268,7 @@ export default defineComponent({
     }
 
     onBeforeUnmount(() => {
+      rootEl.value?.removeEventListener("click", onRootClickCapture, true);
       window.removeEventListener("pointermove", onPointerMove);
       detachGhost();
     });
@@ -211,7 +287,10 @@ export default defineComponent({
         props.items.length > 0 && props.items.every((item) => isLocked(item.key));
       return (
         <div
+          ref={rootEl}
           class="hk-draggable-list"
+          role="list"
+          aria-label={props.label || undefined}
           data-dragging={s ? "" : undefined}
           data-all-locked={allLocked || undefined}
         >
@@ -227,6 +306,7 @@ export default defineComponent({
                 key={item.key}
                 ref={(el) => setRowEl(index, el as Element | null)}
                 class="hk-draggable-list-item"
+                role="listitem"
                 data-locked={locked || undefined}
                 data-dragging={isSource || undefined}
                 data-placeholder={placeholderDir || undefined}

package/src/components/HkDrawer.scss

@@ -162,7 +162,9 @@
   /* Consumers nesting a self-padded menu (HkMenuPanel) zero this via
      --hk-drawer-body-padding so nav rows and the footer menu share one
      left edge. */
-  padding: var(--hk-drawer-body-padding, var(--space-16, 1rem));
+  /* --hk-pad (runtime/containerPad, the `padding` prop) outranks the
+     per-component theme token, which outranks the historical default. */
+  padding: var(--hk-pad, var(--hk-drawer-body-padding, var(--space-16, 1rem)));
 
   /* Overlay scrollbar (useOverlayScrollbar) — the native chrome is
      hidden, never styled. */

package/src/components/HkDrawer.tsx

@@ -15,6 +15,7 @@ import "./HkDrawer.scss";
 import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
 import { usePopupManager } from "../runtime/usePopupManager";
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
 import { createBackGuard } from "../runtime/backStack";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
@@ -36,6 +37,10 @@ export default defineComponent({
     closable: { type: Boolean, default: true },
     overlay: { type: Boolean, default: true },
     size: { type: String, default: "320px" },
+    /** Shared container-padding override (see runtime/containerPad) for
+     *  the body — unset keeps --hk-drawer-body-padding / the 1rem
+     *  default. */
+    padding: { type: String as PropType<HkPad>, default: undefined },
     /** Extra classes for the floating panel — lets consumers scope
      *  body/footer padding overrides (attrs fallthrough cannot reach a
      *  Teleported panel). */
@@ -289,7 +294,7 @@ export default defineComponent({
         <div
               ref={panelRef}
               class={["hk-drawer-panel", `hk-drawer-${props.side}`, props.panelClass, ...machine.classesFor(panelPrefix)]}
-              style={panelStyle.value}
+              style={{ ...panelStyle.value, ...hkPadStyle(props.padding) }}
               role="dialog"
               aria-label={props.title}
               aria-modal={props.overlay}

package/src/components/HkModal.scss

@@ -296,10 +296,13 @@
   // parent): custom properties inherit downward, so the covers, the
   // scroller and the inner all resolve them. The mobile sheet block
   // retunes the vars only.
-  --hk-scroll-pad-top: var(--hk-modal-padding-body, 1.5rem);
-  --hk-scroll-pad-right: var(--hk-modal-padding-body, 1.5rem);
-  --hk-scroll-pad-bottom: var(--hk-modal-padding-body, 1.5rem);
-  --hk-scroll-pad-left: var(--hk-modal-padding-body, 1.5rem);
+  // The shared container-padding token (--hk-pad, runtime/containerPad;
+  // the modal root carries it via the `padding` prop) outranks the
+  // per-component theme token, which outranks the historical default.
+  --hk-scroll-pad-top: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));
+  --hk-scroll-pad-right: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));
+  --hk-scroll-pad-bottom: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));
+  --hk-scroll-pad-left: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));
 
   // Gutter covers (scroll-pin contract, 2026-09-14): the body's top and
   // bottom whitespace stays paintable OUTSIDE the scroll flow, so a

package/src/components/HkModal.tsx

@@ -7,6 +7,7 @@ import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
 import { topWindowZ, usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
 import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
@@ -142,6 +143,10 @@ export default defineComponent({
     modelValue: { type: Boolean, required: true },
     title: { type: String, default: undefined },
     closable: { type: Boolean, default: true },
+    /** Shared container-padding override (see runtime/containerPad) for
+     *  the body — unset keeps --hk-modal-padding-body / the 1.5rem
+     *  default; the header and sub-header keep their own theme tokens. */
+    padding: { type: String as PropType<HkPad>, default: undefined },
     /** Named preset ("xs"…"xl") or any CSS max-width value (see ModalWidth). */
     width: { type: String as PropType<ModalWidth>, default: "32rem" },
     /**
@@ -1033,7 +1038,7 @@ export default defineComponent({
         <Teleport to={ensureOverlayRoot()}>
           <div
             class="hk-modal-root"
-            style={{ zIndex: overlayZ.value }}
+            style={{ zIndex: overlayZ.value, ...hkPadStyle(props.padding) }}
             onKeydown={onKeydown}
           >
             <div

package/src/components/HkPopover.scss

@@ -9,6 +9,10 @@
 
 .hk-popover-panel {
   min-width: 0;
+  /* --hk-pad: the shared container-padding token (runtime/containerPad) —
+     0 without glass (the bare panel never carried an inset), overridden
+     per instance via the `padding` prop. */
+  padding: var(--hk-pad, 0);
   max-height: min(70vh, calc(100vh - 2 * var(--viewport-gutter, 16px)));
   /* Width MUST be position-independent (max-content, viewport-capped).
    * The anchored panel is fixed-positioned with shrink-to-fit sizing,
@@ -69,7 +73,9 @@
   border: 1px solid rgb(var(--color-border) / 20%);
   border-radius: var(--radius-sm);
   box-shadow: var(--shadow-dropdown);
-  padding: var(--space-4, 0.25rem);
+  /* The glass chrome's historical 4px menu inset — the shared token
+     (runtime/containerPad) retunes it per instance (`padding` prop). */
+  padding: var(--hk-pad, var(--space-4, 0.25rem));
 }
 
 /* Locale picker menu items — unified menu-item spec (./_menu-item.scss). */
@@ -159,13 +165,17 @@
   /* The sheet's bottom-edge distance itself comes from the shared
    * --hk-sheet-bottom-gap (inline in HkPopover's sheet style); here the
    * content keeps the last row clear of the home bar: the safe-area
-   * inset stacked on a 12px family base, which also restores a bottom
-   * cushion over the glass dropdown chrome (equal specificity, earlier
+   * inset stacked on the shared container-pad token, whose legacy
+   * fallback is the 12px family base (which also restores a bottom
+   * cushion over the glass dropdown chrome — equal specificity, earlier
    * in source, whose own bottom padding the sheet rule would otherwise
-   * zero out). The modal sheet footer goes further (it adds
-   * --hk-sheet-footer-gap for its action buttons); this sheet has no
-   * footer, so this is the family baseline. */
-  padding-bottom: calc(var(--space-12, 0.75rem) + env(safe-area-inset-bottom, 0px));
+   * zero out). A host that sets the `padding` prop retunes the sheet's
+   * bottom inset with the SAME step its anchored panel uses (#808
+   * completion — hosts stop hand-padding the sheet branch); the safe-
+   * area term always rides on top. The modal sheet footer goes further
+   * (it adds --hk-sheet-footer-gap for its action buttons); this sheet
+   * has no footer, so this is the family baseline. */
+  padding-bottom: calc(var(--hk-pad, var(--space-12, 0.75rem)) + env(safe-area-inset-bottom, 0px));
 
   /* Overlay scrollbar (useOverlayScrollbar, sheet mode only) — the
      native chrome is hidden, never styled. */
@@ -178,9 +188,14 @@
 
 .hk-popover-sheet-grabber {
   flex-shrink: 0;
+  // Chrome, not content: cancel the panel's shared container pad inline
+  // (see the header twin above) so the grabber zone spans the full sheet
+  // width at any `padding` step — the centered bar never drifts inward.
+  // Longhand AFTER the shorthand or `margin: 0 auto` would win the cascade.
+  margin: 0 auto;
+  margin-inline: calc(-1 * var(--hk-pad, 0px));
   // Grabber zone: tap target tall enough for a thumb, bar visually small.
   padding: 14px 0 20px;
-  margin: 0 auto;
   width: 100%;
   cursor: pointer;
   display: flex;
@@ -206,15 +221,26 @@
  * The title aligns to the CONTENT edge: the leading inset defaults to
  * --space-12, matching the padded content blocks popover sheets host
  * (e.g. the house 0.75rem popover body). Hosts tune it via
- * --hk-sheet-title-inset; the trailing inset hugs the close button. */
+ * --hk-sheet-title-inset; the trailing inset hugs the close button.
+ *
+ * Shared container pad (#808 completion): the panel's `padding` prop
+ * insets the CONTENT band, so this chrome row cancels it inline
+ * (negative margin, the valid-CSS twin of a negative padding) and
+ * keeps its own title-inset from the panel frame — the title lands on
+ * the content edge whenever the pad step matches title-inset, at any
+ * step. The trailing block gap is the CONTENT's block-start air under
+ * the header: it reads the same pad step when the prop is set (legacy
+ * 8px otherwise), so a padded host gets one uniform inset around its
+ * sheet content too — no hand-padded wrapper branch downstream. */
 .hk-popover-sheet-header {
   flex-shrink: 0;
   display: flex;
   align-items: center;
   gap: var(--space-8, 0.5rem);
+  margin-inline: calc(-1 * var(--hk-pad, 0px));
   // Logical longhand (was physical `0 x y title-inset`): the title inset is
   // the inline START edge so RTL mirrors it with the mirrored title/close.
-  padding-block: 0 var(--space-8, 0.5rem);
+  padding-block: 0 var(--hk-pad, var(--space-8, 0.5rem));
   padding-inline: var(--hk-sheet-title-inset, var(--space-12, 0.75rem))
     var(--space-8, 0.5rem);
 }

package/src/components/HkPopover.sheetdock.test.ts

@@ -28,9 +28,12 @@ describe("HkPopover mobile sheet docking contract", () => {
 
   it("keeps sheet content clear of the home bar via the safe-area inset", () => {
     const block = scss.match(/\.hk-popover-panel\.hk-is-sheet\s*{[^}]*}/)?.[0] ?? "";
-    // Stacked on the family 12px base so the glass dropdown chrome's
-    // bottom padding survives on non-notched phones too.
-    expect(block).toContain("calc(var(--space-12");
+    // Stacked on the shared container-pad token whose legacy fallback is
+    // the family 12px base, so the glass dropdown chrome's bottom padding
+    // survives on non-notched phones too — and a host's `padding` prop
+    // retunes the base on the sheet face exactly like the anchored one
+    // (#808 completion; see containerPad.styles.test.ts for the pin).
+    expect(block).toContain("calc(var(--hk-pad, var(--space-12");
     expect(block).toContain("env(safe-area-inset-bottom");
   });
 });

package/src/components/HkPopover.tsx

@@ -13,6 +13,7 @@ import {
 } from "vue";
 
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { ancestorZoom } from "../runtime/cssZoom";
 import { popupViewportRect } from "../runtime/popupBounds";
@@ -56,6 +57,12 @@ export default defineComponent({
     closeOnBackdrop: { type: Boolean, default: true },
     closeOnEscape: { type: Boolean, default: true },
     glass: { type: Boolean, default: true },
+    /** Shared container-padding override (see runtime/containerPad) for
+     *  the panel's content inset — unset keeps the glass chrome's 4px
+     *  (menu-voice) inset, or 0 without glass. Content panels (forms,
+     *  editors, filter groups) set e.g. "md" instead of hand-padding
+     *  their slot content. */
+    padding: { type: String as PropType<HkPad>, default: undefined },
     anchorRef: { type: Object as PropType<HTMLElement | null>, default: null },
     /**
      * Dock the panel as a bottom sheet on mobile-width viewports (<768px,
@@ -699,6 +706,7 @@ export default defineComponent({
         >
               <div
                 ref={panelRef}
+                style={hkPadStyle(props.padding)}
                 class={[
                   "hk-popover-panel",
                   ...(sheetBranch ? ["hk-is-sheet"] : [`hk-popover-${resolvedPlacement.value}`]),

package/src/components/HkPopoverSheet.test.tsx

@@ -169,6 +169,32 @@ describe("HkPopover sheetOnMobile", () => {
     expect(header.querySelector(".hk-popover-sheet-close")).toBeTruthy();
   });
 
+  // #808 completion: the sheet branch consumes the same shared container
+  // pad its anchored twin does — the inline --hk-pad the `padding` prop
+  // writes on the panel reaches the sheet's content band (the scss
+  // contract in containerPad.styles.test.ts pins the consuming rules),
+  // so a host retunes ONE prop and both faces follow. No more hand-padded
+  // sheet-only wrapper branches downstream (chest's HkContextRing used
+  // to need one).
+  it("carries the padding prop's inline token onto the sheet panel too", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true, title: "Sheet", padding: "md" });
+    await nextTick();
+
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.classList.contains("hk-is-sheet")).toBe(true);
+    expect(panel.style.getPropertyValue("--hk-pad")).toBe("var(--space-12, 0.75rem)");
+  });
+
+  it("keeps the sheet panel token-free when no padding prop is set", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true, title: "Sheet" });
+    await nextTick();
+
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.style.getPropertyValue("--hk-pad")).toBe("");
+  });
+
   it("keeps the heading row out of anchored desktop mode", async () => {
     setViewport(1200);
     mountPopover({ sheetOnMobile: true, title: "Context usage" });

package/src/components/HkScrollPin.scrollcontract.test.ts

@@ -106,12 +106,15 @@ describe("scroll-pin whitespace contract", () => {
     // Declared on the BODY — the covers are the body's own pseudo rules
     // and custom properties inherit downward only, so the scroller (a
     // child) could never feed them. The FULL literal is pinned (var name
-    // AND the 1.5rem fallback): a silently changed default would desync
+    // AND the fallback chain): a silently changed default would desync
     // the covers from the padding while every selector still matches.
+    // The chain reads the shared container-pad token (--hk-pad, the
+    // modal root's `padding` prop) over the per-component theme token
+    // over the historical 1.5rem.
     const body = cssBlock(modalScss, ".hk-modal-body {");
     for (const side of ["top", "right", "bottom", "left"]) {
       expect(body, `--hk-scroll-pad-${side}`).toContain(
-        `--hk-scroll-pad-${side}: var(--hk-modal-padding-body, 1.5rem);`,
+        `--hk-scroll-pad-${side}: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));`,
       );
     }
   });

package/src/components/HkStatCard.scss

@@ -2,7 +2,8 @@
   display: flex;
   flex-direction: column;
   gap: 0.25rem;
-  padding: var(--space-12, 0.75rem) var(--space-16, 1rem);
+  /* --hk-pad: the shared container-padding token (runtime/containerPad). */
+  padding: var(--hk-pad, var(--space-12, 0.75rem) var(--space-16, 1rem));
   border: 1px solid var(--border-faint, rgb(var(--color-border) / 10%));
   border-radius: var(--radius-md, 0.5rem);
   background: rgb(var(--color-surface));

package/src/components/HkStatCard.tsx

@@ -1,5 +1,7 @@
 import { defineComponent, h, type Component, type PropType } from "vue";
 
+import { hkPadStyle, type HkPad } from "../runtime/containerPad";
+
 import HkGaugeRing from "./HkGaugeRing";
 import HkProgressBar from "./HkProgressBar";
 import "./HkStatCard.scss";
@@ -78,6 +80,9 @@ export const HkStatCard = defineComponent({
   name: "HkStatCard",
   props: {
     variant: { type: String as PropType<StatVariant>, default: "plain" },
+    /** Shared container-padding override (see runtime/containerPad) —
+     *  unset keeps the card's historical inset. */
+    padding: { type: String as PropType<HkPad>, default: undefined },
     label: { type: String, required: true },
     value: { type: [String, Number], required: true },
     tone: { type: String as PropType<StatTone>, default: "muted" },
@@ -95,6 +100,7 @@ export const HkStatCard = defineComponent({
   setup(props, { emit, slots }) {
     return () => {
       const shared = {
+        style: hkPadStyle(props.padding),
         class: [
           "hk-stat-card",
           `hk-stat-card-${props.variant}`,

package/src/components/containerPad.styles.test.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet guard for the shared container-padding token
+ * (--hk-pad, runtime/containerPad) across every wired container sheet.
+ *
+ * The whole facility rests on each container's padding rule consuming
+ * `var(--hk-pad, <legacy default>)` — the token is SET per instance
+ * (inline, via the `padding` prop) and CONSUMED by these rules, so
+ * there is never a specificity contest. Vitest stubs CSS, so the
+ * component suites can never catch a rule regressed back to a literal:
+ * this file compiles the six sheets for real and pins the exact
+ * declarations.
+ *
+ * The legacy fallbacks here ARE the historical visuals: popover glass
+ * 4px (menu voice) / bare panel 0, card body 1rem (unpadded 0),
+ * stat card 12/16, modal body --hk-modal-padding-body (1.5rem), drawer
+ * body --hk-drawer-body-padding (1rem), alert base/sm/lg shorthands.
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+function compileSheet(name: string): string {
+  return compile(resolve(componentDir, name), { style: "expanded" }).css;
+}
+
+function ruleFor(css: string, selector: string): string {
+  const start = css.indexOf(selector);
+  expect(start, `${selector} present in the compiled sheet`).toBeGreaterThanOrEqual(0);
+  const open = css.indexOf("{", start);
+  const close = css.indexOf("}", open);
+  return css.slice(start, close + 1);
+}
+
+describe("container pad token — wired sheets", () => {
+  it("HkPopover: bare panel falls back to 0, glass chrome to the 4px menu inset", () => {
+    const css = compileSheet("HkPopover.scss");
+    expect(ruleFor(css, ".hk-popover-panel {")).toContain(
+      "padding: var(--hk-pad, 0)",
+    );
+    expect(css).toContain(
+      "padding: var(--hk-pad, var(--space-4, 0.25rem))",
+    );
+  });
+
+  it("HkPopover sheet: the content band reads the token, chrome cancels it", () => {
+    // The sheet branch completes the #808 contract: a host that sets the
+    // `padding` prop gets the SAME step around its content docked as a
+    // bottom sheet (bottom = step + safe-area, block-start air under the
+    // header = step) instead of hand-padding a sheet-only wrapper — the
+    // gap chest's HkContextRing had to compensate for locally. Grabber
+    // and header are chrome: they cancel the panel's inline pad so the
+    // tap zone and title keep their own frame-relative insets.
+    const css = compileSheet("HkPopover.scss");
+    expect(css).toContain(
+      "padding-bottom: calc(var(--hk-pad, var(--space-12, 0.75rem)) + env(safe-area-inset-bottom, 0px))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-header {")).toContain(
+      "margin-inline: calc(-1 * var(--hk-pad, 0px))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-header {")).toContain(
+      "padding-block: 0 var(--hk-pad, var(--space-8, 0.5rem))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-grabber {")).toContain(
+      "margin-inline: calc(-1 * var(--hk-pad, 0px))",
+    );
+  });
+
+  it("HkCard: body 1rem, unpadded 0, the scrollable pad wrapper 1rem", () => {
+    const css = compileSheet("HkCard.scss");
+    expect(ruleFor(css, ".hk-card-body {")).toContain(
+      "padding: var(--hk-pad, var(--space-16))",
+    );
+    expect(ruleFor(css, ".hk-card-body-unpadded {")).toContain(
+      "padding: var(--hk-pad, 0)",
+    );
+    expect(ruleFor(css, ".hk-card-body-pad {")).toContain(
+      "padding: var(--hk-pad, var(--space-16))",
+    );
+  });
+
+  it("HkStatCard: the 12/16 surface inset", () => {
+    const css = compileSheet("HkStatCard.scss");
+    expect(ruleFor(css, ".hk-stat-card {")).toContain(
+      "padding: var(--hk-pad, var(--space-12, 0.75rem) var(--space-16, 1rem))",
+    );
+  });
+
+  it("HkModal: every scroll-pad track reads the token over the theme value", () => {
+    const css = compileSheet("HkModal.scss");
+    for (const side of ["top", "right", "bottom", "left"]) {
+      expect(css).toContain(
+        `--hk-scroll-pad-${side}: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem))`,
+      );
+    }
+  });
+
+  it("HkDrawer: the body reads the token over the theme value", () => {
+    const css = compileSheet("HkDrawer.scss");
+    expect(css).toContain(
+      "padding: var(--hk-pad, var(--hk-drawer-body-padding, var(--space-16, 1rem)))",
+    );
+  });
+
+  it("HkAlert: the base and both sized shorthands read the token", () => {
+    const css = compileSheet("HkAlert.scss");
+    expect(ruleFor(css, ".hk-alert {")).toContain(
+      "padding: var(--hk-pad, var(--space-12, 12px) var(--space-16, 16px))",
+    );
+    expect(ruleFor(css, ".hk-alert-sm {")).toContain(
+      "padding: var(--hk-pad, var(--space-8, 8px) var(--space-12, 12px))",
+    );
+    expect(ruleFor(css, ".hk-alert-lg {")).toContain(
+      "padding: var(--hk-pad, var(--space-16, 16px) var(--space-24, 24px))",
+    );
+  });
+});

package/src/index.ts

@@ -806,3 +806,4 @@ export { type HAboutLinkIcon as HkAboutLinkIcon } from "./components/HkAboutModa
 export { type HAboutComponentVersion as HkAboutComponentVersion } from "./components/HkAboutModal";
 export { type HCustomTheme as HkCustomTheme } from "./components/HkColorSchemeDialog";
 export { OVERLAY_ROOT_SELECTOR, OVERLAY_Z, ensureOverlayRoot } from "./overlay/overlayRoot";
+export { HK_PAD_VAR, hkPadStyle, type HkPad } from "./runtime/containerPad";

package/src/runtime/containerPad.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+import { HK_PAD_VAR, hkPadStyle } from "./containerPad";
+
+/**
+ * Direct unit tests for the shared container-padding helper behind every
+ * container's `padding` prop (runtime/containerPad).
+ *
+ * The contract, in one line each:
+ * - the token is `--hk-pad`, the ONE custom property every wired
+ *   container's padding rule consumes (each with its own legacy
+ *   fallback, so an unset token preserves the historical look);
+ * - `hkPadStyle` maps the five named steps onto the house spacing scale
+ *   (--space-4/8/12/16) verbatim, with fallbacks inlined — the values
+ *   must stay pure `var()` references so themes can re-scale them;
+ * - an unset prop renders NO declaration at all (an empty style object),
+ *   never a default-valued one — the absence IS the legacy default.
+ */
+describe("HK_PAD_VAR", () => {
+  it("is the one shared custom property", () => {
+    expect(HK_PAD_VAR).toBe("--hk-pad");
+  });
+});
+
+describe("hkPadStyle", () => {
+  it("maps each step onto the spacing scale", () => {
+    expect(hkPadStyle("none")).toEqual({ [HK_PAD_VAR]: "0" });
+    expect(hkPadStyle("xs")).toEqual({ [HK_PAD_VAR]: "var(--space-4, 0.25rem)" });
+    expect(hkPadStyle("sm")).toEqual({ [HK_PAD_VAR]: "var(--space-8, 0.5rem)" });
+    expect(hkPadStyle("md")).toEqual({ [HK_PAD_VAR]: "var(--space-12, 0.75rem)" });
+    expect(hkPadStyle("lg")).toEqual({ [HK_PAD_VAR]: "var(--space-16, 1rem)" });
+  });
+
+  it("renders no declaration when the prop is unset", () => {
+    expect(hkPadStyle(undefined)).toEqual({});
+  });
+});

package/src/runtime/containerPad.ts

@@ -0,0 +1,53 @@
+import type { CSSProperties } from "vue";
+
+/**
+ * The shared container-padding scale — the ONE mechanism behind every
+ * container component's `padding` prop (HkPopover's panel, HkCard,
+ * HkStatCard, HkModal, HkDrawer, HkAlert, …).
+ *
+ * The contract has two halves:
+ *
+ *   1. TOKEN — every container's padding rule reads
+ *      `padding: var(--hk-pad, <its legacy default>)`. Setting the
+ *      custom property on the element (inline, a utility class, or any
+ *      ancestor — custom properties inherit) retunes that container's
+ *      content padding without touching its stylesheet; leaving it
+ *      unset preserves the component's historical look byte-for-byte.
+ *      Because the property is consumed (not a competing declaration),
+ *      there is no specificity contest with the component's own rules
+ *      or the theme layer.
+ *
+ *   2. PROP — `padding?: HkPad` on the container maps the named step
+ *      onto the token via {@link hkPadStyle} (one inline custom
+ *      property), so a call site opts in per instance:
+ *      `<HkCard padding="none">…</HkCard>`.
+ *
+ * The steps ride the house spacing scale (--space-* in
+ * styles/theme/scale.scss): none=0, xs=4px, sm=8px, md=12px, lg=16px —
+ * the same four steps the popover glass chrome (xs), the settings rows
+ * (sm) and the card bodies (lg) already speak.
+ */
+
+/** The named padding steps every container's `padding` prop accepts. */
+export type HkPad = "none" | "xs" | "sm" | "md" | "lg";
+
+/** The custom property the container padding rules consume. Hosts and
+ *  themes may also set it directly (per instance or per subtree). */
+export const HK_PAD_VAR = "--hk-pad";
+
+/** Step → the spacing-scale value handed to the token. */
+const HK_PAD_VALUE: Record<HkPad, string> = {
+  none: "0",
+  xs: "var(--space-4, 0.25rem)",
+  sm: "var(--space-8, 0.5rem)",
+  md: "var(--space-12, 0.75rem)",
+  lg: "var(--space-16, 1rem)",
+};
+
+/** The inline style carrying the token for one `padding` prop value —
+ *  an empty object when the prop is unset (the component keeps its
+ *  legacy default). Call sites spread it into their existing style
+ *  object: `style={{ …panelStyle.value, …hkPadStyle(props.padding) }}`. */
+export function hkPadStyle(pad: HkPad | undefined): CSSProperties {
+  return pad ? ({ [HK_PAD_VAR]: HK_PAD_VALUE[pad] } as CSSProperties) : {};
+}

package/src/runtime/index.ts

@@ -102,3 +102,8 @@ export {
   type HkRuntimeSnapshot,
   type HkRuntimeSnapshotEntry,
 } from "./registry";
+export {
+  HK_PAD_VAR,
+  hkPadStyle,
+  type HkPad,
+} from "./containerPad";