swatchkit 0.6.2 → 0.8.0

package/README.md

@@ -201,10 +201,17 @@ 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.
+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.
+
+*   **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.
+*   **`--dry-run`:** Shows what would happen without writing anything.
+
+Files created:
 *   **`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.
+*   **`css/`**: Copies static CSS files (`main.css`, `reset.css`, compositions, etc.). **You own these files**.
+*   **`swatchkit/`**: Sets up the documentation structure, layout templates, and token display patterns.
 
 ### 2. `swatchkit` (Build Process)
 Compiles your documentation site into `dist/swatchkit/`.
@@ -228,7 +235,8 @@ SwatchKit includes sensible defaults in `css/variables.css` and `css/global-styl
 | `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/_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`. |
 | `swatchkit/tokens/*.html`| 🚫 **NO** | Overwritten by `swatchkit build` (visual previews). |
 
 ## CLI Reference
@@ -240,17 +248,20 @@ swatchkit [command] [options]
 ### Commands
 
 - `swatchkit` (Default): Builds the library.
-- `swatchkit init`: Scaffolds the layout and token files.
+- `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.
 
 ### 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 layout file during init.              |
+| 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.|
 
 ## Configuration
 
@@ -270,11 +281,83 @@ module.exports = {
   // Override tokens directory (JSON token definitions)
   tokensDir: "./src/tokens",
 
+  // Skip copying CSS into SwatchKit's output directory.
+  // When false, SwatchKit references CSS at cssPath instead of copying it.
+  // See "Common Workflows" below for when to use this.
+  cssCopy: false,
+
+  // Relative path from SwatchKit's HTML to your CSS files.
+  // Only relevant when cssCopy is false.
+  // Defaults to "../<basename of cssDir>/" (e.g., "../css/" if cssDir is "./src/css").
+  // Set explicitly if your deployed CSS lives at a different path.
+  cssPath: "../css/",
+
   // Exclude files (supports glob patterns)
   exclude: ["*.test.js", "temp*"],
 };
 ```
 
+## Common Workflows
+
+### Deploy alongside your project
+
+If your build tool (Vite, Astro, etc.) already outputs CSS to `dist/`, you don't need SwatchKit to copy it again. Set `cssCopy: false` and SwatchKit's HTML will reference your existing CSS.
+
+```javascript
+// swatchkit.config.js
+module.exports = {
+  cssDir: "./src/css",
+  cssCopy: false,
+};
+```
+
+```
+dist/
+├── css/                    # Your build tool puts CSS here
+│   ├── main.css
+│   └── tokens.css
+├── index.html              # Your project
+└── swatchkit/
+    └── index.html          # References ../css/main.css
+```
+
+SwatchKit derives the default `cssPath` from your `cssDir` name. If `cssDir` is `"./src/css"`, it defaults to `"../css/"`. If `cssDir` is `"./styles"`, it defaults to `"../styles/"`.
+
+If your deployed CSS ends up somewhere else (e.g., Vite hashes it into `dist/assets/`), set `cssPath` explicitly:
+
+```javascript
+module.exports = {
+  cssDir: "./src/css",
+  cssCopy: false,
+  cssPath: "../assets/",
+};
+```
+
+### Local dev only (self-contained)
+
+If SwatchKit is just a development tool and you don't want it in `dist/`, set `outDir` to a separate directory. Keep `cssCopy` enabled (the default) so the output is fully self-contained.
+
+```javascript
+// swatchkit.config.js
+module.exports = {
+  cssDir: "./src/css",
+  outDir: "swatchkit-dist",
+};
+```
+
+```
+my-project/
+├── dist/                   # Your production build (no SwatchKit)
+│   └── ...
+└── swatchkit-dist/         # Self-contained, serve locally during dev
+    ├── css/
+    │   ├── main.css
+    │   └── tokens.css
+    └── index.html
+```
+
+You can serve `swatchkit-dist/` locally during development without affecting your production build.
+
 ## 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:

