@x12i/tokens 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,86 @@
-# Temporary Holding Version
-
-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.
+# @x12i/tokens
+
+Design tokens for the Unified UI Kit. One W3C DTCG JSON source, compiled by
+Style Dictionary into everything the kit needs.
+
+| Output | Path | Use |
+| --- | --- | --- |
+| 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 |
+
+Most apps want [`@x12i/themes`](../themes), which packages the CSS files with
+system-preference defaults. Use this package directly for the TypeScript
+constants or the Tailwind mapping.
+
+## Tiers
+
+- **Primitive** (`src/dtcg/primitive`): raw values such as `color.neutral.9` and
+  `space.3`. Color primitives are never referenced by components.
+- **Semantic** (`src/dtcg/semantic`): meaning by role, such as `color.bg.surface`
+  and `color.accent.default`. Themes (`themes/`) and densities (`density/`) each
+  define the same paths with different values.
+- **Component** (`src/dtcg/component`): per-component values, only when no
+  semantic token fits, such as `button.height.md`.
+
+## Usage
+
+```ts
+import { cssVar, themes } from "@x12i/tokens";
+
+cssVar("color.bg.surface"); // "var(--kit-color-bg-surface)"
+themes.dark.color.chart.categorical["1"]; // a hex string, for canvas code
+```
+
+Tailwind v4:
+
+```css
+@import "tailwindcss";
+@import "@x12i/themes/themes.css";
+@import "@x12i/tokens/tailwind.css";
+```
+
+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
+  `src/generated` (git-ignored) and are bundled by `pnpm build`.
+- `pnpm generate:ramps` rewrites `src/dtcg/primitive/color.json` from the ramp
+  recipes in `scripts/generate-ramps.mjs`. The committed JSON is the source of
+  truth afterwards.
+- `pnpm test` runs the contrast test, which computes the ratio of every semantic
+  text and background pair in every theme (4.5:1 for text, 3:1 for UI, and 7:1
+  and 4.5:1 for `hc`) and fails on a regression.
+
+## Status
+
+Color values are placeholders until the visual target is signed off. The
+categorical palette still needs a color-blindness check.