@sharedex/ui 0.0.0-stage → 0.10.0

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.

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@sharedex/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "Headless React components: an animated carousel with pure-function layout effects, page sections (Hero, About, Services, Contact) with layout presets and token-driven default looks, and 88 background effects (CSS, SVG, canvas, WebGL, Three.js) on one cheap runtime.",
+  "license": "MIT",
+  "author": "Mohamad Faseh <contact@mohamadfaseh.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohFaSeh/sharedex.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/MohFaSeh/sharedex#readme",
+  "bugs": {
+    "url": "https://github.com/MohFaSeh/sharedex/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./three": {
+      "types": "./dist/three.d.ts",
+      "default": "./dist/three.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./theme.css": "./theme.css",
+    "./styles/*": "./styles/*",
+    "./guides/*": "./guides/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "theme.css",
+    "styles",
+    "guides"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:only": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "motion": "^12.0.0 || ^13.0.0 || ^14.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": ">=0.165.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@types/three": "^0.186.0",
+    "motion": "^12.43.0",
+    "motion-dom": "^12.43.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "three": "^0.186.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/styles/about.css

@@ -0,0 +1,94 @@
+/* About: story | split-stats | centered */
+
+@layer components {
+  /* ---------- layout ---------- */
+
+  :where([data-sx-section="about"] [data-sx-part="about-inner"]) {
+    grid-template-areas: "text" "stats" "media";
+    align-items: start;
+  }
+  :where([data-sx-section="about"] [data-sx-part="about-text"]) {
+    grid-area: text;
+  }
+  :where([data-sx-section="about"] [data-sx-part="about-stats"]) {
+    grid-area: stats;
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
+    gap: var(--spacing-sx-gap);
+  }
+  :where([data-sx-section="about"] [data-sx-part="about-stat"]) {
+    display: flex;
+    flex-direction: column-reverse;
+  }
+  :where([data-sx-section="about"] [data-sx-part="about-media"]) {
+    grid-area: media;
+    aspect-ratio: 4 / 3;
+  }
+
+  /* story: media beside the text and figures */
+  @container (min-width: 44rem) {
+    :where([data-sx-section="about"][data-sx-layout="story"] [data-sx-part="about-inner"]) {
+      grid-template-columns: 1fr 1fr;
+      grid-template-areas: "media text" "media stats";
+      align-items: center;
+    }
+    :where([data-sx-section="about"][data-sx-layout="story"] [data-sx-part="about-media"]) {
+      aspect-ratio: 4 / 5;
+    }
+
+    /* split-stats: text and figures side by side, a wide image below */
+    :where([data-sx-section="about"][data-sx-layout="split-stats"] [data-sx-part="about-inner"]) {
+      grid-template-columns: 3fr 2fr;
+      grid-template-areas: "text stats" "media media";
+    }
+    :where([data-sx-section="about"][data-sx-layout="split-stats"] [data-sx-part="about-stats"]) {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      align-content: start;
+    }
+    :where([data-sx-section="about"][data-sx-layout="split-stats"] [data-sx-part="about-media"]) {
+      aspect-ratio: 21 / 9;
+    }
+  }
+
+  /* centered: a single centred column */
+  :where([data-sx-section="about"][data-sx-layout="centered"] [data-sx-part="about-text"]) {
+    justify-self: center;
+    max-width: 44rem;
+    text-align: center;
+  }
+  :where([data-sx-section="about"][data-sx-layout="centered"] [data-sx-part="about-stats"]) {
+    justify-items: center;
+    text-align: center;
+  }
+  :where([data-sx-section="about"][data-sx-layout="centered"] [data-sx-part="about-media"]) {
+    aspect-ratio: 16 / 9;
+  }
+
+  /* ---------- visual ---------- */
+
+  :where([data-sx-styled] [data-sx-part="about-body"] p) {
+    max-width: 65ch;
+    margin: calc(var(--spacing-sx-gap) * 0.5) 0 0;
+    text-wrap: pretty;
+  }
+  :where([data-sx-styled][data-sx-layout="centered"] [data-sx-part="about-body"] p) {
+    margin-inline: auto;
+  }
+  :where([data-sx-styled] [data-sx-part="about-stats"]) {
+    margin: 0;
+  }
+  :where([data-sx-styled] [data-sx-part="about-stat"]) {
+    padding-block-start: calc(var(--spacing-sx-gap) * 0.5);
+    border-block-start: 1px solid var(--color-sx-border);
+  }
+  :where([data-sx-styled] [data-sx-part="about-stat-value"]) {
+    margin: 0;
+    font-family: var(--font-sx-display);
+    font-size: var(--text-sx-title);
+    line-height: var(--text-sx-title--line-height);
+  }
+  :where([data-sx-styled] [data-sx-part="about-stat-label"]) {
+    color: var(--color-sx-muted);
+    font-size: 0.9em;
+  }
+}

package/styles/base.css

@@ -0,0 +1,145 @@
+/* Shared by every section. Layout rules first, then visual ([data-sx-styled]). */
+
+@keyframes sx-section-rise {
+  from {
+    opacity: 0;
+    translate: 0 0.75rem;
+  }
+}
+
+@layer components {
+  /* ---------- layout (kept by `unstyled`) ---------- */
+
+  /* Layouts respond to the width the section gets, not the viewport. The
+     section is a stacking context, so a `background` layer (z-index -1)
+     paints above its colour and below its content. */
+  :where([data-sx-section]) {
+    position: relative;
+    isolation: isolate;
+    container-type: inline-size;
+  }
+
+  :where([data-sx-section] > [data-sx-part$="-inner"]) {
+    box-sizing: border-box;
+    display: grid;
+    gap: var(--spacing-sx-gap);
+    width: 100%;
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1.5rem;
+  }
+
+  :where([data-sx-section] :is([data-sx-part$="-text"], [data-sx-part$="-header"], [data-sx-part$="-info"])) {
+    min-width: 0;
+  }
+
+  :where([data-sx-section] [data-sx-part$="-actions"]) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+
+  /* Media fills the box its layout gives it. */
+  :where([data-sx-section] [data-sx-part$="media"]) {
+    overflow: hidden;
+  }
+  :where([data-sx-section] [data-sx-part$="media"] :is(img, video, iframe)) {
+    display: block;
+    width: 100%;
+    height: 100%;
+    border: 0;
+    object-fit: cover;
+  }
+
+  /* ---------- visual (dropped by `unstyled`) ---------- */
+
+  :where([data-sx-section][data-sx-styled]) {
+    padding-block: var(--spacing-sx-section);
+    background: var(--color-sx-secondary);
+    color: var(--color-sx-ink);
+    font-family: var(--font-sx-body);
+    line-height: 1.6;
+  }
+
+  /* Inside a shader <Reveal>, the revealed picture is the section's backdrop:
+     its own colour would paint over it. */
+  :where([data-sx-tr-over] > [data-sx-section][data-sx-styled]) {
+    background: transparent;
+  }
+
+  :where([data-sx-styled] [data-sx-part$="-eyebrow"]) {
+    margin: 0 0 calc(var(--spacing-sx-gap) * 0.3);
+    color: var(--color-sx-primary);
+    font-size: 0.9em;
+    font-weight: 600;
+  }
+
+  :where([data-sx-styled] :is(h1, h2)[data-sx-part$="-title"]) {
+    margin: 0;
+    font-family: var(--font-sx-display);
+    font-size: var(--text-sx-title);
+    line-height: var(--text-sx-title--line-height);
+    text-wrap: balance;
+  }
+
+  :where([data-sx-styled] p[data-sx-part$="-description"]) {
+    max-width: 60ch;
+    margin: calc(var(--spacing-sx-gap) * 0.5) 0 0;
+    color: var(--color-sx-muted);
+    text-wrap: pretty;
+  }
+
+  :where([data-sx-styled] [data-sx-part$="-actions"]) {
+    margin-top: calc(var(--spacing-sx-gap) * 0.75);
+  }
+
+  :where([data-sx-styled] a[data-sx-part$="-action"]:not([data-sx-btn])) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 2.75rem;
+    padding: 0.75rem 1.5rem;
+    border: 1px solid var(--color-sx-primary);
+    border-radius: var(--radius-sx-button);
+    background: var(--color-sx-primary);
+    color: var(--color-sx-on-primary);
+    font-weight: 500;
+    text-decoration: none;
+    transition: background-color 200ms var(--ease-sx-out), border-color 200ms var(--ease-sx-out);
+  }
+  :where([data-sx-styled] a[data-sx-part$="-action"]:not([data-sx-btn]):hover) {
+    background: color-mix(in oklab, var(--color-sx-primary) 85%, var(--color-sx-ink));
+  }
+  :where([data-sx-styled] a[data-sx-part$="-action"]:not([data-sx-btn])[data-sx-variant="secondary"]) {
+    border-color: var(--color-sx-border);
+    background: transparent;
+    color: var(--color-sx-ink);
+  }
+  :where([data-sx-styled] a[data-sx-part$="-action"]:not([data-sx-btn])[data-sx-variant="secondary"]:hover) {
+    border-color: var(--color-sx-ink);
+    background: transparent;
+  }
+
+  /* a Button draws its own ring, on the part you see */
+  :where([data-sx-styled] :is(a, button, [tabindex]):not([data-sx-btn]):focus-visible) {
+    outline: 2px solid var(--color-sx-primary);
+    outline-offset: 2px;
+  }
+
+  :where([data-sx-styled] :is(p, dd, h3) a) {
+    color: inherit;
+    text-decoration-color: var(--color-sx-primary);
+    text-underline-offset: 0.2em;
+  }
+
+  :where([data-sx-styled] [data-sx-part$="media"]) {
+    border-radius: var(--radius-sx-card);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-styled] *) {
+      transition: none;
+      animation: none;
+    }
+  }
+}

