@reactberry/system 2.0.0-beta

package/src/docs/README.md

@@ -0,0 +1,373 @@
+# Design System Documentation
+
+This directory contains comprehensive documentation for this React-based component library built with styled-components and styled-system for consistent, accessible, and maintainable user interfaces.
+
+> **📋 Documentation Status:** Currently under active improvement. See [DOCUMENTATION_AUDIT.md](./DOCUMENTATION_AUDIT.md) for current gaps and planned improvements.
+
+## Quick Start
+
+**New to the design system?** Start here:
+1. 📖 [Getting Started Guide](./guides/getting-started.md) - Your first components
+2. 🧩 [Component Composition](./guides/component-composition.md) - Building complex UIs
+3. 🎨 [Theme Integration](./guides/theming-guide.md) - Customizing appearance
+4. 📱 [Responsive Design](./guides/responsive-design.md) - Mobile-first patterns
+
+## Documentation Structure
+
+```
+docs/
+├── README.md                    # This overview
+├── DOCUMENTATION_AUDIT.md       # Current status and improvement plan
+├── index.md                     # Quick reference for AI assistants
+├── elements.md                  # Core components (Box, Text, Button, Field)
+├── blocks.md                    # Composed components (⚠️ Being expanded)
+├── themes.md                    # Theme system and customization
+├── api/                         # Detailed component APIs
+│   ├── Box.md                   # Layout component reference
+│   ├── Text.md                  # Typography component reference
+│   ├── Button.md                # Button component reference
+│   ├── Field.md                 # Form input reference
+│   └── blocks/                  # 🚧 Block components (coming soon)
+├── guides/                      # Step-by-step tutorials
+│   ├── getting-started.md       # Your first components
+│   ├── component-composition.md # Building complex UIs
+│   ├── theming-guide.md         # Customizing themes
+│   ├── responsive-design.md     # Mobile-first patterns
+│   ├── accessibility.md         # Building inclusive interfaces
+│   └── 🚧 Additional guides     # Migration, testing, performance
+├── examples/                    # Practical patterns
+│   ├── layouts/                 # Layout examples
+│   ├── forms/                   # Form patterns
+│   └── 🚧 More examples         # Navigation, cards, patterns
+└── assets/                      # Design resources
+    ├── design-tokens.md         # Token reference
+    ├── color-palettes.md        # Color system
+    └── typography-scale.md      # Typography system
+```
+
+**Legend:** ✅ Complete | ⚠️ Partial | 🚧 In Progress | 📋 Planned
+
+## Quick Start Guide
+
+### 1. Import Components
+
+```jsx
+// Core elements (fully documented)
+import { Box, Text, Button, Field } from '@/design-system/elements';
+
+// Composed blocks (documentation in progress)
+import { Avatar, Container, Heading } from '@/design-system/blocks';
+```
+
+### 2. Basic Usage
+
+```jsx
+function WelcomeCard() {
+  return (
+    <Box skin="card" p="m" gap="s" maxWidth="400px">
+      <Text as="h2" fontSize="l" fontWeight="bold" color="primary">
+        Welcome to Design System
+      </Text>
+      <Text as="p" fontSize="s" color="secondary" lineHeight="relaxed">
+        Build amazing interfaces with our design system.
+      </Text>
+      <Button variant="primary" $size="medium">
+        Get Started
+      </Button>
+    </Box>
+  );
+}
+```
+
+### 3. Theme Integration
+
+```jsx
+import { ThemeProvider } from '@/lib/theme-provider';
+import { theme } from '@/design-system/themes';
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <WelcomeCard />
+    </ThemeProvider>
+  );
+}
+```
+
+> **💡 Tip:** For complete examples and patterns, see our [Getting Started Guide](./guides/getting-started.md).
+
+## Core Architecture
+
+### Component Hierarchy
+
+```
+┌─────────────────────────────────────┐
+│              Applications           │
+├─────────────────────────────────────┤
+│               Blocks                │  ← 50+ Composed Components
+│    (Avatar, Card, Modal, Layout)    │
+├─────────────────────────────────────┤
+│              Elements               │  ← Core Building Blocks
+│     (Box, Text, Button, Field)      │
+├─────────────────────────────────────┤
+│               Themes                │  ← Design Tokens & Styling
+│      (Colors, Typography, etc.)     │
+└─────────────────────────────────────┘
+```
+
+### Component Rules
+
+#### Box Component (Layout Only)
+- **Use for**: containers, layouts, divs, non-text elements
+- **⚠️ NO typography props**: fontSize, fontWeight, color, etc.
+- **Props**: `skin`, `shape`, `gap`, `p`, `m`, `display`, flex/grid props
+
+#### Text Component (All Text Content)
+- **Use for**: h1-6, p, span, label, any text content
+- **✅ Has typography props**: fontSize, fontWeight, color, lineHeight
+- **Extends**: All Box props + typography props
+
+#### Button & Field Components
+- **Button**: Extends Text with interactive functionality
+- **Field**: Extends Text with form input capabilities
+
+## Essential Concepts
+
+### 1. Theme Aliases (Always Use These)
+
+```jsx
+// ✅ Good - Use theme aliases
+<Box p="m" gap="s" />
+<Text fontSize="l" color="primary" />
+
+// ❌ Bad - Don't use indices or arbitrary values
+<Box p={5} gap="12px" />
+<Text fontSize="18px" color="#3B82F6" />
+```
+
+**Available Aliases:**
+- **Space**: `mini`, `xs`, `s`, `m`, `l`, `xl`, `xxl`, `xxxl`
+- **Font Sizes**: `xs`, `s`, `m`, `l`, `xl`, `xxl`, `xxxl`
+- **Shapes**: `square`, `roundedSmall`, `rounded`, `roundedLarge`, `pill`, `circle`
+
+### 2. Skin System
+
+Pre-defined styling combinations for consistency:
+
+```jsx
+// Surface skins for containers
+<Box skin="base">Base background</Box>
+<Box skin="surface">Secondary surface</Box>
+<Box skin="card">Card with elevation</Box>
+
+// Semantic skins for meaning
+<Box skin="success">Success state</Box>
+<Box skin="error">Error state</Box>
+<Box skin="warning">Warning state</Box>
+
+// Color coding
+<Box skin="blue">Blue category</Box>
+<Box skin="green">Green category</Box>
+```
+
+### 3. Responsive Design
+
+Mobile-first approach with responsive arrays:
+
+```jsx
+<Box 
+  width={[1, 1/2, 1/3]}        // 100% → 50% → 33%
+  p={['xs', 's', 'm']}         // 8px → 12px → 16px
+  display={['block', 'flex']}  // block → flex
+>
+  <Text fontSize={['s', 'm', 'l']}>
+    Responsive content
+  </Text>
+</Box>
+```
+
+## Key Documentation
+
+### 📚 Core References (✅ Complete)
+- **[elements.md](./elements.md)** - Complete Box, Text, Button, Field documentation
+- **[blocks.md](./blocks.md)** - Composed components overview (⚠️ Individual docs in progress)
+- **[themes.md](./themes.md)** - Theme system, tokens, and customization
+
+### 🔧 Detailed APIs (✅ Core Elements Complete)
+- **[api/Box.md](./api/Box.md)** - Layout component props and patterns
+- **[api/Text.md](./api/Text.md)** - Typography component and semantic HTML
+- **[api/Button.md](./api/Button.md)** - Interactive button variants and states
+- **[api/Field.md](./api/Field.md)** - Form input types and validation
+- **api/blocks/** - 🚧 Individual block component documentation (coming soon)
+
+### 📖 Step-by-Step Guides (✅ Core Guides Complete)
+- **[guides/getting-started.md](./guides/getting-started.md)** - Build your first components
+- **[guides/component-composition.md](./guides/component-composition.md)** - Complex UI patterns
+- **[guides/responsive-design.md](./guides/responsive-design.md)** - Mobile-first design
+- **[guides/accessibility.md](./guides/accessibility.md)** - Inclusive interfaces
+- **[guides/theming-guide.md](./guides/theming-guide.md)** - Theme customization
+
+### 💡 Real-World Examples (⚠️ Expanding)
+- **[examples/layouts/dashboard.md](./examples/layouts/dashboard.md)** - Dashboard patterns
+- **[examples/forms/form-patterns.md](./examples/forms/form-patterns.md)** - Form design patterns
+- **examples/navigation/** - 🚧 Navigation patterns (planned)
+- **examples/cards/** - 🚧 Card patterns (planned)
+
+### 🎨 Design Assets (✅ Complete)
+- **[assets/design-tokens.md](./assets/design-tokens.md)** - Complete token reference
+- **[assets/color-palettes.md](./assets/color-palettes.md)** - Color system and accessibility
+- **[assets/typography-scale.md](./assets/typography-scale.md)** - Typography system
+
+## Common Patterns
+
+### Form Field Pattern
+```jsx
+<Box>
+  <Text as="label" htmlFor="email" fontSize="s" fontWeight="medium" mb="xs">
+    Email Address
+  </Text>
+  <Field 
+    id="email"
+    as="input"
+    type="email"
+    placeholder="Enter your email"
+    variant="outline"
+    $size="medium"
+  />
+</Box>
+```
+
+### Interactive Card Pattern
+```jsx
+<Box
+  skin="card"
+  p="m"
+  cursor="pointer"
+  hover="subtle"
+  focus="highlight"
+  shape="rounded"
+>
+  <Text as="h3" fontSize="m" fontWeight="bold">Card Title</Text>
+  <Text fontSize="s" color="secondary">Card content</Text>
+</Box>
+```
+
+### Navigation Pattern
+```jsx
+<Box display="flex" alignItems="center" justifyContent="space-between" p="m">
+  <Text as="h1" fontSize="l" fontWeight="bold" color="primary">
+    Reactberry
+  </Text>
+  <Box display="flex" gap="m" alignItems="center">
+    <Text as="a" href="/home" fontSize="s">Home</Text>
+    <Button variant="primary" $size="small">Sign In</Button>
+  </Box>
+</Box>
+```
+
+## Best Practices Summary
+
+### ✅ Do
+1. **Use Text for all text content**
+   ```jsx
+   <Text as="h1">Heading</Text>
+   <Text as="p">Paragraph</Text>
+   <Text as="label">Label</Text>
+   ```
+
+2. **Use theme aliases consistently**
+   ```jsx
+   <Box p="m" gap="s" />
+   <Text fontSize="l" color="primary" />
+   ```
+
+3. **Follow semantic HTML structure**
+   ```jsx
+   <Box as="main">
+     <Text as="h1">Page Title</Text>
+     <Text as="p">Content</Text>
+   </Box>
+   ```
+
+4. **Use appropriate skins for meaning**
+   ```jsx
+   <Box skin="card">Container</Box>
+   <Box skin="error">Error message</Box>
+   ```
+
+### ❌ Don't
+1. **Don't use Box for text content**
+   ```jsx
+   // Wrong - Box doesn't support typography
+   <Box as="h1" fontSize="xl">Title</Box>
+   
+   // Right - Text supports typography
+   <Text as="h1" fontSize="xl">Title</Text>
+   ```
+
+2. **Don't use arbitrary values**
+   ```jsx
+   // Wrong - Hardcoded values
+   <Box p="16px" color="#333" />
+   
+   // Right - Theme aliases
+   <Box p="m" color="primary" />
+   ```
+
+3. **Don't ignore responsive design**
+   ```jsx
+   // Wrong - Fixed sizing
+   <Box width="300px" />
+   
+   // Right - Responsive arrays
+   <Box width={[1, 1/2, 1/3]} />
+   ```
+
+## Current Status & Roadmap
+
+### ✅ Complete
+- **Core Elements**: Fully documented Box, Text, Button, Field components
+- **Theme System**: Comprehensive theme documentation and customization guides
+- **Guides**: Step-by-step tutorials for common patterns
+- **Examples**: Layout and form patterns with working code
+
+### 🚧 In Progress
+- **Block Components**: Individual documentation for 50+ composed components
+- **Advanced Examples**: Navigation, cards, and complex patterns
+- **Testing Guide**: Component testing and validation strategies
+- **Performance Guide**: Optimization best practices
+
+### 📋 Planned
+- **Migration Guide**: Upgrading between versions
+- **Troubleshooting**: Common issues and solutions
+- **Interactive Playground**: Live component examples
+- **Video Tutorials**: Visual learning resources
+
+## Support & Contributing
+
+### Getting Help
+- **Quick Reference**: Check [index.md](./index.md) for AI-friendly documentation
+- **Component APIs**: Browse detailed [api/](./api/) documentation
+- **Examples**: See [examples/](./examples/) for real-world patterns
+- **Guides**: Follow step-by-step [guides/](./guides/) tutorials
+- **Issues**: Report documentation gaps in [DOCUMENTATION_AUDIT.md](./DOCUMENTATION_AUDIT.md)
+
+### Contributing to Documentation
+1. **Follow the audit plan** - See [DOCUMENTATION_AUDIT.md](./DOCUMENTATION_AUDIT.md) for current priorities
+2. **Use standard templates** - Maintain consistency across all documentation
+3. **Include working examples** - All code should be tested and functional
+4. **Test accessibility** - Ensure examples meet WCAG guidelines
+5. **Update cross-references** - Keep internal links accurate and helpful
+
+### Project Overview
+
+The design system includes:
+- **50+ Blocks** - Composed components (Avatar, Card, Modal, etc.) ⚠️ *Docs in progress*
+- **4 Core Elements** - Building blocks (Box, Text, Button, Field) ✅ *Fully documented*
+- **Comprehensive Theming** - Colors, typography, spacing, shapes ✅ *Complete*
+- **Full Accessibility** - ARIA support, semantic HTML, keyboard navigation ✅ *Documented*
+- **Responsive by Default** - Mobile-first with breakpoint support ✅ *Complete*
+
+---
+
+**📝 Documentation Feedback**: Found an issue or gap in the documentation? Please reference the [Documentation Audit](./DOCUMENTATION_AUDIT.md) or create an issue with specific improvement suggestions.

package/src/docs/reference/README.md

@@ -0,0 +1,299 @@
+# Design System Reference Documentation
+
+**Purpose:** Complete reference materials for Reactberry
+
+This directory contains all reference documentation designed for both human developers and AI assistants.
+
+---
+
+## 📂 Directory Contents
+
+### 🌳 Decision Trees
+**Location:** `./decision-trees/`
+
+Essential flowcharts for choosing the right components and props:
+
+- **[component-selection.md](./decision-trees/component-selection.md)** - "What component do I need?" decision tree
+  - Text vs Box vs Button vs Field
+  - 30+ decision points with examples
+  - Common mistake warnings
+
+- **[prop-selection.md](./decision-trees/prop-selection.md)** - "What props do I use?" decision tree
+  - **Critical:** `size` vs `$size` distinction
+  - Spacing, styling, layout, typography props
+  - Responsive patterns
+
+**Use when:** Starting a new component or unsure which element to use
+
+---
+
+### ⚡ Quick Reference Cards
+**Location:** `./quick-cards/`
+
+One-page cheat sheets for each core component:
+
+- **[box.md](./quick-cards/box.md)** - Box component essentials
+  - Most common use cases (5 examples)
+  - Essential props table
+  - Layout patterns
+  - Common mistakes with fixes
+
+- **[button.md](./quick-cards/button.md)** - Button component essentials
+  - All variants (primary, secondary, ghost, outline)
+  - Size options (small, medium, large)
+  - States (disabled, loading, icon)
+  - **Critical reminder:** Use `$size` not `size`
+
+- **[field.md](./quick-cards/field.md)** - Field component essentials
+  - All input types (text, email, password, textarea, select)
+  - Variants and sizes
+  - Accessibility patterns
+  - **Critical reminder:** Use `$size` not `size`
+
+**Use when:** Quick lookup for component syntax and common patterns
+
+---
+
+### 📚 Pattern Libraries
+
+- **[patterns-registry.md](./patterns-registry.md)** - 35+ copy-paste code patterns
+  - **Layout Patterns:** Flex, grid, cards, containers (8 patterns)
+  - **Form Patterns:** Inputs, validation, actions (7 patterns)
+  - **Interactive Patterns:** Buttons, groups, links (6 patterns)
+  - **Data Display Patterns:** Stats, lists, key-value pairs (4 patterns)
+  - **Navigation Patterns:** Headers, breadcrumbs, tabs (3 patterns)
+  - **Content Patterns:** Headings, empty states, alerts (4 patterns)
+  - **State Patterns:** Loading, error, success (3 patterns)
+  - Each pattern includes: components used, tokens, complexity level, common use cases
+
+**Use when:** Need a starting point for common UI patterns
+
+---
+
+### ✅ Validation & Rules
+
+- **[prop-validation.md](./prop-validation.md)** - Valid vs invalid prop combinations
+  - **Invalid combinations:** What NOT to do with examples
+  - **Required combinations:** What MUST be included
+  - **Recommended patterns:** Best practices
+  - Validation checklist (10 items)
+  - TypeScript validation examples
+
+**Use when:** Debugging prop errors or validating code before committing
+
+---
+
+### 🔗 Component Dependencies
+
+- **[component-dependencies.md](./component-dependencies.md)** - Component relationship graph
+  - Element hierarchy (Box → Text → Button/Field)
+  - Block dependencies (50+ blocks categorized)
+  - Import recommendations
+  - Circular dependency warnings
+  - "When to use what" guide
+
+**Use when:** Understanding component relationships or deciding between element and block components
+
+---
+
+### 🐛 Troubleshooting
+
+- **[common-errors.md](./common-errors.md)** - Top 10 errors with solutions
+  - **Error #1:** Using `size` instead of `$size` on Button/Field ⭐⭐⭐⭐⭐
+  - **Error #2:** Using Box for text content ⭐⭐⭐⭐
+  - **Error #3:** Missing semantic HTML (`as` prop) ⭐⭐⭐⭐
+  - **Error #4:** Arbitrary values instead of theme tokens ⭐⭐⭐
+  - **Error #5:** Missing label-input connection ⭐⭐⭐
+  - Plus 5 more common errors
+  - TypeScript error solutions
+  - Runtime warning fixes
+  - Styling issue troubleshooting
+  - Quick debugging checklist
+
+**Use when:** Encountering errors or unexpected behavior
+
+---
+
+## 🎯 Quick Access by Need
+
+### I need to...
+
+| Need | Go To |
+|------|-------|
+| **Choose a component** | [Component Selection Decision Tree](./decision-trees/component-selection.md) |
+| **Understand size vs $size** | [Prop Selection Decision Tree](./decision-trees/prop-selection.md#-critical-distinction-size-vs-size) |
+| **Get started quickly** | [Quick Reference Cards](./quick-cards/) |
+| **Copy a pattern** | [Patterns Registry](./patterns-registry.md) |
+| **Fix an error** | [Common Errors](./common-errors.md) |
+| **Validate my code** | [Prop Validation](./prop-validation.md) |
+| **Understand dependencies** | [Component Dependencies](./component-dependencies.md) |
+| **Learn Box** | [Box Quick Card](./quick-cards/box.md) |
+| **Learn Button** | [Button Quick Card](./quick-cards/button.md) |
+| **Learn Field** | [Field Quick Card](./quick-cards/field.md) |
+
+---
+
+## 🤖 AI Assistant Usage
+
+### For New Components
+1. **Check:** [Component Selection](./decision-trees/component-selection.md) - Which component?
+2. **Reference:** [Quick Card](./quick-cards/) - Component syntax
+3. **Copy:** [Patterns Registry](./patterns-registry.md) - Similar pattern
+4. **Validate:** [Prop Validation](./prop-validation.md) - Props correct?
+
+### For Debugging
+1. **Error message?** → [Common Errors](./common-errors.md)
+2. **Props not working?** → [Prop Validation](./prop-validation.md)
+3. **Component relationships?** → [Component Dependencies](./component-dependencies.md)
+4. **Still stuck?** → [Decision Trees](./decision-trees/)
+
+### For Learning
+1. **Start:** [Decision Trees](./decision-trees/) - Understand the system
+2. **Practice:** [Patterns Registry](./patterns-registry.md) - Copy and modify
+3. **Reference:** [Quick Cards](./quick-cards/) - Quick lookup
+4. **Master:** [Prop Validation](./prop-validation.md) - Avoid mistakes
+
+---
+
+## 📊 Reference Statistics
+
+- **Decision Trees:** 2 comprehensive flowcharts
+- **Quick Cards:** 3 component cheat sheets
+- **Patterns:** 35+ copy-paste examples
+- **Error Solutions:** 10+ common issues covered
+- **Validation Rules:** 50+ do's and don'ts
+- **Dependency Graphs:** Complete component hierarchy
+
+---
+
+## 🎓 Learning Path
+
+### Beginner → Intermediate
+
+1. **Start:** Read [Component Selection Decision Tree](./decision-trees/component-selection.md)
+   - Understand Box vs Text vs Button vs Field
+   - Learn the decision process
+
+2. **Learn:** Review [Quick Reference Cards](./quick-cards/)
+   - Box for layout
+   - Text for typography
+   - Button for actions ($size!)
+   - Field for inputs ($size!)
+
+3. **Practice:** Copy patterns from [Patterns Registry](./patterns-registry.md)
+   - Start with basic layouts
+   - Try form patterns
+   - Build interactive components
+
+4. **Validate:** Use [Prop Validation](./prop-validation.md) as a checklist
+   - Before committing code
+   - When reviewing PRs
+
+### Intermediate → Advanced
+
+1. **Master:** [Prop Selection Decision Tree](./decision-trees/prop-selection.md)
+   - Understand all prop types
+   - Learn responsive patterns
+   - Master the theme system
+
+2. **Explore:** [Component Dependencies](./component-dependencies.md)
+   - Understand block components
+   - Learn composition patterns
+   - Avoid circular dependencies
+
+3. **Debug:** Use [Common Errors](./common-errors.md) proactively
+   - Learn what to avoid
+   - Set up linting rules
+   - Educate team members
+
+---
+
+## ⚠️ Critical Reminders
+
+**The Big 3 Mistakes:**
+
+1. **size vs $size**
+   - Box/Text use `size` (generic spacing)
+   - Button/Field use `$size` (component sizing)
+   - This is THE most common error!
+
+2. **Box vs Text**
+   - Box = layout/containers only
+   - Text = all text content
+   - Box doesn't support typography props
+
+3. **Theme Tokens**
+   - Always use tokens: `p="m"` not `p="16px"`
+   - Enables consistency and theming
+   - Required for responsive behavior
+
+---
+
+## 🔗 Related Documentation
+
+### Core Documentation
+- **[Main README](../README.md)** - Design system overview
+- **[Elements](../elements.md)** - Core components (Box, Text, Button, Field)
+- **[Blocks](../blocks.md)** - Composed components
+
+### API References
+- **[Box API](../api/Box.md)** - Complete Box documentation
+- **[Text API](../api/Text.md)** - Complete Text documentation
+- **[Button API](../api/Button.md)** - Complete Button documentation
+- **[Field API](../api/Field.md)** - Complete Field documentation
+
+### Guides
+- **[Getting Started](../guides/getting-started.md)** - First steps
+- **[Component Composition](../guides/component-composition.md)** - Building complex UIs
+- **[Responsive Design](../guides/responsive-design.md)** - Mobile-first patterns
+- **[Accessibility](../guides/accessibility.md)** - Inclusive design
+
+### Assets
+- **[Design Tokens](../assets/design-tokens.md)** - All theme tokens
+- **[Color Palettes](../assets/color-palettes.md)** - Color system
+- **[Typography Scale](../assets/typography-scale.md)** - Typography system
+
+---
+
+## 📝 Contributing
+
+### Adding New Patterns
+1. Add to [Patterns Registry](./patterns-registry.md)
+2. Include: components, tokens, complexity, use case
+3. Provide copy-paste code example
+4. Add to search index
+
+### Adding New Errors
+1. Add to [Common Errors](./common-errors.md)
+2. Include: frequency, symptom, wrong code, correct code, why
+3. Rank by frequency (⭐⭐⭐⭐⭐ = most common)
+
+### Updating Quick Cards
+1. Keep to one page per component
+2. Focus on most common use cases (top 5)
+3. Include essential props table
+4. Add common mistakes section
+
+---
+
+## 🆘 Getting Help
+
+**Can't find what you need?**
+
+1. **Search** the [Patterns Registry](./patterns-registry.md) by component, token, or use case
+2. **Check** [Common Errors](./common-errors.md) for your specific error message
+3. **Review** [Decision Trees](./decision-trees/) for conceptual understanding
+4. **Consult** main [README](../README.md) for broader documentation links
+
+**Still stuck?**
+- Check the [DOCUMENTATION_AUDIT](../DOCUMENTATION_AUDIT.md) for known gaps
+- File an issue with specific questions
+- Contribute documentation for patterns you've solved
+
+---
+
+**Last Updated:** 2025-01-09  
+**Maintainer:** Design System Team  
+**Status:** ✅ Complete and AI-optimized
+
+**Purpose:** This reference directory is designed to be both human-readable and machine-parsable, enabling AI assistants to quickly find the right information and generate correct code on the first try.