swatchkit 0.0.5 → 0.0.7

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,35 @@ 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. 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';
 
-### 3. Custom Layouts
+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.
+
+### 4. 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
+### 5. JavaScript Bundling
 If your component needs client-side JS:
 1.  Create a folder: `swatches/carousel/`.
 2.  Add `index.html` (Markup).
@@ -100,15 +130,19 @@ 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',
   
-  // 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

@@ -97,12 +97,23 @@ 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");
 
   return {
     patternsDir,
     outDir,
     cssDir,
+    tokensDir,
     fileConfig, // Expose config to init
     // Internal layout template (relative to this script)
     internalLayout: path.join(__dirname, "src/layout.html"),
@@ -116,6 +127,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 +141,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 +199,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 +217,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 +225,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;
 
@@ -329,7 +348,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)) {
@@ -418,11 +437,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.5",
+  "version": "0.0.7",
   "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 {