@sharedex/ui 0.0.0-stage → 0.9.0

package/guides/buttons.md

@@ -0,0 +1,84 @@
+# Buttons
+
+`Button` is a button or a link that wears any number of effects at once: a fill, a border, a glow, a lift, a magnet,
+a label that rolls, a ripple, a loading state. Each effect is a plain description (`glowShine()`), so they stack and
+cost nothing until mounted.
+
+```tsx
+import { Button, glowShine, cursorMagnet } from "@sharedex/ui";
+
+// module level: an effect made during render would be a new object every render
+const primary = [glowShine(), cursorMagnet()];
+
+<Button effect={primary}>Book a table</Button>
+<Button as="a" href="/menu" variant="outline">See the menu</Button>
+<Button as={Link} href="/shop" effect={primary}>Shop</Button>   // a framework Link works too
+```
+
+In a project generated by the sharedex Design System Builder, the design's effects are ready as
+`primaryButtonEffects` in `design/effects.ts`, and `.claude/rules/design-system.md` gives the class recipe for the
+button's face. Use those; don't pick new effects.
+
+## How it is built
+
+```
+<button data-sx-btn="glowShine cursorMagnet" class={hitClassName}>   still: takes hover, press and focus
+  <span data-sx-btn-body>                                              moves (magnet, lift, tilt)
+    <span data-sx-btn-face class={className}>                         what you see
+```
+
+- **`className` styles what you see** (background, padding, radius); **`hitClassName`** the still outer element
+  (`w-full`, `self-start`, `group`).
+- **Hover belongs to the outer element.** The face never receives `:hover` itself, so Tailwind's `hover:` on
+  `className` does nothing. Put `group` in `hitClassName` and use `group-hover:` / `group-focus-visible:` on the face.
+- `variant`: `"solid"` (default), `"outline"`, `"ghost"`: a default look from the `sx-*` tokens. `unstyled` drops it,
+  for a face styled entirely by `className`.
+- Corners follow `--radius-sx-button` (the control radius, unless the design gives buttons their own shape).
+- `press={false}` turns off the small press every button gets.
+
+## Picking effects
+
+- **One moving thing per button, one always-moving button per screen.** Effects that would write the same motion
+  (two that move the button, two that resize it) fight: the last wins, and dev builds warn in the console.
+- Hover effects show only where hover exists (mouse, trackpad); on a phone, prefer press and state effects.
+- Effects marked mid or high (goo, electric border, liquid glass, refraction) wear a lighter version on weaker
+  devices, during server rendering and on the first paint. That is expected.
+- Reduced motion turns every effect off; the button still works and keeps its focus ring.
+
+## Loading, success, error
+
+```tsx
+import { Button, useButtonAction, stateSwap } from "@sharedex/ui";
+
+const save = useButtonAction(async () => { await saveForm(); }, { resetAfter: 2000 });
+
+<Button {...save} effect={stateSwap()} labels={{ loading: "Saving", success: "Saved", error: "Try again" }}>
+  Save
+</Button>
+```
+
+- While loading the button keeps its focus, ignores a second click (`aria-busy`, `aria-disabled`, never
+  `disabled`) and keeps its width. `labels` are shown in place of the label and announced to screen readers.
+- `progress` (0 to 1) feeds `stateProgress` and `stateRing`.
+
+## Server Components (Next.js App Router)
+
+Almost every effect is plain data: `<Button effect={glowShine()}>` works from a Server Component. Six carry code
+and need a client page or component (`"use client"`): `pressSpark`, `pressBurst`, `pressConfetti`, `pressSpray`,
+`labelScramble`, `glassRefract`. `onClick` and `useButtonAction` need one anyway.
+
+## In sections
+
+`actionEffect` on `Hero.Root` turns its actions into `Button`s: the first wears the effects, the others become
+outline buttons with none. Left out, the actions stay plain links.
+
+```tsx
+<Hero.Root layout="split" content={content} actionEffect={primaryButtonEffects} />
+```
+
+## Don't
+
+- Don't call effect factories during render or inline in JSX props of a component that re-renders often.
+- Don't put `hover:` classes on `className`; use `group` + `group-hover:`.
+- Don't set `outline: none` on a button or its face; the focus ring is drawn on the face.
+- Don't use `disabled` for a button that is busy; use `state="loading"`.

