novahiz 0.1.0

package/skills/ui-design-system/references/responsive-calculations.md

@@ -0,0 +1,390 @@
+# Responsive Design Calculations
+
+Reference for breakpoint math, fluid typography, and responsive layout patterns.
+
+---
+
+## Table of Contents
+
+- [Breakpoint System](#breakpoint-system)
+- [Fluid Typography](#fluid-typography)
+- [Responsive Spacing](#responsive-spacing)
+- [Container Queries](#container-queries)
+- [Grid Systems](#grid-systems)
+
+---
+
+## Breakpoint System
+
+### Standard Breakpoints
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    BREAKPOINT RANGES                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  xs        sm         md         lg         xl        2xl   │
+│  │─────────│──────────│──────────│──────────│─────────│     │
+│  0      480px      640px      768px     1024px    1280px    │
+│                                                      1536px │
+│                                                             │
+│  Mobile   Mobile+    Tablet    Laptop    Desktop   Large    │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Breakpoint Values
+
+| Name | Min Width | Target Devices |
+|------|-----------|----------------|
+| xs | 0 | Small phones |
+| sm | 480px | Large phones |
+| md | 640px | Small tablets |
+| lg | 768px | Tablets, small laptops |
+| xl | 1024px | Laptops, desktops |
+| 2xl | 1280px | Large desktops |
+| 3xl | 1536px | Extra large displays |
+
+### Mobile-First Media Queries
+
+```css
+/* Base styles (mobile) */
+.component {
+  padding: var(--spacing-sm);
+  font-size: var(--fontSize-sm);
+}
+
+/* Small devices and up */
+@media (min-width: 480px) {
+  .component {
+    padding: var(--spacing-md);
+  }
+}
+
+/* Medium devices and up */
+@media (min-width: 768px) {
+  .component {
+    padding: var(--spacing-lg);
+    font-size: var(--fontSize-base);
+  }
+}
+
+/* Large devices and up */
+@media (min-width: 1024px) {
+  .component {
+    padding: var(--spacing-xl);
+  }
+}
+```
+
+### Breakpoint Utility Function
+
+```javascript
+const breakpoints = {
+  xs: 480,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536
+};
+
+function mediaQuery(breakpoint, type = 'min') {
+  const value = breakpoints[breakpoint];
+  if (type === 'min') {
+    return `@media (min-width: ${value}px)`;
+  }
+  return `@media (max-width: ${value - 1}px)`;
+}
+
+// Usage
+const styles = `
+  ${mediaQuery('md')} {
+    display: flex;
+  }
+`;
+```
+
+---
+
+## Fluid Typography
+
+### Clamp Formula
+
+```css
+font-size: clamp(min, preferred, max);
+
+/* Example: 16px to 24px between 320px and 1200px viewport */
+font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
+```
+
+### Fluid Scale Calculation
+
+```
+preferred = min + (max - min) * ((100vw - minVW) / (maxVW - minVW))
+
+Simplified:
+preferred = base + (scaling-factor * vw)
+
+Where:
+  scaling-factor = (max - min) / (maxVW - minVW) * 100
+```
+
+### Fluid Typography Scale
+
+| Style | Mobile (320px) | Desktop (1200px) | Clamp Value |
+|-------|----------------|------------------|-------------|
+| h1 | 32px | 64px | `clamp(2rem, 1rem + 3.6vw, 4rem)` |
+| h2 | 28px | 48px | `clamp(1.75rem, 1rem + 2.3vw, 3rem)` |
+| h3 | 24px | 36px | `clamp(1.5rem, 1rem + 1.4vw, 2.25rem)` |
+| h4 | 20px | 28px | `clamp(1.25rem, 1rem + 0.9vw, 1.75rem)` |
+| body | 16px | 18px | `clamp(1rem, 0.95rem + 0.2vw, 1.125rem)` |
+| small | 14px | 14px | `0.875rem` (fixed) |
+
+### Implementation
+
+```css
+:root {
+  /* Fluid type scale */
+  --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
+  --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
+  --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
+  --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
+}
+
+h1 { font-size: var(--fluid-h1); }
+h2 { font-size: var(--fluid-h2); }
+h3 { font-size: var(--fluid-h3); }
+body { font-size: var(--fluid-body); }
+```
+
+---
+
+## Responsive Spacing
+
+### Fluid Spacing Formula
+
+```css
+/* Spacing that scales with viewport */
+spacing: clamp(minSpace, preferredSpace, maxSpace);
+
+/* Example: 16px to 48px */
+--spacing-responsive: clamp(1rem, 0.5rem + 2vw, 3rem);
+```
+
+### Responsive Spacing Scale
+
+| Token | Mobile | Tablet | Desktop |
+|-------|--------|--------|---------|
+| --space-xs | 4px | 4px | 4px |
+| --space-sm | 8px | 8px | 8px |
+| --space-md | 12px | 16px | 16px |
+| --space-lg | 16px | 24px | 32px |
+| --space-xl | 24px | 32px | 48px |
+| --space-2xl | 32px | 48px | 64px |
+| --space-section | 48px | 80px | 120px |
+
+### Implementation
+
+```css
+:root {
+  --space-section: clamp(3rem, 2rem + 4vw, 7.5rem);
+  --space-component: clamp(1rem, 0.5rem + 1vw, 2rem);
+  --space-content: clamp(1.5rem, 1rem + 2vw, 3rem);
+}
+
+.section {
+  padding-top: var(--space-section);
+  padding-bottom: var(--space-section);
+}
+
+.card {
+  padding: var(--space-component);
+  gap: var(--space-content);
+}
+```
+
+---
+
+## Container Queries
+
+### Container Width Tokens
+
+| Container | Max Width | Use Case |
+|-----------|-----------|----------|
+| sm | 640px | Narrow content |
+| md | 768px | Blog posts |
+| lg | 1024px | Standard pages |
+| xl | 1280px | Wide layouts |
+| 2xl | 1536px | Full-width dashboards |
+
+### Container CSS
+
+```css
+.container {
+  width: 100%;
+  margin-left: auto;
+  margin-right: auto;
+  padding-left: var(--spacing-md);
+  padding-right: var(--spacing-md);
+}
+
+.container--sm { max-width: 640px; }
+.container--md { max-width: 768px; }
+.container--lg { max-width: 1024px; }
+.container--xl { max-width: 1280px; }
+.container--2xl { max-width: 1536px; }
+```
+
+### CSS Container Queries
+
+```css
+/* Define container */
+.card-container {
+  container-type: inline-size;
+  container-name: card;
+}
+
+/* Query container width */
+@container card (min-width: 400px) {
+  .card {
+    display: flex;
+    flex-direction: row;
+  }
+}
+
+@container card (min-width: 600px) {
+  .card {
+    gap: var(--spacing-lg);
+  }
+}
+```
+
+---
+
+## Grid Systems
+
+### 12-Column Grid
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: var(--spacing-md);
+}
+
+/* Column spans */
+.col-1 { grid-column: span 1; }
+.col-2 { grid-column: span 2; }
+.col-3 { grid-column: span 3; }
+.col-4 { grid-column: span 4; }
+.col-6 { grid-column: span 6; }
+.col-12 { grid-column: span 12; }
+
+/* Responsive columns */
+@media (min-width: 768px) {
+  .col-md-4 { grid-column: span 4; }
+  .col-md-6 { grid-column: span 6; }
+  .col-md-8 { grid-column: span 8; }
+}
+```
+
+### Auto-Fit Grid
+
+```css
+/* Cards that automatically wrap */
+.auto-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--spacing-lg);
+}
+
+/* With explicit min/max columns */
+.auto-grid--constrained {
+  grid-template-columns: repeat(
+    auto-fit,
+    minmax(min(100%, 280px), 1fr)
+  );
+}
+```
+
+### Common Layout Patterns
+
+**Sidebar + Content:**
+```css
+.layout-sidebar {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--spacing-lg);
+}
+
+@media (min-width: 768px) {
+  .layout-sidebar {
+    grid-template-columns: 280px 1fr;
+  }
+}
+```
+
+**Holy Grail:**
+```css
+.layout-holy-grail {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-rows: auto 1fr auto;
+  min-height: 100vh;
+}
+
+@media (min-width: 1024px) {
+  .layout-holy-grail {
+    grid-template-columns: 200px 1fr 200px;
+    grid-template-rows: auto 1fr auto;
+  }
+
+  .layout-holy-grail header,
+  .layout-holy-grail footer {
+    grid-column: 1 / -1;
+  }
+}
+```
+
+---
+
+## Quick Reference
+
+### Viewport Units
+
+| Unit | Description |
+|------|-------------|
+| vw | 1% of viewport width |
+| vh | 1% of viewport height |
+| vmin | 1% of smaller dimension |
+| vmax | 1% of larger dimension |
+| dvh | Dynamic viewport height (accounts for mobile chrome) |
+| svh | Small viewport height |
+| lvh | Large viewport height |
+
+### Responsive Testing Checklist
+
+- [ ] 320px (small mobile)
+- [ ] 375px (iPhone SE/8)
+- [ ] 414px (iPhone Plus/Max)
+- [ ] 768px (iPad portrait)
+- [ ] 1024px (iPad landscape/laptop)
+- [ ] 1280px (desktop)
+- [ ] 1920px (large desktop)
+
+### Common Device Widths
+
+| Device | Width | Breakpoint |
+|--------|-------|------------|
+| iPhone SE | 375px | xs-sm |
+| iPhone 14 | 390px | sm |
+| iPhone 14 Pro Max | 430px | sm |
+| iPad Mini | 768px | lg |
+| iPad Pro 11" | 834px | lg |
+| MacBook Air 13" | 1280px | xl |
+| iMac 24" | 1920px | 2xl+ |
+
+---
+
+*See also: `token-generation.md` for breakpoint token details*

package/skills/ui-design-system/references/token-generation.md

@@ -0,0 +1,324 @@
+# Design Token Generation Guide
+
+Reference for color palette algorithms, typography scales, and WCAG accessibility checking.
+
+---
+
+## Table of Contents
+
+- [Color Palette Generation](#color-palette-generation)
+- [Typography Scale System](#typography-scale-system)
+- [Spacing Grid System](#spacing-grid-system)
+- [Accessibility Contrast](#accessibility-contrast)
+- [Export Formats](#export-formats)
+
+---
+
+## Color Palette Generation
+
+### HSV Color Space Algorithm
+
+The token generator uses HSV (Hue, Saturation, Value) color space for precise control.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    COLOR SCALE GENERATION                   │
+├─────────────────────────────────────────────────────────────┤
+│  Input: Brand Color (#0066CC)                               │
+│  ↓                                                          │
+│  Convert: Hex → RGB → HSV                                   │
+│  ↓                                                          │
+│  For each step (50, 100, 200... 900):                      │
+│    • Adjust Value (brightness)                              │
+│    • Adjust Saturation                                      │
+│    • Keep Hue constant                                      │
+│  ↓                                                          │
+│  Output: 10-step color scale                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Brightness Algorithm
+
+```python
+# For light shades (50-400): High fixed brightness
+if step < 500:
+    new_value = 0.95  # 95% brightness
+
+# For dark shades (500-900): Exponential decrease
+else:
+    new_value = base_value * (1 - (step - 500) / 500)
+    # At step 900: brightness ≈ base_value * 0.2
+```
+
+### Saturation Scaling
+
+```python
+# Saturation increases with step number
+# 50 = 30% of base saturation
+# 900 = 100% of base saturation
+new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))
+```
+
+### Complementary Color Generation
+
+```
+Brand Color: #0066CC (H=210°, S=100%, V=80%)
+                    ↓
+           Add 180° to Hue
+                    ↓
+Secondary: #CC6600 (H=30°, S=100%, V=80%)
+```
+
+### Color Scale Output
+
+| Step | Use Case | Brightness | Saturation |
+|------|----------|------------|------------|
+| 50 | Subtle backgrounds | 95% (fixed) | 30% |
+| 100 | Light backgrounds | 95% (fixed) | 38% |
+| 200 | Hover states | 95% (fixed) | 46% |
+| 300 | Borders | 95% (fixed) | 54% |
+| 400 | Disabled states | 95% (fixed) | 62% |
+| 500 | Base color | Original | 70% |
+| 600 | Hover (dark) | Original × 0.8 | 78% |
+| 700 | Active states | Original × 0.6 | 86% |
+| 800 | Text | Original × 0.4 | 94% |
+| 900 | Headings | Original × 0.2 | 100% |
+
+---
+
+## Typography Scale System
+
+### Modular Scale (Major Third)
+
+The generator uses a **1.25x ratio** (major third) to create harmonious font sizes.
+
+```
+Base: 16px
+
+Scale calculation:
+  Smaller sizes: 16px ÷ 1.25^n
+  Larger sizes: 16px × 1.25^n
+
+Result:
+  xs:   10px (16 ÷ 1.25²)
+  sm:   13px (16 ÷ 1.25¹)
+  base: 16px
+  lg:   20px (16 × 1.25¹)
+  xl:   25px (16 × 1.25²)
+  2xl:  31px (16 × 1.25³)
+  3xl:  39px (16 × 1.25⁴)
+  4xl:  49px (16 × 1.25⁵)
+  5xl:  61px (16 × 1.25⁶)
+```
+
+### Type Scale Ratios
+
+| Ratio | Name | Multiplier | Character |
+|-------|------|------------|-----------|
+| 1.067 | Minor Second | Tight | Compact UIs |
+| 1.125 | Major Second | Subtle | App interfaces |
+| 1.200 | Minor Third | Moderate | General use |
+| **1.250** | **Major Third** | **Balanced** | **Default** |
+| 1.333 | Perfect Fourth | Pronounced | Marketing |
+| 1.414 | Augmented Fourth | Bold | Editorial |
+| 1.618 | Golden Ratio | Dramatic | Headlines |
+
+### Pre-composed Text Styles
+
+| Style | Size | Weight | Line Height | Letter Spacing |
+|-------|------|--------|-------------|----------------|
+| h1 | 48px | 700 | 1.2 | -0.02em |
+| h2 | 36px | 700 | 1.3 | -0.01em |
+| h3 | 28px | 600 | 1.4 | 0 |
+| h4 | 24px | 600 | 1.4 | 0 |
+| h5 | 20px | 600 | 1.5 | 0 |
+| h6 | 16px | 600 | 1.5 | 0.01em |
+| body | 16px | 400 | 1.5 | 0 |
+| small | 14px | 400 | 1.5 | 0 |
+| caption | 12px | 400 | 1.5 | 0.01em |
+
+---
+
+## Spacing Grid System
+
+### 8pt Grid Foundation
+
+All spacing values are multiples of 8px for visual consistency.
+
+```
+Base Unit: 8px
+
+Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...
+
+Results:
+  0:  0px
+  1:  4px  (0.5 × 8)
+  2:  8px  (1 × 8)
+  3:  12px (1.5 × 8)
+  4:  16px (2 × 8)
+  5:  20px (2.5 × 8)
+  6:  24px (3 × 8)
+  ...
+```
+
+### Semantic Spacing Mapping
+
+| Token | Numeric | Value | Use Case |
+|-------|---------|-------|----------|
+| xs | 1 | 4px | Inline icon margins |
+| sm | 2 | 8px | Button padding |
+| md | 4 | 16px | Card padding |
+| lg | 6 | 24px | Section spacing |
+| xl | 8 | 32px | Component gaps |
+| 2xl | 12 | 48px | Section margins |
+| 3xl | 16 | 64px | Page sections |
+
+### Why 8pt Grid?
+
+1. **Divisibility**: 8 divides evenly into common screen widths
+2. **Consistency**: Creates predictable vertical rhythm
+3. **Accessibility**: Touch targets naturally align to 48px (8 × 6)
+4. **Integration**: Most design tools default to 8px grids
+
+---
+
+## Accessibility Contrast
+
+### WCAG Contrast Requirements
+
+| Level | Normal Text | Large Text | Definition |
+|-------|-------------|------------|------------|
+| AA | 4.5:1 | 3:1 | Minimum requirement |
+| AAA | 7:1 | 4.5:1 | Enhanced accessibility |
+
+**Large text**: ≥18pt regular or ≥14pt bold
+
+### Contrast Ratio Formula
+
+```
+Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
+
+Where:
+  L1 = Relative luminance of lighter color
+  L2 = Relative luminance of darker color
+
+Relative Luminance:
+  L = 0.2126 × R + 0.7152 × G + 0.0722 × B
+  (Values linearized from sRGB)
+```
+
+### Color Step Contrast Guide
+
+| Background | Minimum Text Step | For AA |
+|------------|-------------------|--------|
+| 50 | 700+ | Large text at 600 |
+| 100 | 700+ | Large text at 600 |
+| 200 | 800+ | Large text at 700 |
+| 300 | 900 | - |
+| 500 (base) | White or 50 | - |
+| 700+ | White or 50-100 | - |
+
+### Semantic Colors Accessibility
+
+Generated semantic colors include contrast colors:
+
+```json
+{
+  "success": {
+    "base": "#10B981",
+    "light": "#34D399",
+    "dark": "#059669",
+    "contrast": "#FFFFFF"  // For text on base
+  }
+}
+```
+
+---
+
+## Export Formats
+
+### JSON Format
+
+Best for: Design tool plugins, JavaScript/TypeScript projects, APIs
+
+```json
+{
+  "colors": {
+    "primary": {
+      "50": "#E6F2FF",
+      "500": "#0066CC",
+      "900": "#002855"
+    }
+  },
+  "typography": {
+    "fontSize": {
+      "base": "16px",
+      "lg": "20px"
+    }
+  }
+}
+```
+
+### CSS Custom Properties
+
+Best for: Web applications, CSS frameworks
+
+```css
+:root {
+  --colors-primary-50: #E6F2FF;
+  --colors-primary-500: #0066CC;
+  --colors-primary-900: #002855;
+  --typography-fontSize-base: 16px;
+  --typography-fontSize-lg: 20px;
+}
+```
+
+### SCSS Variables
+
+Best for: SCSS/SASS projects, component libraries
+
+```scss
+$colors-primary-50: #E6F2FF;
+$colors-primary-500: #0066CC;
+$colors-primary-900: #002855;
+$typography-fontSize-base: 16px;
+$typography-fontSize-lg: 20px;
+```
+
+### Format Selection Guide
+
+| Format | When to Use |
+|--------|-------------|
+| JSON | Figma plugins, Storybook, JS/TS, design tool APIs |
+| CSS | Plain CSS projects, CSS-in-JS (some), web apps |
+| SCSS | SASS pipelines, component libraries, theming |
+| Summary | Quick verification, debugging |
+
+---
+
+## Quick Reference
+
+### Generation Command
+
+```bash
+# Default (modern style, JSON output)
+python scripts/design_token_generator.py "#0066CC"
+
+# Classic style, CSS output
+python scripts/design_token_generator.py "#8B4513" classic css
+
+# Playful style, summary view
+python scripts/design_token_generator.py "#FF6B6B" playful summary
+```
+
+### Style Differences
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Fonts | Inter, Fira Code | Helvetica, Courier | Poppins, Source Code Pro |
+| Border Radius | 8px default | 4px default | 16px default |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+*See also: `component-architecture.md` for component design patterns*