@contentrain/astro-kit 0.1.0

package/components/nav/fixtures.json

@@ -0,0 +1,80 @@
+[
+  {
+    "name": "popover",
+    "props": {
+      "id": "fx-nav-a",
+      "items": [
+        {
+          "label": "Journal",
+          "href": "/"
+        },
+        {
+          "label": "Services",
+          "href": "/services/",
+          "children": [
+            {
+              "label": "Design",
+              "href": "/services/design/"
+            },
+            {
+              "label": "Engineering",
+              "href": "/services/engineering/"
+            }
+          ]
+        },
+        {
+          "label": "About",
+          "href": "/about/"
+        },
+        {
+          "label": "Contact",
+          "href": "/contact/"
+        }
+      ]
+    }
+  },
+  {
+    "name": "details-start",
+    "props": {
+      "id": "fx-nav-b",
+      "mobile": "details",
+      "align": "start",
+      "density": "comfortable",
+      "items": [
+        {
+          "label": "Home",
+          "href": "/"
+        },
+        {
+          "label": "Blog",
+          "href": "/blog/"
+        },
+        {
+          "label": "Contact",
+          "href": "/contact/"
+        }
+      ]
+    }
+  },
+  {
+    "name": "center",
+    "props": {
+      "id": "fx-nav-c",
+      "align": "center",
+      "items": [
+        {
+          "label": "Work",
+          "href": "/work/"
+        },
+        {
+          "label": "Studio",
+          "href": "/studio/"
+        },
+        {
+          "label": "Journal",
+          "href": "/journal/"
+        }
+      ]
+    }
+  }
+]

package/components/nav/meta.json

@@ -0,0 +1,30 @@
+{
+  "id": "nav",
+  "name": "Navigation",
+  "description": "Site navigation: an inline list with hover/focus submenus on wide screens and a toggle on narrow ones that opens a native popover drawer or a <details> dropdown. No JavaScript.",
+  "category": "chrome",
+  "uses": [],
+  "shared": ["types.ts"],
+  "variants": {
+    "mobile": { "options": ["popover", "details"], "default": "popover", "description": "Narrow-screen menu: a side drawer (Popover API) or a dropdown under the toggle." },
+    "align": { "options": ["start", "end", "center"], "default": "end", "description": "Horizontal alignment of the inline list." },
+    "density": { "options": ["compact", "comfortable"], "default": "compact", "description": "Gap and text size of the inline list." }
+  },
+  "props": {
+    "items": { "type": "array", "required": true, "items": { "type": "object", "fields": { "label": { "type": "string", "required": true }, "href": { "type": "url", "required": true }, "newTab": { "type": "boolean" }, "children": { "type": "array" } } }, "description": "Menu entries; one level of children is shown." },
+    "label": { "type": "string", "description": "Accessible name of the navigation landmark (ui-strings nav.label)." },
+    "menuLabel": { "type": "string", "description": "Text of the narrow-screen toggle (ui-strings nav.menu)." },
+    "closeLabel": { "type": "string", "description": "Text of the drawer's close button (ui-strings nav.close)." },
+    "id": { "type": "string", "description": "Unique id when a page renders two navigations." }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": ["core/navigation", "core/page-list"],
+    "elementor": ["elementor/nav-menu"],
+    "divi": ["divi/et_pb_menu", "divi/et_pb_fullwidth_menu"],
+    "classic": ["classic/nav-menu"]
+  },
+  "a11y": "A <nav> landmark with a label; the current page carries aria-current. Submenus open on :focus-within as well as hover. The drawer is a native popover: Escape and light dismiss close it and focus returns to the toggle."
+}

package/components/pagination/Pagination.astro