package/guides/contact.md

@@ -0,0 +1,84 @@
+# Contact
+
+How to reach the client: details, the project's own form, and an optional map.
+
+```tsx
+import { Contact } from "@sharedex/ui";
+
+<Contact.Root
+  layout="split-info"
+  content={{
+    title: "Come by or get in touch",
+    description: "We answer emails within a day.",
+    details: [
+      { label: "Address", value: "Rua das Flores 12, Lisbon", href: "https://maps.app.goo.gl/…" },
+      { label: "Phone", value: "+351 21 000 0000", href: "tel:+351210000000" },
+      { label: "Email", value: "hello@example.com", href: "mailto:hello@example.com" },
+      { label: "Opening hours", value: "Tue–Sun, 7:00–19:00" },
+    ],
+    map: { src: "https://www.openstreetmap.org/export/embed.html?…", title: "Map of our shop" },
+  }}
+>
+  <Contact.Info />
+  <Contact.Form>
+    <ContactForm />   {/* the project's form: fields, validation, sending */}
+  </Contact.Form>
+  <Contact.Map />
+</Contact.Root>
+```
+
+`Contact.Form` is only a slot in the layout. Build the form in the project with
+the project's form conventions and input recipe. Without children, the default
+composition is `Contact.Info` + `Contact.Map` (no form).
+
+## Layouts
+
+| `layout` | Use when |
+|---|---|
+| `split-info` | The standard: details beside the form, map full width below. |
+| `centered` | A short page or no map: one narrow centred column, details in a row. |
+| `map` | Location matters (shop, venue): details and form beside a tall map. |
+
+## Content
+
+```ts
+interface ContactContent {
+  eyebrow?: string;
+  title: string;          // <h2>
+  description?: string;
+  details?: { label: string; value: string; href?: string }[];  // rendered as a <dl>
+  map?: { src: string; title: string };  // an embeddable map URL; title is required for the iframe
+}
+```
+
+## Parts
+
+`Contact.Root` › `Contact.Info` (`Contact.Eyebrow`, `Contact.Title`,
+`Contact.Description`, `Contact.Details`) · `Contact.Form` (slot) ·
+`Contact.Map`.
+
+## Background
+
+`<Contact.Root background={<Background.Root effect={dotPattern()} />}>` draws a decorative layer behind
+the content (the section is its stacking context, so the content needs no z-index). Any effect from
+`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. Keep it still or nearly still: people are reading and typing here. Read
+`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
+
+## Reveal
+
+`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
+the info, then the form, then the map. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
+`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
+`node_modules/@sharedex/ui/guides/transitions.md`.
+
+## Text effects
+
+`titleEffect` and `eyebrowEffect` on `Root` put text effects on the title and the eyebrow (one, or a list that
+stacks): they render as `Text` wearing them. Left out, they stay plain elements. In a project the sharedex Design
+System Builder generated, pass the configured constants: `titleEffect={titleEffects}`, `eyebrowEffect={eyebrowEffects}`
+from `design/effects.ts`. Read `node_modules/@sharedex/ui/guides/text.md`.
+
+## Don't
+
+- Don't put the form's submit logic in the section; it lives with the form.
+- Don't embed a map without the client's address confirmed.

package/guides/gallery.md

