# dss catalog

Read this file, never the core sources. Site sections: `grep -h @catalog components/sections/*.tsx`.

## Tokens (Tailwind classes generated from design.dna.ts)

- Colors (bg-, text-, border-, ring-, fill-): `surface`, `surface-2`, `surface-3`, `ink`, `ink-muted`, `line`, `rule`,
  `accent` (fills) + `accent-ink` (text on accent), `accent-text` (accent as text, AA on surfaces), `secondary` (sparingly).
  Opacity modifiers work (`text-surface/80`). Inverse blocks: `bg-ink text-surface`.
- Type: `font-display`, `font-body`, `font-mono`; `text-display-2xl`, `text-display-xl`, `text-display-lg`, `text-heading`,
  `text-subheading`, `text-body-lg` (line height and tracking included).
- Layout: `py-section` (DNA density), `px-gutter`, `max-w-content`, `max-w-prose`; corners `rounded-card`, `rounded-control`,
  `rounded-media`; rules `rule-t`, `rule-b` (width and color from the DNA).
- Motion: `duration-(--duration-brand) ease-brand`. Textures: `texture-grain`, `texture-halftone`, `texture-grid`, `texture-mesh`.
- `<html>` carries `data-archetype`, `data-motion`, `data-three`, `data-texture`, `data-radius` for variant styling.
- Scroll motion (pure CSS, off for reduced motion and DNA motion none): `reveal`, `reveal-fade`, `reveal-scale`,
  `reveal-stagger` (children; index via `style={stagger(i)}` from @dss/motion), `parallax`, `marquee`, `split-words`.

## @dss/ui (`import { Heading } from '@dss/ui'`; client: `@dss/ui/accordion`)

| Component | Props |
|---|---|
| SkipLink: first focusable element of the layout, jumps to #main. | label |
| VisuallyHidden: text for screen readers only. |  |
| Accordion (client): accessible disclosure list, FAQ default. Pair with faqSchema() from @dss/seo. | items [{ question, answer }], defaultOpen (index), className |
| Button: native button (forms, toggles). For navigation use ButtonLink. | variant: primary \| secondary \| inverse \| ghost \| link; size: sm \| md \| lg |
| ButtonLink: next/link styled as a button. External URLs open safely in a new tab. | href (typed Route or https URL), variant, size |
| Container: centered column with the DNA gutter. | size: content (default, DNA width) \| prose (reading measure) \| full; as |
| Section: vertical rhythm block. Space comes from DNA density; tone swaps the palette. | tone: surface \| raised \| inverse \| accent; space: section (default) \| tight \| none; rule (top rule); id |
| Stack: vertical flow with consistent gaps. | gap: xs \| sm \| md (default) \| lg \| xl; as |
| Cluster: wrapping row (actions, tags, logos). | gap: sm \| md (default) \| lg; align: start \| center \| between |
| Grid: responsive columns. Prefer asymmetric spans (md:col-span-*) for editorial layouts. | cols: 1 \| 2 \| 3 \| 4 \| 12; gap: md (default) \| lg |
| Media: next/image in a ratio box with DNA corners. Always pass a real `alt` and `sizes`. | src, alt, ratio: square \| landscape \| wide \| portrait \| tall, sizes, priority (LCP image only) |
| Heading: display face, size from the DNA type scale. One h1 per page. | level: 1-4 (semantics); size: display-2xl \| display-xl \| display-lg \| heading \| subheading; balance (default true) |
| Text: body copy. Muted tone keeps WCAG AA on surface and surface-2. | size: sm \| base (default) \| lg; tone: ink (default) \| muted; as: p \| span \| div |
| Eyebrow: small label above a heading. Sentence case by default (all-caps eyebrows are a generated-site tell). | caps (opt-in uppercase with tracking) |
| Prose: long-form rich text (MDX, legal pages) at reading measure. |  |

## Motion and 3D (`@dss/motion`, client `@dss/motion/count-up`; `@dss/three` only in components/3d)

