swatchkit 0.0.12 → 0.0.13

package/README.md

@@ -21,8 +21,10 @@ This will create:
 ```
 my-project/
 ├── css/
-│   ├── tokens.css          # Generated design tokens (CSS custom properties)
-│   └── styles.css          # Starter stylesheet (imports tokens.css)
+│   ├── compositions/       # Layout primitives (flow, sidebar, etc.)
+│   ├── tokens.css          # Generated design tokens
+│   ├── styles.css          # Starter stylesheet (imports tokens + compositions)
+│   └── swatchkit-ui.css    # UI styles for the documentation sidebar
 ├── swatchkit/
 │   ├── _layout.html        # Layout template (you own this)
 │   └── tokens/             # Token definitions + documentation patterns
@@ -55,6 +57,7 @@ Then add it to your `package.json` scripts:
 ## Features
 
 ### 1. The Magic Folder & Project Structure
+
 By default, SwatchKit looks for a `swatchkit/` folder in your project root.
 
 **Organize by Folder:**
@@ -74,19 +77,21 @@ swatchkit/
     └── flow.html
 ```
 
-*   **Files at root:** Go to the "Patterns" section.
-*   **Subfolders:** Create a new section (e.g. `utilities/` -> "Utilities").
-*   **Tokens:** Special folder for JSON definitions.
+- **Files at root:** Go to the "Patterns" section.
+- **Subfolders:** Create a new section (e.g. `utilities/` -> "Utilities").
+- **Tokens:** Special folder for JSON definitions.
 
 ### 2. Design Token Engine
+
 SwatchKit scaffolds a design system for you. Edit the JSON files in `swatchkit/tokens/`, and SwatchKit auto-generates `css/tokens.css`.
 
 **Supported Tokens:**
-*   **Colors** (`colors.json`): Generates palettes.
-*   **Fluid Typography** (`text-sizes.json`): Generates `clamp()` based type scales using Utopia methodology.
-*   **Fluid Spacing** (`spacing.json`): Generates `clamp()` based spacing.
-*   **Modular Leading** (`text-leading.json`): Generates line-heights using `pow()` modular scales.
-*   **Fonts & Weights**: Manages font families and weights.
+
+- **Colors** (`colors.json`): Generates palettes.
+- **Fluid Typography** (`text-sizes.json`): Generates `clamp()` based type scales using Utopia methodology.
+- **Fluid Spacing** (`spacing.json`): Generates `clamp()` based spacing.
+- **Modular Leading** (`text-leading.json`): Generates line-heights using `pow()` modular scales.
+- **Fonts & Weights**: Manages font families and weights.
 
 Documentation patterns for these are automatically created alongside the JSON files.
 
@@ -95,33 +100,36 @@ Documentation patterns for these are automatically created alongside the JSON fi
 SwatchKit can auto-calculate fluid typography and spacing scales.
 
 **Static vs Fluid:**
-*   **Static:** Provide a `value` (e.g. `"16px"`).
-*   **Fluid:** Provide `min` and `max` (e.g. `16` and `18`).
-*   **Auto-Fluid:** Provide just ONE side (`min` or `max`), and SwatchKit calculates the other using a default ratio (1.125).
+
+- **Static:** Provide a `value` (e.g. `"16px"`).
+- **Fluid:** Provide `min` and `max` (e.g. `16` and `18`).
+- **Auto-Fluid:** Provide just ONE side (`min` or `max`), and SwatchKit calculates the other using a default ratio (1.125).
 
 **Example (`swatchkit/tokens/text-sizes.json`):**
+
 ```json
 {
   "title": "Text Sizes",
   "fluidRatio": 1.25,
   "items": [
-    { "name": "base", "value": "1rem" },        // Static: 1rem always
-    { "name": "md", "min": 16, "max": 20 },     // Fluid: 16px -> 20px
-    { "name": "lg", "max": 24 },                // Auto: 19.2px -> 24px (24 / 1.25)
-    { "name": "xl", "min": 32 },                // Auto: 32px -> 40px (32 * 1.25)
+    { "name": "base", "value": "1rem" }, // Static: 1rem always
+    { "name": "md", "min": 16, "max": 20 }, // Fluid: 16px -> 20px
+    { "name": "lg", "max": 24 }, // Auto: 19.2px -> 24px (24 / 1.25)
+    { "name": "xl", "min": 32 }, // Auto: 32px -> 40px (32 * 1.25)
     { "name": "jumbo", "max": 64, "fluidRatio": 1.5 } // Auto: 42.6px -> 64px (64 / 1.5)
   ]
 }
 ```
 
 **Generated CSS:**
+
 ```css
 :root {
   --s-base: 1rem;
-  --s-md: clamp(1rem, ... , 1.25rem);
-  --s-lg: clamp(1.2rem, ... , 1.5rem);
-  --s-xl: clamp(2rem, ... , 2.5rem);
-  --s-jumbo: clamp(2.66rem, ... , 4rem);
+  --s-md: clamp(1rem, ..., 1.25rem);
+  --s-lg: clamp(1.2rem, ..., 1.5rem);
+  --s-xl: clamp(2rem, ..., 2.5rem);
+  --s-jumbo: clamp(2.66rem, ..., 4rem);
 }
 ```
 
