@champpaba/claude-agent-kit 1.1.0 → 1.1.1

package/.claude/contexts/design/index.md

@@ -0,0 +1,290 @@
+# Design System Hub
+
+> 🎯 **Purpose**: Design Principal Index - Guide all design decisions with proper context
+
+---
+
+## 🎨 IMPORTANT: Style Guide Priority System
+
+**uxui-frontend agents MUST check this priority order:**
+
+### Priority 1: Project-Specific Style Guide (Highest)
+```
+design-system/STYLE_GUIDE.md
+```
+
+**If this file exists:**
+- ✅ Use STYLE_GUIDE.md as **PRIMARY source of truth**
+- Contains: Complete design system (colors, typography, spacing, components)
+- Generated by: `/designsetup` command (from reference/codebase/AI)
+- **DO NOT** override with universal principles below
+
+**If this file does NOT exist:**
+- ⚠️ Fallback to Priority 2 (universal principles)
+- 💡 Suggest user run: `/designsetup`
+
+### Priority 2: Universal Design Principles (Fallback)
+```
+.claude/contexts/design/*.md (this directory)
+```
+
+**Use these when:**
+- No STYLE_GUIDE.md exists
+- Need general design theory
+- Understanding design concepts (box thinking, color theory)
+
+### Priority 3: Legacy Project Tokens (Deprecated)
+```
+.claude/contexts/domain/[project]/design-tokens.md
+```
+
+**Note:** This is being replaced by STYLE_GUIDE.md
+
+---
+
+## 🧠 Design Decision Framework
+
+**Before ANY design recommendation, ask:**
+
+1. **Do we have a style guide?**
+   - Check: `design-system/STYLE_GUIDE.md`
+   - If YES → Use it (Priority 1)
+   - If NO → Use universal principles (Priority 2)
+
+2. **What type of decision?**
+   - Color/Palette
+   - Layout/Spacing
+   - Depth/Shadows
+   - Typography
+   - Component Structure
+   - Box Relationships
+
+3. **What context?**
+   - Project-specific style guide (STYLE_GUIDE.md)
+   - Universal design principles (this directory)
+
+4. **What's the user goal?**
+   - Usability (Can users complete tasks easily?)
+   - Accessibility (Can ALL users access content?)
+   - Aesthetics (Does it look professional and trustworthy?)
+
+**Then route to:**
+- **Color** → See `color-theory.md` for harmony, contrast, accessibility
+- **Layout** → See `layout.md` + `box-thinking.md` for structure and flow
+- **Depth** → See `shadows.md` for elevation and layering
+- **Typography** → See `typography.md` for hierarchy and readability
+- **Spacing** → See `spacing.md` for consistent gaps and rhythm
+- **Responsive** → See `responsive.md` for behavior across devices
+- **Accessibility** → See `accessibility.md` for WCAG compliance
+
+---
+
+## 📦 Box Thinking Framework
+
+**Core Principle:** Every element is a box. Understand box relationships before writing code.
+
+### Box Analysis Method
+
+> "Before building or improving this layout, take a step back and observe **every element on the screen** — navigation, headers, cards, buttons, sidebars, text blocks — everything that occupies space. Imagine **each of them as a box** and describe how they relate to one another: which boxes contain others, how they align, and how space flows between them."
+
+### Box Relationship Patterns
+
+- **Container Boxes**: What contains what (hierarchy)
+- **Adjacent Boxes**: Side-by-side relationships
+- **Nested Boxes**: Parent-child relationships
+- **Space Flow**: How space flows between boxes
+- **Alignment Logic**: How boxes position relative to each other
+
+### Box Behavior in Responsive Context
+
+> "Now, describe how this layout behaves when the screen or container changes size. Think in terms of movement, proportion, and flow, not pixels. Which sections move above or below others? Which expand, and which step back?"
+
+**Box Movement Patterns:**
+- **Stacking**: Horizontal → Vertical arrangement
+- **Merging**: Multiple boxes → Single unified box
+- **Prioritizing**: Important boxes maintain prominence
+- **Compressing**: Boxes shrink but maintain relationships
+- **Reorganizing**: Smart rules for box rearrangement
+
+**See `box-thinking.md` for complete framework.**
+
+---
+
+## 🎨 Universal Design Principles
+
+### Color System
+
+**60-30-10 Rule** (Industry standard for balanced color distribution)
+- **60% Dominant**: Neutral colors (backgrounds, text) - Creates calm foundation
+- **30% Secondary**: Supporting colors (secondary brand color, muted tones)
+- **10% Accent**: Primary brand color for emphasis (CTAs, highlights)
+
+**Color Harmony Types:**
+- **Monochromatic**: Variations of single hue (most harmonious)
+- **Complementary**: Opposite colors on color wheel (high contrast)
+- **Analogous**: Adjacent colors (cohesive, natural)
+- **Triadic**: 3 colors evenly spaced (vibrant, balanced)
+
+**Accessibility Requirements:**
+- Text on background: Minimum 4.5:1 contrast (WCAG AA)
+- Large text (18pt+): Minimum 3:1 contrast
+- UI components: Minimum 3:1 contrast
+
+**See `color-theory.md` for complete color system.**
+
+---
+
+### Spacing System
+
+**Base Unit Approach:**
+```css
+--spacing: 0.25rem;  /* 4px - Base spacing unit */
+```
+
+**Scale (Multiples of base):**
+- `1x` (0.25rem / 4px) - Tiny gaps
+- `2x` (0.5rem / 8px) - Small gaps
+- `3x` (0.75rem / 12px) - Medium gaps
+- `4x` (1rem / 16px) - Default gaps
+- `6x` (1.5rem / 24px) - Large gaps
+- `8x` (2rem / 32px) - XL gaps
+- `12x` (3rem / 48px) - XXL gaps
+
+**See `spacing.md` for complete spacing system.**
+
+---
+
+### Shadow System
+
+**3-Tier Elevation:**
+
+**Level 1: Subtle** (Cards, Inputs)
+```css
+--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+```
+
+**Level 2: Medium** (Dropdowns, Modals)
+```css
+--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1),
+             0 2px 4px -2px rgb(0 0 0 / 0.1);
+```
+
+**Level 3: Large** (Overlays, Popovers)
+```css
+--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1),
+             0 4px 6px -4px rgb(0 0 0 / 0.1);
+```
+
+**See `shadows.md` for complete shadow system.**
+
+---
+
+### Typography Hierarchy
+
+**5-Level System:**
+
+1. **H1** (Display) - 2.5rem (40px) - Hero titles
+2. **H2** (Headline) - 2rem (32px) - Section titles
+3. **H3** (Title) - 1.5rem (24px) - Subsection titles
+4. **Body** (Text) - 1rem (16px) - Paragraphs, content
+5. **Small** (Caption) - 0.875rem (14px) - Labels, metadata
+
+**Line Height Rules:**
+- Headings: 1.2-1.3 (tight for impact)
+- Body text: 1.5-1.6 (comfortable reading)
+- Small text: 1.4-1.5 (legible but compact)
+
+**See `typography.md` for complete typography system.**
+
+---
+
+### Responsive Behavior
+
+**3-Tier Breakpoint System:**
+
+```css
+/* Mobile-first approach */
+--breakpoint-sm: 640px;   /* Tablets */
+--breakpoint-md: 768px;   /* Small laptops */
+--breakpoint-lg: 1024px;  /* Desktops */
+```
+
+**Layout Flow Rules:**
+- Mobile (< 640px): Stack all boxes vertically
+- Tablet (640-1024px): Partial side-by-side, smart stacking
+- Desktop (> 1024px): Full multi-column layouts
+
+**See `responsive.md` for complete responsive patterns.**
+
+---
+
+## 🔍 When to Use Each File
+
+| Need | File | Purpose |
+|------|------|---------|
+| Choose colors for new feature | `color-theory.md` | Color harmony, contrast, accessibility |
+| Set spacing between elements | `spacing.md` | Consistent gaps, rhythm, whitespace |
+| Add shadows to cards/modals | `shadows.md` | Elevation, depth, layering |
+| Define text hierarchy | `typography.md` | Font sizes, weights, line heights |
+| Plan component layout | `layout.md` + `box-thinking.md` | Box structure, alignment |
+| Make responsive design | `responsive.md` | Breakpoints, movement patterns |
+| Ensure accessibility | `accessibility.md` | WCAG compliance, keyboard nav |
+
+---
+
+## 🎯 Quick Start Checklist
+
+**For every new UI component:**
+
+- [ ] **Box Structure** - Identify all boxes and their relationships
+- [ ] **Color** - Apply 60-30-10 rule, check contrast (4.5:1 min)
+- [ ] **Spacing** - Use multiples of base unit (0.25rem)
+- [ ] **Typography** - Follow 5-level hierarchy
+- [ ] **Shadows** - Use 3-tier elevation system
+- [ ] **Responsive** - Test all 3 breakpoints (mobile, tablet, desktop)
+- [ ] **Accessibility** - Keyboard navigation, screen reader support
+
+---
+
+## 📖 Design System Files
+
+```
+design/
+├── index.md (this file)      # Design hub and decision framework
+├── color-theory.md           # Color harmony, contrast, accessibility
+├── spacing.md                # Spacing scale, rhythm, whitespace
+├── shadows.md                # 3-tier shadow system
+├── typography.md             # Font hierarchy, sizes, weights
+├── layout.md                 # Layout patterns, alignment
+├── responsive.md             # Breakpoints, responsive behavior
+├── box-thinking.md           # Box analysis framework
+└── accessibility.md          # WCAG compliance, a11y patterns
+```
+
+---
+
+## 🔗 Project-Specific Design
+
+**Universal principles (this directory) + Project tokens (domain folder)**
+
+**Project design tokens go in:**
+```
+.claude/contexts/domain/[project-name]/design-tokens.md
+```
+
+**Example:**
+```css
+/* domain/ecommerce/design-tokens.md */
+--primary: #3B82F6;        /* Blue - Trust */
+--secondary: #10B981;      /* Green - Success */
+--accent: #F59E0B;         /* Amber - Urgency */
+```
+
+**How agents use this:**
+1. Load universal principles (design/)
+2. Load project tokens (domain/[project]/)
+3. Apply principles with project colors
+
+---
+
+**💡 Remember: Think in boxes, design with purpose, implement with consistency!**