| Component | Props |
|---|---|
| CountUp (client): animates a number from 0 when it enters the viewport; renders the final value without JS or with reduced motion. Keep the label outside. | value (number), prefix?, suffix?, duration? (ms) |
| Marquee: infinite horizontal loop in CSS (pauses on hover, static when motion is off). Logos, kinetic words. | children (one sequence; it is duplicated), label (accessible name), className |
| SplitWords: headline revealed word by word in CSS (server-rendered, no JS). Use once per page, on the hero. | text, as (h1 \| h2 \| p...), className |
| Scene (client): lazy three.js canvas with poster fallback; never the LCP element. Use inside components/3d only. | load, poster, label, className, dpr, minWidth (default 768: phones keep the poster) |

Scenes (`pnpm dss add scene <id>`, copied into components/3d/, poster fallback, skipped when DNA three is none):

- `gradient` (GradientScene): Full-canvas shader in DNA colors, very light GPU cost. Poster: surface-2 with texture-mesh.
- `particles` (ParticlesScene): 1,400 points on a sphere shell in the DNA accent, pointer parallax. Poster: surface-2 with texture-halftone.

## Registry sections (`pnpm dss add section <id>/<variant> --page /route`)

Without a variant, a variant that fits the DNA archetype is picked with the site seed (one variant per id per site). Props mirror `example.json`.

| Section | Component | Use | Fits |
|---|---|---|---|
| contact/details | Contact | Channels as a definition list plus hours. Page-level h1 (use on the contact page). | editorial, swiss, craft, institutional, organic, luxury, architectural, minimal-mono |
| cta/band | Cta | Ink background, one line, one button. Ends a page. | editorial, swiss, brutalist, institutional, magazine, tech-noir, kinetic-type, craft |
| cta/statement | Cta | A display-size sentence that is itself the link. Quiet, confident close for refined brands. | editorial, luxury, architectural, craft, organic, minimal-mono, institutional |
| faq/accordion | Faq | Radix accordion with FAQPage structured data. | editorial, swiss, institutional, organic, playful, tech-noir, minimal-mono, craft |
| features/bento | Features | Uneven tile grid (one large tile, optional metrics), staggered reveal. Products and studios. | tech-noir, playful, kinetic-type, brutalist |
| features/numbered | Features | Ruled, numbered list beside a title column. Avoids the three-equal-cards pattern. | editorial, swiss, institutional, minimal-mono, magazine, tech-noir |
| gallery/sequence | Gallery | Scroll-snap strip of captioned photos. Needs real images. | architectural, craft, luxury, editorial, organic, magazine |
| hero/fullbleed-image | Hero | Edge-to-edge photo with an ink scrim; text bottom left. Needs one excellent real photo. | architectural, luxury, organic, craft, editorial |
| hero/kinetic | Hero | Giant looping words (CSS marquee) over a ruled statement. Agencies, music, events, bold brands. | kinetic-type, brutalist, magazine, playful |
| hero/mono-index | Hero | Monospace statement, factual lines and a numbered link index. Portfolios, consultants, studios. | minimal-mono, swiss, tech-noir, brutalist |
| hero/scene | Hero | Text left, a lazy three.js shader panel right (poster fallback). For DNA three level hero or immersive. | tech-noir, kinetic-type, playful |
| hero/split-editorial | Hero | Oversized display title left, body and actions right. Text-led, no image required. | editorial, craft, institutional, architectural, luxury, swiss |
| hero/split-media | Hero | Text and actions beside a portrait photo, optional proof facts under a rule. Needs one real photo. | institutional, editorial, craft, organic, luxury, retro-print |
| logos/marquee | Logos | Real clients or partners only. Monochrome SVG logos or names in the display face. | swiss, tech-noir, magazine, kinetic-type, playful, brutalist, institutional, editorial |
| pricing/columns | Pricing | Joined columns on hairlines, one featured plan. Products, memberships, packages. | swiss, tech-noir, playful, minimal-mono, institutional, editorial, organic |
| projects/index | Projects | Lead project with a wide image, then a ruled table. Architects, agencies, builders, portfolios. | architectural, editorial, swiss, minimal-mono, brutalist, craft |
| quote/manifesto | Manifesto | Display-size belief statement with one accent phrase. Brand pause between dense sections. | editorial, luxury, craft, architectural, kinetic-type, organic, magazine |
| services/grid-numbered | Services | Two-column numbered list on rules with price lines. Practices, consultancies, products with tiers of service. | swiss, institutional, minimal-mono, brutalist, magazine, tech-noir, playful |
| services/rows | Services | Full-width ruled rows with optional links and prices. Good for agencies, trades, clinics, restaurants (as a menu). | editorial, craft, institutional, swiss, luxury, architectural, retro-print |
| stats/figures | Stats | Display-size numbers over a rule. Proof, not decoration. | swiss, magazine, institutional, tech-noir, editorial, brutalist, kinetic-type |
| steps/timeline | Steps | Horizontal timeline with accent dots. Only for real sequences. | editorial, swiss, craft, tech-noir, playful, organic, institutional |
| story/split-media | Story | Portrait photo beside a short narrative. Needs a real photo before launch. | editorial, craft, organic, luxury, architectural, institutional |
| story/stacked | Story | Title, two text columns, then a wide captioned image. Architecture, institutions, magazines. | architectural, editorial, magazine, institutional, swiss, minimal-mono |
| team/portraits | Team | Portrait grid with roles and one-line bios. Real photos only. | editorial, craft, institutional, organic, architectural, luxury, swiss |
| testimonials/columns | Testimonials | Three equal ruled columns of quotes. Calmer than a lead quote; good for services and products. | swiss, institutional, tech-noir, playful, minimal-mono, retro-print, kinetic-type, brutalist |
| testimonials/quotes | Testimonials | One display-size quote, then a two-column list. No avatars or stars by default. | editorial, luxury, craft, institutional, magazine, organic, architectural |

