swatchkit 0.0.23 → 0.2.0

package/README.md

@@ -196,6 +196,41 @@ If your component needs client-side JS:
 
 SwatchKit automatically bundles your JS files, wraps them in a safety scope (IIFE), and injects them into the final build.
 
+## How It Works
+
+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.
+*   **`tokens/*.json`**: These are your **Source of Truth**. You edit these files.
+*   **`css/`**: Copies static CSS files (`main.css`, `reset.css`, etc.). **You own these files**.
+*   **`swatchkit/`**: Sets up the documentation structure and layout.
+
+### 2. `swatchkit` (Build Process)
+Compiles your documentation site into `public/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.
+3.  **Copies Assets**: Copies your `css/` folder (including your manually edited `global-styles.css` and `main.css`) to the output folder.
+4.  **Scans Patterns**: Finds all HTML files in `swatchkit/` and stitches them into the documentation site.
+
+### Global Styles & Variables
+SwatchKit includes sensible defaults in `css/variables.css` and `css/global-styles.css`.
+*   These are **static files** copied to your project during `init`.
+*   They are **disabled by default** (commented out in `main.css`).
+*   **Action Required:** Open these files, verify that the variable names match your `tokens/*.json` names, and then uncomment the imports in `main.css` to enable them.
+
+### What is Safe to Edit?
+
+| File / Folder | Safe to Edit? | Notes |
+| :--- | :--- | :--- |
+| `tokens/*.json` | ✅ **YES** | Your source of truth. Safe. |
+| `css/main.css` | ✅ **YES** | Your entry point. Safe. |
+| `css/global-styles.css` | ✅ **YES** | You own this. Manually update if you rename tokens. |
+| `css/tokens.css` | 🚫 **NO** | Overwritten by **every** `swatchkit build` and `swatchkit init`. |
+| `swatchkit/_layout.html`| ✅ **YES** | Safe. **Warning:** `swatchkit init --force` WILL overwrite this. |
+| `swatchkit/tokens/*.html`| 🚫 **NO** | Overwritten by `swatchkit build` (visual previews). |
+
 ## CLI Reference
 
 ```bash

package/build.js

@@ -160,31 +160,31 @@ function resolveSettings(cliOptions, fileConfig) {
 
 // --- 4. Init Command Logic ---
 function runInit(settings, options) {
-  console.log("[SwatchKit] Initializing...");
+  console.log("[SwatchKit] Scaffolding project structure...");
 
   // Ensure swatchkit directory exists
   if (!fs.existsSync(settings.swatchkitDir)) {
-    console.log(`Creating swatchkit directory: ${settings.swatchkitDir}`);
+    console.log(`+ Directory: ${settings.swatchkitDir}`);
     fs.mkdirSync(settings.swatchkitDir, { recursive: true });
   }
 
   // Create tokens/ directory at project root (JSON token definitions)
   const tokensDir = settings.tokensDir;
   if (!fs.existsSync(tokensDir)) {
-    console.log(`Creating tokens directory: ${tokensDir}`);
+    console.log(`+ Directory: ${tokensDir}`);
     fs.mkdirSync(tokensDir, { recursive: true });
   }
 
   // Create swatchkit/tokens/ directory (HTML/JS visual previews)
   const tokensUiDir = path.join(settings.swatchkitDir, "tokens");
   if (!fs.existsSync(tokensUiDir)) {
-    console.log(`Creating tokens UI directory: ${tokensUiDir}`);
+    console.log(`+ Directory: ${tokensUiDir}`);
     fs.mkdirSync(tokensUiDir, { recursive: true });
   }
 
   // Create css/ directory at project root
   if (!fs.existsSync(settings.cssDir)) {
-    console.log(`Creating CSS directory: ${settings.cssDir}`);
+    console.log(`+ Directory: ${settings.cssDir}`);
     fs.mkdirSync(settings.cssDir, { recursive: true });
   }
 
@@ -195,7 +195,7 @@ function runInit(settings, options) {
       const srcPath = path.join(__dirname, "src/blueprints", srcFilename);
       const content = fs.readFileSync(srcPath, "utf-8");
       fs.writeFileSync(destPath, content);
-      console.log(`Created token file at ${destPath}`);
+      console.log(`+ Token Blueprint: ${destFilename}`);
     }
   };
 
@@ -216,7 +216,7 @@ function runInit(settings, options) {
       const srcPath = path.join(__dirname, "src/templates", srcFilename);
       const content = fs.readFileSync(srcPath, "utf-8");
       fs.writeFileSync(destPath, content.trim());
-      console.log(`Created pattern at ${destPath}`);
+      console.log(`+ Pattern Template: ${destFilename}`);
     }
   };
 
@@ -229,15 +229,34 @@ function runInit(settings, options) {
     const srcPath = path.join(__dirname, "src/templates/script.js");
     const content = fs.readFileSync(srcPath, "utf-8");
     fs.writeFileSync(tokensScriptFile, content.trim());
-    console.log(`Created tokens script at ${tokensScriptFile}`);
+    console.log(`+ Script: ${path.basename(tokensScriptFile)}`);
   }
 
   // Create main.css entry point
   if (!fs.existsSync(settings.mainCssFile)) {
     const srcPath = path.join(__dirname, "src/blueprints/main.css");
-    const content = fs.readFileSync(srcPath, "utf-8");
+    let content = fs.readFileSync(srcPath, "utf-8");
+
+    // Default: Copy the files
+    const copyCssBlueprint = (filename) => {
+      const src = path.join(__dirname, "src/blueprints", filename);
+      // Ensure destination path (cssDir) exists
+      if (!fs.existsSync(settings.cssDir)) {
+          fs.mkdirSync(settings.cssDir, { recursive: true });
+      }
+      const dest = path.join(settings.cssDir, filename);
+      // Only copy if destination doesn't exist
+      if (fs.existsSync(src) && !fs.existsSync(dest)) {
+        fs.copyFileSync(src, dest);
+        console.log(`+ CSS Blueprint: ${filename}`);
+      }
+    };
+    
+    copyCssBlueprint("variables.css");
+    copyCssBlueprint("global-styles.css");
+
     fs.writeFileSync(settings.mainCssFile, content);
-    console.log(`Created main stylesheet at ${settings.mainCssFile}`);
+    console.log(`+ CSS Blueprint: main.css`);
   }
 
   // Copy CSS Reset
@@ -245,7 +264,7 @@ function runInit(settings, options) {
   const resetDest = path.join(settings.cssDir, "reset.css");
   if (fs.existsSync(resetSrc) && !fs.existsSync(resetDest)) {
     fs.copyFileSync(resetSrc, resetDest);
-    console.log(`Created CSS reset at ${resetDest}`);
+    console.log(`+ CSS Blueprint: reset.css`);
   }
 
   // Copy Compositions
@@ -260,7 +279,7 @@ function runInit(settings, options) {
   const uiDest = path.join(settings.cssDir, "swatchkit-ui.css");
   if (fs.existsSync(uiSrc) && !fs.existsSync(uiDest)) {
     fs.copyFileSync(uiSrc, uiDest);
-    console.log(`Created UI styles at ${uiDest}`);
+    console.log(`+ CSS Blueprint: swatchkit-ui.css`);
   }
 
   // Generate initial tokens.css
@@ -269,20 +288,18 @@ function runInit(settings, options) {
   const targetLayout = settings.projectLayout;
 
   if (fs.existsSync(targetLayout) && !options.force) {
-    console.warn(`Warning: Layout file already exists at ${targetLayout}`);
-    console.warn("Use --force to overwrite.");
-    return;
-  }
-
-  if (fs.existsSync(settings.internalLayout)) {
-    const layoutContent = fs.readFileSync(settings.internalLayout, "utf-8");
-    fs.writeFileSync(targetLayout, layoutContent);
-    console.log(`Created layout file at ${targetLayout}`);
+    console.warn(`! Layout already exists: ${targetLayout} (Use --force to overwrite)`);
   } else {
-    console.error(
-      `Error: Internal layout file not found at ${settings.internalLayout}`,
-    );
-    process.exit(1);
+    if (fs.existsSync(settings.internalLayout)) {
+      const layoutContent = fs.readFileSync(settings.internalLayout, "utf-8");
+      fs.writeFileSync(targetLayout, layoutContent);
+      console.log(`+ Layout: ${path.basename(targetLayout)}`);
+    } else {
+      console.error(
+        `Error: Internal layout file not found at ${settings.internalLayout}`,
+      );
+      process.exit(1);
+    }
   }
 
   // Copy preview layout template (standalone page for individual swatches)
@@ -294,7 +311,7 @@ function runInit(settings, options) {
         "utf-8",
       );
       fs.writeFileSync(targetPreview, previewContent);
-      console.log(`Created preview layout at ${targetPreview}`);
+      console.log(`+ Layout: ${path.basename(targetPreview)}`);
     }
   }
 }
@@ -313,7 +330,7 @@ function copyDir(src, dest, force = false) {
     } else {
       if (force || !fs.existsSync(destPath)) {
         fs.copyFileSync(srcPath, destPath);
-        if (!force) console.log(`Created file at ${destPath}`);
+        if (!force) console.log(`+ Copied: ${entry.name}`);
       }
     }
   }
@@ -412,6 +429,7 @@ function build(settings) {
   });
 
   // 2.5 Process Tokens
+  console.log("Reading JSON tokens (tokens/*.json)...");
   processTokens(settings.tokensDir, settings.cssDir);
 
   // 2.6 Generate token display HTML from JSON
@@ -419,18 +437,18 @@ function build(settings) {
   if (fs.existsSync(tokensUiDir)) {
     const generated = generateTokenSwatches(settings.tokensDir, tokensUiDir);
     if (generated > 0) {
-      console.log(`Generated ${generated} token display files`);
+      console.log(`Generated ${generated} token documentation files (swatchkit/tokens/*.html)`);
     }
   }
 
   // 3. Copy CSS files (recursively)
   if (fs.existsSync(settings.cssDir)) {
-    console.log("Copying CSS...");
+    console.log("Copying static CSS assets (css/*)...");
     copyDir(settings.cssDir, settings.distCssDir, true);
   }
 
   // 4. Read swatches & JS
-  console.log("Processing swatches...");
+  console.log("Scanning HTML patterns (swatchkit/**/*.html)...");
   const scripts = [];
   const sections = {}; // Map<SectionName, Array<Swatch>>
 

package/package.json

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