@moonarc/core 0.1.0

package/src/components/BrowserFrame.astro

@@ -0,0 +1,172 @@
+---
+/**
+ * BrowserFrame — a browser window around a screenshot or any content: the
+ * three lights, an address bar, optional tabs with one active. Static and
+ * zero JS; the chrome scales with the frame's own width through container
+ * query units, and every colour is a theme token, so `theme="dark"` or
+ * "light" pins one look and "auto" follows the page. Pass `src` (an
+ * imported image or a URL) for a screenshot, or put anything in the slot.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import type { ImageMetadata } from 'astro';
+import { Image } from 'astro:assets';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Shown in the address bar. */
+  url?: string;
+  /** Tab labels; `active` is the index that is selected. */
+  tabs?: string[];
+  active?: number;
+  theme?: 'light' | 'dark' | 'auto';
+  /** A screenshot: an imported image (optimised by Astro) or a plain URL. */
+  src?: ImageMetadata | string;
+  alt?: string;
+  /** Corner radius, any CSS length. */
+  radius?: string;
+}
+
+const { url = 'https://example.com', tabs, active = 0, theme = 'auto', src, alt = '', radius = '0.75rem', class: className, style, ...rest } = Astro.props;
+const host = url.replace(/^https?:\/\//, '');
+const secure = /^https:\/\//.test(url) || !/^https?:\/\//.test(url);
+const vars = [`--ma-browser-r:${radius}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-browser', className]} data-theme={theme === 'auto' ? undefined : theme} style={vars} {...rest}>
+  <div class="ma-browser__bar" aria-hidden="true">
+    <span class="ma-browser__lights"><i></i><i></i><i></i></span>
+    {tabs && tabs.length > 0 && (
+      <span class="ma-browser__tabs">
+        {tabs.map((t, i) => <span class="ma-browser__tab" data-active={i === active ? '' : undefined}>{t}</span>)}
+      </span>
+    )}
+    <span class="ma-browser__url">
+      <svg viewBox="0 0 16 16" class="ma-browser__lock">{secure ? <path d="M4.5 7V5.5a3.5 3.5 0 0 1 7 0V7M3.5 7h9v6h-9z" /> : <path d="M8 3v6M8 11.5v1" />}</svg>
+      <span>{host}</span>
+    </span>
+  </div>
+  <div class="ma-browser__body">
+    {src && typeof src === 'string' && <img src={src} alt={alt} loading="lazy" decoding="async" />}
+    {src && typeof src !== 'string' && <Image src={src} alt={alt} />}
+    <slot />
+  </div>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-browser) {
+      container-type: inline-size;
+      display: grid;
+      /* one column the frame's own width: an auto column grew to the bar's unbroken line (tabs and address are nowrap)
+         and ran the frame out of a phone; now the tabs and the address clip inside it */
+      grid-template-columns: minmax(0, 1fr);
+      grid-template-rows: auto minmax(0, 1fr);
+      overflow: clip;
+      border: 1px solid var(--ma-edge);
+      border-radius: var(--ma-browser-r, 0.75rem);
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      box-shadow: 0 1px 2px var(--ma-glow);
+    }
+    /* pinned themes: base.css's whole token set of that theme, locally (theme.css's tokens follow data-ma-theme) */
+    :where(.ma-browser[data-theme='dark']) {
+      color-scheme: dark;
+      --ma-shine: rgb(255 255 255 / 0.32);
+      --ma-scrim: rgb(10 10 12 / 0.72);
+      --ma-edge: rgb(255 255 255 / 0.1);
+      --ma-ink: rgb(255 255 255 / 0.92);
+      --ma-panel: rgb(24 24 27 / 0.94);
+      --ma-glow: rgb(255 255 255 / 0.14);
+      --ma-dark: 1;
+    }
+    :where(.ma-browser[data-theme='light']) {
+      color-scheme: light;
+      --ma-shine: rgb(255 255 255 / 0.85);
+      --ma-scrim: rgb(255 255 255 / 0.72);
+      --ma-edge: rgb(0 0 0 / 0.08);
+      --ma-ink: rgb(0 0 0 / 0.9);
+      --ma-panel: rgb(255 255 255 / 0.92);
+      --ma-glow: rgb(0 0 0 / 0.1);
+      --ma-dark: 0;
+    }
+    :where(.ma-browser__bar) {
+      display: flex;
+      align-items: center;
+      gap: clamp(0.4rem, 1.5cqw, 0.75rem);
+      padding: clamp(0.35rem, 1.4cqw, 0.6rem) clamp(0.5rem, 2cqw, 0.9rem);
+      border-bottom: 1px solid var(--ma-edge);
+      font-size: clamp(0.55rem, 1.9cqw, 0.8rem);
+      line-height: 1;
+      white-space: nowrap;
+    }
+    :where(.ma-browser__lights) {
+      display: inline-flex;
+      gap: 0.5em;
+      flex: none;
+    }
+    :where(.ma-browser__lights > i) {
+      width: 1em;
+      height: 1em;
+      border-radius: 50%;
+      background: var(--ma-edge);
+    }
+    :where(.ma-browser__lights > i:nth-child(1)) { background: #ff5f57; }
+    :where(.ma-browser__lights > i:nth-child(2)) { background: #febc2e; }
+    :where(.ma-browser__lights > i:nth-child(3)) { background: #28c840; }
+    :where(.ma-browser__tabs) {
+      display: inline-flex;
+      gap: 0.25em;
+      min-width: 0;
+      overflow: clip;
+    }
+    :where(.ma-browser__tab) {
+      padding: 0.5em 0.9em;
+      border-radius: 0.5em;
+      opacity: var(--ma-dim, 0.7);
+      overflow: clip;
+      text-overflow: ellipsis;
+    }
+    :where(.ma-browser__tab[data-active]) {
+      opacity: 1;
+      background: color-mix(in srgb, var(--ma-ink) 8%, transparent);
+    }
+    :where(.ma-browser__url) {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5em;
+      flex: 1 1 auto;
+      min-width: 0;
+      padding: 0.5em 0.9em;
+      border-radius: 0.5em;
+      background: color-mix(in srgb, var(--ma-ink) 5%, transparent);
+      opacity: 0.8;
+      overflow: clip;
+      text-overflow: ellipsis;
+    }
+    :where(.ma-browser__lock) {
+      width: 1em;
+      height: 1em;
+      flex: none;
+      fill: none;
+      stroke: currentColor;
+      stroke-width: 1.4;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+    :where(.ma-browser__body) {
+      position: relative;
+      min-height: 0;
+      overflow: clip;
+    }
+    :where(.ma-browser__body > img) {
+      display: block;
+      width: 100%;
+      height: auto;
+    }
+    /* static: nothing moves, so nothing to reduce */
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-browser) {
+        animation: none;
+      }
+    }
+  }
+</style>

package/src/components/BrowserFrame.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'BrowserFrame',
+  slug: 'browser-frame',
+  title: 'Browser Frame',
+  description: 'A browser window around a screenshot or any content: the three lights, an address bar with a lock, optional tabs with one active. Static, zero JavaScript. The chrome scales with the frame\'s own width through container query units, and every colour is a theme token, so theme="dark" or "light" pins one look and "auto" follows the page.',
+  summary: 'A browser window mockup for screenshots: traffic lights, an address bar, optional tabs, light or dark.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['container-units'] },
+  readout: '<BrowserFrame url="https://moonarc.dev">',
+  usage: `---\nimport shot from '../assets/home.png';\n---\n<BrowserFrame url="https://moonarc.dev" tabs={['Home', 'Components']} src={shot} alt="The home page" />\n<BrowserFrame url="https://example.com" theme="dark">\n  <MyHero />\n</BrowserFrame>`,
+  props: [
+    { name: 'url', type: 'string', default: "'https://example.com'", description: 'Shown in the address bar; https shows a lock.' },
+    { name: 'tabs', type: 'string[]', description: 'Tab labels.' },
+    { name: 'active', type: 'number', default: '0', description: 'Index of the selected tab.' },
+    { name: 'theme', type: "'light' | 'dark' | 'auto'", default: "'auto'", description: 'Pin the base tokens to one theme, or follow the page. The theme.css tokens follow the page; add data-ma-theme="dark" as well to re-derive them inside the frame.' },
+    { name: 'src', type: 'ImageMetadata | string', description: 'A screenshot: an imported image goes through Astro\'s <Image>; a URL is a plain <img>.' },
+    { name: 'alt', type: 'string', default: "''", description: 'Alt text for the screenshot.' },
+    { name: 'radius', type: 'string', default: "'0.75rem'", description: 'Corner radius.' },
+  ],
+  reducedMotion: 'Nothing moves; nothing changes.',
+  clientRouter: 'Static markup; nothing to rebind.',
+  craft: [
+    'Sized in cqw with clamps: at 320 px wide the bar is a thin strip, at 1200 px it is a real toolbar, and the frame never dictates its own width.',
+    'A pinned theme redefines every base token locally (--ma-panel, --ma-edge, --ma-ink, --ma-glow, --ma-shine, --ma-scrim, --ma-dark) with base.css\'s values for that theme rather than painting its own colours, so a dark frame on a light page, and the library components inside it, match the library\'s dark exactly. The theme.css tokens (--background, --card, --primary …) still follow the page: add data-ma-theme="dark" to the frame as well to re-derive them inside it, and set --ma-brand there too if the page sets one.',
+    'The lights keep their three colours in both themes; they are the one thing a browser frame is recognised by.',
+    'Content is a slot, so the frame can hold a live section, a video, or a ScrollScrub with rotateX for the container-scroll look.',
+  ],
+  related: ['scroll-scrub', 'scroll-expand', 'code-tabs'],
+  intents: ['browser window mockup', 'browser frame component', 'safari frame screenshot', 'mac window mockup', 'device frame astro'],
+  replaces: ['Safari (Magic UI)', 'BrowserComponent (Cult UI)', 'BrowserWindow (Eldora UI)'],
+  fixture: { props: { url: 'https://moonarc.dev' }, slot: 'Fixture content for BrowserFrame', expect: 'Fixture content for BrowserFrame' },
+} satisfies ComponentMeta;

package/src/components/BubbleText.astro

@@ -0,0 +1,90 @@
+---
+/**
+ * BubbleText — the letter under the cursor swells to the heaviest weight
+ * and lifts a little; its neighbours follow at half and a quarter. Letters
+ * are split on the server; the neighbours are :hover + * and :has(+ :hover),
+ * so it is pure CSS. Needs a variable font for a continuous swell; static
+ * families step between the weights they have.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** The text. */
+  text: string;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Resting weight. */
+  min?: number;
+  /** Weight under the cursor. */
+  max?: number;
+  /** Duration in ms. Unset: the preset's --ma-duration. */
+  duration?: number;
+}
+
+const { text, as: Tag = 'span', min = 400, max = 800, duration, class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-bubble-min:${min}`, `--ma-bubble-max:${max}`, duration !== undefined && `--ma-bubble-dur:${duration}ms`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+// graphemes, not code points: an emoji with a skin tone or a letter with a combining accent swells as one letter
+const graphemes = (s: string) => Array.from(new Intl.Segmenter().segment(s), (g) => g.segment);
+// dir="auto": words and letters are inline-blocks, which bidi orders by the page's direction, so Latin text on a
+// right-to-left page read back to front. The element takes its direction from its own text instead.
+---
+
+<Tag class:list={['ma-bubble', className]} dir="auto" style={vars} {...rest}>
+  {text.split(/(\s+)/).map((word) =>
+    /^\s+$/.test(word) ? (
+      ' '
+    ) : (
+      <span class="ma-bubble__word" aria-hidden="true">
+        {graphemes(word).map((c) => <span class="ma-bubble__char">{c}</span>)}
+      </span>
+    ),
+  )}
+  <span class="ma-sr">{text}</span>
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-bubble) {
+      white-space: pre-wrap;
+      font-weight: var(--ma-bubble-min, 400);
+    }
+    /* a word is one inline-block, so lines break between words, never between letters */
+    :where(.ma-bubble__word) {
+      display: inline-block;
+      white-space: nowrap;
+    }
+    :where(.ma-bubble__char) {
+      display: inline-block;
+      font-weight: var(--ma-bubble-min, 400);
+      transition:
+        font-weight var(--ma-bubble-dur, var(--ma-duration)) var(--ma-ease),
+        translate var(--ma-bubble-dur, var(--ma-duration)) var(--ma-ease);
+    }
+    @media (hover: hover) {
+      :where(.ma-bubble__char:hover) {
+        font-weight: var(--ma-bubble-max, 800);
+        translate: 0 calc(-1 * var(--ma-travel-hover));
+        transition-duration: var(--ma-duration-fast);
+      }
+      /* neighbours: half the swell, then a quarter */
+      :where(.ma-bubble__char:hover + .ma-bubble__char),
+      :where(.ma-bubble__char:has(+ .ma-bubble__char:hover)) {
+        font-weight: calc((var(--ma-bubble-min, 400) + var(--ma-bubble-max, 800)) / 2);
+        translate: 0 calc(-0.5 * var(--ma-travel-hover));
+        transition-duration: var(--ma-duration-fast);
+      }
+      :where(.ma-bubble__char:hover + .ma-bubble__char + .ma-bubble__char),
+      :where(.ma-bubble__char:has(+ .ma-bubble__char + .ma-bubble__char:hover)) {
+        font-weight: calc(var(--ma-bubble-min, 400) + (var(--ma-bubble-max, 800) - var(--ma-bubble-min, 400)) / 4);
+        translate: 0 calc(-0.25 * var(--ma-travel-hover));
+        transition-duration: var(--ma-duration-fast);
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-bubble__char) {
+        transition: none;
+        translate: 0 0;
+      }
+    }
+  }
+</style>

