# daroms-speed-site

> A Next.js framework and Claude Code workflow that turns a brief into a varied, production-grade website at low token cost.

daroms-speed-site (dss) is built for producing websites on a line: agencies, freelancers and studios who ship many
sites and want each one to look designed for its business, rank, load fast and stay secure.

## What you get

- A **site template** on Next.js 16, React 19, Tailwind CSS v4 and TypeScript, static by default, deployable to
  Cloudflare Workers (OpenNext), Vercel or Docker.
- **Design DNA**: every site rolls an archetype, a type pairing, an accessible OKLCH palette, a grid, a texture, a motion
  profile and a 3D level, avoiding combinations used by previous sites.
- A **section registry** copied into each site (owned code) and versioned **core packages** for SEO, security, data,
  motion and 3D.
- The **dss CLI**: deterministic generators for pages, sections, themes, modules, databases and deployments.
- An **AI layer** for Claude Code: a kernel under 60 lines, rules loaded by file path, forked Sonnet/Haiku skills, guard hooks
  that refuse bad writes, a prompt router, a factory brain shared by all sites, and cost reports.

## Pages

- [Getting started](getting-started.md)
- [Demo: Clear to Board](demo.md)
- [For AI agents](agents.md)
- [Architecture](architecture.md)
- [Design DNA](design-dna.md)
- [AI layer](ai-layer.md)
- [Modules and data](modules.md)
- [Deploy, security and SEO](deploy.md)
- [Visual edits with AimKit](aimkit.md)
- [Factory: brain, sites, batch, upgrades](factory.md)
- [CLI reference](cli.md)

