@half-built/astro 0.1.0

package/src/components/Widget.astro

@@ -0,0 +1,41 @@
+---
+/* Sidebar widget: plain block heading + list, matching the live site's
+   Gutenberg block widgets (which rendered h2.wp-block-heading inside
+   .widget_block; renamed at extraction, step 11.1).
+   List links keep their natural underline: they are proper links. */
+interface Props { title: string; headingLevel?: 2 | 3 | 4; class?: string }
+const { title, headingLevel = 2, class: className } = Astro.props;
+/* Annotated, not cast: an `as` cast in the frontmatter can make the Astro
+   compiler drop the Props type (see PostCard.astro). */
+const Heading: "h2" | "h3" | "h4" = `h${headingLevel}`;
+---
+<section class:list={["widget", className]}>
+  <Heading class="widget-title">{title}</Heading>
+  <div class="widget-body"><slot /></div>
+</section>
+
+<style>
+  .widget { margin: 0 0 2em; }
+  /* Owner ruling 2026-07-26 (diverges from live's larger headings):
+     widget headers share the Subscribe panel's title scale. */
+  .widget-title {
+    margin-top: 0;
+    margin-bottom: 10px;
+    line-height: 1.2;
+    font-size: var(--font-size-base);
+  }
+  .widget-body :global(ul) { list-style: none; padding: 0; margin: 0; }
+  .widget-body :global(li) {
+    margin-bottom: 7px;
+    padding-bottom: 7px;
+    font-size: var(--font-size-sm);
+    border-bottom: 1px solid var(--divider-faint);
+  }
+  .widget-body :global(li:last-child) { margin-bottom: 0; padding-bottom: 0; border-bottom: none; }
+  .widget-body :global(a) {
+    color: var(--ink);
+    transition: var(--transition);
+    text-decoration: underline;
+  }
+  .widget-body :global(a:hover), .widget-body :global(a:focus) { color: var(--ink); }
+</style>

package/src/components/content/BlogImage.astro

@@ -0,0 +1,39 @@
+---
+import type { ImageMetadata } from "astro";
+import CornerBadges from "../CornerBadges.astro";
+import SmartImage from "../SmartImage.astro";
+import LightboxLink from "../LightboxLink.astro";
+
+/* `frameless` is the sanctioned exception to the site-wide 2px image
+   outline (prose.css): the mascot on the brand page floats free (owner
+   ruling 2026-07-26). Everything else takes the default. */
+/* `narrow` caps the image at the half-column responsive step (495px),
+   centered; for shots that read fine small (close-ups, tall crops). */
+/* `genai` marks an AI-generated image with the AI Art corner badge
+   (CornerBadges.astro). */
+interface Props { src: ImageMetadata; alt?: string; caption?: string; frameless?: boolean; narrow?: boolean; genai?: boolean; class?: string }
+const { src, alt = "", caption, frameless = false, narrow = false, genai = false, class: className } = Astro.props;
+---
+{/* Image branching and lb-attrs live in the primitives (step 5). */}
+<figure class:list={["blog-image", frameless && "blog-image-frameless", narrow && "blog-image-narrow", className]}>
+  <LightboxLink href={src.src} w={src.width} h={src.height} caption={caption ?? alt}>
+    <SmartImage src={src} alt={alt} widths={[495, 990, Math.min(src.width, 1980)]} sizes={narrow ? "(max-width: 1024px) 50vw, 495px" : "(max-width: 1024px) 100vw, 990px"} />
+    <CornerBadges genai={genai} />
+  </LightboxLink>
+  {caption && <figcaption class="caption">{caption}</figcaption>}
+</figure>
+
+<style>
+  .blog-image { margin: 20px 0; }
+  .blog-image-frameless :global(img) { border: 0; }
+  /* Images narrower than the column center, matching the centered
+     captions (full-width images are unaffected). The link hugs the image
+     (fit-content, centered) rather than spanning the column, so a corner
+     badge lands on the image's corner and not the column's. */
+  .blog-image :global(.lightbox-link) { width: fit-content; max-width: 100%; margin-inline: auto; }
+  .blog-image :global(img) { max-width: 100%; height: auto; display: block; margin-inline: auto; }
+  .blog-image-narrow :global(.lightbox-link) { max-width: min(495px, 100%); }
+  /* Type from the .caption pattern. Fidelity pass (handoff 5.5): live
+     figcaptions are centered. */
+  figcaption { margin-top: 5px; text-align: center; }
+</style>

