@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/slds/styling-hooks/README.md

@@ -0,0 +1,408 @@
+# SLDS Styling Hooks Knowledge Base
+
+Comprehensive documentation of all 473 SLDS global styling hooks for AI coding agents.
+
+---
+
+## Structure Overview
+
+```
+styling-hooks/
+├── guidance.md                          [✅ COMPLETE] Main agent guidance
+├── review-guidance.md                   [✅ COMPLETE] Validation report
+│
+├── global-semantic/                     [✅ PHASE 3 COMPLETE]
+│   ├── accent-hooks.md                 [12 hooks - Semantic accent colors]
+│   ├── surface-hooks.md                [10 hooks - Surface & container colors]
+│   └── feedback-hooks.md               [26 hooks - Error, success, warning, info, disabled]
+│
+├── categories/                          [✅ PHASE 4C COMPLETE]
+│   ├── color.md                        [Comprehensive color system guidance]
+│   ├── spacing.md                      [Complete spacing system guidance]
+│   ├── typography.md                   [Full typography system guidance]
+│   ├── shadow.md                       [39 shadow hooks - elevation & focus]
+│   ├── radius.md                       [6 radius hooks - border curvature]
+│   └── sizing.md                       [26 sizing hooks - dimensions, borders, typography-width]
+│
+├── metadata/                            [✅ PHASE 1 COMPLETE]
+│   └── hooks-index.json                [All 473 hooks - Complete index]
+│
+└── scripts/
+    └── generate-hooks-index.js         [Script to regenerate index from metadata]
+```
+
+---
+
+## What's Available
+
+### ✅ Phase 1: Core Structure (Complete)
+
+#### 1. `guidance.md` - Main Agent Guidance
+
+**Purpose:** Primary reference for coding agents
+
+**Contains:**
+
+- Overview of all styling hook categories
+- Three-tier color system (Semantic → System → Palette)
+- Current implementation status (what's available vs. planned)
+- Usage patterns for common scenarios
+- Decision trees for hook selection
+- Migration examples and troubleshooting
+
+#### 2. `global-semantic/*.md` - Semantic Color Documentation
+
+**48 Fully Documented Hooks across 3 files:**
+
+- **Accent:** `accent-1/2/3`, `accent-container`, `border-accent`, `on-accent`
+- **Surface:** `surface-1/2/3`, `surface-container`, `surface-inverse`
+- **Feedback:** Error, Success, Warning, Info, Disabled variants
+
+**Includes:** Usage do/don't, context, state progression, accessibility, related hooks
+
+#### 3. `metadata/hooks-index.json` - Complete Hooks Index
+
+**Total:** 473 global SLDS hooks
+
+**Categories:** Color (312), Spacing (48), Font (46), Shadow (27), Sizing (26), Radius (6), Other (8)
+
+**Use For:** Fast lookup and verification of any hook
+
+---
+
+### ✅ Phase 2: Category Guidance (Complete)
+
+#### 1. `categories/color.md` - Color System Guide
+
+**Covers:** ~312 color hooks
+
+**Key Topics:**
+
+- **Three-tier system:** Semantic UI → System → Palette
+- **Magic numbers:** 50-point separation (text), 40-point (UI elements)
+- **85-5-10 color density rule**
+- **Decision tree for tier selection**
+- **All palette families** with usage guidance
+
+**Agent Gets:** When to use each tier, how to ensure accessibility, common patterns
+
+#### 2. `categories/spacing.md` - Spacing System Guide
+
+**Covers:** 48 spacing hooks
+
+**Key Topics:**
+
+- **Base spacing:** Fixed values (spacing-1 through spacing-12)
+- **Density-aware:** Auto-adapts for comfy/compact modes
+- **Directional variants:** block (vertical), inline (horizontal), var (all sides)
+- **Target sizes:** 44×44px minimum for interactive elements
+
+**Agent Gets:** Which spacing type to use when, how to maintain accessibility
+
+#### 3. `categories/typography.md` - Typography System Guide
+
+**Covers:** 49 typography hooks
+
+**Key Topics:**
+
+- **Numbered weight system:** font-weight-1 through font-weight-7
+- **Line heights:** font-lineheight-1 through font-lineheight-6
+- **Font families:** base, monospace
+- **Typography hierarchy patterns**
+
+**Agent Gets:** How to use numbered (not named) hooks, accessibility requirements (1.5 line height, 14px minimum)
+
+---
+
+### ✅ Phase 3: Complete Semantic Hooks (Complete)
+
+#### 1. `global-semantic/accent-hooks.md` - Accent Colors
+
+**12 Hooks:** Fully documented semantic accent colors
+
+**Includes:**
+
+- `accent-1/2/3` - Text/icon colors with state progression
+- `accent-container-1/2/3` - Background fills for brand buttons
+- `border-accent-1/2/3` - Border colors for brand elements
+- `on-accent-1/2/3` - Foreground colors for accent backgrounds
+
+**Metadata:** Usage do/don't, context, state progression, accessibility, related hooks
+
+#### 2. `global-semantic/surface-hooks.md` - Surface & Container Colors
+
+**10 Hooks:** Complete surface color system
+
+**Includes:**
+
+- `surface-1/2/3` - Page-level backgrounds for stacking context
+- `surface-container-1/2/3` - Container backgrounds for elements on surfaces
+- `on-surface-1/2/3` - Foreground colors with emphasis levels
+- `surface-inverse-1` - Dark mode/inverted surfaces
+
+**Key Insights:**
+
+- Surface numbering is aesthetic choice, NOT interaction states
+- Surface vs. surface-container is semantic distinction (same color values)
+- On-surface pairing based on emphasis, not strict number matching
+
+#### 3. `global-semantic/feedback-hooks.md` - Feedback States
+
+**26 Hooks:** Complete feedback color system
+
+**Includes:**
+
+- **Error (7 hooks):** error-1, error-container-1/2, border-error-1/2, on-error-1/2
+- **Success (7 hooks):** success-1, success-container-1/2, border-success-1/2, on-success-1/2
+- **Warning (4 hooks):** warning-1, warning-container-1, border-warning-1, on-warning-1
+- **Info (3 hooks):** info-1, info-container-1, on-info-1
+- **Disabled (5 hooks):** disabled-1/2, disabled-container-1/2, border-disabled-1, on-disabled-1/2
+
+**Key Insights:**
+
+- Error/Success have -2 variants for interactive destructive/confirmation buttons
+- Warning/Info lack -2 variants (no interactive buttons in SLDS2 currently)
+- Disabled variants represent visual weight, not interaction states
+
+---
+
+### ✅ Phase 4C: Shadow, Radius, Sizing (Complete)
+
+#### 1. `categories/shadow.md` - Shadow System
+
+**Covers:** 39 shadow hooks
+
+**Key Topics:**
+
+- **Core shadows:** shadow-1 through shadow-6 for elevation levels
+- **Directional shadows:** block (vertical) and inline (horizontal) placement
+- **Focus shadows:** outline, outset, inset, inverse for keyboard navigation
+- **Inverse shadows:** Dark mode shadow handling
+- **Elevation principles:** Progressive shadow usage for visual hierarchy
+
+**Agent Gets:** When to use each shadow level, how to combine shadows, focus state patterns
+
+#### 2. `categories/radius.md` - Border Radius System
+
+**Covers:** 6 radius hooks
+
+**Key Topics:**
+
+- **Progressive rounding:** radius-border-1 through radius-border-4
+- **Special shapes:** circle (100%) and pill (15rem)
+- **Component-specific usage:** When to use each radius level
+- **Directional radius:** Applying radius to specific corners
+
+**Agent Gets:** Consistent radius choices, circle vs pill usage, accessibility considerations
+
+#### 3. `categories/sizing.md` - Sizing System
+
+**Covers:** 26 sizing hooks (16 general + 4 border + 6 typography-width)
+
+**Key Topics:**
+
+- **Element dimensions:** sizing-1 through sizing-16 for icons, avatars, containers
+- **Border widths:** sizing-border-1 through sizing-border-4
+- **Typography widths:** sizing-content-_ and sizing-heading-_ for optimal readability (character-based)
+- **8-point grid alignment:** Values in multiples of 8
+- **Target sizing:** When to use padding vs fixed dimensions
+- **Responsive scaling:** Relative to root font-size
+
+**Agent Gets:** Icon sizing consistency, avatar dimensions, content width constraints, when NOT to use sizing hooks (spacing)
+
+---
+
+## How Agents Use This Knowledge
+
+### Query Pattern 1: Getting General Guidance
+
+```javascript
+// Agent wants to understand colors
+{
+  {
+    GUIDE_SLDS_STYLING_TOOL;
+  }
+}
+({ topic: 'colors' });
+// Returns: categories/color.md with principles, palette system, rules
+
+// Agent wants to understand spacing
+{
+  {
+    GUIDE_SLDS_STYLING_TOOL;
+  }
+}
+({ topic: 'spacing' });
+// Returns: categories/spacing.md with scale, density-aware hooks, patterns
+```
+
+### Query Pattern 2: Finding Specific Hooks
+
+```javascript
+// Agent needs accent color hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-color-accent-' });
+// Returns: All 12 accent hooks from global-semantic/accent-hooks.md
+
+// Agent wants all spacing hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ category: 'spacing' });
+// Returns: All 48 spacing hooks from metadata/hooks-index.json
+
+// Agent checks if specific hook exists
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ hooks: ['--slds-g-spacing-4'] });
+// Returns: Hook details from index
+```
+
+### Query Pattern 3: Category Exploration
+
+```javascript
+// Agent browses all color hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ category: 'color' });
+// Returns: ~312 color hooks from metadata/hooks-index.json
+
+// Agent searches palette colors
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'palette-neutral' });
+// Returns: All neutral palette hooks
+```
+
+---
+
+## What's Next (Future Phases)
+
+### 🚧 Phase 3: Complete Hook References (Medium Priority)
+
+**Goal:** Generate comprehensive JSON metadata files for all hook categories
+
+1. **`categories/color-hooks.json`** - All 312 color hooks with metadata
+2. **`categories/typography-hooks.json`** - All 46 typography hooks with metadata
+3. **`categories/spacing-hooks.json`** - All 48 spacing hooks with metadata
+4. **`categories/sizing-shadow-radius-hooks.json`** - All utility hooks (sizing: 26, shadow: 27, radius: 6)
+
+**Format:** Detailed metadata (token, category, value, properties) to complement Markdown guides.
+
+### 🔮 Phase 4: Additional Semantic Hooks (Future)
+
+**Goal:** Add more semantic hook documentation as they become available
+
+1. **`global-semantic/container-hooks.md`** - Container color hooks (when documented)
+2. **`global-semantic/border-hooks.md`** - Border semantic hooks (when documented)
+
+---
+
+## Maintenance
+
+### Regenerating the Hooks Index
+
+When `globalstylinghooks.metadata.json` is updated:
+
+```bash
+cd packages/knowledge/styling-hooks
+node scripts/generate-hooks-index.js
+```
+
+This will regenerate `metadata/hooks-index.json` with the latest hook data.
+
+### Adding New Semantic Hooks
+
+1. Create Markdown file in `global-semantic/` directory
+2. Follow format from `accent-hooks.md`
+3. Include: Overview, Available Hooks list, and Detailed Usage sections
+4. Update this README with counts
+
+### Adding New Category Guides
+
+1. Create MD file in `categories/` directory
+2. Include: overview, complete scale/system, decision trees, patterns, accessibility, troubleshooting
+3. Cross-reference other category files and guidance.md
+4. Update this README
+
+---
+
+## Integration with MCP Tools
+
+This knowledge base is consumed by the `{{EXPLORE_SLDS_STYLING_TOOL}}` MCP tool via the `KnowledgeLoader` utility.
+
+### Tool Behavior
+
+**The tool automatically loads:**
+
+- `global-semantic/*.md` → Returns rich documentation for semantic hooks
+- `metadata/hooks-index.json` → Returns basic metadata for all hooks
+- MD files are returned by separate guidance tools
+
+**Query Processing:**
+
+1. Exact lookup (`hooks: ["--slds-g-color-accent-1"]`) → Returns from semantic documentation if available, else from index
+2. Prefix search (`prefix: "--slds-g-color-accent-"`) → Returns all matching hooks
+3. Category filter (`category: "color"`) → Returns all hooks in category
+4. Search (`search: "accent"`) → Fuzzy matches across all hooks
+
+---
+
+## Key Design Decisions
+
+### Why Markdown for Semantic Hooks?
+
+**Decision:** We moved from JSON to Markdown for semantic hook documentation.
+
+**Reasons:**
+
+- ✅ **Context-Rich:** Semantic hooks require explanation (do's/don'ts, accessibility context) which fits better in Markdown.
+- ✅ **Readability:** Easier for both humans and LLMs to consume linear guidance.
+- ✅ **Unified Format:** Aligns with category guides.
+
+**Metadata Role:**
+We still maintain `metadata/hooks-index.json` for fast, structured lookups and existence validation. The Markdown files provide the _qualitative_ guidance, while the JSON index provides the _quantitative_ data (values, categories).
+
+### Why Numbered Spacing (1-12) Not Named (small/medium)?
+
+**Reality:** SLDS metadata uses numbered hooks (`spacing-1` through `spacing-12`)
+
+**Benefits:**
+
+- Precise control over values
+- Clear progression (1 < 2 < 3)
+- No ambiguity (is "small" 8px or 12px?)
+- Aligns with numbered typography scale
+
+**Agent-Friendly:** The MD files provide mapping tables showing numbered hooks with their pixel values and legacy name equivalents.
+
+---
+
+## Questions or Issues?
+
+- **Missing hooks?** Run `{{EXPLORE_SLDS_STYLING_TOOL}}({ search: "your-term" })` to check metadata
+- **Incorrect information?** Check `review-guidance.md` for validation notes
+- **Need to regenerate index?** Run `node scripts/generate-hooks-index.js`
+- **Want to add semantic hooks?** Follow format from `global-semantic/accent-hooks.md`
+
+---
+
+**Last Updated:** November 2025
+**Knowledge Base Version:** 1.1
+**Total Hooks Documented:** 473 (100% of SLDS global hooks)
+**Fully Documented Semantic Hooks:** 48 (Accent: 12, Feedback: 26, Surface: 10)