swatchkit 0.0.18 → 0.0.20

package/README.md

@@ -20,16 +20,21 @@ This will create:
 
 ```
 my-project/
+├── tokens/                 # Design token definitions (you edit these)
+│   ├── colors.json
+│   ├── fonts.json
+│   ├── spacing.json
+│   └── ...
 ├── css/
 │   ├── compositions/       # Layout primitives (flow, sidebar, etc.)
-│   ├── tokens.css          # Generated design tokens
+│   ├── tokens.css          # Generated from tokens/*.json
 │   ├── 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
-│       ├── colors.json
+│   └── tokens/             # Visual documentation for design tokens
 │       ├── colors.html
+│       ├── typography.html
 │       └── ...
 └── public/
     └── swatchkit/          # Built pattern library
@@ -65,8 +70,9 @@ SwatchKit automatically turns subfolders into sections in the documentation side
 
 ```
 swatchkit/
-├── tokens/              # Section: "Design Tokens"
-│   └── colors.json
+├── tokens/              # Section: "Design Tokens" (visual previews)
+│   ├── colors.html
+│   └── typography.html
 ├── components/          # Section: "Components"
 │   ├── button.html
 │   └── card/
@@ -79,11 +85,10 @@ swatchkit/
 
 - **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`.
+SwatchKit scaffolds a design system for you. Edit the JSON files in `tokens/`, and SwatchKit auto-generates `css/tokens.css`.
 
 **Supported Tokens:**
 
@@ -93,7 +98,7 @@ SwatchKit scaffolds a design system for you. Edit the JSON files in `swatchkit/t
 - **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.
+Visual documentation patterns for these tokens live in `swatchkit/tokens/` and are created during init.
 
 ### 3. Intelligent Fluid Logic (New!)
 
@@ -105,7 +110,7 @@ SwatchKit can auto-calculate fluid typography and spacing scales.
 - **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`):**
+**Example (`tokens/text-sizes.json`):**
 
 ```json
 {
@@ -137,7 +142,7 @@ SwatchKit can auto-calculate fluid typography and spacing scales.
 
 You can mix modular scales with manual overrides.
 
-**Example (`swatchkit/tokens/text-leading.json`):**
+**Example (`tokens/text-leading.json`):**
 
 ```json
 {
@@ -225,7 +230,10 @@ module.exports = {
   outDir: "./dist/patterns",
 
   // Override CSS directory
-  css: "./assets/css",
+  cssDir: "./assets/css",
+
+  // Override tokens directory (JSON token definitions)
+  tokensDir: "./src/tokens",
 
   // Exclude files (supports glob patterns)
   exclude: ["*.test.js", "temp*"],

package/build.js

@@ -117,16 +117,16 @@ function resolveSettings(cliOptions, fileConfig) {
       : path.join(cwd, "public/swatchkit");
 
   // 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)
+  // Default: css/ at project root
+  const cssDir = fileConfig.cssDir
+    ? path.resolve(cwd, fileConfig.cssDir)
     : 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(swatchkitDir, "tokens");
+  // Token definitions directory (JSON files the user edits)
+  // Default: tokens/ at project root (separate from swatchkit/ UI)
+  const tokensDir = fileConfig.tokensDir
+    ? path.resolve(cwd, fileConfig.tokensDir)
+    : path.join(cwd, "tokens");
 
   // Exclude patterns
   const exclude = fileConfig.exclude || [];
@@ -164,19 +164,27 @@ function runInit(settings, options) {
     fs.mkdirSync(settings.swatchkitDir, { recursive: true });
   }
 
-  // Create swatches/tokens directory (for both JSON definitions and HTML patterns)
+  // Create tokens/ directory at project root (JSON token definitions)
   const tokensDir = settings.tokensDir;
   if (!fs.existsSync(tokensDir)) {
     console.log(`Creating tokens directory: ${tokensDir}`);
     fs.mkdirSync(tokensDir, { recursive: true });
   }
 
+  // Create swatchkit/tokens/ directory (HTML/JS visual previews)
+  const tokensUiDir = path.join(settings.swatchkitDir, "tokens");
+  if (!fs.existsSync(tokensUiDir)) {
+    console.log(`Creating tokens UI directory: ${tokensUiDir}`);
+    fs.mkdirSync(tokensUiDir, { 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 });
   }
 
+  // Copy JSON token blueprints to tokens/ (project root)
   const copyDefault = (srcFilename, destFilename) => {
     const destPath = path.join(tokensDir, destFilename);
     if (!fs.existsSync(destPath)) {
@@ -187,29 +195,17 @@ function runInit(settings, options) {
     }
   };
 
-  // 1. Create Colors Token
   copyDefault("colors.json", "colors.json");
-
-  // 2. Create Text Weights Token
   copyDefault("text-weights.json", "text-weights.json");
-
-  // 3. Create Text Leading Token
   copyDefault("text-leading.json", "text-leading.json");
-
-  // 4. Create Viewports Token
   copyDefault("viewports.json", "viewports.json");
-
-  // 5. Create Text Sizes Token (Fluid)
   copyDefault("text-sizes.json", "text-sizes.json");
-
-  // 6. Create Spacing Token
   copyDefault("spacing.json", "spacing.json");
-
-  // 7. Create Fonts Token
   copyDefault("fonts.json", "fonts.json");
 
+  // Copy HTML/JS template patterns to swatchkit/tokens/ (UI documentation)
   const copyTemplate = (srcFilename, destFilename) => {
-    const destPath = path.join(tokensDir, destFilename);
+    const destPath = path.join(tokensUiDir, destFilename);
     if (!fs.existsSync(destPath)) {
       const srcPath = path.join(__dirname, "src/templates", srcFilename);
       const content = fs.readFileSync(srcPath, "utf-8");
@@ -218,7 +214,6 @@ function runInit(settings, options) {
     }
   };
 
-  // Create sample patterns
   copyTemplate("colors.html", "colors.html");
   copyTemplate("text-weights.html", "text-weights.html");
   copyTemplate("text-leading.html", "text-leading.html");
@@ -226,8 +221,8 @@ function runInit(settings, options) {
   copyTemplate("spacing.html", "spacing.html");
   copyTemplate("fonts.html", "fonts.html");
 
-  // Create shared script for tokens
-  const tokensScriptFile = path.join(tokensDir, "script.js");
+  // Create shared script for tokens UI
+  const tokensScriptFile = path.join(tokensUiDir, "script.js");
   if (!fs.existsSync(tokensScriptFile)) {
     const srcPath = path.join(__dirname, "src/templates/script.js");
     const content = fs.readFileSync(srcPath, "utf-8");

package/package.json

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