package/src/components/BubbleText.meta.ts

@@ -0,0 +1,38 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'BubbleText',
+  slug: 'bubble-text',
+  title: 'Bubble Text',
+  description:
+    'Swells the letter under the cursor to the heaviest weight and lifts it; its neighbours follow at half and a quarter, and everything settles when the pointer leaves. Letters split on the server, neighbours found with :has(). Pure CSS on a variable font.',
+  summary: 'A variable-font text effect: the letter under the cursor swells and lifts, and its neighbours follow.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['hover'],
+  support: { baseline: 'widely', needs: ['font-variation', 'has'] },
+  readout: '<BubbleText min={400} max={800}>',
+  usage: `<h1><BubbleText text="Hover the letters." /></h1>\n<BubbleText text="light to black" min={300} max={900} duration={300} />`,
+  props: [
+    { name: 'text', type: 'string', description: 'The text; split into words and characters on the server, so lines break between words only.' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'min', type: 'number', default: '400', description: 'Resting weight.' },
+    { name: 'max', type: 'number', default: '800', description: 'Weight under the cursor. The neighbours get the midpoint and the quarter.' },
+    { name: 'duration', type: 'number', default: 'preset (ui: 450)', description: 'Release duration in ms; the swell itself is the fast duration.' },
+  ],
+  reducedMotion: 'The weight still follows the cursor, because that is direct manipulation, but it changes instantly and nothing lifts.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Swell in 150 ms, release on the preset duration: the asymmetry is what makes it feel like pressing into something soft.',
+    'Neighbours at half and a quarter through :hover + * and :has(+ :hover): a bump, not a spotlight. Three letters wide is the width of a fingertip; the bump stops at a word boundary, which is also where the eye stops.',
+    'font-weight on a variable axis is one property with no layout trick; the line does reflow as widths change, so keep it to headlines.',
+    'The lift is the preset\'s hover travel token (2 px on snap, 6 px on lively), so the swell keeps the page\'s scale.',
+    'A visually hidden span (.ma-sr), aria-hidden letters: one string to assistive tech.',
+    'A character is a grapheme (Intl.Segmenter), so an emoji with a skin tone or a letter with a combining accent counts as one. The inline-block characters would follow the page\'s direction, so the element takes dir="auto" and Latin text on a right-to-left page still runs left to right.',
+  ],
+  related: ['weight-wave', 'text-roll', 'magnetic'],
+  intents: ['bubble text hover', 'text weight hover effect', 'letters swell under cursor', 'variable font hover', 'hover text bulge'],
+  replaces: ['BubbleText (Hover.dev)', 'VariableProximity (React Bits) under the cursor'],
+  // an emoji with a skin tone is one letter (a grapheme), not two code points
+  fixture: { props: { text: 'Fixture content for BubbleText 👍🏽' }, expect: 'ma-bubble__char">👍🏽</span>' },
+} satisfies ComponentMeta;