## Modules (`pnpm dss module add <slug>`; read `core/modules/<slug>/README.md` after adding)

- `analytics`: Cookieless audience measurement (Plausible, Umami or Cloudflare Web Analytics), production builds only, no consent banner needed.
- `blog`: Markdown articles in content/blog: index, article pages with Article JSON-LD, RSS, sitemap and llms.txt entries.
- `forms`: Contact form: Server Action (zod, honeypot, rate limit, Turnstile) sending email through Resend.
- `legal`: Legal notice and privacy policy (GDPR, Swiss nLPD) pages linked from the footer, structured placeholders to fill.
- Database: `pnpm dss db init [--driver d1|libsql|postgres]` (schema in server/db/schema.ts, `db()` from server/db/client.ts).

## Archetypes (design.dna.ts `archetype`)

- **editorial**: a considered publication: big serif headlines, generous measure, asymmetric columns. Signature: pull quotes, drop caps, captions under images, one oversized headline per page. Avoid: card grids, icons in circles, centered everything.
- **swiss**: rational grid, flush-left grotesk, one strong signal color, numbers and alignment do the talking. Signature: visible grid, large index numbers, strict baseline, a single red/blue/yellow accent. Avoid: rounded pills, gradients, decorative serif.
- **brutalist**: raw and confident: heavy type, thick borders, system-like layout, high contrast. Signature: thick black rules, marquee text, exposed structure, offset hard shadows. Avoid: soft shadows, pastel gradients, delicate serif.
- **luxury**: restraint and space: high-contrast serif, slow reveals, a muted precious accent. Signature: huge whitespace, letter-spaced small caps, full-bleed imagery, slow fades. Avoid: bright saturated accents, dense copy, bouncy motion.
- **organic**: natural and tactile: earthy palette, soft shapes, paper texture, unhurried rhythm. Signature: organic blob crops, hand-drawn underline, warm off-white surfaces. Avoid: neon, hard black, tech grids.
- **tech-noir**: dark interface aesthetic: mono labels, fine grid lines, one luminous accent, product-first. Signature: terminal-like labels, code snippets, live-looking UI fragments, subtle 3D. Avoid: purple-to-pink gradients, glassmorphism cards, emoji.
- **playful**: cheerful and bold: rounded type, saturated colors, stickers and bouncy motion. Signature: sticker-like badges, tilted cards, color-blocked sections, springy hovers. Avoid: thin serif, grey-on-grey, corporate stock photos.
- **retro-print**: printed-matter nostalgia: slab and fat-face type, halftone, warm inks on cream. Signature: badges and stamps, two-ink color scheme, misregistered offsets. Avoid: glossy gradients, thin geometric sans.
- **minimal-mono**: almost nothing: monospace-led, monochrome, one tiny accent, content as structure. Signature: plain-text lists, timestamps, keyboard-like links, generous line height. Avoid: hero images, decorative illustration, more than one accent.
- **magazine**: newsstand energy: condensed display, dense multi-column layout, big numbers and covers. Signature: cover-style hero, issue numbers, kicker labels, tight leading headlines. Avoid: empty minimalism, pastel palettes.
- **architectural**: space and proportion: thin type, wide margins, full-bleed photography, slow motion. Signature: plan-like line drawings, image sequences, coordinates and dimensions as details. Avoid: bright accents, illustration, playful motion.
- **kinetic-type**: typography as image: oversized moving headlines, variable fonts, scroll-driven motion. Signature: viewport-wide words, variable weight on scroll, marquees, split-letter reveals. Avoid: static stock imagery, small timid headlines.
- **craft**: made by hand: documentary photos, warm serif, process stories, tactile details. Signature: process timelines with real photos, handwritten notes, maker portraits. Avoid: stock photos of smiling people, glossy UI.
- **institutional**: quiet authority: classic serif, deep sober color, clear hierarchy, proof over promises. Signature: credentials and figures up front, named people, precise service lists. Avoid: handshake stock photos, gavel icons, vague superlatives.

