@x12i/tokens 1.0.0 → 1.1.0

package/README.md

@@ -8,6 +8,7 @@ Style Dictionary into everything the kit needs.
 | CSS custom properties, prefixed `--kit-` | `@x12i/tokens/css/*.css` | Runtime theming |
 | Tailwind v4 `@theme` mapping | `@x12i/tokens/tailwind.css` | Utility classes that read the same variables |
 | Typed TypeScript constants | `@x12i/tokens` | Charts and canvases that need raw values |
+| `DESIGN.md` text | `@x12i/tokens/design-md` | Telling a coding agent what the kit looks like |
 | Tokens Studio JSON | `@x12i/tokens/tokens-studio.json` | Syncing with Figma |
 | DTCG source | `@x12i/tokens/dtcg/*` | Your own tooling |
 
@@ -45,6 +46,29 @@ Tailwind v4:
 Utilities mirror token paths, for example `bg-bg-surface` and `text-text-secondary`.
 The mapping uses `@theme inline`, so switching `data-theme` needs no rebuild.
 
+## DESIGN.md
+
+A [DESIGN.md](https://github.com/google-labs-code/design.md) is the file a coding
+agent reads to learn a project's visual identity: colors, type, spacing, shapes,
+components and a few rules in prose. `createDesignMd` writes one for the kit from
+the tokens in this package, so it cannot drift from the CSS.
+
+```ts
+import { createDesignMd } from "@x12i/tokens/design-md";
+
+const markdown = createDesignMd({ theme: "dark" }); // "light" (default), "dark" or "hc"
+```
+
+Each theme gets its own file, with that theme's real color values. The prose names
+the kit's CSS variables, covers motion, and ends with do's and don'ts, including
+running `kit doctor` before finishing. `npx @x12i/kit-cli design` writes the file
+into a project.
+
+It lives in its own entry, so apps that only want the token constants do not load
+the generator (about 15 KB). The tests lint every theme's file with
+`@google/design.md` and fail on a broken reference or a contrast problem between
+a component's text and its background.
+
 ## Scripts
 
 - `pnpm build:tokens` compiles the DTCG source. The TypeScript constants land in