@oneli8/tokens 1.0.0-beta.2 → 1.0.0-beta.3

package/README.md

@@ -1,94 +1,100 @@
 # @oneli8/tokens
 
-The canonical machine-readable source for Oneli8. Authored DTCG-compatible
-files live in `src/`; everything under `build/` is generated.
-
-## Build
+OneLi8 Design System — design tokens compiled from Figma.
 
 ```sh
-npm run build
-npm test
+npm install @oneli8/tokens
 ```
 
-When building a distributed token package without the development repository,
-use `node scripts/build.mjs --standalone` (or `node scripts/test.mjs --standalone`).
-This skips only external contract-file existence checks. Token references,
-schema-related checks and generated values are unchanged. The historical status
-registry is not proof that those components are included in a scoped distribution.
+```js
+import '@oneli8/tokens/css';        // :root custom properties + .ol8-type-* classes
+import { tokens } from '@oneli8/tokens';  // flat { 'color-text-primary': '#151817', ... }
+```
 
-## Delivery adapters
+Every value is generated from `src/tokens.json`, which is verified against the
+Figma file rather than hand-maintained. Do not edit `dist/` — edit the source and
+rebuild.
 
-- CSS: `@oneli8/tokens/css`
-- TypeScript/JavaScript: `@oneli8/tokens`
-- Tailwind CSS v3 preset: `@oneli8/tokens/tailwind`
-- Tailwind CSS v4 theme bridge: `@oneli8/tokens/tailwind.css`
-- Figma importer data: `@oneli8/tokens/figma`
-- Component maturity registry: `@oneli8/tokens/status`
+## What the vocabulary contains
 
-Tailwind is an adapter. It never becomes the source of Oneli8 values.
-Its spacing keys preserve the familiar 3px-indexed utilities: `1 = 3px`,
-`2 = 6px`, `4 = 12px`, `8 = 24px`, through `36 = 108px`.
-Semantic colors are exposed as utilities such as
-`bg-ol8-background-canvas`, `text-ol8-text-primary`, and
-`bg-ol8-action-primary-default`. Product interfaces should not assign
-meaning with raw Candidate 03 palette steps.
+99 colour primitives across 9 ramps, 68 semantic colour roles, 45 Gem material
+roles, 27 control-material roles, a 3px-atomic dimension scale, 9 radii, 9
+composite typography roles and 5 elevations.
 
-## Color modes
+Two rules matter when consuming it:
 
-Color Scheme and Primary Family are independent attributes. They can be
-combined without selecting a prebuilt Cartesian-product theme:
+- **Use semantic roles, not primitives.** `color-blue-600` is a swatch;
+  `color-actionprimary-default` is a decision. Primitives are hidden from Figma
+  pickers for the same reason.
+- **Use the `.ol8-type-<role>` class, not individual font variables.** Typography
+  is composite in Figma — a role bundles family, size, line height, weight and
+  tracking — and the class applies all of them together.
 