package/src/components/content/Button.astro

@@ -0,0 +1,57 @@
+---
+/* The house button (owner request 2026-08-26): one component over the
+   press-box patterns so every button on the site, and later every site
+   on the library, draws the same three looks.
+
+   variant: "plain" is the ink press box (nav links, pagination); "shaded"
+   is the same box on the nav's current-item shade; "accent-1"
+   wears the brand amber and "accent-2" the cyan, both in the callout
+   combination (accent line and ink on a faint tint, filling solid while
+   held). size: "md" is the nav-box size, "lg" the call-to-action size.
+   With href it renders an anchor, otherwise a button (type "button"
+   unless told otherwise). Put an icon first in the slot and it gets the
+   gap; the text is the slot. */
+interface Props {
+  variant?: "plain" | "shaded" | "accent-1" | "accent-2";
+  size?: "md" | "lg";
+  href?: string;
+  type?: "button" | "submit";
+  class?: string;
+}
+const { variant = "plain", size = "md", href, type = "button", class: className } = Astro.props;
+const classes = [
+  "button",
+  "press-box",
+  variant === "shaded" && "press-box-shaded",
+  (variant === "accent-1" || variant === "accent-2") && "press-box-accent",
+  variant === "accent-1" && "press-box-accent-1",
+  variant === "accent-2" && "press-box-accent-2",
+  `button-${size}`,
+];
+---
+{href ? (
+  <a class:list={[...classes, className]} href={href}><slot /></a>
+) : (
+  <button class:list={[...classes, className]} type={type}><slot /></button>
+)}
+
+<style>
+  .button {
+    display: inline-block;
+    font-weight: 700;
+    text-align: center;
+  }
+  .button-md {
+    padding: 7px 15px;
+    font-size: var(--font-size-sm);
+    text-transform: uppercase;
+  }
+  .button-lg {
+    padding: 10px 24px;
+    font-size: var(--font-size-md);
+    letter-spacing: 0.08em;
+  }
+  /* A leading icon sits on the text's baseline with a gap; the svg comes
+     through the slot, hence :global. */
+  .button :global(svg:first-child) { vertical-align: -0.15em; margin-right: 8px; }
+</style>

package/src/components/content/Callout.astro

