@moonarc/core 0.1.0

package/src/components/RotatingText.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'RotatingText',
+  slug: 'rotating-text',
+  title: 'Rotating Text',
+  description:
+    'Cycles through a list of words in place. Each word rises in, holds, and leaves upward, and the box is sized to the widest word so the surrounding text never shifts. Pure CSS.',
+  summary: 'Rotating words in a sentence: each word rises in, holds and leaves, in a box sized so nothing around it shifts.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'newly', needs: ['property'], fallback: 'words crossfade in place without the vertical travel' },
+  readout: '<RotatingText period={1600}>',
+  usage: `<p>Build <RotatingText words={['faster', 'lighter', 'calmer']} /> sites.</p>\n<p>Ship <RotatingText words={['once', 'everywhere', 'today']} fluid />. The sentence follows.</p>`,
+  props: [
+    { name: 'words', type: 'string[]', description: 'Words to cycle through, 2–8. A single word stays in place.' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'period', type: 'number', default: '2200', description: 'Time each word is shown in ms, including its entrance. Under 1500 reads as nervous.' },
+    { name: 'fluid', type: 'boolean', default: 'false', description: 'The box follows the current word\'s width, so the text around it shifts smoothly as words change instead of being sized to the widest word.' },
+  ],
+  reducedMotion: 'Words crossfade in place; the vertical travel is removed.',
+  clientRouter: 'CSS-only; fresh elements restart their own animation after every navigation.',
+  craft: [
+    'inline-grid with every word in one cell sizes the box to the widest word, so the sentence around it never reflows.',
+    'Entrance is ease-out, exit is ease-in, hold is linear: the same asymmetry as any enter/exit pair.',
+    'The travel lives in a registered custom property so reduced motion neutralises it with a single declaration.',
+    'A visually hidden span (.ma-sr) lists every word once; the animated spans are aria-hidden. Not aria-label: RotatingText usually sits inside a sentence as a span, where a label is not allowed and is not read.',
+    'fluid is a second animation on max-width, not a measurement: each word contributes 0 while it is away and its own width while it is the word, so the grid cell (the widest contribution) travels from one width to the next. The growth bound is 0.75 em per character, an upper limit that only sets how fast the width reaches the word\'s real size.',
+  ],
+  related: ['typewriter', 'split-text'],
+  intents: ['rotating words', 'word cycle animation', 'flip words', 'animated headline words', 'text loop astro'],
+  replaces: ['RotatingText (React Bits)', 'FlipWords (Aceternity)', 'WordRotate (Magic UI)'],
+  fixture: { props: { words: ['Fixture content for RotatingText', 'second', 'third'] }, expect: 'Fixture content for RotatingText' },
+} satisfies ComponentMeta;

package/src/components/ScrollExpand.astro

