@spunto/design-system 0.15.0 → 0.16.0

package/README.md

@@ -4,6 +4,16 @@ Spunto's shared design system — the warm/flame **tokens**, JS **color constant
 and the base **UI primitives** used across Spunto apps (the dashboard and Spunto
 Lite). One source of truth so replicated features stay visually consistent.
 
+> **Built on [shadcn/ui](https://ui.shadcn.com).** This package is an adaptation of
+> shadcn/ui, not a design system written from scratch. Its token names and structure,
+> its `cva` + `cn` variant pattern, and most of its primitives were copied from
+> shadcn/ui (the Base UI variant) and then restyled for the Spunto palette and
+> extended with Spunto-specific components. Full credit for the original design and
+> API goes to [shadcn](https://github.com/shadcn) and the
+> [shadcn-ui/ui](https://github.com/shadcn-ui/ui) contributors — MIT licensed, and
+> the reason this package exists at all. If you're not tied to Spunto's look, use
+> shadcn/ui directly.
+
 ## Usage
 
 Import the tokens once in your app's entry CSS, right after Tailwind:
@@ -36,6 +46,9 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   → Tailwind color/radius mapping, a minimal base layer, and the `dot-grid` /
   `grid-lines` background utilities. Brand color is **flame** (`--primary` ≈ `#ea5400`);
   radius base is `0.25rem`; `Build`/`Ship`/`Run` are semantic (`bg-build`, `text-run`…).
+  Plus the two **unthemed** marketing surfaces — `--night` (`bg-night`) and
+  `--code-surface` (`bg-code-surface`) — and the `night-grid` / `night-glow-a`
+  / `night-glow-b` / `night-scroll` utilities they come with.
 - **`cn`** — `clsx` + `tailwind-merge`.
 - **`./colors`** — `cssVar`, `chartColors`, `chartRamp`, `segColors` for JS/chart contexts.
 - **Primitives** — form + layout building blocks styled on `@base-ui/react`:
@@ -102,11 +115,16 @@ import { Button, Card } from "@spunto/design-system"
 import { WorkerCard } from "@spunto/design-system/workers"                                  // domain
 import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
 import { ProjectForm, ProjectPanel } from "@spunto/design-system/projects"                   // domain
+import { Section, ProductHeader } from "@spunto/design-system/marketing"                     // not a domain — see below
 ```
 
 One entry **per domain**, not per component: a project's form and a project's
 panel are the same concept seen twice, so they share `/projects`.
 
+`/marketing` is the exception that proves the rule: it knows no Spunto concept
+(that's exactly why the product registry stayed in the site), but it carries
+opinions a dashboard doesn't want, so it gets an entry too.
+
 ### `@spunto/design-system/workers`
 
 - **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
@@ -254,6 +272,72 @@ And the read-only twin of that form:
 - **Container queries** here too: the panel is 288 px in a sidebar on a 27" screen
   and full width on a phone — and the desktop case is the narrow one.
 
+## Marketing — `/marketing`
+
+```tsx
+import { Section, H2, Kicker, SpecList, Disclosure, CodeBlock, Figure,
+         CopyCommand, NightBand, NightChip, ProductHeader, Reveal,
+         usePrefersReducedMotion, useLoopClock } from "@spunto/design-system/marketing"
+```
+
+The vocabulary of a **marketing page** — a numbered chapter, a display headline,
+a mono kicker, key/value rows, a disclosure row, a copyable command, a night
+band. Its own entry rather than the root, for two reasons: an app that draws a
+dashboard has no use for it, and these primitives carry opinions the root
+deliberately doesn't (a display face, a fixed dark surface).
+
+- **`Section`** — the chapter: hairline, number in the accent, mono title,
+  margin `note`, then the content. Repeating one opening down a page is what
+  makes it read as a document rather than a stack of blocks.
+- **`H2`** / **`Kicker`** — the display headline (Syne, capped at 24ch) and the
+  mono line above it. **One `Kicker`, not two**: the site had `Kicker` and
+  `Eyebrow` doing the same job under two names and two letter-spacings; the wider
+  one is now a `className`.
+- **`SpecList`** — key/value rows, the default way to list facts without bullets.
+- **`Disclosure`** — the row you open. `<details name>` gives the exclusive
+  accordion natively: no state, no hydration surface, and it works before the JS
+  lands.
+- **`CodeBlock`** / **`Figure`** — a snippet on the `--code-surface` token
+  (deliberately unhighlighted: a highlighter is a dependency and ~30 kB for a
+  six-line snippet), and a framed, captioned screenshot whose **image element is
+  a slot** (`render.image`) — same rule as links, the package never imports
+  `next/image`.
+- **`CopyCommand`** — the call to action when it's a command. **One component,
+  two registers** (`tone="day" | "night"`), where the site had `CopyCommand` and
+  `NightCommand`: same behaviour, two files, two places to fix a bug. What lands
+  in the clipboard is the joined-up one-liner, not the wrapped version.
+- **`NightBand`** / **`NightChip`** — the dark band a page opens on, lit by its
+  `glow` accent. `--night` is *not themed*: it's the dark moment of the page, so
+  it stays deeper than the dark theme's own background and identical in both.
+  The drifting light sources are CSS animations (stopped by
+  `prefers-reduced-motion`), never a rAF loop.
+- **`ProductHeader`** — mark, name, kind, headline, promise, the one command, the
+  chips. **Generalised on the way in**: the site's version took a `Product` out
+  of its own registry, this one knows about no product at all — everything
+  product-specific goes through `actions`.
+- **`Reveal`** + **`usePrefersReducedMotion`** / **`useLoopClock`** — scroll
+  reveal as an `IntersectionObserver` and a CSS transition, and the "how far into
+  the loop are we" clock that pauses off screen and commits at ~14 Hz.
+
+Two rules the package enforces here:
+
+- **No framework imports.** No `next/link`, no `next/image`. Navigation is the
+  caller's (`actions` slots), and `Figure` takes an image `render` slot — the
+  same motif as `CommandPaletteLinkRender` and `WorkerCard`'s `render.link`.
+- **No motion library.** `framer-motion` as a hard dependency would weigh on
+  every consumer, including the ones that never draw a landing page. `Reveal` is
+  ~20 lines of observer + transition instead.
+
+`Section`, `H2`, `Kicker`, `SpecList`, `Disclosure`, `CodeBlock`, `Figure`,
+`NightBand`, `NightChip` and `ProductHeader` carry **no `"use client"`** — they
+render from a React Server Component. Only `CopyCommand`, `Reveal` and the hooks
+are client files. (Same split, same care, as `buttonVariants`/`alertVariants`.)
+
+**What stays in the site, on purpose:** the product registry and anything reading
+it, the navs and footers (they hard-code URLs and a session), the product logos
+and OG cards. The rule: *if it needs to know a product, a URL or a session, it's
+the site; if it only lays out or types, it's the system.*
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once
@@ -323,6 +407,21 @@ Adding a component = add its entry to `content/components.ts` + a demo file in
 `showcase/src/demos/`; the visual page and its `.md` are then produced
 automatically (see `showcase/vite-plugin-llms.ts`).
 
+## Credits
+
+- **[shadcn/ui](https://ui.shadcn.com)** ([shadcn-ui/ui](https://github.com/shadcn-ui/ui), MIT) —
+  **the base of this package.** The token contract (`--background`/`--foreground`,
+  `--card`, `--muted-foreground`, `--primary`, `--ring`…), the `cn` helper, the
+  `cva` variant pattern and most primitives here started as shadcn/ui components
+  (Base UI variant) and were restyled, not reinvented. The parts that are ours are
+  the palette values, the `Build`/`Ship`/`Run` semantics, and the Spunto-specific
+  components (`Terminal`, `TerminalPanel`, `ImagePull`, and everything under the
+  domain sub-exports).
+- **[Base UI](https://base-ui.com)** (MIT) — the unstyled primitives underneath.
+- **[Tailwind CSS](https://tailwindcss.com)** (MIT) — the styling pipeline.
+- **[xterm.js](https://xtermjs.org)** (MIT) — the terminal surface.
+- **[lucide](https://lucide.dev)** (ISC) — the icons.
+
 ## Peer requirements
 
 - React 19+, and a **Tailwind CSS v4** pipeline in the consuming app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./src/components/projects/index.ts",
       "import": "./src/components/projects/index.ts"
     },
+    "./marketing": {
+      "types": "./src/components/marketing/index.ts",
+      "import": "./src/components/marketing/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"

package/src/components/marketing/code-block.tsx

@@ -0,0 +1,89 @@
+// Snippets and screenshots — the two ways a marketing page shows the product
+// rather than describing it. Both static, both server-renderable.
+
+import type { ReactElement, ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/* ─── CodeBlock ────────────────────────────────────────────────────────────
+   A real snippet (a compose file, a script, an import), on the same warm dark
+   surface as every other terminal-ish panel — the `--code-surface` token
+   (`bg-code-surface`), so the value lives in `styles.css` and not as a magic
+   `oklch(…)` string recopied into each component.
+
+   Deliberately unhighlighted: a syntax highlighter is another dependency and
+   another 30 kB on a marketing page, and these snippets are six lines long. A
+   consumer that wants highlighting renders its own `<pre>` inside the frame. */
+
+export interface CodeBlockProps {
+  code: string
+  /** Optional filename bar above the snippet. */
+  filename?: ReactNode
+  className?: string
+}
+
+export function CodeBlock({ code, filename, className }: CodeBlockProps) {
+  return (
+    <div translate="no" className={cn("overflow-hidden rounded-lg border border-border", className)}>
+      {filename && (
+        <div className="border-b border-border bg-card px-4 py-2 font-mono text-[10.5px] uppercase tracking-[0.14em] text-muted-foreground">
+          {filename}
+        </div>
+      )}
+      <pre className="night-scroll overflow-x-auto bg-code-surface px-4 py-4 font-mono text-[11.5px] leading-[1.8] text-stone-200 md:text-[12.5px]">
+        <code>{code}</code>
+      </pre>
+    </div>
+  )
+}
+
+/* ─── Figure — a real screenshot, framed and captioned ─────────────────────
+   Marketing illustrations are product screenshots rather than drawings, so they
+   get a browser-ish frame and a caption saying what you're looking at.
+
+   The image element is a **slot**, for the same reason links are: the package
+   never imports `next/image` (or any framework primitive). Default is a plain
+   `<img>`; a Next app passes `render={{ image: (p) => <Image {...p} /> }}` and
+   gets its optimizer back. */
+
+export interface FigureImageProps {
+  src: string
+  alt: string
+  width: number
+  height: number
+  className?: string
+}
+
+export type FigureImageRender = (props: FigureImageProps) => ReactElement
+
+export interface FigureProps {
+  src: string
+  alt: string
+  caption?: ReactNode
+  width: number
+  height: number
+  render?: { image?: FigureImageRender }
+  className?: string
+}
+
+export function Figure({ src, alt, caption, width, height, render, className }: FigureProps) {
+  const image = render?.image ?? ((props: FigureImageProps) => <img {...props} alt={props.alt} />)
+
+  return (
+    <figure className={className}>
+      <div className="overflow-hidden rounded-lg border border-border bg-card">
+        <div className="flex items-center gap-1.5 border-b border-border px-3 py-2" aria-hidden>
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+          <span className="h-2.5 w-2.5 rounded-full bg-border" />
+        </div>
+        {image({ src, alt, width, height, className: "w-full" })}
+      </div>
+      {caption && (
+        <figcaption className="mt-2.5 font-mono text-[10px] uppercase tracking-[0.14em] text-muted-foreground/60">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  )
+}

package/src/components/marketing/copy-command.tsx

@@ -0,0 +1,139 @@
+"use client"
+
+import { useEffect, useRef, useState, type ReactNode } from "react"
+import { CheckIcon, CopyIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+/* ─── CopyCommand — the call to action, when it's a command ────────────────
+   The primary action on an infrastructure landing is usually a command rather
+   than a signup form, so it gets the care a button would: the copy affordance
+   is always visible (there is no hover on a phone), and what lands in the
+   clipboard is the joined-up one-liner, not the pretty wrapped version.
+
+   **One component, two registers.** The site had this twice — `CopyCommand` on
+   the light document and `NightCommand` on the dark band, same behaviour, two
+   files, two places to fix a bug. Here it's one component and a `tone`:
+
+     - `"day"`   — bordered card on the light document, dark `<pre>` inside.
+     - `"night"` — translucent black on a `NightBand`, no opaque surface of its
+                   own so the band's glow shows through.
+
+   `accent` colours the `$` prompt (and, in the night register, is the only warm
+   thing in the block) — a page passes its own product accent. */
+
+export type CommandTone = "day" | "night"
+
+export interface CopyCommandProps {
+  command: string
+  /** Mono label in the bar — "your machine", "on each node you connect"… */
+  caption?: ReactNode
+  /** Small print under the block. */
+  note?: ReactNode
+  tone?: CommandTone
+  /** Any CSS colour, used for the `$` prompt. */
+  accent?: string
+  className?: string
+  /** Label of the copy button, for screen readers. */
+  copyLabel?: string
+}
+
+export function CopyCommand({
+  command,
+  caption,
+  note,
+  tone = "day",
+  accent,
+  className,
+  copyLabel = "Copy the command",
+}: CopyCommandProps) {
+  const [copied, setCopied] = useState(false)
+  // A visitor who copies then navigates away would otherwise leave a 2s timer
+  // behind, firing setState on an unmounted component.
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  useEffect(() => () => void (timer.current && clearTimeout(timer.current)), [])
+
+  function copy() {
+    // The multi-line form is for reading; what gets pasted is the one-liner.
+    const text = command.replace(/\\\n\s*/g, "")
+    navigator.clipboard
+      ?.writeText(text)
+      .then(() => {
+        setCopied(true)
+        if (timer.current) clearTimeout(timer.current)
+        timer.current = setTimeout(() => setCopied(false), 2000)
+      })
+      .catch(() => {
+        /* Denied permission / insecure context: the command is still selectable. */
+      })
+  }
+
+  const night = tone === "night"
+
+  return (
+    <div className={className}>
+      <div
+        translate="no"
+        className={cn(
+          "overflow-hidden rounded-lg border",
+          night ? "border-white/15 bg-black/30 backdrop-blur-sm" : "border-border"
+        )}
+      >
+        <div
+          className={cn(
+            "flex items-center justify-between gap-3 border-b px-3 py-2 font-mono text-[10.5px] uppercase tracking-[0.14em] md:px-4",
+            night ? "border-white/10 text-stone-400" : "border-border bg-card text-muted-foreground"
+          )}
+        >
+          <span className="truncate">{caption ?? "your machine"}</span>
+          <button
+            type="button"
+            onClick={copy}
+            aria-label={copyLabel}
+            className={cn(
+              "inline-flex shrink-0 items-center gap-1.5 rounded-md border px-2 py-1 text-[10px] uppercase tracking-[0.14em] transition-colors",
+              night
+                ? "border-white/15 hover:border-white/35 hover:text-white"
+                : "border-border hover:border-primary/40 hover:text-foreground"
+            )}
+          >
+            {copied ? (
+              <>
+                <CheckIcon className={cn("h-3 w-3", night ? "text-emerald-400" : "text-emerald-500")} />
+                copied
+              </>
+            ) : (
+              <>
+                <CopyIcon className="h-3 w-3" />
+                copy
+              </>
+            )}
+          </button>
+        </div>
+        <pre
+          className={cn(
+            "night-scroll overflow-x-auto px-3 py-3.5 font-mono text-[11px] leading-[1.75] text-stone-200 md:px-4 md:text-[12px]",
+            // On the band the block stays translucent; on the document it needs
+            // its own dark surface, the same one CodeBlock uses.
+            !night && "bg-code-surface"
+          )}
+        >
+          <code>
+            <span
+              className={cn("select-none", !accent && !night && "text-primary", !accent && night && "text-flame")}
+              style={accent ? { color: accent } : undefined}
+            >
+              ${" "}
+            </span>
+            {command}
+          </code>
+        </pre>
+      </div>
+      {note && (
+        <p className={cn("mt-2.5 text-[12.5px] leading-relaxed", night ? "text-stone-400" : "text-muted-foreground")}>
+          {note}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/components/marketing/index.ts

@@ -0,0 +1,55 @@
+// @spunto/design-system/marketing — the vocabulary of a marketing page.
+//
+// Fourth sub-export, after `/workers`, `/devcontainer` and `/projects`, and the
+// first one that isn't a Spunto domain: these are layout and typography
+// primitives — a numbered chapter, a display headline, a mono kicker, key/value
+// rows, a disclosure row, a copyable command, a night band. They live behind
+// their own entry rather than in the root because an app that draws a dashboard
+// has no use for them, and because they carry their own opinions (a display
+// face, a fixed dark surface) that the root primitives deliberately don't.
+//
+// **The rule for what belongs here**, applied on the way in and worth keeping:
+// if a component needs to know a product, a URL or a session, it stays in the
+// site. If it only lays out or types, it comes here. That is why the site's
+// product registry, its navs and footers, its product logos and its OG cards
+// did *not* travel — they are the site, not the system.
+//
+// Two constraints the package enforces that the site's own kits didn't have to:
+//
+//   - **No framework imports.** No `next/link`, no `next/image`. Navigation is
+//     the caller's (`actions` slots, plain children) and `Figure` takes an image
+//     `render` slot — the same motif as `CommandPaletteLinkRender` and
+//     `WorkerCard`'s `render.link`.
+//   - **No motion library.** `Reveal` is an IntersectionObserver and a CSS
+//     transition; `useLoopClock` is one rAF. A design system doesn't put
+//     `framer-motion` in the bundle of consumers who never draw a landing page.
+//
+// Server components: everything static (`Section`, `H2`, `Kicker`, `SpecList`,
+// `Disclosure`, `CodeBlock`, `Figure`, `NightBand`, `NightChip`,
+// `ProductHeader`) is free of `"use client"` and renders on the server. Only
+// `CopyCommand`, `Reveal` and the hooks are client files.
+
+export { Section, H2, Kicker, SpecList, Disclosure } from "./section"
+export type { SectionProps, H2Props, KickerProps, SpecListProps, DisclosureProps } from "./section"
+
+export { CodeBlock, Figure } from "./code-block"
+export type { CodeBlockProps, FigureProps, FigureImageProps, FigureImageRender } from "./code-block"
+
+export { CopyCommand } from "./copy-command"
+export type { CopyCommandProps, CommandTone } from "./copy-command"
+
+export { NightBand, NightChip } from "./night-band"
+export type { NightBandProps, NightChipProps } from "./night-band"
+
+export { ProductHeader } from "./product-header"
+export type { ProductHeaderProps } from "./product-header"
+
+export { Reveal } from "./reveal"
+export type { RevealProps } from "./reveal"
+
+export { usePrefersReducedMotion, useLoopClock } from "./motion"
+export type { LoopClock } from "./motion"
+
+// Re-exported here so a consumer of the marketing surface doesn't have to import
+// the root entry just to compose class names.
+export { cn } from "../../utils"

package/src/components/marketing/motion.ts

@@ -0,0 +1,92 @@
+"use client"
+
+import { useEffect, useRef, useState, useSyncExternalStore } from "react"
+
+/* ─── prefers-reduced-motion, as a value ───────────────────────────────────
+   `useSyncExternalStore` rather than an effect + state: the subscription *is*
+   the media query, so there is no first-render frame with the wrong answer and
+   nothing to keep in sync by hand. The server snapshot is `false` (assume
+   motion, then correct on hydration) — the alternative renders the still frame
+   to everyone. */
+
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)"
+
+function subscribeReducedMotion(onChange: () => void) {
+  const mq = window.matchMedia(REDUCED_MOTION_QUERY)
+  mq.addEventListener("change", onChange)
+  return () => mq.removeEventListener("change", onChange)
+}
+
+export function usePrefersReducedMotion(): boolean {
+  return useSyncExternalStore(
+    subscribeReducedMotion,
+    () => window.matchMedia(REDUCED_MOTION_QUERY).matches,
+    () => false
+  )
+}
+
+/* ─── useLoopClock — "how far into the loop are we" ────────────────────────
+   The animated artifacts of a landing page (a terminal typing itself out, a
+   build filling up) are usually pure functions of one number. Modelling them
+   that way keeps each to a single rAF, makes the reduced-motion path a matter
+   of picking a frame, and makes them trivially testable.
+
+   Two things this does that a naive rAF loop doesn't:
+
+     - it **stops when the element is off screen** (IntersectionObserver on the
+       returned ref), so a page with three animated panels runs one loop, not
+       three;
+     - it **commits at ~14 Hz, not 60** (`resolutionMs`) — a marketing page has
+       no business re-rendering a React tree on every frame.
+
+   Attach `ref` to the element that has to be visible for the clock to run, and
+   drive everything else from `t` (milliseconds into the loop). */
+
+export interface LoopClock<T extends HTMLElement> {
+  /** Milliseconds elapsed in the current loop, in `[0, loop)`. */
+  t: number
+  /** Attach to the animated element — the clock pauses while it's off screen. */
+  ref: React.RefObject<T | null>
+}
+
+export function useLoopClock<T extends HTMLElement = HTMLDivElement>(
+  /** Loop length, in milliseconds. */
+  loop: number,
+  /** `false` freezes the clock at 0 — pass `!prefersReducedMotion`. */
+  enabled: boolean,
+  /** Minimum gap between two committed values. */
+  resolutionMs = 70,
+  /** Changing it restarts the loop from zero. */
+  resetKey: unknown = null
+): LoopClock<T> {
+  const [t, setT] = useState(0)
+  const ref = useRef<T>(null)
+  const [visible, setVisible] = useState(true)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const io = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting), { rootMargin: "120px" })
+    io.observe(el)
+    return () => io.disconnect()
+  }, [])
+
+  useEffect(() => {
+    if (!enabled || !visible) return
+    let raf = 0
+    let committed = -1
+    const start = performance.now()
+    const tick = (now: number) => {
+      const v = (now - start) % loop
+      if (v < committed || v - committed >= resolutionMs) {
+        committed = v
+        setT(v)
+      }
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [enabled, visible, loop, resolutionMs, resetKey])
+
+  return { t, ref }
+}

package/src/components/marketing/night-band.tsx

@@ -0,0 +1,75 @@
+// The night register — a fixed dark band inside an otherwise light document.
+//
+// Static markup only (no state, no effect), so it stays server-renderable: the
+// drifting light source is a CSS animation carried by `styles.css`, not a rAF
+// loop, because this is usually the most-viewed element of a site and it has no
+// business holding one open.
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/* ─── NightBand ────────────────────────────────────────────────────────────
+   A page that is cream on cream from top to bottom is calm at a glance and
+   flat over its full height. The band is the contrast: near-black, with the
+   accent as a light source behind it, dropping back into the document
+   underneath on a hairline.
+
+   The surface is the `--night` token (`bg-night`), deliberately deeper than the
+   dark theme's own background so the band still reads as a band when the whole
+   site is already dark — and identical in both themes, since it *is* the dark
+   moment of the page rather than a themed surface. */
+
+export interface NightBandProps {
+  children: ReactNode
+  /** The light source. A page passes its own accent — any CSS colour. */
+  glow?: string
+  className?: string
+}
+
+export function NightBand({ children, glow = "var(--flame)", className }: NightBandProps) {
+  return (
+    <div className={cn("relative isolate overflow-hidden bg-night text-stone-100", className)}>
+      <div aria-hidden className="night-grid pointer-events-none absolute inset-0" />
+      {/* `glow` transitions, so a page that lets the visitor pick a product in
+          the hero changes temperature with the selection. */}
+      <div
+        aria-hidden
+        className="night-glow-a pointer-events-none absolute -left-[10%] -top-[45%] h-[85%] w-[70%] opacity-[0.5] transition-[background] duration-700"
+        style={{ background: `radial-gradient(closest-side, ${glow}, transparent)` }}
+      />
+      <div
+        aria-hidden
+        className="night-glow-b pointer-events-none absolute -bottom-[55%] right-[-15%] h-[90%] w-[60%] opacity-[0.22] transition-[background] duration-700"
+        style={{ background: `radial-gradient(closest-side, ${glow}, transparent)` }}
+      />
+      {/* Hairline at the seam, so the band ends on a line like everything else. */}
+      <div aria-hidden className="pointer-events-none absolute inset-x-0 bottom-0 h-px bg-white/10" />
+      <div className="relative">{children}</div>
+    </div>
+  )
+}
+
+/* ─── NightChip — a small fact on a night surface ─────────────────────────── */
+
+export interface NightChipProps {
+  children: ReactNode
+  /** Any CSS colour: tints the border and lights the leading dot. */
+  accent?: string
+  className?: string
+}
+
+export function NightChip({ children, accent, className }: NightChipProps) {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-full border border-white/15 px-2 py-1 font-mono text-[9px] uppercase tracking-[0.1em] text-stone-300 sm:px-2.5 sm:text-[10px] sm:tracking-[0.14em]",
+        className
+      )}
+      style={accent ? { borderColor: `color-mix(in oklch, ${accent} 45%, transparent)` } : undefined}
+    >
+      {accent && <span className="h-1.5 w-1.5 rounded-full" style={{ backgroundColor: accent }} />}
+      {children}
+    </span>
+  )
+}

package/src/components/marketing/product-header.tsx

@@ -0,0 +1,115 @@
+// The opening of a product page. Static shell (server-renderable) around the
+// one interactive part, `CopyCommand`.
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+import { CopyCommand } from "./copy-command"
+import { NightBand, NightChip } from "./night-band"
+
+/* ─── ProductHeader ────────────────────────────────────────────────────────
+   Mark, name, kind, headline, promise, the one command, the honest chips. The
+   same shape repeated across a catalogue is what makes several product pages
+   read as one family rather than N landing pages that happen to share a nav.
+
+   **Generalised on the way into the package.** The site's version took a
+   `Product` out of its own registry and looked its accent up in a table, so it
+   couldn't draw anything that wasn't a Spunto product. Here it takes a mark, a
+   name, a kind, an accent colour and (optionally) a command — it knows about no
+   product at all. Everything product-specific a page wants beside the command
+   (a Source link, a docs link, a signup button) goes through `actions`, which
+   is also where a link belongs: the package doesn't import a router. */
+
+export interface ProductHeaderProps {
+  /** The product's logo — any node, usually an inline SVG sized by the caller. */
+  mark?: ReactNode
+  name: ReactNode
+  /** Mono qualifier beside the name: "self-hosted platform", "CLI"… */
+  kind?: ReactNode
+  headline: ReactNode
+  intro?: ReactNode
+  /** Short facts under the intro — "MIT", "no account", "one binary"… */
+  chips?: string[]
+  /** Any CSS colour. Lights the band, the mark, the chips and the `$` prompt. */
+  accent?: string
+  /** When set, the header draws the two-column layout with a copyable command. */
+  command?: string
+  commandCaption?: ReactNode
+  commandNote?: ReactNode
+  /** Buttons and links under the command — the caller renders its own. */
+  actions?: ReactNode
+  className?: string
+}
+
+export function ProductHeader({
+  mark,
+  name,
+  kind,
+  headline,
+  intro,
+  chips,
+  accent = "var(--flame)",
+  command,
+  commandCaption,
+  commandNote,
+  actions,
+  className,
+}: ProductHeaderProps) {
+  const aside = command !== undefined || actions !== undefined
+
+  return (
+    <NightBand glow={accent} className={className}>
+      <div className="mx-auto max-w-6xl px-5 pb-16 pt-28 md:px-10 md:pb-20 md:pt-36">
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+          {mark && <span style={{ color: accent }}>{mark}</span>}
+          <span className="font-display text-lg font-bold tracking-tight text-white">{name}</span>
+          {kind && <span className="font-mono text-[10.5px] uppercase tracking-[0.16em] text-stone-400">{kind}</span>}
+        </div>
+
+        {/* Full width — the product's one line shouldn't have to share a column
+            with the command block and wrap four times.
+
+            The phone size is fluid, not a fixed 2.5rem: these headlines are
+            hand-broken with a `<br />`, so a line is never allowed to wrap, and
+            at a fixed 40px a long word ran past the content box of a 320px
+            screen — letters off the edge of the band, clipped by its
+            `overflow-hidden`. 10vw keeps the longest word inside the gutters at
+            every phone width (and leaves room for the fallback face while the
+            display font loads), then stops growing at the same 2.5rem. */}
+        <h1 className="font-display mt-6 max-w-[19ch] text-[clamp(2rem,10vw,2.5rem)] font-bold leading-[1.0] tracking-[-0.045em] text-white sm:text-5xl xl:text-[3.9rem]">
+          {headline}
+        </h1>
+
+        {/* `min-w-0` on both cells, and it is not cosmetic. A grid item's
+            automatic minimum size is its min-content width, and the command
+            block's `<pre>` doesn't shrink below its longest line: on a phone
+            (one column) the track grows past the page and the band clips
+            everything in it — invisibly. Capping the track lets the `<pre>`
+            scroll on its own, which is what `overflow-x-auto` was there for. */}
+        <div className={cn("mt-9 grid gap-10", aside && "lg:grid-cols-[1.05fr_0.95fr] lg:items-start lg:gap-14")}>
+          <div className="min-w-0">
+            {intro && <p className="max-w-[56ch] text-[15px] leading-relaxed text-stone-300 md:text-base">{intro}</p>}
+            {chips && chips.length > 0 && (
+              <div className="mt-6 flex flex-wrap gap-2">
+                {chips.map((c) => (
+                  <NightChip key={c} accent={accent}>
+                    {c}
+                  </NightChip>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {aside && (
+            <div className="min-w-0 lg:pb-1">
+              {command !== undefined && (
+                <CopyCommand tone="night" command={command} caption={commandCaption} note={commandNote} accent={accent} />
+              )}
+              {actions && <div className="mt-5 flex flex-wrap items-center gap-3">{actions}</div>}
+            </div>
+          )}
+        </div>
+      </div>
+    </NightBand>
+  )
+}

package/src/components/marketing/reveal.tsx

@@ -0,0 +1,71 @@
+"use client"
+
+import { useEffect, useRef, useState, type ReactNode } from "react"
+
+import { cn } from "../../utils"
+import { usePrefersReducedMotion } from "./motion"
+
+/* ─── Reveal — fade-and-lift into view on scroll ───────────────────────────
+   The one animated primitive that made it into the package, and the reason it
+   could is that it carries **no motion library**. The site's version was
+   `framer-motion` (`useInView` + a `motion.div`); adding that as a hard
+   dependency of the design system would weigh on every consumer, including the
+   dashboards that never draw a landing page. An IntersectionObserver and a CSS
+   transition do the same job here, in ~20 lines.
+
+   Reduced motion short-circuits to a plain `<div>`: no observer, no transition,
+   the content is simply there. */
+
+export interface RevealProps {
+  children: ReactNode
+  className?: string
+  /** Stagger, in seconds — give siblings 0, 0.08, 0.16… */
+  delay?: number
+  /** How far it lifts, in pixels. */
+  y?: number
+  /** `false` re-hides the element when it leaves the viewport. */
+  once?: boolean
+}
+
+export function Reveal({ children, className, delay = 0, y = 28, once = true }: RevealProps) {
+  const reduced = usePrefersReducedMotion()
+  const ref = useRef<HTMLDivElement>(null)
+  const [shown, setShown] = useState(false)
+
+  useEffect(() => {
+    if (reduced) return
+    const el = ref.current
+    if (!el) return
+    const io = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setShown(true)
+          if (once) io.disconnect()
+        } else if (!once) {
+          setShown(false)
+        }
+      },
+      // Same threshold as the framer-motion original: the element has to be
+      // 80px inside the viewport before it counts as seen.
+      { rootMargin: "-80px" }
+    )
+    io.observe(el)
+    return () => io.disconnect()
+  }, [reduced, once])
+
+  if (reduced) return <div className={className}>{children}</div>
+
+  return (
+    <div
+      ref={ref}
+      className={cn("transition-[opacity,transform] duration-[600ms] ease-[cubic-bezier(0.22,1,0.36,1)]", className)}
+      style={{
+        opacity: shown ? 1 : 0,
+        transform: shown ? undefined : `translateY(${y}px)`,
+        transitionDelay: delay ? `${delay}s` : undefined,
+      }}
+    >
+      {children}
+    </div>
+  )
+}

package/src/components/marketing/section.tsx

@@ -0,0 +1,161 @@
+// Marketing page scaffolding — the static half of the vocabulary.
+//
+// No `"use client"` on purpose: `Section`, `H2`, `Kicker`, `SpecList` and
+// `Disclosure` render no state and hold no effect, so they stay callable from a
+// React Server Component. The package already splits this way for
+// `buttonVariants` / `alertVariants`; the marketing entry keeps the same line —
+// everything interactive lives in its own file with the directive on it
+// (`copy-command.tsx`, `reveal.tsx`, `use-loop-clock.ts`).
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+/* ─── Section — every chapter opens the same way ────────────────────────────
+   A hairline rule, a mono label ("01 — WHAT IT IS"), an optional note pushed to
+   the right margin, then the content. Repeating that shape down a page is what
+   makes a marketing page read as one document rather than a stack of unrelated
+   blocks. */
+
+export interface SectionProps {
+  /** Anchor id — the section scrolls under a sticky header (`scroll-mt-20`). */
+  id?: string
+  /** Chapter number, drawn in the accent colour before the title. */
+  n?: string
+  title: string
+  /** Right-hand margin note, hidden below `sm` where there is no margin. */
+  note?: ReactNode
+  children: ReactNode
+  className?: string
+}
+
+export function Section({ id, n, title, note, children, className }: SectionProps) {
+  return (
+    <section id={id} className={cn("scroll-mt-20 border-t border-border px-5 py-16 md:px-10 md:py-24", className)}>
+      <div className="mb-10 flex items-baseline justify-between gap-4 border-b border-border pb-3 font-mono text-[11px] uppercase tracking-[0.18em] text-muted-foreground md:mb-14">
+        <span>
+          {n && <span className="text-primary">{n}</span>}
+          {n && " — "}
+          {title}
+        </span>
+        {note && <span className="hidden text-muted-foreground/50 sm:block">{note}</span>}
+      </div>
+      {children}
+    </section>
+  )
+}
+
+/* ─── Headline ──────────────────────────────────────────────────────────────
+   Display face (Syne) via the `font-display` utility the tokens already
+   generate — the kits carried a `style={{ fontFamily: "var(--font-display)" }}`
+   object around because the site had no such utility; the package does. */
+
+export interface H2Props {
+  children: ReactNode
+  className?: string
+}
+
+export function H2({ children, className }: H2Props) {
+  return (
+    <h2
+      className={cn(
+        "font-display max-w-[24ch] text-3xl font-bold leading-[1.05] tracking-[-0.03em] md:text-[2.6rem]",
+        className
+      )}
+    >
+      {children}
+    </h2>
+  )
+}
+
+/* ─── Kicker — the mono line above a headline ───────────────────────────────
+   One component, not two: the site had `Kicker` (home + product pages) and
+   `Eyebrow` (Ads landings) doing the same job at 0.22em and 0.25em tracking.
+   The package publishes a single `Kicker`; a page that wants the wider letter
+   spacing passes it through `className`. */
+
+export interface KickerProps {
+  children: ReactNode
+  className?: string
+}
+
+export function Kicker({ children, className }: KickerProps) {
+  return <p className={cn("font-mono text-[11px] uppercase tracking-[0.22em] text-primary", className)}>{children}</p>
+}
+
+/* ─── SpecList — facts without bullets ─────────────────────────────────────
+   Key/value rows, the default way to list what something *is* on a marketing
+   page: denser than a bulleted list and it never invents a verb. */
+
+export interface SpecListProps {
+  rows: [string, ReactNode][]
+  className?: string
+}
+
+export function SpecList({ rows, className }: SpecListProps) {
+  return (
+    <dl className={cn("border-t border-border", className)}>
+      {rows.map(([k, v]) => (
+        <div
+          key={k}
+          className="grid grid-cols-[6.5rem_1fr] gap-4 border-b border-border py-2.5 md:grid-cols-[8.5rem_1fr]"
+        >
+          <dt className="pt-0.5 font-mono text-[10px] uppercase tracking-[0.16em] text-muted-foreground/70">{k}</dt>
+          {/* `min-w-0 break-words` — the value column carries the odd API name
+              (`Input.dispatchMouseEvent`), and a token longer than the track
+              would otherwise widen the grid and push the row off a narrow
+              phone rather than wrap. */}
+          <dd className="min-w-0 break-words text-sm leading-relaxed text-foreground/85">{v}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}
+
+/* ─── Disclosure — a row you open ──────────────────────────────────────────
+   A marketing page that lays every argument out at once (five timeline entries
+   and seven FAQ answers, all expanded) is a wall a visitor bounces off. Closed,
+   a chapter is five headlines you scan in four seconds; open, it's the same
+   text as before.
+
+   `<details name>` gives the exclusive-accordion behaviour natively: no state,
+   no hydration surface, and it works before the JS lands — which is also why
+   this component stays server-renderable. Browsers that don't know `name` yet
+   just allow several rows open at once: the same page, less tidy. */
+
+export interface DisclosureProps {
+  /** Shared by the rows of one accordion — only one of them stays open. */
+  group: string
+  summary: ReactNode
+  /** Small left-hand column: a time, a product, a number. */
+  aside?: ReactNode
+  defaultOpen?: boolean
+  children: ReactNode
+  className?: string
+}
+
+export function Disclosure({ group, summary, aside, defaultOpen = false, children, className }: DisclosureProps) {
+  return (
+    <details name={group} open={defaultOpen} className={cn("group border-b border-border", className)}>
+      <summary className="flex cursor-pointer list-none items-baseline gap-4 py-4 transition-colors hover:text-primary [&::-webkit-details-marker]:hidden">
+        {/* On a phone the aside sits *above* the headline rather than in a
+            column beside it: a 6rem gutter on a 393pt screen wraps every title
+            onto two lines. */}
+        {aside && <span className="hidden w-[9rem] shrink-0 md:block">{aside}</span>}
+        <span className="min-w-0 flex-1">
+          {aside && <span className="mb-1.5 block md:hidden">{aside}</span>}
+          <span className="font-display block text-[17px] font-bold leading-snug tracking-[-0.02em] md:text-xl">
+            {summary}
+          </span>
+        </span>
+        <span
+          aria-hidden
+          className="mt-1 shrink-0 font-mono text-lg leading-none text-muted-foreground/60 transition-transform group-open:rotate-45"
+        >
+          +
+        </span>
+      </summary>
+      <div className={cn("pb-6", aside && "md:pl-[10rem]")}>{children}</div>
+    </details>
+  )
+}

package/styles.css

@@ -1,5 +1,8 @@
 /*
- * @spunto/design-system — design tokens (warm / Mistral-inspired, brand: flame).
+ * @spunto/design-system — design tokens (warm, brand: flame).
+ *
+ * Token names and structure follow shadcn/ui (https://ui.shadcn.com, MIT) — the
+ * base this whole design system is built on. Only the values are ours.
  *
  * Import AFTER `@import "tailwindcss"` in your app's entry CSS:
  *   @import "tailwindcss";
@@ -196,6 +199,9 @@
   --color-ship: var(--ship);
   --color-run: var(--run);
   --color-flame: var(--flame);
+  /* Marketing surfaces — the two fixed dark values (see `--night` below) */
+  --color-night: var(--night);
+  --color-code-surface: var(--code-surface);
   /* Square-leaning radius scale — driven by --radius (4px base) */
   --radius-sm: calc(var(--radius) * 0.5);
   --radius-md: calc(var(--radius) * 0.75);
@@ -206,7 +212,7 @@
   --radius-4xl: calc(var(--radius) * 3.5);
 }
 
-/* ─── Light mode — Warm cream, Mistral-inspired ─────────────────────────── */
+/* ─── Light mode — Warm cream ───────────────────────────────────────────── */
 :root {
   --background: oklch(0.975 0.012 82);
   --foreground: oklch(0.20 0.018 55);
@@ -308,6 +314,26 @@
   --sidebar-ring: oklch(0.70 0.20 43);
 }
 
+/* ─── Marketing night surfaces — deliberately NOT themed ─────────────────────
+ *
+ * Two dark values that stay the same in light and dark mode, because they are
+ * the *dark moment* of a page rather than a surface that follows the theme:
+ *
+ *   --night        the contrast band a marketing page opens on (`NightBand`).
+ *                  Deeper than the dark theme's own background (0.155) so the
+ *                  band still reads as a band when the whole site is dark.
+ *   --code-surface the warm dark behind a snippet or a copyable command
+ *                  (`CodeBlock`, `CopyCommand`) — the same one every
+ *                  terminal-ish panel of the site uses.
+ *
+ * They live here, as tokens (`bg-night`, `bg-code-surface`), precisely because
+ * they used to be two near-identical `oklch(…)` literals copy-pasted into two
+ * component files — which is how a design system ends up with two blacks. */
+:root {
+  --night: oklch(0.14 0.013 50);
+  --code-surface: oklch(0.16 0.012 52);
+}
+
 /* ─── Base layer ─────────────────────────────────────────────────────────── */
 @layer base {
   * {
@@ -364,6 +390,50 @@
     linear-gradient(to bottom, oklch(0.92 0.04 70 / 0.04) 1px, transparent 1px);
 }
 
+/* ─── Night band utilities (@spunto/design-system/marketing) ─────────────────
+ * The blueprint grid, the drifting light sources and the scrollbar of a `<pre>`
+ * sitting on a dark surface. Never themed — like `--night` itself, these paint
+ * on a fixed dark band, so there is no `.dark` variant. */
+.night-grid {
+  background-image:
+    linear-gradient(to right, oklch(0.92 0.04 70 / 0.05) 1px, transparent 1px),
+    linear-gradient(to bottom, oklch(0.92 0.04 70 / 0.05) 1px, transparent 1px);
+  background-size: 56px 56px;
+}
+
+/* The light source on a night band drifts, slowly enough that you notice it
+   only if you stay. Pure CSS on purpose — this is usually the most-viewed
+   element of a page and it has no business holding a rAF loop open. */
+@keyframes night-drift-a {
+  0%, 100% { transform: translate3d(0, 0, 0) scale(1); }
+  50%      { transform: translate3d(6%, 4%, 0) scale(1.12); }
+}
+@keyframes night-drift-b {
+  0%, 100% { transform: translate3d(0, 0, 0) scale(1.06); }
+  50%      { transform: translate3d(-7%, -5%, 0) scale(1); }
+}
+.night-glow-a { animation: night-drift-a 26s ease-in-out infinite; }
+.night-glow-b { animation: night-drift-b 34s ease-in-out infinite; }
+
+@media (prefers-reduced-motion: reduce) {
+  .night-glow-a,
+  .night-glow-b {
+    animation: none;
+  }
+}
+
+/* Scrollable code on a night surface: the global thumb is `--border`, which is
+   cream in the light theme and lands as a bright bar under a dark <pre>. */
+.night-scroll::-webkit-scrollbar-thumb {
+  background: oklch(1 0 0 / 0.18);
+}
+.night-scroll::-webkit-scrollbar-thumb:hover {
+  background: oklch(1 0 0 / 0.3);
+}
+.night-scroll {
+  scrollbar-color: oklch(1 0 0 / 0.18) transparent;
+}
+
 /* ─── Toast — stacking + enter/exit motion (mounted by SpuntoProvider) ─────
  *
  * The look (colors, spacing, typography) lives on the components as Tailwind