@x12i/kit-cli 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+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,119 @@
-# Temporary Holding Version
+# @x12i/kit-cli
 
-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.
+Command line for the Unified UI Kit. The binary is called `kit`.
+
+```sh
+npx @x12i/kit-cli doctor
+```
+
+| Command | Status |
+| --- | --- |
+| `kit init` | Writes `kit.config.json` (`--theme`, `--density`, `--force`). |
+| `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, rule or path).
+
+## doctor
+
+```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.
+
+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"],
+    "rules": {
+      "physical-property": "off",
+      "hardcoded-spacing": "error"
+    }
+  }
+}
+```
+
+- 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`.
+
+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, scanProject, RULES } from "@x12i/kit-cli";
+
+// 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`.