Made by [Daroms'Art](https://daromsart.xyz/), MIT licensed.

---

# Getting started

> Create a site with one command, open it in Claude Code, and let the /dss-site skill take it from brief to deploy.

## Requirements

Node.js 22.18 or newer, pnpm 9, git, Python 3.10+ (hooks), and Claude Code. Docker or a Cloudflare/Vercel account
for deployment.

## Create a site

```bash
npx @daromsart/daroms-speed-site new atelier-nord --name "Atelier Nord" --preset vitrine \
  --industry "furniture workshop" --mood warm,crafted --url https://ateliernord.ch
cd atelier-nord
pnpm dev
```

`dss new` copies the template, attaches the framework in `core/` (git submodule, `--copy` for a self-contained
snapshot), installs dependencies, rolls a Design DNA, generates the preset's pages from registry sections, installs the
preset's modules (contact form, legal pages) and syncs the AI layer into `.claude/`.

Presets: `vitrine` (home, services, about, contact), `landing` (one conversion page), `portfolio` (work first),
`blank`.

## Build it with Claude Code

Open the folder in Claude Code and run:

```
/dss-site A furniture workshop in Lyon that makes forty solid-wood tables a year
```

The orchestrator walks through brief, research, inspiration, DNA, sitemap, copy, pages, SEO, checks, polish, deploy and
learning, with a checkpoint after each step. Mechanical steps run as forked Sonnet or Haiku skills.

Individual skills work on their own: `/dss-copy home`, `/dss-page /services`, `/dss-seo`, `/dss-check`, `/dss-edit`.

## Check and ship

```bash
pnpm dss doctor          # manifest, theme, pages, placeholders, types, lint
pnpm dss deploy          # noindexed preview
pnpm dss deploy --prod   # production (needs the real domain and no placeholders)
pnpm dss cost            # tokens and API-equivalent price per step
```

---

# Demo: Clear to Board

> A real site built by the dss agent from one brief: an independent guide to Europe's ETIAS and EES rules, with an in-browser checker that spots fake ETIAS websites.

**Live preview: [clear-to-board.romeoerika-razaka.workers.dev](https://clear-to-board.romeoerika-razaka.workers.dev/)**
(Cloudflare Workers, noindexed like every dss preview).

![Clear to Board home page: the headline "There is nothing to apply for yet." beside the link checker flagging europa.eu.etias-apply.com as a look-alike address](https://daromsartof.github.io/daroms-speed-site/demo/clear-to-board.jpg)

## The problem it solves

ETIAS, the 20-euro travel authorisation for visa-exempt visitors to Europe, is not in operation and has no start date
(checked 13 November 2026). Meanwhile, in October 2026, the UK travel association ABTA warned alongside Frontex that
more than 150 fraudulent or misleading websites target travellers with paid "applications". The site answers the
question in one line, gives the official address, and checks any link in the browser before someone pays.

## How it was built

1. One Markdown brief with the facts and their sources (pitch, audience, offer, proof, voice, pages).
2. `pnpm dss factory run ./briefs --out ./sites --agent`: `dss new` scaffolded the site, then headless Claude Code ran
   `/dss-site --auto`: research, inspiration, Design DNA, sitemap, copy, pages, SEO, checks, polish and lessons for the
   factory brain. Each step is a commit; each decision is a line in `site.spec.md > Journal`.
3. The agent dropped the preset's services, team and testimonials (none exist), added `/etias`, `/ees` and `/scams`,
   and wrote the signature section: a hostname checker with tests for look-alikes (`europa.eu.etias-apply.com`), the
   userinfo trick (`europa.eu@evil.com`) and homoglyphs (a Cyrillic `е`).
4. Two follow-ups on request: the checker moved into the hero, and the legal pages were filled from the publisher's
   own legal notice. Then `pnpm dss deploy` for the preview.

| Agent run          |                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------ |
| Duration           | 24 minutes, 5 sessions                                                               |
| Cost at API prices | $6.38 (Opus orchestrator 49%, Sonnet workers 51%, Haiku research and brain under 1%) |
| Output             | 17 static routes, 2 journal articles, legal and privacy pages, report form           |

## Result

- Lighthouse mobile **100** for performance, accessibility, best practices and SEO on the home, `/etias`, `/scams` and
  `/contact` pages; LCP 0.8 s, CLS 0.
- Design DNA `institutional`: Source Serif with IBM Plex, a deep green accent and an oxblood secondary, chosen by the
  agent after rejecting amber (too close to the EU's gold).
- Strict CSP and security headers, no cookies, no analytics, robots and `noindex` on the preview.
- The framework improved from the run: headless permissions, `pnpm test` in sites, the first Cloudflare preview, a
  false positive in a rule hook. Each fix is in the [changelog](https://github.com/daromsartof/daroms-speed-site/blob/main/CHANGELOG.md).

## Run your own

```bash
npx @daromsart/daroms-speed-site new my-site --preset vitrine --industry "<industry>" --mood "<two or three words>"
cd my-site && pnpm dev
# in Claude Code: /dss-site <one-sentence idea>
```

Batch mode and the brief format: [Factory](factory.md). What an agent reads first: [For AI agents](agents.md).

---

# For AI agents

> The operating manual for an agent (Claude Code or any coding agent): what to read, how to start a site, the contract every site follows and the checks to run before saying done.

## Read this documentation as Markdown

- Every page of the docs site has a raw Markdown twin: append `.md` to the page name (`getting-started.md`,
  `agents.md`, `catalog.md`).
- `llms.txt` lists every page with a one-line summary; `llms-full.txt` is the whole documentation and the catalog in
  one file. Load `llms-full.txt` once instead of crawling pages.

## Inside a generated site

- `CLAUDE.md` loads the kernel (`core/_ai/CLAUDE.core.md`, under 60 lines) and the rules digest. Detailed rules load
  by file path from `.claude/rules/`.
- `site.spec.md` is the brief and the single source of facts; its `Journal` records decisions, `Open facts` what is
  still unknown.
- `core/CATALOG.md` lists tokens, components, sections, modules, archetypes and package APIs. Never read core sources.

## Start a site

```bash
npx @daromsart/daroms-speed-site new <slug> --preset vitrine --industry "<industry>" --mood "<two or three words>"
cd <slug> && pnpm dev
```

Then `/dss-site <one-sentence idea>` in Claude Code (a checkpoint after each step), or headless for a batch:
`pnpm dss factory run ./briefs --out ./sites --agent` (decisions go to the Journal, the run stops before deploy).

## The contract

| What                        | Where                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| Every visible word          | `content/<page>.ts`, typed `as const`                                                               |
| Pages                       | `app/**/page.tsx`: metadata and sections only                                                       |
| Sections                    | `components/sections/*.tsx`: owned code, a `// dss-section:` stamp and a `@catalog` line            |
| Look and feel               | `design.dna.ts`, then `pnpm dss theme`; generated theme files are never edited                      |
| Pages, modules, deploy, CSP | `site.manifest.ts`, rewritten by the CLI                                                            |
| Forms and mutations         | `server/actions/*` through `safeAction`                                                             |
| Unknown facts               | `[placeholders]` plus `site.spec.md > Open facts`; never invent testimonials, numbers or legal data |
| Studio credit               | the footer link to https://daromsart.xyz/ (`content/site.ts > footer.credit`) stays on every site   |

## Commands

- Generate before writing: `pnpm dss g page|section`, `pnpm dss add section <id>`, `pnpm dss module add <slug>`,
  `pnpm dss dna roll`, `pnpm dss db init`.
- Check: `pnpm dss doctor` (theme, pages, placeholders, credit, types, lint), `pnpm test`, `pnpm build`.
- Ship: `pnpm dss deploy` (noindexed preview), `pnpm dss deploy --prod` (needs the real domain and
  `doctor --strict`), then `pnpm dss cost`.

## Guard rails

Hooks refuse a write before it lands and say why in one line: fix the cause, never work around it.

- DNA token classes only: no hex or rgb, no default Tailwind palette, no inline style.
- No hard-coded copy in JSX, no em dashes, no generated-copy cliches, no emoji.
- No `any`, files under 250 lines, Next.js 16 APIs (`proxy.ts`, async `params`, `revalidateTag(tag, profile)`).
- Secrets stay server-side; `.env*` and `.dev.vars` are never read.
- A reasoned exception takes a `dss-ignore` comment on the line.

## Headless runs

- A new folder is not a trusted workspace: Claude Code ignores the project's `permissions.allow`. `factory run` passes
  the rules on the command line; for a manual `claude -p`, pass `--allowedTools` with the rules from
  `.claude/settings.json`.
- Each shell command must match an allow rule: prefer the Read and Grep tools to compound shell pipelines.
- Done means verified: doctor, tests and build pass, and the result names what could not be checked.

---

# Architecture

> Versioned infrastructure in core packages, owned visual code in the site, data files the CLI rewrites, generated files nobody edits.

## Core and site

```
core/ (the framework)          site (the client project)
  packages/  @dss/*              site.manifest.ts   pages, modules, deploy, SEO, CSP, redirects
  registry/  sections, scenes    design.dna.ts      the Design DNA
  modules/   forms, blog...      content/*.ts       every visible word, typed
  template/  base site, presets  app/               thin pages: metadata + sections
  _ai/       AI layer            components/        owned sections, site chrome, 3D scenes
  cli/       dss                 server/            database and server actions
```

The core is attached as a git submodule pinned to a commit or tag (`--copy` makes a snapshot for client handoff,
`--link` symlinks a framework checkout for development). Claude never edits `core/` from a site (permission deny).

## Packages

| Package         | Role                                                                                   |
| --------------- | -------------------------------------------------------------------------------------- |
| `@dss/site`     | `defineManifest` (zod) and `withDss`: headers, CSP, images, redirects, deploy output   |
| `@dss/design`   | Design DNA, archetypes, font pairs, OKLCH palettes, theme generators                   |
| `@dss/ui`       | token-driven primitives (Section, Heading, Media, ButtonLink, Accordion...)            |
| `@dss/seo`      | metadata, canonical, hreflang, JSON-LD, robots, sitemap, llms.txt, noindex on previews |
| `@dss/security` | static CSP and presets, `safeAction`, Turnstile, rate limiting, env validation         |
| `@dss/motion`   | CSS scroll-driven motion, marquee, split words, count-up                               |
| `@dss/three`    | lazy three.js `<Scene>` with poster fallback                                           |
| `@dss/data`     | Drizzle on D1, libSQL or Postgres                                                      |
| `@dss/aimkit`   | vendored AimKit bridge, MCP server and Chrome extension                                |

Packages are TypeScript sources. Config-time imports (`next.config.ts`, `site.manifest.ts`, the CLI) go through
Node-safe entries loaded with Node's type stripping.

## Ownership rules

- **Generated, never edited**: `app/theme.css`, `app/fonts.ts`, `app/theme.ts`, `content/meta.ts`, `lib/modules.ts`,
  `components/site/module-slots.tsx`, `core/CATALOG.md`, `_ai/digest.md`.
- **Data files rewritten by the CLI**: `site.manifest.ts`, `design.dna.ts` (keep literal values).
- **Owned by the site**: sections copied from the registry (each keeps a `// dss-section:` stamp and a `@catalog`
  line), module files, everything in `content/`.
- **AI files**: `dss-*` entries in `.claude/` are overwritten by the sync; site-specific ones use `site-`.

---

# Design DNA

> Each site rolls a deterministic, accessible design identity that avoids the combinations of recent sites and the usual generated-site tells.

## Fields

`design.dna.ts` holds: archetype, font pairing, palette (mode, accent hue, chroma and lightness, neutral hue and tint,
secondary offset), type scale, grid, corner radius, rules, texture, density, imagery direction, motion profile and 3D
level. `pnpm dss theme` turns it into Tailwind v4 tokens (`app/theme.css`), next/font loaders (`app/fonts.ts`) and the
browser theme color.

## Archetypes

editorial, swiss, brutalist, luxury, organic, tech-noir, playful, retro-print, minimal-mono, magazine, architectural,
kinetic-type, craft, institutional. Each has a design read, allowed options, a signature to honour and an avoid list
(listed in `core/CATALOG.md`).

## Rolling

```bash
pnpm dss dna roll --mood warm,precise                 # new DNA, theme regenerated
pnpm dss dna roll --dry --seed acme-2                 # preview a candidate
pnpm dss dna roll --archetype swiss --mode dark --hue 20 --fonts archivo-wide
```

The roller scores candidates on industry fit and mood words, then penalises resemblance to the last twelve sites
recorded in `~/.dss/brain/dna-history.jsonl` and generic indigo/violet accents. Values are rounded so the saved file
renders exactly the same theme.

## Accessibility by construction

Text tokens are pushed in lightness until they meet WCAG minimums on both surfaces: ink 7:1, muted text and accent text
4.5:1, text on the accent 4.5:1. Hundreds of rolled DNAs are tested on every build.

## Anti-slop gates

The rule hook refuses default Tailwind palette classes, raw colors, emoji in copy, em dashes and generated-copy
cliches in `content/` (elevate, seamless, unlock, cutting-edge...). The `dss-critic` agent reviews captures against the
DNA and the avoid lists.

---

# AI layer

> How dss keeps Claude Code fast and cheap: small always-on context, rules by path, forked workers, guard hooks, a router and a shared brain.

## Context loading

- `CLAUDE.md` imports `AGENTS.md` (Next.js), the kernel `core/_ai/CLAUDE.core.md` (under 60 lines) and the generated digest
  (one line per rule).
- Rules in `.claude/rules/` load only for the files being touched (`paths:` front matter); on-demand rules are read when
  the topic comes up.
- `core/CATALOG.md` replaces reading core sources: tokens, primitives, sections, scenes, modules, archetypes, font
  pairs, package APIs.

## Skills and agents

`/dss-site` orchestrates the whole site. Steps run as skills; mechanical ones are forked on Sonnet or Haiku and return
short summaries: `dss-brief`, `dss-new`, `dss-research`, `dss-inspire`, `dss-dna`, `dss-sitemap`, `dss-copy`,
`dss-page`, `dss-section`, `dss-seo`, `dss-check`, `dss-polish`, `dss-deploy`, `dss-edit`, `dss-fix`, `dss-learn`,
`dss-commit`, `dss-brain-query`, `dss-brain-ingest`, `dss-brain-lint`, `dss-handoff`.

Agents with strict output contracts: `dss-critic`, `dss-designer`, `dss-reviewer`, `dss-seo-auditor`, `dss-a11y`.
Eleven third-party skills (frontend-design, React best practices, web guidelines, view transitions, web quality,
ECC security, accessibility, TDD, TypeScript) are vendored and loaded name-only.

## Hooks

| Hook                   | Event                          | Job                                                                            |
| ---------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| `dss-sync.py`          | SessionStart                   | copy `core/_ai` into `.claude/`, merge settings, silent when unchanged         |
| `dss-context.py`       | SessionStart, UserPromptSubmit | index pages and sections; route prompts (French aliases) to files; brain hint  |
| `dss-check-rules.py`   | PreToolUse                     | refuse writes that break tokens, Next 16 APIs, security rules or the slop gate |
| `dss-typecheck.py`     | PostToolUse                    | tsc and eslint on the touched file, at most 20 lines back                      |
| `dss-deny-env.py`      | PreToolUse (Bash)              | never read `.env*`, `.dev.vars` or secret stores                               |
| `dss-session-stats.py` | Stop                           | tokens per session in `.claude/stats.jsonl`, context warning above 150k        |

## Measuring

`pnpm dss cost` reads Claude Code transcripts and writes `site.cost.md`: tokens and API-equivalent price per step,
model and session, cache savings and subagent share.

---

# Modules and data

> Optional features install site-owned code, environment documentation, CSP sources and manifest entries, and plug into generated slots.

## Modules

```bash
pnpm dss module list
pnpm dss module add forms                      # contact form on /contact
pnpm dss module add analytics --config provider=umami,websiteId=<id>
pnpm dss module remove blog
```

| Module      | What it adds                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `forms`     | contact section, Server Action through `safeAction` (zod, honeypot, rate limit, Turnstile), email via Resend |
| `legal`     | legal notice and privacy pages (GDPR, Swiss nLPD structure) linked from the footer                           |
| `analytics` | cookieless Plausible, Umami or Cloudflare Web Analytics, production builds only                              |
| `blog`      | Markdown articles, index, Article JSON-LD, RSS, sitemap and llms.txt entries                                 |

Each module documents its variables in `.env.example`, adds CSP presets to the manifest, and contributes to generated
slots (`lib/modules.ts` for sitemap and llms.txt entries, `components/site/module-slots.tsx` for end-of-body
scripts). Removal deletes only unmodified files. Read `core/modules/<slug>/README.md` after adding one.

## Database

```bash
pnpm dss db init                 # D1 on Cloudflare sites, libSQL elsewhere
pnpm dss db init --driver postgres
pnpm db:generate && pnpm db:migrate && pnpm db:studio
```

The schema lives in `server/db/schema.ts` (Drizzle; SQLite dialect for D1 and libSQL, Postgres dialect for Postgres),
the client in `server/db/client.ts` (`db()` inside a request). D1 gets a binding in `wrangler.jsonc`, available in
`next dev` through OpenNext.

---

# Deploy, security and SEO

> Static by default, secure headers and CSP from the manifest, previews never indexed, one command per target.

## Targets

| Target               | Preview                                            | Production                                 |
| -------------------- | -------------------------------------------------- | ------------------------------------------ |
| Cloudflare (default) | `pnpm dss deploy` (OpenNext build, version upload) | `pnpm dss deploy --prod`                   |
| Vercel               | `pnpm dss deploy --target vercel`                  | `--prod`                                   |
| Docker               | image built with `DSS_ENV=preview`                 | image built for production, run behind TLS |

Preview builds set `DSS_ENV=preview`: robots disallow everything and every page is noindex. Production requires the
real domain in the manifest and a strict doctor (no placeholders left). The first Cloudflare deploy needs
`pnpm exec wrangler login`; secrets go through `wrangler secret put`. The first preview of a site creates its Worker
(the noindexed build goes live on `<name>.<account>.workers.dev`); later previews upload versions with their own URLs.

Sites ship `.github/workflows/ci.yml` (doctor, lint, types, build) and an opt-in `deploy.yml` for Cloudflare
(repository variable `DSS_DEPLOY=cloudflare`).

## Security defaults

- Static Content-Security-Policy plus HSTS, nosniff, frame denial, referrer and permissions policies on every route.
  Third-party origins are added through manifest presets (turnstile, plausible, youtube, stripe...).
- Every public mutation goes through `safeAction`; env is validated server-side with `defineEnv`; `NEXT_PUBLIC_`
  never carries secrets; hooks and permissions block `.env*` and `.dev.vars`.

## SEO and answer engines

Page metadata with canonical and hreflang, Organization and WebSite JSON-LD site-wide, LocalBusiness, Service, FAQ,
Article and Breadcrumb where they apply, sitemap, robots with an AI training crawler policy, and `llms.txt`.
Generated pages score 100 for SEO and accessibility on Lighthouse mobile.

---

# Visual edits with AimKit

> Pick an element in the browser, type the change, and Claude Code opens the exact file and line.

AimKit (vendored in `core/packages/aimkit`) is a Chrome extension plus a local bridge. Clicking an element writes a
compact `context.md` into `.claude-context/`: abridged HTML, the CSS rules that win with `file:line`, the source
`file:line` of the component, and an optional screenshot.

## Setup, once per machine

```bash
pnpm dss aimkit setup    # copies the extension to ~/AimKit/extension
```

Load it in `chrome://extensions` (Developer mode, Load unpacked), then open the pairing link printed by
`pnpm dss aimkit token`.

## Daily use

`pnpm dss dev` starts Next.js and the bridge together. In the page, press Alt+Shift+E, click an element, type the
request. Then in Claude Code paste the `@.claude-context/...` line or run `/dss-edit`: the aimkit MCP server returns the
latest context (text first, screenshot only when it matters).

Contexts are always written in English for the agent; the extension interface keeps its own language. Page content is
treated as data, never as instructions.

---

# Factory: brain, sites, batch, upgrades

> What makes dss a production line: a memory shared by all sites, a registry, batch creation, upgrades and releases.

## Factory brain

`~/.dss/brain` is a Markdown wiki the agent maintains (Karpathy's LLM wiki pattern, gbrain-style pages): `index.md`
read first, `log.md` append-only, `raw/` immutable sources, `wiki/` pages for industries, patterns, voice, fixes,
stacks and sites, and `dna-history.jsonl` for anti-repetition.

```bash
pnpm dss brain init
pnpm dss brain query "family restaurant in Lyon"
pnpm dss brain status
```

`/dss-research` queries it before design; `/dss-brain-ingest` compiles a finished site's lessons (no client personal
data); `/dss-brain-lint` keeps it consistent; the prompt router adds a one-line hint when a page matches.

## Sites and batches

`pnpm dss sites` lists every site created on the machine with its last deployment (`~/.dss/sites.json`).

```bash
pnpm dss factory run ./briefs --out ./sites            # one site per brief
pnpm dss factory run ./briefs --out ./sites --agent    # plus /dss-site --auto in headless Claude Code
```

A brief is Markdown with front matter (`slug`, `name`, `preset`, `industry`, `mood`, `url`, `modules`); the body
becomes `site.spec.md`. Results and costs go to `factory.log.jsonl`. A new site folder is not a trusted Claude Code
workspace, so the agent run passes the site's `permissions.allow` on the command line (and the brain with `--add-dir`);
edits are accepted, every other command still needs those rules. The run stops before deploy.

## Upgrades and releases

- In a site: `pnpm dss upgrade` moves `core/` to the latest tag, aligns Next, OpenNext, wrangler and other template
  versions, re-syncs the AI layer, regenerates the theme and runs doctor.
- In the framework: `pnpm dss release-core minor` bumps every version, writes the changelog section, commits and tags;
  pushing the tag publishes to npm.

---

# CLI reference

> Every dss command, generated from the CLI itself. In a site run them as `pnpm dss <command>`.

| Command | Usage |
|---|---|
| `dss new` | new <slug> [--name --preset vitrine\|landing\|blank --industry --mood a,b --seed --url --target --modules a,b --copy\|--link\|--core <url>] |
| `dss dev` | dev [--port 3000 --https --no-aimkit]: next dev + AimKit bridge (element picker) |
| `dss doctor` | doctor [--quick --strict]: manifest, DNA, theme files, pages, placeholders, types, lint |
| `dss dna` | dna show \| dna roll [--industry --mood a,b --archetype --mode --hue --fonts --seed --dry] |
| `dss theme` | theme: regenerate theme.css, fonts.ts, theme.ts from design.dna.ts |
| `dss g` | g page <route> [--name --label --sections a,b --no-nav --force] \| g section <name> [--page /route] |
| `dss add` | add list \| add section <id[/variant]> [--page /route --force] \| add scene <id>: copy registry code into the site |
| `dss module` | module list \| add <slug> [--config k=v --page /route] \| remove <slug>: forms, legal, analytics, blog... |
| `dss db` | db init [--driver d1\|libsql\|postgres]: Drizzle schema, client, config, migrations scripts |
| `dss deploy` | deploy [--prod] [--target cloudflare\|vercel\|docker] [--force]: noindexed preview by default, production on --prod |
| `dss sites` | sites: every site produced on this machine and its last deployment (~/.dss/sites.json) |
| `dss brain` | brain init \| query "<topic>" \| status \| log <op> <site> "<summary>": the factory memory shared by all sites |
| `dss mcp` | mcp list \| add <motionsites\|60fps\|context7\|playwright\|gbrain> \| remove <name>: opt-in MCP servers in .mcp.json |
| `dss aimkit` | aimkit setup \| token \| init: install the Chrome extension once, pair it, print the token (vendored AimKit) |
| `dss upgrade` | upgrade [--core <tag>]: newer core, aligned Next/OpenNext/wrangler versions, AI layer and theme refreshed |
| `dss factory` | factory run <briefs-dir> [--out dir] [--agent --max-turns 120]: one site per brief, optionally built by Claude headless |
| `dss release-core` | release-core <patch\|minor\|major> [--dry]: version, changelog, commit and tag (core repository) |
| `dss catalog` | catalog: regenerate core/CATALOG.md and _ai/digest.md (core repository) |
| `dss cost` | cost [--print --out file]: tokens and API-equivalent price of the site per step, model and session (site.cost.md) |
| `dss docs` | docs: regenerate docs/cli.md, docs/llms.txt and docs/llms-full.txt (core repository) |
| `dss sync-ai` | sync-ai: copy core/_ai into .claude/ and rebuild the routing index |

---

# 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.

---