@fracazo/design-system 0.2.1 → 0.7.0

package/skills/product-design/references/rules.md

@@ -0,0 +1,319 @@
+# Rules
+
+Every rule has a stable ID, a scope, the rule, why, exceptions, its source
+and an example pair. `Enforced by` says who catches a violation today:
+`lint` (the package's ESLint plugin, rule `design-system/<id>`; `lint,
+warn` means it ships at warning level until the product is clean),
+`contract` (ds-check-brand), `base` (the house base layer in globals.css),
+`prose` (this skill and review), or `lint candidate` (checkable by code, not
+yet written; see coverage-gaps.md).
+Cite the ID in findings. Add a rule only per SKILL.md's integrity section.
+
+## Colour
+
+### rule/no-colour-literal
+Scope: any `className` in product code, stories and the showcase.
+Rule: no hex, oklch(), rgb() or hsl() value, including arbitrary utilities
+like `bg-[#fff]`.
+Why: a literal drifts from the brand file and breaks dark mode silently.
+Exceptions: renderers that cannot use CSS variables (react-pdf, email HTML,
+OG images), listed per product in its ESLint config.
+Source: DESIGN.md, Guardrails; guardrails/eslint.ts.
+Enforced by: lint.
+Bad: `className="bg-[#c2727a] text-white"`
+Good: `className="bg-primary text-primary-foreground"`
+
+### rule/no-dark-pairs
+Scope: any `className`.
+Rule: never a hand-authored light and dark pair (`bg-x dark:bg-y`) for a
+colour. The token owns both themes; write one class.
+Why: two literals drift independently and the dark half is never reviewed.
+Exceptions: `dark:` on a non-colour property (opacity, display) is fine.
+Source: DESIGN.md, Reject list; BirthGuide SPEC_016.
+Enforced by: lint (the arbitrary-value form). A `dark:` token beside its
+light twin is still prose.
+Bad: `bg-[#E6EFE2] dark:bg-[oklch(0.34_0.045_150)]`
+Good: `bg-chip-1-soft`
+
+### rule/on-dark-ramp
+Scope: children of an always-dark surface (`bg-dark`, `bg-dark-2`).
+Rule: text and icons use the mode-constant on-dark ramp (`text-dark-ink` to
+`text-dark-faint-2`, `text-dark-brand` for the one accent), never a
+theme-varying token such as `text-ink` or `text-ink-3`.
+Why: the surface never changes theme, so its text must not; `text-ink` on
+the footer renders espresso on espresso in light mode.
+Exceptions: none.
+Source: DESIGN.md, Colour; BirthGuide usage story.
+Enforced by: lint, warn (a theme-varying text token inside a JSX subtree
+whose root carries `bg-dark`; a nested light surface resets the context).
+Bad: `<footer className="bg-dark"><p className="text-ink">`
+Good: `<footer className="bg-dark"><p className="text-dark-ink-2">`
+
+### rule/semantic-first
+Scope: any styling decision.
+Rule: semantic utilities (`bg-card`, `text-muted-foreground`,
+`border-border`) before primitives (`bg-band`, `text-ink-3`); primitives
+only where no role fits.
+Why: semantics move together across products and themes; primitives are
+brand material.
+Exceptions: alternating bands, captions on light surfaces, chips, glows and
+the always-dark family, which have no semantic role by design.
+Source: DESIGN.md, Colour.
+Enforced by: prose.
+Bad: `text-ink-2` for body copy under a heading.
+Good: `text-muted-foreground`.
+
+### rule/divergent-six
+Scope: brand files and roles.css.
+Rule: secondary, muted, border, input, muted-foreground and
+accent-foreground hold their own literals per theme. Never alias them to a
+primitive.
+Why: dark tuned them away from the primitives; dark border and input are
+translucent hairlines, nothing like the opaque warm line.
+Exceptions: none.
+Source: DESIGN.md, Tokens; roles.css header.
+Enforced by: contract (the six are required in both light and dark) and
+prose.
+Bad: `--border: var(--line);` in the dark block.
+Good: `--border: oklch(1 0 0 / 10%);`
+
+### rule/no-stock-palette
+Scope: product UI (not PDFs or emails).
+Rule: no Tailwind default palette colour (`amber-500`, `blue-600`,
+`gray-200`) in a className.
+Why: it competes with the brand, ignores dark mode and looks generic.
+Exceptions: none in UI. Known violation: BirthGuide `PregnancyProgress.tsx`
+(coverage gap).
+Source: BirthGuide brand spec 9.2; DESIGN.md, Colour.
+Enforced by: lint, warn (BirthGuide has 48 occurrences, mostly in the
+calculator tools; a cleanup spec turns it to error).
+Bad: `bg-amber-100 text-amber-800`
+Good: `bg-highlight-soft text-highlight-ink`
+
+### rule/status-colour-means-preference
+Scope: `status-want`, `status-ifnec`, `status-no` and their `-soft` washes.
+Rule: use only to encode a reader's preference state; never as decoration
+or as generic success and danger colours.
+Why: colour that carries meaning must carry only that meaning.
+Exceptions: none. Destructive actions use `destructive`.
+Source: DESIGN.md, Colour; roles.css comment.
+Enforced by: prose.
+Bad: a green `bg-status-want-soft` behind a marketing testimonial.
+Good: the "Want" chip on a preference card.
+
+## Radius, type and space
+
+### rule/no-radius-literal
+Scope: any `className`.
+Rule: radii are `rounded-sm` to `rounded-4xl` plus `rounded-20`. No
+`rounded-[Npx]`.
+Why: a new radius is a design decision; 34 hand-written 20px radii once
+drifted before `rounded-20` named them.
+Exceptions: none. A genuinely new radius becomes a token first.
+Source: DESIGN.md, Radius.
+Enforced by: lint.
+Bad: `rounded-[14px]`
+Good: `rounded-xl`
+
+### rule/concentric-radii
+Scope: a rounded child whose corners meet a rounded parent's.
+Rule: outer radius = inner radius + padding, landing on a named token
+(lg + p-4 = 4xl, md + p-3 = rounded-20, sm + p-4 = 3xl, md + p-2.5 = 2xl,
+sm + p-3 = 2xl).
+Why: concentric corners read as one shape; equal radii at different depths
+read as a mistake.
+Exceptions: corners that never meet; gaps that would need a negative inner
+radius.
+Source: DESIGN.md, Radius; BirthGuide SPEC_021 (exemplar
+concentric-radii-and-button-optics).
+Enforced by: prose.
+Bad: `rounded-lg p-4` parent around a `rounded-lg` child.
+Good: `rounded-4xl p-4` parent around a `rounded-lg` child.
+
+### rule/no-arbitrary-clamp
+Scope: any `className`.
+Rule: fluid sizes are the named roles `text-display`, `text-section-title`,
+`text-lede`, `py-band`, `mt-band-gap`. No `text-[clamp(...)]`.
+Why: near-miss clamps drift a few pixels from one another and nobody can
+tell which is intended.
+Exceptions: a deliberate one-off with an inline disable stating why (five
+exist in BirthGuide). birthplans.app has the rule off pending its type-role
+pass; no new clamp literals there either.
+Source: DESIGN.md, Type; exemplar clamp-drift-to-named-roles.
+Enforced by: lint (BirthGuide, starter); prose (birthplans until the pass).
+Bad: `text-[clamp(1.9rem,4vw,3rem)]`
+Good: `text-section-title`
+
+### rule/tap-targets
+Scope: interactive elements on coarse pointers.
+Rule: at least 44px; buttons and inputs 48px.
+Why: one-handed use, at 3am, on a phone.
+Exceptions: inline text links.
+Source: PRINCIPLES.md technical rules; DESIGN.md, Accessibility.
+Enforced by: base (`@media (pointer: coarse)` block) for the package
+components; prose for custom controls.
+
+### rule/inputs-16px
+Scope: text inputs, selects, textareas.
+Rule: font-size at least 16px.
+Why: iOS Safari zooms into smaller inputs on focus.
+Exceptions: none.
+Source: base layer comment.
+Enforced by: base.
+
+## Motion
+
+### rule/transition-for-interactive-state
+Scope: hover, selection, expand, collapse and any state the reader can
+reverse mid-animation.
+Rule: CSS transitions, not keyframes.
+Why: transitions retarget when interrupted; keyframes restart from zero.
+Exceptions: one-shot staged sequences such as a hero entrance.
+Source: DESIGN.md, Motion; BirthGuide principles story.
+Enforced by: prose.
+
+### rule/entrance-once-per-visit
+Scope: entrance and load animations.
+Rule: play once per visit (session flag set before first paint), render at
+rest on reloads and in-visit navigation, collapse under
+`prefers-reduced-motion`.
+Why: replaying an entrance on every reload reads as a bug and costs the
+reader time.
+Exceptions: none.
+Source: BirthGuide layout.tsx; DESIGN.md, Motion.
+Enforced by: prose.
+
+### rule/no-clipped-ambient
+Scope: glow blobs, gradients and other ambient layers.
+Rule: an ambient layer must not be clipped at a section boundary; dissolve
+it with a mask or extend the clip past the blob and its blur.
+Why: a clipped blur draws a hard horizontal seam exactly where two sections
+meet.
+Exceptions: none.
+Source: exemplar hero-glow-seam.
+Enforced by: prose (verify rendered).
+
+## Interaction and components
+
+### rule/focus-visible
+Scope: any element with a focus ring.
+Rule: use `focus-visible:` for rings, not `focus:`.
+Why: Radix autofocuses the first control on open, so a `focus:` ring paints
+on a modal the reader opened with a mouse. Keyboard users still get the
+ring with `focus-visible:`.
+Exceptions: none. Re-running `shadcn add` reverts the dialog; the reason is
+recorded above the element.
+Source: exemplar dialog-close-focus-visible.
+Enforced by: lint, warn (`focus:ring`, `focus:outline`, `focus:border`).
+The skip link in each layout is a legitimate `focus:` use; disable inline
+with the reason.
+Bad: `focus:ring-2 focus:ring-ring`
+Good: `focus-visible:ring-2 focus-visible:ring-ring`
+
+### rule/one-emphasis-signal
+Scope: cards, offers, any surface competing for attention.
+Rule: a surface carries one emphasis signal (a chip, a tinted border, a
+heavy shadow, an accent button, bold uppercase type). When it carries
+several, remove until one remains.
+Why: stacked signals cancel each other and read as shouting.
+Exceptions: the single primary action of a step may sit inside an
+emphasised card.
+Source: exemplar calm-the-offering-cards.
+Enforced by: prose.
+
+### rule/house-pattern-for-answers
+Scope: questionnaire and preference capture in both products.
+Rule: enumerable answers use the house icon-card groups (single or multi
+select), not bare radios, checkboxes or selects. A single date uses a
+native date input.
+Why: 44px tappable cards with icons are the product's tested answer
+pattern; the OS date picker beats any custom one on mobile.
+Exceptions: dense utilitarian or admin UI may use RadioGroup, Checkbox,
+Select.
+Source: component intent blocks (radio-group, checkbox, select, calendar).
+Enforced by: prose.
+
+### rule/sheet-on-mobile-aside-on-desktop
+Scope: supplementary content beside a flow.
+Rule: a bottom Sheet on mobile; an aside on desktop, split at the
+breakpoint. Dialog only for a focused task that needs full attention.
+Why: a modal is the heaviest surface; supplementary content should not
+take the whole screen on desktop.
+Exceptions: previews and confirmations use Dialog on all sizes.
+Source: component intent blocks (sheet, dialog, popover).
+Enforced by: prose.
+
+### rule/no-template-reflexes
+Scope: composition.
+Rule: no centred hero plus three cards by default, no metric boxes, no
+badges as metadata, no nested cards, no decorative gradients or glass, no
+carousels or autoplay, no visible theme switcher.
+Why: these are the shapes a generator reaches for when it has not framed
+the reader's job.
+Exceptions: a card grid when the items are genuinely peer units.
+Source: DESIGN.md, Reject list.
+Enforced by: prose.
+
+### rule/no-values-in-stories
+Scope: Storybook stories and the package showcase.
+Rule: stories import components and tokens; they never define a colour,
+spacing or variant of their own.
+Why: Storybook is a consumer; a missing value is a finding, not a local
+fix.
+Exceptions: none.
+Source: BirthGuide usage story.
+Enforced by: lint (colour rule covers stories); prose.
+
+## Copy
+
+### rule/no-em-dash
+Scope: everything: UI copy, comments, commit messages, generated documents,
+metadata.
+Rule: never an em dash. Commas, colons, full stops, parentheses instead.
+Why: house style across every product and repo.
+Exceptions: none (legacy occurrences are removed when a file is touched).
+Source: every CLAUDE.md; DESIGN.md.
+Enforced by: lint, warn (every U+2014 in a source file, comments
+included); docs and commit messages stay prose.
+
+### rule/voice-bans
+Scope: all user-facing writing.
+Rule: no wellness-speak ("your journey", "mama", "you've got this"), no
+filler affirmations ("amazing", "incredible"), no AI marketing words
+("seamless", "empower", "unlock", "cutting-edge", "revolutionise",
+"great question"). Short sentences, one idea each. Read aloud.
+Why: the products earn trust by sounding like a midwife who respects the
+reader.
+Exceptions: none.
+Source: PRINCIPLES.md voice rules; both CLAUDE.md copy sections.
+Enforced by: prose (a word list is a lint candidate).
+
+### rule/sentence-case
+Scope: headings, buttons, labels, navigation.
+Rule: sentence case. All caps only on the mono kicker label with wide
+tracking.
+Why: Title Case reads as marketing; all caps reads as shouting.
+Exceptions: proper nouns.
+Source: PRINCIPLES.md; DESIGN.md, Type.
+Enforced by: prose.
+
+### rule/english-per-product
+Scope: copy, comments, commit messages.
+Rule: BirthGuide is Australian English (caesarean, labour, colour);
+birthplans.app is US English (cesarean, labor, color, anesthesiologist).
+The package and the starter are Australian English.
+Why: each product speaks to its market; mixing reads as carelessness.
+Exceptions: Tailwind class names stay US spelling everywhere.
+Source: each CLAUDE.md language section.
+Enforced by: prose.
+
+### rule/claim-only-what-ships
+Scope: landing and product copy.
+Rule: outcomes and features named in copy are ones the product delivers
+today.
+Why: the reader is deciding under pressure; an overclaim is a broken
+promise at the bedside.
+Exceptions: none.
+Source: BirthGuide landing commits ("make the outcome copy claim only what
+the product delivers").
+Enforced by: prose.

package/skills/product-design/references/surfaces.md

@@ -0,0 +1,50 @@
+# Surfaces
+
+Load when: starting any work, to name the scope; and for product-specific
+routes.
+Canonical owner: BirthGuide `_context/PRINCIPLES.md` (scopes and budgets);
+`DESIGN.md`, Two surface scopes and the brand chapters.
+
+## Scopes
+
+**Engagement**: the product itself. Failure is "it did not load when I
+needed it". Cold start under 1.5s on a three-year-old phone on slow 4G,
+first paint under 1s; no hero imagery, no decorative motion; optimistic
+writes; 44px targets; 16px inputs.
+
+**Conversion**: landing, guides, articles. Failure is "it looked cheap" or
+"search buried it". LCP under 2.5s, CLS under 0.1, INP under 200ms, first
+load under 1MB, images under 200KB each and 500KB per page. Illustration
+over photography, custom only; one custom typeface; entrance motion once
+per visit.
+
+The hospital case applies to both: a landing page opened on a ward tour is
+still read under pressure.
+
+## BirthGuide (Australian English)
+
+- Conversion: `/` (hero, offerings, program curriculum, comparison,
+  testimonials, pricing, FAQ, footer), `/guides/*`, `/tools/*`.
+- Engagement: `/questionnaire`, `/plan/edit/*`, `/plan/[slug]` (the
+  published plan read at the bedside), downloads, `/program/*` sessions,
+  `/resume`, `/unsubscribe`.
+- Always-dark: footer and showcase bands. Landing phone mock uses `dark-3`
+  and `dark-4`.
+- Served token API: `public/brand.css` (generated; lint fails when stale).
+- Local Storybook is the component gallery for both products.
+
+## birthplans.app (US English)
+
+- Conversion: `/` (hero, plan comparison, free answers, pricing, FAQ, stat
+  band), guides.
+- Engagement: `/questionnaire` (with the did-you-know bar and the
+  preference status ramp), `/plan/*` preview and download; one output, the
+  PDF.
+- Always-dark: footer.
+- Fluid-type lint rule is off until the type-role pass; no new clamps.
+- No Storybook, no served brand.css.
+
+## Starter
+
+One proof page. Delete it. Everything else here applies once the product
+has surfaces.

package/skills/product-design/references/tokens.md

@@ -0,0 +1,54 @@
+# Tokens
+
+Load when: any decision that picks a colour, surface, shadow or theme
+behaviour.
+Canonical owner: `css/roles.css` (roles and the brand contract) and the
+product's brand file (values). `DESIGN.md`, Tokens and Colour, explains the
+model. Do not restate values here; read them.
+
+## Decide in this order
+
+1. Is there a shadcn semantic for it? `bg-background`, `bg-card`,
+   `bg-popover`, `bg-primary`, `bg-secondary`, `bg-muted`, `bg-accent`,
+   `text-foreground`, `text-muted-foreground`, `border-border`,
+   `border-input`, `ring-ring`, `bg-destructive`. Use it
+   (rule/semantic-first).
+2. Is the surface an alternating band, a caption on a light surface, an
+   accent chip, a glow, or a highlight pill? Use the primitive that names
+   it: `bg-band`, `bg-band-2`, `bg-surface-2`, `text-ink-3`, `chip-1/2/3`,
+   `glow-1/2`, `highlight`.
+3. Is the surface always dark in both themes? `bg-dark` or `bg-dark-2`, and
+   every foreground on it from the on-dark ramp (rule/on-dark-ramp).
+4. Does the colour encode a preference state? `status-*`
+   (rule/status-colour-means-preference).
+5. None of the above: the value does not exist. Do not inline it. Raise a
+   role proposal in the design-system repo (minor version, contract entry,
+   both brand files).
+
+## Things that look wrong and are not
+
+- The six divergent semantics hold literals in both themes and are not
+  aliased (rule/divergent-six). Dark `border` and `input` are translucent
+  white hairlines.
+- `--dark-3` and `--dark-4` exist for the landing phone mock; nothing else
+  should use them.
+- `--headline-accent` behaves differently per brand (BirthGuide: brand ink
+  in light, sand in dark; birthplans: sand, applied only under `dark:`).
+- `chip-3` is the sister product's tint in each brand. Do not "correct" it.
+- `--dark-soft-2`, `--dark-faint`, `--dark-faint-2` are near-identical greys
+  kept on purpose (exact-match discipline). Collapsing them needs Alex.
+
+## Shadows
+
+`shadow-card`, `shadow-card-hover`, `shadow-card-selected` replace flat
+borders with layered depth; selected embeds `var(--primary)` as a ring.
+`shadow-warm-sm/md/lg` for landing cards (dark swaps to black-based
+shadows). `shadow-bar` under a floating bottom bar. Spacing separates
+before a border does. No raw `shadow-[...]`.
+
+## Adding a role
+
+A new or renamed role: add to `roles.css` (theme mapping and the contract
+lists), value it in every brand file, bump the package minor, note it in
+the changelog, then bump each product and snapshot compare (additions
+only). A change that a brand must satisfy anew is a major.

package/skills/product-design/references/type-and-space.md

@@ -0,0 +1,42 @@
+# Type and space
+
+Load when: sizes, weights, radii, spacing rhythm, alignment.
+Canonical owner: `css/roles.css` (fluid type roles, radius ramp, band
+rhythm); `DESIGN.md`, Radius and Type.
+
+## Type
+
+- One sans per product, one mono, mapped in the brand file's `@theme` block
+  from `next/font` variables. `display: optional` so text never blocks.
+- Headings: weight 600, tracking -0.02em, `text-wrap: balance` (base
+  layer). Paragraphs `text-wrap: pretty`.
+- Fluid sizes are roles (rule/no-arbitrary-clamp): `text-display` (with its
+  0.9 line-height companion) for the one display headline,
+  `text-section-title` for section headings, `text-lede` for the lede
+  (leading set at the use site). Everything else is the static scale.
+- Numbers in columns: `tabular-nums`. Headline figures stay proportional.
+- Mono is for code, identifiers and the small uppercase kicker
+  (`font-mono text-xs font-semibold uppercase tracking-[0.16em]
+  text-ink-3`); nothing else, and nothing else is all caps
+  (rule/sentence-case).
+- Prose measure around 60 to 68 characters (`max-w-prose`).
+
+## Radius
+
+Ramp from the brand's `--radius`: `sm` to `4xl`, plus `rounded-20`
+(rule/no-radius-literal). Concentric corners: outer = inner + padding on a
+named token (rule/concentric-radii). Text buttons sit on a size-scaled
+ladder (xs sm, sm md, default lg, lg xl); icon-only buttons are circles.
+
+## Rhythm
+
+Landing sections: `py-band` for section verticals, `mt-band-gap` between a
+section header and its content. Inside a card the padding steps are `p-4`,
+`p-6`, `p-7` (the house card is `rounded-20 p-7 shadow-warm-sm`). Spacing
+off the 4px grid is a smell; check whether an existing step fits first.
+
+## Alignment
+
+Shared baselines and unmistakable gutters. A narrow table in a wide
+section, or a card that is the only misaligned element in a row, is a
+defect at P2.

package/skills/product-design/references/verification.md

@@ -0,0 +1,35 @@
+# Verification
+
+Load when: before claiming a change is safe, complete or zero-visual.
+Canonical owner: each product's CLAUDE.md verification section and
+`scripts/design-snapshot.ts`; the package's `pnpm check` and `pnpm build`.
+
+## Every UI change
+
+1. `pnpm lint` (ESLint guardrails plus the brand contract; BirthGuide also
+   checks the served brand.css).
+2. `pnpm typecheck` or `tsc --noEmit`; `pnpm build`.
+3. Render it: both themes, 360px and 1280px, every materially changed
+   state, keyboard order and focus, long content. Say what you saw; never
+   claim visual verification from source alone.
+
+## Token, role or component work
+
+- Snapshot before editing (`pnpm design:snapshot baseline.json`), after
+  (`after.json`), compare. A refactor compares identical. An intentional
+  change shows only the keys you meant to move; state the count.
+- Renames: apply the rename map to the baseline's keys and require zero
+  value differences (a small comparer script did this twice on 5 Sep 2026;
+  map order matters, longest names first).
+- Clear `.next` after restructuring the CSS import graph; stop any other
+  dev server on the same checkout first.
+- `design-baseline.json` is the committed intended state. An intentional
+  change regenerates it in the same branch and the commit names the delta.
+
+## Package release
+
+`pnpm check`, `pnpm build`, `ds-check-brand` against both product brand
+files, `ds-build-brand-css --check` against BirthGuide's committed
+`public/brand.css`. Alex publishes (browser auth); tag `vX.Y.Z`. After a
+merge that adds devDependencies, `pnpm install` in the main checkout before
+publishing.

package/template/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+## What this is
+
+A new product on `@fracazo/design-system`, written by `ds-init` from the
+package's `template/`: Next 16, Tailwind v4, the package, one blank brand
+file, the guardrails on. Rewrite the top of this file to describe the
+product and keep the rules below.
+
+## Read first
+
+When shaping, building, reviewing or writing copy for user-facing UI, load
+`node_modules/@fracazo/design-system/skills/product-design/SKILL.md` first
+It
+names the request mode, routes to the reference that applies and cites rules
+by stable ID. Skip it for backend-only work, telemetry, generated files and
+tests with no shipped UI.
+
+`node_modules/@fracazo/design-system/DESIGN.md` is the written authority:
+who the reader is, the priority order, how a page is composed, the reject
+list. `css/roles.css` in the same package holds the roles and the brand
+contract. The component intent lives in each component's source.
+
+## Rules
+
+- The brand lives in `src/system/brands/*.css` and nowhere else. No colour
+  literal, radius literal or clamp() size in a `className`; ESLint errors on
+  them. A value the roles do not cover is a proposal for the design-system
+  repo, not a local addition.
+- Components come from `@fracazo/design-system/ui/*`. Never copy one into
+  this repo to change it; change it upstream and bump the dependency. A
+  component that must import app code is the exception and stays here.
+- `pnpm lint` runs ESLint and the brand contract check and must pass before
+  a merge. `pnpm typecheck` and `pnpm build` too.
+- Never use em dashes, anywhere. Commas, colons, full stops instead.
+- Feature branch, then fast-forward merge to `main`; no PRs. Conventional
+  Commits, present tense.
+- Do not add dependencies without discussing first.
+
+## Tooling notes
+
+- pnpm 11: `pnpm-workspace.yaml` approves the native build scripts and
+  excludes `@fracazo/design-system` from the minimum-release-age gate, so a
+  fresh release of the package installs the day it ships.
+- The site follows the system colour scheme; there is no manual toggle. The
+  inline script in `layout.tsx` sets `.dark` before first paint and
+  `ThemeSync` follows live changes.

package/template/README.md

@@ -0,0 +1,16 @@
+# starter
+
+A product on [`@fracazo/design-system`](https://github.com/fracazo/design-system),
+written by `ds-init`. Rename this file's title, then follow the numbered
+steps in the package README under "Start a product".
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Before every merge:
+
+```bash
+pnpm lint && pnpm typecheck && pnpm build
+```

package/template/eslint.config.mjs

@@ -0,0 +1,20 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import { designSystemGuardrails } from "@fracazo/design-system/eslint";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+  // Both design system guardrails, on from day one: no raw colour values and
+  // no arbitrary clamp() type sizes in a className. Add an exemption only for
+  // a renderer that genuinely cannot use CSS variables (react-pdf, email HTML,
+  // OG images), and say why in a comment next to it.
+  designSystemGuardrails({
+    files: ["src/**/*.{ts,tsx}"],
+    ignores: [],
+  }),
+]);
+
+export default eslintConfig;

package/template/gitignore

@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Claude Code local tooling
+.claude/

package/template/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

package/template/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "starter",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint && pnpm brand:contract",
+    "typecheck": "tsc --noEmit",
+    "brand:contract": "ds-check-brand src/system/brands/starter.css",
+    "brand:build": "ds-build-brand-css --brand src/system/brands/starter.css --out public/brand.css --name Starter --url https://example.com"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@fracazo/design-system": "^0.6.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.0",
+    "next": "16.1.6",
+    "radix-ui": "^1.6.7",
+    "react": "19.2.3",
+    "react-day-picker": "^9.14.0",
+    "react-dom": "19.2.3",
+    "react-hook-form": "^7.87.0",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}