@champpaba/claude-agent-kit 1.0.0

package/template/.claude/contexts/design/typography.md

@@ -0,0 +1,465 @@
+# Typography System
+
+> **Purpose:** Consistent type hierarchy, readability, and typographic rhythm
+
+---
+
+## Type Scale (5-Level Hierarchy)
+
+**Core Principle:** Use a modular scale for harmonious font sizes
+
+### Standard Type Scale
+
+| Level | Token | Size (rem) | Pixels | Use Case |
+|-------|-------|------------|--------|----------|
+| **H1** | `text-4xl` | 2.5rem | 40px | Hero titles, landing page headers |
+| **H2** | `text-3xl` | 2rem | 32px | Page titles, section headers |
+| **H3** | `text-2xl` | 1.5rem | 24px | Subsection titles, card headers |
+| **Body** | `text-base` | 1rem | 16px | Paragraphs, content, buttons |
+| **Small** | `text-sm` | 0.875rem | 14px | Labels, captions, metadata |
+
+### Extended Scale (for flexibility)
+
+```css
+:root {
+  /* Tiny */
+  --text-xs: 0.75rem;    /* 12px - Fine print, badges */
+
+  /* Small */
+  --text-sm: 0.875rem;   /* 14px - Labels, captions */
+
+  /* Base */
+  --text-base: 1rem;     /* 16px - Body text */
+
+  /* Medium */
+  --text-lg: 1.125rem;   /* 18px - Emphasized body text */
+
+  /* Large */
+  --text-xl: 1.25rem;    /* 20px - Small headings */
+  --text-2xl: 1.5rem;    /* 24px - H3 */
+  --text-3xl: 2rem;      /* 32px - H2 */
+  --text-4xl: 2.5rem;    /* 40px - H1 */
+
+  /* Extra Large */
+  --text-5xl: 3rem;      /* 48px - Hero (desktop) */
+  --text-6xl: 3.75rem;   /* 60px - Display (marketing) */
+}
+```
+
+---
+
+## Font Weights
+
+**Standard Weights:**
+
+| Weight | Value | Use Case |
+|--------|-------|----------|
+| **Light** | 300 | Rarely used (decorative only) |
+| **Regular** | 400 | Body text, paragraphs |
+| **Medium** | 500 | Emphasized text, labels |
+| **Semibold** | 600 | Buttons, important labels |
+| **Bold** | 700 | Headings (H1-H3), strong emphasis |
+| **Extrabold** | 800 | Hero titles (rare) |
+
+**Implementation:**
+```css
+:root {
+  --font-weight-light: 300;
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --font-weight-extrabold: 800;
+}
+```
+
+**Usage Guidelines:**
+- ✅ Body text: Regular (400)
+- ✅ Headings: Bold (700)
+- ✅ Buttons: Semibold (600) or Medium (500)
+- ✅ Labels: Medium (500)
+- ❌ Avoid Light (300) for body text (low readability)
+- ❌ Avoid Extrabold (800) except for hero titles
+
+---
+
+## Line Height (Leading)
+
+**Rule:** Tighter for headings, looser for body text
+
+### Standard Line Heights
+
+| Element Type | Line Height | Ratio | Use Case |
+|--------------|-------------|-------|----------|
+| **Headings** | 1.2 | Tight | Visual impact, hierarchy |
+| **Headings** | 1.3 | Medium | Balance (alternative) |
+| **Body Text** | 1.5 | Comfortable | Readability, long-form |
+| **Body Text** | 1.6 | Loose | Extra comfort (rare) |
+| **Small Text** | 1.4 | Compact | Labels, captions |
+| **Code** | 1.7 | Extra space | Technical content |
+
+**Implementation:**
+```css
+:root {
+  --leading-tight: 1.2;      /* Headings */
+  --leading-snug: 1.3;       /* Headings (alternative) */
+  --leading-normal: 1.5;     /* Body text */
+  --leading-relaxed: 1.6;    /* Body text (loose) */
+  --leading-loose: 1.7;      /* Code blocks */
+}
+
+h1, h2, h3 {
+  line-height: var(--leading-tight);
+}
+
+p, li {
+  line-height: var(--leading-normal);
+}
+
+code, pre {
+  line-height: var(--leading-loose);
+}
+```
+
+**Why This Matters:**
+- Tight line height (1.2): Headings feel "punchy" and impactful
+- Normal line height (1.5): Body text is comfortable to read
+- Loose line height (1.7): Code is easier to scan
+
+---
+
+## Letter Spacing (Tracking)
+
+**Rule:** Looser for uppercase, tighter for display text
+
+```css
+:root {
+  --tracking-tighter: -0.05em;  /* Large headings */
+  --tracking-tight: -0.025em;   /* H1-H3 */
+  --tracking-normal: 0;         /* Body text */
+  --tracking-wide: 0.025em;     /* Uppercase, small text */
+  --tracking-wider: 0.05em;     /* ALL CAPS */
+  --tracking-widest: 0.1em;     /* Extreme emphasis */
+}
+
+h1 {
+  letter-spacing: var(--tracking-tighter);  /* -0.05em */
+}
+
+.label-uppercase {
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-wide);     /* 0.025em */
+}
+
+.all-caps {
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-wider);    /* 0.05em */
+}
+```
+
+**When to Use:**
+- ✅ Tighter tracking: Large headings (H1, Hero)
+- ✅ Wider tracking: Uppercase text, labels
+- ✅ Normal tracking: Body text, paragraphs
+- ❌ Avoid tight tracking on small text (hard to read)
+
+---
+
+## Font Families
+
+### System Font Stack (Recommended)
+
+**Advantages:**
+- ✅ No web font loading (instant render)
+- ✅ Native OS appearance
+- ✅ Optimal performance
+- ✅ Familiar to users
+
+**Implementation:**
+```css
+:root {
+  /* Sans-serif (default) */
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI",
+               Roboto, "Helvetica Neue", Arial, sans-serif;
+
+  /* Monospace (code) */
+  --font-mono: ui-monospace, "Cascadia Code", "Source Code Pro",
+               Menlo, Monaco, "Courier New", monospace;
+
+  /* Serif (optional) */
+  --font-serif: ui-serif, Georgia, Cambria, "Times New Roman",
+                Times, serif;
+}
+
+body {
+  font-family: var(--font-sans);
+}
+
+code, pre {
+  font-family: var(--font-mono);
+}
+```
+
+### Web Fonts (Optional)
+
+**Popular Choices:**
+- **Inter**: Modern, versatile, excellent readability
+- **Roboto**: Clean, professional, Google's default
+- **Poppins**: Geometric, friendly, modern
+- **Open Sans**: Humanist, neutral, widely used
+- **Lato**: Semi-rounded, approachable
+
+**Implementation (Google Fonts):**
+```html
+<!-- In <head> -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+```css
+:root {
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+}
+```
+
+**⚠️ Performance Considerations:**
+- Use `font-display: swap` to avoid FOIT (Flash of Invisible Text)
+- Limit to 3-4 weights (e.g., 400, 500, 600, 700)
+- Consider variable fonts (fewer requests)
+
+---
+
+## Typographic Hierarchy
+
+### Complete Heading System
+
+```css
+h1 {
+  font-size: var(--text-4xl);        /* 40px */
+  font-weight: var(--font-weight-bold);  /* 700 */
+  line-height: var(--leading-tight);    /* 1.2 */
+  letter-spacing: var(--tracking-tighter); /* -0.05em */
+  margin-bottom: var(--spacing-6);      /* 24px */
+}
+
+h2 {
+  font-size: var(--text-3xl);        /* 32px */
+  font-weight: var(--font-weight-bold);  /* 700 */
+  line-height: var(--leading-tight);    /* 1.2 */
+  letter-spacing: var(--tracking-tight);   /* -0.025em */
+  margin-bottom: var(--spacing-4);      /* 16px */
+}
+
+h3 {
+  font-size: var(--text-2xl);        /* 24px */
+  font-weight: var(--font-weight-semibold); /* 600 */
+  line-height: var(--leading-snug);     /* 1.3 */
+  margin-bottom: var(--spacing-4);      /* 16px */
+}
+
+p {
+  font-size: var(--text-base);       /* 16px */
+  font-weight: var(--font-weight-regular); /* 400 */
+  line-height: var(--leading-normal);   /* 1.5 */
+  margin-bottom: var(--spacing-4);      /* 16px */
+}
+
+small {
+  font-size: var(--text-sm);         /* 14px */
+  font-weight: var(--font-weight-regular); /* 400 */
+  line-height: var(--leading-normal);   /* 1.5 */
+}
+```
+
+---
+
+## Responsive Typography
+
+### Mobile-First Scaling
+
+```css
+/* Mobile (default) */
+h1 {
+  font-size: 2rem;  /* 32px */
+}
+
+h2 {
+  font-size: 1.5rem;  /* 24px */
+}
+
+/* Tablet (640px+) */
+@media (min-width: 640px) {
+  h1 {
+    font-size: 2.25rem;  /* 36px */
+  }
+
+  h2 {
+    font-size: 1.75rem;  /* 28px */
+  }
+}
+
+/* Desktop (1024px+) */
+@media (min-width: 1024px) {
+  h1 {
+    font-size: 2.5rem;  /* 40px */
+  }
+
+  h2 {
+    font-size: 2rem;  /* 32px */
+  }
+}
+```
+
+**Scaling Pattern:**
+- Mobile: 80% of desktop size
+- Tablet: 90% of desktop size
+- Desktop: 100% (base size)
+
+---
+
+## Text Color & Contrast
+
+### Standard Text Colors
+
+```css
+:root {
+  /* Light mode */
+  --text-primary: rgb(17, 24, 39);      /* gray-900 - Headings */
+  --text-secondary: rgb(55, 65, 81);    /* gray-700 - Body text */
+  --text-tertiary: rgb(107, 114, 128);  /* gray-500 - Muted text */
+  --text-disabled: rgb(156, 163, 175);  /* gray-400 - Disabled */
+}
+
+.dark {
+  /* Dark mode */
+  --text-primary: rgb(255, 255, 255);   /* White - Headings */
+  --text-secondary: rgb(229, 231, 235); /* gray-200 - Body */
+  --text-tertiary: rgb(156, 163, 175);  /* gray-400 - Muted */
+  --text-disabled: rgb(75, 85, 99);     /* gray-600 - Disabled */
+}
+```
+
+**WCAG Contrast Requirements:**
+| Text Size | WCAG AA | WCAG AAA |
+|-----------|---------|----------|
+| Normal text (<18pt) | 4.5:1 | 7:1 |
+| Large text (≥18pt) | 3:1 | 4.5:1 |
+
+---
+
+## Common Patterns
+
+### Article/Blog Post
+
+```css
+.prose {
+  max-width: 65ch;  /* Optimal reading width */
+  font-size: var(--text-base);
+  line-height: var(--leading-relaxed);  /* 1.6 - Extra comfort */
+  color: var(--text-secondary);
+}
+
+.prose h1 {
+  margin-top: var(--spacing-12);
+  margin-bottom: var(--spacing-6);
+}
+
+.prose h2 {
+  margin-top: var(--spacing-8);
+  margin-bottom: var(--spacing-4);
+}
+
+.prose p {
+  margin-bottom: var(--spacing-4);
+}
+
+.prose strong {
+  font-weight: var(--font-weight-semibold);
+  color: var(--text-primary);
+}
+```
+
+### Button Text
+
+```css
+.button {
+  font-size: var(--text-base);        /* 16px */
+  font-weight: var(--font-weight-semibold);  /* 600 */
+  line-height: 1;                     /* Tight for buttons */
+  letter-spacing: var(--tracking-normal);
+}
+
+.button-sm {
+  font-size: var(--text-sm);          /* 14px */
+  font-weight: var(--font-weight-medium);     /* 500 */
+}
+```
+
+### Labels & Form Fields
+
+```css
+.label {
+  font-size: var(--text-sm);          /* 14px */
+  font-weight: var(--font-weight-medium);     /* 500 */
+  line-height: var(--leading-normal);  /* 1.5 */
+  color: var(--text-primary);
+  margin-bottom: var(--spacing-2);     /* 8px */
+}
+
+.input {
+  font-size: var(--text-base);        /* 16px - iOS zoom prevention */
+  font-weight: var(--font-weight-regular);    /* 400 */
+  line-height: var(--leading-normal);  /* 1.5 */
+}
+```
+
+---
+
+## Best Practices
+
+### DO:
+- ✅ Use modular scale (1.25x or 1.5x ratio)
+- ✅ Limit to 3-4 font sizes for simplicity
+- ✅ Use relative units (rem, em) for scalability
+- ✅ Test readability on mobile devices
+- ✅ Ensure 4.5:1 contrast for body text
+- ✅ Use system fonts for performance
+- ✅ Match line height to font size (smaller = tighter)
+
+### DON'T:
+- ❌ Use more than 2 font families
+- ❌ Use pixel units for font sizes
+- ❌ Set font-size < 16px on inputs (iOS zoom)
+- ❌ Use low-contrast text (fails accessibility)
+- ❌ Use light font weights for body text
+- ❌ Forget responsive scaling
+- ❌ Use excessive letter spacing on body text
+
+---
+
+## Quick Reference
+
+**Type Scale:**
+| Element | Size | Weight | Line Height |
+|---------|------|--------|-------------|
+| H1 | 40px (2.5rem) | Bold (700) | 1.2 |
+| H2 | 32px (2rem) | Bold (700) | 1.2 |
+| H3 | 24px (1.5rem) | Semibold (600) | 1.3 |
+| Body | 16px (1rem) | Regular (400) | 1.5 |
+| Small | 14px (0.875rem) | Regular (400) | 1.5 |
+
+**Font Weights:**
+- Body text: 400 (Regular)
+- Labels: 500 (Medium)
+- Buttons: 600 (Semibold)
+- Headings: 700 (Bold)
+
+**Line Heights:**
+- Headings: 1.2-1.3
+- Body text: 1.5-1.6
+- Small text: 1.4-1.5
+
+---
+
+**💡 Remember:** Good typography is invisible. It should aid readability, not distract!

package/template/.claude/contexts/domain/README.md

@@ -0,0 +1,164 @@
+# Domain-Specific Contexts
+
+This folder contains **project-specific** business logic, design tokens, and domain patterns.
+
+---
+
+## 📁 Structure
+
+```
+domain/
+├── README.md (this file)
+└── {project-name}/          # Your project domain
+    ├── overview.md          # Domain overview
+    ├── design-tokens.md     # Project-specific colors, fonts
+    ├── business-rules.md    # Domain logic, validations
+    ├── api-contracts.md     # API specifications
+    └── workflows.md         # User flows, process diagrams
+```
+
+---
+
+## 🎯 Examples
+
+### E-commerce Project
+```
+domain/ecommerce/
+├── overview.md           # E-commerce platform overview
+├── design-tokens.md      # Brand colors (primary, secondary, accent)
+├── checkout-flow.md      # 4-step checkout process
+├── inventory-rules.md    # Stock management, backorder logic
+└── payment-gateway.md    # Stripe integration patterns
+```
+
+### IELTS Speaking Test
+```
+domain/ielts/
+├── overview.md           # IELTS platform overview
+├── design-tokens.md      # Primary: rgb(15, 42, 74), Secondary: rgb(212, 185, 120)
+├── test-structure.md     # Part 1, 2, 3 specifications
+├── scoring.md            # Speechace (0-100) → IELTS (0-9) conversion
+├── speechace-api.md      # API integration, rate limits
+└── audio-validation.md   # Part-specific audio limits (45s, 110s, 60s)
+```
+
+### CRM System
+```
+domain/crm/
+├── overview.md           # CRM system overview
+├── design-tokens.md      # Enterprise brand colors
+├── sales-pipeline.md     # Lead → Opportunity → Customer
+├── contact-management.md # Contact lifecycle, data model
+└── reporting.md          # Dashboard metrics, KPIs
+```
+
+---
+
+## 🔧 How to Create Your Domain
+
+### Step 1: Create Directory
+```bash
+mkdir -p .claude/contexts/domain/myproject
+```
+
+### Step 2: Add Overview
+```markdown
+<!-- domain/myproject/overview.md -->
+# MyProject Overview
+
+## What is this?
+Brief description of your project domain.
+
+## Core Concepts
+- Concept 1: Description
+- Concept 2: Description
+
+## Key Features
+- Feature 1
+- Feature 2
+```
+
+### Step 3: Add Design Tokens (Optional)
+```markdown
+<!-- domain/myproject/design-tokens.md -->
+# MyProject Design Tokens
+
+## Colors
+```css
+--color-primary: #007bff    /* Brand Blue */
+--color-secondary: #6c757d  /* Gray */
+--color-accent: #28a745     /* Green */
+--color-error: #dc3545      /* Red */
+```
+
+## Typography
+- Font Family: 'Inter', sans-serif
+- Headings: 700 (bold)
+- Body: 400 (regular)
+```
+
+### Step 4: Add Business Rules (Optional)
+```markdown
+<!-- domain/myproject/business-rules.md -->
+# Business Rules
+
+## Validation Rules
+- Email must be unique
+- Password min 8 characters
+- Phone number format: +XX-XXX-XXX-XXXX
+
+## Business Logic
+- Free shipping: Orders > $50
+- Discount: 10% for members
+- Refund: Within 30 days
+```
+
+---
+
+## 🤖 How Agents Use Domain Contexts
+
+### Automatic Loading
+```
+Orchestrator:
+1. Detects tech stack (Next.js, Prisma)
+2. Checks domain/ folder
+3. IF exists → Loads domain/{project}/*.md
+4. Passes to specialist agents
+
+Example:
+Task: "Create login form"
+→ uxui-frontend agent loads:
+  ✅ patterns/testing.md (universal)
+  ✅ design/color-theory.md (universal)
+  ✅ domain/myproject/design-tokens.md (project-specific)
+  ✅ Context7: Next.js docs (dynamic)
+```
+
+---
+
+## ✅ Best Practices
+
+### DO:
+- ✅ Create domain folder for each project
+- ✅ Document business rules clearly
+- ✅ Include examples and edge cases
+- ✅ Keep design tokens separate from universal design foundation
+- ✅ Update when requirements change
+
+### DON'T:
+- ❌ Mix domain logic with universal patterns
+- ❌ Hardcode values (use env variables)
+- ❌ Leave outdated documentation
+- ❌ Skip domain context for complex projects
+
+---
+
+## 📖 References
+
+- **Universal Patterns:** `.claude/contexts/patterns/`
+- **Design Foundation:** `.claude/contexts/design/`
+- **Agents:** `.claude/agents/`
+
+---
+
+**Start by creating `domain/{your-project}/overview.md`!**