@hraness/design-kit 0.36.5 → 0.39.0

package/src/mockups/client.tsx

@@ -9,6 +9,7 @@ import {
   useMemo,
   useRef,
   useState,
+  version,
 } from "react";
 
 import { joinMockupClasses, type MockupTheme } from "./core.js";
@@ -23,6 +24,18 @@ import { joinMockupClasses, type MockupTheme } from "./core.js";
 // measure only in the browser.
 const useIsomorphicLayoutEffect: typeof useLayoutEffect = typeof document === "undefined" ? () => undefined : useLayoutEffect;
 
+// React 18 drops unknown boolean attributes; React 19 recognizes inert as
+// boolean. Keep the actual HTML attribute in both supported runtimes. The
+// record describes compatibility attributes without claiming React 18's
+// HTMLAttributes (or React 19's boolean-only inert prop) accepts both forms.
+const inertAttribute: Readonly<Record<string, true | "">> = {
+  inert: Number.parseInt(version, 10) >= 19 ? true : "",
+};
+const noInertAttribute: Readonly<Record<string, true | "">> = {};
+function inertAttributes(inactive: boolean): Readonly<Record<string, true | "">> {
+  return inactive ? inertAttribute : noInertAttribute;
+}
+
 function assertUniqueIds(items: readonly Readonly<{ id: string }>[], what: string): void {
   if (items.length === 0) throw new RangeError(`${what} needs at least one entry.`);
   const seen = new Set<string>();
@@ -128,6 +141,8 @@ export type ShowcaseState<M extends string, O extends string = string> = Readonl
 export type ShowcaseSurface<S extends string, M extends string, O extends string = string> = Readonly<{
   id: S;
   label: string;
+  /** Optional explanation of what this surface illustrates. */
+  hint?: string;
   render: (state: ShowcaseState<M, O>) => ReactNode;
 }>;
 
@@ -208,7 +223,7 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
   // Pure, nonanimated authored states reserve one maximum before any choice.
   // They stay hidden and inert; only a detached measurement clone reveals them.
   const measurements = useMemo(() => fit !== "fill" ? null : surfaces.flatMap((entry) => modes.flatMap((choice) => (options ?? [{ id: undefined }]).map((optionChoice) => (
-    <div aria-hidden="true" className="hkm-mode-surface" data-hkm-measurement="" hidden inert key={JSON.stringify([entry.id, choice.id, optionChoice.id])}>
+    <div aria-hidden="true" className="hkm-mode-surface" data-hkm-measurement="" hidden {...inertAttributes(true)} key={JSON.stringify([entry.id, choice.id, optionChoice.id])}>
       <div className="hkm-fit"><div className="hkm-fit-inner">
         {entry.render({ animated: false, mode: choice.id, option: optionChoice.id, previousMode: choice.id, theme })}
       </div></div>
@@ -238,10 +253,12 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
   };
 
   const statusNode = status?.({ mode, option, surface: surface.id });
-  const hint = [modeChoice.hint, optionInactive ? undefined : optionChoice?.hint]
-    .map((text) => optionalText(text, "ModeShowcase hint"))
-    .filter((text) => text !== undefined)
-    .join(" ");
+  const describeChoice = (surfaceHint: string | undefined, modeHint: string | undefined, optionHint: string | undefined) =>
+    [surfaceHint, modeHint, optionHint].map((text) => optionalText(text, "ModeShowcase hint")).filter((text) => text !== undefined).join(" ");
+  const hint = describeChoice(surface.hint, modeChoice.hint, optionInactive ? undefined : optionChoice?.hint);
+  const hints = [...new Set(surfaces.flatMap((entry) => modes.flatMap((choice) =>
+    (optionInactiveModes.includes(choice.id) ? [undefined] : (options ?? [undefined])).map((optionEntry) =>
+      describeChoice(entry.hint, choice.hint, optionEntry?.hint)))))].filter((text) => text !== "");
   const hasStatus = statusNode !== undefined && statusNode !== null && statusNode !== false && statusNode !== "";
   return (
     <figure
@@ -307,7 +324,12 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
               </div>
             )}
           </div>
-          {hint === "" ? null : <p className="hkm-showcase-hint">{hint}</p>}
+          {hints.length === 0 ? null : (
+            <div className="hkm-showcase-hints">
+              <p className="hkm-showcase-hint">{hint}</p>
+              {hints.filter((text) => text !== hint).map((text) => <p aria-hidden="true" className="hkm-showcase-hint" data-hkm-reserving="" {...inertAttributes(true)} key={text}>{text}</p>)}
+            </div>
+          )}
         </div>
         <div className="hkm-mode-stage" ref={stage}>
           {measurements}
@@ -317,7 +339,7 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
               className="hkm-mode-surface"
               data-hkm-animated={entry.id === surface.id && animated ? "" : undefined}
               data-hkm-from={entry.id === surface.id && animated ? previousMode : undefined}
-              inert={entry.id !== surface.id}
+              {...inertAttributes(entry.id !== surface.id)}
               key={entry.id}
             >
               <FitToWidth minWidth={fit === "fill" ? 1 : minWidth}>
@@ -345,7 +367,7 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
 export type ThroughStep = Readonly<{
   id: string;
   label: string;
-  /** Optional accessible context; the visual keeps its own explanation. */
+  /** Optional explanation beside the label, and below the preview on compact screens. */
   hint?: string;
   render: (state: Readonly<{ animated: boolean; theme: MockupTheme | undefined }>) => ReactNode;
 }>;
@@ -416,14 +438,14 @@ function fitShowcaseStage(stage: HTMLDivElement, minimumHeight: number): void {
     // The tallest complete slide establishes the floor. Fitted type never feeds
     // back into it, and changing the active tab never requests a measurement.
     stage.style.setProperty("--hkm-showcase-fill-height", `${naturalHeight}px`);
-    for (const fixture of probe.querySelectorAll("[data-hkm-measurement]")) fixture.remove();
     probe.style.blockSize = `${naturalHeight}px`;
     probe.removeAttribute("data-hkm-measuring");
     const bodies = presentationBodies(stage).filter((body) => body.closest("[data-hkm-measurement]") === null);
     const copies = presentationBodies(probe);
-    for (const [index, copy] of copies.entries()) {
-      const body = bodies[index];
-      if (body === undefined) continue;
+    // Every authored state uses one readable size. A short terminal must not
+    // become a different typographic scale when the next tab has more lines.
+    let sharedSize = 4;
+    for (const copy of copies) {
       const lines = [...copy.querySelectorAll<HTMLElement>(".hkm-terminal-line")];
       const wrappedRows = (line: HTMLElement) => Math.ceil((line.getBoundingClientRect().height - 0.5) / Number.parseFloat(getComputedStyle(line).lineHeight));
       const baselineRows = lines.map(wrappedRows);
@@ -435,8 +457,9 @@ function fitShowcaseStage(stage: HTMLDivElement, minimumHeight: number): void {
         if (copy.scrollHeight <= copy.clientHeight + 1 && copy.scrollWidth <= copy.clientWidth + 1 && lines.every((line, index) => { const baseline = baselineRows[index]; return baseline !== undefined && wrappedRows(line) <= baseline; })) low = candidate;
         else high = candidate;
       }
-      body.style.setProperty("--hkm-terminal-presentation-size", `${Math.floor(low * 1000) / 1000}rem`);
+      sharedSize = Math.min(sharedSize, low);
     }
+    for (const body of bodies) body.style.setProperty("--hkm-terminal-presentation-size", `${Math.floor(sharedSize * 1000) / 1000}rem`);
     stage.setAttribute("data-hkm-fitted", "");
   } finally {
     probe.remove();
@@ -485,9 +508,12 @@ function useFittedShowcaseStage(fit: "natural" | "fill", source: unknown, variat
 }
 
 /**
- * Folder tabs and chevron controls walk a flow. All render functions stay mounted
- * to reserve the tallest panel; inactive panels are inert and visually hidden.
- * The keyboard model matches `ModeShowcase`.
+ * A tabbed walkthrough: the steps and the preview share one edge. Compact
+ * layouts attach a tab strip to the preview's top edge between Back and Next;
+ * at 720px and wider the steps stack on its start edge with their
+ * explanations. All render functions stay mounted to reserve the tallest
+ * panel; inactive panels are inert and visually hidden. The keyboard model
+ * matches `ModeShowcase`.
  */
 export function StepThrough({
   caption,
@@ -500,7 +526,7 @@ export function StepThrough({
   theme,
 }: Readonly<{
   steps: readonly ThroughStep[];
-  /** Fill the tallest natural slide and fit presentation terminals without scaling. */
+  /** Fill the tallest natural slide and fit presentation terminals at one shared size. */
   fit?: "natural" | "fill";
   caption?: string;
   initial?: string;
@@ -516,17 +542,68 @@ export function StepThrough({
   const id = useId();
   const [index, setIndex] = useState(() => Math.max(0, steps.findIndex((step) => step.id === initial)));
   const [animated, setAnimated] = useState(false);
+  const [vertical, setVertical] = useState(false);
+  const layout = useRef<HTMLDivElement>(null);
+  const tablist = useRef<HTMLDivElement>(null);
   const tabs = useRef(new Map<number, HTMLButtonElement>());
   const current = Math.min(index, steps.length - 1);
-  const step = itemAt(steps, current, "StepThrough steps");
+  const hints = steps.map((entry) => optionalText(entry.hint, "StepThrough hint"));
+  const currentHint = hints[current];
+
+  useIsomorphicLayoutEffect(() => {
+    const node = layout.current;
+    if (node === null || typeof ResizeObserver === "undefined") return undefined;
+    const measure = () => setVertical(node.clientWidth >= 720);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  // A strip that cannot show every label in full keeps only the selected
+  // label visible; the rest show their numbers and keep their accessible names.
+  useIsomorphicLayoutEffect(() => {
+    const list = tablist.current;
+    if (list === null || typeof ResizeObserver === "undefined") return undefined;
+    let disposed = false;
+    const measure = () => {
+      if (disposed) return;
+      list.removeAttribute("data-hkm-compact");
+      if (vertical) return;
+      const truncated = [...list.querySelectorAll<HTMLElement>(".hkm-step-label")].some((label) => label.scrollWidth > label.clientWidth + 1);
+      if (truncated) list.setAttribute("data-hkm-compact", "");
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(list);
+    void document.fonts.ready.then(measure);
+    return () => {
+      disposed = true;
+      observer.disconnect();
+      list.removeAttribute("data-hkm-compact");
+    };
+  }, [current, vertical]);
+
+  useIsomorphicLayoutEffect(() => {
+    const list = tablist.current;
+    const selected = tabs.current.get(current);
+    if (vertical || list === null || selected === undefined) return;
+    const bounds = list.getBoundingClientRect();
+    const active = selected.getBoundingClientRect();
+    // Scroll only the owned strip, without moving the surrounding page.
+    if (active.left < bounds.left) list.scrollLeft += active.left - bounds.left;
+    else if (active.right > bounds.right) list.scrollLeft += active.right - bounds.right;
+  }, [current, vertical]);
 
   const go = (next: number, focus = false) => {
     if (next < 0 || next >= steps.length || next === current) return;
     setIndex(next);
     setAnimated(true);
-    if (focus) tabs.current.get(next)?.focus();
+    if (focus) tabs.current.get(next)?.focus({ preventScroll: true });
   };
   const onTabKey = (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (vertical && (event.key === "ArrowLeft" || event.key === "ArrowRight")) return;
+    if (!vertical && (event.key === "ArrowUp" || event.key === "ArrowDown")) return;
     const next = nextTabIndex(event.key, current, steps.length);
     if (next === undefined) return;
     event.preventDefault();
@@ -535,61 +612,75 @@ export function StepThrough({
 
   return (
     <figure aria-label={`Illustration: ${label.toLowerCase()}`} className={joinMockupClasses("hkm-showcase", "hkm-steps", className)} data-hkm-fit={fit === "fill" ? fit : undefined} data-hkm-theme={theme} data-nosnippet="">
-      <div className="hkm-showcase-controls">
-        <div aria-label={label} className="hkm-tabs hkm-folder-tabs hkm-step-tabs" role="tablist">
+      <div className="hkm-step-layout" ref={layout}>
+        <div className="hkm-showcase-controls hkm-step-controls">
+          <div className="hkm-step-nav">
+            <button aria-label="Back" className="hkm-step-button" disabled={current === 0} onClick={() => go(current - 1)} type="button">
+              <svg aria-hidden="true" focusable="false" height="20" viewBox="0 0 24 24" width="20"><path d="m14.5 5-7 7 7 7" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.75" /></svg>
+            </button>
+            <span aria-hidden="true" className="hkm-step-count">{current + 1} / {steps.length}</span>
+            <div aria-label={label} aria-orientation={vertical ? "vertical" : "horizontal"} className="hkm-tabs hkm-step-tabs" ref={tablist} role="tablist">
+              {steps.map((entry, position) => (
+                <button
+                  aria-controls={`${id}-panel-${entry.id}`}
+                  aria-describedby={hints[position] === undefined ? undefined : `${id}-hint-${entry.id}`}
+                  aria-label={entry.label}
+                  aria-selected={position === current}
+                  className="hkm-tab"
+                  data-hkm-done={position < current ? "" : undefined}
+                  id={`${id}-tab-${entry.id}`}
+                  key={entry.id}
+                  onClick={() => go(position)}
+                  onKeyDown={onTabKey}
+                  ref={(element) => {
+                    if (element === null) tabs.current.delete(position);
+                    else tabs.current.set(position, element);
+                  }}
+                  role="tab"
+                  tabIndex={position === current ? 0 : -1}
+                  type="button"
+                >
+                  <span aria-hidden="true" className="hkm-step-number">{position + 1}</span>
+                  <span className="hkm-step-copy">
+                    <span className="hkm-step-label">{entry.label}</span>
+                    {hints[position] === undefined ? null : <span className="hkm-step-hint" id={`${id}-hint-${entry.id}`}>{hints[position]}</span>}
+                  </span>
+                </button>
+              ))}
+            </div>
+            <button aria-label="Next" className="hkm-step-button" disabled={current === steps.length - 1} onClick={() => go(current + 1)} type="button">
+              <svg aria-hidden="true" focusable="false" height="20" viewBox="0 0 24 24" width="20"><path d="m9.5 5 7 7-7 7" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.75" /></svg>
+            </button>
+          </div>
+        </div>
+        <div className="hkm-showcase-stage hkm-step-stage" ref={stage}>
           {steps.map((entry, position) => (
-            <button
-              aria-controls={`${id}-panel-${entry.id}`}
-              aria-selected={position === current}
-              className="hkm-tab"
-              data-hkm-done={position < current ? "" : undefined}
-              id={`${id}-tab-${entry.id}`}
+            <div
+              aria-hidden={position !== current}
+              aria-labelledby={`${id}-tab-${entry.id}`}
+              className="hkm-step-panel"
+              data-hkm-animated={position === current && animated ? "" : undefined}
+              id={`${id}-panel-${entry.id}`}
+              {...inertAttributes(position !== current)}
               key={entry.id}
-              onClick={() => go(position)}
-              onKeyDown={onTabKey}
-              ref={(element) => {
-                if (element === null) tabs.current.delete(position);
-                else tabs.current.set(position, element);
-              }}
-              role="tab"
+              role="tabpanel"
               tabIndex={position === current ? 0 : -1}
-              type="button"
             >
-              <span aria-hidden="true" className="hkm-step-number">{position + 1}</span>
-              {entry.label}
-            </button>
+              {fit === "fill"
+                ? <div className="hkm-fit"><div className="hkm-fit-inner">{entry.render({ animated: position === current && animated, theme })}</div></div>
+                : <FitToWidth minWidth={minWidth}>{entry.render({ animated: position === current && animated, theme })}</FitToWidth>}
+            </div>
           ))}
         </div>
-      </div>
-      <div className="hkm-showcase-stage hkm-step-stage" ref={stage}>
-        {steps.map((entry, position) => (
-          <div
-            aria-hidden={position !== current}
-            aria-labelledby={`${id}-tab-${entry.id}`}
-            className="hkm-step-panel"
-            data-hkm-animated={position === current && animated ? "" : undefined}
-            id={`${id}-panel-${entry.id}`}
-            inert={position !== current}
-            key={entry.id}
-            role="tabpanel"
-          >
-            {fit === "fill"
-              ? <div className="hkm-fit"><div className="hkm-fit-inner">{entry.render({ animated: position === current && animated, theme })}</div></div>
-              : <FitToWidth minWidth={minWidth}>{entry.render({ animated: position === current && animated, theme })}</FitToWidth>}
+        {hints.some((hint) => hint !== undefined) ? (
+          <div aria-hidden="true" className="hkm-step-descriptions">
+            {steps.map((entry, position) => <p className="hkm-step-description" data-hkm-active={position === current ? "" : undefined} key={entry.id}>{hints[position]}</p>)}
           </div>
-        ))}
-      </div>
-      <div className="hkm-step-nav">
-        <button aria-label="Back" className="hkm-step-button" disabled={current === 0} onClick={() => go(current - 1)} type="button">
-          <svg aria-hidden="true" focusable="false" height="28" viewBox="0 0 24 24" width="28"><path d="m14.5 5-7 7 7 7" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.75" /></svg>
-        </button>
-        <span aria-live="polite" className="hkm-showcase-status hkm-step-announcement">
-          Step {current + 1} of {steps.length}{step.hint === undefined ? "" : `. ${step.hint}`}
-        </span>
-        <button aria-label="Next" className="hkm-step-button" data-hkm-primary="" disabled={current === steps.length - 1} onClick={() => go(current + 1)} type="button">
-          <svg aria-hidden="true" focusable="false" height="28" viewBox="0 0 24 24" width="28"><path d="m9.5 5 7 7-7 7" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.75" /></svg>
-        </button>
+        ) : null}
       </div>
+      <span aria-live="polite" className="hkm-showcase-status hkm-step-announcement">
+        Step {current + 1} of {steps.length}{currentHint === undefined ? "" : `. ${currentHint}`}
+      </span>
       {captionText === undefined ? null : (
         <figcaption className="hkm-showcase-caption"><span>{captionText}</span></figcaption>
       )}

package/src/mockups/core.tsx

@@ -1,5 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 
+import { providerMark, providerMarkMonogram, providerMarkOnAccent } from "../provider-marks.js";
+
 /*
  * Shared pieces for the code-built mockups. Server-safe plain React: no hooks,
  * no context, no StyleX, and no runtime dependency other than React, so a film
@@ -306,6 +308,34 @@ export function MockupGlyph({
   );
 }
 
+/**
+ * A product's brand mark from the shared provider-mark registry, such as
+ * "Apple Contacts", "LinkedIn", or "iMessage". `tile` draws the vendor glyph
+ * in readable ink on the brand color, like an app icon; `glyph` follows the
+ * surrounding text color. Names without a registered mark get a neutral
+ * monogram tile, never an invented logo. Decorative: always aria-hidden, so
+ * name the product in nearby text.
+ */
+export function MockupBrandMark({
+  className,
+  name,
+  size = 32,
+  variant = "tile",
+}: Readonly<{ name: string; size?: number; variant?: "tile" | "glyph"; className?: string }>) {
+  if (!(size > 0)) throw new RangeError("MockupBrandMark size must be positive.");
+  const mark = providerMark(name);
+  const style = { "--hkm-mark-size": `${String(size)}px`, ...(mark === undefined || variant !== "tile" ? {} : { "--hkm-mark-accent": mark.accent, "--hkm-mark-ink": providerMarkOnAccent(mark) }) } as CSSProperties;
+  if (mark === undefined) {
+    return <span aria-hidden="true" className={joinMockupClasses("hkm-brand-mark", className)} data-hkm-monogram="" style={style}>{providerMarkMonogram(name)}</span>;
+  }
+  return (
+    <span aria-hidden="true" className={joinMockupClasses("hkm-brand-mark", className)} data-hkm-mark={mark.id} data-hkm-variant={variant} style={style}>
+      {/* Generated from vendored, sanitized artwork in provider-marks.generated.ts. */}
+      <svg dangerouslySetInnerHTML={{ __html: mark.glyph.body }} fill="currentColor" focusable="false" viewBox={mark.glyph.viewBox} />
+    </span>
+  );
+}
+
 /** The three window buttons at the start of a title bar. Decorative. */
 export function WindowLights() {
   return (

package/src/mockups.css

@@ -107,6 +107,39 @@
     flex: none;
   }
 
+  /* Brand marks are app-icon tiles: the vendor glyph in readable ink on the
+   * vendor color. The glyph variant follows the surrounding text instead. */
+  .hkm-root .hkm-brand-mark {
+    display: inline-grid;
+    flex: none;
+    place-items: center;
+    inline-size: var(--hkm-mark-size, 32px);
+    block-size: var(--hkm-mark-size, 32px);
+    border-radius: calc(var(--hkm-mark-size, 32px) * 0.26);
+    background: var(--hkm-mark-accent, var(--hkm-field));
+    color: var(--hkm-mark-ink, var(--hkm-muted));
+    box-shadow: inset 0 0 0 1px light-dark(rgb(0 0 0 / 0.06), rgb(255 255 255 / 0.1));
+    font: 650 calc(var(--hkm-mark-size, 32px) * 0.36)/1 var(--hkm-font);
+    letter-spacing: 0.01em;
+  }
+
+  .hkm-root .hkm-brand-mark svg {
+    display: block;
+    inline-size: 56%;
+    block-size: 56%;
+  }
+
+  .hkm-root .hkm-brand-mark[data-hkm-variant="glyph"] {
+    background: none;
+    box-shadow: none;
+    color: inherit;
+  }
+
+  .hkm-root .hkm-brand-mark[data-hkm-variant="glyph"] svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
   .hkm-root .hkm-avatar {
     display: inline-grid;
     flex: none;
@@ -2329,22 +2362,13 @@
   }
 
   .hkm-showcase .hkm-step-number {
-    display: inline-grid;
-    place-items: center;
-    inline-size: 20px;
-    block-size: 20px;
-    border: 1px solid currentColor;
-    border-radius: 50%;
-    font-size: 11px;
+    flex: none;
+    color: var(--hkm-sc-muted);
+    font-size: 0.875rem;
+    line-height: 1.5;
     font-variant-numeric: tabular-nums;
   }
 
-  .hkm-showcase .hkm-tab[data-hkm-done] .hkm-step-number {
-    border-color: var(--hkm-accent);
-    background: var(--hkm-accent);
-    color: var(--hkm-accent-foreground);
-  }
-
   .hkm-showcase .hkm-showcase-settings {
     display: flex;
     flex-wrap: wrap;
@@ -2412,11 +2436,26 @@
     outline-color: var(--hkm-accent-foreground);
   }
 
+  .hkm-showcase .hkm-showcase-hints {
+    display: grid;
+    min-inline-size: 0;
+  }
+
+  .hkm-showcase .hkm-showcase-hints > .hkm-showcase-hint {
+    grid-area: 1 / 1;
+  }
+
+  .hkm-showcase .hkm-showcase-hint[data-hkm-reserving] {
+    visibility: hidden;
+    pointer-events: none;
+  }
+
   .hkm-showcase .hkm-showcase-hint {
     min-block-size: 2.9em;
     margin: 0;
     color: var(--hkm-sc-muted);
     font-size: 13px;
+    overflow-wrap: anywhere;
   }
 
   .hkm-showcase .hkm-showcase-stage {
@@ -2512,14 +2551,14 @@
     }
   }
 
-  /* Folder tabs share an edge with each showcase panel. */
+  /* Mode selectors retain a shared edge with their preview panel. */
   .hkm-showcase:is(.hkm-steps, .hkm-modes) { gap: 0; }
   .hkm-showcase.hkm-steps .hkm-showcase-controls { padding: 0; border: 0; border-radius: 0; background: transparent; }
   .hkm-showcase .hkm-folder-tabs { gap: 6px; margin: 0; padding: 0; border: 0; position: relative; z-index: 1; }
   .hkm-showcase .hkm-folder-tabs .hkm-tab { min-block-size: 48px; padding: 12px 18px; border: 1px solid var(--hkm-sc-line); border-block-end: 0; border-radius: 12px 12px 0 0; background: var(--hkm-sc-field); color: var(--hkm-sc-muted); }
   .hkm-showcase .hkm-folder-tabs .hkm-tab[aria-selected="true"] { background: var(--hkm-sc-bg); color: var(--hkm-sc-fg); }
   .hkm-showcase .hkm-folder-tabs .hkm-tab:hover { color: var(--hkm-sc-fg); }
-  .hkm-showcase.hkm-steps .hkm-step-stage { display: grid; border: 1px solid var(--hkm-sc-line); border-radius: 0 12px 12px 12px; background: var(--hkm-sc-bg); margin-block-start: -1px; overflow: clip; }
+  .hkm-showcase.hkm-steps .hkm-step-stage { display: grid; min-inline-size: 0; border: 1px solid var(--hkm-sc-line); border-radius: var(--hkm-step-radius, 12px); background: var(--hkm-sc-bg); overflow: clip; }
   .hkm-showcase.hkm-modes .hkm-mode-panel { border: 1px solid var(--hkm-sc-line); border-radius: 12px; background: var(--hkm-sc-bg); overflow: clip; }
   .hkm-showcase.hkm-modes .hkm-folder-tabs + .hkm-mode-panel { border-start-start-radius: 0; margin-block-start: -1px; }
   .hkm-showcase.hkm-modes .hkm-showcase-controls { border: 0; border-block-end: 1px solid var(--hkm-sc-line); border-radius: 0; }
@@ -2527,10 +2566,13 @@
   .hkm-mode-surface { grid-area: 1 / 1; min-inline-size: 0; align-self: start; }
   .hkm-mode-surface[aria-hidden="true"] { visibility: hidden; pointer-events: none; }
   .hkm-showcase.hkm-modes .hkm-mode-surface > .hkm-fit > .hkm-fit-inner > .hkm-root,
-  .hkm-showcase.hkm-modes .hkm-mode-surface > .hkm-fit > .hkm-fit-inner > .hkm-root > .hkm-window { border: 0; border-radius: 0; box-shadow: none; }
+  .hkm-showcase.hkm-modes .hkm-mode-surface > .hkm-fit > .hkm-fit-inner > .hkm-root > .hkm-window,
+  .hkm-showcase.hkm-steps .hkm-step-panel > .hkm-fit > .hkm-fit-inner > .hkm-root,
+  .hkm-showcase.hkm-steps .hkm-step-panel > .hkm-fit > .hkm-fit-inner > .hkm-root > .hkm-window { border: 0; border-radius: 0; box-shadow: none; }
   .hkm-step-panel { grid-area: 1 / 1; min-inline-size: 0; align-self: start; }
   .hkm-step-panel[aria-hidden="true"] { visibility: hidden; pointer-events: none; }
-  .hkm-showcase.hkm-steps .hkm-step-panel .hkm-root { border-start-start-radius: 0; border-start-end-radius: 0; box-shadow: none; }
+  /* Browser and app titles use the same chrome geometry inside a sequence. */
+  .hkm-showcase .hkm-root :is(.hkm-title-bar, .hkm-browser-bar) { block-size: 44px; font-size: 13px; }
   /* Fill uses the tallest complete slide as its natural height. It does not
    * scale text or ask fitted font sizes to determine the stage height. */
   .hkm-showcase[data-hkm-fit="fill"] [data-hkm-measuring] [data-hkm-fill-frame] > .hkm-window > .hkm-page { max-block-size: none; }
@@ -2567,11 +2609,75 @@
     flex: none;
   }
 
-  .hkm-showcase.hkm-steps .hkm-step-nav { justify-content: space-between; padding-block-start: 18px; gap: 16px; }
-  .hkm-showcase.hkm-steps .hkm-step-button { display: inline-grid; place-items: center; min-inline-size: 52px; min-block-size: 52px; padding: 10px; border: 0; border-radius: 12px; background: transparent; color: var(--hkm-sc-fg); }
-  .hkm-showcase.hkm-steps .hkm-step-button[data-hkm-primary] { background: var(--hkm-sc-fg); color: var(--hkm-sc-bg); }
-  .hkm-showcase.hkm-steps .hkm-step-button:disabled { color: var(--hkm-sc-muted); background: transparent; }
-  .hkm-showcase.hkm-steps .hkm-step-button[data-hkm-primary]:disabled { background: var(--hkm-sc-field); }
+  /* A walkthrough is one tabbed selector: the steps and the preview share an
+   * edge. Compact layouts attach a tab strip to the preview's top edge between
+   * Back and Next. Wide layouts stack the steps on its start edge, flush with
+   * a square corner, and put Back and Next under them. The selected tab takes
+   * the window-chrome color so it reads as part of the frame below it. */
+  .hkm-showcase.hkm-steps {
+    --hkm-step-radius: 12px;
+    --hkm-step-tab-radius: 10px;
+    --hkm-step-tab-selected: var(--hkm-chrome);
+    --hkm-step-tab-hover: color-mix(in srgb, var(--hkm-chrome) 55%, transparent);
+    font-size: 1rem;
+    line-height: 1.5;
+  }
+  .hkm-showcase .hkm-step-layout { display: grid; grid-template-columns: minmax(0, 1fr); grid-template-areas: "controls" "stage" "descriptions"; align-items: start; min-inline-size: 0; }
+  .hkm-showcase.hkm-steps .hkm-step-controls { grid-area: controls; position: relative; z-index: 1; min-inline-size: 0; margin-block-end: -1px; }
+  .hkm-showcase.hkm-steps .hkm-step-stage { grid-area: stage; }
+  .hkm-showcase.hkm-steps .hkm-step-nav { display: grid; grid-template-columns: 44px minmax(0, 1fr) 44px; grid-template-areas: "back tabs next"; align-items: end; gap: 6px; min-inline-size: 0; padding: 0; }
+  .hkm-showcase.hkm-steps .hkm-step-button { display: inline-grid; place-items: center; inline-size: 44px; min-inline-size: 44px; min-block-size: 44px; margin-block-end: 1px; padding: 0; border: 0; border-radius: var(--hkm-step-tab-radius); background: transparent; color: var(--hkm-sc-fg); }
+  .hkm-showcase.hkm-steps .hkm-step-button:first-child { grid-area: back; }
+  .hkm-showcase.hkm-steps .hkm-step-button:last-child { grid-area: next; }
+  .hkm-showcase.hkm-steps .hkm-step-button:hover:enabled { background: var(--hkm-step-tab-hover); }
+  .hkm-showcase.hkm-steps .hkm-step-button:disabled { background: transparent; color: var(--hkm-sc-muted); cursor: default; }
+  .hkm-showcase .hkm-step-count { display: none; grid-area: count; color: var(--hkm-sc-muted); font: 500 0.8125rem/1 var(--hkm-mono); font-variant-numeric: tabular-nums; text-align: center; }
+  .hkm-showcase.hkm-steps .hkm-step-tabs { grid-area: tabs; display: flex; gap: 2px; min-inline-size: 0; margin: 0; padding: 0; overflow-x: auto; overflow-y: hidden; border: 0; scrollbar-width: none; }
+  .hkm-showcase.hkm-steps .hkm-step-tabs::-webkit-scrollbar { display: none; }
+  .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab { display: inline-flex; flex: 0 1 auto; align-items: center; gap: 10px; min-inline-size: 44px; min-block-size: 44px; padding: 10px 16px; border: 1px solid transparent; border-block-end: 0; border-radius: var(--hkm-step-tab-radius) var(--hkm-step-tab-radius) 0 0; background: transparent; color: var(--hkm-sc-muted); font-size: 0.9375rem; line-height: 1.4; font-weight: 550; text-align: start; white-space: nowrap; }
+  .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab:hover { background: var(--hkm-step-tab-hover); color: var(--hkm-sc-fg); }
+  .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab[aria-selected="true"] { border-color: var(--hkm-sc-line); background: var(--hkm-step-tab-selected); color: var(--hkm-sc-fg); }
+  /* A preview pinned to its own theme lends that theme to the selected tab,
+   * so a dark window on a light page still reads as one frame. */
+  .hkm-showcase.hkm-steps:has(.hkm-step-panel[aria-hidden="false"] .hkm-root[data-hkm-theme="dark"]) .hkm-step-tabs .hkm-tab[aria-selected="true"] { color-scheme: dark; }
+  .hkm-showcase.hkm-steps:has(.hkm-step-panel[aria-hidden="false"] .hkm-root[data-hkm-theme="light"]) .hkm-step-tabs .hkm-tab[aria-selected="true"] { color-scheme: light; }
+  .hkm-showcase.hkm-steps:has(.hkm-step-panel[aria-hidden="false"] .hkm-root[data-hkm-theme]) .hkm-step-tabs .hkm-tab[aria-selected="true"] { color: var(--hkm-fg); }
+  .hkm-showcase.hkm-steps:has(.hkm-step-panel[aria-hidden="false"] .hkm-root[data-hkm-theme]) .hkm-step-tabs .hkm-tab[aria-selected="true"] :is(.hkm-step-number, .hkm-step-label) { color: var(--hkm-fg); }
+  .hkm-showcase.hkm-steps:has(.hkm-step-panel[aria-hidden="false"] .hkm-root[data-hkm-theme]) .hkm-step-tabs .hkm-tab[aria-selected="true"] .hkm-step-hint { color: var(--hkm-muted); }
+  .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab:focus-visible { outline-offset: -3px; }
+  .hkm-showcase.hkm-steps .hkm-step-number { color: var(--hkm-sc-muted); font: 500 0.8125rem/1.4 var(--hkm-mono); }
+  .hkm-showcase.hkm-steps .hkm-tab[aria-selected="true"] .hkm-step-number { color: var(--hkm-sc-fg); }
+  .hkm-showcase .hkm-step-copy { display: flex; flex-direction: column; gap: 4px; min-inline-size: 0; }
+  .hkm-showcase .hkm-step-label { overflow: hidden; font: inherit; text-overflow: ellipsis; }
+  .hkm-showcase .hkm-step-hint { display: none; color: var(--hkm-sc-muted); font-size: 0.875rem; line-height: 1.45; font-weight: 400; }
+  .hkm-showcase .hkm-step-descriptions { grid-area: descriptions; display: grid; padding: 12px 4px 0; }
+  .hkm-showcase .hkm-step-description { grid-area: 1 / 1; margin: 0; color: var(--hkm-sc-muted); font-size: 0.875rem; line-height: 1.5; }
+  .hkm-showcase .hkm-step-description:not([data-hkm-active]) { visibility: hidden; }
+  .hkm-showcase .hkm-step-panel:focus-visible { outline: 2px solid var(--hkm-accent); outline-offset: -4px; }
+  /* A strip too narrow for every label keeps the selected label and shows
+   * numbers for the rest; each label stays the tab's accessible name. */
+  .hkm-showcase.hkm-steps .hkm-step-tabs[data-hkm-compact] .hkm-tab:not([aria-selected="true"]) { flex: none; justify-content: center; padding-inline: 12px; }
+  .hkm-showcase.hkm-steps .hkm-step-tabs[data-hkm-compact] .hkm-tab:not([aria-selected="true"]) .hkm-step-copy { display: none; }
+  @container hkm-showcase (max-width: 519px) {
+    .hkm-showcase.hkm-steps .hkm-step-nav { grid-template-columns: 40px minmax(0, 1fr) 40px; gap: 4px; }
+    .hkm-showcase.hkm-steps .hkm-step-button { inline-size: 40px; min-inline-size: 40px; }
+    .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab { gap: 8px; padding-inline: 12px; font-size: 0.875rem; }
+  }
+  @container hkm-showcase (min-width: 720px) {
+    .hkm-showcase .hkm-step-layout { grid-template-columns: minmax(200px, 0.72fr) minmax(0, 1.6fr); grid-template-areas: "controls stage"; align-items: stretch; }
+    .hkm-showcase.hkm-steps .hkm-step-controls { margin-block-end: 0; margin-inline-end: -1px; }
+    .hkm-showcase.hkm-steps .hkm-step-stage { align-self: stretch; border-start-start-radius: 0; }
+    .hkm-showcase.hkm-steps .hkm-step-nav { grid-template-areas: "tabs tabs tabs" "back count next"; align-items: center; row-gap: 14px; column-gap: 6px; }
+    .hkm-showcase.hkm-steps .hkm-step-button { margin: 0; }
+    .hkm-showcase .hkm-step-count { display: block; }
+    .hkm-showcase.hkm-steps .hkm-step-tabs { flex-direction: column; gap: 2px; overflow: visible; }
+    .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab { display: grid; flex: none; grid-template-columns: 2.5ch minmax(0, 1fr); align-items: start; gap: 12px; padding: 14px 16px; border: 1px solid transparent; border-inline-end: 0; border-radius: var(--hkm-step-tab-radius) 0 0 var(--hkm-step-tab-radius); white-space: normal; }
+    .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab[aria-selected="true"] { border-color: var(--hkm-sc-line); }
+    .hkm-showcase.hkm-steps .hkm-step-number { padding-block-start: 0.1rem; }
+    .hkm-showcase .hkm-step-label { overflow: visible; }
+    .hkm-showcase .hkm-step-hint { display: block; }
+    .hkm-showcase .hkm-step-descriptions { display: none; }
+  }
   .hkm-showcase.hkm-steps .hkm-step-announcement { position: absolute; inline-size: 1px; block-size: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
   .hkm-showcase:is(.hkm-steps, .hkm-modes) .hkm-showcase-caption { margin-block-start: 1rem; }
 
@@ -2679,7 +2785,8 @@
 
     .hkm-showcase .hkm-tab[aria-selected="true"],
     .hkm-showcase .hkm-segmented button[aria-pressed="true"],
-    .hkm-showcase .hkm-tab[data-hkm-done] .hkm-step-number,
+    .hkm-showcase.hkm-steps .hkm-tab[aria-selected="true"],
+    .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab[aria-selected="true"],
     .hkm-root .hkm-popover-item[data-hkm-selected],
     .hkm-root .hkm-work-mark {
       forced-color-adjust: none;
@@ -2687,6 +2794,19 @@
       color: HighlightText;
     }
 
+    .hkm-showcase.hkm-steps .hkm-tab[aria-selected="true"] :is(.hkm-step-number, .hkm-step-hint) {
+      color: HighlightText;
+    }
+
+    /* Fill stages reserve their authored field for the live preview. Keep the
+     * selected tab in the system pair even when that fill rule is authored by
+     * a consumer layer with a stronger declaration. */
+    .hkm-showcase[data-hkm-fit="fill"].hkm-steps .hkm-tab[aria-selected="true"] {
+      forced-color-adjust: none;
+      background: Highlight !important;
+      color: HighlightText !important;
+    }
+
     .hkm-showcase .hkm-segmented button[aria-pressed="true"]:disabled {
       background: ButtonFace;
       color: GrayText;
@@ -2708,3 +2828,18 @@
     }
   }
 }
+
+/* Consumer layers and palette variable chains can add stronger declarations
+ * after the legacy component layer. Keep the system selection pair as the
+ * final forced-colors contract. */
+@media (forced-colors: active) {
+  .hkm-showcase.hkm-steps .hkm-step-tabs .hkm-tab[aria-selected="true"] {
+    forced-color-adjust: none;
+    background: Highlight !important;
+    color: HighlightText !important;
+  }
+
+  .hkm-showcase.hkm-steps .hkm-tab[aria-selected="true"] :is(.hkm-step-number, .hkm-step-hint) {
+    color: HighlightText !important;
+  }
+}