swatchkit 1.0.1 → 1.1.1

package/build.js

@@ -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"),
   ];
@@ -544,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()) {
@@ -555,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)
@@ -594,7 +622,7 @@ ${scriptContent}
     }
 
     if (name && content) {
-      swatches.push({ name, id, content });
+      swatches.push({ name, id, content, description: description || null });
     }
   });
 
@@ -791,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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swatchkit",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "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"]
+    }
+  ]
+}