swatchkit 1.1.0 → 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.0",
+  "version": "2.0.0",
   "description": "A lightweight tool for creating HTML pattern libraries.",
   "main": "build.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "files": [
     "build.js",
-    "src/layout.html"
+    "src/"
   ],
   "scripts": {
     "start": "node build.js",

package/src/blueprints/colors.json

@@ -0,0 +1,11 @@
+{
+  "title": "Colors",
+  "description": "Hex color codes that can be shared, cross-platform. They can be converted at point of usage, such as HSL for web or CMYK for print.",
+  "items": [
+    { "name": "color-dark", "value": "#1a2420" },
+    { "name": "color-dark-glare", "value": "#2d3830" },
+    { "name": "color-mid", "value": "#8a9a8e" },
+    { "name": "color-light", "value": "#f8faf7" },
+    { "name": "color-primary", "value": "#e07a5f" }
+  ]
+}

package/src/blueprints/compositions/cluster.css

@@ -0,0 +1,20 @@
+/*
+  CLUSTER
+  Distributes items with consistent spacing, regardless of their size.
+
+  Credit: Adapted from Every Layout (The Cluster)
+  Docs:   https://every-layout.dev/layouts/cluster/
+
+  CUSTOM PROPERTIES:
+  --gutter: Space between items (default: --space-m)
+  --cluster-horizontal-alignment: Horizontal alignment (default: flex-start)
+  --cluster-vertical-alignment: Vertical alignment (default: center)
+*/
+
+.cluster {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gutter, var(--space-m));
+  justify-content: var(--cluster-horizontal-alignment, flex-start);
+  align-items: var(--cluster-vertical-alignment, center);
+}

package/src/blueprints/compositions/flow.css

@@ -0,0 +1,10 @@
+/* 
+  FLOW
+  Adds vertical rhythm between direct siblings.
+  
+  Credit: Adapted from Every Layout (The Stack)
+  Docs:   https://every-layout.dev/layouts/stack/
+*/
+.flow > * + * {
+  margin-block-start: var(--flow-space, 1em);
+}

package/src/blueprints/compositions/grid.css

@@ -0,0 +1,36 @@
+/**
+ * Auto Grid Swatch
+ *
+ * A flexible layout that creates an auto-filling grid with configurable item sizes.
+ * Implements the "RAM" (Repeat, Auto, Minmax) pattern to adapt without media queries.
+ *
+ * Related: https://every-layout.dev/layouts/grid/
+ *
+ * Usage: <div class="grid">...</div>
+ */
+
+.grid {
+  /*
+   * --gutter: Space between items
+   * --grid-min-item-size: Minimum width of an item before wrapping
+   * --grid-placement: auto-fill (default) or auto-fit
+   */
+  display: grid;
+  grid-template-columns: repeat(
+    var(--grid-placement, auto-fill),
+    minmax(var(--grid-min-item-size, 16rem), 1fr)
+  );
+  gap: var(--gutter, var(--space-l));
+}
+
+/* A split 50/50 layout */
+.grid[data-layout="50-50"] {
+  --grid-placement: auto-fit;
+  --grid-min-item-size: clamp(16rem, 50vw, 33rem);
+}
+
+/* Three column grid layout */
+.grid[data-layout="thirds"] {
+  --grid-placement: auto-fit;
+  --grid-min-item-size: clamp(16rem, 33%, 20rem);
+}

package/src/blueprints/compositions/index.css

@@ -0,0 +1,12 @@
+/* === CSS Compositions === */
+
+/* Layout primitives based on CUBE CSS / Every Layout */
+
+@import "flow.css";
+@import "sidebar.css";
+@import "wrapper.css";
+@import "cluster.css";
+@import "repel.css";
+@import "switcher.css";
+@import "prose.css";
+@import "grid.css";

package/src/blueprints/compositions/prose.css

@@ -0,0 +1,89 @@
+/**
+ * Prose Swatch
+ * 
+ * A CUBE CSS "Block" designed to optimize the reading experience for long-form content.
+ * It manages spacing, line length, and typography for a comfortable rhythm.
+ * 
+ * Usage: <article class="prose flow">...</article>
+ */
+
+.prose {
+  /* Increase flow spacing for better reading rhythm */
+  --flow-space: var(--space-l);
+}
+
+/**
+ * Prevent large headings from breaking layout on small screens.
+ * hyphenation and break-word handling ensures text wraps gracefully.
+ */
+.prose :is(h1, h2, h3) {
+  overflow-wrap: anywhere;
+  hyphens: auto;
+}
+
+/**
+ * Constrain line length for optimal readability (measure).
+ * text-wrap: pretty prevents orphans and awkward breaks.
+ */
+.prose :is(p, li, dl, figcaption, blockquote) {
+  max-width: 60ch;
+  text-wrap: pretty;
+}
+
+/**
+ * Reduce spacing after headings to visually group them with their content.
+ */
+.prose :is(h1, h2, h3, h4) + *:not([class]) {
+  --flow-space: var(--space-m);
+}
+
+/**
+ * Add more breathing room around heavy elements like figures and tables.
+ */
+.prose :is(figure, table),
+.prose :is(figure, table) + * {
+  --flow-space: var(--space-2xl);
+}
+
+/**
+ * Add extra space before headings to clearly separate sections.
+ */
+.prose * + :is(h1, h2, h3, h4):not([class]) {
+  --flow-space: var(--space-xl);
+}
+
+/**
+ * Tighter spacing for list items to keep lists cohesive.
+ */
+.prose :is(ul, ol):not([class]) li + li,
+.prose :is(ul, ol):not([class]) li > :is(ol, ul) {
+  --flow-space: var(--space-xs);
+}
+
+/**
+ * Horizontal rules act as major section breaks, so give them plenty of space.
+ */
+.prose hr {
+  --flow-space: var(--space-2xl);
+}
+
+/**
+ * Add a border to media elements to prevent them from blending into the background,
+ * especially in light mode.
+ */
+.prose :is(img, picture, video) {
+  border: var(--stroke-solid);
+}
+
+/**
+ * On larger screens, relax the aggressive wrapping rules for headings.
+ * 47.5em matches 760px, the default 'viewport-mid' token. 
+ * Preferring em here to catch the case where a user adjusts their browser default font size.
+ * Note: CSS variables cannot be used in media queries in standard CSS.
+ */
+@media (min-width: 47.5em) {
+  .prose :is(h1, h2, h3) {
+    overflow-wrap: unset;
+    hyphens: unset;
+  }
+}