@@ -0,0 +1,97 @@
+# Galleries: 3D carousels, the Ticker and the Grid (for Claude Code)
+
+Three ways to show a collection of cards that move:
+
+| You want | Use |
+|---|---|
+| A row of cards, one in focus, prev / next / drag | `<Carousel.Root>` with a layout preset |
+| Cards in a 3D shape (cylinder, spiral, globe …) | the same carousel with `barrel`, `helix`, `ring`, `staircase`, `fallAway`, `sphere` |
+| A strip that runs forever (logos, words, quotes) | `<Ticker>` |
+| A wall of cards you pan in every direction | `<Grid.Root>` + `<Grid.Viewport>` |
+
+Cards are always your markup. The package positions them; it never draws them.
+
+## Carousel shapes
+
+```tsx
+import { Carousel, barrel, helix, sphere } from "@sharedex/ui";
+
+const CONFIG = { layout: barrel(), autoplay: { enabled: false } };   // module level, or useMemo
+
+<Carousel.Root items={looks} config={CONFIG} slotClassName="w-[150px] h-[200px] mt-[150px]">
+  <Carousel.Viewport className="h-[520px]">
+    <Carousel.Track>
+      <Carousel.Window>{(slot) => <Carousel.Slot {...slot}><Card item={slot.item} /></Carousel.Slot>}</Carousel.Window>
+    </Carousel.Track>
+  </Carousel.Viewport>
+</Carousel.Root>
+```
+
+- **Keep layouts in module constants or `useMemo`.** A new layout object every render starts a morph.
+- 3D shapes reach past one card's box: give the Viewport a height, and push cards inside it with a margin
+  in `slotClassName` (`mt-[150px]`, `ml-[calc(50%-55px)]`).
+- `helix` is vertical with `engine: { axis: "y" }`; `barrel` / `ring` without an `angle` and `sphere` are
+  closed rings (every card mounted, the ring turns forever).
+
+## Gallery behaviours
+
+| Want | Write |
+|---|---|
+| A wave or a lean while it moves | `layout: modify(scale(), speedWave())`, `modify(barrel(), speedTilt())` |
+| The page scroll turns it | `useScrollLink(engine, { pxPerCard: 330, target: sectionRef })` + `physics: { drag: false }` |
+| Switch shapes with a morph | change `config.layout` (between module constants) |
+| Cards fly in / out | `engine: { enter: presence.contract(), exit: presence.scatter() }`; `await engine.hide()` / `show()` |
+| Open a card | `engine: { open: openView.detail() }` (or `panel()` + `<Carousel.Panel>`, `inline()`); a card's `onClick={() => engine.open(slot.itemIndex)}` |
+| Swipe cards off a deck | `config={stage(cardStack({ exit: "throw" }))}` (one-card mode: the Viewport sets the card size) |
+| Colour the page by the focused card | read `engine.position` with `useTransform` (it is the card index, fractional while moving) |
+
+## Ticker
+
+```tsx
+import { Ticker } from "@sharedex/ui";
+
+<Ticker items={logos} velocity={60} gap={32} fade={64} hoverSpeed={0} aria-label="Clients">
+  {(logo) => <img src={logo.src} alt={logo.name} className="h-8" />}
+</Ticker>
+```
+
+- `velocity` px/s: positive runs towards the reading start, negative the other way, `0` stops time.
+- Scroll bands: `velocity={0} offset={scrollY}` and `offset={useTransform(scrollY, (v) => -v)}` for the
+  opposite band (`useScroll` from `motion/react`).
+- `axis="y"` for columns (give it a height); `drag` to push it; `hoverSpeed={0}` to pause under the pointer
+  and keyboard focus (moving content needs a pause: WCAG 2.2.2).
+- Items can be any size. Copies are `aria-hidden` and `inert`; reduced motion keeps it still.
+
+## Grid
+
+```tsx
+import { Grid, gridOpen, type GridCell } from "@sharedex/ui";
+
+<Grid.Root items={pieces} columns={6} gap={24} cellClassName="w-[180px] h-[230px]"
+  tilt={{ x: 24, z: -8 }} bulge={140} fog snap open={gridOpen.panel()}
+  onActivate={(piece) => track(piece)} itemLabel={(piece) => piece.title}>
+  <Grid.Viewport className="h-[80vh]" aria-label="Collection">
+    {(cell: GridCell<Piece>) => <Card item={cell.item} />}
+  </Grid.Viewport>
+  <Grid.Panel>{(piece: Piece) => <Notes piece={piece} />}</Grid.Panel>
+</Grid.Root>
+```
+
+- **Annotate the cell** (`(cell: GridCell<Piece>)`): the Viewport can't see the Root's item type.
+- **No links or buttons inside cards.** The plane repeats every card forever; the Viewport is the one tab
+  stop. Use `onActivate` (a click that isn't a drag, or Enter) and `open`; put real controls in `Grid.Panel`.
+- **`draggable={false}` on images**, or the browser's image drag steals the pan.
+- Flat with no `bulge` / `fog` / `modifiers` is the cheapest (one transform for the whole plane). `wheel`
+  (pan with the mouse wheel) and `drift` (idle pan) are opt-in.
+- Open views: `gridOpen.zoom()`, `strip()` (big card + thumbnail strip), `panel()` (room for `Grid.Panel`).
+  Esc, a drag or a click beside the cards closes; `useGridCell()` tells a card if it is the open one.
+- The plane takes every touch gesture inside it (`touch-action: none`): on phones, leave page around it to
+  scroll by.
+
+## Don't
+
+- Don't rebuild a 3D carousel with a CSS `preserve-3d` wrapper around the Track: the Track's opacity
+  flattens it. The shapes place each card in 3D on their own.
+- Don't recreate layout, presence or open-view objects in render.
+- Don't put a `Ticker` or `Grid` inside an element with `overflow: hidden` and no height and expect it to
+  size itself: give the box a height (columns, grids) or a width (horizontal tickers fill it).

package/guides/hero.md

@@ -0,0 +1,114 @@
+# Hero
+
+The opening section of a page. Its title renders the page's only `<h1>`, so
+use one Hero per page, first.
+
+```tsx
+import { Hero } from "@sharedex/ui";
+
+<Hero.Root
+  layout="split"
+  content={{
+    eyebrow: "Since 1998",
+    title: "Fresh bread every morning",
+    description: "Order by 6 pm, pick up from 7 am.",
+    actions: [
+      { label: "Order for tomorrow", href: "/order" },
+      { label: "See the menu", href: "/menu" },
+    ],
+    media: { kind: "image", src: "/hero.jpg", alt: "Loaves cooling on a rack" },
+  }}
+/>
+```
+
+## Layouts
+
+| `layout` | Use when |
+|---|---|
+| `split` | A strong photo or illustration supports the message. Text beside media from 44rem section width, stacked below. |
+| `centered` | The message carries the page; media is secondary (16:9 below the text). |
+| `media-background` | The image IS the brand (a venue, a product shot). Media fills the section behind the text, with a scrim. Needs a photo with a calm area for text. |
+
+## Content
+
+```ts
+interface HeroContent {
+  eyebrow?: string;        // short context line above the title
+  title: string;           // the page's <h1>: one clear promise, not the company name
+  description?: string;    // one or two sentences
+  actions?: { label: string; href: string }[];  // first = primary, rest = secondary
+  media?:
+    | { kind: "image"; src: string; alt: string }
+    | { kind: "video"; src: string; label: string; poster?: string; autoPlay?: boolean }
+    | { kind: "node"; node: ReactNode };      // anything, e.g. a <Carousel.Root>
+}
+```
+
+## Parts
+
+`Hero.Root` (`<section aria-labelledby>`) › `Hero.Text` › `Hero.Eyebrow`,
+`Hero.Title` (`<h1>`), `Hero.Description`, `Hero.Actions` (links with
+`data-sx-variant="primary" | "secondary"`, or `Button`s with `actionEffect`) · `Hero.Media`.
+
+Every part takes `className` and `children` (children replace its default
+content).
+
+## Background
+
+`<Hero.Root background={<Background.Root effect={aurora()} />}>` draws a decorative layer behind the
+content (the section is its stacking context, so the content needs no z-index). Any effect from
+`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. With `layout="media-background"` the media covers the section above the background layer; use one or the other, or a transparent image over an effect. Read
+`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
+
+## Reveal
+
+`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
+the text, then the media (not in `media-background`: the picture is already there and the text appears over it). With `reveal` the default rise of the text is off. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
+`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
+`node_modules/@sharedex/ui/guides/transitions.md`.
+
+## Text effects
+
+`titleEffect` and `eyebrowEffect` on `Root` put text effects on the title and the eyebrow (one, or a list that
+stacks): they render as `Text` wearing them. Left out, they stay plain elements. In a project the sharedex Design
+System Builder generated, pass the configured constants: `titleEffect={titleEffects}`, `eyebrowEffect={eyebrowEffects}`
+from `design/effects.ts`.
+
+**A cycling word.** `content.titleWords` take turns after the title (`title: "We build"`, `titleWords: ["websites",
+"apps"]`); `titleCycle` on `Root` sets how they change (`{ look: "flip", interval: 3 }`). Every word is in the HTML,
+and the space is the longest word's. The title's effects go on its fixed words. Read `node_modules/@sharedex/ui/guides/text.md`.
+
+## Button effects
+
+`actionEffect` on `Root` renders the actions as `Button`s: the first wears the effects (one, or a list that stacks),
+the others become outline buttons with none. Left out, they stay plain links. In a project the sharedex Design System
+Builder generated, pass the configured constant: `actionEffect={primaryButtonEffects}` from `design/effects.ts`.
+Effects that carry code (`pressConfetti`, `labelScramble` …) need a client page. Read
+`node_modules/@sharedex/ui/guides/buttons.md`.
+
+## Restyling in a client project
+
+```tsx
+<Hero.Root layout="split" content={content}>
+  <Hero.Text>
+    <Hero.Eyebrow className="text-accent" />
+    <Hero.Title className="text-display text-foreground" />
+    <Hero.Description />
+    <Hero.Actions />
+  </Hero.Text>
+  <Hero.Media className="rounded-card shadow-card" />
+</Hero.Root>
+```
+
+- Action links use the project's button recipe automatically through the sx
+  tokens (corners from `--radius-sx-button`). To use the exact recipe classes
+  instead, render your own links (or `<Button>`s) inside `<Hero.Actions>`.
+- The hero text rises in once on load (the page's one entrance animation). It
+  is off under reduced motion and removed by `unstyled`.
+
+## Don't
+
+- Don't render a second `<h1>` elsewhere on the page.
+- Don't put the company name in `title`; it belongs in the header.
+- Don't use `media-background` with a busy photo and no `description` check:
+  read the text against the image at narrow width.

package/guides/services.md

@@ -0,0 +1,79 @@
+# Services
+
+What the client offers, as a list of items.
+
+```tsx
+import { Services } from "@sharedex/ui";
+
+<Services.Root
+  layout="cards-grid"
+  content={{
+    eyebrow: "What we bake",
+    title: "From the oven",
+    description: "Everything is made on site, the same day.",
+    items: [
+      { title: "Sourdough", description: "Crusty loaves with a 36-hour rise.", icon: <BreadIcon /> },
+      { title: "Catering", description: "Bread baskets for events.", href: "/catering" },
+    ],
+  }}
+/>
+```
+
+## Layouts
+
+| `layout` | Use when |
+|---|---|
+| `cards-grid` | 3–9 comparable items. As many columns as fit (each ≥ 16rem). An item image leads its card. |
+| `list` | Many items, or items that are mostly text. One row each, icon at the start; images are hidden. |
+| `alternating` | 2–4 key services that each deserve a photo. Image beside text, switching sides. Give every item `media`. |
+
+## Content
+
+```ts
+interface ServicesContent {
+  eyebrow?: string;
+  title: string;          // <h2>
+  description?: string;
+  items: {
+    title: string;        // <h3>; becomes a link when href is set
+    description: string;  // one sentence
+    href?: string;
+    icon?: ReactNode;     // decorative, rendered aria-hidden
+    media?: SectionMedia;
+  }[];
+}
+```
+
+## Parts
+
+`Services.Root` › `Services.Header` (`Services.Eyebrow`, `Services.Title`,
+`Services.Description`) · `Services.Items` (`<ul>`; takes a render function
+`(item, index) => ReactNode` to render one item yourself while keeping the list
+and layout).
+
+## Background
+
+`<Services.Root background={<Background.Root effect={dotPattern()} />}>` draws a decorative layer behind
+the content (the section is its stacking context, so the content needs no z-index). Any effect from
+`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. Cards sit on top of it; prefer a low-contrast pattern so card edges stay readable. Read
+`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
+
+## Reveal
+
+`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
+the header, then every item one by one. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
+`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
+`node_modules/@sharedex/ui/guides/transitions.md`.
+
+## Text effects
+
+`titleEffect` and `eyebrowEffect` on `Root` put text effects on the title and the eyebrow (one, or a list that
+stacks): they render as `Text` wearing them. Left out, they stay plain elements. In a project the sharedex Design
+System Builder generated, pass the configured constants: `titleEffect={titleEffects}`, `eyebrowEffect={eyebrowEffects}`
+from `design/effects.ts`. Read `node_modules/@sharedex/ui/guides/text.md`.
+
+## Don't
+
+- Don't mix items with and without images in `alternating`.
+- Don't use emoji as icons in a professional or minimal voice; use the
+  project's icon set.

package/guides/text.md

@@ -0,0 +1,93 @@
+# Text
+
+`Text` is a heading or a paragraph that wears any number of text effects: an entrance, a fill, an outline, a hover, a
+glitch. Each effect is a plain description (`enterRise()`), so they stack. `Typewriter`, `WordCycle`, `NumberRoll` and
+`TextPath` cover text that changes or follows a shape.
+
+```tsx
+import { Text, enterRise, inkGradient, WordCycle, NumberRoll } from "@sharedex/ui";
+
+// module level: an effect made during render would be a new object every render
+const title = [enterRise({ by: "chars" }), inkGradient()];
+
+<Text as="h2" effect={title}>Fresh bread, every morning</Text>
+<h1>We bake <WordCycle words={["bread", "cakes", "pies"]} look="flip" /></h1>
+<NumberRoll value={1250} format={{ style: "currency", currency: "EUR" }} />
+```
+
+In a project generated by the sharedex Design System Builder, the design's effects are ready in `design/effects.ts`:
+`titleEffects` for headings, `eyebrowEffects` for the short line above them. Use those; don't pick new ones.
+
+## How it is built
+
+```
+<h2 data-sx-text="enterRise inkGradient">
+  <span data-sx-text-read>Fresh bread, every morning</span>   what screen readers and search engines read, once
+  <span data-sx-text-show aria-hidden>…letters…</span>          what moves; hidden from screen readers
+```
+
+- **The words are in the HTML.** Words and letters are cut on the server; lines are measured in the browser once the
+  fonts have loaded. Without scripts, or under reduced motion, the text shows as it is, in its look.
+- **Children must be plain text** for effects that move letters, words or lines. Anything else moves as one piece.
+- `as` picks the element (`h1`, `h2`, `p`, `span` …); `className` and every other prop go on it.
+- Letters are cut only where they stand alone: Arabic and other joined scripts move word by word, and past 120 letters
+  a letter effect drops to words.
+
+## Picking effects
+
+- **One entrance per text, and effects only on headings.** One moving thing at a time reads; ten don't.
+- Effects stack when they write different things: an entrance (`enter*`) with a fill (`ink*`) or a hover
+  (`pointer*`) is fine. Two that write the same thing (two fills, two entrances) fight: the last wins, and dev builds
+  warn in the console.
+- The groups: `enter*` (arrive once in view), `ink*` (fills, shine, gradients), `stroke*` (outlines, underlines,
+  hand-drawn notes), `decode*` (scramble), `scrub*` (tied to the scroll), `pointer*` (under the mouse),
+  `warp*` (glitch, waves), `solid*` (depth, echo, particles, falling letters).
+- Hover effects show only where hover exists (mouse, trackpad). Mid and high effects (`warpShader`, `warpAscii`,
+  `warpGoo` …) wear a lighter version on weaker devices, during server rendering and on the first paint.
+
+## Server Components (Next.js App Router)
+
+Most effects are plain data and work from a Server Component. These need a client page or component
+(`"use client"`), because they carry code or pick a lighter version by device: `decodeHover`, `decodeReveal`,
+`decodeBinary`, `scrubSkew`, `inkLines`, `pointerProximity`, `pointerPressure`, `pointerJello`, `pointerTrail`,
+`pointerRipple`, `warpShader`, `warpFuzz`, `warpAscii`, `warpSquiggle`, `warpGoo`, `solidParticles`, `solidFall`.
+
+## In sections
+
+Every section's `Root` takes `titleEffect` and `eyebrowEffect`: set, the title and the eyebrow render as `Text`
+wearing them; left out, they stay plain elements.
+
+```tsx
+<Hero.Root layout="split" content={content} titleEffect={titleEffects} eyebrowEffect={eyebrowEffects} />
+```
+
+**A cycling word in the Hero's title.** `content.titleWords` take turns after the title, and `titleCycle` (WordCycle's
+settings) sets how. The title is the start of the sentence; the title's effects go on its fixed words.
+
+```tsx
+<Hero.Root content={{ title: "We build", titleWords: ["websites", "apps", "brands"] }} titleCycle={{ look: "flip" }} />
+```
+
+**About's figures roll.** `statRoll` (`true`, or NumberRoll's settings) makes each figure written as one number roll to
+it once in view, keeping what surrounds it: `"40+"` rolls to 40 and keeps its `+`; `"4.9/5"` rolls to 4.9. A figure
+that isn't one plain number (`"1 000"`, `"24h"` is fine) stays as written. The final value is in the HTML.
+
+```tsx
+<About.Root content={content} statRoll={{ look: "spin" }} />
+```
+
+## Don't
+
+- Don't call effect factories during render.
+- Don't put effects on body copy, links or buttons (buttons have their own: see `buttons.md`).
+- Don't set `letter-spacing` or `text-transform: uppercase` on Arabic text: it breaks the joins.
+- A `WordCycle` or `Typewriter` that keeps looping needs a way to pause it (WCAG 2.2.2: motion past 5 s). One control
+  for the whole page is enough: `usePauseLoops()` gives `[paused, setPaused]` for your own button, and every loop on
+  the page obeys it. Put the button somewhere stable (the header or footer), never inside the heading:
+
+  ```tsx
+  const [paused, setPaused] = usePauseLoops();
+  <button type="button" aria-pressed={paused} onClick={() => setPaused(!paused)}>
+    {paused ? "Play animations" : "Pause animations"}
+  </button>
+  ```

