swatchkit 0.4.1 → 0.6.0

package/README.md

@@ -36,7 +36,7 @@ my-project/
 │       ├── colors.html
 │       ├── typography.html
 │       └── ...
-└── public/
+└── dist/
     └── swatchkit/          # Built pattern library
         └── index.html
 ```
@@ -207,7 +207,7 @@ Copies "blueprints" into your project to get you started.
 *   **`swatchkit/`**: Sets up the documentation structure and layout.
 
 ### 2. `swatchkit` (Build Process)
-Compiles your documentation site into `public/swatchkit/`.
+Compiles your documentation site into `dist/swatchkit/`.
 
 1.  **Reads JSON Tokens**: Scans `tokens/*.json` and calculates fluid typography/spacing.
 2.  **Generates CSS**: Creates `css/tokens.css`. **Do not edit this file**; it is overwritten every build.
@@ -249,7 +249,7 @@ swatchkit [command] [options]
 | `--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: `public/swatchkit`). |
+| `--outDir` | `-o`  | Output directory (Default: `dist/swatchkit`).   |
 | `--force`  | `-f`  | Overwrite layout file during init.              |
 
 ## Configuration
@@ -275,6 +275,23 @@ module.exports = {
 };
 ```
 
+## Using with a Framework
+
+SwatchKit outputs to `dist/swatchkit/` by default. If your framework (Vite, Astro, etc.) cleans the `dist/` directory during its build, run SwatchKit **after** your framework build:
+
+```json
+{
+  "scripts": {
+    "build": "vite build && swatchkit",
+    "dev": "vite dev & swatchkit -w"
+  }
+}
+```
+
+In watch mode, SwatchKit detects when its output directory is deleted by an external tool and automatically rebuilds.
+
+SwatchKit only ever writes inside its own output subdirectory — it will never modify or delete other files in `dist/`.
+
 ## Acknowledgements
 
 The CSS compositions included by default in SwatchKit are adapted from [Every Layout](https://every-layout.dev/) by Heydon Pickering and Andy Bell. Highly recommend their documentation for a deep dive into their brilliant CSS techniques.

package/build.js

@@ -2,7 +2,7 @@
 const fs = require("fs");
 const path = require("path");
 const chokidar = require("chokidar");
-const { processTokens } = require("./src/tokens");
+const { processTokens, generateTokenUtilities } = require("./src/tokens");
 const { generateTokenSwatches } = require("./src/generators");
 
 /**
@@ -110,12 +110,12 @@ function resolveSettings(cliOptions, fileConfig) {
   const swatchkitDir = findSwatchkitDir();
 
   // Output Dir
-  // Default: public/swatchkit
+  // Default: dist/swatchkit
   const outDir = cliOptions.outDir
     ? path.resolve(cwd, cliOptions.outDir)
     : fileConfig.outDir
       ? path.resolve(cwd, fileConfig.outDir)
-      : path.join(cwd, "public/swatchkit");
+      : path.join(cwd, "dist/swatchkit");
 
   // CSS directory - where tokens.css and user's main.css live
   // Default: css/ at project root
@@ -298,7 +298,11 @@ function runInit(settings, options) {
   // processTokens now expects the folder where tokens.css should live
   // We pass settings.cssDir, but processTokens internally joins 'tokens.css'
   // So we need to point it to css/global
-  processTokens(settings.tokensDir, path.join(settings.cssDir, "global"));
+  const tokensContext = processTokens(settings.tokensDir, path.join(settings.cssDir, "global"));
+  
+  if (tokensContext) {
+    generateTokenUtilities(tokensContext, path.join(settings.cssDir, "utilities"));
+  }
 
   const targetLayout = settings.projectLayout;
 
@@ -424,6 +428,24 @@ ${scriptContent}
   return swatches;
 }
 
+function validateOutDir(outDir) {
+  const cwd = process.cwd();
+  const relative = path.relative(cwd, outDir);
+
+  if (
+    !relative ||                          // outDir === cwd
+    relative === '..' ||                  // above cwd
+    relative.startsWith('../') ||         // above cwd
+    path.isAbsolute(relative) ||          // different drive/root
+    relative.split(path.sep).length < 2   // top-level dir like "dist" with no subfolder
+  ) {
+    console.error(
+      `[SwatchKit] Refusing to clean outDir "${outDir}" — must be a subdirectory at least 2 levels deep (e.g., dist/swatchkit).`,
+    );
+    process.exit(1);
+  }
+}
+
 function build(settings) {
   console.log(`[SwatchKit] Starting build...`);
   console.log(`  Source:   ${settings.swatchkitDir}`);
@@ -438,7 +460,13 @@ function build(settings) {
     process.exit(1);
   }
 
-  // 2. Ensure dist directories exist
+  // 2. Clean previous output (only our subdirectory, never the parent)
+  validateOutDir(settings.outDir);
+  if (fs.existsSync(settings.outDir)) {
+    fs.rmSync(settings.outDir, { recursive: true });
+  }
+
+  // 3. Ensure dist directories exist
   [settings.outDir, settings.distCssDir, settings.distJsDir].forEach((dir) => {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   });
@@ -446,7 +474,12 @@ function build(settings) {
   // 2.5 Process Tokens
   console.log("Reading JSON tokens (tokens/*.json)...");
   // Output tokens.css to css/global/tokens.css
-  processTokens(settings.tokensDir, path.join(settings.cssDir, "global"));
+  const tokensContext = processTokens(settings.tokensDir, path.join(settings.cssDir, "global"));
+  
+  // Generate Utilities to css/utilities/tokens.css
+  if (tokensContext) {
+    generateTokenUtilities(tokensContext, path.join(settings.cssDir, "utilities"));
+  }
 
   // 2.6 Generate token display HTML from JSON
   const tokensUiDir = path.join(settings.swatchkitDir, "tokens");
@@ -674,7 +707,7 @@ function build(settings) {
 
 // --- 6. Watch Logic ---
 function watch(settings) {
-  const watchPaths = [
+  const sourcePaths = [
     settings.swatchkitDir,
     settings.tokensDir,
     settings.projectLayout,
@@ -683,30 +716,48 @@ function watch(settings) {
 
   console.log("[SwatchKit] Watch mode enabled.");
   console.log("Watching for changes in:");
-  watchPaths.forEach((p) => console.log(`  - ${p}`));
+  sourcePaths.forEach((p) => console.log(`  - ${p}`));
+  console.log(`  Polling: ${settings.outDir} (rebuild if deleted by external tools)`);
 
   let buildTimeout;
+  let isRebuilding = false;
+
   const rebuild = () => {
     if (buildTimeout) clearTimeout(buildTimeout);
     buildTimeout = setTimeout(() => {
       try {
+        isRebuilding = true;
         console.log("[SwatchKit] Change detected. Rebuilding...");
         build(settings);
       } catch (e) {
         console.error("[SwatchKit] Build failed:", e.message);
+      } finally {
+        isRebuilding = false;
       }
     }, 100); // 100ms debounce
   };
 
-  const watcher = chokidar.watch(watchPaths, {
+  // Watch source files for changes
+  const sourceWatcher = chokidar.watch(sourcePaths, {
     ignored: /(^|[\/\\])\../, // ignore dotfiles
     persistent: true,
     ignoreInitial: true,
   });
 
-  watcher.on("all", (event, path) => {
+  sourceWatcher.on("all", () => {
     rebuild();
   });
+
+  // Poll for output directory deletion (e.g., when a framework build wipes dist/).
+  // We use polling instead of a chokidar watcher on the output dir to avoid
+  // infinite rebuild loops — since our own build deletes and recreates the
+  // output directory, an event-based watcher would retrigger endlessly.
+  setInterval(() => {
+    if (!isRebuilding && !fs.existsSync(settings.outDir)) {
+      console.log("[SwatchKit] Output directory was deleted. Rebuilding...");
+      rebuild();
+    }
+  }, 2000);
 }
 
 // --- Main Execution ---

package/package.json

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