package/src/blueprints/compositions/repel.css

@@ -0,0 +1,23 @@
+/*
+  REPEL
+  Pushes items away from each other where space allows, stacking on small viewports.
+
+  Credit: Adapted from Every Layout (The Cluster)
+  Docs:   https://every-layout.dev/layouts/cluster/
+
+  CUSTOM PROPERTIES:
+  --gutter: Space between items (default: --space-m)
+  --repel-vertical-alignment: Vertical alignment (default: center)
+*/
+
+.repel {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  align-items: var(--repel-vertical-alignment, center);
+  gap: var(--gutter, var(--space-m));
+}
+
+.repel[data-nowrap] {
+  flex-wrap: nowrap;
+}

package/src/blueprints/compositions/sidebar.css

@@ -0,0 +1,44 @@
+/* 
+  SIDEBAR
+  Layout with a flexible main content area and a fixed-width sidebar.
+  
+  Credit: Adapted from Every Layout (The Sidebar)
+  Docs:   https://every-layout.dev/layouts/sidebar/
+
+  CUSTOM PROPERTIES:
+  --gutter: Space between sidebar and content (default: --space-s-l)
+  --sidebar-target-width: Target width of sidebar (default: 20rem)
+  --sidebar-content-min-width: Min width of content before stacking (default: 50%)
+*/
+
+.sidebar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gutter, var(--space-s-l));
+}
+
+.sidebar:not([data-direction]) > :first-child {
+  flex-basis: var(--sidebar-target-width, 20rem);
+  flex-grow: 1;
+}
+
+.sidebar:not([data-direction]) > :last-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-width: var(--sidebar-content-min-width, 50%);
+}
+
+.sidebar[data-reversed] {
+  flex-direction: row-reverse;
+}
+
+.sidebar[data-direction="rtl"] > :last-child {
+  flex-basis: var(--sidebar-target-width, 20rem);
+  flex-grow: 1;
+}
+
+.sidebar[data-direction="rtl"] > :first-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-width: var(--sidebar-content-min-width, 50%);
+}

package/src/blueprints/compositions/switcher.css

@@ -0,0 +1,32 @@
+/*
+  SWITCHER
+  Lays out items horizontally until there is insufficient space, then stacks them.
+  Optimized for 3 items.
+
+  Credit: Adapted from Every Layout (The Switcher)
+  Docs:   https://every-layout.dev/layouts/switcher/
+
+  CUSTOM PROPERTIES:
+  --gutter: Space between items (default: --space-l)
+  --switcher-target-container-width: Container breakpoint width (default: 40rem)
+  --switcher-vertical-alignment: Vertical alignment (default: flex-start)
+*/
+
+.switcher {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gutter, var(--space-l));
+  align-items: var(--switcher-vertical-alignment, flex-start);
+}
+
+.switcher > * {
+  flex-grow: 1;
+  flex-basis: calc(
+    (var(--switcher-target-container-width, 40rem) - 100%) * 999
+  );
+}
+
+/* Max 3 items, so anything greater than 3 is full width */
+.switcher > :nth-child(n + 4) {
+  flex-basis: 100%;
+}

package/src/blueprints/compositions/wrapper.css

@@ -0,0 +1,14 @@
+/* 
+  WRAPPER
+  
+  Credit: More or less, adapted from Every Layout (The Center)
+  Docs:   https://every-layout.dev/layouts/center/
+*/
+
+.wrapper {
+  margin-inline: auto;
+  max-inline-size: var(--wrapper-max-width, 1360px);
+  padding-inline-start: var(--gutter);
+  padding-inline-end: var(--gutter);
+  position: relative;
+}

package/src/blueprints/fonts.json

@@ -0,0 +1,24 @@
+{
+  "title": "Fonts",
+  "description": "Each array of fonts creates a priority-based order. The first font in the array should be the ideal font, followed by sensible, web-safe fallbacks",
+  "items": [
+    {
+      "name": "font-base",
+      "description": "System fonts for body copy and globally set text.",
+      "value": [
+        "Satoshi",
+        "Inter",
+        "Segoe UI",
+        "Roboto",
+        "Helvetica Neue",
+        "Arial",
+        "sans-serif"
+      ]
+    },
+    {
+      "name": "font-mono",
+      "description": "Monospace font for code samples etc",
+      "value": ["DM Mono", "monospace"]
+    }
+  ]
+}