@@ -0,0 +1,90 @@
+---
+/**
+ * ScrollExpand — an image that starts narrow and rounded and opens to the
+ * full width as it scrolls into view, zero JS. Nothing about the layout
+ * changes: the element is full width from the start and a clip-path inset
+ * (with its rounding) shrinks it, animated on the element's own view()
+ * timeline; the content underneath scales up a touch for depth. Without
+ * scroll timelines, and under reduced motion, it is simply full width.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  as?: HTMLTag;
+  /** Starting width as a fraction of the full width, 0.2–1. */
+  from?: number;
+  /** Starting corner radius, any CSS length; it eases to `radiusEnd`. */
+  radius?: string;
+  radiusEnd?: string;
+  /** Starting scale of the content inside. */
+  scale?: number;
+  /** animation-range on the element's view timeline. */
+  range?: string;
+}
+
+const { as: Tag = 'div', from = 0.6, radius = '2rem', radiusEnd = '0px', scale = 0.92, range = 'entry 0% cover 45%', class: className, style, ...rest } = Astro.props;
+const inset = ((1 - Math.max(0.2, Math.min(from, 1))) / 2) * 100;
+const vars = [`--ma-expand-inset:${inset}%`, `--ma-expand-r:${radius}`, `--ma-expand-r-end:${radiusEnd}`, `--ma-expand-scale:${scale}`, `--ma-expand-range:${range}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-expand', className]} style={vars} {...rest}>
+  <div class="ma-expand__inner"><slot /></div>
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-expand) {
+      display: block;
+      overflow: clip;
+    }
+    :where(.ma-expand__inner) {
+      display: block;
+      transform-origin: 50% 50%;
+    }
+    :where(.ma-expand__inner > img),
+    :where(.ma-expand__inner > picture > img),
+    :where(.ma-expand__inner > video) {
+      display: block;
+      width: 100%;
+      height: auto;
+    }
+    @supports (animation-timeline: view()) {
+      :where(.ma-expand) {
+        animation: ma-expand linear both;
+        animation-range: var(--ma-expand-range, entry 0% cover 45%);
+      }
+      :where(.ma-expand__inner) {
+        animation: ma-expand-inner linear both;
+        animation-range: var(--ma-expand-range, entry 0% cover 45%);
+      }
+      /* the timeline in its own rule: a minifier folds it into the animation shorthand otherwise, and the shorthand cannot carry it */
+      :where(html) :where(.ma-expand),
+      :where(html) :where(.ma-expand__inner) {
+        animation-timeline: view();
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-expand),
+      :where(.ma-expand__inner) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-expand {
+    from {
+      clip-path: inset(0 var(--ma-expand-inset, 20%) round var(--ma-expand-r, 2rem));
+    }
+    to {
+      clip-path: inset(0 0 round var(--ma-expand-r-end, 0px));
+    }
+  }
+  @keyframes ma-expand-inner {
+    from {
+      scale: var(--ma-expand-scale, 0.92);
+    }
+    to {
+      scale: 1;
+    }
+  }
+</style>

package/src/components/ScrollExpand.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ScrollExpand',
+  slug: 'scroll-expand',
+  title: 'Scroll Expand',
+  description: 'An image that starts narrow and rounded and opens to the full width as it scrolls into view. The layout never changes: the element is full width from the start and a clip-path inset with its rounding shrinks it, animated on the element\'s own view() timeline; the content inside scales up a touch for depth. Without scroll timelines it is simply full width. Zero JavaScript.',
+  summary: 'An image that opens from narrow and rounded to the full width as it scrolls into view.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline', 'clip-path'], fallback: 'full width, static (Firefox)' },
+  readout: '<ScrollExpand from={0.6} radius="2rem">',
+  usage: `<ScrollExpand from={0.6} radius="2rem">\n  <img src="/case-study.jpg" alt="The studio" width="1600" height="900" />\n</ScrollExpand>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'from', type: 'number', default: '0.6', description: 'Starting width as a fraction of the full width, 0.2–1.' },
+    { name: 'radius', type: 'string', default: "'2rem'", description: 'Starting corner radius.' },
+    { name: 'radiusEnd', type: 'string', default: "'0px'", description: 'Corner radius at full width.' },
+    { name: 'scale', type: 'number', default: '0.92', description: 'Starting scale of the content inside.' },
+    { name: 'range', type: 'string', default: "'entry 0% cover 45%'", description: 'animation-range on the element\'s view timeline.' },
+  ],
+  reducedMotion: 'Full width from the start; no clip, no scale.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'clip-path, not width: a width change reflows the page on every scroll frame; a clip is a compositor property and the neighbours never move.',
+    'The corner radius rides on the same inset (inset(… round r)), so the rounding eases away as the edges reach the viewport: one keyframe, no second animation.',
+    'The inner scale runs the opposite way to the clip (content grows as the frame opens), which reads as a camera pulling back rather than a curtain.',
+    'The default range ends at cover 45 %: full width is reached while the image is still in the lower half of the viewport, so the reader never scrolls past a half-open frame.',
+  ],
+  related: ['scroll-scrub', 'parallax', 'browser-frame'],
+  intents: ['image expands on scroll', 'scroll zoom image full width', 'container scroll expand', 'scroll expand media', 'hero image grows on scroll'],
+  replaces: ['ScrollExpandMedia (Motion Primitives)', 'ContainerScroll (Aceternity)', 'scroll zoom hero (Codrops)'],
+  fixture: { slot: 'Fixture content for ScrollExpand', expect: 'Fixture content for ScrollExpand' },
+} satisfies ComponentMeta;

