@discourser/design-system 0.22.2 → 0.22.4

package/docs/GUIDELINES_REVIEW.md

@@ -0,0 +1,728 @@
+# Guidelines Directory Review for Figma Make
+
+**Review Date:** 2026-01-13
+**Reviewer:** Claude Sonnet 4.5
+**Reference:** [Figma Make Guidelines Documentation](https://developers.figma.com/docs/code/write-design-system-guidelines/)
+
+## Executive Summary
+
+**Overall Status:** 🟡 **Good Foundation, Needs Enhancement**
+
+Your guidelines have **excellent comprehensive component documentation** (21 components with 300+ pages) but need some adjustments to fully align with Figma Make's AI consumption requirements.
+
+### Quick Stats
+
+- ✅ **Components Documented:** 21/30 (70%)
+- ✅ **Token Files:** 4/4 (100%)
+- ⚠️ **Overview Files:** 1/2+ recommended
+- ✅ **Guidelines.md:** Present with step-by-step structure
+- ⚠️ **Missing Documentation:** 9 components
+
+---
+
+## 1. What's Complete and Excellent ✅
+
+### Component Documentation (21 components)
+
+**Documented with comprehensive guidelines:**
+
+**Interactive Elements (5):**
+
+- Button
+- IconButton
+- Switch
+- Checkbox
+- RadioGroup
+
+**Form Elements (3):**
+
+- Input
+- Textarea
+- Select
+
+**Layout & Container (4):**
+
+- Card
+- Accordion
+- Tabs
+- Drawer
+
+**Overlays (3):**
+
+- Dialog
+- Popover
+- Tooltip
+
+**Feedback & Status (5):**
+
+- Badge
+- Avatar
+- Toast
+- Progress
+- Skeleton
+
+**Typography (1):**
+
+- Header
+
+### Token Documentation (4 complete)
+
+All required token categories documented:
+
+- ✅ **colors.md** (187 lines) - Excellent semantic token explanation
+- ✅ **typography.md** (226 lines) - Complete M3 type scale
+- ✅ **spacing.md** (289 lines) - Clear 8px grid system
+- ✅ **elevation.md** (274 lines) - M3 surface tint elevation
+
+### Guidelines.md Structure
+
+✅ **Strong step-by-step structure** (aligns with Figma requirements)
+✅ **Clear navigation instructions**
+✅ **Imperative language** ("MUST read", "DO NOT")
+✅ **Organized by component category**
+
+---
+
+## 2. What's Missing ⚠️
+
+### Missing Component Documentation (9 components)
+
+These components exist in your codebase but lack guidelines:
+
+**Utility Components:**
+
+1. **InputAddon** - Input decorations (icons, buttons)
+2. **InputGroup** - Grouped input layouts
+3. **Slider** - Numeric range selection
+4. **CloseButton** - Standard close button
+5. **Icon** - Icon wrapper component
+6. **Spinner** - Loading spinner (different from Skeleton)
+7. **AbsoluteCenter** - Centering utility
+8. **Group** - Layout helper
+9. **Loader** - Loading indicator
+
+**Priority Level:**
+
+- 🔴 **High Priority:** InputAddon, InputGroup, Slider, Spinner
+- 🟡 **Medium Priority:** CloseButton, Icon
+- 🟢 **Low Priority:** AbsoluteCenter, Group, Loader (utility components, less frequently used)
+
+### Missing Overview Files
+
+According to Figma Make best practices, you should have:
+
+**Currently Have:**
+
+- ✅ `overview-components.md` (204 lines)
+
+**Missing/Recommended:**
+
+- ⚠️ **overview-icons.md** - Icon system overview (if you have an icon system)
+- ⚠️ **overview-patterns.md** - Common UI patterns (forms, layouts, navigation)
+- ⚠️ **overview-accessibility.md** - Accessibility principles across components
+
+---
+
+## 3. Alignment with Figma Make Requirements
+
+### ✅ Strengths (Already Aligned)
+
+#### 1. Guidelines.md Structure
+
+**Requirement:** "Providing instructions in Guidelines.md helps Figma Make select the other detailed guidelines files most appropriate for its task."
+
+**Your Implementation:**
+
+```markdown
+## IMPORTANT: Always Read These First
+
+Before writing any code, follow these steps IN ORDER:
+
+### Step 1: Read Overview Files (REQUIRED)
+
+### Step 2: Read Design Token Files (REQUIRED)
+
+### Step 3: Plan Components Needed (REQUIRED)
+
+### Step 4: Read Component Guidelines BEFORE Using Components (REQUIRED)
+```
+
+✅ **Excellent** - Clear, imperative, step-by-step
+
+#### 2. Imperative Language
+
+**Requirement:** "Use imperative, unambiguous statements. Avoid hedging."
+
+**Your Examples:**
+
+- ✅ "MUST read its guidelines file first"
+- ✅ "DO NOT write code using a component until..."
+- ✅ "Always use semantic tokens, never raw hex values"
+
+✅ **Strong** - No hedging, absolute instructions
+
+#### 3. Token Philosophy
+
+**Requirement:** "Explain _why_ these tokens exist, how they create hierarchy"
+
+**Your colors.md:**
+
+```markdown
+## Why Semantic Colors?
+
+Semantic colors automatically adapt to light/dark themes and follow M3 color roles.
+Using semantic names ensures:
+
+- Automatic theme switching
+- Consistent contrast ratios
+- Proper color relationships
+- Accessibility compliance
+```
+
+✅ **Excellent** - Clear philosophy with benefits
+
+#### 4. Component Do's & Don'ts
+
+**Requirement:** "Correct usage patterns with code examples, incorrect patterns to avoid"
+
+**Your Pattern (every component):**
+
+```markdown
+## DO NOT
+
+❌ Don't use native HTML when components exist
+<button>Submit</button> // Use <Button> instead
+
+✅ Use design system components
+<Button variant="filled">Submit</Button>
+```
+
+✅ **Excellent** - Clear ❌/✅ pattern with code examples
+
+### ⚠️ Areas for Enhancement
+
+#### 1. Decision Trees (Missing)
+
+**Requirement:** "Start files with decision trees or quick-reference tables"
+
+**Current State:** Your components have selection guides buried in content
+
+**Recommendation:** Add decision trees at the **top** of each component file
+
+**Example for Select component:**
+
+```markdown
+# Select
+
+## When to Use This Component
+
+**Decision Tree:**
+```
+
+Need user to choose from options?
+├─ 1-3 options? → Use RadioGroup
+├─ 4-20 options? → Use Select ✅
+├─ 20+ options with search? → Use Select with search
+└─ Freeform input? → Use Input with autocomplete
+
+```
+
+**Improved Format:**
+
+| Scenario | Use This Component | Why |
+|----------|-------------------|-----|
+| 1-3 exclusive choices | RadioGroup | Clear visual comparison |
+| 4-20 options | Select | Compact, scannable |
+| 20+ with search | Select (searchable) | Efficient finding |
+| Freeform text | Input | User needs flexibility |
+```
+
+#### 2. Multi-Token Examples (Sparse)
+
+**Requirement:** "Demonstrate how different tokens work together"
+
+**Current State:** Token files show individual tokens well, but limited cross-token examples
+
+**Recommendation:** Add section to each token file showing token combinations
+
+**Example for colors.md:**
+
+````markdown
+## Token Combinations in Practice
+
+### Primary Button (Filled)
+
+```typescript
+<Button variant="filled">
+  // Uses these tokens together:
+  bg: 'primary'           // #4C662B in light mode
+  color: 'onPrimary'      // #FFFFFF in light mode
+  textStyle: 'labelLarge' // Typography token
+  px: 'lg'                // Spacing token
+  borderRadius: 'l2'      // Border radius token
+</Button>
+```
+````
+
+### Card on Surface
+
+```typescript
+<Card>
+  // Uses these tokens together:
+  bg: 'surfaceContainerLow'     // Elevated surface
+  color: 'onSurface'             // Default text
+  borderColor: 'outlineVariant'  // Subtle border
+  p: 'lg'                        // Padding
+  borderRadius: 'l3'             // Large radius
+</Card>
+```
+
+````
+
+#### 3. Context Management (Could Be Improved)
+
+**Requirement:** "Keep Guidelines.md focused on navigation only. Move detailed info to specialized files."
+
+**Current State:** Your Guidelines.md has some detailed content (Quick Reference tables, import examples)
+
+**Recommendation:** Move details to overview files
+
+**Current (195 lines):**
+```markdown
+## Package Imports
+[Detailed import code examples]
+
+## Quick Reference
+[Large tables with variants/sizes]
+````
+
+**Improved Structure:**
+
+```markdown
+# Guidelines.md (keep short, ~100 lines)
+
+- Navigation steps only
+- Links to overview files
+
+# overview-components.md (expand this)
+
+- Import patterns
+- Quick reference tables
+- Component category explanations
+
+# overview-imports.md (new file)
+
+- Detailed import examples
+- Package structure
+- Module exports
+```
+
+#### 4. Working Code Examples (Good, Could Add Edge Cases)
+
+**Requirement:** "Include working code examples for all patterns"
+
+**Current State:** ✅ You have 15-30 examples per component
+
+**Enhancement:** Add **edge case** examples explicitly
+
+**Example for Select:**
+
+````markdown
+## Edge Cases
+
+### Empty State
+
+```typescript
+<Select.Root collection={items} value={[]}>
+  {items.length === 0 ? (
+    <Select.Control>
+      <Select.ValueText placeholder="No options available" />
+    </Select.Control>
+  ) : (
+    // Normal select rendering
+  )}
+</Select.Root>
+```
+````
+
+### Pre-selected Value Not in List
+
+```typescript
+// Handle gracefully when defaultValue doesn't exist
+const safeDefaultValue = items.find(item => item.value === savedValue)
+  ? savedValue
+  : items[0]?.value;
+
+<Select.Root defaultValue={safeDefaultValue}>
+  {/* ... */}
+</Select.Root>
+```
+
+````
+
+---
+
+## 4. Specific Recommendations by Priority
+
+### 🔴 High Priority (Critical for Figma Make)
+
+#### 1. Add Decision Trees to Top of Component Files
+
+**Why:** Figma Make AI needs quick decision logic without reading entire file
+
+**Action:** Add a "When to Use" section with decision tree at line 5-15 of each component
+
+**Template:**
+```markdown
+# [Component Name]
+
+**Purpose:** [One sentence]
+
+## When to Use This Component
+
+[Decision tree or comparison table]
+
+## Import
+[Rest of content...]
+````
+
+**Estimate:** 2-3 hours for all 21 components
+
+#### 2. Document Missing High-Priority Components
+
+**Components:**
+
+- InputAddon (used with Input)
+- InputGroup (form layouts)
+- Slider (range selection)
+- Spinner (loading states)
+
+**Why:** These are frequently used with other components, AI needs to know they exist
+
+**Action:** Create component guidelines following your existing template
+
+**Estimate:** 6-8 hours (4 components × 1.5-2 hours each)
+
+#### 3. Add Multi-Token Integration Examples
+
+**Where:** Add new section to each token file (colors, typography, spacing, elevation)
+
+**Section Title:** "## How [Token Type] Works With Other Tokens"
+
+**Content:** 5-10 examples showing token combinations in real components
+
+**Estimate:** 3-4 hours total
+
+### 🟡 Medium Priority (Improves AI Accuracy)
+
+#### 4. Create overview-patterns.md
+
+**Purpose:** Document common patterns that span multiple components
+
+**Content:**
+
+```markdown
+# Common UI Patterns
+
+## Form Layouts
+
+### Vertical Form (Default)
+
+[Complete example with Input, Textarea, Select, Button]
+
+### Horizontal Form (Compact)
+
+[Example with InputGroup, Button]
+
+### Multi-Step Form
+
+[Example with Tabs, validation, progress]
+
+## Navigation Patterns
+
+### Sidebar Navigation
+
+[Example with Drawer, Card, Icon]
+
+### Tabbed Interface
+
+[Example with Tabs, Card content]
+
+## Feedback Patterns
+
+### Success Flow
+
+[Toast + Progress + Badge examples]
+
+### Error Handling
+
+[Input validation + Toast + Dialog]
+
+## Loading States
+
+### Page Load
+
+[Skeleton → Content transition]
+
+### Partial Load
+
+[Spinner for specific sections]
+```
+
+**Estimate:** 4-5 hours
+
+#### 5. Refactor Guidelines.md for Cleaner Navigation
+
+**Current:** 195 lines with mixed navigation + content
+
+**Target:** ~100 lines, navigation only
+
+**Actions:**
+
+- Move "Package Imports" section → overview-imports.md (new)
+- Move "Quick Reference" tables → overview-components.md (expand existing)
+- Keep only: System intro, Step-by-step instructions, Core principles
+
+**Estimate:** 2 hours
+
+#### 6. Add Edge Case Examples to Complex Components
+
+**Target Components:**
+
+- Select (empty state, invalid pre-selected value, dynamic options)
+- Dialog (nested dialogs, focus trap edge cases)
+- Tabs (dynamic tabs, too many tabs, accessibility)
+- Drawer (stacked drawers, mobile considerations)
+
+**Estimate:** 3-4 hours
+
+### 🟢 Low Priority (Nice to Have)
+
+#### 7. Document Utility Components
+
+**Components:** CloseButton, Icon, AbsoluteCenter, Group, Loader
+
+**Rationale:** Less frequently used, AI can infer usage more easily
+
+**Estimate:** 3-4 hours
+
+#### 8. Create overview-accessibility.md
+
+**Content:**
+
+- WCAG 2.1 compliance overview
+- Keyboard navigation patterns across components
+- Screen reader testing guidelines
+- Color contrast requirements
+- Focus management principles
+
+**Estimate:** 3-4 hours
+
+#### 9. Add overview-icons.md (if you have icon system)
+
+**Only if:** You have a standardized icon system/library
+
+**Content:**
+
+- Icon naming conventions
+- Icon sizing system
+- When to use Icon vs. IconButton
+- Custom icon integration
+
+**Estimate:** 2-3 hours
+
+---
+
+## 5. Token Documentation Quality Assessment
+
+### colors.md ✅ Excellent
+
+**Strengths:**
+
+- ✅ Clear "Why Semantic Colors?" philosophy
+- ✅ Complete token reference with light/dark values
+- ✅ Usage guidance for each token
+- ✅ Color pairing rules ("on-" pattern)
+- ✅ Accessibility mention
+
+**Minor Enhancements:**
+
+- Add decision tree for choosing color tokens
+- Add 3-5 multi-token examples (color + typography + spacing)
+
+### typography.md ✅ Excellent
+
+**Strengths:**
+
+- ✅ Complete M3 type scale
+- ✅ Clear use cases for each scale
+- ✅ Font family tokens documented
+- ✅ Line height, weight, letter spacing included
+
+**Minor Enhancements:**
+
+- Add decision tree for selecting text styles
+- Add examples showing typography + color pairings
+
+### spacing.md ✅ Excellent
+
+**Strengths:**
+
+- ✅ Clear 8px grid explanation
+- ✅ Usage patterns with code examples
+- ✅ Common patterns section
+- ✅ Component internal vs layout spacing distinction
+
+**Minor Enhancements:**
+
+- Add decision tree for spacing selection
+- Add examples of spacing + elevation combinations
+
+### elevation.md ✅ Excellent
+
+**Strengths:**
+
+- ✅ M3 surface tint system explained
+- ✅ Clear elevation levels with use cases
+- ✅ Shadow vs. tint approach documented
+
+**Minor Enhancements:**
+
+- Add decision tree for elevation selection
+- Add examples showing elevation + color tokens
+
+---
+
+## 6. Implementation Roadmap
+
+### Phase 1: Critical Alignment (Week 1)
+
+**Goal:** Ensure Figma Make can accurately use existing components
+
+1. **Day 1-2:** Add decision trees to all 21 component files
+2. **Day 3:** Add multi-token examples to token files
+3. **Day 4-5:** Document InputAddon, InputGroup, Slider, Spinner
+
+**Deliverable:** Fully Figma Make-optimized documentation for 25 components
+
+### Phase 2: Enhanced Patterns (Week 2)
+
+**Goal:** Improve AI understanding of component interactions
+
+1. **Day 1-2:** Create overview-patterns.md
+2. **Day 3:** Refactor Guidelines.md for cleaner navigation
+3. **Day 4-5:** Add edge case examples to complex components
+
+**Deliverable:** Pattern library and refined navigation
+
+### Phase 3: Complete Coverage (Week 3)
+
+**Goal:** 100% component coverage + accessibility overview
+
+1. **Day 1-2:** Document utility components (CloseButton, Icon, etc.)
+2. **Day 3-4:** Create overview-accessibility.md
+3. **Day 5:** Create overview-icons.md (if applicable)
+
+**Deliverable:** Complete design system documentation
+
+---
+
+## 7. Figma Make Integration Checklist
+
+Use this to verify alignment with Figma Make requirements:
+
+### File Structure
+
+- [x] `guidelines/Guidelines.md` exists and provides navigation
+- [x] `guidelines/overview-components.md` exists
+- [ ] `guidelines/overview-patterns.md` (recommended)
+- [ ] `guidelines/overview-accessibility.md` (recommended)
+- [x] `guidelines/design-tokens/` folder with 4 token categories
+- [x] `guidelines/components/` folder with component docs
+
+### Guidelines.md Quality
+
+- [x] Step-by-step instructions for AI
+- [x] Imperative language (no hedging)
+- [x] Clear file navigation structure
+- [ ] Kept under 150 lines (currently 195, could trim)
+- [x] Links to all overview files
+
+### Token Documentation Quality
+
+- [x] Philosophy section (why tokens exist)
+- [x] Complete token reference
+- [x] Usage guidance for each token
+- [ ] Decision trees for token selection
+- [ ] Multi-token integration examples (5+ per file)
+
+### Component Documentation Quality
+
+- [x] Purpose statement
+- [x] Import examples
+- [x] Props/API reference
+- [x] 15+ working code examples
+- [x] Do's & Don'ts with ❌/✅
+- [x] Accessibility guidelines
+- [ ] Decision tree at top of file
+- [ ] Edge case examples
+
+### Content Quality
+
+- [x] Imperative, unambiguous statements
+- [x] No hedging language ("must" not "should")
+- [x] Code examples are complete and working
+- [x] Clear incorrect vs. correct patterns
+- [x] Organized for AI context selection
+
+### Coverage
+
+- [x] 70% of components documented (21/30)
+- [ ] 100% of commonly-used components (missing 4 high-priority)
+- [x] All major token categories
+- [ ] Common UI patterns documented
+
+---
+
+## 8. Conclusion
+
+### Overall Assessment
+
+**Score: 8/10** - Excellent foundation, minor enhancements needed
+
+**Strengths:**
+
+- ✅ **Comprehensive component docs** - 300+ pages, 500+ examples
+- ✅ **Strong imperative language** - Clear AI instructions
+- ✅ **Complete token system** - All M3 categories documented
+- ✅ **Excellent structure** - Step-by-step Guidelines.md
+- ✅ **Do's & Don'ts** - Clear ❌/✅ patterns throughout
+
+**Priority Improvements:**
+
+1. 🔴 **Add decision trees** to component files (2-3 hours)
+2. 🔴 **Document 4 missing components** (6-8 hours)
+3. 🔴 **Add multi-token examples** (3-4 hours)
+4. 🟡 **Create overview-patterns.md** (4-5 hours)
+5. 🟡 **Refactor Guidelines.md** (2 hours)
+
+### Estimated Effort
+
+**To achieve 10/10 Figma Make optimization:**
+
+- **Phase 1 (Critical):** 11-15 hours
+- **Phase 2 (Enhanced):** 9-11 hours
+- **Phase 3 (Complete):** 8-10 hours
+
+**Total:** 28-36 hours of work
+
+### Recommendation
+
+**Start with Phase 1** to maximize Figma Make effectiveness with minimal effort. The decision trees and multi-token examples will provide the biggest AI accuracy improvement.
+
+Your existing documentation is **already usable with Figma Make** - these enhancements will make it **exceptional**.
+
+---
+
+**Generated:** 2026-01-13 by Claude Sonnet 4.5
+**Next Review:** After Phase 1 implementation