@@ -0,0 +1,75 @@
+---
+/* Admonition panel (Confluence-style info/warning/error blocks), owner
+   request 2026-08-21, rendered in the house line system: a 2px box in the
+   type's line color, a low-opacity tint of the same color, and a label
+   straddling the top rule the way the theme's date boxes do. Inks stay in
+   the house families (graphite, amber, cyan, red): note and info read
+   graphite and the type is told by the label text, tip and warning take
+   the first accent, success the second, error the red. */
+interface Props {
+  type?: "note" | "info" | "tip" | "success" | "warning" | "error";
+  title?: string;
+  class?: string;
+}
+const { type = "note", title, class: className } = Astro.props;
+const label = title ?? type;
+---
+{/* role="note", not <aside>: aside is a landmark, and html-validate's
+    unique-landmark rule (rightly) demands unique names, which repeated
+    callouts on one page cannot provide. */}
+<div class:list={["callout", `callout-${type}`, "rule-box", "tint-overlay", className]} role="note">
+  <strong class="callout-label boxed-label">{label}</strong>
+  <div class="callout-body"><slot /></div>
+</div>
+
+<style>
+  /* Box from .rule-box, tint from .tint-overlay; this component only
+     keys both to the type's line color and adds its margin. */
+  .callout {
+    --tint-color: var(--callout-line);
+    --tint-opacity: 0.06;
+
+    border-color: var(--callout-line);
+    margin: 30px 0;
+  }
+  .callout::before { pointer-events: none; }
+  .callout-label {
+    position: absolute;
+    top: 0;
+    left: 20px;
+    /* Center the label on the 2px top rule, not on the padding-box edge. */
+    transform: translateY(calc(-50% - 2px));
+    padding: 4px 10px;
+    font-size: var(--font-size-xs);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    line-height: 1;
+    color: var(--callout-ink);
+    border-color: var(--callout-line);
+  }
+  .callout-body { position: relative; }
+  .callout-body > :global(:last-child) { margin-bottom: 0; }
+
+  .callout-note,
+  .callout-info,
+  .callout-success {
+    --callout-line: var(--rule);
+    --callout-ink: var(--ink);
+  }
+  .callout-tip,
+  .callout-warning {
+    --callout-line: var(--accent-1);
+    --callout-ink: var(--accent-1-ink);
+  }
+  /* Success takes the second accent (owner call 2026-08-26): cyan is the
+     "it worked" temperature, and it keeps the amber for tip and warning. */
+  .callout-success {
+    --callout-line: var(--accent-2);
+    --callout-ink: var(--accent-2-ink);
+  }
+  .callout-error {
+    --callout-line: var(--error-ink);
+    --callout-ink: var(--error-ink);
+  }
+</style>

package/src/components/content/CodeBlock.astro

@@ -0,0 +1,7 @@
+---
+interface Props { filename?: string; class?: string }
+const { filename, class: className } = Astro.props;
+---
+<div class:list={["code-block", className]} data-code-filename={filename}>
+  <slot />
+</div>

package/src/components/content/Gallery.astro

@@ -0,0 +1,57 @@
+---
+/* The caption is a string prop for the common case; a named `caption`
+   slot takes over when the caption needs markup (a link in an edit
+   aside, owner request 2026-08-27). */
+interface Props { columns?: number; caption?: string; class?: string }
+const { columns = 3, caption, class: className } = Astro.props;
+const hasCaptionSlot = Astro.slots.has("caption");
+---
+{/* Frame comes from the .bracket-frame pattern, same enclosure as the
+    article itself (owner request 2026-07-29). */}
+<figure class:list={["gallery-figure", className]}>
+  <div class:list={["gallery-plates", "bracket-frame", `gallery-cols-${columns}`]} style={`--gallery-cols:${columns}`}>
+    <slot />
+  </div>
+  {hasCaptionSlot ? (
+    <figcaption class="caption"><slot name="caption" /></figcaption>
+  ) : (
+    caption && <figcaption class="caption">{caption}</figcaption>
+  )}
+</figure>
+
+<style>
+  /* The figure wrapper exists so a gallery-level caption reads as part of
+     the gallery (owner request 2026-07-30); outer spacing lives here. */
+  .gallery-figure { margin: 20px 0; }
+  .gallery-plates {
+    display: grid;
+    grid-template-columns: repeat(var(--gallery-cols), 1fr);
+    gap: 12px;
+  }
+  @media (--bp-phone) { .gallery-plates { grid-template-columns: repeat(2, 1fr); } }
+  @media (max-width: 480px) { .gallery-plates { grid-template-columns: 1fr; } }
+  /* Type from the .caption pattern; centered under the plates like
+     BlogImage's. */
+  figcaption { margin-top: 5px; text-align: center; }
+  /* Orphan rule (owner request 2026-07-29): a lone plate on the last row
+     centers instead of hugging the left column. The :global() escape is
+     needed because plates are GalleryImage children, outside this
+     component's style scope. Keyed on the column count, since the nth
+     math differs per count; columns other than 2 and 3 get no rule. */
+  @media (--bp-phone-up) {
+    .gallery-cols-3 > :global(:nth-child(3n + 1):last-child) { grid-column: 2; }
+    .gallery-cols-2 > :global(:nth-child(odd):last-child) {
+      grid-column: 1 / -1;
+      justify-self: center;
+      width: calc(50% - 6px);
+    }
+  }
+  /* Below 768px every gallery is two columns, whatever it asked for. */
+  @media (min-width: 481px) and (--bp-phone) {
+    .gallery-plates > :global(:nth-child(odd):last-child) {
+      grid-column: 1 / -1;
+      justify-self: center;
+      width: calc(50% - 6px);
+    }
+  }
+</style>

