@reforma/project-tokens 0.0.1 → 0.0.2

package/README.md

@@ -1,12 +1,52 @@
 # @reforma/project-tokens
 
 Compile project DTCG JSON into CSS, Tailwind theme bindings, and mode metadata.
-The compiler runs locally on Node 24 or newer. It does not call a Reforma service.
+The compiler runs locally on Node 24 or newer.
+
+## Files
+
+The compiler reads a DTCG resolver and the documents that resolver references.
+It writes `tokens.css`, `tailwind.css`, and `modes.json` into the directory
+from `--out`. Without that flag, the directory is `.generated` beside the resolver.
+The JSON stays the source. Ignore the output directory.
+
+```text
+tokens/tokens.resolver.json       sets, modes, default
+tokens/base.json                  every value for the default context
+tokens/dark.json                  sparse overrides for one other context
+tokens/.generated/tokens.css      custom properties
+tokens/.generated/tailwind.css    Tailwind @theme bindings
+tokens/.generated/modes.json      context names, selectors, revision
+```
+
+The directory and the JSON filenames are yours. `$ref` inside the resolver
+decides which documents are read. `base.json` and `dark.json` above are only
+an example: one complete document, then a document that overrides existing
+paths for another context. A mode file does not declare types and does not
+add tokens that exist only in that mode.
+
+Pass `--entry` to point at the resolver and `--out` to choose the output
+directory. If you omit `--entry`, the CLI uses
+`.reforma/tokens/tokens.resolver.json`. If you omit `--out`, it writes
+`.generated` beside the resolver.
+
+`tokens.css` puts the default context on `:root` and each other context on a
+selector such as `html[data-theme="dark"]`. `tailwind.css` is an
+`@theme inline` block. It includes only names Tailwind already treats as theme
+keys, including `color`, `spacing`, `font`, `text`, `radius`, and `shadow`.
+Any other group stays a plain variable in `tokens.css`. `modes.json` records
+the default, each modifier's contexts, the selector for every permutation,
+the input revision, and hashes of the source files.
+
+This generated `tailwind.css` is not the project's Tailwind entry. The app
+imports its own Tailwind CSS, then these generated files. `check` writes
+nothing. `build`, `watch`, and `dev` replace the three files when the output
+changes, and leave the last good output in place when the JSON is invalid.
 
 ## CLI
 
