swatchkit 1.1.1 → 2.0.0

package/build.js

@@ -175,10 +175,8 @@ function resolveSettings(cliOptions, fileConfig) {
     // Derived paths
     distCssDir: path.join(outDir, "css"),
     distTokensCssFile: path.join(outDir, "css", "tokens.css"),
-    distJsDir: path.join(outDir, "js"),
     distPreviewDir: path.join(outDir, "preview"),
     outputFile: path.join(outDir, "index.html"),
-    outputJsFile: path.join(outDir, "js/swatches.js"),
     tokensCssFile: path.join(cssDir, "global", "tokens.css"),
     mainCssFile: path.join(cssDir, "main.css"),
   };
@@ -231,6 +229,22 @@ function buildInitManifest(settings) {
     });
   }
 
+  // Hello swatch (default example in swatchkit/swatches/hello/)
+  for (const file of ["index.html", "README.md"]) {
+    manifest.push({
+      src: path.join(templatesDir, "hello", file),
+      dest: path.join(settings.swatchkitDir, "swatches", "hello", file),
+    });
+  }
+
+  // Swatches CSS folder (css/swatches/)
+  for (const file of ["index.css", "hello.css"]) {
+    manifest.push({
+      src: path.join(blueprintsDir, "swatches", file),
+      dest: path.join(settings.cssDir, "swatches", file),
+    });
+  }
+
   // Utility and composition display templates — walk each subfolder
   for (const section of ["utilities", "compositions"]) {
     const sectionSrc = path.join(templatesDir, section);
@@ -301,8 +315,11 @@ function getInitDirs(settings) {
     path.join(settings.swatchkitDir, "tokens"),
     path.join(settings.swatchkitDir, "utilities"),
     path.join(settings.swatchkitDir, "compositions"),
+    path.join(settings.swatchkitDir, "swatches"),
+    path.join(settings.swatchkitDir, "swatches", "hello"),
     settings.cssDir,
     path.join(settings.cssDir, "global"),
+    path.join(settings.cssDir, "swatches"),
   ];
 }
 
@@ -550,7 +567,26 @@ function copyDir(src, dest, force = false) {
   }
 }
 
-function scanSwatches(dir, scriptsCollector, exclude = []) {
+// Special filenames that SwatchKit reads and treats differently — not copied verbatim.
+const SWATCH_SPECIAL_FILES = new Set(["index.html", "description.html"]);
+
+// Recursively copy a swatch's assets (all files and subdirs except index.html,
+// description.html, and anything prefixed with _ or .) to destDir.
+function copySwatchAssets(srcDir, destDir) {
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copySwatchAssets(src, dest);
+    } else if (!SWATCH_SPECIAL_FILES.has(entry.name)) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+function scanSwatches(dir, destDir, exclude = []) {
   const swatches = [];
   if (!fs.existsSync(dir)) return swatches;
 
@@ -583,23 +619,14 @@ function scanSwatches(dir, scriptsCollector, exclude = []) {
           description = fs.readFileSync(descriptionFile, "utf-8");
         }
 
-        // Find all .js files
-        const jsFiles = fs
-          .readdirSync(itemPath)
-          .filter((file) => file.endsWith(".js"));
-
-        jsFiles.forEach((jsFile) => {
-          const scriptContent = fs.readFileSync(
-            path.join(itemPath, jsFile),
-            "utf-8",
-          );
-          scriptsCollector.push(`
-/* --- Swatch: ${name} / File: ${jsFile} --- */
-(function() {
-${scriptContent}
-})();
-`);
-        });
+        // Copy all non-special files and subdirectories from the component
+        // folder into its preview output directory so index.html can reference
+        // them with relative paths (e.g. ./styles.css, ./script.js, ./img/).
+        // Files and directories prefixed with _ or . are skipped.
+        if (destDir) {
+          const swatchDestDir = path.join(destDir, item);
+          copySwatchAssets(itemPath, swatchDestDir);
+        }
       }
     }
     // Handle Single File
