dispersa 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Dispersa
 
-A TypeScript build system for processing [DTCG 2025.10](https://www.designtokens.org/) design tokens. Dispersa loads resolver documents, resolves references and modifiers, applies filters and transforms, then renders output to CSS, JSON, and JS/TS modules.
+A TypeScript build system for processing [DTCG 2025.10](https://www.designtokens.org/) design tokens. Dispersa loads resolver documents, resolves references and modifiers, applies filters and transforms, then renders output to CSS, JSON, JS/TS or custom modules.
 
 ## Features
 
@@ -17,71 +17,109 @@ A TypeScript build system for processing [DTCG 2025.10](https://www.designtokens
 
 **Composite types:** `shadow`, `typography`, `border`, `strokeStyle`, `transition`, `gradient`
 
-## Installation
+## Getting started
+
+### New project
 
 ```bash
-pnpm add dispersa
+pnpm create dispersa
 ```
 
-## Quick start
+The scaffold prompts for a project directory, lets you pick a template (programmatic or CLI-based), and optionally installs dependencies.
 
-Define a DTCG resolver document (`tokens.resolver.json`):
+### Add to an existing project
 
-```json
-{
-  "version": "2025.10",
-  "sets": {
-    "core": {
-      "sources": [{ "$ref": "./tokens/base.json" }, { "$ref": "./tokens/alias.json" }]
-    }
-  },
-  "modifiers": {
-    "theme": {
-      "default": "light",
-      "contexts": {
-        "light": [{ "$ref": "./tokens/themes/light.json" }],
-        "dark": [{ "$ref": "./tokens/themes/dark.json" }]
-      }
-    }
-  },
-  "resolutionOrder": [{ "$ref": "#/sets/core" }, { "$ref": "#/modifiers/theme" }]
-}
+```bash
+pnpm add dispersa
 ```
 
-Build tokens:
+## Quick start
+
+Define tokens inline and build CSS -- no files needed:
 
 ```typescript
-import { Dispersa, css, json } from 'dispersa'
+import type { ResolverDocument } from 'dispersa'
+import { Dispersa, css } from 'dispersa'
 import { colorToHex, nameKebabCase } from 'dispersa/transforms'
 
-const dispersa = new Dispersa({
-  resolver: './tokens.resolver.json',
-  buildPath: './dist',
-})
+const resolver: ResolverDocument = {
+  version: '2025.10',
+  sets: {
+    base: {
+      sources: [
+        {
+          color: {
+            brand: {
+              primary: {
+                $type: 'color',
+                $value: { colorSpace: 'srgb', components: [0, 0.4, 0.8] },
+              },
+            },
+            neutral: {
+              white: {
+                $type: 'color',
+                $value: { colorSpace: 'srgb', components: [1, 1, 1] },
+              },
+              black: {
+                $type: 'color',
+                $value: { colorSpace: 'srgb', components: [0, 0, 0] },
+              },
+            },
+          },
+          spacing: {
+            small: { $type: 'dimension', $value: { value: 8, unit: 'px' } },
+            medium: { $type: 'dimension', $value: { value: 16, unit: 'px' } },
+          },
+        },
+      ],
+    },
+  },
+  modifiers: {
+    theme: {
+      default: 'light',
+      contexts: {
+        light: [
+          {
+            semantic: {
+              background: { $type: 'color', $value: '{color.neutral.white}' },
+              text: { $type: 'color', $value: '{color.neutral.black}' },
+            },
+          },
+        ],
+        dark: [
+          {
+            semantic: {
+              background: { $type: 'color', $value: '{color.neutral.black}' },
+              text: { $type: 'color', $value: '{color.neutral.white}' },
+            },
+          },
+        ],
+      },
+    },
+  },
+  resolutionOrder: [{ $ref: '#/sets/base' }, { $ref: '#/modifiers/theme' }],
+}
+
+const dispersa = new Dispersa({ resolver })
 
 const result = await dispersa.build({
   outputs: [
     css({
       name: 'css',
-      file: 'tokens.css',
       preset: 'bundle',
       selector: ':root',
       transforms: [nameKebabCase(), colorToHex()],
     }),
-    json({
-      name: 'json',
-      file: 'tokens-{theme}.json',
-      preset: 'standalone',
-      structure: 'flat',
-    }),
   ],
 })
 
-if (result.success) {
-  console.log(`Generated ${result.outputs.length} file(s)`)
+for (const output of result.outputs) {
+  console.log(output.content)
 }
 ```
 
+> For file-based tokens, define JSON files and reference them with `$ref` in your resolver document. See the [`basic` example](./examples/basic/) for a complete setup.
+
 ## Output formats
 
 Dispersa ships four builder functions. Each returns an `OutputConfig` that can be passed to `build()`.
@@ -133,6 +171,12 @@ Renders JavaScript/TypeScript modules.
 | `transforms`     | `Transform[]`              | --             | Per-output transforms                        |
 | `filters`        | `Filter[]`                 | --             | Per-output filters                           |
 
+### Experimental: native platform outputs
+
+Dispersa also ships `ios()` and `android()` builders for Swift/SwiftUI and Kotlin/Jetpack Compose. These are **experimental** -- APIs and generated code may change.
+
+See the [multi-platform example](./examples/multi-platform/) for a complete setup.
+
 ## Output presets
 
 Presets control how modifier permutations are packaged into files.
@@ -630,10 +674,10 @@ All hooks support both sync and async functions.
 
 ## CLI
 
-Dispersa ships a CLI package (`dispersa-cli`) with a config-first workflow.
+Dispersa includes a CLI for a config-first workflow.
 
 ```bash
-pnpm add dispersa-cli
+pnpm add dispersa
 ```
 
 ```bash
@@ -645,7 +689,7 @@ The CLI auto-discovers config files named `dispersa.config.(ts|js|mts|mjs|cts|cj
 
 ```typescript
 // dispersa.config.ts
-import { defineConfig } from 'dispersa-cli'
+import { defineConfig } from 'dispersa/config'
 import { css, json } from 'dispersa'
 import { colorToHex, nameKebabCase } from 'dispersa/transforms'