-Install the package, then call the `reforma-tokens` binary from a script. The default
-entry is `.reforma/tokens/tokens.resolver.json`.
+Install the package, then call the `reforma-tokens` binary from a script.
+`--entry` selects the resolver. The default is `.reforma/tokens/tokens.resolver.json`.
 
 ```json
 {
@@ -29,20 +69,16 @@ command.
 | `dev -- command ...` | Build before starting the command. Watch sources. Forward signals and the exit status. |
 
 `--cwd directory` selects the workspace. `--entry path` selects its resolver.
+`--out directory` selects the output directory.
 Repeat `--context axis=value` to supply contexts, including axes without defaults.
 Every permutation is validated. The selected or default input supplies `:root`.
 Names are case-sensitive. Compilation stops at 1000 permutations.
 
-Ignore `.reforma/tokens/.generated/` in Git. A build writes `tokens.css`,
-`tailwind.css`, and `modes.json` there, and may leave staging and lock files
-while it runs. Import the generated CSS before application styles, and import
-`tailwind.css` through the project's Tailwind entry.
-
-A failed rebuild leaves the last successful output unchanged. Watch and dev print
-one JSON diagnostic per line on stderr and `{ "status": "stale", "revision" }`
-when input is invalid. A successful rebuild prints `{ "status": "ready", "revision" }`
-on stdout. The app keeps running after a bad edit. An invalid first build does
-not start the dev command.
+A build may also leave staging and lock files in the output directory while it runs.
+Watch and dev print one JSON diagnostic per line on stderr and
+`{ "status": "stale", "revision" }` when input is invalid. A successful rebuild
+prints `{ "status": "ready", "revision" }` on stdout. The app keeps running after
+a bad edit. An invalid first build does not start the dev command.
 
 ## API
 

package/dist/cli.js

@@ -111,11 +111,11 @@ async function main() {
     const separator = args.indexOf('--');
     const childCommand = separator < 0 ? [] : args.slice(separator + 1);
     const { values, positionals } = parseArgs({ args: separator < 0 ? args : args.slice(0, separator), allowPositionals: true, options: {
-            cwd: { type: 'string' }, entry: { type: 'string' }, context: { type: 'string', multiple: true }, help: { type: 'boolean' },
+            cwd: { type: 'string' }, entry: { type: 'string' }, out: { type: 'string' }, context: { type: 'string', multiple: true }, help: { type: 'boolean' },
         } });
     const [command] = positionals;
     if (values.help) {
-        process.stdout.write('reforma-tokens <build|check|watch|dev -- command...> [--cwd directory] [--entry resolver.json] [--context axis=value]\n');
+        process.stdout.write('reforma-tokens <build|check|watch|dev -- command...> [--cwd directory] [--entry resolver.json] [--out directory] [--context axis=value]\n');
         return;
     }
     if (!['build', 'check', 'watch', 'dev'].includes(command ?? '') || positionals.length !== 1)
@@ -129,7 +129,7 @@ async function main() {
             throw new Error('Expected --context axis=value.');
         input[context.slice(0, separator)] = context.slice(separator + 1);
     }
-    const options = { workspaceRoot: await realpath(resolve(values.cwd ?? process.cwd())), entry: values.entry, input };
+    const options = { workspaceRoot: await realpath(resolve(values.cwd ?? process.cwd())), entry: values.entry, out: values.out, input };
     if (command === 'watch' || command === 'dev')
         return watch(options, childCommand);
     const result = await (command === 'check' ? compileProjectTokens(options) : buildProjectTokens(options));

package/dist/compilation/compiler.d.ts

@@ -38,6 +38,8 @@ export interface TokenPermutation {
 export interface TokenCompilationOptions {
     workspaceRoot: string;
     entry?: string;
+    /** Directory for generated CSS and mode metadata. Defaults to `.generated` beside the resolver. */
+    out?: string;
     /** Required values for modifiers without a default. */
     input?: Record<string, string>;
     /** In-memory candidate files, keyed by workspace-relative path. Never persisted by compilation. */

package/dist/compilation/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/compilation/compiler.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEtG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mGAAmG;IACnG,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAUD,mFAAmF;AACnF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiStG"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/compilation/compiler.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEtG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mGAAmG;IACnG,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAUD,mFAAmF;AACnF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiStG"}

package/dist/generation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"AAKA,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAYtH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,0BAYnE;AAED,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoIxL;AAED,0FAA0F;AAC1F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEpG"}
+{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"AAKA,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAYtH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,0BAYnE;AAOD,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoIxL;AAED,0FAA0F;AAC1F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEpG"}

package/dist/generation.js

@@ -28,9 +28,14 @@ export async function readTokenDependency(root, path) {
         throw error;
     }
 }
+function generatedDirectory(root, options) {
+    if (options.out)
+        return resolve(root, options.out);
+    return resolve(root, dirname(options.entry ?? '.reforma/tokens/tokens.resolver.json'), '.generated');
+}
 export async function withTokenCompilationLock(options, work) {
     const root = await realpath(options.workspaceRoot);
-    const directory = resolve(root, dirname(options.entry ?? '.reforma/tokens/tokens.resolver.json'), '.generated');
+    const directory = generatedDirectory(root, options);
     // Check every existing ancestor before creating output or following a symlink.
     for (let path = directory; path !== root; path = dirname(path)) {
         const rel = relative(root, path);

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@reforma/project-tokens",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "description": "Portable DTCG 2025.10 compiler for project design tokens.",
     "type": "module",
     "license": "UNLICENSED",
     "author": "Reforma, Inc. <dev@reforma.ai>",
     "repository": {
         "type": "git",
-        "url": "https://github.com/reforma-dev/reforma",
+        "url": "https://github.com/reforma-ai/reforma",
         "directory": "packages/project-tokens"
     },
     "exports": {