-```html
-<main data-ol8-color-scheme="dark" data-ol8-primary="orange">
-  ...
-</main>
+## Entry points
+
+| Import | What it gives you |
+|---|---|
+| `@oneli8/tokens` | flat `{ name: value }` map, with a literal-union key type |
+| `@oneli8/tokens/css` | the custom properties and `.ol8-type-*` classes |
+| `@oneli8/tokens/tailwind` | Tailwind v3 preset |
+| `@oneli8/tokens/tailwind.css` | Tailwind v4 `@theme` bridge |
+| `@oneli8/tokens/figma` | round-trip payload: collections, theme modes, type and elevation styles |
+| `@oneli8/tokens/status` | component maturity records |
+| `@oneli8/tokens/source` | the editable `tokens.json` |
+
+```js
+// tailwind.config.js (v3)
+import ol8 from '@oneli8/tokens/tailwind';
+export default { presets: [ol8], content: ['./src/**/*'] };
 ```
 
-- `data-ol8-color-scheme="light|dark"`
-- `data-ol8-primary="blue|orange|green"`
-- `data-ol8-type-mode="compact|medium|expanded"`
+```css
+/* Tailwind v4 */
+@import "@oneli8/tokens/css";
+@import "@oneli8/tokens/tailwind.css";
+```
 
-The CSS keeps Semantic color references live through custom-property aliases,
-so changing the Primary family updates its Default, Hover, Pressed, content,
-link, and qualified focus roles together.
+Both adapters emit `var(--ol8-*)` references rather than resolved values, so
+Tailwind classes follow the theme attributes exactly like the raw custom
+properties do. `bg-ol8-actionprimary-default` repaints when you switch the
+primary family; it does not bake a blue at build time.
 
-## Elevation and Gem material
+The JS map is the exception: it holds resolved literals, because code that reads
+it wants an actual colour, not a `var()` string.
 
-Five visual elevation roles and five independent stacking tiers are generated
-for CSS, Tailwind, TypeScript, and Figma. Tailwind examples include
-`shadow-ol8-raised`, `shadow-ol8-overlay`, and `z-ol8-modal`.
+## Naming
 
-Gem material colors preserve their Candidate 03 references and governed alpha.
-They are optional environmental-material roles, not replacements for
-`Color / Surface`, feedback, selection, focus, or action semantics. Reduced
-Transparency resolves through each recipe's opaque equivalent.
+Hyphens separate hierarchy levels; compound words inside a level run together.
+So `--ol8-focus-ring-innerwidth`, not `inner-width` — and likewise
+`surfacedefault`, `disabledcontent`, `paddinginline`, `cutedge`,
+`opaqueequivalent`. This mirrors the Figma variable names exactly.
 
-### Tailwind CSS v3
+## Theming
 
-```js
-import oneli8 from "@oneli8/tokens/tailwind";
+Three independent axes, each an attribute. They compose — set two at once and you
+get both; there is no Cartesian product of pre-baked modes.
 
-export default {
-  presets: [oneli8],
-};
+```html
+<html data-ol8-color-scheme="dark" data-ol8-primary="orange">
 ```
 
-### Tailwind CSS v4
+| Attribute | Values | Effect |
+|---|---|---|
+| `data-ol8-color-scheme` | `dark` | Remaps 86 semantic roles onto dark primitives. Omit for light. |
+| `data-ol8-primary` | `blue` (default), `orange`, `green` | Repoints the `color-primary-*` ramp at another family. |
 
-```css
-@import "tailwindcss";
-@import "@oneli8/tokens/tailwind.css";
-@import "@oneli8/tokens/css";
-```
+Family swapping works because semantic roles are emitted as *references*
+(`--ol8-color-actionprimary-default: var(--ol8-color-primary-600)`), never as
+baked hex. Repoint the ramp and every role that reads it repaints. Anything you
+author yourself should follow the same rule: reference the semantic role, not a
+primitive, or your UI will not follow the theme.
+
+Not yet ported from the Figma theme source: the `typographyViewport` axis
+(`medium` / `expanded`), which needs `font.size.090`, `font.line.096` and a
+`font.tracking.*` scale this tree has never synced; dark overrides for the five
+`elevation-*` composites; and dark link-state and icon-button-surface roles,
+which have no token in this vocabulary yet.
+
+## Licence
 
-The current encoding contains approved Dimension, Spacing, Sizing, Shape,
-Border, Focus, Typography, Motion, Candidate 03 Color, Semantic Light/Dark
-color modes, Blue/Orange/Green Primary families, Elevation, stacking order,
-approved Gem material geometry and colors, plus 125 approved Component geometry
-recipes and ten evidence-backed maturity records. The Navigation slice adds
-shared recipes for Tabs, Segmented Control, and Tab Bar without creating
-component-private foundation scales.
-
-Thin agent adapters live in `../agent/`. A browser example that consumes the
-generated CSS, ESM tokens, and maturity registry without copying values lives
-in `../../examples/web-token-consumer/`.
+Apache-2.0. Created by Akshay Dhore. See `LICENSE` and `NOTICE`.