package/styles/button.css

@@ -0,0 +1,48 @@
+/*
+ * The default look of Button, from the sx tokens. Imported by ../theme.css.
+ *
+ * Same contract as the section defaults (see .claude/rules/tailwind-theme.md): everything in `@layer components`,
+ * every selector in `:where()`, so a utility class on the button always wins. It applies only with
+ * `[data-sx-styled]`, which `unstyled` drops. It paints the face: the outer element takes the clicks and paints nothing.
+ */
+@layer components {
+  :where([data-sx-btn][data-sx-styled] > [data-sx-btn-body] > [data-sx-btn-face]) {
+    --sx-btn-bw: 1px; /* the border's width: layers reach over it, so a fill or a ring covers the whole button */
+    min-block-size: 2.75rem;
+    padding: 0.75rem 1.5rem;
+    border: 1px solid var(--color-sx-primary);
+    border-radius: var(--radius-sx-button);
+    background: var(--color-sx-primary);
+    color: var(--color-sx-on-primary);
+    font-weight: 500;
+    transition: background-color 200ms var(--ease-sx-out), border-color 200ms var(--ease-sx-out);
+  }
+  :where([data-sx-btn][data-sx-variant="outline"] > [data-sx-btn-body] > [data-sx-btn-face]) {
+    border-color: var(--color-sx-border);
+    background: transparent;
+    color: var(--color-sx-ink);
+  }
+  :where([data-sx-btn][data-sx-variant="ghost"] > [data-sx-btn-body] > [data-sx-btn-face]) {
+    border-color: transparent;
+    background: transparent;
+    color: var(--color-sx-ink);
+  }
+  /* a loading button is aria-disabled to block a second click, but it is busy, not disabled: it keeps its look */
+  :where([data-sx-btn][data-sx-styled]:is([aria-disabled="true"], :disabled):not([data-sx-btn-state="loading"]) > [data-sx-btn-body] > [data-sx-btn-face]) {
+    border-color: var(--color-sx-border);
+    background: var(--color-sx-border);
+    color: var(--color-sx-muted);
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    :where([data-sx-btn][data-sx-variant="solid"]:not([aria-disabled="true"], :disabled):hover > [data-sx-btn-body] > [data-sx-btn-face]) {
+      background: color-mix(in oklab, var(--color-sx-primary) 85%, var(--color-sx-ink));
+    }
+    :where([data-sx-btn][data-sx-variant="outline"]:not([aria-disabled="true"], :disabled):hover > [data-sx-btn-body] > [data-sx-btn-face]) {
+      border-color: var(--color-sx-ink);
+    }
+    :where([data-sx-btn][data-sx-variant="ghost"]:not([aria-disabled="true"], :disabled):hover > [data-sx-btn-body] > [data-sx-btn-face]) {
+      background: color-mix(in oklab, var(--color-sx-ink) 8%, transparent);
+    }
+  }
+}