package/src/components/content/GalleryImage.astro

@@ -0,0 +1,35 @@
+---
+import type { ImageMetadata } from "astro";
+import CornerBadges from "../CornerBadges.astro";
+import SmartImage from "../SmartImage.astro";
+import LightboxLink from "../LightboxLink.astro";
+
+/* `genai` marks an AI-generated plate with the AI Art corner badge
+   (CornerBadges.astro). */
+interface Props { src: ImageMetadata; alt?: string; caption?: string; genai?: boolean; class?: string }
+const { src, alt = "", caption, genai = false, class: className } = Astro.props;
+---
+<figure class:list={["gallery-plate", className]}>
+  <div class="plate-frame">
+    <LightboxLink href={src.src} w={src.width} h={src.height} caption={caption ?? alt}>
+      <SmartImage src={src} alt={alt} widths={[320, 640]} sizes="(max-width: 600px) 100vw, 320px" />
+      <CornerBadges genai={genai} />
+    </LightboxLink>
+  </div>
+  {caption && <figcaption class="caption">{caption}</figcaption>}
+</figure>
+
+<style>
+  .gallery-plate { margin: 0; }
+  .plate-frame { border: var(--stroke) solid var(--rule); line-height: 0; }
+  /* The frame owns the outline; zero the default img border from
+     prose.css so plates don't double-line. */
+  .plate-frame :global(img) { width: 100%; height: 220px; object-fit: cover; border: 0; }
+  /* Type from the .caption pattern, tracked a touch wider under a plate.
+     Caption case is the author's own; the uppercase transform from the
+     original plate design was dropped by owner request 2026-07-26. */
+  figcaption {
+    letter-spacing: 0.04em;
+    margin-top: 5px;
+  }
+</style>

package/src/components/content/Group.astro

@@ -0,0 +1,15 @@
+---
+/* Boxed prose container. Born in phase 1 as a bare passthrough (the
+   migration target for Gutenberg's Group block); styled 2026-08-21 to
+   match the style guide's description of it, as the label-less,
+   tint-less sibling of Callout's box. The box itself is the .rule-box
+   pattern; only the outer margin is this component's. */
+interface Props { class?: string }
+const { class: className } = Astro.props;
+---
+<div class:list={["content-group", "rule-box", className]}><slot /></div>
+
+<style>
+  .content-group { margin: 30px 0; }
+  .content-group > :global(:last-child) { margin-bottom: 0; }
+</style>

package/src/components/content/MediaText.astro