package/.claude/contexts/design/layout.md

@@ -0,0 +1,400 @@
+# Layout Patterns
+
+> **Purpose:** Common layout structures and alignment strategies
+
+---
+
+## Core Layout Principles
+
+1. **Box Model First** - Understand all elements as boxes (see `box-thinking.md`)
+2. **Flex for 1D** - Use flexbox for single-axis layouts (rows or columns)
+3. **Grid for 2D** - Use CSS Grid for multi-axis layouts (rows AND columns)
+4. **Responsive by Default** - Design mobile-first, enhance for larger screens
+
+---
+
+## Common Layout Patterns
+
+### 1. Stack (Vertical)
+
+**Use for:** Form fields, article content, vertical lists
+
+```css
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);  /* 16px */
+}
+
+/* Variants */
+.stack-tight {
+  gap: var(--spacing-2);  /* 8px */
+}
+
+.stack-loose {
+  gap: var(--spacing-8);  /* 32px */
+}
+```
+
+**HTML:**
+```html
+<div class="stack">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+---
+
+### 2. Inline (Horizontal)
+
+**Use for:** Button groups, breadcrumbs, navigation
+
+```css
+.inline {
+  display: flex;
+  flex-direction: row;
+  gap: var(--spacing-4);  /* 16px */
+  align-items: center;  /* Vertical centering */
+}
+
+/* Variants */
+.inline-start {
+  justify-content: flex-start;  /* Left-aligned */
+}
+
+.inline-center {
+  justify-content: center;  /* Centered */
+}
+
+.inline-end {
+  justify-content: flex-end;  /* Right-aligned */
+}
+
+.inline-between {
+  justify-content: space-between;  /* Space between items */
+}
+```
+
+---
+
+### 3. Sidebar Layout
+
+**Use for:** Dashboard, admin panels, documentation
+
+```css
+.sidebar-layout {
+  display: grid;
+  grid-template-columns: 250px 1fr;  /* Fixed sidebar + fluid main */
+  gap: var(--spacing-6);  /* 24px */
+  min-height: 100vh;
+}
+
+@media (max-width: 768px) {
+  .sidebar-layout {
+    grid-template-columns: 1fr;  /* Stack on mobile */
+  }
+}
+```
+
+**HTML:**
+```html
+<div class="sidebar-layout">
+  <aside class="sidebar">Sidebar</aside>
+  <main class="main-content">Main Content</main>
+</div>
+```
+
+---
+
+### 4. Holy Grail Layout
+
+**Use for:** Classic web pages (header, sidebar, content, footer)
+
+```css
+.holy-grail {
+  display: grid;
+  grid-template-areas:
+    "header header header"
+    "sidebar main aside"
+    "footer footer footer";
+  grid-template-columns: 200px 1fr 200px;
+  grid-template-rows: auto 1fr auto;
+  min-height: 100vh;
+  gap: var(--spacing-4);
+}
+
+.header { grid-area: header; }
+.sidebar { grid-area: sidebar; }
+.main { grid-area: main; }
+.aside { grid-area: aside; }
+.footer { grid-area: footer; }
+
+@media (max-width: 1024px) {
+  .holy-grail {
+    grid-template-areas:
+      "header"
+      "main"
+      "sidebar"
+      "aside"
+      "footer";
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+---
+
+### 5. Card Grid
+
+**Use for:** Product listings, portfolios, image galleries
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: var(--spacing-6);  /* 24px */
+}
+
+/* Auto-fill: Creates as many columns as fit */
+/* minmax(300px, 1fr): Min 300px, max equal width */
+```
+
+**Responsive Behavior:**
+- Mobile: 1 column
+- Tablet: 2 columns
+- Desktop: 3-4 columns (auto-adjusts)
+
+---
+
+### 6. Center Element
+
+**Use for:** Modals, empty states, landing hero sections
+
+```css
+/* Flexbox method */
+.center-flex {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 100vh;
+}
+
+/* Grid method */
+.center-grid {
+  display: grid;
+  place-items: center;  /* Shorthand for center both axes */
+  min-height: 100vh;
+}
+
+/* Absolute positioning (legacy) */
+.center-absolute {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+```
+
+---
+
+### 7. Header with Navigation
+
+**Use for:** Site headers, app nav bars
+
+```css
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: var(--spacing-4) var(--spacing-6);
+  background: white;
+  box-shadow: var(--shadow-sm);
+}
+
+.nav {
+  display: flex;
+  gap: var(--spacing-6);
+}
+
+@media (max-width: 768px) {
+  .nav {
+    display: none;  /* Hide on mobile (use hamburger menu) */
+  }
+}
+```
+
+---
+
+### 8. Container (Max-Width)
+
+**Use for:** Constraining content width for readability
+
+```css
+.container {
+  max-width: 1280px;  /* Desktop max width */
+  margin-left: auto;
+  margin-right: auto;
+  padding-left: var(--spacing-6);  /* 24px */
+  padding-right: var(--spacing-6);
+}
+
+/* Variants */
+.container-narrow {
+  max-width: 768px;  /* Blog posts, forms */
+}
+
+.container-wide {
+  max-width: 1536px;  /* Dashboards, wide layouts */
+}
+```
+
+**Optimal Reading Widths:**
+- Text content: 65-75 characters per line (~768px)
+- Dashboard: 1280-1536px
+- Full-width: No max-width (use sparingly)
+
+---
+
+## Alignment Strategies
+
+### Flexbox Alignment
+
+**Main Axis (justify-content):**
+```css
+.flex-start { justify-content: flex-start; }    /* Left/Top */
+.flex-center { justify-content: center; }       /* Center */
+.flex-end { justify-content: flex-end; }        /* Right/Bottom */
+.flex-between { justify-content: space-between; } /* Space between */
+.flex-around { justify-content: space-around; }  /* Space around */
+```
+
+**Cross Axis (align-items):**
+```css
+.items-start { align-items: flex-start; }   /* Top/Left */
+.items-center { align-items: center; }      /* Center */
+.items-end { align-items: flex-end; }       /* Bottom/Right */
+.items-stretch { align-items: stretch; }    /* Stretch to fill */
+```
+
+### Grid Alignment
+
+```css
+/* Place items (both axes) */
+.place-center { place-items: center; }
+.place-start { place-items: start; }
+.place-end { place-items: end; }
+
+/* Justify/align individual item */
+.justify-self-center { justify-self: center; }
+.align-self-center { align-self: center; }
+```
+
+---
+
+## Z-Index Layering
+
+**Standard Z-Index Scale:**
+
+```css
+:root {
+  --z-base: 1;          /* Base content */
+  --z-dropdown: 10;     /* Dropdowns, popovers */
+  --z-sticky: 20;       /* Sticky headers */
+  --z-modal-backdrop: 100;  /* Modal overlays */
+  --z-modal: 110;       /* Modal content */
+  --z-popover: 200;     /* Tooltips, toasts */
+  --z-notification: 1000;   /* Notifications (top layer) */
+}
+```
+
+**Usage:**
+```css
+.content { z-index: var(--z-base); }
+.dropdown { z-index: var(--z-dropdown); }
+.modal-backdrop { z-index: var(--z-modal-backdrop); }
+.modal { z-index: var(--z-modal); }
+.toast { z-index: var(--z-notification); }
+```
+
+---
+
+## Aspect Ratios
+
+**Use for:** Images, videos, cards with consistent proportions
+
+```css
+/* Modern approach (aspect-ratio property) */
+.aspect-square { aspect-ratio: 1 / 1; }    /* 1:1 */
+.aspect-video { aspect-ratio: 16 / 9; }    /* 16:9 */
+.aspect-portrait { aspect-ratio: 3 / 4; }  /* 3:4 */
+
+/* Legacy approach (padding-bottom hack) */
+.aspect-ratio-16-9 {
+  position: relative;
+  padding-bottom: 56.25%;  /* 9/16 = 0.5625 */
+}
+
+.aspect-ratio-16-9 > * {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+```
+
+---
+
+## Best Practices
+
+### DO:
+- ✅ Use flexbox for 1D layouts
+- ✅ Use grid for 2D layouts
+- ✅ Design mobile-first (stack by default)
+- ✅ Use semantic HTML (header, main, aside, footer)
+- ✅ Constrain content width for readability
+- ✅ Use CSS custom properties for spacing
+- ✅ Test on all screen sizes
+
+### DON'T:
+- ❌ Use floats for layouts (legacy technique)
+- ❌ Use fixed pixel widths (not responsive)
+- ❌ Nest too many layout containers (keep it flat)
+- ❌ Forget semantic HTML
+- ❌ Use arbitrary z-index values (100, 9999)
+- ❌ Overcomplicate layouts (KISS principle)
+
+---
+
+## Quick Reference
+
+**Layout Techniques:**
+| Pattern | Technique | Use Case |
+|---------|-----------|----------|
+| Stack | Flexbox (column) | Vertical lists, forms |
+| Inline | Flexbox (row) | Horizontal groups, nav |
+| Sidebar | Grid (2 columns) | Admin panels, docs |
+| Card Grid | Grid (auto-fill) | Products, galleries |
+| Center | Flexbox/Grid | Modals, empty states |
+
+**Container Widths:**
+| Type | Max Width | Use Case |
+|------|-----------|----------|
+| Narrow | 768px | Blog posts, forms |
+| Default | 1280px | Standard pages |
+| Wide | 1536px | Dashboards |
+| Full | none | Landing pages |
+
+**Z-Index Layers:**
+| Layer | Z-Index | Element Type |
+|-------|---------|--------------|
+| Base | 1 | Content |
+| Dropdown | 10 | Dropdowns, popovers |
+| Modal | 100-110 | Modals, overlays |
+| Notification | 1000 | Toasts, alerts |
+
+---
+
+**💡 Remember:** Good layout is invisible. Users should focus on content, not structure!