tokens-to-css 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Osvaldo Morgan
+
+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

@@ -0,0 +1,191 @@
+# tokens-to-css
+
+Convert design-token JSON into a CSS custom-properties stylesheet.
+
+You hand it a token file — a path or a URL — and it writes a stylesheet of
+`:root` custom properties your app can link, with alias relationships kept as
+`var(--…)` rather than flattened. It is not a multi-platform token pipeline and
+does not try to become one.
+
+Zero runtime dependencies.
+
+```bash
+npm i -D tokens-to-css
+```
+
+## Use it
+
+```js
+import { generateCss } from 'tokens-to-css'
+
+await generateCss('design/tokens.json')
+// wrote assets/css/tokens.css
+```
+
+That is the whole integration. No config file, no CLI: you own the invocation
+site, so it goes wherever your build already lives — an npm script, a build
+step, a bootstrap file.
+
+Given this:
+
+```json
+{
+  "color": {
+    "brand": { "$value": "#5A4FCF", "$type": "color" },
+    "ink":   { "$value": "#191627", "$type": "color" },
+    "text":  { "$value": "{color.ink}" }
+  },
+  "space": {
+    "md": { "$value": { "value": 16, "unit": "px" }, "$type": "dimension" }
+  }
+}
+```
+
+you get this:
+
+```css
+:root {
+  --color-brand: #5A4FCF;
+  --color-ink: #191627;
+  --color-text: var(--color-ink);
+  --space-md: 16px;
+}
+```
+
+Look at `--color-text`. Your token file said *text is ink*, and so does the
+stylesheet — the relationship survived instead of being flattened to `#191627`.
+Change the primitive and everything pointing at it moves, which is the reason to
+keep tokens in a hierarchy at all.
+
+A URL works wherever a path does:
+
+```js
+await generateCss('https://tokens.example.com/design.json')
+```
+
+## What it reads
+
+Three shapes, checked in this order. The first that matches decides how the
+document is read.
+
+| | |
+| --- | --- |
+| **Tokens Studio** | Exports with `$themes` / `$metadata`. The token set wrapper is dropped from the name, so you get `--color-brand`, not `--global-color-brand`. |
+| **DTCG** | `$value`, `$type`, aliases — including the object notation the current spec uses for colours and dimensions. |
+| **Style Dictionary legacy** | `value` / `type` without the dollar. Converts to a byte-identical stylesheet. |
+
+Hierarchy is not a separate concern: three-tier, CTI, EightShapes-like or any
+other nesting all flatten through the same naming rule.
+
+Full detail, including everything it refuses, is in
+[docs/formats.md](docs/formats.md).
+
+## When it fails
+
+It either writes a correct stylesheet or writes nothing at all. There is no
+partial output, and a failed run never touches the stylesheet already there.
+
+```
+TokenCssError [ALIAS_DANGLING]
+1 reference points nowhere:
+  "color.text" references "color.inkk", which does not exist
+```
+
+Every failure carries a stable code you can branch on:
+
+```js
+try {
+  await generateCss('design/tokens.json')
+} catch (error) {
+  error.code        // e.g. 'ALIAS_DANGLING'
+  error.source      // the Token Source, as you passed it
+  error.tokenPaths  // the offending tokens
+}
+```
+
+The eight codes are listed in [docs/failures.md](docs/failures.md), generated
+from the source that defines them.
+
+## Options
+
+All optional.
+
+```js
+await generateCss('design/tokens.json', {
+  outDir: 'public/styles',       // default: assets/css
+  fileName: 'design-tokens.css', // default: tokens.css
+  baseDir: process.cwd(),        // what relative paths resolve against
+  http: {                        // only used when the source is a URL
+    allowInsecure: false,        // https only, unless you say otherwise
+    timeoutMs: 10_000,
+    maxBytes: 10_000_000,
+    maxRedirects: 3,
+  },
+})
+```
+
+A remote source is fetched under a guard: `https` by default, one deadline
+across the whole exchange, a size cap enforced while the body streams, redirects
+re-validated at every hop, and loopback, private, link-local and cloud-metadata
+addresses refused — including when the URL names one literally.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | Five steps from install to a stylesheet, including breaking it on purpose |
+| [What it accepts](docs/formats.md) | The three shapes, the order they are checked, and everything refused |
+| [The naming rule](docs/naming.md) | How `color.brand` becomes `--color-brand`, and why that is a promise |
+| [Failure codes](docs/failures.md) | The eight codes and what each one means |
+
+## What it will not do
+
+Some of these are on purpose and stay that way; the rest are recorded as
+deferred, not forgotten.
+
+- **Invent units.** A token whose value is `16` emits `16`, never `16px`,
+  whatever its `$type` says.
+- **Flatten references.** `var(--…)` all the way down.
+- **Evaluate expressions.** `{spacing.md} * 2` is refused rather than computed.
+  There is no evaluator in this package. `calc()` and `clamp()` are valid CSS
+  and pass through untouched.
+- **Convert composite tokens.** Typography, shadow, border, gradient and
+  transition are refused: a typography token is five CSS properties, and
+  accepting it would change what "one token, one custom property" means.
+  Deferred to a version after this one.
+- **Pick a winner on a collision.** Two token paths that produce the same
+  custom-property name fail the conversion rather than one quietly overwriting
+  the other.
+
+## Requirements
+
+Node **22.12 or newer**. Development and CI target Node 24; CI also runs 22 and
+26. ESM only, with TypeScript types included.
+
+Conversion writes to disk, so it needs a writable filesystem. There is no
+browser build.
+
+## Contributing
+
+```bash
+npm install
+npm run check     # lint + typecheck + tests
+npm run build
+```
+
+`npm run lint` is not a style linter. It enforces the architecture: the build
+fails if a pure stage (`src/dialects/`, `src/validate/`, `src/emit/`,
+`src/model/`, `src/pipeline.ts`) reaches for the filesystem or the network, and
+it checks that the generated fixtures and documentation still match the code
+they came from.
+
+The [fixtures](fixtures/README.md) are the specification — nine files that must
+convert byte for byte, seventeen that must fail with a named code. Where the
+documentation and the fixtures disagree, the fixtures are right.
+
+The requirements, the architecture and the work breakdown live under
+[`_bmad-output/planning-artifacts/`](_bmad-output/planning-artifacts/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+//#region src/options.d.ts
+/**
+ * What a caller passes in and gets back.
+ *
+ * These live apart from the public surface so the orchestrator can read them
+ * without importing the entry point that calls it — a cycle between the two
+ * would work in ESM and still be the wrong shape (AD-1).
+ */
+/** How a remote Token Source is fetched. Ignored when the source is a local path. */
+interface HttpOptions {
+  /** Allow `http:` URLs. Off by default — only `https:` is fetched. */
+  readonly allowInsecure?: boolean;
+  /** Total budget for the request, in milliseconds. */
+  readonly timeoutMs?: number;
+  /** Largest response body accepted, in bytes. */
+  readonly maxBytes?: number;
+  /** How many redirects to follow before giving up. */
+  readonly maxRedirects?: number;
+}
+/** Everything a caller can adjust about a conversion. */
+interface GenerateCssOptions {
+  /** Directory the stylesheet is written to. Defaults to `assets/css`. */
+  readonly outDir?: string;
+  /** Filename inside that directory. Defaults to `tokens.css`. */
+  readonly fileName?: string;
+  /** Base for resolving relative paths. Defaults to the current working directory. */
+  readonly baseDir?: string;
+  /** Network policy for a URL Token Source. */
+  readonly http?: HttpOptions;
+}
+/** What a successful conversion reports back. Deliberately carries no CSS. */
+interface GenerateCssResult {
+  /** Absolute path of the stylesheet that was written. */
+  readonly outputPath: string;
+  /** How many custom properties it declares. */
+  readonly tokenCount: number;
+}
+/** The defaults a conversion uses when the caller says nothing. */
+declare const DEFAULTS: Readonly<{
+  outDir: "assets/css";
+  fileName: "tokens.css";
+  http: Readonly<{
+    allowInsecure: false;
+    timeoutMs: 10000;
+    maxBytes: 10000000;
+    maxRedirects: 3;
+  }>;
+}>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * The failure contract — public surface, frozen by semver (AD-4).
+ *
+ * Every failure in this library is a `TokenCssError` carrying one of the codes
+ * below. Callers branch on `code`; they never match on message text, so message
+ * wording stays free to improve. Renaming or merging a code is a major version.
+ */
+/**
+ * The complete set of ways a conversion can fail.
+ *
+ * One code per failure class in the PRD. Adding a code is a minor version;
+ * renaming, merging, or removing one is a major version.
+ */
+declare const FailureCode: Readonly<{
+  /** The path or URL could not be read: missing, denied, unreachable, timed out, oversized, or refused by network policy. */
+  readonly SOURCE_UNREADABLE: 'SOURCE_UNREADABLE';
+  /** The source was read but its content is not valid JSON. */
+  readonly SOURCE_INVALID_JSON: 'SOURCE_INVALID_JSON';
+  /** The document is not a shape this version accepts. */
+  readonly FORMAT_NOT_ALLOWED: 'FORMAT_NOT_ALLOWED';
+  /** Aliases reference each other in a loop. */
+  readonly ALIAS_CYCLE: 'ALIAS_CYCLE';
+  /** An alias points at a token that does not exist. */
+  readonly ALIAS_DANGLING: 'ALIAS_DANGLING';
+  /** A value is an object, array, boolean, or null rather than a scalar. */
+  readonly COMPOSITE_VALUE: 'COMPOSITE_VALUE';
+  /** Two or more tokens would emit the same custom-property name. */
+  readonly NAME_COLLISION: 'NAME_COLLISION';
+  /** The stylesheet could not be written. */
+  readonly OUTPUT_WRITE_FAILED: 'OUTPUT_WRITE_FAILED';
+}>;
+/** One of the eight failure codes. */
+type FailureCode = (typeof FailureCode)[keyof typeof FailureCode];
+/** What a `TokenCssError` is constructed from. */
+interface TokenCssErrorInit {
+  /** The failure class. */
+  readonly code: FailureCode;
+  /** The Token Source the conversion was working on, as the caller supplied it. */
+  readonly source: string;
+  /** Dotted paths of the offending tokens, for token-scoped failures. */
+  readonly tokenPaths?: readonly string[];
+  /** The underlying error, when this one wraps something lower-level. */
+  readonly cause?: unknown;
+}
+/**
+ * The only error this library throws.
+ *
+ * There are no subclasses: the `code` is what callers branch on, and one type
+ * means a caller never has to ask which error shape it caught.
+ */
+declare class TokenCssError extends Error {
+  readonly name = "TokenCssError";
+  /** The failure class. Stable across minor versions. */
+  readonly code: FailureCode;
+  /** The Token Source being converted when this failed. */
+  readonly source: string;
+  /** Offending token paths — empty for failures that are not token-scoped. */
+  readonly tokenPaths: readonly string[];
+  constructor(message: string, init: TokenCssErrorInit);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Convert a design-token document into a CSS custom-properties stylesheet.
+ *
+ * Reads the Token Source, validates it completely, and writes the stylesheet —
+ * or throws a `TokenCssError` and writes nothing at all. There is no partial
+ * success: a previous stylesheet at the target path is left untouched whenever
+ * the conversion fails.
+ *
+ * @param source Path to a single local file, or a URL.
+ * @param options Output location and network policy.
+ * @returns Where the stylesheet was written, and how many properties it holds.
+ * @throws {TokenCssError} With a `code` naming the failure class.
+ */
+declare function generateCss(source: string | URL, options?: GenerateCssOptions): Promise<GenerateCssResult>;
+//#endregion
+export { DEFAULTS, FailureCode, type GenerateCssOptions, type GenerateCssResult, type HttpOptions, TokenCssError, type TokenCssErrorInit, generateCss };