@designtools/manifest 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @designtools/manifest
+
+## 0.1.0
+
+### Minor Changes
+
+- First release. `designtools-manifest build` reads a React design system, and the brand around it, into committed JSON inside the system folder:
+  - `components.json`: props through react-docgen-typescript; variants from `tv()` or `cva()` configs, local or imported, or the props' literal unions when there is neither; `data-slot` parts; status and usage from JSDoc (`@status`, `@use`, `@avoid`, `@instead`, `@replaces`, `@role`, `@keyboard`); and `*.examples.tsx`: canonical, do and don't, each with its JSX.
+  - `tokens.json`: every custom property in the token stylesheets, with its light, dark and P3 values and the comment above it.
+  - `rules.json`, `patterns.json`, `taxonomy.json` and `assets.json`: rules from `*.rule.json` (with a JSON Schema), patterns from `*.pattern.tsx`, the system's names with their curated wrong forms, and the brand assets with how to use them.
+
+  `check` fails when the committed files are out of date. `diff <base>` classifies every change as breaking, additive, visual or docs. `agents` writes the pointer section of CLAUDE.md or AGENTS.md, `prose-check` warns about wrong and restated names without ever failing, and `provenance` prints the version and commit for generated pages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Made by Many Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @designtools/manifest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads a React design system, and the brand around it, into committed JSON: every component with its props, variants, parts, usage, status and examples; every token; the rules, brand and interface alike; the product's patterns; one vocabulary with its wrong forms; and the brand assets. Docs pages, checks and agents read those files instead of the source, so none of them has to parse TypeScript, and none of them drifts from it.
+
+```bash
+npx @designtools/manifest build         # writes src/ds/manifest/*.json
+npx @designtools/manifest check         # exits 1 if the committed files are out of date
+npx @designtools/manifest diff main     # classifies every change against main
+npx @designtools/manifest agents        # writes the pointer section of CLAUDE.md or AGENTS.md
+npx @designtools/manifest prose-check   # warns about wrong and restated names in prose; never fails
+npx @designtools/manifest provenance    # "Generated from acme-web@1.4.0 at 3f2a9c1", for generated pages
+```
+
+Deterministic: the same source gives the same bytes, with sorted keys, no timestamps and no absolute paths, so a diff of the files shows only real changes.
+
+## Setup
+
+Record the system folder and the token stylesheets once, in `designtools.json` at the project root:
+
+```json
+{
+  "manifest": {
+    "system": "src/ds",
+    "tokens": ["app/styles/tokens.css", "app/styles/scale.css"]
+  }
+}
+```
+
+The manifest is written inside the system folder (`src/ds/manifest/`), so it moves with the system if the system moves to its own package. Flags override the file: `--system`, `--tokens` (repeat it), `--tsconfig`, `--out`, `--root`.
+
+## What it reads
+
+**Components.** Every exported component in a `.tsx` file under the system folder. Fixtures, tests, stories and `.d.ts` files are skipped. Props come from [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript), run once over a single TypeScript program, so types resolve across files and through the project's path aliases. A component's own props are kept, and so are those of a Base UI primitive it wraps. Props inherited from the DOM, ARIA or React are left out, and recorded as what it `inherits` (`"span"`, `"@base-ui/react/select:Select.Root"`).
+
+**Variants.** Read from the `tv()` (tailwind-variants) or `cva()` call, not inferred from types, because the config is already data: axes, options, defaults, compound conditions, and a `tv()` config's named parts. The config can be in the component's file or imported from another project file. A component with no config falls back to its own props whose types are unions of string literals.
+
+**Slots.** Every literal `data-slot` the component renders, including those rendered by private helpers in the same file.
+
+**Examples.** A co-located `<name>.examples.tsx`. `canonical` is the one to copy; `do…` and `dont…` exports pair up in order; anything else is a further example. Each records its JSDoc (the why) and the JSX it returns, as written, so docs can show the code and agents can copy it. The manifest never runs them. There is no register of states: loading, empty and error stay with each screen.
+
+**JSDoc.** Optional, and nothing is required. A component's JSDoc, or failing that its variant config's, is its description. These tags are read:
+
+| Tag | Becomes |
+| --- | --- |
+| `@name` | The display name, when it should differ from the export |
+| `@description` | Added to the description |
+| `@category` | The docs navigation group |
+| `@example` | A JSX snippet; repeat for several |
+| `@see` | A link or a related component; repeat for several |
+| `@deprecated` | The component, or a prop, is deprecated, with the reason |
+| `@primitive` | The primitive it wraps |
+| `@aria` | The ARIA pattern it follows |
+| `@status` | `stable`, `emerging` or `deprecated`, then an optional note |
+| `@use` | When to reach for it |
+| `@avoid` | When not to |
+| `@instead` | What to use instead, comma-separated |
+| `@replaces` | Raw elements it stands in for (`button`), which the adherence report counts |
+| `@role`, `@keyboard` | What assistive technology meets, and the keys it answers |
+| `@nodocgen` | Leaves the component out |
+
+Any other tag is a warning, with a suggestion when it is close to one of these.
+
+**Tokens.** Every custom property in the listed stylesheets: the colour tiers `@designtools/tokens` generates and the scale you author beside them. Each token records its value in every context it is declared in: `default` (`@theme`, `:root`), `light`, `dark`, `p3:` for the wide-gamut layer, and any other selector as written. A `prefers-color-scheme` fallback never overrides an explicit dark block. The comment above a declaration, or above the run of declarations it starts, becomes its description. Tiers follow Tailwind's namespaces (`--text-*`, `--radius-*`, …); semantic colours like `--primary` are recognised by their values.
+
+**Rules.** One `<id>.rule.json` per rule in `<system>/rules`, brand and interface in the same format: title, statement, rationale, threshold, what it applies to, exceptions, the tokens it rests on, whether it is `confirmed` or still an `assumption`, and the check that proves it. [`schemas/rule.schema.json`](schemas/rule.schema.json) validates them in an editor.
+
+**Patterns.** Any `<id>.pattern.tsx` in the system folder. The file's JSDoc names and describes it (`@name`, `@status`), its imports say which components it composes, and each named export is a composition, recorded like an example.
+
+**Taxonomy.** The canonical names come from everything else: components, variant axes and their meaningful options, semantic colours, patterns and rules. `<system>/taxonomy.json` adds the wrong forms (`{ "name": "destructive", "wrong": ["error", "danger"] }`) and product terms the code never names (`{ "name": "sign in", "kind": "product", "wrong": ["log in"] }`).
+
+**Brand assets.** Every image in `<system>/brand`, with an `assets.json` there saying how to use each: kind, usage, minimum size, clear space, the surfaces it may sit on, alt text. SVG and PNG sizes are read from the files. A file the index does not mention is listed anyway, with a warning.
+
+## The files
+
+`components.json`, abridged:
+
+```json
+{
+  "generator": "@designtools/manifest@0.1.0",
+  "schema": "designtools.manifest/1",
+  "system": "src/ds",
+  "components": [
+    {
+      "name": "Badge",
+      "export": "Badge",
+      "source": "src/ds/badge/badge.tsx",
+      "description": "A pill: soft tinted background, strong text of the same hue.",
+      "inherits": ["span"],
+      "props": {
+        "intent": { "type": "\"default\" | \"neutral\" | \"success\"", "values": ["default", "neutral", "success"], "required": false }
+      },
+      "variants": {
+        "from": "tv",
+        "config": "badge",
+        "axes": [{ "name": "intent", "default": "neutral", "options": [{ "name": "default" }, { "name": "neutral" }, { "name": "success" }] }]
+      },
+      "slots": ["badge"],
+      "status": "stable",
+      "usage": { "use": "A short status beside the thing it describes.", "avoid": "Anything people can press.", "instead": ["Button"] },
+      "examples": {
+        "source": "src/ds/badge/badge.examples.tsx",
+        "canonical": { "name": "canonical", "code": "<Badge intent=\"success\">Paid</Badge>" },
+        "do": [{ "name": "doShortLabel", "description": "One or two words, in sentence case." }],
+        "dont": [{ "name": "dontClickable", "description": "A badge is not a button." }],
+        "other": []
+      }
+    }
+  ]
+}
+```
+
+`tokens.json`, abridged:
+
+```json
+{
+  "generator": "@designtools/manifest@0.1.0",
+  "schema": "designtools.manifest/1",
+  "sources": ["app/styles/tokens.css", "app/styles/scale.css"],
+  "tokens": [
+    { "name": "--primary", "tier": "color", "values": { "light": "var(--color-primary-700)", "dark": "var(--color-primary-800)" }, "source": "app/styles/tokens.css" },
+    { "name": "--radius-md", "tier": "radius", "values": { "default": "0.375rem" }, "description": "corners, scaled to the element", "source": "app/styles/scale.css" }
+  ]
+}
+```
+
+Beside them sit `rules.json`, `patterns.json`, `taxonomy.json` and `assets.json`, under the same rules. The full schema is in [`src/types.ts`](src/types.ts), which has no imports so it can be copied: `@designtools/blocks` carries an identical copy.
+
+## Commands
+
+| Command | Exit code |
+| --- | --- |
+| `build` | 0, or 2 on a usage error |
+| `check` | 0 when both files match the source, 1 when either is missing or out of date. A version change is reported as such |
+| `diff [base]` | 0, or 1 with `--fail-on <class>` when a change of that class is found. `base` defaults to `main` |
+| `agents` | 0; with `--check`, 1 when the section is out of date |
+| `prose-check [file…]` | Always 0. Prose is for people to fix, never a reason to fail a build |
+| `provenance` | 0 |
+
+`diff` builds the manifest from the current source and compares it with the files committed at `base`. Every change is classified:
+
+| Class | Examples |
+| --- | --- |
+| breaking | A component, prop, variant option, token or `data-slot` removed; a prop made required; a new required prop; a prop type changed |
+| additive | A new component, optional prop, variant option, token, slot or state |
+| visual | A token value or a default variant changed |
+| docs | A description, status, usage, example, rule, pattern, term or asset changed |
+
+Components are matched by their path inside the system folder, so moving the whole system is not a change. The report is markdown, ready to post on a pull request; `--json` prints the changes as data.
+
+## For agents
+
+`agents` writes a section of `CLAUDE.md` (or `AGENTS.md`) between markers, and leaves the rest of the file alone. It points agents at each manifest file and the docs, and lists nothing: a list of components or tokens written into prose is a second copy that drifts.
+
+`prose-check` reads `CLAUDE.md`, `AGENTS.md`, `.claude/`, `docs/` and the system folder's markdown, and warns about a component tag the system does not have (`<Modal>`), a wrong form from the taxonomy (`Dropdown` for `Select`, "log in" for "sign in"), and a paragraph or list that restates several components or tokens. The generated section is skipped.
+
+`provenance` prints the project's version and the commit it was built at (`VERCEL_GIT_COMMIT_SHA` or `GITHUB_SHA` when set, else git), for the header of a generated docs page. A generated page never carries a review date.
+
+## Programmatic use
+
+```ts
+import { buildManifest, diffManifests, loadConfig } from "@designtools/manifest";
+
+const built = buildManifest(loadConfig({ root: "." }));
+built.components.components; // ComponentEntry[]
+built.files; // { "src/ds/manifest/components.json": "…" }
+```
+
+## Licence
+
+[MIT](LICENSE), © Made by Many Ltd.