package/src/components/ScrollProgress.astro

@@ -0,0 +1,73 @@
+---
+/**
+ * ScrollProgress — a hairline that fills as the page is read, zero JS.
+ *
+ * scale-x is bound to the document scroll timeline; nothing listens to
+ * scroll. Browsers without scroll timelines do not show the bar at all,
+ * which is better than a bar that is always full.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Thickness in px. */
+  height?: number;
+  /** Bar colour. */
+  color?: string;
+  /** Edge of the viewport. */
+  position?: 'top' | 'bottom';
+  /** Which scroller to track: the document, or the nearest scrolling ancestor (then the bar is sticky inside it). */
+  scope?: 'root' | 'nearest';
+}
+
+const { height = 2, color = 'currentColor', position = 'top', scope = 'root', class: className, ...rest } = Astro.props;
+---
+
+<div class:list={['ma-scroll-progress', className]} aria-hidden="true" data-position={position === 'bottom' ? 'bottom' : undefined} data-scope={scope === 'nearest' ? 'nearest' : undefined} style={`--ma-sp-h:${height}px;--ma-sp-color:${color}`} {...rest}></div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-scroll-progress) {
+      display: none;
+      position: fixed;
+      inset: 0 0 auto;
+      z-index: 50;
+      height: var(--ma-sp-h, 2px);
+      background: var(--ma-sp-color, currentColor);
+      transform-origin: 0 50%;
+      scale: 0 1;
+      pointer-events: none;
+    }
+    :where(.ma-scroll-progress[data-position='bottom']) {
+      inset: auto 0 0;
+    }
+    :where(.ma-scroll-progress[data-scope='nearest']) {
+      position: sticky;
+      inset: 0 0 auto;
+      margin-bottom: calc(var(--ma-sp-h, 2px) * -1);
+    }
+    @supports (animation-timeline: scroll()) {
+      :where(.ma-scroll-progress) {
+        display: block;
+        animation: ma-scroll-progress linear both;
+      }
+      :where(html) :where(.ma-scroll-progress) {
+        animation-timeline: scroll(root block);
+      }
+      :where(html) :where(.ma-scroll-progress[data-scope='nearest']) {
+        animation-timeline: scroll(nearest block);
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      /* progress is information, not motion: it stays */
+      :where(.ma-scroll-progress) {
+        transition: none;
+      }
+    }
+  }
+
+  @keyframes ma-scroll-progress {
+    to {
+      scale: 1 1;
+    }
+  }
+</style>

package/src/components/ScrollProgress.meta.ts

@@ -0,0 +1,32 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ScrollProgress',
+  slug: 'scroll-progress',
+  title: 'Scroll Progress',
+  description: 'A hairline along the top of the viewport that fills as the page is read. Zero JavaScript: its scale is bound to the document\'s scroll timeline, so nothing listens to scroll and it is never a frame behind.',
+  summary: 'A reading progress bar along the top of the page, bound to the scroll so it is never a frame behind.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline'], fallback: 'the bar is not rendered (Firefox)' },
+  readout: '<ScrollProgress height={2}>',
+  usage: `<ScrollProgress color="var(--accent)" />`,
+  props: [
+    { name: 'height', type: 'number', default: '2', description: 'Thickness in px.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Bar colour.' },
+    { name: 'position', type: "'top' | 'bottom'", default: "'top'", description: 'Edge of the viewport.' },
+    { name: 'scope', type: "'root' | 'nearest'", default: "'root'", description: 'Track the document, or the nearest scrolling ancestor; with nearest, the bar sticks to the top of that scroller.' },
+  ],
+  reducedMotion: 'Unchanged: the bar reports position and does not animate on its own.',
+  clientRouter: 'CSS-only; the new page\'s bar starts at its own scroll position.',
+  craft: [
+    'scale on a transform-origin at the left: one compositor property, no width recalculation.',
+    'Hidden where scroll timelines are missing, because a full bar on load is worse than no bar.',
+    'aria-hidden: the reading position is already in the scrollbar for assistive tech.',
+  ],
+  related: ['parallax', 'reveal'],
+  intents: ['scroll progress bar', 'reading progress indicator', 'page scroll indicator', 'progress bar on scroll astro'],
+  replaces: ['ScrollProgress (Magic UI)', 'framer-motion useScroll progress bar'],
+  fixture: { expect: 'class="ma-scroll-progress"' },
+} satisfies ComponentMeta;