@@ -0,0 +1,69 @@
+---
+// Links between the pages of a list. Addresses follow WordPress — the list
+// itself for page 1, `<base>page/<n>/` after — so a migrated archive keeps
+// its page URLs.
+import { tv } from 'tailwind-variants'
+
+const pagination = tv({
+  slots: {
+    root: 'mt-12 flex flex-wrap items-center gap-1',
+    item: 'inline-flex min-w-8 items-center justify-center gap-1.5 rounded-md px-2 py-2 text-sm no-underline sm:min-w-10 sm:px-3',
+    link: 'text-ink hover:bg-surface-muted',
+    current: 'bg-ink font-semibold text-surface',
+  },
+  variants: {
+    style: {
+      numbered: {},
+      simple: { root: 'justify-between' },
+    },
+    align: { start: {}, center: {}, end: {} },
+  },
+  compoundVariants: [
+    { style: 'numbered', align: 'start', class: { root: 'justify-start' } },
+    { style: 'numbered', align: 'center', class: { root: 'justify-center' } },
+    { style: 'numbered', align: 'end', class: { root: 'justify-end' } },
+  ],
+  defaultVariants: { style: 'numbered', align: 'center' },
+})
+
+interface Props {
+  /** The list's first-page address, e.g. `/category/news/`. */
+  base: string
+  current: number
+  total: number
+  /** Accessible name of the navigation ("Pagination"). */
+  label?: string | undefined
+  prevLabel?: string | undefined
+  nextLabel?: string | undefined
+  /** Word read before a page number ("Page"). */
+  pageLabel?: string | undefined
+  style?: 'numbered' | 'simple' | undefined
+  align?: 'start' | 'center' | 'end' | undefined
+}
+
+const { base, current, total, label = 'Pagination', prevLabel = 'Previous', nextLabel = 'Next', pageLabel = 'Page', style = 'numbered', align } = Astro.props
+const slots = pagination({ style, align })
+const href = (page: number) => (page <= 1 ? base : `${base}page/${page}/`)
+// First, last and two either side of the current page; gaps become an ellipsis.
+const shown = [...new Set([1, current - 2, current - 1, current, current + 1, current + 2, total])]
+  .filter(page => page >= 1 && page <= total)
+  .toSorted((a, b) => a - b)
+---
+{total > 1 && (
+  <nav aria-label={label} class={slots.root()}>
+    {current > 1
+      ? <a href={href(current - 1)} rel="prev" class:list={[slots.item(), slots.link()]}><span aria-hidden="true">←</span> <span class="max-sm:sr-only">{prevLabel}</span></a>
+      : style === 'simple' && <span />}
+    {style === 'numbered' && shown.map((page, index) => (
+      <>
+        {index > 0 && page - shown[index - 1]! > 1 && <span class:list={[slots.item(), 'text-ink-muted']} aria-hidden="true">…</span>}
+        {/* Two away from the current page: dropped on phones so the row fits one line. */}
+        {page === current
+          ? <span aria-current="page" class:list={[slots.item(), slots.current()]}><span class="sr-only">{pageLabel} </span>{page}</span>
+          : <a href={href(page)} class:list={[slots.item(), slots.link(), Math.abs(page - current) === 2 && page !== 1 && page !== total && 'max-md:hidden']}><span class="sr-only">{pageLabel} </span>{page}</a>}
+      </>
+    ))}
+    {style === 'simple' && <span class="text-sm text-ink-muted">{pageLabel} {current} / {total}</span>}
+    {current < total && <a href={href(current + 1)} rel="next" class:list={[slots.item(), slots.link()]}><span class="max-sm:sr-only">{nextLabel}</span> <span aria-hidden="true">→</span></a>}
+  </nav>
+)}

package/components/pagination/fixtures.json

@@ -0,0 +1,6 @@
+[
+  { "name": "numbered-middle", "props": { "base": "/blog/", "current": 5, "total": 12 } },
+  { "name": "simple", "props": { "base": "/blog/", "current": 2, "total": 3, "style": "simple" } },
+  { "name": "numbered-start", "props": { "base": "/tag/astro/", "current": 1, "total": 3, "align": "start" } },
+  { "name": "numbered-end", "props": { "base": "/tag/astro/", "current": 3, "total": 3, "align": "end" } }
+]

package/components/pagination/meta.json

@@ -0,0 +1,31 @@
+{
+  "id": "pagination",
+  "name": "Pagination",
+  "description": "Links between the pages of a post list, at WordPress addresses (<base>page/<n>/).",
+  "category": "content",
+  "uses": [],
+  "shared": [],
+  "variants": {
+    "style": { "options": ["numbered", "simple"], "default": "numbered", "description": "Numbered pages with ellipses, or previous/next with 'Page n / m'." },
+    "align": { "options": ["start", "center", "end"], "default": "center", "description": "Alignment of the numbered style." }
+  },
+  "props": {
+    "base": { "type": "string", "required": true, "description": "The list's first-page address, ending in a slash." },
+    "current": { "type": "integer", "required": true, "min": 1, "description": "Current page number." },
+    "total": { "type": "integer", "required": true, "min": 1, "description": "Number of pages; nothing renders when it is 1." },
+    "label": { "type": "string", "description": "Accessible name (ui-strings pagination.label)." },
+    "prevLabel": { "type": "string", "description": "ui-strings pagination.prev." },
+    "nextLabel": { "type": "string", "description": "ui-strings pagination.next." },
+    "pageLabel": { "type": "string", "description": "ui-strings pagination.page." }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": ["core/query-pagination"],
+    "elementor": ["elementor/posts:pagination"],
+    "divi": ["divi/et_pb_blog:pagination"],
+    "classic": ["classic/pagination"]
+  },
+  "a11y": "A labelled <nav>; the current page is aria-current=page; prev/next carry rel. Numbers are prefixed with a visually hidden 'Page'."
+}

