swatchkit 1.1.0 → 1.1.1

package/src/blueprints/global/variables.css

@@ -0,0 +1,58 @@
+/**
+ * SwatchKit Variables
+ *
+ * Utility custom properties that extend your design tokens.
+ * These provide consistent values for layouts, interactions, and UI details.
+ * This file is yours to edit — add your own variables here freely.
+ *
+ * Variable references use the default token names from tokens/*.json.
+ * If you have renamed any tokens, update the var() references below to match.
+ *
+ * Based on Andy Bell's Complete CSS course methodology.
+ */
+
+:root {
+  /**
+   * Gutter: Used by all layout compositions for consistent spacing.
+   * Assigns a fluid spacing token so gutters scale with viewport.
+   */
+  --gutter: var(--space-m-l);
+
+  /**
+   * Measure: Maximum line length for optimal readability.
+   * 65 characters is widely considered ideal for body text.
+   */
+  --measure: 65ch;
+
+  /**
+   * Transitions: Specific timing for different interaction types.
+   * Movement should be snappy and linear; fades need time to be visible;
+   * bounce adds playful emphasis for special interactions.
+   */
+  --transition-base: 250ms ease;
+  --transition-movement: 200ms linear;
+  --transition-fade: 300ms ease;
+  --transition-bounce: 500ms cubic-bezier(0.5, 0.05, 0.2, 1.5);
+
+  /**
+   * Strokes: Consistent border values throughout the UI.
+   * Having both dashed and solid variants covers most use cases.
+   */
+  --stroke-width: 1px;
+  --stroke: var(--stroke-width) dashed var(--color-mid);
+  --stroke-solid: var(--stroke-width) solid var(--color-mid);
+
+  /**
+   * Border Radius: Using rem (not em) prevents radius from varying
+   * based on element font-size, keeping corners consistent site-wide.
+   */
+  --radius-s: 0.2rem;
+  --radius-m: 0.75rem;
+  --radius-l: 2.5rem;
+
+  /**
+   * Uppercase Kerning: Uppercase text looks squished without extra
+   * letter-spacing. This variable fixes that consistently site-wide.
+   */
+  --uppercase-kerning: 0.04ch;
+}

package/src/blueprints/main.css

@@ -0,0 +1,27 @@
+/**
+ * SwatchKit Main Stylesheet
+ *
+ * This is your app's CSS entry point. It imports design tokens, reset,
+ * global styles, and compositions. Edit freely — this file is yours.
+ * Note: swatchkit init --force will overwrite blueprint files (with .bak backups).
+ * The only truly auto-generated files are css/global/tokens.css and
+ * css/utilities/tokens.css — do not edit those manually.
+ */
+
+/* 
+ * Import Global Styles (Reset, Tokens, Variables, Elements) 
+ * 
+ * NOTE: Some global styles (variables & elements) are DISABLED by default.
+ * You must open `css/global/index.css` to verify variable names and enable them.
+ */
+@import "global/index.css";
+
+/* Import layout compositions */
+@import "compositions/index.css";
+
+/* Import utilities */
+@import "utilities/index.css";
+
+/* === Your App Styles === */
+
+/* Add your component styles below */

package/src/blueprints/spacing.json

@@ -0,0 +1,19 @@
+{
+  "title": "Spacing",
+  "description": "Consistent spacing sizes, based on a ratio, with min and max sizes. This allows you to set spacing based on the context size. For example, min for mobile and max for desktop browsers.",
+  "items": [
+    { "name": "space-xs", "min": 7, "max": 8 },
+    { "name": "space-s", "min": 14, "max": 16 },
+    { "name": "space-m", "min": 21, "max": 24 },
+    { "name": "space-l", "min": 35, "max": 40 },
+    { "name": "space-xl", "min": 49, "max": 56 },
+    { "name": "space-2xl", "min": 56, "max": 64 },
+    { "name": "space-3xl", "min": 70, "max": 80 },
+    { "name": "space-4xl", "min": 105, "max": 120 },
+    { "name": "space-s-l", "min": 14, "max": 40 },
+    { "name": "space-xs-l", "min": 7, "max": 40 },
+    { "name": "space-m-l", "min": 21, "max": 40 },
+    { "name": "space-s-m", "min": 14, "max": 24 },
+    { "name": "space-2xl-4xl", "min": 56, "max": 120 }
+  ]
+}

package/src/blueprints/swatchkit-ui.css

