swatchkit 1.0.0 → 1.1.0

package/build.js

@@ -222,7 +222,7 @@ function buildInitManifest(settings) {
   }
 
   // Template files (swatchkit/tokens/)
-  const templateFiles = ["prose.html", "script.js"];
+  const templateFiles = ["prose.html"];
   for (const file of templateFiles) {
     manifest.push({
       src: path.join(templatesDir, file),
@@ -231,6 +231,26 @@ function buildInitManifest(settings) {
     });
   }
 
+  // Utility and composition display templates — walk each subfolder
+  for (const section of ["utilities", "compositions"]) {
+    const sectionSrc = path.join(templatesDir, section);
+    if (!fs.existsSync(sectionSrc)) continue;
+    const folders = fs.readdirSync(sectionSrc).filter(f =>
+      fs.statSync(path.join(sectionSrc, f)).isDirectory()
+    );
+    for (const folder of folders) {
+      const folderSrc = path.join(sectionSrc, folder);
+      const files = fs.readdirSync(folderSrc).filter(f => f.endsWith(".html"));
+      for (const file of files) {
+        manifest.push({
+          src: path.join(folderSrc, file),
+          dest: path.join(settings.swatchkitDir, section, folder, file),
+          transform: (content) => content.trim(),
+        });
+      }
+    }
+  }
+
   // CSS entry point
   manifest.push({
     src: path.join(blueprintsDir, "main.css"),
@@ -279,6 +299,8 @@ function getInitDirs(settings) {
     settings.swatchkitDir,
     settings.tokensDir,
     path.join(settings.swatchkitDir, "tokens"),
+    path.join(settings.swatchkitDir, "utilities"),
+    path.join(settings.swatchkitDir, "compositions"),
     settings.cssDir,
     path.join(settings.cssDir, "global"),
   ];
@@ -350,17 +372,15 @@ function reportInitStatus(settings) {
 
 // --- 5. New Command Logic ---
 function generateConfig(cssDir) {
-  const isDefaultCssDir = cssDir === './src/css';
   return `// swatchkit.config.js
 module.exports = {
   // Where your CSS lives. SwatchKit scaffolds blueprints here and reads
   // tokens from here when building the pattern library.
   cssDir: "${cssDir}",
 
-  // Set to true if SwatchKit should copy your CSS into its output directory,
-  // making the pattern library self-contained. Set to false if a build tool
-  // (Vite, Astro, Eleventy, etc.) is already handling your CSS.
-  cssCopy: ${isDefaultCssDir ? 'false' : 'true'},
+  // Set to false if a build tool (Vite, Astro, Eleventy, etc.) is already
+  // handling your CSS and you don't need SwatchKit to copy it.
+  cssCopy: true,
 
   // Where token JSON files live.
   // tokensDir: "./tokens",
@@ -491,6 +511,23 @@ function runInit(settings, options) {
       path.join(settings.cssDir, "utilities"),
     );
   }
+
+  const cwd2 = process.cwd();
+  const tokensDir = path.relative(cwd2, settings.tokensDir);
+  console.log(`
+Done! Here's what to do next:
+
+  1. Edit your design tokens in ${tokensDir}/
+       colors.json        — your colour palette
+       text-sizes.json    — fluid type scale
+       spacing.json       — fluid spacing scale
+       fonts.json         — font stacks
+       text-weights.json  — font weights
+
+  2. Run "swatchkit" to build the pattern library
+
+  3. Open dist/swatchkit/index.html to view it
+`);
 }
 
 // --- 6. Build Logic ---
@@ -529,7 +566,7 @@ function scanSwatches(dir, scriptsCollector, exclude = []) {
     const itemPath = path.join(dir, item);
     const stat = fs.statSync(itemPath);
 
-    let name, content, id;
+    let name, content, id, description;
 
     // Handle Component Directory
     if (stat.isDirectory()) {
@@ -540,6 +577,12 @@ function scanSwatches(dir, scriptsCollector, exclude = []) {
         id = item;
         content = fs.readFileSync(indexFile, "utf-8");
 
+        // Optional description shown above the iframe in the main UI
+        const descriptionFile = path.join(itemPath, "description.html");
+        if (fs.existsSync(descriptionFile)) {
+          description = fs.readFileSync(descriptionFile, "utf-8");
+        }
+
         // Find all .js files
         const jsFiles = fs
           .readdirSync(itemPath)
@@ -579,7 +622,7 @@ ${scriptContent}
     }
 
     if (name && content) {
-      swatches.push({ name, id, content });
+      swatches.push({ name, id, content, description: description || null });
     }
   });
 
@@ -776,6 +819,7 @@ function build(settings) {
         return `
       <section id="${p.id}" class="region flow">
         <h2>${p.name} <small style="font-weight: normal; opacity: 0.6; font-size: 0.7em">(${section})</small></h2>
+        ${p.description ? `<div class="swatch-description">${p.description}</div>` : ''}
         <iframe src="${previewPath}" style="width: 100%; border: var(--stroke); min-height: 25rem; resize: vertical; overflow: auto;"></iframe>
         <div class="swatchkit-preview-link"><a href="${previewLink}">View full screen</a></div>
         <details>
@@ -789,13 +833,19 @@ function build(settings) {
   });
 
   // 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) {
-    fs.writeFileSync(settings.outputJsFile, scripts.join("\n"));
     console.log(
-      `Bundled ${scripts.length} scripts to ${settings.outputJsFile}`,
+      `Bundled ${scripts.length} swatch scripts to ${settings.outputJsFile}`,
     );
-  } else {
-    fs.writeFileSync(settings.outputJsFile, "// No swatch scripts found");
   }
 
   // 7. Generate preview pages (standalone full-screen view of each swatch)

package/package.json

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