adevkit 0.1.0__py3-none-any.whl

devkit/skills/embedded/design-system/references/tailwind-integration.md

@@ -0,0 +1,251 @@
+# Tailwind Integration
+
+Map design system tokens to Tailwind CSS configuration.
+
+## CSS Variables Setup
+
+### Base Layer
+
+```css
+/* globals.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    /* Primitives */
+    --color-blue-600: 37 99 235;  /* HSL: 217 91% 60% */
+
+    /* Semantic */
+    --background: 0 0% 100%;
+    --foreground: 222 47% 11%;
+    --primary: 217 91% 60%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 14% 96%;
+    --secondary-foreground: 222 47% 11%;
+    --muted: 220 14% 96%;
+    --muted-foreground: 220 9% 46%;
+    --accent: 220 14% 96%;
+    --accent-foreground: 222 47% 11%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 220 13% 91%;
+    --input: 220 13% 91%;
+    --ring: 217 91% 60%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222 47% 4%;
+    --foreground: 210 40% 98%;
+    --primary: 217 91% 60%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 217 33% 17%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217 33% 17%;
+    --muted-foreground: 215 20% 65%;
+    --accent: 217 33% 17%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62% 30%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 217 33% 17%;
+    --input: 217 33% 17%;
+    --ring: 217 91% 60%;
+  }
+}
+```
+
+## Tailwind Config
+
+### tailwind.config.ts
+
+```typescript
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  darkMode: ['class'],
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [],
+}
+
+export default config
+```
+
+## HSL Format Benefits
+
+Using HSL without function allows opacity modifiers:
+
+```tsx
+// With HSL format (space-separated)
+<div className="bg-primary/50">   // 50% opacity
+<div className="text-primary/80"> // 80% opacity
+
+// CSS output
+background-color: hsl(217 91% 60% / 0.5);
+```
+
+## Component Classes
+
+### Button Example
+
+```css
+@layer components {
+  .btn {
+    @apply inline-flex items-center justify-center
+           rounded-md font-medium
+           transition-colors
+           focus-visible:outline-none focus-visible:ring-2
+           focus-visible:ring-ring focus-visible:ring-offset-2
+           disabled:pointer-events-none disabled:opacity-50;
+  }
+
+  .btn-default {
+    @apply bg-primary text-primary-foreground
+           hover:bg-primary/90;
+  }
+
+  .btn-secondary {
+    @apply bg-secondary text-secondary-foreground
+           hover:bg-secondary/80;
+  }
+
+  .btn-outline {
+    @apply border border-input bg-background
+           hover:bg-accent hover:text-accent-foreground;
+  }
+
+  .btn-ghost {
+    @apply hover:bg-accent hover:text-accent-foreground;
+  }
+
+  .btn-destructive {
+    @apply bg-destructive text-destructive-foreground
+           hover:bg-destructive/90;
+  }
+
+  /* Sizes */
+  .btn-sm { @apply h-8 px-3 text-xs; }
+  .btn-md { @apply h-10 px-4 text-sm; }
+  .btn-lg { @apply h-12 px-6 text-base; }
+}
+```
+
+## Spacing Integration
+
+```typescript
+// tailwind.config.ts
+theme: {
+  extend: {
+    spacing: {
+      // Map to CSS variables if needed
+      'section': 'var(--spacing-section)',
+      'component': 'var(--spacing-component)',
+    }
+  }
+}
+```
+
+## Animation Tokens
+
+```typescript
+// tailwind.config.ts
+theme: {
+  extend: {
+    transitionDuration: {
+      fast: '150ms',
+      normal: '200ms',
+      slow: '300ms',
+    },
+    keyframes: {
+      'accordion-down': {
+        from: { height: '0' },
+        to: { height: 'var(--radix-accordion-content-height)' },
+      },
+      'accordion-up': {
+        from: { height: 'var(--radix-accordion-content-height)' },
+        to: { height: '0' },
+      },
+    },
+    animation: {
+      'accordion-down': 'accordion-down 0.2s ease-out',
+      'accordion-up': 'accordion-up 0.2s ease-out',
+    },
+  }
+}
+```
+
+## Dark Mode Toggle
+
+```typescript
+// Toggle dark mode
+function toggleDarkMode() {
+  document.documentElement.classList.toggle('dark')
+}
+
+// System preference
+if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+  document.documentElement.classList.add('dark')
+}
+```
+
+## shadcn/ui Alignment
+
+This configuration aligns with shadcn/ui conventions:
+
+- Same CSS variable naming
+- Same HSL format
+- Same color scale structure
+- Compatible with `npx shadcn@latest add` commands
+
+### Using with shadcn/ui
+
+```bash
+# Initialize (uses same token structure)
+npx shadcn@latest init
+
+# Add components (styled with these tokens)
+npx shadcn@latest add button card input
+```
+
+Components will automatically use your design system tokens.

