@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/design-md/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: design-md
+description: Google's open DESIGN.md specification for describing visual identities to coding agents. YAML tokens + Markdown rationale + npx CLI for WCAG validation and W3C DTCG/Tailwind export. Use for formal, agent-consumable design system documentation.
+source: NousResearch/hermes-agent
+---
+
+# DESIGN.md
+
+[Google's open spec](https://github.com/google-labs-code/design.md) (Apache-2.0) for writing visual identities as structured files that coding agents can consume. Combines machine-readable YAML tokens with human-readable Markdown rationale.
+
+**Not the same as `design-system-tokens`**: that skill covers our internal three-layer token architecture (primitive→semantic→component) for building actual CSS systems. `design-md` is a *specification format* — a document you write to describe a brand to an agent, with a CLI for validation and export.
+
+## When to Use
+
+- Creating a formal design spec a coding agent will reference when building UI
+- Multi-project brand consistency where the spec needs to be version-controlled
+- Validating color palette for WCAG AA contrast compliance
+- Exporting to Tailwind theme JSON or W3C DTCG token format
+- Working with teams who want a single source of truth for design tokens
+
+Use `popular-web-designs` or `warm-editorial-ui` instead for one-off prototypes or visual inspiration.
+
+## File Structure
+
+```
+DESIGN.md
+```
+Single file. YAML front matter (tokens) + Markdown body (rationale).
+
+```yaml
+---
+version: alpha
+name: "Brand Name"
+description: "One-line description of the visual identity"
+
+colors:
+  primary: "#6366f1"
+  primary-hover: "#4f46e5"
+  background: "#ffffff"
+  surface: "#f8fafc"
+  text: "#0f172a"
+  text-secondary: "#64748b"
+  border: "#e2e8f0"
+  success: "#10b981"
+  warning: "#f59e0b"
+  danger: "#ef4444"
+
+typography:
+  font-heading: "Inter"
+  font-body: "Inter"
+  font-mono: "JetBrains Mono"
+  size-xs: "0.75rem"
+  size-sm: "0.875rem"
+  size-base: "1rem"
+  size-lg: "1.125rem"
+  size-xl: "1.25rem"
+  size-2xl: "1.5rem"
+  size-3xl: "1.875rem"
+  size-4xl: "2.25rem"
+
+spacing:
+  xs: "0.25rem"
+  sm: "0.5rem"
+  md: "1rem"
+  lg: "1.5rem"
+  xl: "2rem"
+  2xl: "3rem"
+
+rounded:
+  sm: "0.25rem"
+  md: "0.375rem"
+  lg: "0.5rem"
+  xl: "0.75rem"
+  full: "9999px"
+---
+```
+
+## Markdown Sections (canonical order)
+
+```markdown
+## Overview
+One paragraph: brand personality, target audience, emotional goal.
+
+## Colors
+Why each color was chosen. Contrast ratios for key pairs. Light/dark mode notes.
+
+## Typography
+Font selection rationale. Hierarchy explanation. When to use heading vs body.
+
+## Layout
+Grid system. Max content width. Whitespace philosophy.
+
+## Elevation & Depth
+Shadow system. Z-index scale. When to use each elevation level.
+
+## Shapes
+Border-radius philosophy. When to use rounded vs sharp.
+
+## Components
+Key component decisions. Button variants. Card patterns. Form style.
+
+## Do's and Don'ts
+Concrete usage rules. What breaks the brand. Common mistakes.
+```
+
+## Token Reference Syntax
+
+Use dotted paths to reference other tokens (single source of truth):
+
+```yaml
+colors:
+  primary: "#6366f1"
+  button-bg: "{colors.primary}"         # references primary
+  button-hover: "{colors.primary-hover}"
+```
+
+## Critical Rules
+
+- **Component variants as sibling keys** — never nested:
+  ```yaml
+  # ✓ Correct
+  button-primary-bg: "#6366f1"
+  button-primary-hover-bg: "#4f46e5"
+  button-secondary-bg: "transparent"
+  
+  # ✗ Wrong (no nesting)
+  button:
+    primary:
+      bg: "#6366f1"
+  ```
+- **Hex colors must be quoted** in YAML (they start with `#` which YAML treats as comments if unquoted)
+- **Negative values must be quoted**: `margin-top: "-0.5rem"` not `margin-top: -0.5rem`
+- Current spec version is `alpha` — the schema may evolve
+
+## CLI
+
+```bash
+# Install (one-time)
+npx @google/design.md --help
+
+# Validate structure and WCAG contrast
+npx @google/design.md validate DESIGN.md
+
+# Compare two versions (detect regressions)
+npx @google/design.md diff DESIGN.md DESIGN.v2.md
+
+# Export to Tailwind theme config
+npx @google/design.md export --format tailwind DESIGN.md > tailwind-theme.json
+
+# Export to W3C DTCG format
+npx @google/design.md export --format dtcg DESIGN.md > tokens.json
+```
+
+## Workflow
+
+1. **Gather brand inputs**: existing screenshots, hex codes, font names, brand guidelines
+2. **Write YAML tokens** first — colors, typography, spacing, rounded
+3. **Write Markdown sections** — explain rationale, not just values
+4. **Run validate** — check WCAG contrast on critical pairs (primary on background, text on surface)
+5. **Export if needed** — Tailwind JSON for implementation, DTCG for design tools
+6. **Commit alongside code** — `DESIGN.md` lives in the repo root or `docs/`
+
+## Integration with Other Skills
+
+- After writing `DESIGN.md`, use `popular-web-designs` for inspiration on how real brands apply similar systems
+- Use `design-system-tokens` when you need to implement the spec as actual CSS custom properties
+- Use `warm-editorial-ui` when the project is your organization's internal app family — it already has a complete DESIGN.md-compatible token set

package/bundles/antigravity-plugin-extras/skills/design-system-tokens/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: design-system-tokens
+description: Token architecture and component specifications. Three-layer tokens (primitive → semantic → component), CSS variables, spacing/typography scales, and component state definitions. Use for design token creation and systematic design.
+license: MIT
+---
+
+# Design System
+
+Token architecture, component specifications, systematic design, slide generation.
+
+## When to Use
+
+- Design token creation
+- Component state definitions
+- CSS variable systems
+- Spacing/typography scales
+- Design-to-code handoff
+- Tailwind theme configuration
+- **Slide/presentation generation**
+
+## Token Architecture
+
+Load: `references/token-architecture.md`
+
+### Three-Layer Structure
+
+```
+Primitive (raw values)
+       ↓
+Semantic (purpose aliases)
+       ↓
+Component (component-specific)
+```
+
+**Example:**
+```css
+/* Primitive */
+--color-blue-600: #2563EB;
+
+/* Semantic */
+--color-primary: var(--color-blue-600);
+
+/* Component */
+--button-bg: var(--color-primary);
+```
+
+## Quick Start
+
+**Generate tokens:**
+```bash
+node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
+```
+
+**Validate usage:**
+```bash
+node scripts/validate-tokens.cjs --dir src/
+```
+
+## References
+
+| Topic | File |
+|-------|------|
+| Token Architecture | `references/token-architecture.md` |
+| Primitive Tokens | `references/primitive-tokens.md` |
+| Semantic Tokens | `references/semantic-tokens.md` |
+| Component Tokens | `references/component-tokens.md` |
+| Component Specs | `references/component-specs.md` |
+| States & Variants | `references/states-and-variants.md` |
+| Tailwind Integration | `references/tailwind-integration.md` |
+
+## Component Spec Pattern
+
+| Property | Default | Hover | Active | Disabled |
+|----------|---------|-------|--------|----------|
+| Background | primary | primary-dark | primary-darker | muted |
+| Text | white | white | white | muted-fg |
+| Border | none | none | none | muted-border |
+| Shadow | sm | md | none | none |
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `generate-tokens.cjs` | Generate CSS from JSON token config |
+| `validate-tokens.cjs` | Check for hardcoded values in code |
+| `search-slides.py` | BM25 search + contextual recommendations |
+| `slide-token-validator.py` | Validate slide HTML for token compliance |
+| `fetch-background.py` | Fetch images from Pexels/Unsplash |
+
+## Templates
+
+| Template | Purpose |
+|----------|---------|
+| `design-tokens-starter.json` | Starter JSON with three-layer structure |
+
+## Integration
+
+**With brand:** Extract primitives from brand colors/typography
+**With ui-styling:** Component tokens → Tailwind config
+
+**Skill Dependencies:** brand, ui-styling
+**Primary Agents:** ui-ux-designer, frontend-developer
+
+## Slide System
+
+Brand-compliant presentations using design tokens + Chart.js + contextual decision system.
+
+### Source of Truth
+
+| File | Purpose |
+|------|---------|
+| `docs/brand-guidelines.md` | Brand identity, voice, colors |
+| `assets/design-tokens.json` | Token definitions (primitive→semantic→component) |
+| `assets/design-tokens.css` | CSS variables (import in slides) |
+| `assets/css/slide-animations.css` | CSS animation library |
+
+### Slide Search (BM25)
+
+```bash
+# Basic search (auto-detect domain)
+python scripts/search-slides.py "investor pitch"
+
+# Domain-specific search
+python scripts/search-slides.py "problem agitation" -d copy
+python scripts/search-slides.py "revenue growth" -d chart
+
+# Contextual search (Premium System)
+python scripts/search-slides.py "problem slide" --context --position 2 --total 9
+python scripts/search-slides.py "cta" --context --position 9 --prev-emotion frustration
+```
+
+### Decision System CSVs
+
+| File | Purpose |
+|------|---------|
+| `data/slide-strategies.csv` | 15 deck structures + emotion arcs + sparkline beats |
+| `data/slide-layouts.csv` | 25 layouts + component variants + animations |
+| `data/slide-layout-logic.csv` | Goal → Layout + break_pattern flag |
+| `data/slide-typography.csv` | Content type → Typography scale |
+| `data/slide-color-logic.csv` | Emotion → Color treatment |
+| `data/slide-backgrounds.csv` | Slide type → Image category (Pexels/Unsplash) |
+| `data/slide-copy.csv` | 25 copywriting formulas (PAS, AIDA, FAB) |
+| `data/slide-charts.csv` | 25 chart types with Chart.js config |
+
+### Contextual Decision Flow
+
+```
+1. Parse goal/context
+        ↓
+2. Search slide-strategies.csv → Get strategy + emotion beats
+        ↓
+3. For each slide:
+   a. Query slide-layout-logic.csv → layout + break_pattern
+   b. Query slide-typography.csv → type scale
+   c. Query slide-color-logic.csv → color treatment
+   d. Query slide-backgrounds.csv → image if needed
+   e. Apply animation class from slide-animations.css
+        ↓
+4. Generate HTML with design tokens
+        ↓
+5. Validate with slide-token-validator.py
+```
+
+### Pattern Breaking (Duarte Sparkline)
+
+Premium decks alternate between emotions for engagement:
+```
+"What Is" (frustration) ↔ "What Could Be" (hope)
+```
+
+System calculates pattern breaks at 1/3 and 2/3 positions.
+
+### Slide Requirements
+
+**ALL slides MUST:**
+1. Import `assets/design-tokens.css` - single source of truth
+2. Use CSS variables: `var(--color-primary)`, `var(--slide-bg)`, etc.
+3. Use Chart.js for charts (NOT CSS-only bars)
+4. Include navigation (keyboard arrows, click, progress bar)
+5. Center align content
+6. Focus on persuasion/conversion
+
+### Chart.js Integration
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>
+
+<canvas id="revenueChart"></canvas>
+<script>
+new Chart(document.getElementById('revenueChart'), {
+    type: 'line',
+    data: {
+        labels: ['Sep', 'Oct', 'Nov', 'Dec'],
+        datasets: [{
+            data: [5, 12, 28, 45],
+            borderColor: '#FF6B6B',  // Use brand coral
+            backgroundColor: 'rgba(255, 107, 107, 0.1)',
+            fill: true,
+            tension: 0.4
+        }]
+    }
+});
+</script>
+```
+
+### Token Compliance
+
+```css
+/* CORRECT - uses token */
+background: var(--slide-bg);
+color: var(--color-primary);
+font-family: var(--typography-font-heading);
+
+/* WRONG - hardcoded */
+background: #0D0D0D;
+color: #FF6B6B;
+font-family: 'Space Grotesk';
+```
+
+### Reference Implementation
+
+Working example with all features:
+```
+assets/designs/slides/claudekit-pitch-251223.html
+```
+
+### Command
+
+```bash
+/slides:create "10-slide investor pitch for ClaudeKit Marketing"
+```
+
+## Best Practices
+
+1. Never use raw hex in components - always reference tokens
+2. Semantic layer enables theme switching (light/dark)
+3. Component tokens enable per-component customization
+4. Use HSL format for opacity control
+5. Document every token's purpose
+6. **Slides must import design-tokens.css and use var() exclusively**