package/src/components/ScrollScrub.astro

@@ -0,0 +1,96 @@
+---
+/**
+ * ScrollScrub — bind any transform to scroll position, zero JS.
+ *
+ * Reveal answers "appear when seen"; this answers "move exactly as I
+ * scroll": translate, scale, rotate and opacity go from the given start
+ * values to neutral across a range of the element's own view timeline.
+ * Without scroll timelines the element shows its end state.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Start x offset in px. */
+  x?: number;
+  /** Start y offset in px. */
+  y?: number;
+  /** Start scale. */
+  scale?: number;
+  /** Start rotation in degrees. */
+  rotate?: number;
+  /** Start opacity. */
+  opacity?: number;
+  /** Start tilt on the X axis in degrees — the "container scroll" look. Adds perspective to the element itself. */
+  rotateX?: number;
+  /** Perspective in px, used with rotateX. */
+  perspective?: number;
+  /** animation-range of the element's view timeline. */
+  range?: string;
+}
+
+const { as: Tag = 'div', x = 0, y = 0, scale = 1, rotate = 0, opacity = 1, rotateX, perspective = 1200, range = 'entry 0% cover 40%', class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-ss-x:${x}px`, `--ma-ss-y:${y}px`, `--ma-ss-scale:${scale}`, `--ma-ss-rotate:${rotate}deg`, `--ma-ss-opacity:${opacity}`, `--ma-ss-range:${range}`, rotateX !== undefined && `--ma-ss-rx:${rotateX}deg`, rotateX !== undefined && `--ma-ss-p:${perspective}px`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-scrub', className]} data-tilt={rotateX !== undefined ? '' : undefined} style={inline} {...rest}>
+  <slot />
+</Tag>
+
+<style is:global>
+  @layer components {
+    @supports (animation-timeline: view()) {
+      :where(.ma-scrub) {
+        will-change: translate, scale, rotate, opacity;
+        animation: ma-scrub linear both;
+        animation-range: var(--ma-ss-range, entry 0% cover 40%);
+      }
+      :where(html) :where(.ma-scrub) {
+        animation-timeline: view();
+      }
+      /* rotateX: the 3D pair on the same element — perspective() and rotateX() in one transform, no wrapper */
+      :where(.ma-scrub[data-tilt]) {
+        animation-name: ma-scrub-tilt;
+        will-change: translate, scale, rotate, opacity, transform;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-scrub) {
+        animation: none;
+        will-change: auto;
+      }
+    }
+  }
+
+  @keyframes ma-scrub-tilt {
+    from {
+      translate: var(--ma-ss-x, 0px) var(--ma-ss-y, 0px);
+      scale: var(--ma-ss-scale, 1);
+      rotate: var(--ma-ss-rotate, 0deg);
+      opacity: var(--ma-ss-opacity, 1);
+      transform: perspective(var(--ma-ss-p, 1200px)) rotateX(var(--ma-ss-rx, 0deg));
+    }
+    to {
+      translate: 0 0;
+      scale: 1;
+      rotate: 0deg;
+      opacity: 1;
+      transform: perspective(var(--ma-ss-p, 1200px)) rotateX(0deg);
+    }
+  }
+  @keyframes ma-scrub {
+    from {
+      translate: var(--ma-ss-x, 0px) var(--ma-ss-y, 0px);
+      scale: var(--ma-ss-scale, 1);
+      rotate: var(--ma-ss-rotate, 0deg);
+      opacity: var(--ma-ss-opacity, 1);
+    }
+    to {
+      translate: 0 0;
+      scale: 1;
+      rotate: 0deg;
+      opacity: 1;
+    }
+  }
+</style>

package/src/components/ScrollScrub.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ScrollScrub',
+  slug: 'scroll-scrub',
+  title: 'Scroll Scrub',
+  description: 'Bind translate, scale, rotate and opacity to the scroll position: the element goes from the start values you give to neutral across a range of its own passage through the viewport, exactly in step. Zero JavaScript.',
+  summary: "Scroll-linked animation: bind translate, scale, rotate and opacity to an element's passage through the viewport.",
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline'], fallback: 'the end state, static (Firefox)' },
+  readout: '<ScrollScrub y={80} scale={0.9}>',
+  usage: `<ScrollScrub y={80} scale={0.9} opacity={0}>\n  <img src="/screenshot.png" alt="" />\n</ScrollScrub>\n<ScrollScrub rotate={-6} range="entry 0% entry 100%">tilted in</ScrollScrub>\n<ScrollScrub rotateX={24} scale={0.94} range="entry 0% cover 55%">\n  <BrowserFrame url="https://example.com" src={shot} alt="" />\n</ScrollScrub>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'x', type: 'number', default: '0', description: 'Start x offset in px.' },
+    { name: 'y', type: 'number', default: '0', description: 'Start y offset in px.' },
+    { name: 'scale', type: 'number', default: '1', description: 'Start scale.' },
+    { name: 'rotate', type: 'number', default: '0', description: 'Start rotation in degrees.' },
+    { name: 'opacity', type: 'number', default: '1', description: 'Start opacity.' },
+    { name: 'rotateX', type: 'number', description: 'Start tilt on the X axis in degrees (the "container scroll" look); the element straightens across the range. Perspective is applied on the element itself, no wrapper.' },
+    { name: 'perspective', type: 'number', default: '1200', description: 'Perspective in px, with rotateX.' },
+    { name: 'range', type: 'string', default: "'entry 0% cover 40%'", description: 'animation-range on the element\'s view timeline: which part of its passage the change spans.' },
+  ],
+  reducedMotion: 'No scrubbing; the element shows its end state.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Default range entry 0% → cover 40%: the change completes while the element is still in the lower half of the viewport, so it is settled by the time the reader reaches it.',
+    'Linear timing; a scrubbed animation with easing feels detached from the hand.',
+    'Reveal is a trigger, this is a binding. Use Reveal for entrances; use ScrollScrub when the motion must track the scroll.',
+  ],
+  related: ['reveal', 'parallax', 'card-stack'],
+  intents: ['scroll linked animation', 'scrub animation with scroll', 'animate on scroll position', 'scroll-driven transform', 'scrolltrigger scrub alternative'],
+  replaces: ['GSAP ScrollTrigger scrub: true', 'framer-motion useScroll + useTransform'],
+  fixture: { expect: 'class="ma-scrub"' },
+} satisfies ComponentMeta;