@@ -0,0 +1,60 @@
+---
+import type { ImageMetadata } from "astro";
+import CornerBadges from "../CornerBadges.astro";
+import SmartImage from "../SmartImage.astro";
+import LightboxLink from "../LightboxLink.astro";
+
+/* `genai` marks an AI-generated image with the AI Art corner badge
+   (CornerBadges.astro). */
+interface Props { src: ImageMetadata; alt?: string; mediaSide?: "left" | "right"; natural?: boolean; genai?: boolean; class?: string }
+const { src, alt = "", mediaSide = "left", natural = false, genai = false, class: className } = Astro.props;
+---
+<figure class:list={["media-text", mediaSide === "right" && "media-right", natural && "media-natural", className]}>
+  <div class="media-text-media">
+    <LightboxLink href={src.src} w={src.width} h={src.height} caption={alt}>
+      {natural
+        /* No responsive widths/sizes here: a `sizes` attribute makes the
+           browser report that size as the intrinsic width, which defeats
+           the natural-size rendering below. */
+        ? <SmartImage src={src} alt={alt} />
+        : <SmartImage src={src} alt={alt} widths={[480, 960]} sizes="(max-width: 600px) 100vw, 480px" />}
+      <CornerBadges genai={genai} />
+    </LightboxLink>
+  </div>
+  <figcaption class="media-text-content caption"><slot /></figcaption>
+</figure>
+
+<style>
+  .media-text {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    align-items: center;
+    margin: 20px 0;
+  }
+  .media-right .media-text-media { order: 2; }
+  .media-text-media { margin: 0; line-height: 0; }
+  /* The side text is the caption: type from the .caption pattern (owner
+     request 2026-08-14), left-aligned while it sits in its own column;
+     it centers only when stacked below. */
+  .media-text-content { text-align: left; }
+  .media-text-content :global(p) { margin: 0 0 0.5em; }
+  .media-text-content :global(p:last-child) { margin-bottom: 0; }
+  /* Outline comes from the .prose img standard in prose.css. */
+  .media-text-media :global(img) { width: 100%; height: auto; }
+  /* natural: opt-in for small diagrams and cartoons that look blown out
+     when stretched to the media column; renders at intrinsic size,
+     centered in the cell (owner request 2026-07-30). */
+  .media-natural .media-text-media { text-align: center; }
+  /* The link hugs the natural-size image so a corner badge lands on the
+     image, not the cell (same idiom as BlogImage). */
+  .media-natural .media-text-media :global(.lightbox-link) { width: fit-content; max-width: 100%; margin-inline: auto; }
+  .media-natural .media-text-media :global(img) { width: auto; max-width: 100%; }
+  @media (max-width: 600px) {
+    /* Stacked, the caption sits below the image like BlogImage's:
+       centered, hugging at the same 5px. */
+    .media-text { grid-template-columns: 1fr; gap: 5px; }
+    .media-right .media-text-media { order: 0; }
+    .media-text-content { text-align: center; }
+  }
+</style>

package/src/components/content/Palette.astro