@@ -130,49 +138,56 @@ SwatchKit can auto-calculate fluid typography and spacing scales.
 You can mix modular scales with manual overrides.
 
 **Example (`swatchkit/tokens/text-leading.json`):**
+
 ```json
 {
   "base": 1,
   "ratio": 1.2,
   "items": [
-    { "name": "tight", "step": -1 },   // Modular: 1 * (1.2 ^ -1)
-    { "name": "flat", "value": 1 },    // Manual: 1
-    { "name": "loose", "step": 1 }     // Modular: 1 * (1.2 ^ 1)
+    { "name": "tight", "step": -1 }, // Modular: 1 * (1.2 ^ -1)
+    { "name": "flat", "value": 1 }, // Manual: 1
+    { "name": "loose", "step": 1 } // Modular: 1 * (1.2 ^ 1)
   ]
 }
 ```
 
 ### 5. CSS Workflow
 
-SwatchKit generates `css/tokens.css` with your design tokens as CSS custom properties. The starter `css/styles.css` imports this file:
+SwatchKit generates `css/tokens.css` with your design tokens. The starter `css/styles.css` imports this file along with layout primitives:
 
 ```css
 @import 'tokens.css';
+@import 'compositions/index.css';
 
 body {
   font-family: var(--font-base);
   color: var(--color-dark);
 }
-
-/* Add your app styles here */
 ```
 
-The pattern library uses **your stylesheet**, so components render exactly as they will in your app.
+The pattern library uses **your stylesheet** (`styles.css`), so components render exactly as they will in your app.
+
+**Documentation Styling:**
+The sidebar and documentation layout are styled by `css/swatchkit-ui.css`. This file is separate from your app styles so you can customize the docs UI without affecting your production CSS.
 
 ### 6. Custom Layouts
+
 When you run `swatchkit init`, we create `swatchkit/_layout.html`.
 **You own this file.**
-*   Link to your own stylesheets.
-*   Add custom fonts, scripts, or meta tags.
-*   Change the HTML structure, logo, or classes.
+
+- Link to your own stylesheets.
+- Add custom fonts, scripts, or meta tags.
+- Change the HTML structure, logo, or classes.
 
 SwatchKit injects content into the `<!-- PATTERNS -->`, `<!-- SIDEBAR_LINKS -->`, and `<!-- HEAD_EXTRAS -->` placeholders.
 
 ### 7. JavaScript Bundling
+
 If your component needs client-side JS:
-1.  Create a folder: `swatchkit/carousel/`.
-2.  Add `index.html` (Markup).
-3.  Add `script.js` (Logic).
+
+1. Create a folder: `swatchkit/carousel/`.
+2. Add `index.html` (Markup).
+3. Add `script.js` (Logic).
 
 SwatchKit automatically bundles your JS files, wraps them in a safety scope (IIFE), and injects them into the final build.
 