package/src/components/ShimmerButton.astro

@@ -0,0 +1,109 @@
+---
+/**
+ * ShimmerButton — a highlight sweeps across the body of a button on a loop,
+ * zero JS. The sheen is one pseudo-element gradient whose background-position
+ * animates: no layout, though every frame repaints the button's own box; the
+ * label sits above it. Hover lifts the button on the preset's hover travel and adds a
+ * ring; :focus-visible draws the same. Renders a <button> or an <a>.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'button'> {
+  /** Element to render. */
+  as?: 'button' | 'a';
+  /** For `as="a"`. */
+  href?: string;
+  /** Sheen colour. */
+  color?: string;
+  /** Button background. */
+  background?: string;
+  /** Label colour. */
+  text?: string;
+  /** Seconds per sweep, pause included. */
+  duration?: number;
+  /** Corner radius, any CSS length. */
+  radius?: string;
+}
+
+const { as: Tag = 'button', href, color = 'var(--ma-shine)', background = 'var(--ma-ink)', text = 'var(--ma-panel)', duration = 3, radius = '999px', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-shimmer-c:${color}`, `--ma-shimmer-bg:${background}`, `--ma-shimmer-fg:${text}`, `--ma-shimmer-dur:${duration}s`, `--ma-shimmer-r:${radius}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-shimmer', className]} href={Tag === 'a' ? href : undefined} type={Tag === 'button' ? 'button' : undefined} style={vars} {...rest}>
+  <slot />
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-shimmer) {
+      position: relative;
+      isolation: isolate;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: 0.5em;
+      padding: 0.7em 1.4em;
+      border: 1px solid color-mix(in srgb, var(--ma-shimmer-fg, var(--ma-panel)) 18%, transparent);
+      border-radius: var(--ma-shimmer-r, 999px);
+      background: var(--ma-shimmer-bg, var(--ma-ink));
+      color: var(--ma-shimmer-fg, var(--ma-panel));
+      font: inherit;
+      font-weight: 500;
+      line-height: 1.2;
+      text-decoration: none;
+      white-space: nowrap;
+      cursor: pointer;
+      overflow: clip;
+      transition:
+        translate var(--ma-duration-fast) var(--ma-ease-out),
+        box-shadow var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-shimmer)::before {
+      content: '';
+      position: absolute;
+      inset: -1px;
+      z-index: -1;
+      pointer-events: none;
+      background: linear-gradient(110deg, transparent 36%, var(--ma-shimmer-c, var(--ma-shine)) 50%, transparent 64%);
+      background-size: 250% 100%;
+      background-position: 120% 0;
+      animation: ma-shimmer var(--ma-shimmer-dur, 3s) var(--ma-ease-in-out) infinite;
+    }
+    @media (hover: hover) {
+      :where(.ma-shimmer:hover) {
+        translate: 0 calc(-0.5 * var(--ma-travel-hover));
+        box-shadow: 0 0 0 1px color-mix(in srgb, var(--ma-shimmer-c, var(--ma-shine)) 55%, transparent);
+      }
+    }
+    :where(.ma-shimmer:focus-visible) {
+      /* --ma-shimmer-ring: the label colour is the ring by default; a section whose button inverts on its ground sets
+         the ground's own text colour here, since a ring in the label colour is the ground's colour (HeroWaitlist, 7G) */
+      outline: 2px solid var(--ma-shimmer-ring, currentColor);
+      outline-offset: 3px;
+      box-shadow: 0 0 0 1px color-mix(in srgb, var(--ma-shimmer-c, var(--ma-shine)) 55%, transparent);
+    }
+    :where(.ma-shimmer:active) {
+      translate: 0 0;
+      scale: 0.98;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-shimmer)::before {
+        animation: none;
+        display: none;
+      }
+      :where(.ma-shimmer:hover) {
+        translate: 0 0;
+      }
+    }
+  }
+
+  @keyframes ma-shimmer {
+    0% {
+      background-position: 120% 0;
+    }
+    55%,
+    100% {
+      background-position: -30% 0;
+    }
+  }
+</style>