package/guides/transitions.md

@@ -0,0 +1,112 @@
+# Transitions (for Claude Code)
+
+Effects that play at a moment: a one-card carousel changing card, a section appearing as it scrolls
+into view, a part of the page tied to the scroll. Every transition is a factory returning a plain
+description (`wipe({ from: "start" })`); the host that plays it handles timing, device tiers and
+reduced motion.
+
+The idea behind all of them: **a transition is a function of one number, `p`** (0 = hidden,
+1 = shown). In a carousel `p` comes from the card's position, so dragging scrubs the transition; in a
+reveal it goes from 0 to 1 once the element is on screen.
+
+## Pick the right tool
+
+| You want | Use |
+|---|---|
+| A section's content to appear as it scrolls in | `reveal` on the section's `Root` |
+| Any other element to appear as it scrolls in | `<Reveal effect={fadeUp()}>` / `<Reveal.Group>` |
+| A full-width slideshow, one slide at a time | `<Carousel.Root config={stage(look)}>` |
+| A slideshow of photos blending with WebGL | `stage(fade({ crossFade: true }))` + `<Carousel.Shader>` |
+| A row of cards with a look | a layout preset: `scale`, `coverflow`, `panorama`, `expo`, `material`, `superFlow` … |
+| A section tied to the scroll (sticky, pinned, zooming) | `Curtain`, `StackCards`, `PinnedExpand`, `TextMaskZoom`, `SplitText` |
+
+## Section reveals
+
+```tsx
+import { Services, About, blurFade } from "@sharedex/ui";
+
+<Services.Root content={services} reveal />                       // fadeUp, parts 0.12 s apart
+<About.Root content={about} reveal={blurFade()} />
+<Services.Root content={services} reveal={{ effect: blurFade(), stagger: 0.1, delay: 0.2 }} />
+```
+
+The main parts play in order: Hero text then media (not the `media-background` backdrop), About
+text / stats / media, Services header then every card, Contact info / form / map. Options:
+`effect` (any CSS transition, default `fadeUp()`), `stagger`, `delay`, `duration`, `once` (true),
+`threshold` (0.15). Your own elements inside a section do not play: wrap them in `<Reveal>`.
+
+## Reveal anything else
+
+```tsx
+import { Reveal, fadeUp, wipe } from "@sharedex/ui";
+
+<Reveal effect={fadeUp()}><h2>Our work</h2></Reveal>
+<Reveal effect={wipe({ from: "start" })} delay={0.2}><img src="/team.jpg" alt="The team" /></Reveal>
+<Reveal.Group effect={fadeUp()} stagger={0.08} className="grid gap-6 sm:grid-cols-3">
+  {cards}
+</Reveal.Group>
+<Reveal effect={fadeUp()} trigger="scroll">…follows the scroll, forwards and back…</Reveal>
+```
+
+`Reveal.Group` wraps each child in one element: put grid classes on the group, sizing classes on
+`itemClassName`.
+
+## The transitions
+
+- **Everyday reveals**: `fadeUp`, `blurFade`, `zoomOut`.
+- **Masks** (both places): `wipe`, `iris`, `diagonal`, `splitCurtain`, `colorBlock`, `gradientMask`,
+  `blurSharp`, `pixelGrid`, `shutters`, `slicer` (needs a picture), `blinds`, `randomGrid`,
+  `columnWave`, `ink`, `gooey`.
+- **One-card carousel only**: `fade`, `cube`, `flip`, `push`, `cards`, `cardStack`, `tinder`,
+  `creative` (you set the leaving and coming states).
+- **Shaders** (WebGL, pictures only): `noiseBurn`, `ripple`, `displacement`, `stretchWarp`,
+  `pixelDissolve`, `chromaticShift`, `liquidMorph`, `crossZoom`, `swirl`, `dreamy`,
+  `directionalWarp`, `morph`, `gridFlip`, `pageCurl` (carousel only). Use them with
+  `<Carousel.Shader effect={…} image={(item) => item.src} />` or `<Reveal effect={…} image="/x.jpg">`.
+  A section inside a shader `Reveal` drops its own background colour: the picture is its backdrop and the
+  section's content sits on top (check the text stays readable on it). A section `background` effect would
+  still cover the picture, so pick one or the other.
+
+The docs site shows every one live, with its options.
+
+## One-card carousel
+
+```tsx
+import { Carousel, stage, cube, wipe } from "@sharedex/ui";
+
+const CONFIG = stage(cube());          // or stage(wipe()), stage() for a plain slide
+<Carousel.Root items={slides} config={CONFIG}>…Viewport › Track › Window › Slot…</Carousel.Root>
+```
+
+Keep `config` a module-level constant (a new object every render re-resolves the engine).
+`Carousel.Parallax` makes a layer of a card lag behind it (`amount`), in any look.
+
+## Multi-card looks and filters
+
+`layout: panorama()` (curved wall), `expo()` (the active card opens, the others make room),
+`material()` (Android's hero carousel: clipped strips beside one large card), `superFlow()` (cards
+lean while moving). `engine: { filterTransition: "view" }` makes a filter click move the cards that
+stay to their new place with the browser's View Transitions API, instead of fading everything.
+
+## Rules
+
+- **Default to CSS transitions.** They cost almost nothing and run on every device. Shaders have a
+  tier (`mid`, `high`): weaker devices, server rendering and WebGL failures show their CSS fallback.
+  You don't need to handle this.
+- **One shader carousel per page**, and pictures from the same origin (or served with CORS).
+- **Reduced motion is handled**: reveals become a short fade, carousel looks a fade, scroll parts
+  their end state. Don't add your own `prefers-reduced-motion` branches.
+- **RTL is handled**: "start" / "end" follow the reading direction.
+- **Content is in the HTML** before the transition plays (search engines read it); it is only
+  hidden until it is on screen.
+- **Sticky scroll parts** (`Curtain`, `StackCards`, `PinnedExpand`, `TextMaskZoom`) stop working
+  inside a parent with `overflow: hidden`. Use `overflow: clip` for rounded corners.
+
+## Don't
+
+- Don't reveal everything. One reveal per section, a short stagger; the Hero already has its own
+  entrance.
+- Don't put a shader transition on a section (`reveal` takes CSS transitions only).
+- Don't animate with your own `useEffect` + scroll listener: `Reveal trigger="scroll"` and the
+  scroll parts already use native scroll timelines, with a fallback.
+- Don't add GSAP or another animation library for these effects.