@@ -0,0 +1,42 @@
+---
+/* Color-chip palette table, the treatment lifted from the BEADZ brand
+   page: bordered swatch, role, hex. Hand-authored-page component (the
+   migrator never emits it). Chip color is per-entry data, so it rides an
+   inline background-color, which the html-validate gate whitelists for
+   exactly this dynamic-value case. */
+interface Entry { role: string; hex: string; note?: string }
+interface Props { entries: Entry[]; class?: string }
+const { entries, class: className } = Astro.props;
+---
+<div class:list={["table-scroll", className]}>
+  <table class="palette">
+    <thead>
+      <tr>
+        <th><span class="screen-reader-text">Swatch</span></th>
+        <th>Role</th>
+        <th>Hex</th>
+        <th>Used for</th>
+      </tr>
+    </thead>
+    <tbody>
+      {entries.map((e) => (
+        <tr>
+          <td><span class="palette-chip" aria-hidden="true" style={`background-color:${e.hex}`}></span></td>
+          <td>{e.role}</td>
+          <td><code>{e.hex}</code></td>
+          <td>{e.note}</td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .palette-chip {
+    display: inline-block;
+    width: 18px;
+    height: 18px;
+    border: var(--stroke) solid var(--rule);
+    vertical-align: middle;
+  }
+</style>

package/src/components/content/Quote.astro

@@ -0,0 +1,21 @@
+---
+/* Attributed quote (spec 2026-08-14-quote-attribution-design.md).
+   Renders a plain blockquote so the boxed treatment in prose.css applies
+   unchanged; the provenance line is opt-in and most quotes should not
+   carry one (Nomenclature callouts and quotes already introduced by the
+   surrounding prose stay bare markdown). The tilde prefix stands in for
+   the traditional em dash, which is banned house-wide; the tilde is
+   already the site's separator (post titles). */
+interface Props { by?: string; when?: string; class?: string }
+const { by, when, class: className } = Astro.props;
+const attribution = [by, when].filter(Boolean).join(", ");
+---
+<blockquote class:list={[className]}>
+  <slot />
+  {attribution && <footer class="quote-attribution caption">~ {attribution}</footer>}
+</blockquote>
+
+<style>
+  /* Type from the .caption pattern, right-aligned under the quote. */
+  .quote-attribution { text-align: right; }
+</style>

package/src/components/content/Spacer.astro

@@ -0,0 +1,5 @@
+---
+interface Props { size?: number; class?: string }
+const { size = 40, class: className } = Astro.props;
+---
+<div aria-hidden="true" style={`height:${size}px`} class:list={["spacer", className]}></div>

package/src/components/content/Step.astro

@@ -0,0 +1,126 @@
+---
+import type { ImageMetadata } from "astro";
+import SmartImage from "../SmartImage.astro";
+import LightboxLink from "../LightboxLink.astro";
+
+/* One row of a Walkthrough (spec
+   docs/superpowers/specs/2026-08-15-walkthrough-steps-design.md): photo(s)
+   on the left at a fixed 200px per photo, the author's prose beside at body
+   size. The prose is the step's text, not a caption; alt feeds the lightbox
+   caption. Below 600px the row stacks, photo centered above the prose. */
+interface Photo { src: ImageMetadata; alt?: string }
+/* Exactly one of `src` (with `alt`) or `images`: the union says so to
+   typed callers; the runtime check below says so to MDX. */
+type Props = ({ src: ImageMetadata; images?: never } | { src?: never; images: Photo[] }) & {
+  alt?: string;
+  class?: string;
+};
+const { src, alt = "", images, class: className } = Astro.props;
+
+const hasSingle = src !== undefined;
+const hasMany = images !== undefined && images.length > 0;
+if (hasSingle === hasMany) {
+  throw new Error("Step: pass exactly one of `src` (with `alt`) or a non-empty `images` array");
+}
+const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
+---
+<li class:list={["step", className]}>
+  <div class="step-media">
+    {photos.map((p) => {
+      const a = p.alt ?? "";
+      return (
+        <LightboxLink href={p.src.src} w={p.src.width} h={p.src.height} caption={a}>
+          <SmartImage src={p.src} alt={a} widths={[200, Math.min(p.src.width, 400)]} sizes="200px" />
+        </LightboxLink>
+      );
+    })}
+  </div>
+  <div class="step-body"><slot /></div>
+</li>
+
+<style>
+  .step {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: 20px;
+    align-items: start;
+    /* prose.css pads every .prose li; rows space themselves via
+       the Walkthrough gap instead. */
+    padding: 0;
+    counter-increment: walkthrough-step;
+  }
+  /* Photos sit in a row, one 200px track each, so a two-photo step's cell
+     is 410px and its prose starts further right (owner pick M3). The row
+     does not wrap, so two photos is the practical cap for the 990px
+     prose column: three still fits, four is 830px, five overflows. */
+  .step-media {
+    position: relative;
+    display: grid;
+    grid-auto-flow: column;
+    grid-auto-columns: 200px;
+    gap: 10px;
+    line-height: 0;
+  }
+  /* The 2px outline comes from .prose img in prose.css. */
+  .step-media :global(img) { width: 100%; height: auto; }
+  /* The body is 1fr of the layout's column; nothing here narrows it. */
+  .step-body { min-width: 0; }
+  .step-body :global(p:last-child) { margin-bottom: 0; }
+
+  /* Number chip (owner pick B2): a 28px filled square riding the media
+     cell's top-left corner, half outside the frame so it never covers the
+     photo. The 14px margins reserve its overhang on every step of a
+     numbered walkthrough, chip or not, so rows stay aligned. Decorative:
+     the <ol> already carries list position for assistive tech. Whether
+     the chip shows is the parent's call: Walkthrough sets
+     --step-chip-display and --step-media-margin on its numbered variant
+     (step 5 replaced the :global(.walkthrough-numbered) parent-read). */
+  /* stylelint-disable-next-line no-duplicate-selectors -- split from the
+     grid rule above so the contract stays grouped with its own comment. */
+  .step-media { margin: var(--step-media-margin, 0); }
+  .step-media::before {
+    content: counter(walkthrough-step);
+    display: var(--step-chip-display, none);
+    position: absolute;
+    top: -14px;
+    left: -14px;
+    z-index: 1;
+    width: 28px;
+    height: 28px;
+    align-items: center;
+    justify-content: center;
+    background: var(--ink);
+    color: var(--on-ink);
+    font-family: var(--font-body);
+    font-size: 14px;
+    font-weight: 700;
+    line-height: 1;
+  }
+
+  /* Tablets and phone-landscape (2026-08-16 fix wave): between 600px and
+     about 780px a two-photo cell is still a hard 410px, which leaves the
+     prose a 140-310px ribbon while the row is still two-column. Owner pick
+     M3 keeps the row layout above 800px, so stack the media cell's photos
+     here without touching the row itself; the 600px rules below still take
+     over the row layout and stay unchanged. */
+  @media (max-width: 800px) {
+    .step-media {
+      grid-auto-flow: row;
+      grid-auto-columns: auto;
+      grid-template-columns: 200px;
+    }
+  }
+
+  /* Phones (owner pick P2): stack, photo centered above the prose, photos
+     of a multi-photo step stacking too. Same breakpoint as MediaText. */
+  @media (max-width: 600px) {
+    .step { grid-template-columns: 1fr; gap: 10px; }
+    .step-media {
+      grid-auto-flow: row;
+      grid-auto-columns: auto;
+      grid-template-columns: 200px;
+      justify-self: center;
+      margin: var(--step-media-margin-stacked, 0);
+    }
+  }
+</style>

package/src/components/content/Walkthrough.astro

@@ -0,0 +1,42 @@
+---
+/* Step-by-step photo walkthrough (spec
+   docs/superpowers/specs/2026-08-15-walkthrough-steps-design.md): an ordered
+   list of Step rows. Every photo inside forms one lightbox set; lightbox.ts
+   setFor() keys on the .walkthrough class, so keep it on the <ol>. */
+interface Props { numbered?: boolean; class?: string }
+const { numbered = false, class: className } = Astro.props;
+---
+{/* list-style: none drops the implicit list role in Safari/VoiceOver, so
+   role="list" restores it. html-validate's no-redundant-role and
+   prefer-native-element both flag that as unnecessary on a native <ol>,
+   which is true generically but wrong for this specific case; disabled
+   surgically for this element only. */}
+<!-- [html-validate-disable-next no-redundant-role, prefer-native-element] -->
+<ol class:list={["walkthrough", numbered && "walkthrough-numbered", className]} role="list">
+  <slot />
+</ol>
+
+<style>
+  /* List semantics without list styling. prose.css gives .prose ol
+     a left margin, indent, and decimal markers; the corner chip in Step is
+     the only visible number, and only when numbered. */
+  .walkthrough {
+    list-style: none;
+    margin: 20px 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 22px;
+    counter-reset: walkthrough-step;
+  }
+
+  /* The numbered variant's contract with Step (step 5): custom
+     properties instead of a :global parent-read. Inherited by every
+     slotted Step; un-numbered walkthroughs leave the defaults (no chip,
+     no reserved margin). */
+  .walkthrough-numbered {
+    --step-chip-display: flex;
+    --step-media-margin: 14px 0 0 14px;
+    --step-media-margin-stacked: 14px 0 0;
+  }
+</style>