swatchkit 0.6.1 → 0.7.0

package/README.md

@@ -270,11 +270,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

@@ -132,12 +132,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"),
@@ -467,7 +479,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 +504,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 +667,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 +720,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swatchkit",
-  "version": "0.6.1",
+  "version": "0.7.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>