# Component Documentation Guide **CRITICAL:** Use this process EVERY time you document a new Dynamic UI component. --- ## Why This Matters **Recent Example:** DLayout was documented without reading source code. Wrong prop names (`span` vs `cols`) caused 25 minutes of debugging and incorrect widget generation. **Rule:** NEVER document based on assumptions or "what makes sense". ALWAYS verify against implementation. --- ## 5-Step Verification Process ### Step 1: Read Source Code FIRST **Always start here before writing ANY documentation:** ```bash # Navigate to component source cd ~/Code/dynamic-2.0/dynamic-ui/libraries/dynamic-ui-react/src/components # Read the component file cat DComponentName/DComponentName.tsx # Read the types file (if separate) cat DComponentName/types.ts ``` **What to extract:** - Complete Props interface - Default prop values - Any type unions or enums - Internal implementation details (for best practices) --- ### Step 2: Extract Props Interface EXACTLY **Copy the EXACT type definition from source:** ```typescript // From source: DLayoutPane.tsx type DLayoutPaneProps = { cols?: string | number; // ✅ Copy EXACTLY as written colsXs?: string | number; colsSm?: string | number; colsMd?: string | number; colsLg?: string | number; colsXl?: string | number; colsXxl?: string | number; className?: string; style?: CSSProperties; children: ReactNode; } ``` **❌ DON'T:** - Rename props to "make more sense" - Guess prop types based on similar components - Assume optional/required without checking **✅ DO:** - Copy prop names EXACTLY - Copy types EXACTLY (including unions) - Note which props are optional vs required - Copy any JSDoc comments --- ### Step 3: Verify with Storybook **Run Storybook and test the component:** ```bash cd ~/Code/dynamic-2.0/dynamic-ui npm run storybook # Opens on http://localhost:6006 ``` **In Storybook:** 1. Find component story 2. Test all controls (props) 3. Try different combinations 4. Copy working examples 5. Note any warnings in console **What to capture:** - Basic usage example (copy from story) - Common patterns (from different story variations) - Edge cases (from story args) - Visual behavior with different props --- ### Step 4: Document in This Order **Use this exact structure:** ```markdown ## DComponentName **Brief description (1 sentence)** ### Props [Props table from Step 2 - EXACT types from source] ### Basic Usage [Example copied from Storybook - Step 3] ### Common Patterns [2-3 examples from Storybook stories] ### ⚠️ Common Mistakes [Document what NOT to do - based on type system] ### Best Practices [Based on component internals from Step 1] ### v2.0 Changes (if applicable) [Document what changed from v1.x] ``` --- ### Step 5: Validation Checklist Before considering documentation complete: - [ ] **All props in table match source code types** (exact names, types, optional/required) - [ ] **Basic example tested in Storybook** (copy-paste works) - [ ] **Common patterns tested in Storybook** (all examples work) - [ ] **No assumptions made** (everything verified against source or Storybook) - [ ] **Props table includes:** - [ ] Exact prop name from source - [ ] Exact type from source (including unions) - [ ] Required vs Optional (correct) - [ ] Default value (if any) - [ ] Description (what it does) - [ ] **Examples use correct prop names** (no guessing) - [ ] **Best practices based on implementation** (not assumptions) --- ## Common Mistakes to Avoid ### ❌ Mistake #1: Documenting Without Reading Source ```markdown ## DLayout Uses custom CSS Grid system... ❌ WRONG - never checked source ``` **Why it's wrong:** Assumed prop name based on "what makes sense" **Correct approach:** Read DLayoutPane.tsx → see `cols` prop → document `cols` --- ### ❌ Mistake #2: Guessing Prop Types ```markdown ❌ WRONG - guessed based on common patterns ``` **Why it's wrong:** Assumed `value` like HTML5 progress element **Correct approach:** Read DProgress.tsx → see `currentValue` prop → document `currentValue` --- ### ❌ Mistake #3: Incomplete Props Table ```markdown | Prop | Type | Description | |------|------|-------------| | cols | number | Column span | ❌ WRONG - missing responsive props ``` **Why it's wrong:** Only documented one prop, missed colsLg, colsMd, etc. **Correct approach:** Copy ENTIRE Props interface from source --- ### ❌ Mistake #4: Wrong System Description ```markdown DLayout uses a custom CSS Grid system where columns don't need to add up to 12. ❌ WRONG - never verified implementation ``` **Why it's wrong:** Described system without reading CSS classes **Correct approach:** Check component code → see `g-col-{n}` classes → document Bootstrap Grid CSS --- ## Example: Correct Documentation Process **Component:** DLayout + DLayoutPane (from Nov 2 audit) ### Step 1: Read Source ✅ ```bash cat ~/Code/dynamic-2.0/dynamic-ui/libraries/dynamic-ui-react/src/components/DLayout/DLayoutPane.tsx ``` **Found:** ```typescript type DLayoutPaneProps = { cols?: string | number; colsXs?: string | number; // ... all responsive props className?: string; children: ReactNode; } ``` ### Step 2: Extract Props ✅ Created exact props table: - `cols` (not `span`) - All responsive variants - Optional, not required ### Step 3: Verify Storybook ✅ ```bash npm run storybook ``` Tested examples: - Basic 2-column layout - 3-column dashboard - Responsive layout ### Step 4: Document ✅ Created complete documentation: - Props table (exact from source) - Basic example (from Storybook) - Dashboard pattern (from Storybook) - Comparison with DRow/DCol ### Step 5: Validate ✅ - [x] Props match source exactly - [x] Examples tested in Storybook - [x] No assumptions made - [x] Complete props table **Result:** Correct documentation that prevents widget generation errors. --- ## When to Use This Guide **Use this guide when:** - Documenting NEW v2.0 components (mandatory) - Updating existing component docs after API changes - Someone reports component docs are inaccurate - Adding new component to dynamic-context for first time **Don't skip steps:** - Each step catches different types of errors - Step 1 catches wrong prop names - Step 2 catches wrong types - Step 3 catches wrong usage patterns - Step 4 ensures consistent structure - Step 5 catches incomplete docs --- ## Quick Reference Card **Before documenting any component:** 1. ✅ Read source code first 2. ✅ Copy Props interface exactly 3. ✅ Test in Storybook 4. ✅ Document with verified info 5. ✅ Validate completeness **Never:** - ❌ Document based on "what makes sense" - ❌ Guess prop names - ❌ Skip Storybook verification - ❌ Assume types without checking --- **Last Updated:** November 2, 2025 **Reason:** Created after DLayout documentation error (25 min debugging) **Prevents:** Wrong component documentation causing widget generation errors