@@ -0,0 +1,79 @@
+/* SwatchKit UI Styles */
+
+:root {
+  /* trigger intrinsic sizing by invalidating the flex-basis value */
+  --sidebar-target-width: -1rem;
+  --sidebar-content-min-width: 66%;
+}
+
+body {
+  margin: 0;
+}
+
+/* nav { */
+/*   /* TODO: consider a utility class here */
+*/
+/*   padding-block-start: var(--space-l); */
+/*   outline: 2px solid var(--color-dark-glare); */
+/*   background-color: var(--color-mid); */
+/* } */
+
+main {
+  /* TODO: consider a utility class here */
+  padding-block-start: var(--space-l);
+}
+
+/* Sidebar Navigation */
+/* .swatchkit-nav { */
+/*   background-color: var(--color-light); */
+/*   border-right: 1px solid var(--color-mid); */
+/* } */
+
+.swatchkit-nav h2 {
+  font-size: var(--text-size-1, 1.25rem);
+  font-weight: var(--font-weight-bold, 700);
+  color: var(--color-dark);
+}
+
+.swatchkit-nav a {
+  display: block;
+  text-decoration: none;
+  color: var(--color-dark-glare, #333);
+  padding-block: var(--space-xs, 0.5rem);
+}
+
+.swatchkit-nav a:hover {
+  color: var(--color-primary);
+  text-decoration: underline;
+}
+
+/* Pattern Preview Blocks */
+.swatchkit-pattern {
+  margin-bottom: var(--space-2xl);
+  border-bottom: 1px solid var(--color-mid);
+  padding-bottom: var(--space-l);
+}
+
+.swatchkit-pattern h2 {
+  margin-top: 0;
+  font-size: var(--text-size-2, 1.5rem);
+  color: var(--color-dark);
+}
+
+.swatchkit-preview {
+  border: 1px solid var(--color-mid);
+  padding: var(--space-l);
+  border-radius: 4px;
+  background: var(--color-light);
+  margin-bottom: var(--space-m);
+}
+
+.swatchkit-code {
+  background: var(--color-dark);
+  color: var(--color-light);
+  padding: var(--space-m);
+  border-radius: 4px;
+  overflow-x: auto;
+  font-family: var(--font-mono, monospace);
+  font-size: 0.875rem;
+}

package/src/blueprints/text-leading.json

@@ -0,0 +1,13 @@
+{
+  "title": "Text Leading",
+  "description": "Modular scale for line-heights",
+  "base": 1,
+  "ratio": 1.2,
+  "items": [
+    { "name": "leading-micro", "step": -1 },
+    { "name": "leading-flat", "step": 0 },
+    { "name": "leading-fine", "step": 1 },
+    { "name": "leading-standard", "step": 2 },
+    { "name": "leading-loose", "step": 3 }
+  ]
+}

package/src/blueprints/text-sizes.json

@@ -0,0 +1,21 @@
+{
+  "title": "Text Sizes",
+  "description": "Fluid typography steps generated using Utopia clamp() methodology.",
+  "items": [
+    { "name": "step--2", "min": 11.85, "max": 12.5 },
+    { "name": "step--1", "min": 13.33, "max": 15 },
+    { "name": "step-0", "min": 15, "max": 18 },
+    { "name": "step-1", "min": 16.88, "max": 21.6 },
+    { "name": "step-2", "min": 18.98, "max": 25.92 },
+    { "name": "step-3", "min": 21.36, "max": 31.1 },
+    { "name": "step-4", "min": 24.03, "max": 37.32 },
+    { "name": "step-5", "min": 27.03, "max": 44.79 },
+    { "name": "step-6", "min": 30.41, "max": 53.75 },
+    { "name": "step-7", "min": 34.21, "max": 64.5 },
+    { "name": "step-8", "min": 38.49, "max": 77.4 },
+    { "name": "step-9", "min": 43.3, "max": 92.88 },
+    { "name": "step-10", "min": 48.5, "max": 111.45 },
+    { "name": "step-11", "min": 60.62, "max": 167.17 },
+    { "name": "step-12", "min": 60.62, "max": 230 }
+  ]
+}

package/src/blueprints/text-weights.json

@@ -0,0 +1,11 @@
+{
+  "title": "Text Weights",
+  "description": "Helper classes and custom properties for common font weights",
+  "meta": {},
+  "items": [
+    { "name": "weight-regular", "value": 400 },
+    { "name": "weight-medium", "value": 500 },
+    { "name": "weight-bold", "value": 700 },
+    { "name": "weight-black", "value": 900 }
+  ]
+}

package/src/blueprints/utilities/index.css

@@ -0,0 +1,9 @@
+/* === CSS Utilities === */
+
+/* Single-purpose helper classes */
+
+/* Auto-generated utility classes from your tokens */
+@import "tokens.css";
+
+@import "visually-hidden.css";
+@import "region.css";

package/src/blueprints/utilities/region.css

@@ -0,0 +1,12 @@
+/* 
+A container that provides consistent vertical spacing for
+chunks/sections/regions of content. Also a relative position container.
+*/
+
+.region {
+  padding-block: var(--region-space, var(--space-m));
+  position: relative;
+}
+
+.region[data-disable-space-top] {
+}

package/src/blueprints/utilities/visually-hidden.css

@@ -0,0 +1,18 @@
+/* 
+  Visually Hidden Utility
+
+  Hides content visually while keeping it accessible to assistive technologies
+  (like screen readers). Use this instead of `display: none` when you want
+  content to be available to users who rely on non-visual browsing.
+*/
+.visually-hidden {
+  border: 0;
+  clip: rect(0 0 0 0);
+  height: 0;
+  margin: 0;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  width: 1px;
+  white-space: nowrap;
+}

package/src/blueprints/viewports.json

@@ -0,0 +1,10 @@
+{
+  "title": "Viewports",
+  "description": "The min and maximum viewports used to generate fluid type and space scales.",
+  "items": [
+    { "name": "viewport-min", "value": 330 },
+    { "name": "viewport-mid", "value": 760 },
+    { "name": "viewport-large", "value": 940 },
+    { "name": "viewport-max", "value": 1350 }
+  ]
+}

package/src/generators/index.js

@@ -0,0 +1,401 @@
+/**
+ * Token HTML Generators
+ * 
+ * These functions read JSON token files and generate HTML
+ * for the SwatchKit UI that references the actual token names.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read and parse a JSON token file
+ */
+function readTokenFile(tokensDir, filename) {
+  const filePath = path.join(tokensDir, filename);
+  if (!fs.existsSync(filePath)) return null;
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`[SwatchKit] Error reading ${filename}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * Generate colors.html from colors.json
+ */
+function generateColors(tokensDir) {
+  const data = readTokenFile(tokensDir, 'colors.json');
+  if (!data || !data.items) return null;
+
+  const rows = data.items.map(item => {
+    const varName = `--${item.name}`;
+    return `      <tr>
+        <td>
+          <div style="display: flex; align-items: center; gap: 0.5rem; flex-wrap: nowrap;">
+            <div style="background: ${item.value}; width: 2rem; height: 2rem; border-radius: 4px; border: 1px solid rgba(0,0,0,0.1); flex-shrink: 0;" role="presentation"></div>
+            <strong>${item.name}</strong>
+          </div>
+        </td>
+        <td><code>${item.value}</code></td>
+        <td><code>var(${varName})</code></td>
+        <td><code>.color:${item.name}</code></td>
+        <td><code>.background-color:${item.name}</code></td>
+      </tr>`;
+  }).join('\n');
+
+  return `<style>
+  .color-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.9rem;
+  }
+  .color-table th,
+  .color-table td {
+    text-align: left;
+    padding: 0.5rem 0.75rem;
+    border-bottom: 1px solid #ddd;
+    vertical-align: middle;
+  }
+  .color-table th {
+    font-weight: bold;
+    background: #f5f5f5;
+  }
+  .color-table code {
+    font-family: monospace;
+  }
+</style>
+
+<table class="color-table">
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Hex code</th>
+      <th>Custom Property</th>
+      <th>Color Utility Class</th>
+      <th>BG Utility Class</th>
+    </tr>
+  </thead>
+  <tbody>
+${rows}
+  </tbody>
+</table>`;
+}
+
+/**
+ * Generate typography.html from text-sizes.json
+ */
+function generateTypography(tokensDir) {
+  const data = readTokenFile(tokensDir, 'text-sizes.json');
+  if (!data || !data.items) return null;
+
+  const steps = data.items.map(item => {
+    const varName = `--${item.name}`;
+    return `  <div style="font-size: var(${varName})">${item.name} <span class="token-value" data-var="${varName}"></span></div>`;
+  }).join('\n');
+
+  return `<style>
+  .type-ladder > * {
+    margin-bottom: 1.5rem;
+    line-height: 1.2;
+  }
+  .type-ladder .token-value {
+    display: block;
+    font-size: 0.875rem;
+    font-weight: normal;
+    color: #666;
+    margin-top: 0.25rem;
+    font-family: monospace;
+  }
+</style>
+<div class="type-ladder">
+${steps}
+</div>`;
+}
+
+/**
+ * Generate spacing.html from spacing.json
+ */
+function generateSpacing(tokensDir) {
+  const data = readTokenFile(tokensDir, 'spacing.json');
+  if (!data || !data.items) return null;
+
+  const scaleRows = data.items.map(item => {
+    const varName = `--${item.name}`;
+    const minVal = item.min !== undefined ? `${item.min}px` : (item.value || '—');
+    const maxVal = item.max !== undefined ? `${item.max}px` : (item.value || '—');
+    return `      <tr>
+        <td>
+          <div class="spacing-swatch" style="height: var(${varName});"></div>
+        </td>
+        <td><strong>${item.name}</strong></td>
+        <td><code>var(${varName})</code></td>
+        <td>${minVal}</td>
+        <td>${maxVal}</td>
+      </tr>`;
+  }).join('\n');
+
+  const usageRows = data.items.map(item => {
+    const slug = item.name;
+    return `      <tr>
+        <td><code>var(--${slug})</code></td>
+        <td><code>.padding-block:${slug}</code></td>
+        <td><code>.padding-inline:${slug}</code></td>
+        <td><code>.margin-block:${slug}</code></td>
+        <td><code>.flow-space:${slug}</code></td>
+        <td><code>.gutter:${slug}</code></td>
+        <td><code>.region-space:${slug}</code></td>
+      </tr>`;
+  }).join('\n');
+
+  return `<style>
+  .spacing-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.9rem;
+    margin-bottom: 2rem;
+  }
+  .spacing-table th,
+  .spacing-table td {
+    text-align: left;
+    padding: 0.5rem 0.75rem;
+    border-bottom: 1px solid #ddd;
+    vertical-align: middle;
+  }
+  .spacing-table th {
+    font-weight: bold;
+    background: #f5f5f5;
+  }
+  .spacing-table code {
+    font-family: monospace;
+  }
+  .spacing-swatch {
+    background: var(--color-primary, #666);
+    min-height: 4px;
+    width: 100%;
+    min-width: 4px;
+    border-radius: 2px;
+  }
+</style>
+
+<h2 style="font-family: monospace; margin-bottom: 0.5rem;">Scale</h2>
+<table class="spacing-table">
+  <thead>
+    <tr>
+      <th width="120px"></th>
+      <th>Name</th>
+      <th>Custom Property</th>
+      <th>Min</th>
+      <th>Max</th>
+    </tr>
+  </thead>
+  <tbody>
+${scaleRows}
+  </tbody>
+</table>
+
+<h2 style="font-family: monospace; margin-bottom: 0.5rem;">Usage</h2>
+<table class="spacing-table">
+  <thead>
+    <tr>
+      <th>Custom Property</th>
+      <th>Padding Block</th>
+      <th>Padding Inline</th>
+      <th>Margin Block</th>
+      <th>Flow Space</th>
+      <th>Gutter</th>
+      <th>Region Space</th>
+    </tr>
+  </thead>
+  <tbody>
+${usageRows}
+  </tbody>
+</table>`;
+}
+
+/**
+ * Generate fonts.html from fonts.json
+ */
+function generateFonts(tokensDir) {
+  const data = readTokenFile(tokensDir, 'fonts.json');
+  if (!data || !data.items) return null;
+
+  const stacks = data.items.map(item => {
+    const varName = `--${item.name}`;
+    return `  <div style="font-family: var(${varName}); margin-bottom: 2rem;">
+    <strong>${item.name}</strong> <code class="token-value" data-var="${varName}">var(${varName})</code>
+    <p>The quick brown fox jumps over the lazy dog.</p>
+  </div>`;
+  }).join('\n');
+
+  return `<div class="font-stack">
+${stacks}
+</div>`;
+}
+
+/**
+ * Generate text-weights.html from text-weights.json
+ */
+function generateTextWeights(tokensDir) {
+  const data = readTokenFile(tokensDir, 'text-weights.json');
+  if (!data || !data.items) return null;
+
+  const weights = data.items.map(item => {
+    const varName = `--${item.name}`;
+    return `  <div style="font-weight: var(${varName})">
+    ${item.name} (${item.value}) - The quick brown fox jumps over the lazy dog.
+  </div>`;
+  }).join('\n');
+
+  return `<div style="font-family: sans-serif; display: grid; gap: 1rem;">
+${weights}
+</div>`;
+}
+
+/**
+ * Generate text-leading.html from text-leading.json
+ */
+function generateTextLeading(tokensDir) {
+  const data = readTokenFile(tokensDir, 'text-leading.json');
+  if (!data || !data.items) return null;
+
+  const loremText = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.`;
+
+  const leadings = data.items.map(item => {
+    const varName = `--${item.name}`;
+    return `  <div style="line-height: var(${varName})">
+    <div class="meta">
+      <strong>${item.name}</strong>
+      <code>var(${varName})</code>
+      <span class="token-value" data-var="${varName}"></span>
+    </div>
+    <p>${loremText}</p>
+  </div>`;
+  }).join('\n\n');
+
+  return `<div class="flow">
+${leadings}
+</div>
+
+<style>
+  .meta {
+    font-family: monospace;
+    font-size: 0.85rem;
+    margin-bottom: 0.5rem;
+    background: #eee;
+    padding: 0.25rem 0.5rem;
+    display: inline-block;
+    border-radius: 4px;
+  }
+  .token-value {
+    color: #666;
+    margin-left: 0.5rem;
+  }
+</style>`;
+}
+
+/**
+ * Generate viewports.html from viewports.json
+ */
+function generateViewports(tokensDir) {
+  const data = readTokenFile(tokensDir, 'viewports.json');
+  if (!data || !data.items) return null;
+
+  const items = data.items.map(item => {
+    const varName = `--${item.name}`;
+    const displayValue = typeof item.value === 'number' ? `${item.value}px` : item.value;
+    const barWidth = typeof item.value === 'number' ? `${item.value}px` : '100%';
+    return `  <div class="viewport-item">
+    <div class="viewport-bar" style="width: ${barWidth}">
+      <span class="viewport-meta">
+        <strong>${item.name}</strong>
+        <code>var(${varName})</code>
+        <span class="viewport-value">${displayValue}</span>
+      </span>
+    </div>
+  </div>`;
+  }).join('\n');
+
+  return `<style>
+  .viewport-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    font-family: monospace;
+  }
+  .viewport-item {
+    display: flex;
+  }
+  .viewport-bar {
+    background: var(--color-primary, #666);
+    border-radius: 4px;
+    padding: 0.5rem 0.75rem;
+    min-width: max-content;
+    flex-shrink: 0;
+  }
+  .viewport-meta {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    font-size: 0.9rem;
+    color: var(--color-light, #fff);
+    white-space: nowrap;
+  }
+  .viewport-meta code {
+    opacity: 0.75;
+  }
+  .viewport-value {
+    font-weight: bold;
+    margin-left: auto;
+    padding-left: 2rem;
+  }
+</style>
+<div class="viewport-list">
+${items}
+</div>`;
+}
+
+/**
+ * Generate all token HTML files and write them to the tokens UI directory
+ */
+function generateTokenSwatches(tokensDir, tokensUiDir) {
+  const generators = [
+    { filename: 'colors.html', fn: generateColors },
+    { filename: 'typography.html', fn: generateTypography },
+    { filename: 'spacing.html', fn: generateSpacing },
+    { filename: 'fonts.html', fn: generateFonts },
+    { filename: 'text-weights.html', fn: generateTextWeights },
+    { filename: 'text-leading.html', fn: generateTextLeading },
+    { filename: 'viewports.html', fn: generateViewports },
+  ];
+
+  let generated = 0;
+
+  generators.forEach(({ filename, fn }) => {
+    const html = fn(tokensDir);
+    if (html) {
+      const destPath = path.join(tokensUiDir, filename);
+      const existing = fs.existsSync(destPath) ? fs.readFileSync(destPath, 'utf-8') : null;
+      if (existing !== html) {
+        fs.writeFileSync(destPath, html);
+        generated++;
+      }
+    }
+  });
+
+  return generated;
+}
+
+module.exports = {
+  generateColors,
+  generateTypography,
+  generateSpacing,
+  generateFonts,
+  generateTextWeights,
+  generateTextLeading,
+  generateViewports,
+  generateTokenSwatches,
+};