package/src/components/ShimmerButton.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ShimmerButton',
+  slug: 'shimmer-button',
+  title: 'Shimmer Button',
+  description: 'A highlight sweeps across the body of a button on a loop; hover lifts it on the preset\'s hover travel and adds a ring, and focus draws the same. One pseudo-element gradient whose position animates: no layout, though every frame repaints the button\'s own box. Renders a <button> or an <a>. Zero JavaScript.',
+  summary: 'A button with a shimmer that sweeps across it on a loop. It lifts on hover and draws a ring on focus.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['always', 'hover'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<ShimmerButton duration={3}>',
+  usage: `<ShimmerButton>Get started</ShimmerButton>\n<ShimmerButton as="a" href="/pricing/" color="oklch(90% 0.12 80)" background="oklch(45% 0.15 55)" text="#fff">See pricing →</ShimmerButton>`,
+  props: [
+    { name: 'as', type: "'button' | 'a'", default: "'button'", description: 'Element to render.' },
+    { name: 'href', type: 'string', description: 'For as="a".' },
+    { name: 'color', type: 'string', default: 'var(--ma-shine)', description: 'Sheen colour; the token is theme-aware.' },
+    { name: 'background', type: 'string', default: 'var(--ma-ink)', description: 'Button background.' },
+    { name: 'text', type: 'string', default: 'var(--ma-panel)', description: 'Label colour.' },
+    { name: 'duration', type: 'number', default: '3', description: 'Seconds per sweep, pause included.' },
+    { name: 'radius', type: 'string', default: "'999px'", description: 'Corner radius.' },
+    { name: '--ma-shimmer-ring', type: 'CSS colour (custom property)', default: 'currentColor', description: 'The focus ring\'s colour, the label colour by default. Set it in a rule or style on the button or any ancestor when the button inverts on its ground. The label colour is then the ground\'s colour and the ring vanishes; the ground\'s own text colour is the ring that reads.' },
+  ],
+  reducedMotion: 'The sheen is removed; a plain button that still lifts nothing on hover.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'The sheen runs 55 % of the period and rests the other 45 %: a loop that never pauses reads as a spinner.',
+    'The gradient is a pseudo-element behind the label (z-index −1 inside an isolated stacking context), so the text is never tinted.',
+    'Hover lifts by half the preset\'s hover travel: a button is heavier than a link.',
+    'Ring on hover and focus-visible come from the same declaration, so keyboard users see exactly what pointer users see.',
+  ],
+  related: ['arrow-button', 'shiny-text', 'border-beam'],
+  intents: ['shimmer button', 'shiny button', 'animated cta button', 'button with light sweep', 'glowing button astro'],
+  replaces: ['ShimmerButton (Magic UI)', 'ShinyButton (Magic UI)', 'HoverBorderGradient (Aceternity)'],
+  fixture: { slot: 'Fixture content for ShimmerButton', expect: 'Fixture content for ShimmerButton' },
+} satisfies ComponentMeta;