package/components/post-card/PostCard.astro

@@ -0,0 +1,67 @@
+---
+// One post in a list: image, category, date, title, excerpt and author. The
+// whole card is clickable through its title link.
+import { tv } from 'tailwind-variants'
+import KitImage from '../_shared/KitImage.astro'
+import type { ImageInput, LinkInput } from '../_shared/types'
+
+const card = tv({
+  slots: {
+    root: 'group relative flex gap-4',
+    media: 'shrink-0 overflow-hidden rounded-[var(--radius-card)]',
+    body: 'flex min-w-0 flex-col gap-2',
+    meta: 'flex flex-wrap items-center gap-x-2 text-sm text-ink-muted',
+    title: 'leading-snug font-semibold text-balance text-ink',
+    excerpt: 'text-ink-muted',
+  },
+  variants: {
+    layout: {
+      vertical: { root: 'flex-col', media: 'w-full', title: 'text-xl', excerpt: 'line-clamp-3' },
+      horizontal: { root: 'flex-col sm:flex-row sm:items-start', media: 'w-full sm:w-64', title: 'text-xl', excerpt: 'line-clamp-2' },
+      minimal: { root: 'flex-col border-b border-line pb-5', media: 'hidden', title: 'text-lg', excerpt: 'line-clamp-2' },
+    },
+  },
+  defaultVariants: { layout: 'vertical' },
+})
+
+interface Props {
+  title: string
+  href: string
+  excerpt?: string | undefined
+  /** Publication date: a Date, or ISO 8601 text as Contentrain stores it. */
+  date?: Date | string | undefined
+  /** BCP 47 locale the date is written in (site.language). */
+  locale?: string | undefined
+  image?: ImageInput | undefined
+  category?: LinkInput | undefined
+  author?: string | undefined
+  headingLevel?: 2 | 3 | undefined
+  layout?: 'vertical' | 'horizontal' | 'minimal' | undefined
+}
+
+const { title, href, excerpt, date: rawDate, locale = 'en', image, category, author, headingLevel = 2, layout } = Astro.props
+const date = rawDate === undefined ? undefined : new Date(rawDate)
+const slots = card({ layout })
+const Heading = `h${headingLevel}` as 'h2' | 'h3'
+---
+<article class={slots.root()}>
+  {image && layout !== 'minimal' && (
+    <div class={slots.media()}>
+      <KitImage image={image} sizes={layout === 'horizontal' ? '256px' : '(min-width: 1024px) 360px, 100vw'} class="aspect-[16/9] w-full object-cover transition duration-300 group-hover:scale-[1.02]" />
+    </div>
+  )}
+  <div class={slots.body()}>
+    {(category || date) && (
+      <p class={slots.meta()}>
+        {category && <a href={category.href} class="relative z-10 font-medium text-accent no-underline hover:underline">{category.label}</a>}
+        {category && date && <span aria-hidden="true">·</span>}
+        {date && <time datetime={date.toISOString()}>{date.toLocaleDateString(locale, { dateStyle: 'long', timeZone: 'UTC' })}</time>}
+      </p>
+    )}
+    <Heading class={slots.title()}>
+      <a href={href} class="text-current no-underline after:absolute after:inset-0 after:content-[''] hover:text-accent">{title}</a>
+    </Heading>
+    {excerpt && <p class={slots.excerpt()}>{excerpt}</p>}
+    {author && <p class="text-sm text-ink-muted">{author}</p>}
+  </div>
+</article>

package/components/post-card/fixtures.json

