@x12i/kit-cli 1.0.0 → 1.1.0

package/README.md

@@ -9,41 +9,111 @@ npx @x12i/kit-cli doctor
 | Command | Status |
 | --- | --- |
 | `kit init` | Writes `kit.config.json` (`--theme`, `--density`, `--force`). |
-| `kit doctor [paths...]` | Finds hard-coded hex colors in CSS, TS, JS, HTML, Vue, Svelte and MDX files. Exits with 1 when it finds any, so it can gate CI. |
+| `kit doctor [paths...]` | Checks CSS, SCSS, TS, JS, HTML, Vue, Svelte and MDX files against the kit's conventions: tokens instead of hard-coded values, restrained motion, logical properties, visible focus. Exits with 1 on an error, or on any finding with `--strict`, so it can gate CI. |
+| `kit design` | Writes a `DESIGN.md` that tells a coding agent what the kit looks like (`--theme`, `--out`, `--force`). |
 | `kit theme [name]` | Lists the built-in themes and densities. Generating a theme is planned. |
 | `kit add <component...>` | Stub. The component registry is planned, so it exits with 1 and says so. |
 
 Exit codes: `0` success, `1` the command ran and found a problem, `2` bad usage
-(unknown command, option, theme or path).
+(unknown command, option, theme, rule or path).
 
 ## doctor
 
-`kit doctor` is a minimal scan. It finds `#rgb`, `#rgba`, `#rrggbb` and
-`#rrggbbaa` values. It skips `node_modules`, `dist`, `build`, `coverage` and
-other build folders, minified files and `.d.ts` files. It does not flag URL
-fragments, `href="#anchor"` links or HTML entities.
+```sh
+kit doctor src                # scan a folder
+kit doctor --strict           # a warning also fails the run
+kit doctor --json             # findings as JSON
+kit doctor --list-rules       # every rule, its default severity and what it checks
+```
+
+Each line is `file:line:col  match  message  (severity rule)`, and the run ends
+with a count of errors and warnings. A hard-coded hex color is an **error**, as it
+always was. Every other rule is a **warning** by default, so adding the new rules
+to an existing project does not turn a passing build red.
+
+| Group | Rules |
+| --- | --- |
+| Tokens | `hardcoded-color` (error), `hardcoded-color-function`, `hardcoded-font-size`, `hardcoded-font-family`, `hardcoded-spacing`, `hardcoded-radius` |
+| Motion | `hardcoded-duration`, `hardcoded-easing`, `bounce-easing`, `transition-all`, `layout-animation`, `missing-reduced-motion` |
+| Layout and focus | `physical-property`, `outline-none`, `important` |
+
+A value that uses a token is fine, and so is a mix such as
+`calc(var(--kit-space-2) * 3)`. The scan reads CSS declarations, `<style>` blocks
+and `style` attributes in markup, template literals, and string values in style
+objects. It skips `node_modules`, `dist`, `build`, `coverage` and other build
+folders, minified files and `.d.ts` files, and it does not flag URL fragments,
+`href="#anchor"` links or HTML entities.
+
+Some limits to know about:
+
+- `left` and `right` with a percentage (`left: 50%`) are not flagged. Centering and
+  anchoring use them with a physical `translate`, and the logical twin would break
+  in right to left.
+- `physical-property` is not reported inside a selector that names a side
+  (`.panel.left`, `.handle-right`, `[data-side="left"]`, `.text-left`), because
+  that code places things on that side on purpose.
+- `missing-reduced-motion` is one finding for the whole scan: it fires when
+  something animates and no scanned file handles `prefers-reduced-motion`.
+- It reads text. It does not resolve imports or compute styles, so a value built
+  at runtime is not seen.
 
-- Add `kit-ignore` to a line (in a comment) to keep a color on purpose, such as a
-  brand logo.
-- List paths to skip in `kit.config.json`:
+Configure it in `kit.config.json`. A rule is `"off"`, `"warn"` or `"error"`:
 
 ```json
 {
   "version": 1,
   "theme": "light",
   "density": "default",
-  "doctor": { "ignore": ["legacy", "src/vendor"] }
+  "doctor": {
+    "ignore": ["legacy", "src/vendor"],
+    "rules": {
+      "physical-property": "off",
+      "hardcoded-spacing": "error"
+    }
+  }
 }
 ```
 
-- `--json` prints the findings as JSON.
+- Add `kit-ignore` to a line (in a comment) to keep a value on purpose, such as a
+  brand logo color.
+- `ignore` lists paths to skip, for example generated files.
+- `--json` prints an array of findings. Each has `file`, `line`, `column`,
+  `match`, `rule`, `severity` and `message`.
 
-Spacing, font sizes and `rgb()` or `hsl()` colors are not scanned yet.
+The text output has more on each line than it used to. Parse `--json`, not the
+text.
+
+## design
+
+`kit design` writes the kit's `DESIGN.md` into your project, so a coding agent
+that reads it builds with the kit's colors, type, spacing and motion instead of
+inventing its own. It follows the [DESIGN.md format](https://github.com/google-labs-code/design.md)
+and is generated from the same tokens as the CSS, so it cannot drift from them.
+
+```sh
+kit design                     # writes ./DESIGN.md, using the theme in kit.config.json
+kit design --theme dark
+kit design --out docs/DESIGN.md
+kit design --out -             # print instead of writing
+```
+
+It will not overwrite a file that exists unless you pass `--force`. The file ends
+by telling the agent to run `kit doctor` before it finishes, which is what catches
+the values an agent hard-codes anyway.
 
 ## API
 
 ```ts
-import { scanForHardcodedColors } from "@x12i/kit-cli";
+import { scanForHardcodedColors, scanProject, RULES } from "@x12i/kit-cli";
 
-const findings = await scanForHardcodedColors(process.cwd(), ["src"]);
+// The original scan: hex colors only.
+const colors = await scanForHardcodedColors(process.cwd(), ["src"]);
+
+// Every rule. Pass `rules` to change severities and `ignore` to skip paths.
+const findings = await scanProject(process.cwd(), ["src"], {
+  rules: { "physical-property": "off" },
+});
 ```
+
+The same text is available from code as `createDesignMd({ theme })` in
+`@x12i/tokens/design-md`.