swatchkit 0.0.6 → 0.0.8

package/README.md

@@ -16,10 +16,23 @@ npx swatchkit init
 npx swatchkit
 ```
 
-This will:
-1.  Create a `swatches/` folder.
-2.  Scaffold a complete **Design System** in `src/tokens/` (Colors, Fluid Type, Spacing).
-3.  Build your site to `public/swatchkit/`.
+This will create:
+
+```
+my-project/
+├── css/
+│   ├── tokens.css          # Generated design tokens (CSS custom properties)
+│   └── styles.css          # Starter stylesheet (imports tokens.css)
+├── swatches/
+│   ├── _layout.html        # Layout template (you own this)
+│   └── tokens/             # Token definitions + documentation patterns
+│       ├── colors.json
+│       ├── colors.html
+│       └── ...
+└── public/
+    └── swatchkit/          # Built pattern library
+        └── index.html
+```
 
 ---
 
@@ -47,7 +60,7 @@ By default, SwatchKit looks for a `swatches/` folder in your project root.
 *   **Component Folder:** Drop a folder like `swatches/carousel/` containing `index.html`. It works the same way.
 
 ### 2. Design Token Engine
-SwatchKit scaffolds a powerful, CUBE CSS-friendly design system for you. Edit the JSON files in `src/tokens/`, and SwatchKit auto-generates `src/css/tokens.css`.
+SwatchKit scaffolds a design system for you. Edit the JSON files in `swatches/tokens/`, and SwatchKit auto-generates `css/tokens.css`.
 
 **Supported Tokens:**
 *   **Colors** (`colors.json`): Generates palettes.
@@ -56,18 +69,85 @@ SwatchKit scaffolds a powerful, CUBE CSS-friendly design system for you. Edit th
 *   **Modular Leading** (`text-leading.json`): Generates line-heights using `pow()` modular scales.
 *   **Fonts & Weights**: Manages font families and weights.
 
-Docs for these are automatically created in `swatches/tokens/*.html`.
+Documentation patterns for these are automatically created alongside the JSON files.
+
+### 3. Intelligent Fluid Logic (New!)
+
+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).
+
+**Example (`swatches/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)
+  ]
+}
+```
+
+**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);
+}
+```
+
+### 4. Hybrid Text Leading
+
+You can mix modular scales with manual overrides.
 
-### 3. Custom Layouts
+**Example (`swatches/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)
+  ]
+}
+```
+
+### 5. CSS Workflow
+
+SwatchKit generates `css/tokens.css` with your design tokens as CSS custom properties. The starter `css/styles.css` imports this file:
+
+```css
+@import 'tokens.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.
+
+### 6. Custom Layouts
 When you run `swatchkit init`, we create `swatches/_layout.html`.
 **You own this file.**
-*   Add your own `<link rel="stylesheet" href="/css/app.css">`.
+*   Link to your own stylesheets.
 *   Add custom fonts, scripts, or meta tags.
 *   Change the HTML structure, logo, or classes.
 
-SwatchKit simply injects the content into the `<!-- PATTERNS -->`, `<!-- SIDEBAR_LINKS -->`, and `<!-- HEAD_EXTRAS -->` placeholders.
+SwatchKit injects content into the `<!-- PATTERNS -->`, `<!-- SIDEBAR_LINKS -->`, and `<!-- HEAD_EXTRAS -->` placeholders.
 
-### 4. JavaScript Bundling
+### 7. JavaScript Bundling
 If your component needs client-side JS:
 1.  Create a folder: `swatches/carousel/`.
 2.  Add `index.html` (Markup).
@@ -100,15 +180,22 @@ Optional. Create `swatchkit.config.js` in your root for persistent settings.
 ```javascript
 module.exports = {
   // Override default pattern directory
-  input: './src/patterns',
+  input: './patterns',
 
   // Override default output directory
-  outDir: './dist/docs',
+  outDir: './dist/patterns',
+  
+  // Override CSS directory
+  css: './assets/css',
+  
+  // Exclude files (supports glob patterns)
+  exclude: ['*.test.js', 'temp*'],
   
-  // Override Token Defaults
+  // Override token settings
   tokens: {
+    input: './design-tokens',    // Where token JSON files live
     leading: {
-      ratio: 1.25, // Change modular scale ratio
+      ratio: 1.25,               // Modular scale ratio
       base: 1
     }
   }

package/build.js

@@ -66,6 +66,27 @@ function loadConfig(configPath) {
   return {};
 }
 
+// --- 2.5 Glob Matching Helper ---
+function matchesPattern(filename, pattern) {
+  // Simple wildcard support
+  if (pattern.includes("*")) {
+    const parts = pattern.split("*");
+    // Handle "foo*"
+    if (pattern.endsWith("*") && !pattern.startsWith("*")) {
+        return filename.startsWith(parts[0]);
+    }
+    // Handle "*bar"
+    if (pattern.startsWith("*") && !pattern.endsWith("*")) {
+        return filename.endsWith(parts[1]);
+    }
+    // Handle "*bar*"
+    if (pattern.startsWith("*") && pattern.endsWith("*")) {
+        return filename.includes(parts[1]);
+    }
+  }
+  return filename === pattern;
+}
+
 // --- 3. Smart Defaults & Path Resolution ---
 function resolveSettings(cliOptions, fileConfig) {
   const cwd = process.cwd();
@@ -97,12 +118,27 @@ function resolveSettings(cliOptions, fileConfig) {
       ? path.resolve(cwd, fileConfig.outDir)
       : path.join(cwd, "public/swatchkit");
 
-  const cssDir = path.join(cwd, "src/css");
+  // CSS directory - where tokens.css and user's styles.css live
+  // Default: css/ at project root (not src/css/)
+  const cssDir = fileConfig.css
+    ? path.resolve(cwd, fileConfig.css)
+    : path.join(cwd, "css");
+
+  // Token definitions directory
+  // Default: swatches/tokens/ (not src/tokens/)
+  const tokensDir = fileConfig.tokens?.input
+    ? path.resolve(cwd, fileConfig.tokens.input)
+    : path.join(patternsDir, "tokens");
+  
+  // Exclude patterns
+  const exclude = fileConfig.exclude || [];
 
   return {
     patternsDir,
     outDir,
     cssDir,
+    tokensDir,
+    exclude,
     fileConfig, // Expose config to init
     // Internal layout template (relative to this script)
     internalLayout: path.join(__dirname, "src/layout.html"),
@@ -116,6 +152,7 @@ function resolveSettings(cliOptions, fileConfig) {
     outputFile: path.join(outDir, "index.html"),
     outputJsFile: path.join(outDir, "js/patterns.js"),
     tokensCssFile: path.join(cssDir, "tokens.css"),
+    stylesCssFile: path.join(cssDir, "styles.css"),
   };
 }
 
@@ -129,27 +166,26 @@ function runInit(settings, options) {
     fs.mkdirSync(settings.patternsDir, { recursive: true });
   }
 
-  // Create patterns/tokens directory
-  const patternsTokensDir = path.join(settings.patternsDir, "tokens");
-  if (!fs.existsSync(patternsTokensDir)) {
-    console.log(`Creating patterns/tokens directory: ${patternsTokensDir}`);
-    fs.mkdirSync(patternsTokensDir, { recursive: true });
-  }
-
-  // Create src/tokens directory and sample colors.json
-  const tokensDir = path.join(process.cwd(), "src/tokens");
+  // Create swatches/tokens directory (for both JSON definitions and HTML patterns)
+  const tokensDir = settings.tokensDir;
   if (!fs.existsSync(tokensDir)) {
     console.log(`Creating tokens directory: ${tokensDir}`);
     fs.mkdirSync(tokensDir, { recursive: true });
   }
 
+  // Create css/ directory at project root
+  if (!fs.existsSync(settings.cssDir)) {
+    console.log(`Creating CSS directory: ${settings.cssDir}`);
+    fs.mkdirSync(settings.cssDir, { recursive: true });
+  }
+
   const copyDefault = (srcFilename, destFilename) => {
     const destPath = path.join(tokensDir, destFilename);
     if (!fs.existsSync(destPath)) {
       const srcPath = path.join(__dirname, 'src/blueprints', srcFilename);
       const content = fs.readFileSync(srcPath, 'utf-8');
       fs.writeFileSync(destPath, content);
-      console.log(`Created sample tokens file at ${destPath}`);
+      console.log(`Created token file at ${destPath}`);
     }
   };
 
@@ -188,12 +224,12 @@ function runInit(settings, options) {
   copyDefault('fonts.json', 'fonts.json');
 
   const copyTemplate = (srcFilename, destFilename) => {
-    const destPath = path.join(patternsTokensDir, destFilename);
+    const destPath = path.join(tokensDir, destFilename);
     if (!fs.existsSync(destPath)) {
       const srcPath = path.join(__dirname, 'src/templates', srcFilename);
       const content = fs.readFileSync(srcPath, 'utf-8');
       fs.writeFileSync(destPath, content.trim());
-      console.log(`Created sample pattern at ${destPath}`);
+      console.log(`Created pattern at ${destPath}`);
     }
   };
 
@@ -206,7 +242,7 @@ function runInit(settings, options) {
   copyTemplate('fonts.html', 'fonts.html');
 
   // Create shared script for tokens
-  const tokensScriptFile = path.join(patternsTokensDir, "script.js");
+  const tokensScriptFile = path.join(tokensDir, "script.js");
   if (!fs.existsSync(tokensScriptFile)) {
     const srcPath = path.join(__dirname, 'src/templates/script.js');
     const content = fs.readFileSync(srcPath, 'utf-8');
@@ -214,8 +250,16 @@ function runInit(settings, options) {
     console.log(`Created tokens script at ${tokensScriptFile}`);
   }
 
-  // Generate initial CSS
-  processTokens(process.cwd(), settings.cssDir);
+  // Create starter styles.css
+  if (!fs.existsSync(settings.stylesCssFile)) {
+    const srcPath = path.join(__dirname, 'src/blueprints/styles.css');
+    const content = fs.readFileSync(srcPath, 'utf-8');
+    fs.writeFileSync(settings.stylesCssFile, content);
+    console.log(`Created starter stylesheet at ${settings.stylesCssFile}`);
+  }
+
+  // Generate initial tokens.css
+  processTokens(settings.tokensDir, settings.cssDir);
 
   const targetLayout = settings.projectLayout;
 
@@ -245,8 +289,10 @@ function scanDirectory(dir, scriptsCollector, exclude = []) {
   const items = fs.readdirSync(dir);
 
   items.forEach((item) => {
-    // Skip excluded items, _layout.html, or hidden files
-    if (exclude.includes(item)) return;
+    // Skip excluded items
+    if (exclude.some(pattern => matchesPattern(item, pattern))) return;
+
+    // Skip _layout.html or hidden files
     if (item.startsWith("_") || item.startsWith(".")) return;
 
     const itemPath = path.join(dir, item);
@@ -329,7 +375,7 @@ function build(settings) {
   });
 
   // 2.5 Process Tokens
-  processTokens(process.cwd(), settings.cssDir);
+  processTokens(settings.tokensDir, settings.cssDir);
 
   // 3. Copy CSS files
   if (fs.existsSync(settings.cssDir)) {
@@ -353,8 +399,9 @@ function build(settings) {
   const tokensDir = path.join(settings.patternsDir, "tokens");
   const tokenPages = scanDirectory(tokensDir, scripts);
 
-  // Pass 2: Patterns (in [patternsDir], excluding 'tokens')
-  const patternPages = scanDirectory(settings.patternsDir, scripts, ["tokens"]);
+  // Pass 2: Patterns (in [patternsDir], excluding 'tokens' and user excludes)
+  const userExcludes = settings.exclude || [];
+  const patternPages = scanDirectory(settings.patternsDir, scripts, ["tokens", ...userExcludes]);
 
   // Combine for content generation (Tokens first, then Patterns)
   const allPatterns = [...tokenPages, ...patternPages];
@@ -418,11 +465,8 @@ function build(settings) {
     layoutContent = fs.readFileSync(settings.internalLayout, "utf-8");
   }
 
-  let headExtras = "";
-  // Check if the tokens file exists in the *output* directory (where we copied it to)
-  if (fs.existsSync(settings.distTokensCssFile)) {
-    headExtras = '<link rel="stylesheet" href="css/tokens.css">';
-  }
+  // HEAD_EXTRAS placeholder available for future use (e.g., custom fonts)
+  const headExtras = "";
 
   const finalHtml = layoutContent
     .replace("<!-- SIDEBAR_LINKS -->", sidebarLinks)

package/package.json

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

package/src/layout.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>SwatchKit</title>
-    <link rel="stylesheet" href="/css/global.css" />
+    <link rel="stylesheet" href="css/styles.css" />
     <!-- HEAD_EXTRAS -->
     <style>
         body {