package/src/components/CardStack.astro

@@ -0,0 +1,79 @@
+---
+/**
+ * CardStack — cards stick as you scroll and each one shrinks back as the
+ * next slides over it. Zero JS: every child is sticky, and each card's
+ * scale is bound to the *next* card's view timeline through timeline-scope,
+ * so the shrink is exactly in step with the cover. Up to eight cards.
+ * Without scroll timelines, or without timeline-scope (Chrome 115), the
+ * cards still stack; they just do not shrink.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Sticky offset from the top of the viewport, any CSS length. */
+  top?: string;
+  /** Extra offset per card so the stack's edges peek out. */
+  peek?: string;
+  /** Scale a covered card shrinks to. */
+  scale?: number;
+  /** Minimum height of each card's slot, so there is something to scroll through. */
+  height?: string;
+}
+
+const { top = '10vh', peek = '1rem', scale = 0.92, height = '70vh', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-stack-top:${top}`, `--ma-stack-peek:${peek}`, `--ma-stack-scale:${scale}`, `--ma-stack-h:${height}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-stack', className]} style={vars} {...rest}>
+  <slot />
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-stack) {
+      display: grid;
+      gap: var(--ma-stack-peek, 1rem);
+      timeline-scope: --ma-c1, --ma-c2, --ma-c3, --ma-c4, --ma-c5, --ma-c6, --ma-c7, --ma-c8;
+    }
+    :where(.ma-stack > *) {
+      position: sticky;
+      top: calc(var(--ma-stack-top, 10vh) + var(--ma-stack-i, 0) * var(--ma-stack-peek, 1rem));
+      min-height: var(--ma-stack-h, 70vh);
+      transform-origin: 50% 0;
+    }
+    :where(.ma-stack > :nth-child(1)) { --ma-stack-i: 0; view-timeline-name: --ma-c1; }
+    :where(.ma-stack > :nth-child(2)) { --ma-stack-i: 1; view-timeline-name: --ma-c2; }
+    :where(.ma-stack > :nth-child(3)) { --ma-stack-i: 2; view-timeline-name: --ma-c3; }
+    :where(.ma-stack > :nth-child(4)) { --ma-stack-i: 3; view-timeline-name: --ma-c4; }
+    :where(.ma-stack > :nth-child(5)) { --ma-stack-i: 4; view-timeline-name: --ma-c5; }
+    :where(.ma-stack > :nth-child(6)) { --ma-stack-i: 5; view-timeline-name: --ma-c6; }
+    :where(.ma-stack > :nth-child(7)) { --ma-stack-i: 6; view-timeline-name: --ma-c7; }
+    :where(.ma-stack > :nth-child(8)) { --ma-stack-i: 7; view-timeline-name: --ma-c8; }
+    /* timeline-scope arrived a release after view timelines (Chrome 116): without it the names never reach a sibling */
+    @supports (animation-timeline: view()) and (timeline-scope: none) {
+      :where(.ma-stack > :not(:last-child)) {
+        animation: ma-stack linear both;
+        animation-range: entry 0% entry 100%;
+      }
+      :where(.ma-stack > :nth-child(1):not(:last-child)) { animation-timeline: --ma-c2; }
+      :where(.ma-stack > :nth-child(2):not(:last-child)) { animation-timeline: --ma-c3; }
+      :where(.ma-stack > :nth-child(3):not(:last-child)) { animation-timeline: --ma-c4; }
+      :where(.ma-stack > :nth-child(4):not(:last-child)) { animation-timeline: --ma-c5; }
+      :where(.ma-stack > :nth-child(5):not(:last-child)) { animation-timeline: --ma-c6; }
+      :where(.ma-stack > :nth-child(6):not(:last-child)) { animation-timeline: --ma-c7; }
+      :where(.ma-stack > :nth-child(7):not(:last-child)) { animation-timeline: --ma-c8; }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-stack > *) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-stack {
+    to {
+      scale: var(--ma-stack-scale, 0.92);
+      filter: brightness(0.85);
+    }
+  }
+</style>

