create-nexst-monorepo 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-nexst-monorepo",
+  "version": "0.1.0",
+  "description": "Scaffold a Next.js + NestJS monorepo with bun, turbo, oxlint, vitest, Prisma, Docker, kustomize and CI",
+  "keywords": ["create", "monorepo", "nextjs", "nestjs", "bun", "template"],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-nexst-monorepo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.4"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --target=node --outfile dist/index.js",
+    "prepack": "bun run build && bun scripts/pack-template.ts",
+    "postpack": "rm -rf template",
+    "lint": "oxlint",
+    "lint:ts": "tsc --noEmit",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "test": "vitest run",
+    "test:matrix": "bun scripts/verify-matrix.ts"
+  },
+  "devDependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@types/node": "^26.6.3",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  }
+}

package/template/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "nexst-plugins",
+  "interface": {
+    "displayName": "Nexst Plugins"
+  },
+  "plugins": [
+    {
+      "name": "superpowers",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/obra/superpowers.git",
+        "ref": "v6.2.0"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/template/.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "enabledPlugins": {
+    "context7@claude-plugins-official": true,
+    "frontend-design@claude-plugins-official": true
+  }
+}

package/template/.claude/skills/frontend-design/LICENSE.txt

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/template/.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: frontend-design
+description: Use when building, restyling, or reviewing any user-facing UI — a page, component, layout, landing page, artifact, or prototype — and whenever a decision about colour, typography, spacing, motion, or interface copy has to be made.
+license: Adapted from Anthropic's frontend-design skill; complete terms in LICENSE.txt
+---
+
+# Frontend Design
+
+Approach this as the design lead at a small studio: every decision about
+palette, typography, layout, and copy is deliberate and defensible, and nothing
+ships because it was the default.
+
+**Two situations, opposite disciplines. Decide which one you are in first.**
+
+## Which mode
+
+**Does this render inside the product?** (anything in `apps/web`, or any UI a
+user of this app will see)
+
+| | **Product mode** — yes | **Studio mode** — no |
+|---|---|---|
+| Palette, type, radius | Fixed. Use the tokens. | Yours to design. |
+| Where distinctiveness comes from | Layout, information design, copy | Everything |
+| Success looks like | Indistinguishable from the rest of the app | Could not be mistaken for anyone else's |
+
+Studio mode covers standalone artifacts, marketing one-offs, prototypes,
+internal tools, and other projects. When in doubt — if a real user of the app
+could reach it — it is product mode.
+
+---
+
+## Product mode
+
+**Read the semantic tokens in `apps/web/src/app/globals.css` before writing
+markup.** They are the brand: what each colour means in light and dark. If the
+project adds a brand guideline, keep it in `references/brand.md` and read it
+first.
+
+The short version, in the order it goes wrong:
+
+1. **Semantic tokens only.** No raw hex, no ramp step in a component, no
+   `neutral-*`. Every colour exists in both light and dark.
+2. **Reuse the components in `src/components/*`.** They carry variants, focus
+   rings, ARIA wiring, and loading states you would otherwise reimplement worse.
+3. **One primary CTA per page.** Everything else neutral.
+4. **`text-sm` is the default.** Small type and dense spacing are the house style.
+5. **Every string through `next-intl`, in every locale under `apps/web/messages`.**
+6. **Check it in both modes and at `sm:` before calling it done.**
+
+Creative work in product mode goes into *structure*: what the user sees first,
+what collapses, what a row has to say for itself, what the empty state offers.
+Not into new colours. A new hex value here is not a bold choice, it is a bug.
+
+If a design genuinely needs something the system lacks, that is a theme change:
+use **theme-factory** to add it to the theme, validate, emit, and say so — do not smuggle it in as a one-off utility class.
+
+---
+
+## Studio mode
+
+Here the brief is paying for a point of view. Make opinionated choices specific
+to *this* subject and take one real aesthetic risk you can justify.
+
+**Ground it in the subject.** If the brief doesn't pin down what the product is,
+pin it yourself: name the subject, its audience, and the page's single job, and
+state your choice. The subject's own world — its materials, instruments,
+artifacts, vernacular — is where distinctive choices come from. Use memory about
+this human's preferences and past work as a hint.
+
+**Plan before building.** Draft a compact token system first:
+
+- **Colour** — 4–6 named hex values. Build it with **theme-factory** so it comes out as a validated ramp + semantic layer, not five loose swatches.
+- **Type** — faces for 2+ roles: a characterful display face used with restraint, a complementary body face, a utility face for captions or data if needed. Not the families you reach for on every project.
+- **Layout** — a one-sentence concept plus ASCII wireframes to compare options.
+- **Signature** — the one element this page will be remembered by.
+
+**Then critique the plan against the brief before writing code.** Work through a
+similar prompt in your head: if you would have arrived at the same plan for a
+different subject, it is a default, not a choice. Revise that part and say what
+you changed and why.
+
+**Calibration — AI-generated design currently clusters around three looks:**
+(1) warm cream background near `#F4F1EA` + high-contrast serif display +
+terracotta accent; (2) near-black background + one acid-green or vermilion
+accent; (3) broadsheet layout with hairline rules, zero radius, dense columns.
+All are legitimate for some briefs, but they appear regardless of subject.
+Where the brief pins a direction, follow it exactly — the brief's own words
+always win, including when it asks for one of these. Where it leaves an axis
+free, don't spend that freedom on a default.
+
+**The hero is a thesis.** Open with the most characteristic thing in the
+subject's world, in whatever form fits: a headline, an image, an animation, a
+live demo. A big number with a small label, supporting stats, and a gradient
+accent is the template answer — use it only if it is genuinely the best one.
+
+**Structure is information.** Numbering, eyebrows, dividers, and labels should
+encode something true about the content. `01 / 02 / 03` is only right when the
+content actually is a sequence.
+
+**Match complexity to the vision.** Maximalist directions need elaborate
+execution; minimal directions need precision in spacing, type, and detail.
+Elegance is executing the chosen vision well.
+
+**Spend your boldness in one place.** Let the signature element be the one
+memorable thing and keep everything around it quiet. Chanel's rule: before
+leaving the house, look in the mirror and remove one accessory.
+
+---
+
+## Both modes
+
+**Copy is design material.** Words appear to make the interface easier to
+understand. Write from the user's side of the screen — name things by what
+people control, never by how the system is built. Active voice; a control says
+what happens when it is used ("Save changes", not "Submit"), and keeps the same
+name through the whole flow, so a "Publish" button produces a "Published"
+toast. Errors explain what went wrong and how to fix it, in the interface's
+voice; they don't apologise and are never vague. An empty screen is an
+invitation to act. Sentence case, plain verbs, no filler. Each element does
+exactly one job.
+
+**Motion is deliberate.** One orchestrated moment lands harder than scattered
+effects. Extra animation is one of the strongest tells that a design was
+generated rather than designed.
+
+**Quality floor, built in without announcing it:** responsive down to mobile,
+visible keyboard focus, contrast that passes measurement rather than the eye,
+`prefers-reduced-motion` respected, no layout shift.
+
+**Critique your own work as you build.** Take screenshots if the environment
+supports it — a picture is worth 1000 tokens. Do the iteration in your thinking
+and show the human ideas only once you have confidence they will land.
+
+**Watch CSS specificity.** Type-based selectors (`.section`) and element-based
+ones (`.cta`) cancel each other out constantly, especially on section padding
+and margins.
+
+## Common mistakes
+
+| Mistake | Mode | Fix |
+|---|---|---|
+| New hex value for a one-off badge | Product | Use a semantic token, or change the theme properly |
+| Rebuilding an input's frame and error text | Product | Pass the props; the component wires ARIA |
+| Three blue buttons on one screen | Product | One primary CTA, rest neutral |
+| Hardcoded English string | Product | `next-intl` key in every locale |
+| Gradient or frosted-glass panel | Product | Flat surfaces, one accent, hairline borders |
+| Reaching for cream + serif + terracotta | Studio | That is a default, not a choice — revise |
+| Building before the token plan exists | Studio | Plan, critique the plan, then build |
+| Animating everything | Both | One deliberate moment |
+
+## Reference
+
+- `apps/web/src/app/globals.css` — the semantic token system (product mode)
+- `../theme-factory/SKILL.md` — creating, extending, and auditing themes

package/template/.claude/skills/theme-factory/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: theme-factory
+description: Use when a colour palette, dark mode, semantic token layer, or whole design system has to be created, extended, ported, or audited — including adding brand colours, checking contrast, or turning an existing stylesheet into a maintainable token system.
+---
+
+# Theme Factory
+
+A theme is **data**, not a vibe. It lives in one JSON file, gets validated by a
+script, and the stylesheet is emitted from it. Anything you cannot express in
+that file is not part of the theme — it is a one-off, and one-offs are how
+design systems rot.
+
+## When to use
+
+- Creating a palette or theme from scratch, or a second mode (dark, high-contrast, print)
+- Adding a colour, radius, or ramp to an existing system
+- Auditing a stylesheet: is the contrast real, do the ramps behave, is anything drifting
+- Porting a system between Tailwind / CSS variables / a design tool
+
+Not for: picking one accent colour for a throwaway snippet, or restyling a
+single component inside a system that already has tokens (use those tokens).
+
+## The three layers
+
+Every theme has exactly these, and they only ever reference downward:
+
+| Layer | What it is | Example | Who may use it |
+|---|---|---|---|
+| **Ramps** | Raw brand scales, 50→900 | `brand-blue-500` | The semantic layer only |
+| **Semantic** | Named roles, per mode | `primary`, `muted-foreground`, `border` | Components |
+| **Components** | Utilities and variants | `bg-primary text-primary-foreground` | Pages |
+
+**A component that names a ramp step or a raw hex has skipped a layer.** That is
+the single most common failure — it is invisible in light mode and breaks the
+moment a second mode exists. Every colour a component touches must be a semantic
+token, and every semantic token must exist in every mode.
+
+## Pipeline
+
+```bash
+# 1. Write or edit <name>.theme.json  (schema: references/schema.md)
+# 2. Validate — contrast, ramp monotonicity, mode parity, categorical separation
+node scripts/theme.mjs validate <name>.theme.json
+
+# 3. Read the actual numbers when you changed a colour
+node scripts/theme.mjs contrast <name>.theme.json
+
+# 4. Emit the stylesheet
+node scripts/theme.mjs emit <name>.theme.json --out globals-theme.css
+```
+
+The emitted CSS is a build product. **Never hand-edit it** — change the JSON and
+re-emit, otherwise the JSON stops being true and every later audit lies.
+
+Validation is not advisory. `validate` exits non-zero on failures; a theme that
+fails is not finished, and "it looks fine on my screen" is not a counter-argument
+to a 3.1:1 measurement.
+
+## Deriving a theme from an existing app
+
+When a codebase already has a stylesheet, extract rather than invent:
+
+1. Read the real token declarations (`@theme`, `:root`, `.dark`).
+2. Transcribe them into the JSON verbatim — same hex values, same references.
+3. Emit and diff against the original. **The token set must come out identical.**
+   A diff means you guessed somewhere; fix the JSON, not the diff.
+4. Only then propose changes, as edits to the JSON.
+
+Then measure what the code actually does, and record it in the JSON's `type`,
+`space`, and `elevation` sections: count utility usage across the source, and
+write down the winners as the conventions. A scale nobody uses is fiction; the
+frequencies are the design system whether or not anyone documented it.
+
+## Choosing colours for a new theme
+
+- **Build ramps, not colours.** One accent hex gives you nothing to hover, press, or disable with. Nine steps do.
+- **Ramps must darken monotonically.** The validator checks this; a lightness reversal mid-ramp makes hover states move the wrong direction.
+- **The dark mode is not an inversion.** Saturated brand colours read heavier on dark surfaces — a token that carries text usually needs a lighter step (e.g. `500` → `300`), while surfaces need more separation than pure inversion gives. Set them per mode; only tokens verified in both may be inherited.
+- **Categorical hues encode meaning.** If a colour identifies a *kind* of thing, it means the same thing everywhere and must clear 3:1 against every surface it lands on, in every mode, and stay separable from its neighbours. The validator checks all three.
+- **Pick a radius and mean it.** One `--radius` that the named steps all resolve to beats six steps drifting apart. Reserve larger radii for genuinely large surfaces and `full` for things that are actually round.
+
+## Common mistakes
+
+| Mistake | Why it hurts |
+|---|---|
+| Hand-editing the emitted CSS | JSON and CSS diverge silently; every later audit is wrong |
+| A token defined in light but not dark | Inherits a hex tuned for a white surface; usually unreadable |
+| Component uses `brand-blue-500` directly | Cannot be re-themed, ignores dark mode |
+| Adding a colour "just for this one badge" | This is how a 3-colour system becomes a 40-colour system |
+| Trusting the eye over the validator | 4.4:1 and 4.6:1 look identical and only one is legal |
+
+## Reference
+
+- `references/schema.md` — the theme JSON shape, field by field
+- `scripts/theme.mjs` — validator and emitter (Node, no dependencies)

package/template/.claude/skills/theme-factory/references/schema.md

@@ -0,0 +1,104 @@
+# Theme JSON schema
+
+One file per theme, named `<name>.theme.json`. Every field below is read by
+`scripts/theme.mjs`; anything else you add is documentation and is ignored by
+the tooling.
+
+```jsonc
+{
+  "name": "nexst",                   // required — used in output and messages
+  "source": "path/to/globals.css",   // where this was extracted from, if it was
+  "extractedOn": "2026-08-07",
+
+  "font": {                          // roles → faces. One face for every role is
+    "sans": {                        // a legitimate choice; state it explicitly.
+      "family": "Lexend",
+      "loader": "next/font/google",
+      "variable": "--font-lexend",
+      "role": "everything — display, body, UI, data",
+      "weightsLoaded": ["400", "500", "600", "700"],
+      "weightsUsed":   ["400", "500", "600", "700"]   // divergence = wasted bytes
+    }
+  },
+
+  "ramps": {                         // required — raw scales, hex only
+    "brand-blue": { "50": "#eef3ff", "…": "…", "900": "#1c2f79" }
+  },
+  "rampNotes": {                     // optional — emitted as a CSS comment
+    "brand-blue": "Cool, slightly cyan-leaning vivid blue"
+  },
+
+  "semantic": {                      // required — the first mode is the base,
+    "light": {                       // every other mode is a `.mode { }` override
+      "background": "#fbfcfe",
+      "primary": "brand-blue-500",   // ramp reference → emitted as var(--color-…)
+      "primary-foreground": "#ffffff"
+    },
+    "dark": { "background": "#0d1017", "…": "…" }
+  },
+  "notes": {                         // optional — emitted above that token
+    "destructive-solid": "Always paired with white text."
+  },
+  "verifiedInherits": ["kind-carddeck"],  // literals a later mode may inherit
+                                          // because they were checked there
+
+  "radius": {                        // required — emitted verbatim as --<key>
+    "radius": "0.5rem",
+    "radius-sm": "calc(var(--radius) - 4px)",
+    "radius-lg": "var(--radius)"
+  },
+
+  "type": {                          // required — documentation, not emitted
+    "scale":   [{ "token": "text-sm", "size": "0.875rem", "role": "…", "share": "252 uses" }],
+    "weights": [{ "token": "font-medium", "value": 500, "role": "…", "share": "188 uses" }]
+  },
+  "space": {                         // required — documentation, not emitted
+    "unit": "0.25rem",
+    "gaps": [{ "token": "gap-2", "role": "default — items inside one control" }],
+    "padding": [{ "token": "p-4", "role": "card padding" }],
+    "controlHeights": { "sm": "h-9", "default": "h-11" }
+  },
+  "elevation": [{ "token": "shadow-sm", "role": "buttons and cards — the default" }],
+  "breakpoints": { "strategy": "mobile-first", "usage": { "sm": 183, "md": 62 } }
+}
+```
+
+## Value resolution
+
+A semantic value is either a literal `#rrggbb`, a ramp reference
+(`<ramp-name>-<step>`), or another semantic token in the same mode. References
+resolve recursively and are emitted as `var(--color-…)`, so the CSS keeps the
+indirection the JSON describes. Circular references are a validation failure.
+
+## What `validate` enforces
+
+| Check | Level | Rule |
+|---|---|---|
+| Required top-level fields | fail | `name`, `ramps`, `semantic`, `radius`, `type`, `space`, `font` |
+| Ramp values are hex | fail | No references inside a ramp |
+| Ramp monotonicity | warn | Each step must be darker than the last |
+| Mode parity | warn | A later mode omitting a token inherits it; flagged when the inherited value is a literal hex, unless listed in `verifiedInherits` |
+| Text contrast | fail | 4.5:1 for the foreground/background pairs below |
+| Focus ring | fail | 3:1 against `background` |
+| Categorical hues (`kind-*`) | fail | 3:1 against `card` in every mode |
+| Categorical separation | warn | Adjacent hues must differ in lightness or channel |
+| Radius count | warn | More than 4 distinct radii |
+
+Checked text pairs: `foreground` on `background` and `card`;
+`muted-foreground` on `background` and `card`; `desc` on `card`;
+`primary-foreground` on `primary`; `secondary-foreground` on `secondary`;
+`accent-foreground` on `accent`; `destructive-foreground` on
+`destructive-solid`; `destructive` on `card`.
+
+Pairs whose tokens are absent are skipped, so a theme using different names
+still validates — but it also gets less checking. Prefer these names; if a
+theme genuinely needs others, add the pair to `PAIRS` in `scripts/theme.mjs`
+rather than leaving the contrast unmeasured.
+
+## Adding a mode
+
+Add a key under `semantic`. It becomes a `.<key> { }` block inside
+`@layer theme`, in declaration order, so `dark` stays `.dark`. List **every**
+token that needs a different value there; rely on inheritance only for ramp
+references and for literals you have actually measured on that mode's surfaces
+(then record them in `verifiedInherits` so the warning stays meaningful).