@designid/tokens 1.1.2 → 1.2.0

package/README.md

@@ -25,6 +25,8 @@ To build the design system tokens, you need to run the `bun tokens-build` or `bu
 ### Quick Start
 Copy the example folder in this project. To be able to configure it, you need to customize `designid.config.ts` based on your setup.
 
+> **Note:** All commands (`tokens-build`, `tokens-watch`, `tokens-editor`) automatically compile your `designid.config.ts` to `.mjs` when they run. You never need to manually compile your config file!
+
 #### Building tokens
 If you have the `designid.config.ts` in your root project folder you can execute the following build script.
 ```bash
@@ -45,6 +47,96 @@ To build the design system tokens in development mode, you can use the `tokens-w
 bun tokens-watch
 ```
 
+## Token Editor
+
+A web-based editor for managing W3C Design Tokens with full CRUD operations, token references, and mode support.
+
+### Configuration
+
+Configure the editor in your `designid.config.ts`:
+
+```typescript
+{
+  $metaData: {
+    editor: {
+      enabled: true,        // Enable/disable the editor
+      port: 3002,           // Editor server port
+    },
+  },
+}
+```
+
+### Starting the Editor
+
+After installing the package, you can start the editor using the `tokens-editor` command:
+
+#### 1. Using the CLI command (Recommended)
+```bash
+# Start with settings from config file
+tokens-editor
+
+# Override port from command line  
+tokens-editor --port=4000
+
+# Start with verbose logging
+tokens-editor --verbose
+
+# View all options
+tokens-editor --help
+```
+
+**Note:** CLI arguments override config file settings. The editor automatically compiles your config file when starting, so you don't need to manually compile `designid.config.ts` anymore - just run the editor and it will handle compilation for you!
+
+#### 2. Using npm scripts
+```bash
+# Start the server
+npm run editor:server
+
+# Open in browser
+npm run editor:open
+```
+
+#### 3. Programmatic API (from external packages)
+
+```typescript
+import { startEditorServer } from '@designid/tokens/editor';
+
+// Start with default options (port 3002)
+await startEditorServer();
+
+// Start with custom options
+await startEditorServer({
+  port: 4000,
+  configPath: './my-config.ts',
+  verbose: true
+});
+```
+
+**EditorServerOptions:**
+- `port` (number, default: 3002) - Server port
+- `configPath` (string, default: './designid.config.ts') - Path to config file
+- `verbose` (boolean, default: false) - Enable verbose logging
+
+#### 4. Direct command (for development)
+```bash
+bun src/editor/server.ts
+```
+
+The editor will be available at `http://localhost:3002` (or your custom port).
+
+### Editor Features
+
+- 🌲 **Tree View**: Hierarchical display of tokens with expand/collapse
+- 🔍 **Search & Filter**: Search by token path and name
+- ✏️ **Full CRUD**: Create, read, update, and delete tokens
+- 🔗 **Token References**: Autocomplete with `{path}` syntax
+- 🎨 **Mode Support**: Light, dark, and custom theme modes
+- ✅ **Path Validation**: Client and server-side validation
+- 🔄 **Real-time Feedback**: Live warnings for conflicts and errors
+- 📝 **W3C Compliance**: Full support for W3C Design Tokens spec
+
+For detailed documentation, see [src/editor/README.md](src/editor/README.md).
+
 ### File structure
 The file structure of the design system tokens is as follows in a typical web application project: