swatchkit 0.12.0 → 1.0.1

package/README.md

@@ -9,10 +9,13 @@ It follows the "Magic Folder" principle: drop files in, and a library comes out.
 Try it instantly in any project:
 
 ```bash
-# 1. Initialize the layout and design tokens
-npx swatchkit init
+# 1. Create a config (sets your CSS location and preferences)
+npx swatchkit new
 
-# 2. Build the library
+# 2. Scaffold layout, tokens, and CSS blueprints
+npx swatchkit scaffold
+
+# 3. Build the library
 npx swatchkit
 ```
 
@@ -101,7 +104,7 @@ SwatchKit scaffolds a design system for you. Edit the JSON files in `tokens/`, a
 - **Modular Leading** (`text-leading.json`): Generates line-heights using `pow()` modular scales.
 - **Fonts & Weights**: Manages font families and weights.
 
-Visual documentation patterns for these tokens live in `swatchkit/tokens/` and are created during init.
+Visual documentation patterns for these tokens live in `swatchkit/tokens/` and are created during scaffold.
 
 ### 3. Intelligent Fluid Logic (New!)
 
@@ -180,7 +183,7 @@ The sidebar and documentation layout are styled by `css/swatchkit-ui.css`. This
 
 ### 6. Custom Layouts
 
-When you run `swatchkit init`, we create `swatchkit/_layout.html`.
+When you run `swatchkit scaffold`, we create `swatchkit/_layout.html`.
 **You own this file.**
 
 - Link to your own stylesheets.
@@ -203,12 +206,12 @@ SwatchKit automatically bundles your JS files, wraps them in a safety scope (IIF
 
 Understanding the build pipeline helps you know which files to edit and which are generated.
 
-### 1. `swatchkit init` (Scaffolding)
-Copies "blueprints" into your project to get you started. Init tracks a manifest of every file it manages (token JSONs, CSS blueprints, layout templates) so it can report what's new, changed, or up to date.
+### 1. `swatchkit scaffold` (Scaffolding)
+Copies "blueprints" into your project to get you started. Scaffold tracks a manifest of every file it manages (token JSONs, CSS blueprints, layout templates) so it can report what's new, changed, or up to date.
 
 *   **Fresh project:** Creates directories and copies all blueprint files.
-*   **Already initialized:** Prints a status report comparing your files to the latest blueprints. Suggests `--force` if anything has changed.
-*   **`--force`:** Overwrites all init-managed files with the latest blueprints. Your custom swatch HTML files and any CSS files without blueprint counterparts are never touched.
+*   **Already scaffolded:** Prints a status report comparing your files to the latest blueprints. Suggests `--force` if anything has changed.
+*   **`--force`:** Overwrites all scaffold-managed files with the latest blueprints. Your custom swatch HTML files and any CSS files without blueprint counterparts are never touched.
 *   **`--dry-run`:** Shows what would happen without writing anything.
 
 Files created:
@@ -227,7 +230,7 @@ Compiles your documentation site into `dist/swatchkit/`.
 
 ### Global Styles & Variables
 SwatchKit includes sensible defaults in `css/global/variables.css` and `css/global/elements.css`.
-*   These are **static files** copied to your project during `init` and **enabled by default**.
+*   These are **static files** copied to your project during `scaffold` and **enabled by default**.
 *   Variable references use the default token names from `tokens/*.json`. If you rename any tokens, update the `var()` references in these files to match.
 *   Both files are yours to edit — add your own variables and element styles freely.
 
@@ -239,9 +242,9 @@ SwatchKit includes sensible defaults in `css/global/variables.css` and `css/glob
 | `css/main.css` | ✅ **YES** | Your entry point. Safe. |
 | `css/global/variables.css` | ✅ **YES** | You own this. Update var() references if you rename tokens. |
 | `css/global/elements.css` | ✅ **YES** | You own this. Update var() references if you rename tokens. |
-| `css/tokens.css` | 🚫 **NO** | Overwritten by **every** `swatchkit build` and `swatchkit init`. |
-| `swatchkit/_layout.html`| ✅ **YES** | Safe during normal use. `init --force` overwrites all init-managed files, including this one. |
-| `swatchkit/_preview.html`| ✅ **YES** | Same as `_layout.html` — safe unless you run `init --force`. |
+| `css/tokens.css` | 🚫 **NO** | Overwritten by every build and `swatchkit scaffold`. |
+| `swatchkit/_layout.html`| ✅ **YES** | Safe during normal use. `scaffold --force` overwrites all scaffold-managed files, including this one. |
+| `swatchkit/_preview.html`| ✅ **YES** | Same as `_layout.html` — safe unless you run `scaffold --force`. |
 | `swatchkit/tokens/*.html`| 🚫 **NO** | Overwritten by `swatchkit build` (visual previews). |
 
 ## CLI Reference
@@ -252,27 +255,31 @@ swatchkit [command] [options]
 
 ### Commands
 
-- `swatchkit` (Default): Builds the library.
-- `swatchkit init`: Scaffolds the layout and token files. If the project is already initialized, prints a status report showing which files differ from their blueprints (auto dry-run).
-- `swatchkit init --force`: Overwrites all init-managed files with the latest blueprints. Custom swatch files and CSS files without blueprint counterparts are never touched.
-- `swatchkit init --dry-run`: Shows what would be created or changed without writing anything.
+- `swatchkit new`: Creates `swatchkit.config.js`. Prompts for your CSS directory location. Run this first in any new project.
+- `swatchkit new --cssDir ./src/css`: Non-interactive — creates config without prompting.
+- `swatchkit new --force`: Overwrites an existing config (backs up the old one).
+- `swatchkit scaffold`: Copies CSS blueprints, token JSON files, and layout templates into your project using the settings from `swatchkit.config.js`. If already scaffolded, prints a status report.
+- `swatchkit scaffold --force`: Overwrites all scaffold-managed files with the latest blueprints (with backups).
+- `swatchkit scaffold --dry-run`: Shows what would be created or changed without writing anything.
+- `swatchkit` (Default): Builds the pattern library.
 
 ### Flags
 
-| Flag        | Short | Description                                                     |
-| :---------- | :---- | :-------------------------------------------------------------- |
-| `--watch`   | `-w`  | Watch files and rebuild on change.                              |
-| `--config`  | `-c`  | Path to config file.                                            |
-| `--input`   | `-i`  | Pattern directory (Default: `swatchkit/`).                      |
-| `--outDir`  | `-o`  | Output directory (Default: `dist/swatchkit`).                   |
-| `--force`   | `-f`  | Overwrite all init-managed files with latest blueprints.        |
-| `--dry-run` |       | Show what init would create or change, without writing anything.|
-| `--help`    | `-h`  | Show help message.                                              |
-| `--version` | `-v`  | Show version number.                                            |
+| Flag        | Short | Description                                                        |
+| :---------- | :---- | :----------------------------------------------------------------- |
+| `--watch`   | `-w`  | Watch files and rebuild on change.                                 |
+| `--config`  | `-c`  | Path to config file.                                               |
+| `--input`   | `-i`  | Pattern directory (Default: `swatchkit/`).                         |
+| `--outDir`  | `-o`  | Output directory (Default: `dist/swatchkit`).                      |
+| `--cssDir`  |       | CSS directory, for use with `new` (Default: `src/css`).            |
+| `--force`   | `-f`  | Overwrite existing files (`new`: config, `scaffold`: blueprints).  |
+| `--dry-run` |       | Show what scaffold would create or change, without writing.        |
+| `--help`    | `-h`  | Show help message.                                                 |
+| `--version` | `-v`  | Show version number.                                               |
 
 ## Configuration
 
-Optional. Create `swatchkit.config.js` in your root for persistent settings.
+`swatchkit.config.js` is created by `swatchkit new`. You can also create it manually in your project root.
 
 ```javascript
 module.exports = {

package/build.js

@@ -18,14 +18,17 @@ function parseArgs(args) {
     config: null,
     input: null,
     outDir: null,
+    cssDir: null,
     force: false,
     dryRun: false,
   };
 
   for (let i = 2; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "init") {
-      options.command = "init";
+    if (arg === "new") {
+      options.command = "new";
+    } else if (arg === "scaffold") {
+      options.command = "scaffold";
     } else if (arg === "-w" || arg === "--watch") {
       options.watch = true;
     } else if (arg === "-h" || arg === "--help") {
@@ -49,6 +52,10 @@ function parseArgs(args) {
       if (i + 1 < args.length) {
         options.outDir = args[++i];
       }
+    } else if (arg === "--cssDir") {
+      if (i + 1 < args.length) {
+        options.cssDir = args[++i];
+      }
     }
   }
   return options;
@@ -215,7 +222,7 @@ function buildInitManifest(settings) {
   }
 
   // Template files (swatchkit/tokens/)
-  const templateFiles = ["prose.html", "script.js"];
+  const templateFiles = ["prose.html"];
   for (const file of templateFiles) {
     manifest.push({
       src: path.join(templatesDir, file),
@@ -336,12 +343,76 @@ function reportInitStatus(settings) {
 
   if (changed.length > 0 || created.length > 0 || newDirs.length > 0) {
     console.log(
-      "  Run 'swatchkit init --force' to update all files to latest blueprints.\n",
+      "  Run 'swatchkit scaffold --force' to update all files to latest blueprints.\n",
     );
   }
 }
 
-// --- 5. Init Command Logic ---
+// --- 5. New Command Logic ---
+function generateConfig(cssDir) {
+  return `// swatchkit.config.js
+module.exports = {
+  // Where your CSS lives. SwatchKit scaffolds blueprints here and reads
+  // tokens from here when building the pattern library.
+  cssDir: "${cssDir}",
+
+  // Set to false if a build tool (Vite, Astro, Eleventy, etc.) is already
+  // handling your CSS and you don't need SwatchKit to copy it.
+  cssCopy: true,
+
+  // Where token JSON files live.
+  // tokensDir: "./tokens",
+
+  // Where the built pattern library is output.
+  // outDir: "./dist/swatchkit",
+
+  // Files or folders to exclude from the pattern library (supports globs).
+  // exclude: [],
+};
+`;
+}
+
+function runNew(cliOptions) {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, 'swatchkit.config.js');
+
+  if (fs.existsSync(configPath) && !cliOptions.force) {
+    console.log('[SwatchKit] swatchkit.config.js already exists.');
+    console.log('  Run "swatchkit new --force" to overwrite it.');
+    return;
+  }
+
+  // Non-interactive mode: --cssDir flag provided
+  if (cliOptions.cssDir) {
+    const content = generateConfig(cliOptions.cssDir);
+    fs.writeFileSync(configPath, content);
+    console.log(`+ Created: swatchkit.config.js (cssDir: ${cliOptions.cssDir})`);
+    console.log('  Next: run "swatchkit scaffold" to set up your project.');
+    return;
+  }
+
+  // Interactive mode: prompt for CSS directory
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  rl.question('Where does your CSS live? [src/css]: ', (answer) => {
+    rl.close();
+    const cssDir = answer.trim() ? `./${answer.trim().replace(/^\.\//, '')}` : './src/css';
+    const content = generateConfig(cssDir);
+
+    if (fs.existsSync(configPath) && cliOptions.force) {
+      const backupPath = getBackupPath(configPath);
+      fs.copyFileSync(configPath, backupPath);
+      console.log(`  ~ Backed up: swatchkit.config.js → ${path.basename(backupPath)}`);
+    }
+
+    fs.writeFileSync(configPath, content);
+    console.log(`+ Created: swatchkit.config.js (cssDir: ${cssDir})`);
+    console.log('  Next: run "swatchkit scaffold" to set up your project.');
+  });
+}
+
+// --- 6. Scaffold Command Logic (formerly init) ---
 function runInit(settings, options) {
   const isInitialized = fs.existsSync(settings.swatchkitDir);
 
@@ -418,6 +489,23 @@ function runInit(settings, options) {
       path.join(settings.cssDir, "utilities"),
     );
   }
+
+  const cwd2 = process.cwd();
+  const tokensDir = path.relative(cwd2, settings.tokensDir);
+  console.log(`
+Done! Here's what to do next:
+
+  1. Edit your design tokens in ${tokensDir}/
+       colors.json        — your colour palette
+       text-sizes.json    — fluid type scale
+       spacing.json       — fluid spacing scale
+       fonts.json         — font stacks
+       text-weights.json  — font weights
+
+  2. Run "swatchkit" to build the pattern library
+
+  3. Open dist/swatchkit/index.html to view it
+`);
 }
 
 // --- 6. Build Logic ---
@@ -716,13 +804,19 @@ function build(settings) {
   });
 
   // 6. Write JS Bundle
+  // Always prepend the internal token display script (resolves CSS custom
+  // property values shown in token documentation pages).
+  const tokenDisplayScript = fs.readFileSync(
+    path.join(__dirname, "src/templates/script.js"),
+    "utf-8",
+  );
+  const internalScript = `/* --- SwatchKit: token display --- */\n(function() {\n${tokenDisplayScript}\n})();`;
+  const allScripts = [internalScript, ...scripts];
+  fs.writeFileSync(settings.outputJsFile, allScripts.join("\n"));
   if (scripts.length > 0) {
-    fs.writeFileSync(settings.outputJsFile, scripts.join("\n"));
     console.log(
-      `Bundled ${scripts.length} scripts to ${settings.outputJsFile}`,
+      `Bundled ${scripts.length} swatch scripts to ${settings.outputJsFile}`,
     );
-  } else {
-    fs.writeFileSync(settings.outputJsFile, "// No swatch scripts found");
   }
 
   // 7. Generate preview pages (standalone full-screen view of each swatch)
@@ -882,19 +976,19 @@ function printHelp() {
 Usage: swatchkit [command] [options]
 
 Commands:
+  new          Create a swatchkit.config.js for your project
+  scaffold     Set up CSS blueprints, token files, and layout templates
   (default)    Build the pattern library
-  init         Scaffold layout, tokens, and CSS blueprints
 
 Options:
   -w, --watch     Watch files and rebuild on change
   -c, --config    Path to config file
   -i, --input     Pattern directory (default: swatchkit/)
   -o, --outDir    Output directory (default: dist/swatchkit)
-  -f, --force     Overwrite all blueprint files with latest SwatchKit versions.
-                  Your existing files are backed up as .bak/.bak2 etc. before
-                  overwriting. Only css/global/tokens.css and
-                  css/utilities/tokens.css are excluded (auto-generated).
-      --dry-run   Show what init would create or change, without writing
+      --cssDir    CSS directory, for use with "new" (default: src/css)
+  -f, --force     Overwrite existing files (new: overwrites config,
+                  scaffold: overwrites all blueprint files with backups)
+      --dry-run   Show what scaffold would create or change, without writing
   -h, --help      Show this help message
   -v, --version   Show version number`);
 }
@@ -915,7 +1009,9 @@ try {
   const fileConfig = loadConfig(cliOptions.config);
   const settings = resolveSettings(cliOptions, fileConfig);
 
-  if (cliOptions.command === "init") {
+  if (cliOptions.command === "new") {
+    runNew(cliOptions);
+  } else if (cliOptions.command === "scaffold") {
     runInit(settings, cliOptions);
   } else {
     build(settings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swatchkit",
-  "version": "0.12.0",
+  "version": "1.0.1",
   "description": "A lightweight tool for creating HTML pattern libraries.",
   "main": "build.js",
   "bin": {