package/build.js

@@ -19,6 +19,7 @@ function parseArgs(args) {
     input: null,
     outDir: null,
     force: false,
+    dryRun: false,
   };
 
   for (let i = 2; i < args.length; i++) {
@@ -29,6 +30,8 @@ function parseArgs(args) {
       options.watch = true;
     } else if (arg === "-f" || arg === "--force") {
       options.force = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
     } else if (arg === "-c" || arg === "--config") {
       // Handle case where flag is last arg
       if (i + 1 < args.length) {
@@ -132,12 +135,24 @@ function resolveSettings(cliOptions, fileConfig) {
   // Exclude patterns
   const exclude = fileConfig.exclude || [];
 
+  // CSS copy behavior
+  // When true (default), copies cssDir into outDir/css/ for a self-contained build.
+  // When false, skips the copy — expects CSS to already exist at cssPath relative to output.
+  const cssCopy = fileConfig.cssCopy !== undefined ? fileConfig.cssCopy : true;
+
+  // Relative path from SwatchKit HTML output to the user's CSS directory.
+  // Only used when cssCopy is false. Derived from cssDir basename by default
+  // (e.g., cssDir: "./src/css" -> "../css/", cssDir: "./styles" -> "../styles/").
+  const cssPath = fileConfig.cssPath || (cssCopy ? "css/" : `../${path.basename(cssDir)}/`);
+
   return {
     swatchkitDir,
     outDir,
     cssDir,
     tokensDir,
     exclude,
+    cssCopy,
+    cssPath,
     fileConfig, // Expose config to init
     // Internal layout templates (relative to this script)
     internalLayout: path.join(__dirname, "src/layout.html"),
@@ -158,184 +173,227 @@ function resolveSettings(cliOptions, fileConfig) {
   };
 }
 
-// --- 4. Init Command Logic ---
-function runInit(settings, options) {
-  console.log("[SwatchKit] Scaffolding project structure...");
-
-  // Ensure swatchkit directory exists
-  if (!fs.existsSync(settings.swatchkitDir)) {
-    console.log(`+ Directory: ${settings.swatchkitDir}`);
-    fs.mkdirSync(settings.swatchkitDir, { recursive: true });
+// --- 4. Init Manifest & Dry Run ---
+
+// Builds a list of all files that init manages.
+// Each entry maps a blueprint source to a project destination.
+// Used by both the actual init and the dry-run status report.
+function buildInitManifest(settings) {
+  const manifest = [];
+  const blueprintsDir = path.join(__dirname, "src/blueprints");
+  const templatesDir = path.join(__dirname, "src/templates");
+
+  // Token blueprint JSON files
+  const tokenFiles = [
+    "colors.json",
+    "text-weights.json",
+    "text-leading.json",
+    "viewports.json",
+    "text-sizes.json",
+    "spacing.json",
+    "fonts.json",
+  ];
+  for (const file of tokenFiles) {
+    manifest.push({
+      src: path.join(blueprintsDir, file),
+      dest: path.join(settings.tokensDir, file),
+    });
   }
 
-  // Create tokens/ directory at project root (JSON token definitions)
-  const tokensDir = settings.tokensDir;
-  if (!fs.existsSync(tokensDir)) {
-    console.log(`+ Directory: ${tokensDir}`);
-    fs.mkdirSync(tokensDir, { recursive: true });
+  // Template files (swatchkit/tokens/)
+  const templateFiles = ["prose.html", "script.js"];
+  for (const file of templateFiles) {
+    manifest.push({
+      src: path.join(templatesDir, file),
+      dest: path.join(settings.swatchkitDir, "tokens", file),
+      transform: (content) => content.trim(),
+    });
   }
 
-  // Create swatchkit/tokens/ directory (HTML/JS visual previews)
-  const tokensUiDir = path.join(settings.swatchkitDir, "tokens");
-  if (!fs.existsSync(tokensUiDir)) {
-    console.log(`+ Directory: ${tokensUiDir}`);
-    fs.mkdirSync(tokensUiDir, { recursive: true });
-  }
+  // CSS entry point
+  manifest.push({
+    src: path.join(blueprintsDir, "main.css"),
+    dest: settings.mainCssFile,
+  });
 
-  // Create css/ directory at project root
-  if (!fs.existsSync(settings.cssDir)) {
-    console.log(`+ Directory: ${settings.cssDir}`);
-    fs.mkdirSync(settings.cssDir, { recursive: true });
-  }
+  // SwatchKit UI styles
+  manifest.push({
+    src: path.join(blueprintsDir, "swatchkit-ui.css"),
+    dest: path.join(settings.cssDir, "swatchkit-ui.css"),
+  });
 
-  // Create css/global directory
-  const globalCssDir = path.join(settings.cssDir, "global");
-  if (!fs.existsSync(globalCssDir)) {
-    console.log(`+ Directory: ${globalCssDir}`);
-    fs.mkdirSync(globalCssDir, { recursive: true });
+  // CSS folder blueprints (global, compositions, utilities)
+  const cssFolders = ["global", "compositions", "utilities"];
+  for (const folder of cssFolders) {
+    const srcDir = path.join(blueprintsDir, folder);
+    if (fs.existsSync(srcDir)) {
+      const files = fs
+        .readdirSync(srcDir)
+        .filter((f) => !fs.statSync(path.join(srcDir, f)).isDirectory());
+      for (const file of files) {
+        manifest.push({
+          src: path.join(srcDir, file),
+          dest: path.join(settings.cssDir, folder, file),
+        });
+      }
+    }
   }
 
-  // Copy JSON token blueprints to tokens/ (project root)
-  const copyDefault = (srcFilename, destFilename) => {
-    const destPath = path.join(tokensDir, destFilename);
-    if (!fs.existsSync(destPath)) {
-      const srcPath = path.join(__dirname, "src/blueprints", srcFilename);
-      const content = fs.readFileSync(srcPath, "utf-8");
-      fs.writeFileSync(destPath, content);
-      console.log(`+ Token Blueprint: ${destFilename}`);
-    }
-  };
+  // Layout files
+  manifest.push({
+    src: settings.internalLayout,
+    dest: settings.projectLayout,
+  });
+  manifest.push({
+    src: settings.internalPreviewLayout,
+    dest: settings.projectPreviewLayout,
+  });
+
+  return manifest;
+}
+
+// Directories that init ensures exist.
+function getInitDirs(settings) {
+  return [
+    settings.swatchkitDir,
+    settings.tokensDir,
+    path.join(settings.swatchkitDir, "tokens"),
+    settings.cssDir,
+    path.join(settings.cssDir, "global"),
+  ];
+}
+
+// Compare init-managed files against their blueprint sources and print a
+// status report showing what would be created, changed, or is up to date.
+function reportInitStatus(settings) {
+  const cwd = process.cwd();
+  const manifest = buildInitManifest(settings);
+  const dirs = getInitDirs(settings);
 
-  copyDefault("colors.json", "colors.json");
-  copyDefault("text-weights.json", "text-weights.json");
-  copyDefault("text-leading.json", "text-leading.json");
-  copyDefault("viewports.json", "viewports.json");
-  copyDefault("text-sizes.json", "text-sizes.json");
-  copyDefault("spacing.json", "spacing.json");
-  copyDefault("fonts.json", "fonts.json");
-
-  // Copy HTML/JS template patterns to swatchkit/tokens/ (UI documentation)
-  // Note: Token display templates (colors, typography, spacing, etc.) are
-  // generated dynamically at build time from the JSON token files.
-  const copyTemplate = (srcFilename, destFilename) => {
-    const destPath = path.join(tokensUiDir, destFilename);
-    if (!fs.existsSync(destPath)) {
-      const srcPath = path.join(__dirname, "src/templates", srcFilename);
-      const content = fs.readFileSync(srcPath, "utf-8");
-      fs.writeFileSync(destPath, content.trim());
-      console.log(`+ Pattern Template: ${destFilename}`);
+  const newDirs = [];
+  const created = [];
+  const changed = [];
+  const upToDate = [];
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      newDirs.push(path.relative(cwd, dir) + "/");
     }
-  };
+  }
 
-  // Only copy non-token templates (prose is a kitchen sink, not a token display)
-  copyTemplate("prose.html", "prose.html");
-
-  // Create shared script for tokens UI
-  const tokensScriptFile = path.join(tokensUiDir, "script.js");
-  if (!fs.existsSync(tokensScriptFile)) {
-    const srcPath = path.join(__dirname, "src/templates/script.js");
-    const content = fs.readFileSync(srcPath, "utf-8");
-    fs.writeFileSync(tokensScriptFile, content.trim());
-    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");
-    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}`);
+  for (const entry of manifest) {
+    const relDest = path.relative(cwd, entry.dest);
+    if (!fs.existsSync(entry.dest)) {
+      created.push(relDest);
+    } else {
+      let srcContent = fs.readFileSync(entry.src, "utf-8");
+      if (entry.transform) srcContent = entry.transform(srcContent);
+      const destContent = fs.readFileSync(entry.dest, "utf-8");
+      if (srcContent !== destContent) {
+        changed.push(relDest);
+      } else {
+        upToDate.push(relDest);
       }
-    };
-    
-    // Global blueprints are now copied as a folder below
+    }
+  }
 
-    fs.writeFileSync(settings.mainCssFile, content);
-    console.log(`+ CSS Blueprint: main.css`);
+  if (newDirs.length === 0 && created.length === 0 && changed.length === 0) {
+    console.log("[SwatchKit] All init-managed files are up to date.");
+    return;
   }
 
-  // Copy Global Styles Folder
-  const globalSrc = path.join(__dirname, "src/blueprints/global");
-  const globalDest = path.join(settings.cssDir, "global");
-  if (fs.existsSync(globalSrc)) {
-    copyDir(globalSrc, globalDest);
+  if (newDirs.length > 0 || created.length > 0) {
+    console.log("\n  New (will be created):");
+    for (const d of newDirs) console.log(`    + ${d}`);
+    for (const f of created) console.log(`    + ${f}`);
   }
 
-  // Copy Compositions
-  const compositionsSrc = path.join(__dirname, "src/blueprints/compositions");
-  const compositionsDest = path.join(settings.cssDir, "compositions");
-  if (fs.existsSync(compositionsSrc)) {
-    copyDir(compositionsSrc, compositionsDest);
+  if (changed.length > 0) {
+    console.log("\n  Changed (differs from latest blueprint):");
+    for (const f of changed) console.log(`    ~ ${f}`);
   }
 
-  // Copy Utilities
-  const utilitiesSrc = path.join(__dirname, "src/blueprints/utilities");
-  const utilitiesDest = path.join(settings.cssDir, "utilities");
-  if (fs.existsSync(utilitiesSrc)) {
-    copyDir(utilitiesSrc, utilitiesDest);
+  if (upToDate.length > 0) {
+    console.log("\n  Up to date:");
+    for (const f of upToDate) console.log(`    = ${f}`);
   }
 
-  // Copy SwatchKit UI Styles
-  const uiSrc = path.join(__dirname, "src/blueprints/swatchkit-ui.css");
-  const uiDest = path.join(settings.cssDir, "swatchkit-ui.css");
-  if (fs.existsSync(uiSrc) && !fs.existsSync(uiDest)) {
-    fs.copyFileSync(uiSrc, uiDest);
-    console.log(`+ CSS Blueprint: swatchkit-ui.css`);
+  console.log("");
+
+  if (changed.length > 0 || created.length > 0 || newDirs.length > 0) {
+    console.log(
+      "  Run 'swatchkit init --force' to update all files to latest blueprints.\n",
+    );
   }
+}
 
-  // Generate initial tokens.css
-  // 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
-  const tokensContext = processTokens(settings.tokensDir, path.join(settings.cssDir, "global"));
-  
-  if (tokensContext) {
-    generateTokenUtilities(tokensContext, path.join(settings.cssDir, "utilities"));
+// --- 5. Init Command Logic ---
+function runInit(settings, options) {
+  const isInitialized = fs.existsSync(settings.swatchkitDir);
+
+  // --dry-run: always just report status, change nothing.
+  // Already initialized without --force: auto dry-run.
+  if (options.dryRun || (isInitialized && !options.force)) {
+    if (isInitialized && !options.dryRun) {
+      console.log("[SwatchKit] Project already initialized.");
+    }
+    reportInitStatus(settings);
+    return;
+  }
+
+  // Sanity check: internal layout template must exist
+  if (!fs.existsSync(settings.internalLayout)) {
+    console.error(
+      `Error: Internal layout file not found at ${settings.internalLayout}`,
+    );
+    process.exit(1);
   }
 
-  const targetLayout = settings.projectLayout;
+  console.log("[SwatchKit] Scaffolding project structure...");
 
-  if (fs.existsSync(targetLayout) && !options.force) {
-    console.warn(`! Layout already exists: ${targetLayout} (Use --force to overwrite)`);
-  } else {
-    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);
+  // Ensure directories exist
+  const cwd = process.cwd();
+  for (const dir of getInitDirs(settings)) {
+    if (!fs.existsSync(dir)) {
+      console.log(`+ Directory: ${path.relative(cwd, dir)}/`);
+      fs.mkdirSync(dir, { recursive: true });
     }
   }
 
-  // Copy preview layout template (standalone page for individual swatches)
-  const targetPreview = settings.projectPreviewLayout;
-  if (!fs.existsSync(targetPreview)) {
-    if (fs.existsSync(settings.internalPreviewLayout)) {
-      const previewContent = fs.readFileSync(
-        settings.internalPreviewLayout,
-        "utf-8",
-      );
-      fs.writeFileSync(targetPreview, previewContent);
-      console.log(`+ Layout: ${path.basename(targetPreview)}`);
+  // Copy all manifest files
+  const manifest = buildInitManifest(settings);
+  for (const entry of manifest) {
+    const exists = fs.existsSync(entry.dest);
+    if (options.force || !exists) {
+      // Ensure parent directory exists (for CSS subdirs like compositions/)
+      const parentDir = path.dirname(entry.dest);
+      if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+      }
+
+      let content = fs.readFileSync(entry.src, "utf-8");
+      if (entry.transform) content = entry.transform(content);
+      fs.writeFileSync(entry.dest, content);
+
+      const label = path.relative(cwd, entry.dest);
+      console.log(`${exists ? "~ Updated" : "+ Created"}: ${label}`);
     }
   }
+
+  // Generate tokens.css and utility tokens.css (always — these are generated files)
+  const tokensContext = processTokens(
+    settings.tokensDir,
+    path.join(settings.cssDir, "global"),
+  );
+  if (tokensContext) {
+    generateTokenUtilities(
+      tokensContext,
+      path.join(settings.cssDir, "utilities"),
+    );
+  }
 }
 
-// --- 5. Build Logic ---
+// --- 6. Build Logic ---
 function copyDir(src, dest, force = false) {
   if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -467,7 +525,9 @@ function build(settings) {
   }
 
   // 3. Ensure dist directories exist
-  [settings.outDir, settings.distCssDir, settings.distJsDir].forEach((dir) => {
+  const distDirs = [settings.outDir, settings.distJsDir];
+  if (settings.cssCopy) distDirs.push(settings.distCssDir);
+  distDirs.forEach((dir) => {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   });
 
@@ -490,10 +550,12 @@ function build(settings) {
     }
   }
 
-  // 3. Copy CSS files (recursively)
-  if (fs.existsSync(settings.cssDir)) {
+  // 3. Copy CSS files (recursively) — skip if cssCopy is disabled
+  if (settings.cssCopy && fs.existsSync(settings.cssDir)) {
     console.log("Copying static CSS assets (css/*)...");
     copyDir(settings.cssDir, settings.distCssDir, true);
+  } else if (!settings.cssCopy) {
+    console.log(`Skipping CSS copy (cssCopy: false). CSS referenced at: ${settings.cssPath}`);
   }
 
   // 4. Read swatches & JS
@@ -651,25 +713,32 @@ function build(settings) {
     sortedKeys.forEach((section) => {
       const swatches = sections[section];
       swatches.forEach((p) => {
-        // Determine output path and relative CSS path
+        // Determine output path and relative CSS path.
+        // Preview pages need to navigate up to the swatchkit output root,
+        // then follow cssPath to reach the CSS files.
         let previewFile, cssPath;
         if (p.sectionSlug) {
           const sectionDir = path.join(settings.distPreviewDir, p.sectionSlug);
           if (!fs.existsSync(sectionDir))
             fs.mkdirSync(sectionDir, { recursive: true });
           previewFile = path.join(sectionDir, `${p.id}.html`);
-          cssPath = "../../"; // preview/section/file.html -> ../../css/
+          cssPath = "../../" + settings.cssPath; // preview/section/file.html -> ../../ + cssPath
         } else {
           if (!fs.existsSync(settings.distPreviewDir))
             fs.mkdirSync(settings.distPreviewDir, { recursive: true });
           previewFile = path.join(settings.distPreviewDir, `${p.id}.html`);
-          cssPath = "../"; // preview/file.html -> ../css/
+          cssPath = "../" + settings.cssPath; // preview/file.html -> ../ + cssPath
         }
 
+        // JS always lives in the swatchkit output dir, so jsPath just
+        // navigates back to the output root (not to the user's CSS dir).
+        const jsPath = p.sectionSlug ? "../../" : "../";
+
         const previewHtml = previewLayoutContent
           .replace("<!-- PREVIEW_TITLE -->", p.name)
           .replace("<!-- PREVIEW_CONTENT -->", p.content)
           .replaceAll("<!-- CSS_PATH -->", cssPath)
+          .replaceAll("<!-- JS_PATH -->", jsPath)
           .replace("<!-- HEAD_EXTRAS -->", "");
 
         fs.writeFileSync(previewFile, previewHtml);
@@ -697,6 +766,7 @@ function build(settings) {
   const finalHtml = layoutContent
     .replace("<!-- SIDEBAR_LINKS -->", sidebarLinks)
     .replace("<!-- SWATCHES -->", swatchBlocks)
+    .replaceAll("<!-- CSS_PATH -->", settings.cssPath)
     .replace("<!-- HEAD_EXTRAS -->", headExtras);
 
   // 9. Write output
@@ -705,7 +775,7 @@ function build(settings) {
   console.log(`Build complete! Generated ${settings.outputFile}`);
 }
 
-// --- 6. Watch Logic ---
+// --- 7. Watch Logic ---
 function watch(settings) {
   const sourcePaths = [
     settings.swatchkitDir,

package/package.json

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

package/src/layout.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>SwatchKit</title>
-    <link rel="stylesheet" href="css/main.css" />
-    <link rel="stylesheet" href="css/swatchkit-ui.css" />
+    <link rel="stylesheet" href="<!-- CSS_PATH -->main.css" />
+    <link rel="stylesheet" href="<!-- CSS_PATH -->swatchkit-ui.css" />
     <!-- HEAD_EXTRAS -->
   </head>
   <body>