@@ -183,33 +198,40 @@ swatchkit [command] [options]
 ```
 
 ### Commands
-*   `swatchkit` (Default): Builds the library.
-*   `swatchkit init`: Scaffolds the layout and token files.
+
+- `swatchkit` (Default): Builds the library.
+- `swatchkit init`: Scaffolds the layout and token files.
 
 ### Flags
-| Flag | Short | Description |
-| :--- | :--- | :--- |
-| `--watch` | `-w` | Watch files and rebuild on change. |
-| `--config` | `-c` | Path to config file. |
-| `--input` | `-i` | Pattern directory (Default: `swatchkit/`). |
-| `--outDir` | `-o` | Output directory (Default: `public/swatchkit`). |
-| `--force` | `-f` | Overwrite layout file during init. |
+
+| Flag       | Short | Description                                     |
+| :--------- | :---- | :---------------------------------------------- |
+| `--watch`  | `-w`  | Watch files and rebuild on change.              |
+| `--config` | `-c`  | Path to config file.                            |
+| `--input`  | `-i`  | Pattern directory (Default: `swatchkit/`).      |
+| `--outDir` | `-o`  | Output directory (Default: `public/swatchkit`). |
+| `--force`  | `-f`  | Overwrite layout file during init.              |
 
 ## Configuration
+
 Optional. Create `swatchkit.config.js` in your root for persistent settings.
 
 ```javascript
 module.exports = {
   // Override default pattern directory
-  input: './patterns',
+  input: "./patterns",
 
   // Override default output directory
-  outDir: './dist/patterns',
-  
+  outDir: "./dist/patterns",
+
   // Override CSS directory
-  css: './assets/css',
-  
+  css: "./assets/css",
+
   // Exclude files (supports glob patterns)
-  exclude: ['*.test.js', 'temp*']
+  exclude: ["*.test.js", "temp*"],
 };
 ```
+
+## Acknowledgements
+
+The CSS compositions included by default in SwatchKit are adapted from [Every Layout](https://every-layout.dev/) by Heydon Pickering and Andy Bell. Highly recommend their documentation for a deep dive into their brilliant CSS techniques.

package/build.js

@@ -243,6 +243,21 @@ function runInit(settings, options) {
     console.log(`Created starter stylesheet at ${settings.stylesCssFile}`);
   }
 
+  // Copy Compositions
+  const compositionsSrc = path.join(__dirname, 'src/blueprints/compositions');
+  const compositionsDest = path.join(settings.cssDir, 'compositions');
+  if (fs.existsSync(compositionsSrc)) {
+      copyDir(compositionsSrc, compositionsDest);
+  }
+
+  // Copy SwatchKit UI Styles
+  const uiSrc = path.join(__dirname, 'src/blueprints/swatchkit-ui.css');
+  const uiDest = path.join(settings.cssDir, 'swatchkit-ui.css');
+  if (fs.existsSync(uiSrc) && !fs.existsSync(uiDest)) {
+    fs.copyFileSync(uiSrc, uiDest);
+    console.log(`Created UI styles at ${uiDest}`);
+  }
+
   // Generate initial tokens.css
   processTokens(settings.tokensDir, settings.cssDir);
 
@@ -267,6 +282,25 @@ function runInit(settings, options) {
 }
 
 // --- 5. Build Logic ---
+function copyDir(src, dest, force = false) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, force);
+    } else {
+      if (force || !fs.existsSync(destPath)) {
+        fs.copyFileSync(srcPath, destPath);
+        if (!force) console.log(`Created file at ${destPath}`);
+      }
+    }
+  }
+}
+
 function scanSwatches(dir, scriptsCollector, exclude = []) {
   const swatches = [];
   if (!fs.existsSync(dir)) return swatches;
@@ -362,18 +396,10 @@ function build(settings) {
   // 2.5 Process Tokens
   processTokens(settings.tokensDir, settings.cssDir);
 
-  // 3. Copy CSS files
+  // 3. Copy CSS files (recursively)
   if (fs.existsSync(settings.cssDir)) {
     console.log("Copying CSS...");
-    const cssFiles = fs
-      .readdirSync(settings.cssDir)
-      .filter((file) => file.endsWith(".css"));
-    cssFiles.forEach((file) => {
-      fs.copyFileSync(
-        path.join(settings.cssDir, file),
-        path.join(settings.distCssDir, file),
-      );
-    });
+    copyDir(settings.cssDir, settings.distCssDir, true);
   }
 
   // 4. Read swatches & JS

package/package.json

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

package/src/layout.html

@@ -1,90 +1,26 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>SwatchKit</title>
     <link rel="stylesheet" href="css/styles.css" />
+    <link rel="stylesheet" href="css/swatchkit-ui.css" />
     <!-- HEAD_EXTRAS -->
-    <style>
-        body {
-            display: flex;
-            margin: 0;
-            min-height: 100vh;
-            font-family: system-ui, -apple-system, sans-serif;
-        }
-        aside {
-            width: 250px;
-            background-color: #f7f7f7;
-            border-right: 1px solid #e5e5e5;
-            padding: 2rem 1.5rem;
-            flex-shrink: 0;
-            height: 100vh;
-            position: sticky;
-            top: 0;
-            overflow-y: auto;
-        }
-        aside h2 {
-            margin-top: 0;
-            font-size: 1.25rem;
-            margin-bottom: 1.5rem;
-        }
-        aside nav {
-            display: flex;
-            flex-direction: column;
-            gap: 0.75rem;
-        }
-        aside nav a {
-            text-decoration: none;
-            color: #333;
-        }
-        aside nav a:hover {
-            color: #000;
-            text-decoration: underline;
-        }
-        main {
-            flex: 1;
-            padding: 3rem;
-            max-width: 1200px;
-        }
-        section {
-            margin-bottom: 4rem;
-            border-bottom: 1px solid #eee;
-            padding-bottom: 2rem;
-        }
-        section h2 {
-            margin-top: 0;
-            font-size: 1.5rem;
-            margin-bottom: 1rem;
-        }
-        .preview {
-            border: 1px solid #e5e5e5;
-            padding: 2rem;
-            border-radius: 4px;
-            background: white;
-            margin-bottom: 1.5rem;
-        }
-        pre {
-            background: #2d2d2d;
-            color: #fff;
-            padding: 1rem;
-            border-radius: 4px;
-            overflow-x: auto;
-        }
-    </style>
-</head>
-<body>
-    <aside>
+  </head>
+  <body>
+    <div class="sidebar">
+      <nav class="swatchkit-nav flow">
         <header>
             <h2>SwatchKit</h2>
         </header>
-        <nav>
-            <!-- SIDEBAR_LINKS -->
-        </nav>
-    </aside>
-    <main>
+        <!-- SIDEBAR_LINKS -->
+      </nav>
+      <main class="swatchkit-main flow">
         <!-- SWATCHES -->
-    </main>
+      </main>
+    </div>
     <script src="js/swatches.js"></script>
-</body>
-</html>
+  </body>
+</html>
+