package/src/components/CardStack.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'CardStack',
+  slug: 'card-stack',
+  title: 'Card Stack',
+  description: 'Cards stick to the top as you scroll and each one shrinks and dims as the next slides over it, as on Apple product pages. Zero JavaScript: sticky positioning plus each card\'s scale bound to the next card\'s view timeline. Up to eight cards.',
+  summary: 'Cards that stick as you scroll, each shrinking and dimming as the next slides over it, as on Apple product pages.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline', 'timeline-scope'], fallback: 'cards still stack with sticky positioning, without the shrink (Firefox, Chrome 115)' },
+  readout: '<CardStack scale={0.92}>',
+  usage: `<CardStack top="8vh" peek="1.25rem">\n  <section class="rounded-2xl bg-surface p-8">One</section>\n  <section class="rounded-2xl bg-surface p-8">Two</section>\n  <section class="rounded-2xl bg-surface p-8">Three</section>\n</CardStack>`,
+  props: [
+    { name: 'top', type: 'string', default: "'10vh'", description: 'Sticky offset from the top of the viewport.' },
+    { name: 'peek', type: 'string', default: "'1rem'", description: 'Extra offset per card so the stacked edges show.' },
+    { name: 'scale', type: 'number', default: '0.92', description: 'Scale a covered card shrinks to.' },
+    { name: 'height', type: 'string', default: "'70vh'", description: 'Minimum height of each card; it is what you scroll through.' },
+  ],
+  reducedMotion: 'Cards stack without shrinking or dimming.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'A card cannot read its own stuck position, so each card animates on the next card\'s timeline: the shrink is driven by the thing covering it, which is what the eye expects.',
+    'timeline-scope on the container hoists eight named timelines so siblings can reference each other.',
+    'transform-origin at the top edge, so a shrinking card recedes under the incoming one instead of floating.',
+    'Give every card an opaque background; sticky stacking only reads when the lower card is hidden.',
+  ],
+  related: ['parallax', 'scroll-scrub', 'reveal'],
+  intents: ['card stack scroll', 'sticky stacking cards', 'stacked cards on scroll', 'apple style card stack', 'scroll stack astro'],
+  replaces: ['ScrollStack (React Bits)', 'StickyScroll (Aceternity)', 'GSAP pinned card stacks'],
+  fixture: { slot: '<div>Fixture content for CardStack</div><div>Two</div>', expect: 'Fixture content for CardStack' },
+} satisfies ComponentMeta;