package/src/components/ShinyText.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * ShinyText — a highlight sweeps across the text on a loop, zero JS.
+ *
+ * The text is painted once in its own colour; a pseudo-element repeats it
+ * with a moving gradient clipped to the glyphs on top. Only background-
+ * position animates: no layout, but it is not composited either, so each
+ * frame repaints the text's own box.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** The text. */
+  text: string;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Seconds per sweep, including the pause. */
+  duration?: number;
+  /** Highlight colour. */
+  color?: string;
+  /** Width of the highlight as a fraction of the text, 0–1. */
+  width?: number;
+}
+
+const { text, as: Tag = 'span', duration = 3, color = 'var(--ma-shine)', width = 0.25, class: className, style, ...rest } = Astro.props;
+const half = Math.max(0.05, Math.min(width, 0.6)) * 50;
+// the caller's style joins the component's properties instead of replacing them (duration, colour and width were lost)
+const vars = [`--ma-shiny-duration:${duration}s`, `--ma-shiny-color:${color}`, `--ma-shiny-a:${50 - half}%`, `--ma-shiny-b:${50 + half}%`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-shiny', className]} data-text={text} style={vars} {...rest}>{text}</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-shiny) {
+      position: relative;
+      display: inline-block;
+    }
+    :where(.ma-shiny)::after {
+      /* the copy is paint only: the alternative text after the slash is empty, so assistive tech reads the sentence
+         once (generated content is part of an element's name). The first line is for engines without that syntax. */
+      content: attr(data-text);
+      content: attr(data-text) / '';
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      color: transparent;
+      background: linear-gradient(110deg, transparent var(--ma-shiny-a, 37.5%), var(--ma-shiny-color, var(--ma-shine)) 50%, transparent var(--ma-shiny-b, 62.5%));
+      background-size: 250% 100%;
+      background-position: 120% 0;
+      -webkit-background-clip: text;
+      background-clip: text;
+      animation: ma-shiny var(--ma-shiny-duration, 3s) var(--ma-ease-in-out) infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-shiny)::after {
+        animation: none;
+        opacity: 0;
+      }
+    }
+  }
+
+  @keyframes ma-shiny {
+    0% {
+      background-position: 120% 0;
+    }
+    60%,
+    100% {
+      background-position: -20% 0;
+    }
+  }
+</style>