devkit/skills/embedded/design-system/references/token-architecture.md

@@ -0,0 +1,224 @@
+# Token Architecture
+
+Three-layer token system for scalable, themeable design systems.
+
+## Layer Overview
+
+```
+┌─────────────────────────────────────────┐
+│  Component Tokens                       │  Per-component overrides
+│  --button-bg, --card-padding            │
+├─────────────────────────────────────────┤
+│  Semantic Tokens                        │  Purpose-based aliases
+│  --color-primary, --spacing-section     │
+├─────────────────────────────────────────┤
+│  Primitive Tokens                       │  Raw design values
+│  --color-blue-600, --space-4            │
+└─────────────────────────────────────────┘
+```
+
+## Why Three Layers?
+
+| Layer | Purpose | When to Change |
+|-------|---------|----------------|
+| Primitive | Base values (colors, sizes) | Rarely - foundational |
+| Semantic | Meaning assignment | Theme switching |
+| Component | Component customization | Per-component needs |
+
+## Layer 1: Primitive Tokens
+
+Raw design values without semantic meaning.
+
+```css
+:root {
+  /* Colors */
+  --color-gray-50: #F9FAFB;
+  --color-gray-900: #111827;
+  --color-blue-500: #3B82F6;
+  --color-blue-600: #2563EB;
+
+  /* Spacing (4px base) */
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-4: 1rem;     /* 16px */
+  --space-6: 1.5rem;   /* 24px */
+
+  /* Typography */
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+
+  /* Radius */
+  --radius-sm: 0.25rem;
+  --radius-default: 0.5rem;
+  --radius-lg: 0.75rem;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
+  --shadow-default: 0 1px 3px rgb(0 0 0 / 0.1);
+}
+```
+
+## Layer 2: Semantic Tokens
+
+Purpose-based aliases that reference primitives.
+
+```css
+:root {
+  /* Background */
+  --color-background: var(--color-gray-50);
+  --color-foreground: var(--color-gray-900);
+
+  /* Primary */
+  --color-primary: var(--color-blue-600);
+  --color-primary-hover: var(--color-blue-700);
+
+  /* Secondary */
+  --color-secondary: var(--color-gray-100);
+  --color-secondary-foreground: var(--color-gray-900);
+
+  /* Muted */
+  --color-muted: var(--color-gray-100);
+  --color-muted-foreground: var(--color-gray-500);
+
+  /* Destructive */
+  --color-destructive: var(--color-red-600);
+  --color-destructive-foreground: white;
+
+  /* Spacing */
+  --spacing-component: var(--space-4);
+  --spacing-section: var(--space-6);
+}
+```
+
+## Layer 3: Component Tokens
+
+Component-specific tokens referencing semantic layer.
+
+```css
+:root {
+  /* Button */
+  --button-bg: var(--color-primary);
+  --button-fg: white;
+  --button-hover-bg: var(--color-primary-hover);
+  --button-padding-x: var(--space-4);
+  --button-padding-y: var(--space-2);
+  --button-radius: var(--radius-default);
+
+  /* Input */
+  --input-bg: var(--color-background);
+  --input-border: var(--color-gray-300);
+  --input-focus-ring: var(--color-primary);
+  --input-padding: var(--space-2) var(--space-3);
+
+  /* Card */
+  --card-bg: var(--color-background);
+  --card-border: var(--color-gray-200);
+  --card-padding: var(--space-4);
+  --card-radius: var(--radius-lg);
+  --card-shadow: var(--shadow-default);
+}
+```
+
+## Dark Mode
+
+Override semantic tokens for dark theme:
+
+```css
+.dark {
+  --color-background: var(--color-gray-900);
+  --color-foreground: var(--color-gray-50);
+  --color-muted: var(--color-gray-800);
+  --color-muted-foreground: var(--color-gray-400);
+  --color-secondary: var(--color-gray-800);
+}
+```
+
+## Naming Convention
+
+```
+--{category}-{item}-{variant}-{state}
+
+Examples:
+--color-primary           # category-item
+--color-primary-hover     # category-item-state
+--button-bg-hover         # component-property-state
+--space-section-sm        # category-semantic-variant
+```
+
+## Categories
+
+| Category | Examples |
+|----------|----------|
+| color | primary, secondary, muted, destructive |
+| space | 1, 2, 4, 8, section, component |
+| font-size | xs, sm, base, lg, xl |
+| radius | sm, default, lg, full |
+| shadow | sm, default, lg |
+| duration | fast, normal, slow |
+
+## File Organization
+
+```
+tokens/
+├── primitives.css     # Raw values
+├── semantic.css       # Purpose aliases
+├── components.css     # Component tokens
+└── index.css          # Imports all
+```
+
+Or single file with layer comments:
+
+```css
+/* === PRIMITIVES === */
+:root { ... }
+
+/* === SEMANTIC === */
+:root { ... }
+
+/* === COMPONENTS === */
+:root { ... }
+
+/* === DARK MODE === */
+.dark { ... }
+```
+
+## Migration from Flat Tokens
+
+Before (flat):
+```css
+--button-primary-bg: #2563EB;
+--button-secondary-bg: #F3F4F6;
+```
+
+After (three-layer):
+```css
+/* Primitive */
+--color-blue-600: #2563EB;
+--color-gray-100: #F3F4F6;
+
+/* Semantic */
+--color-primary: var(--color-blue-600);
+--color-secondary: var(--color-gray-100);
+
+/* Component */
+--button-bg: var(--color-primary);
+--button-secondary-bg: var(--color-secondary);
+```
+
+## W3C DTCG Alignment
+
+Token JSON format (W3C Design Tokens Community Group):
+
+```json
+{
+  "color": {
+    "blue": {
+      "600": {
+        "$value": "#2563EB",
+        "$type": "color"
+      }
+    }
+  }
+}
+```