@@ -608,18 +635,6 @@ ${scriptContent}
       id = name;
       content = fs.readFileSync(itemPath, "utf-8");
     }
-    // Handle Loose JS Files (e.g. script.js in tokens/)
-    else if (item.endsWith(".js")) {
-      const scriptContent = fs.readFileSync(itemPath, "utf-8");
-      scriptsCollector.push(`
-/* --- File: ${item} --- */
-(function() {
-${scriptContent}
-})();
-`);
-      // Don't add to swatches list, just scripts
-      return;
-    }
 
     if (name && content) {
       swatches.push({ name, id, content, description: description || null });
@@ -668,7 +683,7 @@ function build(settings) {
   }
 
   // 3. Ensure dist directories exist
-  const distDirs = [settings.outDir, settings.distJsDir];
+  const distDirs = [settings.outDir];
   if (settings.cssCopy) distDirs.push(settings.distCssDir);
   distDirs.forEach((dir) => {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -701,9 +716,8 @@ function build(settings) {
     console.log(`Skipping CSS copy (cssCopy: false). CSS referenced at: ${settings.cssPath}`);
   }
 
-  // 4. Read swatches & JS
+  // 4. Read swatches
   console.log("Scanning HTML patterns (swatchkit/**/*.html)...");
-  const scripts = [];
   const sections = {}; // Map<SectionName, Array<Swatch>>
 
   if (fs.existsSync(settings.swatchkitDir)) {
@@ -723,7 +737,9 @@ function build(settings) {
           // It is a Section Container (e.g. "Utilities")
           const sectionName =
             item === "tokens" ? "Design Tokens" : toTitleCase(item);
-          const swatches = scanSwatches(itemPath, scripts, exclude);
+          // Pass the preview dest dir so extra files get copied alongside each swatch
+          const sectionDestDir = path.join(settings.distPreviewDir, item);
+          const swatches = scanSwatches(itemPath, sectionDestDir, exclude);
           // Tag each swatch with its section slug for preview paths
           swatches.forEach((s) => (s.sectionSlug = item));
           if (swatches.length > 0) {
@@ -749,24 +765,19 @@ function build(settings) {
       } else if (stat.isDirectory()) {
         const indexFile = path.join(itemPath, "index.html");
         if (fs.existsSync(indexFile)) {
-          // Component folder swatch at root
+          // Component folder swatch at root — copy extra files to preview dest
           const name = item;
           const content = fs.readFileSync(indexFile, "utf-8");
-          rootSwatches.push({ name, id: name, content, sectionSlug: null });
-
-          // Collect JS
-          const jsFiles = fs
-            .readdirSync(itemPath)
-            .filter((f) => f.endsWith(".js"));
-          jsFiles.forEach((jsFile) => {
-            const scriptContent = fs.readFileSync(
-              path.join(itemPath, jsFile),
-              "utf-8",
-            );
-            scripts.push(
-              `/* ${name}/${jsFile} */ (function(){${scriptContent}})();`,
-            );
-          });
+          const descriptionFile = path.join(itemPath, "description.html");
+          const description = fs.existsSync(descriptionFile)
+            ? fs.readFileSync(descriptionFile, "utf-8")
+            : null;
+
+          // Copy extra files into preview/id/
+          const swatchDestDir = path.join(settings.distPreviewDir, name);
+          copySwatchAssets(itemPath, swatchDestDir);
+
+          rootSwatches.push({ name, id: name, content, description, sectionSlug: null });
         }
       }
     });
@@ -810,11 +821,13 @@ function build(settings) {
           .replace(/"/g, "&quot;")
           .replace(/'/g, "&#039;");
 
-        // Build preview path: preview/{section}/{name}.html or preview/{name}.html
+        // Build preview path: preview/{section}/{id}/ or preview/{id}/
+        // Each swatch is a directory with its own index.html so sibling assets
+        // (css, js, images, etc.) can be referenced with relative paths.
         const previewPath = p.sectionSlug
-          ? `preview/${p.sectionSlug}/${p.id}.html`
-          : `preview/${p.id}.html`;
-        const previewLink = previewPath.replace(/\.html$/, '');
+          ? `preview/${p.sectionSlug}/${p.id}/`
+          : `preview/${p.id}/`;
+        const previewLink = previewPath;
 
         return `
       <section id="${p.id}" class="region flow">
@@ -832,23 +845,9 @@ function build(settings) {
       .join("\n");
   });
 
-  // 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) {
-    console.log(
-      `Bundled ${scripts.length} swatch scripts to ${settings.outputJsFile}`,
-    );
-  }
-
-  // 7. Generate preview pages (standalone full-screen view of each swatch)
+  // 6. Generate preview pages (standalone full-screen view of each swatch)
+  // Each swatch gets its own directory: preview/{section}/{id}/index.html
+  // This allows index.html to reference sibling assets with relative paths.
   let previewLayoutContent;
   if (fs.existsSync(settings.projectPreviewLayout)) {
     previewLayoutContent = fs.readFileSync(
@@ -867,32 +866,25 @@ function build(settings) {
     sortedKeys.forEach((section) => {
       const swatches = sections[section];
       swatches.forEach((p) => {
-        // 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;
+        // Each swatch is output as a directory with index.html inside.
+        // preview/{section}/{id}/index.html  — depth: 3 levels from outDir
+        // preview/{id}/index.html            — depth: 2 levels from outDir
+        let swatchDir, 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 = "../../" + settings.cssPath; // preview/section/file.html -> ../../ + cssPath
+          swatchDir = path.join(settings.distPreviewDir, p.sectionSlug, p.id);
+          cssPath = "../../../" + settings.cssPath; // preview/section/id/index.html -> ../../../ + cssPath
         } else {
-          if (!fs.existsSync(settings.distPreviewDir))
-            fs.mkdirSync(settings.distPreviewDir, { recursive: true });
-          previewFile = path.join(settings.distPreviewDir, `${p.id}.html`);
-          cssPath = "../" + settings.cssPath; // preview/file.html -> ../ + cssPath
+          swatchDir = path.join(settings.distPreviewDir, p.id);
+          cssPath = "../../" + settings.cssPath; // preview/id/index.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 ? "../../" : "../";
+        if (!fs.existsSync(swatchDir)) fs.mkdirSync(swatchDir, { recursive: true });
+        const previewFile = path.join(swatchDir, "index.html");
 
         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);

package/package.json

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

package/src/blueprints/main.css

@@ -2,18 +2,15 @@
  * SwatchKit Main Stylesheet
  *
  * This is your app's CSS entry point. It imports design tokens, reset,
- * global styles, and compositions. Edit freely — this file is yours.
- * Note: swatchkit init --force will overwrite blueprint files (with .bak backups).
+ * global styles, compositions, utilities, and component swatches.
+ * Edit freely — this file is yours.
+ *
+ * Note: swatchkit scaffold --force will overwrite blueprint files (with .bak backups).
  * The only truly auto-generated files are css/global/tokens.css and
  * css/utilities/tokens.css — do not edit those manually.
  */
 
-/* 
- * Import Global Styles (Reset, Tokens, Variables, Elements) 
- * 
- * NOTE: Some global styles (variables & elements) are DISABLED by default.
- * You must open `css/global/index.css` to verify variable names and enable them.
- */
+/* Import global styles (reset, tokens, variables, elements) */
 @import "global/index.css";
 
 /* Import layout compositions */
@@ -22,6 +19,9 @@
 /* Import utilities */
 @import "utilities/index.css";
 
+/* Import swatches (component styles) */
+@import "swatches/index.css";
+
 /* === Your App Styles === */
 
 /* Add your component styles below */

package/src/blueprints/swatches/hello.css

@@ -0,0 +1,11 @@
+/* === Hello Swatch ===
+ *
+ * Styles for the hello swatch (swatchkit/swatches/hello/).
+ * Replace or delete this file once you have real components to document.
+ */
+
+.hello-swatch {
+  font-family: var(--font-base, sans-serif);
+  font-size: var(--size-step-0, 1rem);
+  color: var(--color-primary, currentColor);
+}

package/src/blueprints/swatches/index.css

@@ -0,0 +1,7 @@
+/* === Swatches ===
+ *
+ * Component styles for your swatches. Add a CSS file per component
+ * and import it here.
+ */
+
+@import "hello.css";

package/src/generators/index.js

@@ -8,6 +8,39 @@
 const fs = require('fs');
 const path = require('path');
 
+// Inline script that resolves CSS custom property values and annotates
+// .token-value elements with their computed value (e.g. "(#3b82f6)").
+// Included directly in any generated HTML fragment that uses .token-value
+// so the fragment is self-contained and doesn't depend on a shared bundle.
+const TOKEN_DISPLAY_SCRIPT = `<script>
+(function() {
+  var elements = document.querySelectorAll('.token-value');
+  if (!elements.length) return;
+  elements.forEach(function(el) {
+    var prop = el.getAttribute('data-var');
+    var computed = getComputedStyle(el).getPropertyValue(prop).trim();
+    if (computed) {
+      el.innerHTML += ' <span style="opacity:0.5;font-family:monospace;font-size:0.8em">(' + computed + ')</span>';
+    } else {
+      var temp = document.createElement('div');
+      temp.style.fontSize = '16px';
+      temp.style.lineHeight = 'var(' + prop + ')';
+      document.body.appendChild(temp);
+      var computedPx = getComputedStyle(temp).lineHeight;
+      document.body.removeChild(temp);
+      var displayValue = computedPx;
+      if (computedPx.endsWith('px')) {
+        var ratio = Math.round((parseFloat(computedPx) / 16) * 100) / 100;
+        displayValue = String(ratio);
+      }
+      if (displayValue) {
+        el.innerHTML += ' <span style="opacity:0.5;font-family:monospace;font-size:0.8em">(' + displayValue + ')</span>';
+      }
+    }
+  });
+})();
+</script>`;
+
 /**
  * Read and parse a JSON token file
  */
@@ -113,7 +146,8 @@ function generateTypography(tokensDir) {
 </style>
 <div class="type-ladder">
 ${steps}
-</div>`;
+</div>
+${TOKEN_DISPLAY_SCRIPT}`;
 }
 
 /**
@@ -233,7 +267,8 @@ function generateFonts(tokensDir) {
 
   return `<div class="font-stack">
 ${stacks}
-</div>`;
+</div>
+${TOKEN_DISPLAY_SCRIPT}`;
 }
 
 /**
@@ -294,7 +329,8 @@ ${leadings}
     color: #666;
     margin-left: 0.5rem;
   }
-</style>`;
+</style>
+${TOKEN_DISPLAY_SCRIPT}`;
 }
 
 /**

package/src/layout.html

@@ -20,6 +20,5 @@
         <!-- SWATCHES -->
       </main>
     </div>
-    <script src="js/swatches.js"></script>
   </body>
 </html>

package/src/preview-layout.html

@@ -9,6 +9,5 @@
   </head>
   <body class="wrapper region">
     <!-- PREVIEW_CONTENT -->
-    <script src="<!-- JS_PATH -->js/swatches.js"></script>
   </body>
 </html>

package/src/templates/hello/README.md

@@ -0,0 +1,83 @@
+# Hello Swatch
+
+This is your first swatch. It lives at `swatchkit/swatches/hello/`.
+
+## How swatch folders work
+
+SwatchKit treats every folder inside `swatchkit/` that contains an `index.html`
+as a swatch. The `index.html` is rendered inside a preview iframe in the pattern
+library. It is an HTML fragment — no `<html>`, `<head>`, or `<body>` needed, since
+SwatchKit wraps it in a full page automatically.
+
+## Sibling files are copied alongside
+
+Every file in this folder **other than** `index.html` and `description.html` is
+copied into the build output next to the preview page. That means your `index.html`
+can reference sibling files using relative paths:
+
+```html
+<link rel="stylesheet" href="./styles.css">
+<script src="./script.js"></script>
+<img src="./demo-image.png" alt="">
+```
+
+This makes each swatch self-contained. Drop in whatever assets the demo needs.
+
+## description.html
+
+If you add a `description.html` file to this folder, its contents will be
+displayed above the iframe in the pattern library UI — useful for documenting
+usage notes, props, or design decisions.
+
+## Global CSS
+
+Component styles that belong in your real app's stylesheet (not just the demo)
+live in `css/swatches/`. The `hello.css` file there is imported into `main.css`
+via `css/swatches/index.css`. Add new component CSS files to that folder and
+import them from `css/swatches/index.css`.
+
+## Opting out with underscores
+
+Prefix any file or folder with `_` to exclude it from the build entirely —
+it won't be rendered as a swatch and won't be copied to the output.
+
+This works at every level:
+
+- `swatchkit/swatches/_wip/` — entire swatch folder ignored
+- `swatchkit/_drafts/` — entire section folder ignored
+- `swatchkit/swatches/hello/_notes.md` — single file inside a swatch, not copied
+- `swatchkit/swatches/hello/_fixtures/` — subdirectory inside a swatch, not copied
+
+This is useful for work-in-progress components, private notes, test fixtures,
+or any file that should live alongside a swatch but never appear in the output.
+
+## A note on CSS isolation
+
+SwatchKit does not scope or isolate CSS between swatches. Every preview page
+loads the same global stylesheet (`main.css` and everything it imports), so
+styles defined in `css/swatches/hello.css` are active on *every* swatch's
+preview page — not just this one.
+
+This means `button { background: red }` in one swatch's CSS will affect the
+`<button>` elements in every other swatch. If two swatches both style `button`
+differently, the cascade determines which wins.
+
+The fix is to scope your styles with a component-specific class:
+
+```css
+/* Instead of this: */
+button { background: red; }
+
+/* Do this: */
+.hello-swatch button { background: red; }
+```
+
+The same applies to sibling CSS files (`./styles.css` next to `index.html`) —
+they load per-page on top of the global stylesheet, so unscoped rules will
+still bleed into any swatch that shares the same elements.
+
+## This README
+
+This file (`README.md`) is ignored by SwatchKit's UI — it is just for you and
+your team. It gets copied into the build output alongside `index.html`, but it
+is not rendered anywhere in the pattern library.

package/src/templates/hello/index.html

@@ -0,0 +1 @@
+<p class="hello-swatch">Hello from SwatchKit! Edit <code>swatchkit/swatches/hello/index.html</code> to get started.</p>

package/src/templates/script.js

@@ -1,15 +1,12 @@
-// Token Value Display Script
+// Token Value Display Script (reference copy — not used directly by the build)
 //
 // Shows the computed (resolved) value of CSS custom properties next to each
 // .token-value element in the token documentation pages. For example, a color
 // token swatch might display "(#3b82f6)" beside the variable name.
 //
-// How it reaches the browser:
-//   1. `swatchkit init` copies this file to swatchkit/tokens/script.js
-//   2. The build scans section directories for loose .js files, collects them
-//      (along with any component-folder scripts), wraps each in an IIFE, and
-//      concatenates them into dist/swatchkit/js/swatches.js
-//   3. The layout templates include a <script> tag pointing to js/swatches.js
+// The minified version of this logic is inlined directly into the HTML fragments
+// generated by src/generators/index.js (TOKEN_DISPLAY_SCRIPT constant), so each
+// token swatch page is fully self-contained with no external script dependency.
 
 const elements = document.querySelectorAll('.token-value');
 if (elements.length > 0) {