@champpaba/claude-agent-kit 1.1.0 → 1.4.0

package/.claude/contexts/design/box-thinking.md

@@ -0,0 +1,566 @@
+# Box Thinking Framework
+
+> **Purpose:** Analyze and plan layouts by thinking of all elements as boxes
+
+---
+
+## ⚠️ Context Note
+
+**This file contains layout analysis METHODOLOGY** (applies to all projects).
+
+**If your project has a STYLE_GUIDE.md with reference screenshot:**
+→ View the screenshot and apply Box Thinking to understand its layout
+→ Use STYLE_GUIDE.md spacing values when implementing boxes
+
+Box Thinking = **How to think about layout**
+STYLE_GUIDE.md = **What values to use**
+
+---
+
+## Core Philosophy
+
+**Every element on a screen is a box.**
+
+Before writing any layout code, **observe and describe**:
+1. What boxes exist?
+2. How do boxes relate to each other?
+3. How do boxes move when resized?
+
+---
+
+## The Box Analysis Method
+
+### Step 1: Identify All Boxes
+
+> "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**."
+
+**Example: E-commerce Product Page**
+
+```
+Boxes identified:
+├─ Header Box (navigation, logo, cart)
+├─ Hero Box (product image + title)
+├─ Sidebar Box (filters, categories)
+├─ Main Content Box
+│  ├─ Product Grid Box
+│  │  ├─ Product Card Box 1
+│  │  ├─ Product Card Box 2
+│  │  └─ Product Card Box 3
+│  └─ Pagination Box
+└─ Footer Box (links, copyright)
+```
+
+---
+
+### Step 2: Describe Box Relationships
+
+**5 Types of Relationships:**
+
+#### 1. Container Boxes (Hierarchy)
+**What contains what?**
+
+```
+Header Box CONTAINS:
+├─ Logo Box
+├─ Navigation Box (contains menu items)
+└─ User Actions Box (contains cart, profile)
+
+Product Card Box CONTAINS:
+├─ Image Box
+├─ Title Box
+├─ Price Box
+└─ Button Box
+```
+
+**Code Implication:**
+```html
+<header class="header-box">
+  <div class="logo-box">Logo</div>
+  <nav class="nav-box">
+    <a>Home</a>
+    <a>Products</a>
+  </nav>
+  <div class="actions-box">
+    <button>Cart</button>
+  </div>
+</header>
+```
+
+---
+
+#### 2. Adjacent Boxes (Side-by-Side)
+**Which boxes sit next to each other?**
+
+```
+Desktop Layout:
+[Sidebar Box] [Main Content Box]
+
+Header Layout:
+[Logo Box] [Nav Box] [Actions Box]
+```
+
+**Code Implication:**
+```css
+.header-box {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: 250px 1fr;
+}
+```
+
+---
+
+#### 3. Nested Boxes (Parent-Child)
+**How deep does nesting go?**
+
+```
+Page Box
+└─ Section Box
+   └─ Container Box
+      └─ Card Box
+         └─ Content Box
+            ├─ Title Box
+            └─ Text Box
+```
+
+**⚠️ Warning:** Too much nesting = complex CSS
+**Rule:** Max 3-4 levels deep
+
+---
+
+#### 4. Space Flow (Gaps Between Boxes)
+**How does space flow between boxes?**
+
+```
+Vertical Flow (Stack):
+┌─────────────┐
+│ Header Box  │ ← 16px gap ↓
+├─────────────┤
+│ Hero Box    │ ← 24px gap ↓
+├─────────────┤
+│ Content Box │ ← 24px gap ↓
+└─────────────┘
+
+Horizontal Flow (Inline):
+[Logo] ←20px→ [Nav] ←20px→ [Actions]
+```
+
+**Code Implication:**
+```css
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-6);  /* 24px */
+}
+
+.inline {
+  display: flex;
+  gap: var(--spacing-5);  /* 20px */
+}
+```
+
+---
+
+#### 5. Alignment Logic
+**How do boxes position relative to each other?**
+
+```
+Top-aligned:
+┌──┐  ┌────┐  ┌──────┐
+│  │  │    │  │      │
+│  │  │    │  └──────┘
+│  │  └────┘
+└──┘
+
+Center-aligned:
+     ┌────┐
+┌──┐ │    │  ┌──────┐
+│  │ │    │  │      │
+└──┘ │    │  └──────┘
+     └────┘
+
+Bottom-aligned:
+┌──┐
+│  │  ┌────┐
+│  │  │    │  ┌──────┐
+└──┘  └────┘  └──────┘
+```
+
+**Code Implication:**
+```css
+.align-top { align-items: flex-start; }
+.align-center { align-items: center; }
+.align-bottom { align-items: flex-end; }
+```
+
+---
+
+## Box Behavior in Responsive Context
+
+### Question to Ask:
+
+> "How does this layout behave 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?"
+
+---
+
+### 4 Box Movement Patterns
+
+#### 1. Stacking (Horizontal → Vertical)
+
+**Desktop (Wide Screen):**
+```
+┌────────────┬──────────────────┐
+│ Sidebar    │ Main Content     │
+│ Box        │ Box              │
+└────────────┴──────────────────┘
+```
+
+**Mobile (Narrow Screen):**
+```
+┌──────────────────┐
+│ Main Content Box │
+├──────────────────┤
+│ Sidebar Box      │
+└──────────────────┘
+```
+
+**Code:**
+```css
+.container {
+  display: flex;
+  gap: var(--spacing-6);
+}
+
+@media (max-width: 768px) {
+  .container {
+    flex-direction: column;
+  }
+}
+```
+
+---
+
+#### 2. Merging (Multiple → Single)
+
+**Desktop (3 columns):**
+```
+┌─────┬─────┬─────┐
+│ Box │ Box │ Box │
+│  1  │  2  │  3  │
+└─────┴─────┴─────┘
+```
+
+**Tablet (2 columns):**
+```
+┌─────────┬─────────┐
+│ Box 1   │ Box 2   │
+├─────────┴─────────┤
+│ Box 3             │
+└───────────────────┘
+```
+
+**Mobile (1 column):**
+```
+┌───────────────────┐
+│ Box 1             │
+├───────────────────┤
+│ Box 2             │
+├───────────────────┤
+│ Box 3             │
+└───────────────────┘
+```
+
+**Code:**
+```css
+.grid {
+  display: grid;
+  gap: var(--spacing-4);
+}
+
+/* Desktop: 3 columns */
+@media (min-width: 1024px) {
+  .grid { grid-template-columns: repeat(3, 1fr); }
+}
+
+/* Tablet: 2 columns */
+@media (min-width: 640px) and (max-width: 1023px) {
+  .grid { grid-template-columns: repeat(2, 1fr); }
+}
+
+/* Mobile: 1 column */
+@media (max-width: 639px) {
+  .grid { grid-template-columns: 1fr; }
+}
+```
+
+---
+
+#### 3. Prioritizing (Show Important, Hide Secondary)
+
+**Desktop (Show All):**
+```
+┌─────┬──────────┬────────┬─────┐
+│Logo │ Nav      │ Search │ User│
+└─────┴──────────┴────────┴─────┘
+```
+
+**Mobile (Hide Nav, Show Hamburger):**
+```
+┌─────┬──────────────┬─────┐
+│Logo │              │  ☰  │
+└─────┴──────────────┴─────┘
+```
+
+**Code:**
+```css
+.nav { display: flex; }
+.hamburger { display: none; }
+
+@media (max-width: 768px) {
+  .nav { display: none; }
+  .hamburger { display: block; }
+}
+```
+
+---
+
+#### 4. Compressing (Shrink, Maintain Relationships)
+
+**Desktop (Generous Spacing):**
+```
+┌─────────────────────────┐
+│                         │
+│   Hero Box              │ ← 48px padding
+│                         │
+└─────────────────────────┘
+```
+
+**Mobile (Compact Spacing):**
+```
+┌───────────────┐
+│ Hero Box      │ ← 16px padding
+└───────────────┘
+```
+
+**Code:**
+```css
+.hero {
+  padding: var(--spacing-12);  /* 48px on desktop */
+}
+
+@media (max-width: 768px) {
+  .hero {
+    padding: var(--spacing-4);  /* 16px on mobile */
+  }
+}
+```
+
+---
+
+## Box Implementation Rules
+
+### Margins (Space Outside Box)
+
+**Use for:** Pushing boxes away from each other
+
+```css
+.box {
+  margin-bottom: var(--spacing-6);  /* 24px gap below */
+}
+
+/* Or use gap in parent */
+.container {
+  display: flex;
+  gap: var(--spacing-6);  /* 24px between all children */
+}
+```
+
+**Prefer `gap` over `margin`** (cleaner, more predictable)
+
+---
+
+### Padding (Space Inside Box)
+
+**Use for:** Creating breathing room inside a box
+
+```css
+.card-box {
+  padding: var(--spacing-6);  /* 24px inside box */
+}
+
+.button-box {
+  padding: var(--spacing-2) var(--spacing-4);  /* 8px top/bottom, 16px left/right */
+}
+```
+
+---
+
+### Borders (Box Boundaries)
+
+**Use sparingly** - Prefer color/shadow for separation
+
+```css
+/* ❌ Heavy borders everywhere */
+.box {
+  border: 2px solid black;
+}
+
+/* ✅ Subtle separation */
+.box {
+  border: 1px solid rgb(0 0 0 / 0.1);
+  box-shadow: var(--shadow-sm);
+}
+```
+
+**Alternative:** Use background color contrast instead of borders
+
+---
+
+### Consistent Gaps
+
+**Always use spacing scale:**
+
+```css
+/* ✅ Good */
+gap: var(--spacing-4);  /* 16px */
+gap: var(--spacing-6);  /* 24px */
+
+/* ❌ Bad */
+gap: 17px;  /* Arbitrary value */
+```
+
+---
+
+## Practical Example: Product Card
+
+### Box Analysis
+
+**Identify Boxes:**
+```
+Product Card Box
+├─ Image Box
+├─ Content Box
+│  ├─ Title Box
+│  ├─ Price Box
+│  └─ Description Box
+└─ Action Box
+   └─ Button Box
+```
+
+**Relationships:**
+- Container: Card contains Image, Content, Action
+- Nested: Content contains Title, Price, Description
+- Vertical Flow: Image → Content → Action
+- Gaps: 16px between sections
+
+**Responsive Behavior:**
+- Desktop: Image left, Content right (side-by-side)
+- Mobile: Image top, Content bottom (stacked)
+
+---
+
+### Implementation
+
+```html
+<div class="product-card-box">
+  <div class="image-box">
+    <img src="product.jpg" alt="Product">
+  </div>
+  <div class="content-box">
+    <h3 class="title-box">Product Title</h3>
+    <p class="price-box">$99.99</p>
+    <p class="description-box">Description text</p>
+  </div>
+  <div class="action-box">
+    <button class="button-box">Add to Cart</button>
+  </div>
+</div>
+```
+
+```css
+/* Box structure */
+.product-card-box {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);  /* 16px between sections */
+  padding: var(--spacing-6);  /* 24px inside card */
+  border-radius: var(--spacing-2);
+  box-shadow: var(--shadow-sm);
+}
+
+/* Content box (nested) */
+.content-box {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);  /* 8px between title/price/desc */
+}
+
+/* Responsive: side-by-side on desktop */
+@media (min-width: 768px) {
+  .product-card-box {
+    flex-direction: row;
+    align-items: center;
+  }
+
+  .image-box {
+    flex-shrink: 0;
+    width: 200px;
+  }
+
+  .content-box {
+    flex: 1;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### DO:
+- ✅ Identify all boxes before coding
+- ✅ Describe relationships in plain language
+- ✅ Think in terms of movement (stack, merge, compress)
+- ✅ Use consistent gaps (spacing scale)
+- ✅ Keep nesting shallow (max 3-4 levels)
+- ✅ Test responsive behavior on real devices
+
+### DON'T:
+- ❌ Jump straight to code without box analysis
+- ❌ Use arbitrary spacing values
+- ❌ Nest boxes too deeply (> 4 levels)
+- ❌ Forget responsive behavior
+- ❌ Think in pixels (think in relationships)
+
+---
+
+## Quick Reference
+
+**Box Analysis Questions:**
+1. What boxes exist? (List all elements)
+2. What contains what? (Hierarchy)
+3. What's next to what? (Adjacent)
+4. How does space flow? (Gaps)
+5. How do boxes align? (Top/Center/Bottom)
+6. How do boxes move? (Stack/Merge/Compress)
+
+**Box Implementation:**
+- **Margins**: Space outside (prefer `gap`)
+- **Padding**: Space inside
+- **Borders**: Use sparingly (prefer shadows)
+- **Gaps**: Use spacing scale (4, 8, 16, 24, 32, 48px)
+
+**Responsive Patterns:**
+- **Stacking**: Horizontal → Vertical
+- **Merging**: 3 cols → 2 cols → 1 col
+- **Prioritizing**: Show essential, hide secondary
+- **Compressing**: Reduce spacing, maintain structure
+
+---
+
+**💡 Remember:** If you can't describe the boxes and their relationships, you can't build the layout!