devkit/skills/embedded/design-system/scripts/embed-tokens.cjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * embed-tokens.cjs
+ * Reads design-tokens.css and outputs embeddable inline CSS.
+ * Use when generating standalone HTML files (infographics, slides, etc.)
+ *
+ * Usage:
+ *   node embed-tokens.cjs           # Output full CSS
+ *   node embed-tokens.cjs --minimal # Output only commonly used tokens
+ *   node embed-tokens.cjs --style   # Wrap in <style> tags
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Find project root (look for assets/design-tokens.css)
+function findProjectRoot(startDir) {
+  // Walk up until dirname stops changing: on Windows the root is 'C:\', so a
+  // `dir !== '/'` guard never terminates.
+  let dir = startDir;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'assets', 'design-tokens.css'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const projectRoot = findProjectRoot(process.cwd());
+if (!projectRoot) {
+  console.error('Error: Could not find assets/design-tokens.css');
+  process.exit(1);
+}
+
+const tokensPath = path.join(projectRoot, 'assets', 'design-tokens.css');
+
+// Minimal tokens commonly used in infographics/slides
+const MINIMAL_TOKENS = [
+  '--primitive-spacing-',
+  '--primitive-fontSize-',
+  '--primitive-fontWeight-',
+  '--primitive-lineHeight-',
+  '--primitive-radius-',
+  '--primitive-shadow-glow-',
+  '--primitive-gradient-',
+  '--primitive-duration-',
+  '--color-primary',
+  '--color-secondary',
+  '--color-accent',
+  '--color-background',
+  '--color-surface',
+  '--color-foreground',
+  '--color-border',
+  '--typography-font-',
+  '--card-',
+];
+
+function extractTokens(css, minimal = false) {
+  // Extract :root block
+  const rootMatch = css.match(/:root\s*\{([^}]+)\}/g);
+  if (!rootMatch) return '';
+
+  let allVars = [];
+  for (const block of rootMatch) {
+    const vars = block.match(/--[\w-]+:\s*[^;]+;/g) || [];
+    allVars = allVars.concat(vars);
+  }
+
+  if (minimal) {
+    allVars = allVars.filter(v =>
+      MINIMAL_TOKENS.some(token => v.includes(token))
+    );
+  }
+
+  // Dedupe
+  allVars = [...new Set(allVars)];
+
+  return `:root {\n  ${allVars.join('\n  ')}\n}`;
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const minimal = args.includes('--minimal');
+const wrapStyle = args.includes('--style');
+
+try {
+  const css = fs.readFileSync(tokensPath, 'utf-8');
+  let output = extractTokens(css, minimal);
+
+  if (wrapStyle) {
+    output = `<style>\n/* Design Tokens (embedded for standalone HTML) */\n${output}\n</style>`;
+  } else {
+    output = `/* Design Tokens (embedded for standalone HTML) */\n${output}`;
+  }
+
+  console.log(output);
+} catch (err) {
+  console.error(`Error reading tokens: ${err.message}`);
+  process.exit(1);
+}