@sharedex/ui 0.0.0-stage → 0.10.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,107 @@
+# 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, built from @sharedex/ui's controls */}
+  </Contact.Form>
+  <Contact.Map />
+</Contact.Root>
+```
+
+`Contact.Form` is only a slot in the layout. Build the form in the project, from
+`@sharedex/ui`'s controls, wired the project's way (read
+`node_modules/@sharedex/ui/guides/forms.md`). Without children, the default
+composition is `Contact.Info` + `Contact.Map` (no form).
+
+```tsx
+"use client"; // React Hook Form runs in the browser; the section around it can stay a Server Component
+import { Field, Checkbox, ErrorSummary, Button } from "@sharedex/ui";
+import { fieldEffects, checkboxEffects, primaryButtonEffects } from "@/design/effects"; // those the design picked
+
+export function ContactForm() {
+  const { register, handleSubmit, formState: { errors, submitCount } } = useForm({ resolver, defaultValues, mode: "onTouched", shouldFocusError: false });
+  return (
+    <form noValidate onSubmit={handleSubmit(send)}>
+      <ErrorSummary errors={errors} attempt={submitCount} />
+      <Field label="Email" type="email" autoComplete="email" effect={fieldEffects} error={errors.email?.message} {...register("email")} />
+      <Field as="textarea" label="Message" rows={4} grow counter={1000} effect={fieldEffects} error={errors.message?.message} {...register("message")} />
+      <Checkbox label="I agree to the privacy notice" effect={checkboxEffects} error={errors.privacy?.message} {...register("privacy")} />
+      <Button type="submit" effect={primaryButtonEffects}>Send message</Button>
+    </form>
+  );
+}
+```
+
+After a successful send, `FormSwap` (`look="success"`) swaps the form for the thanks
+message and moves the focus to it, so a screen reader reads it.
+
+## 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/forms.md

@@ -0,0 +1,105 @@
+# Forms
+
+`@sharedex/ui`'s form controls each render the browser's own control (`<input>`, `<textarea>`, `<select>`, a checkbox,
+a radio, a range, a file input) and paint around it. The real control does the work: the label, the keyboard, autofill,
+password managers, screen readers, a plain form submit. Effects are plain descriptions (`inputFloat()`) that stack.
+Don't build inputs by hand.
+
+```tsx
+import { Field, Checkbox, Switch, Select, ErrorSummary, inputFloat, validColor, checkDraw } from "@sharedex/ui";
+
+// module level: an effect made during render is a new object every render
+const fieldEffects = [inputFloat(), validColor()];
+
+<Field label="Email" type="email" effect={fieldEffects} error={errors.email?.message} {...register("email")} />
+<Checkbox label="I agree to the terms" effect={checkDraw()} {...register("terms")} />
+```
+
+In a project generated by the sharedex Design System Builder, the design's effects are ready in `design/effects.ts`,
+one list per kind of control: `fieldEffects` (`Field`, `NumberField`), `checkboxEffects` (`Checkbox`, `CheckGroup`),
+`radioEffects` (`RadioGroup`), `switchEffects` (`Switch`), `pickerEffects` (`Select`, `Combobox`, `TagsField`),
+`rangeEffects` (`Range`); only the ones the design picked exist. Use those; don't pick new ones. The look of fields is
+the design's: pass nothing, or `variant` as `.claude/rules/design-system.md` says.
+
+## The controls
+
+| Need | Control | Value |
+|---|---|---|
+| Text, email, password, a message | `Field` (`as="textarea"`; `clearable`, `reveal`, `counter`, `strength`, `status`, `hint`, `grow`; `inline` inside a sentence) | native: `register` |
+| One choice, on or off | `Checkbox`, `Switch` | native |
+| Several choices | `CheckGroup` (select all, a count), `ChipGroup` (filter chips) | native (a list) |
+| One of a few | `RadioGroup` (cards, segments, stars through effects), `ChipGroup multiple={false}` | native |
+| One of many | `Select` (the real `<select>`) | native |
+| Search, many at once, your own words | `Combobox` (`multiple`, `creatable`, `loading`), `TagsField` | a list: `Controller` |
+| A number | `NumberField` (steps, scrub), `Range` (one or two thumbs) | native (`valueAsNumber`); two thumbs: `Controller` |
+| A one-time code, a PIN | `OtpField` (`mask` for a PIN) | native |
+| Files | `FileDrop` (`accept`, `maxSize`, `maxFiles`, `reorder`, `page`, `progress`) | `File[]`: `Controller` |
+| Errors | `ErrorSummary` (takes the focus on submit), `focusFirstError(form)` | |
+| Flow | `FormSteps` (`Root` / `Step` / `Progress` / `Next` / `Back`), `FormReveal`, `FormSwap` | |
+| Small widgets | `InlineEdit`, `SaveStatus`, `PasswordRules`, `FormBuddy` (a sign-in companion) | |
+
+## Wiring (React Hook Form + Zod)
+
+```tsx
+// the schema is a module-level constant; only the resolver changes, with the language
+const resolver = useMemo(() => zodResolver(schema, { error: makeZodErrorMap(t) }), [t, i18n.language]);
+const { register, control, handleSubmit, formState: { errors, submitCount } } = useForm({
+  resolver, defaultValues, mode: "onTouched", shouldFocusError: false,
+});
+
+<form noValidate onSubmit={handleSubmit(send)}>
+  <ErrorSummary errors={errors} attempt={submitCount} />
+  <Field label={t("name")} effect={fieldEffects} error={errors.name?.message} {...register("name")} />
+  <RadioGroup label={t("plan")} options={plans} error={errors.plan?.message} {...register("plan")} />
+  <Controller name="topics" control={control} render={({ field }) => (
+    <Combobox label={t("topics")} multiple options={topics} error={errors.topics?.message} {...field} />
+  )} />
+  <Controller name="files" control={control} render={({ field }) => (
+    <FileDrop label={t("files")} accept="image/*,.pdf" maxSize={5_000_000} error={errors.files?.message} {...field} />
+  )} />
+</form>
+```
+
+- **Every prop and the `ref` land on the real control**, so `register()` spreads straight onto `Field`, `Checkbox`,
+  `CheckGroup`, `RadioGroup`, `Switch`, `Select`, `ChipGroup`, `OtpField`, `NumberField` and a one-thumb `Range`. A value
+  no native control holds (a list, files) goes through a `Controller`'s `field`, as it is.
+- **The error's words go in `error`.** The control then sets `aria-invalid`, points `aria-describedby` at the message,
+  and announces it. A red line or a shake is never the only signal.
+- `mode: "onTouched"` checks a field when it is first left, then live: the same moment `:user-invalid` picks. Complete
+  `defaultValues`: `""` for text, `false` for a checkbox, `[]` for lists, `undefined` for a radio group.
+- The error map goes in per parse, never through `z.config()` (it is global and would mix languages on a server). The
+  server action re-runs `schema.safeParse(values, { error: makeZodErrorMap(t) })` in the sender's language and returns
+  the first message.
+- **A plain form works too**: every control submits its value by name (lists as several inputs, files in the real file
+  input), and the browser's own checks (`required`, `type`, `pattern`) drive the same error looks.
+- **Files go from the browser to storage** (a signed upload address); the form sends their addresses. `FileDrop`'s
+  `progress(file)` shows how far each got.
+
+## Effects
+
+Each control takes `effect`: one effect or a list; they stack. Effect names start with their control: `input*` and
+`valid*` (Field), `check*`, `radio*`, `switch*`, `picker*` / `list*` / `chipPop` (Select, Combobox, TagsField), `range*`,
+`chip*` (ChipGroup), `file*` (FileDrop), `step*` (FormSteps). A control warns in development about an effect made for
+another one, and about two effects that move the same thing (the last wins: keep one).
+
+- **One look per moment.** A floating label with an underline and a red/green border reads well; five label effects
+  don't.
+- **Server Components:** the controls are client components that a Server Component can render, and almost every
+  effect is plain data. `checkConfetti`, `rangeElastic` and `inputCycle` (unless `vanish: false`) carry code: the
+  component holding them starts with `"use client"`. `FormReveal` needs no client code at all.
+- **Reduced motion** keeps every state (an error's colour and words, a check, a chosen option) and drops the movement.
+  Endless loops (`inputBeam`, `inputSkeleton`, `switchNeon`) pause off screen and with the page's pause switch
+  (`usePauseLoops`).
+
+## Rules
+
+- A real `<label>` for every control (`label`, or `aria-label` where the sentence names it, as with `inline`). A
+  placeholder never replaces a label.
+- Text inputs stay at 16 px or more on phones (the base sheet does it: don't shrink them), so iOS doesn't zoom in.
+- Restyle with `className` (the box you see), `rootClassName` (the whole control), `labelClassName`; your utility
+  classes win over the defaults. `unstyled` drops the look and keeps the structure.
+- Every built-in word ("Show password", "Clear", "No results", "Drop files here") is a `labels` prop: pass it
+  translated.
+- RTL works through logical properties: slides, lines and thumbs follow the reading direction. A code (`OtpField`)
+  always reads left to right.
+- `Contact.Form` is the place for a contact form: see [contact.md](contact.md).

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.