## Font pairings (design.dna.ts `fonts`)

- `fraunces-instrument`: Fraunces / Instrument Sans, soft optical serif, warm and contemporary (editorial, organic, craft)
- `newsreader-hanken`: Newsreader / Hanken Grotesk, news serif with a neutral grotesk (editorial, magazine, institutional)
- `instrument-serif-geist`: Instrument Serif / Geist, condensed display serif, quiet sans (editorial, architectural, luxury)
- `bodoni-figtree`: Bodoni Moda / Figtree, high-contrast didone, fashion register (luxury, magazine)
- `cormorant-manrope`: Cormorant Garamond / Manrope, airy garalde for calm, premium pages (luxury, organic, architectural)
- `gloock-onest`: Gloock / Onest, heavy contrasty serif, poster energy (retro-print, editorial, kinetic-type)
- `young-serif-public`: Young Serif / Public Sans, friendly old-style serif, honest sans (craft, retro-print, organic)
- `caslon-franklin`: Libre Caslon Display / Libre Franklin, classic American pairing, trustworthy (institutional, editorial, luxury)
- `source-serif-plex`: Source Serif 4 / IBM Plex Sans + IBM Plex Mono, serious, technical, legible (institutional, tech-noir, editorial)
- `spectral-work`: Spectral / Work Sans, screen-first serif, calm and precise (institutional, craft, architectural)
- `garamond-schibsted`: EB Garamond / Schibsted Grotesk, literary garamond, sturdy grotesk (craft, editorial, institutional)
- `space-grotesk-work`: Space Grotesk / Work Sans + Space Mono, quirky grotesk with a mono sibling (tech-noir, swiss, brutalist)
- `bricolage-familjen`: Bricolage Grotesque / Familjen Grotesk, expressive variable grotesk (playful, kinetic-type, magazine)
- `syne-manrope`: Syne / Manrope, wide, art-school display (kinetic-type, playful, architectural)
- `unbounded-onest`: Unbounded / Onest, extended rounded display, loud and modern (playful, kinetic-type, tech-noir)
- `anton-franklin`: Anton / Libre Franklin, condensed impact headlines (magazine, kinetic-type, brutalist)
- `bebas-figtree`: Bebas Neue / Figtree, all-caps condensed display, sporty (magazine, brutalist, kinetic-type)
- `archivo-black-chivo`: Archivo Black / Chivo + Chivo Mono, blunt heavy grotesk, industrial (brutalist, swiss, magazine)
- `archivo-wide`: Archivo / Archivo, one family, two widths: expanded headlines, normal body (swiss, institutional, architectural)
- `familjen-public`: Familjen Grotesk / Public Sans, rational grotesk system (swiss, institutional, minimal-mono)
- `jetbrains-geist`: JetBrains Mono / Geist + JetBrains Mono, mono-led developer aesthetic (tech-noir, minimal-mono, brutalist)
- `space-mono-work`: Space Mono / Work Sans + Space Mono, retro typewriter mono (retro-print, brutalist, minimal-mono)
- `plex-mono-plex`: IBM Plex Mono / IBM Plex Sans + IBM Plex Mono, engineered superfamily (minimal-mono, tech-noir, institutional)
- `dm-mono-dm-sans`: DM Mono / DM Sans + DM Mono, soft mono with geometric body (minimal-mono, swiss, architectural)
- `fredoka-nunito`: Fredoka / Nunito, rounded and friendly, family or kids (playful, organic, craft)
- `italiana-tenor`: Italiana / Tenor Sans, thin fashion display, spa and boutique (luxury, architectural, organic)
- `marcellus-lora`: Marcellus / Lora, inscriptional caps with a bookish body (organic, craft, luxury)
- `alegreya-pair`: Alegreya / Alegreya Sans, calligraphic humanist superfamily (craft, organic, editorial)
- `zilla-work`: Zilla Slab / Work Sans, slab with print character (retro-print, craft, magazine)
- `bitter-public`: Bitter / Public Sans, sturdy slab, civic and dependable (institutional, retro-print, craft)
- `red-hat-pair`: Red Hat Display / Red Hat Text, open, friendly corporate superfamily (playful, swiss, tech-noir)
- `darker-manrope`: Darker Grotesque / Manrope, tall tight grotesk, fashion-architectural (architectural, luxury, kinetic-type)
- `sora-onest`: Sora / Onest, geometric tech, product register (tech-noir, playful, swiss)
- `crimson-hanken`: Crimson Pro / Hanken Grotesk, book serif, literary calm (editorial, craft, organic)
- `petrona-schibsted`: Petrona / Schibsted Grotesk, robust text serif with presence (editorial, magazine, institutional)
- `abril-work`: Abril Fatface / Work Sans, fat-face poster headlines (retro-print, magazine, kinetic-type)
- `funnel-pair`: Funnel Display / Funnel Sans, sharp contemporary superfamily (swiss, playful, architectural)
- `hedvig-pair`: Hedvig Letters Serif / Hedvig Letters Sans, quiet Scandinavian serif and sans (editorial, minimal-mono, organic)
- `mona-hubot`: Hubot Sans / Mona Sans, width-axis grotesks for kinetic headlines (kinetic-type, tech-noir, swiss)
- `dela-gothic-rubik`: Dela Gothic One / Rubik, blocky display, street poster (brutalist, playful, kinetic-type)
- `literata-host`: Literata / Host Grotesk, reading serif with a modern grotesk (editorial, institutional, craft)
- `gelasio-afacad`: Gelasio / Afacad, warm transitional serif, soft sans (organic, luxury, craft)

## Package APIs

- `@dss/seo`: deployEnv, isIndexable, absoluteUrl, canonicalPath, rootMetadata, pageMetadata, robots, sitemap, llmsTxt, AI_TRAINING_CRAWLERS, nodeId, organizationSchema, websiteSchema, localBusinessSchema, breadcrumbSchema, faqSchema, serviceSchema, articleSchema, eventSchema, buildGraph. `@dss/seo/react`: JsonLd.
- `@dss/security/server`: safeAction, formDataToObject, verifyTurnstile, memoryRateLimiter, cloudflareRateLimiter, defineEnv, clientIp.
- `@dss/site/config` (next.config.ts, manifest): defineManifest, MANIFEST_INPUT, ManifestSchema, PageSchema, OrganizationSchema, withDss, linkedCoreRoot.
- CSP presets (manifest `security.csp.presets`): turnstile, plausible, umami, cloudflareAnalytics, youtube, vimeo, calcom, googleMaps, stripe.
- `@dss/data`: id, timestamps; `/d1`: d1Db; `/libsql`: libsqlDb; `/config`: dssDrizzleConfig.