@@ -0,0 +1,54 @@
+[
+  {
+    "name": "vertical",
+    "props": {
+      "title": "What a careful migration keeps",
+      "href": "/blog/what-a-careful-migration-keeps/",
+      "excerpt": "Addresses, formatting and rankings: what a careful WordPress to Astro migration keeps, block by block.",
+      "date": "2026-09-28T09:00:00Z",
+      "category": {
+        "label": "Guides",
+        "href": "/category/guides/"
+      },
+      "author": "Mira Kovač",
+      "image": {
+        "src": "/kit-fixtures/photo-1.svg",
+        "alt": "",
+        "width": 1200,
+        "height": 800
+      }
+    },
+    "frame": "narrow"
+  },
+  {
+    "name": "horizontal",
+    "props": {
+      "layout": "horizontal",
+      "title": "Designing with fewer requests",
+      "href": "/blog/designing-with-fewer-requests/",
+      "excerpt": "One stylesheet, no runtime, images sized at build time.",
+      "date": "2026-09-26T09:00:00Z",
+      "image": {
+        "src": "/kit-fixtures/photo-2.svg",
+        "alt": "",
+        "width": 1200,
+        "height": 800
+      }
+    }
+  },
+  {
+    "name": "minimal",
+    "props": {
+      "layout": "minimal",
+      "headingLevel": 3,
+      "title": "Redirects: the unglamorous hero",
+      "href": "/blog/redirects/",
+      "excerpt": "Keep every address. Redirect the ones you cannot keep.",
+      "date": "2026-09-16T09:00:00Z",
+      "category": {
+        "label": "News",
+        "href": "/category/news/"
+      }
+    }
+  }
+]

package/components/post-card/meta.json