package/styles/contact.css

@@ -0,0 +1,87 @@
+/* Contact: split-info | centered | map */
+
+@layer components {
+  /* ---------- layout ---------- */
+
+  :where([data-sx-section="contact"] [data-sx-part="contact-inner"]) {
+    grid-template-areas: "info" "form" "map";
+    align-items: start;
+  }
+  :where([data-sx-section="contact"] [data-sx-part="contact-info"]) {
+    grid-area: info;
+  }
+  :where([data-sx-section="contact"] [data-sx-part="contact-form"]) {
+    grid-area: form;
+    min-width: 0;
+  }
+  :where([data-sx-section="contact"] [data-sx-part="contact-map"]) {
+    grid-area: map;
+    aspect-ratio: 16 / 9;
+  }
+  :where([data-sx-section="contact"] [data-sx-part="contact-details"]) {
+    display: grid;
+    gap: calc(var(--spacing-sx-gap) * 0.5);
+  }
+
+  @container (min-width: 44rem) {
+    /* split-info: details beside the form, map underneath */
+    :where([data-sx-section="contact"][data-sx-layout="split-info"] [data-sx-part="contact-inner"]) {
+      grid-template-columns: 1fr 1fr;
+      grid-template-areas: "info form" "map map";
+    }
+    :where([data-sx-section="contact"][data-sx-layout="split-info"] [data-sx-part="contact-map"]) {
+      aspect-ratio: 21 / 9;
+    }
+
+    /* map: details and form stacked beside a tall map */
+    :where([data-sx-section="contact"][data-sx-layout="map"] [data-sx-part="contact-inner"]) {
+      grid-template-columns: 1fr 1fr;
+      grid-template-areas: "info map" "form map";
+    }
+    :where([data-sx-section="contact"][data-sx-layout="map"] [data-sx-part="contact-map"]) {
+      align-self: stretch;
+      aspect-ratio: auto;
+      min-block-size: 24rem;
+    }
+  }
+
+  /* centered: one narrow centred column */
+  :where([data-sx-section="contact"][data-sx-layout="centered"] :is([data-sx-part="contact-info"], [data-sx-part="contact-form"])) {
+    justify-self: center;
+    width: 100%;
+    max-width: 38rem;
+  }
+  :where([data-sx-section="contact"][data-sx-layout="centered"] [data-sx-part="contact-info"]) {
+    text-align: center;
+  }
+  :where([data-sx-section="contact"][data-sx-layout="centered"] [data-sx-part="contact-details"]) {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: var(--spacing-sx-gap);
+  }
+
+  /* ---------- visual ---------- */
+
+  :where([data-sx-styled] [data-sx-part="contact-details"]) {
+    margin: var(--spacing-sx-gap) 0 0;
+  }
+  :where([data-sx-styled][data-sx-layout="centered"] p[data-sx-part="contact-description"]) {
+    margin-inline: auto;
+  }
+  :where([data-sx-styled] [data-sx-part="contact-detail-label"]) {
+    color: var(--color-sx-muted);
+    font-size: 0.85em;
+    font-weight: 600;
+  }
+  :where([data-sx-styled] [data-sx-part="contact-detail-value"]) {
+    margin: 0;
+  }
+  :where([data-sx-styled] [data-sx-part="contact-form"]) {
+    box-sizing: border-box;
+    padding: calc(var(--spacing-sx-gap) * 0.75);
+    border: 1px solid var(--color-sx-border);
+    border-radius: var(--radius-sx-card);
+    background: color-mix(in oklab, var(--color-sx-ink) 3%, var(--color-sx-secondary));
+  }
+}