package/src/components/Carousel.astro

@@ -0,0 +1,147 @@
+---
+/**
+ * Carousel — scroll-snap strip with native buttons and markers, zero JS.
+ *
+ * Children are the slides. Scrolling, snapping, momentum and touch are the
+ * browser's. Where ::scroll-button() and ::scroll-marker exist (Chromium),
+ * previous/next buttons and dots are generated pseudo-elements that scroll
+ * the container and track the current slide; elsewhere the strip is still
+ * swipeable and keyboard-scrollable, without the chrome.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Slides visible at once. */
+  perView?: number;
+  /** Gap between slides, any CSS length. */
+  gap?: string;
+  /** Dot markers under the strip. */
+  markers?: boolean;
+  /** Previous / next buttons. */
+  buttons?: boolean;
+  /** Snap strictness. */
+  snap?: 'mandatory' | 'proximity';
+  /** Accessible name for the strip. */
+  label?: string;
+}
+
+const { perView = 1, gap = '1rem', markers = true, buttons = true, snap = 'mandatory', label = 'Carousel', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-car-n:${perView}`, `--ma-car-gap:${gap}`, `--ma-car-snap:${snap}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-carousel', className]} data-markers={markers ? '' : undefined} data-buttons={buttons ? '' : undefined} style={vars} {...rest}>
+  <div class="ma-carousel__track" role="region" aria-label={label} tabindex="0">
+    <slot />
+  </div>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-carousel) {
+      position: relative;
+    }
+    :where(.ma-carousel__track) {
+      display: grid;
+      grid-auto-flow: column;
+      grid-auto-columns: calc((100% - (var(--ma-car-n, 1) - 1) * var(--ma-car-gap, 1rem)) / var(--ma-car-n, 1));
+      gap: var(--ma-car-gap, 1rem);
+      overflow-x: auto;
+      overscroll-behavior-x: contain;
+      scroll-snap-type: x var(--ma-car-snap, mandatory);
+      scroll-behavior: smooth;
+      scrollbar-width: none;
+      scroll-marker-group: after;
+    }
+    :where(.ma-carousel__track)::-webkit-scrollbar {
+      display: none;
+    }
+    :where(.ma-carousel__track:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 4px;
+      border-radius: 0.5rem;
+    }
+    :where(.ma-carousel__track > *) {
+      scroll-snap-align: start;
+      scroll-snap-stop: always;
+    }
+    /* buttons — generated, and they scroll the container by one page. Plain absolute insets against the
+       positioned root: the pseudo-elements sit outside the track's scrollable overflow, so they never scroll
+       with the slides, and no anchor is needed (anchoring a pseudo-element to its own container is not
+       reliably supported, and the two buttons then land on top of each other). */
+    :where(.ma-carousel[data-buttons] .ma-carousel__track)::scroll-button(*) {
+      position: absolute;
+      top: 50%;
+      translate: 0 -50%;
+      z-index: 1;
+      display: grid;
+      place-items: center;
+      width: 2.25rem;
+      height: 2.25rem;
+      border-radius: 999px;
+      border: 1px solid var(--ma-edge);
+      background: var(--ma-panel);
+      color: inherit;
+      cursor: pointer;
+      font: inherit;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out), translate var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-carousel[data-buttons] .ma-carousel__track)::scroll-button(*):disabled {
+      opacity: 0.3;
+      cursor: default;
+    }
+    :where(.ma-carousel[data-buttons] .ma-carousel__track)::scroll-button(*):hover:not(:disabled) {
+      translate: 0 calc(-50% - 1px);
+    }
+    /* with markers the slides sit above a marker row: centre on the slides, not on the whole box */
+    :where(.ma-carousel[data-buttons][data-markers] .ma-carousel__track)::scroll-button(*) {
+      top: calc(50% - 0.6875rem);
+    }
+    :where(.ma-carousel[data-buttons] .ma-carousel__track)::scroll-button(inline-start) {
+      content: var(--ma-car-prev, '←') / 'Previous';
+      inset-inline-start: 0.5rem;
+    }
+    :where(.ma-carousel[data-buttons] .ma-carousel__track)::scroll-button(inline-end) {
+      content: var(--ma-car-next, '→') / 'Next';
+      inset-inline-end: 0.5rem;
+    }
+    /* right to left the inline-start button is the right-hand one, so the arrows turn with it. [dir] and not :dir():
+       :dir() reached Chrome in 120, and a build that targets an older Chrome rewrites it into a guess from lang, which a page that sets only dir never
+       matches. An ltr island one level inside an rtl page is set back */
+    :where([dir='rtl'] .ma-carousel, .ma-carousel[dir='rtl']) {
+      --ma-car-prev: '→';
+      --ma-car-next: '←';
+    }
+    :where([dir='rtl'] [dir='ltr'] .ma-carousel, [dir='rtl'] .ma-carousel[dir='ltr']) {
+      --ma-car-prev: '←';
+      --ma-car-next: '→';
+    }
+    /* markers — one per slide, current one filled */
+    :where(.ma-carousel[data-markers] .ma-carousel__track)::scroll-marker-group {
+      display: flex;
+      justify-content: center;
+      padding-top: 0.875rem;
+    }
+    /* a 24 px target (WCAG 2.5.8) around the 8 px dot: the padding is hit area, the colour stays on the content box, the
+       negative block margin keeps the row as tall as the dot, and the targets sit edge to edge */
+    :where(.ma-carousel[data-markers] .ma-carousel__track > *)::scroll-marker {
+      content: '';
+      width: 0.5rem;
+      height: 0.5rem;
+      padding: max(0.5rem, calc(12px - 0.25rem));
+      margin-block: calc(-1 * max(0.5rem, calc(12px - 0.25rem)));
+      border-radius: 999px;
+      background: var(--ma-edge);
+      background-clip: content-box;
+      transition: background-color var(--ma-duration-fast) var(--ma-ease-out), scale var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-carousel[data-markers] .ma-carousel__track > *)::scroll-marker:target-current {
+      background-color: currentColor;
+      scale: 1.25;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-carousel__track) {
+        scroll-behavior: auto;
+      }
+    }
+  }
+</style>