@@ -0,0 +1,32 @@
+{
+  "id": "post-card",
+  "name": "Post card",
+  "description": "One post in a list (index, archive, related posts): image, category, date, title, excerpt, author. The whole card links to the post.",
+  "category": "content",
+  "uses": [],
+  "shared": ["KitImage.astro", "types.ts"],
+  "variants": {
+    "layout": { "options": ["vertical", "horizontal", "minimal"], "default": "vertical", "description": "Image on top, image beside the text, or text only with a divider." }
+  },
+  "props": {
+    "title": { "type": "string", "required": true, "description": "Post title (posts.title)." },
+    "href": { "type": "url", "required": true, "description": "Post address (from the permalink pattern)." },
+    "excerpt": { "type": "text", "description": "Summary (posts.excerpt)." },
+    "date": { "type": "datetime", "description": "Publication date (posts.published_at)." },
+    "locale": { "type": "string", "description": "Locale the date is written in (site.language)." },
+    "image": { "type": "object", "fields": { "src": { "type": "image", "required": true }, "alt": { "type": "string", "required": true }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "Cover (posts.cover → media)." },
+    "category": { "type": "object", "fields": { "label": { "type": "string", "required": true }, "href": { "type": "url", "required": true } }, "description": "Primary category and its archive." },
+    "author": { "type": "string", "description": "Author name (posts.author → authors.name)." },
+    "headingLevel": { "type": "integer", "min": 2, "max": 3, "default": 2, "description": "Title heading level in the page outline." }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": ["core/query", "core/post-template", "core/latest-posts"],
+    "elementor": ["elementor/posts", "elementor/archive-posts"],
+    "divi": ["divi/et_pb_blog"],
+    "classic": ["classic/archive-item"]
+  },
+  "a11y": "An <article> with one link (the title), stretched over the card; the category link sits above it and stays separately focusable. Dates are <time datetime>."
+}

package/components/prose/Prose.astro

@@ -0,0 +1,30 @@
+---
+// A rich-text body as the editor wrote it. A migrated post keeps the markup
+// WordPress rendered — `wp-block-*` classes, alignments, preset colors — and
+// is styled by Tailwind Typography bound to the site's tokens (`prose-site`)
+// plus the Gutenberg block styles in the starter's styles/wp-blocks.css. The
+// body is the site's own content from its own repository, so it is rendered
+// as HTML. Only post and page bodies carry `data-pagefind-body`, so search
+// indexes content, not chrome.
+import { tv } from 'tailwind-variants'
+
+const prose = tv({
+  base: 'prose prose-site max-w-none',
+  variants: {
+    size: { base: 'prose-base', lg: 'prose-lg' },
+  },
+  defaultVariants: { size: 'lg' },
+})
+
+interface Props {
+  /** Rendered HTML of a richtext field. */
+  html: string
+  /** Index this body for site search. */
+  searchable?: boolean | undefined
+  class?: string | undefined
+  size?: 'base' | 'lg' | undefined
+}
+
+const { html, searchable = true, class: className, size } = Astro.props
+---
+<div class={prose({ size, class: className })} data-pagefind-body={searchable ? '' : undefined} set:html={html} />

package/components/prose/fixtures.json

@@ -0,0 +1,4 @@
+[
+  { "name": "lg", "frame": "narrow", "props": { "html": "<h2 class=\"wp-block-heading\">Keeping what works</h2><p>A careful migration keeps <strong>addresses</strong>, <a href=\"/about/\">formatting</a> and rankings.</p><ul class=\"wp-block-list\"><li>Permalinks stay put.</li><li>Archives survive.</li></ul><blockquote class=\"wp-block-quote\"><p>The fastest request is the one the server never has to think about.</p><cite>Every performance engineer</cite></blockquote><div class=\"wp-block-buttons is-layout-flex\"><div class=\"wp-block-button\"><a class=\"wp-block-button__link wp-element-button\" href=\"/contact/\">Get in touch</a></div></div>" } },
+  { "name": "base", "frame": "narrow", "props": { "size": "base", "searchable": false, "html": "<p class=\"has-drop-cap\">Moving a WordPress site to a static stack is mostly about keeping what already works.</p><figure class=\"wp-block-table is-style-stripes\"><table><thead><tr><th>Metric</th><th>Before</th><th>After</th></tr></thead><tbody><tr><td>Requests</td><td>84</td><td>9</td></tr><tr><td>LCP</td><td>3.1 s</td><td>0.8 s</td></tr></tbody></table></figure>" } }
+]

package/components/prose/meta.json

@@ -0,0 +1,69 @@
+{
+  "id": "prose",
+  "name": "Prose",
+  "description": "A rich-text body (post or page content) rendered as the editor wrote it: WordPress block markup kept, styled by Tailwind Typography on the site's tokens and the starter's Gutenberg block styles. The fallback for every builder element no rule maps to a component. Container blocks (core/group, core/columns) are not sources: their children are matched instead. Needs the starter's global.css (prose-site utility, wp-blocks.css).",
+  "category": "content",
+  "uses": [],
+  "shared": [],
+  "variants": {
+    "size": {
+      "options": [
+        "base",
+        "lg"
+      ],
+      "default": "lg",
+      "description": "Type scale of the body."
+    }
+  },
+  "props": {
+    "html": {
+      "type": "richtext",
+      "required": true,
+      "description": "Rendered HTML of a richtext field (posts.body, pages.body)."
+    },
+    "searchable": {
+      "type": "boolean",
+      "default": true,
+      "description": "Mark the body for the site search index (data-pagefind-body)."
+    }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {
+    "gutenberg": [
+      "core/paragraph",
+      "core/heading",
+      "core/list",
+      "core/list-item",
+      "core/quote",
+      "core/pullquote",
+      "core/image",
+      "core/table",
+      "core/code",
+      "core/preformatted",
+      "core/verse",
+      "core/separator",
+      "core/spacer",
+      "core/embed",
+      "core/video",
+      "core/audio",
+      "core/file",
+      "core/html",
+      "core/freeform",
+      "core/post-content"
+    ],
+    "elementor": [
+      "elementor/text-editor",
+      "elementor/theme-post-content"
+    ],
+    "divi": [
+      "divi/et_pb_text",
+      "divi/et_pb_post_content"
+    ],
+    "classic": [
+      "classic/the-content"
+    ]
+  },
+  "a11y": "Keeps the author's heading levels and list/table semantics; embedded media keep their own titles and captions. Block styles give focus-visible links and readable measure."
+}

package/components/slider/Slider.astro

@@ -0,0 +1,136 @@
+---
+// A carousel of images with optional captions. Without JavaScript it is a
+// horizontally scrolling, snapping row — every slide is reachable. With it,
+// Embla turns the row into a paged carousel with previous/next buttons and
+// slide dots.
+import { tv } from 'tailwind-variants'
+import Button from '../_shared/Button.astro'
+import KitImage from '../_shared/KitImage.astro'
+import type { ActionInput, ImageInput } from '../_shared/types'
+
+const slider = tv({
+  slots: {
+    viewport: 'flex snap-x snap-mandatory gap-4 overflow-x-auto scroll-smooth group-data-[ready]:snap-none group-data-[ready]:overflow-hidden [scrollbar-width:none]',
+    slide: 'relative min-w-0 shrink-0 snap-start overflow-hidden',
+    image: 'w-full object-cover',
+    caption: 'flex flex-col items-start gap-2',
+  },
+  variants: {
+    perView: {
+      '1': { slide: 'basis-full' },
+      '2': { slide: 'basis-[85%] sm:basis-[calc(50%-0.5rem)]' },
+      '3': { slide: 'basis-[85%] sm:basis-[calc(50%-0.5rem)] lg:basis-[calc(33.333%-0.667rem)]' },
+    },
+    aspect: {
+      wide: { image: 'aspect-[4/3] md:aspect-[21/9]' },
+      standard: { image: 'aspect-[3/2]' },
+      square: { image: 'aspect-square' },
+    },
+    caption: {
+      below: { image: 'rounded-[var(--radius-card)]', caption: 'pt-4' },
+      // Over the image on wide screens; under it on phones, where the image is too short to hold text.
+      overlay: { image: 'rounded-[var(--radius-card)] md:rounded-none', slide: 'md:rounded-[var(--radius-card)]', caption: 'pt-4 md:absolute md:inset-x-0 md:bottom-0 md:bg-gradient-to-t md:from-ink/80 md:to-transparent md:p-6 md:pt-16 md:text-surface' },
+    },
+  },
+  defaultVariants: { perView: '1', aspect: 'wide', caption: 'overlay' },
+})
+
+interface Slide {
+  image: ImageInput
+  title?: string | undefined
+  text?: string | undefined
+  action?: ActionInput | undefined
+}
+
+interface Props {
+  slides: Slide[]
+  /** Accessible name of the carousel ("Featured projects"). */
+  label: string
+  prevLabel?: string | undefined
+  nextLabel?: string | undefined
+  /** Word before a slide number in dot labels and slide names ("Slide"). */
+  slideLabel?: string | undefined
+  /** Word between a slide number and the count ("of"). */
+  ofLabel?: string | undefined
+  loop?: boolean | undefined
+  perView?: '1' | '2' | '3' | undefined
+  aspect?: 'wide' | 'standard' | 'square' | undefined
+  caption?: 'below' | 'overlay' | undefined
+}
+
+const { slides, label, prevLabel = 'Previous slide', nextLabel = 'Next slide', slideLabel = 'Slide', ofLabel = 'of', loop = false, perView = '1', aspect, caption } = Astro.props
+const slots = slider({ perView, aspect, caption })
+const sizes = perView === '1' ? '(min-width: 1216px) 1152px, 100vw' : perView === '2' ? '(min-width: 640px) 50vw, 85vw' : '(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 85vw'
+// Arrows from sm up; on phones the carousel is swiped and the dots show the position.
+const arrow = 'absolute top-1/2 z-10 hidden size-11 -translate-y-1/2 items-center justify-center rounded-full bg-surface/90 text-ink shadow-md ring-1 ring-line hover:bg-surface disabled:opacity-40 sm:group-data-[ready]:flex'
+---
+<section class="group container-page relative py-8" aria-roledescription="carousel" aria-label={label} data-kit-slider data-loop={loop ? '' : undefined} data-slide-label={slideLabel}>
+  <div class={slots.viewport()} data-viewport>
+    <div class="flex gap-4 [&>*]:shrink-0 group-data-[ready]:[&>*]:snap-align-none" data-container>
+      {slides.map((slide, index) => (
+        <div class={slots.slide()} role="group" aria-roledescription="slide" aria-label={`${slideLabel} ${index + 1} ${ofLabel} ${slides.length}`}>
+          <KitImage image={slide.image} sizes={sizes} priority={index === 0} class={slots.image()} />
+          {(slide.title || slide.text || slide.action) && (
+            <div class={slots.caption()}>
+              {slide.title && <p class="text-xl font-semibold text-balance">{slide.title}</p>}
+              {slide.text && <p class="opacity-85">{slide.text}</p>}
+              {slide.action && <Button action={slide.action} size="sm" class="mt-2" />}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  </div>
+  {slides.length > 1 && (
+    <>
+      <button type="button" class:list={[arrow, 'left-6 md:left-10']} aria-label={prevLabel} data-prev>
+        <svg aria-hidden="true" viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2"><path d="M15 18l-6-6 6-6" /></svg>
+      </button>
+      <button type="button" class:list={[arrow, 'right-6 md:right-10']} aria-label={nextLabel} data-next>
+        <svg aria-hidden="true" viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 6l6 6-6 6" /></svg>
+      </button>
+      <div class="mt-4 hidden justify-center group-data-[ready]:flex" data-dots></div>
+    </>
+  )}
+</section>
+
+<script>
+  import EmblaCarousel from 'embla-carousel'
+
+  for (const root of document.querySelectorAll<HTMLElement>('[data-kit-slider]')) {
+    const viewport = root.querySelector<HTMLElement>('[data-viewport]')
+    if (!viewport || root.dataset.ready !== undefined) continue
+    root.dataset.ready = ''
+    // Reduced motion: slides change instantly instead of gliding.
+    const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches
+    const embla = EmblaCarousel(viewport, { loop: root.dataset.loop !== undefined, align: 'start', containScroll: 'trimSnaps', duration: reduce ? 0 : 25 })
+    const prev = root.querySelector<HTMLButtonElement>('[data-prev]')
+    const next = root.querySelector<HTMLButtonElement>('[data-next]')
+    const dots = root.querySelector<HTMLElement>('[data-dots]')
+    prev?.addEventListener('click', () => embla.scrollPrev())
+    next?.addEventListener('click', () => embla.scrollNext())
+
+    const label = root.dataset.slideLabel ?? 'Slide'
+    const buttons = embla.scrollSnapList().map((_, index) => {
+      const dot = document.createElement('button')
+      dot.type = 'button'
+      // A 24px target around a 10px dot (WCAG 2.5.8): on phones the dots are the only controls.
+      dot.className = 'group/dot grid size-6 place-items-center rounded-full'
+      const mark = document.createElement('span')
+      mark.className = 'size-2.5 rounded-full bg-ink/25 group-aria-[current=true]/dot:bg-ink'
+      dot.append(mark)
+      dot.setAttribute('aria-label', `${label} ${index + 1}`)
+      dot.addEventListener('click', () => embla.scrollTo(index))
+      dots?.append(dot)
+      return dot
+    })
+    const sync = () => {
+      const selected = embla.selectedScrollSnap()
+      buttons.forEach((dot, index) => dot.setAttribute('aria-current', String(index === selected)))
+      if (prev) prev.disabled = !embla.canScrollPrev()
+      if (next) next.disabled = !embla.canScrollNext()
+    }
+    embla.on('select', sync).on('reInit', sync)
+    sync()
+  }
+</script>

package/components/slider/fixtures.json

@@ -0,0 +1,5 @@
+[
+  { "name": "single-wide-overlay", "props": { "label": "Featured work", "slides": [{ "image": { "src": "/kit-fixtures/photo-1.svg", "alt": "Blue gradient", "width": 1200, "height": 800 }, "title": "Northwind Journal", "text": "A WordPress blog moved to Astro in an afternoon.", "action": { "label": "Read the case", "href": "/work/northwind/" } }, { "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "Green gradient", "width": 1200, "height": 800 }, "title": "Harbor & Co" }, { "image": { "src": "/kit-fixtures/photo-3.svg", "alt": "Orange gradient", "width": 1200, "height": 800 }, "title": "Field Notes" }] } },
+  { "name": "two-standard-below", "props": { "label": "Gallery", "perView": "2", "aspect": "standard", "caption": "below", "loop": true, "slides": [{ "image": { "src": "/kit-fixtures/photo-4.svg", "alt": "", "width": 1200, "height": 800 }, "title": "Studio" }, { "image": { "src": "/kit-fixtures/photo-5.svg", "alt": "", "width": 1200, "height": 800 }, "title": "Workshop" }, { "image": { "src": "/kit-fixtures/photo-6.svg", "alt": "", "width": 1200, "height": 800 }, "title": "Garden" }] } },
+  { "name": "three-square", "props": { "label": "Team", "perView": "3", "aspect": "square", "slides": [{ "image": { "src": "/kit-fixtures/avatar-1.svg", "alt": "Mira", "width": 96, "height": 96 } }, { "image": { "src": "/kit-fixtures/avatar-2.svg", "alt": "Jon", "width": 96, "height": 96 } }, { "image": { "src": "/kit-fixtures/avatar-3.svg", "alt": "Lea", "width": 96, "height": 96 } }, { "image": { "src": "/kit-fixtures/photo-1.svg", "alt": "Studio", "width": 1200, "height": 800 } }] } }
+]