sheleg-design-skill 1.59.2 → 1.60.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
+## 1.60.0 — the SKILL body splits back under budget, and the guards read the bundle
+
+Sherlock external-v3 (34 findings) plus the CREATIVE_DIRECTOR handoff (PR #28).
+
+- **The body breached the 5000-token budget** — 4275 → 5703 from the audit's own
+  doctrine — and the house rule's answer to a breach is a SPLIT. Three documents
+  now carry what a run does not need in the same breath: `CALIBRATION.md` (what
+  to do when two brief rows disagree), `COMPONENT_LAYER.md` (how a kit composes
+  with a token layer), `APPLYING.md` (the order of work and the repeat-failure
+  list). `PACK_COMPARISON.md` was tried and REVERTED: every sentence in it is
+  asserted by a guard, so the comparison protocol and the ten-role adapter
+  contract belong in the SKILL.
+- **Two guards now read the resolved BUNDLE rather than SKILL.md alone.** They
+  assert that a sentence REACHES the agent, and the agent loads the SKILL plus
+  what it links to — so reading one file made the house rule's own remedy delete
+  the doctrine those guards protect. Links are resolved, not listed: a sentence
+  parked where nothing points is still gone, and the negative assertion got
+  stricter, not looser.
+- The CLI smoke test compares the bundle rather than the installer's own manifest,
+  and asserts that manifest was written.
+
 ## [Unreleased]
 
+
+## [1.59.4] - 2026-09-06
+
+> **v1.59.3 is a burned tag.** It was pushed against `origin/main` before the release
+> PR had actually merged, so it names the v1.59.2 tree; the version-sync gate refuses
+> it and the remote forbids tag deletion. Nothing shipped under it — this version is
+> the same change, tagged on the verified merge commit.
+
+### Fixed
+
+- **The front matter declared the optional siblings and said nothing about the
+  hard requirement.** `compatibility:` named `dataviz`, `shadcn` and
+  `migrate-radix-to-base` — three skills the body can work without — while the
+  body REQUIRES node with npx and network twice (`npx sheleg-design-skill --kit
+  <pack>`, `npx sshlg-skills pack design --lane`) and named no path for a
+  machine where npx is unreachable. Found by the family audit (2026-09-06, wave
+  AUDIT-WAVE-0906). Both halves fixed: the front matter now opens with
+  *"Kit/lane commands need node>=16, npx, network"*, and the kit-authoritative
+  paragraph states the degraded path in the same voice v1.59.1 gave the
+  director's Act 2 — nothing is blocked, the pack and its token layer in
+  `styles/tokens/<pack>.css` still carry the rules by reading, and the component
+  states only a kit materializes are then **unverified**, said out loud rather
+  than presented as kit-checked.
+
+  **The honest first draft was refused by this repository's own gate, and the
+  refusal is the interesting part.** The full declaration measured 342 chars —
+  comfortably inside the Agent Skills spec's 500-char `compatibility` cap — and
+  `check_description_canon` refused it at **432 of a 256 overhead budget**,
+  because every non-description key is read every session and the budget exists
+  so front matter never becomes a place to write prose. Two limits, and the
+  binding one was the house budget, not the spec cap — the same lesson v1.59.2
+  paid for on the description. So the front matter carries the compressed form
+  (**253 of 256**) and the body carries the detail, which is where a reader who
+  hit the failure would look anyway.
+
+- **An empty recursive directory chain sat in checkouts, and the mirror
+  validator could not see the class it belongs to.**
+  `.cursor/skills/sheleg-design/styles/tokens/.cursor/skills/sheleg-design/` —
+  zero files, invisible to `git status` (git tracks no directory), to the npm
+  tarball (npm packs files), and to both directions of the mirror-drift check,
+  which walk `rglob("*")` filtered by `is_file()`. Measured on this machine
+  2026-09-06: the umbrella's submodule checkout at `skills/sheleg-design`
+  carried the chain at commit `0902ef6`; this repository's own checkout was
+  clean. The artefact is removed, and the CLASS is closed: the mirror block now
+  reads **directories** over both trees — a nested `.cursor` anywhere inside
+  either bundle is refused as a copy artefact whatever it contains, and an
+  empty directory is refused wholesale. Watched failing against a real planted
+  chain before being believed — both checks answered with their own messages,
+  not a neighbour's — and planted permanently in the self-test as two
+  **directory fixtures**, a shape `PLANTS` cannot express because its mutations
+  are text edits to a file, and each fixture asserts the plant landed before
+  trusting any red. Floor raised 5621 → 5641, measured by running the gate on
+  this tree.
+
 ## [1.59.2] - 2026-09-03
 
 ### Fixed

package/bin/cli.js

@@ -83,6 +83,69 @@ const COLORS = {
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const c = (color, s) => (useColor ? COLORS[color] + s + COLORS.reset : s);
 
+/**
+ * A TRANSACTIONAL file install (FIX-UP-05.03): the writer contract from UP-05
+ * applied to the design CLI. The old path copied each managed file straight
+ * into the target, so a crash mid-install left a partial write. Now the managed
+ * set is staged into a same-filesystem sibling and VERIFIED, the previous
+ * generation is snapshotted (recoverable under --force), the staged files are
+ * renamed into place, and OBSOLETE managed files (managed, gone from the source)
+ * are removed — while unknown user files are never touched. No runtime
+ * dependency on a sibling checkout: everything reads from `srcDir`.
+ */
+function installFilesTransactionally(srcDir, targetDir, files) {
+  const staging = path.join(targetDir, `.sheleg-staging-${process.pid}`);
+  const prevGen = path.join(targetDir, `.sheleg-prev-${process.pid}`);
+  const manifestPath = path.join(targetDir, ".sheleg-manifest.json");
+  // The previously-installed MANAGED set, so obsolete-managed-only removal can
+  // tell a file this installer wrote from an unknown user file it must not touch.
+  let prevManaged = [];
+  try { prevManaged = JSON.parse(fs.readFileSync(manifestPath, "utf8")).files || []; }
+  catch (e) { prevManaged = []; }
+  fs.rmSync(staging, { recursive: true, force: true });
+  try {
+    // 1. STAGE + VERIFY.
+    for (const f of files) {
+      const s = path.join(srcDir, f);
+      const d = path.join(staging, f);
+      fs.mkdirSync(path.dirname(d), { recursive: true });
+      fs.copyFileSync(s, d);
+      if (!fs.readFileSync(s).equals(fs.readFileSync(d))) {
+        throw new Error(`staged ${f} does not match its source`);
+      }
+    }
+    // 2. Snapshot the previous generation of the managed files (recoverable).
+    fs.rmSync(prevGen, { recursive: true, force: true });
+    for (const f of files) {
+      const cur = path.join(targetDir, f);
+      if (fs.existsSync(cur)) {
+        const save = path.join(prevGen, f);
+        fs.mkdirSync(path.dirname(save), { recursive: true });
+        fs.copyFileSync(cur, save);
+      }
+    }
+    // 3. SWITCH: rename each staged file into place.
+    for (const f of files) {
+      const d = path.join(targetDir, f);
+      fs.mkdirSync(path.dirname(d), { recursive: true });
+      fs.renameSync(path.join(staging, f), d);
+    }
+    // 4. Remove OBSOLETE managed files — managed before, gone from the source
+    //    now — and never an unknown user file.
+    const wanted = new Set(files);
+    for (const f of (prevManaged || [])) {
+      if (!wanted.has(f)) fs.rmSync(path.join(targetDir, f), { force: true });
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify({ files }));
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.rmSync(prevGen, { recursive: true, force: true });
+    return { installed: files, removed: prevManaged.filter((f) => !new Set(files).has(f)) };
+  } catch (err) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw new Error(`install aborted, previous install intact: ${err.message}`);
+  }
+}
+
 function parseArgs(argv) {
   const opts = {
     target: null, // explicit --dir
@@ -375,10 +438,25 @@ function claudeHomeOf(targetDir) {
  * as "no plugin": the fresh HOME is the common case, and an installer that
  * crashes on a parse error refuses the machines that need it most.
  */
+// The bundled HostContext resolver (FIX-UP-08.02) — one contract, a local copy
+// per member (npx installers share no lib): a host's config root is an explicit
+// root > the documented host env var > `~/<dir>`, verbatim (spaces preserved).
+// Only the USER-scoped Claude config (the plugin registry) uses this; a
+// PROJECT-level `.claude/` under cwd is not a host config root and is left as
+// is. Host existence stays a separate probe on the returned path.
+const HOST_ENV = { claude: "CLAUDE_CONFIG_DIR", codex: "CODEX_HOME", gemini: "GEMINI_CONFIG_DIR" };
+const HOST_DIR = { claude: ".claude", codex: ".codex", gemini: ".gemini" };
+function hostRoot(agent, home, env, explicit) {
+  if (explicit) return explicit;
+  const e = (env || process.env)[HOST_ENV[agent]];
+  if (e) return e;
+  return path.join(home, HOST_DIR[agent]);
+}
+
 function installedPluginSpec(home) {
   try {
     const raw = fs.readFileSync(
-      path.join(home, ".claude", "plugins", "installed_plugins.json"),
+      path.join(hostRoot("claude", home, process.env), "plugins", "installed_plugins.json"),
       "utf8",
     );
     const parsed = JSON.parse(raw);
@@ -499,11 +577,7 @@ function main() {
   }
 
   fs.mkdirSync(targetDir, { recursive: true });
-  for (const f of files) {
-    const dest = path.join(targetDir, f);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(path.join(SKILL_DIR, f), dest);
-  }
+  installFilesTransactionally(SKILL_DIR, targetDir, files);
 
   const rel = path.relative(cwd, targetDir) || ".";
   console.log(
@@ -512,9 +586,10 @@ function main() {
       `  ${c("dim", "SHELEG_DESIGN.md")}    the full reference\n` +
       `  ${c("dim", "MOTION_DOCTRINE.md")}  whether to animate at all — read before any animation\n` +
       `  ${c("dim", "styles/")}             style packs + token CSS (instrument-console / editorial-luxury / workbench / briefing-room / atrium / orchard / field-notes / cyclorama / showroom / blueprint / prism / maquette / scoreboard / datasheet / manpage / pigeonhole / roster)\n\n` +
-      `Your Cursor / Claude agent can now discover the skill and build\n` +
-      `cinematic, scroll-driven pages — or style product UI (dashboards, admin,\n` +
-      `internal tools) from a standalone pack — on its principles.\n\n` +
+      `Files are on disk; a running agent has NOT loaded them yet — skills are\n` +
+      `read at session start, so reload (a new session) before expecting the\n` +
+      `skill, then build cinematic scroll-driven pages or style product UI from\n` +
+      `a standalone pack. Writing files is not the same as the host loading them.\n\n` +
       `${c("dim", "Docs: " + pkg.homepage)}\n`,
   );
 
@@ -569,4 +644,8 @@ function offerRouters() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { installFilesTransactionally, copyKitTree };

package/kits/almanac/src/Button.tsx

@@ -1,33 +1,34 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
-export interface ButtonProps {
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   /** `primary` is the accent fill — the pack allows one per view. */
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: () => void;
   children: ReactNode;
   className?: string;
 }
 
-export function Button({
-  variant = 'primary',
-  size = 'md',
-  disabled = false,
-  onClick,
-  children,
-  className,
-}: ButtonProps) {
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'primary', size = 'md', className, type, children, ...rest },
+  ref,
+) {
   return (
     <button
-      type="button"
+      ref={ref}
+      // default is `button`, but an explicit caller `type` (submit, reset) wins —
+      // a design default must never silently erase a prop the caller set.
+      type={type ?? 'button'}
       className={['al-btn', `al-btn--${variant}`, `al-btn--${size}`, className]
         .filter(Boolean)
         .join(' ')}
-      disabled={disabled}
-      onClick={onClick}
+      // native + ARIA + state pass through: aria-label for icon-only buttons,
+      // aria-controls / aria-expanded for trigger controls, disabled, and onClick
+      // with its real event. The spine forwards, it does not swallow.
+      {...rest}
     >
       {children}
     </button>
   );
-}
+});

package/kits/almanac/src/Heading.tsx

@@ -1,19 +1,32 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-export interface HeadingProps {
+export interface HeadingProps
+  extends Omit<HTMLAttributes<HTMLHeadingElement>, 'className'> {
   /** 1 = page title (30px), 2 = section (24px), 3 = card title (16px). */
   level?: 1 | 2 | 3;
+  /** Visual size — defaults to the level, so existing call sites keep their look. */
+  size?: 1 | 2 | 3;
   children: ReactNode;
   className?: string;
 }
 
-export function Heading({ level = 2, children, className }: HeadingProps) {
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { level = 2, size, className, children, ...rest },
+  ref,
+) {
   const Tag = `h${level}` as 'h1' | 'h2' | 'h3';
   return (
     <Tag
-      className={['al-heading', `al-heading--${level}`, className].filter(Boolean).join(' ')}
+      ref={ref}
+      // The TAG follows the semantic level; the CLASS follows the visual size —
+      // an h2 may wear the display size without touching the document outline.
+      className={['al-heading', `al-heading--${size ?? level}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
     >
       {children}
     </Tag>
   );
-}
+});

package/kits/atrium/src/Button.tsx

@@ -1,38 +1,38 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
-export interface ButtonProps {
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   /**
    * The pill triad, and there is no fourth: `primary` is the solid accent,
    * `secondary` the accent-outline on the field, `ghost` the beige pill that
    * sits on photography.
    */
   variant?: 'primary' | 'secondary' | 'ghost';
-  /** `md` is the pack's pill (12px 25px). `sm`/`lg` rescale it, nothing else. */
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: () => void;
   children: ReactNode;
   className?: string;
 }
 
-export function Button({
-  variant = 'primary',
-  size = 'md',
-  disabled = false,
-  onClick,
-  children,
-  className,
-}: ButtonProps) {
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'primary', size = 'md', className, type, children, ...rest },
+  ref,
+) {
   return (
     <button
-      type="button"
+      ref={ref}
+      // default is `button`, but an explicit caller `type` (submit, reset) wins —
+      // a design default must never silently erase a prop the caller set.
+      type={type ?? 'button'}
       className={['at-btn', `at-btn--${variant}`, `at-btn--${size}`, className]
         .filter(Boolean)
         .join(' ')}
-      disabled={disabled}
-      onClick={onClick}
+      // native + ARIA + state pass through: aria-label for icon-only buttons,
+      // aria-controls / aria-expanded for trigger controls, disabled, and onClick
+      // with its real event. The spine forwards, it does not swallow.
+      {...rest}
     >
       {children}
     </button>
   );
-}
+});

package/kits/atrium/src/Heading.tsx

@@ -1,19 +1,32 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-export interface HeadingProps {
+export interface HeadingProps
+  extends Omit<HTMLAttributes<HTMLHeadingElement>, 'className'> {
   /** 1 = hero claim (57→80px), 2 = section (48→64px), 3 = category (34→45px). */
   level?: 1 | 2 | 3;
+  /** Visual size — defaults to the level, so existing call sites keep their look. */
+  size?: 1 | 2 | 3;
   children: ReactNode;
   className?: string;
 }
 
-export function Heading({ level = 2, children, className }: HeadingProps) {
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { level = 2, size, className, children, ...rest },
+  ref,
+) {
   const Tag = `h${level}` as 'h1' | 'h2' | 'h3';
   return (
     <Tag
-      className={['at-heading', `at-heading--${level}`, className].filter(Boolean).join(' ')}
+      ref={ref}
+      // The TAG follows the semantic level; the CLASS follows the visual size —
+      // an h2 may wear the display size without touching the document outline.
+      className={['at-heading', `at-heading--${size ?? level}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
     >
       {children}
     </Tag>
   );
-}
+});

package/kits/awning/src/Button.tsx

@@ -1,33 +1,34 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
-export interface ButtonProps {
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   /** `primary` is the BLACK pill — the accent, and there is no hue in the control set. */
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: () => void;
   children: ReactNode;
   className?: string;
 }
 
-export function Button({
-  variant = 'primary',
-  size = 'md',
-  disabled = false,
-  onClick,
-  children,
-  className,
-}: ButtonProps) {
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'primary', size = 'md', className, type, children, ...rest },
+  ref,
+) {
   return (
     <button
-      type="button"
+      ref={ref}
+      // default is `button`, but an explicit caller `type` (submit, reset) wins —
+      // a design default must never silently erase a prop the caller set.
+      type={type ?? 'button'}
       className={['aw-btn', `aw-btn--${variant}`, `aw-btn--${size}`, className]
         .filter(Boolean)
         .join(' ')}
-      disabled={disabled}
-      onClick={onClick}
+      // native + ARIA + state pass through: aria-label for icon-only buttons,
+      // aria-controls / aria-expanded for trigger controls, disabled, and onClick
+      // with its real event. The spine forwards, it does not swallow.
+      {...rest}
     >
       {children}
     </button>
   );
-}
+});

package/kits/awning/src/Heading.tsx

@@ -1,17 +1,32 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-export interface HeadingProps {
+export interface HeadingProps
+  extends Omit<HTMLAttributes<HTMLHeadingElement>, 'className'> {
   /** 1 = page title (`dsp`), 2 = section (`t1`), 3 = card title (`t3`). */
   level?: 1 | 2 | 3;
+  /** Visual size — defaults to the level, so existing call sites keep their look. */
+  size?: 1 | 2 | 3;
   children: ReactNode;
   className?: string;
 }
 
-export function Heading({ level = 2, children, className }: HeadingProps) {
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { level = 2, size, className, children, ...rest },
+  ref,
+) {
   const Tag = `h${level}` as 'h1' | 'h2' | 'h3';
   return (
-    <Tag className={['aw-h', `aw-h--${level}`, className].filter(Boolean).join(' ')}>
+    <Tag
+      ref={ref}
+      // The TAG follows the semantic level; the CLASS follows the visual size —
+      // an h2 may wear the display size without touching the document outline.
+      className={['aw-h', `aw-h--${size ?? level}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
       {children}
     </Tag>
   );
-}
+});

package/kits/babylove/src/Button.tsx

@@ -1,19 +1,34 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
-export interface ButtonProps {
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   /** `primary` is the accent fill — at most one per view. */
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: () => void;
   children: ReactNode;
   className?: string;
 }
 
-export function Button({ variant = 'primary', size = 'md', disabled = false, onClick, children, className }: ButtonProps) {
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'primary', size = 'md', className, type, children, ...rest },
+  ref,
+) {
   return (
-    <button type="button" className={['bl-btn', `bl-btn--${variant}`, `bl-btn--${size}`, className].filter(Boolean).join(' ')} disabled={disabled} onClick={onClick}>
+    <button
+      ref={ref}
+      // default is `button`, but an explicit caller `type` (submit, reset) wins —
+      // a design default must never silently erase a prop the caller set.
+      type={type ?? 'button'}
+      className={['bl-btn', `bl-btn--${variant}`, `bl-btn--${size}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      // native + ARIA + state pass through: aria-label for icon-only buttons,
+      // aria-controls / aria-expanded for trigger controls, disabled, and onClick
+      // with its real event. The spine forwards, it does not swallow.
+      {...rest}
+    >
       {children}
     </button>
   );
-}
+});

package/kits/babylove/src/Heading.tsx

@@ -1,13 +1,32 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-export interface HeadingProps {
+export interface HeadingProps
+  extends Omit<HTMLAttributes<HTMLHeadingElement>, 'className'> {
   /** 1 = page title (28px), 2 = section (20px), 3 = card title (15px). */
   level?: 1 | 2 | 3;
+  /** Visual size — defaults to the level, so existing call sites keep their look. */
+  size?: 1 | 2 | 3;
   children: ReactNode;
   className?: string;
 }
 
-export function Heading({ level = 2, children, className }: HeadingProps) {
-  const Tag = (`h${level}`) as 'h1' | 'h2' | 'h3';
-  return <Tag className={[`bl-heading--${level}`, className].filter(Boolean).join(' ')}>{children}</Tag>;
-}
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { level = 2, size, className, children, ...rest },
+  ref,
+) {
+  const Tag = `h${level}` as 'h1' | 'h2' | 'h3';
+  return (
+    <Tag
+      ref={ref}
+      // The TAG follows the semantic level; the CLASS follows the visual size —
+      // an h2 may wear the display size without touching the document outline.
+      className={[`bl-heading--${size ?? level}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </Tag>
+  );
+});

package/kits/blueprint/src/Button.tsx

@@ -1,33 +1,34 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
-export interface ButtonProps {
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   /** `primary` is the pack's default fill — at most one accent action per view. */
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: () => void;
   children: ReactNode;
   className?: string;
 }
 
-export function Button({
-  variant = 'primary',
-  size = 'md',
-  disabled = false,
-  onClick,
-  children,
-  className,
-}: ButtonProps) {
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'primary', size = 'md', className, type, children, ...rest },
+  ref,
+) {
   return (
     <button
-      type="button"
+      ref={ref}
+      // default is `button`, but an explicit caller `type` (submit, reset) wins —
+      // a design default must never silently erase a prop the caller set.
+      type={type ?? 'button'}
       className={['bp-btn', `bp-btn--${variant}`, `bp-btn--${size}`, className]
         .filter(Boolean)
         .join(' ')}
-      disabled={disabled}
-      onClick={onClick}
+      // native + ARIA + state pass through: aria-label for icon-only buttons,
+      // aria-controls / aria-expanded for trigger controls, disabled, and onClick
+      // with its real event. The spine forwards, it does not swallow.
+      {...rest}
     >
       {children}
     </button>
   );
-}
+});

package/kits/blueprint/src/Heading.tsx

@@ -1,19 +1,32 @@
-import type { ReactNode } from 'react';
+import { forwardRef } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-export interface HeadingProps {
+export interface HeadingProps
+  extends Omit<HTMLAttributes<HTMLHeadingElement>, 'className'> {
   /** 1 = page title, 2 = section, 3 = sub-head. */
   level?: 1 | 2 | 3;
+  /** Visual size — defaults to the level, so existing call sites keep their look. */
+  size?: 1 | 2 | 3;
   children: ReactNode;
   className?: string;
 }
 
-export function Heading({ level = 2, children, className }: HeadingProps) {
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { level = 2, size, className, children, ...rest },
+  ref,
+) {
   const Tag = `h${level}` as 'h1' | 'h2' | 'h3';
   return (
     <Tag
-      className={['bp-heading', `bp-heading--${level}`, className].filter(Boolean).join(' ')}
+      ref={ref}
+      // The TAG follows the semantic level; the CLASS follows the visual size —
+      // an h2 may wear the display size without touching the document outline.
+      className={['bp-heading', `bp-heading--${size ?? level}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
     >
       {children}
     </Tag>
   );
-}
+});