package/src/components/Carousel.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Carousel',
+  slug: 'carousel',
+  title: 'Carousel',
+  description: 'A scroll-snap strip with previous/next buttons and dot markers that the browser generates and keeps in sync. Zero JavaScript. Touch, momentum, keyboard and snapping are native everywhere; the buttons and dots appear where ::scroll-button() and ::scroll-marker exist.',
+  summary: 'A scroll-snap carousel with native touch, momentum and keyboard, plus browser-made buttons and dots where supported.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click', 'pointer'],
+  support: { baseline: 'limited', needs: ['scroll-snap', 'scroll-marker'], fallback: 'a swipeable, keyboard-scrollable snap strip without buttons or dots (Firefox, Safari)' },
+  readout: '<Carousel perView={3}>',
+  usage: `<Carousel perView={3} gap="1rem" label="Testimonials">\n  <figure>…</figure>\n  <figure>…</figure>\n  <figure>…</figure>\n</Carousel>`,
+  props: [
+    { name: 'perView', type: 'number', default: '1', description: 'Slides visible at once.' },
+    { name: 'gap', type: 'string', default: "'1rem'", description: 'Gap between slides.' },
+    { name: 'markers', type: 'boolean', default: 'true', description: 'Dot markers under the strip (where supported).' },
+    { name: 'buttons', type: 'boolean', default: 'true', description: 'Previous / next buttons (where supported).' },
+    { name: 'snap', type: "'mandatory' | 'proximity'", default: "'mandatory'", description: 'Snap strictness.' },
+    { name: 'label', type: 'string', default: "'Carousel'", description: 'Accessible name of the scrolling region.' },
+  ],
+  reducedMotion: 'Buttons and markers jump instead of smooth-scrolling; the strip still snaps.',
+  clientRouter: 'CSS-only; scroll position resets with the page.',
+  craft: [
+    'The strip is a grid with auto-flow columns: slide width is one expression of perView and gap, no measuring.',
+    'Buttons are ::scroll-button(): they scroll by a page, disable at the ends, and need no event handler. They are absolutely positioned against the carousel at its inline edges, so they never scroll with the slides, and in a right-to-left page they swap sides and their arrows turn.',
+    'Markers are ::scroll-marker on each slide; :target-current is the browser telling you which slide is in view. Each dot is 8 px inside a 24 px target, the WCAG 2.5.8 minimum.',
+    'scroll-snap-stop: always so a fast flick never skips a slide.',
+  ],
+  related: ['tabs', 'marquee', 'card-stack'],
+  intents: ['carousel', 'slider', 'scroll snap carousel', 'image carousel astro', 'carousel without javascript', 'testimonial slider'],
+  replaces: ['Embla', 'Swiper for simple strips', 'Carousel (shadcn)', 'Carousel (React Bits)'],
+  fixture: { slot: '<div>Fixture content for Carousel</div><div>Two</div><div>Three</div>', expect: 'Fixture content for Carousel' },
+} satisfies ComponentMeta;