@schandlergarcia/sf-web-components 1.9.28 → 1.9.30

package/.a4drules/skills/command-center-guide/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: command-center-guide
+description: Master guide for building command center dashboards. Routes to the appropriate specialized skills based on task type. Use this when starting any command center work to understand which skills to apply and in what order.
+---
+
+# Command Center Development Guide
+
+This is the master routing guide for building command center dashboards. It helps you understand which skills to use, when to use them, and how they work together.
+
+## Available Skills
+
+The command center codebase has **4 specialized skills** that work together:
+
+| Skill Name | Purpose | Line Count | When to Use |
+|------------|---------|------------|-------------|
+| **[component-library](#component-library)** | Complete component API reference | 55 + 8 sub-files | Looking up component props, data shapes, or choosing which component to use |
+| **[command-center-builder](#command-center-builder)** | Dashboard build rules and workflows | 46 + 6 sub-files | Building/editing dashboards, layouts, styling, validation |
+| **[command-center-project](#command-center-project)** | Project structure and routing | 100 lines | Understanding project organization, adding new pages to routes |
+| **[outer-app](#outer-app)** | App shell and global navigation | 61 lines | Modifying header, sidebar, global nav, or app wrapper |
+
+Plus **1 feature rule**:
+- **command-center-dashboard-rule.md** (50 lines) — Automated validation rules for dashboards
+
+## Decision Tree: Which Skill to Use?
+
+Follow this decision tree to find the right skill:
+
+### 1. Are you building or editing a dashboard page?
+
+**YES** → Use **[command-center-builder](#command-center-builder)**
+
+Start with [getting-started.md](../command-center-builder/getting-started.md) to understand critical requirements, then follow the workflow:
+- Page structure & layout → [page-layout.md](../command-center-builder/page-layout.md)
+- Choosing components → [components-styling.md](../command-center-builder/components-styling.md)
+- Building charts → [charts-visualization.md](../command-center-builder/charts-visualization.md)
+- Validation → [completion-checklist.md](../command-center-builder/completion-checklist.md)
+
+**NO** → Continue to question 2
+
+### 2. Do you need to look up a component's props or data shape?
+
+**YES** → Use **[component-library](#component-library)**
+
+Start with [when-to-use.md](../component-library/when-to-use.md) decision matrix, then go to the relevant detail file:
+- Cards (MetricCard, ChartCard, TableCard, etc.) → [card-components.md](../component-library/card-components.md)
+- Charts & visualizations → [charts.md](../component-library/charts.md)
+- Forms & filters → [forms-filters.md](../component-library/forms-filters.md)
+- Chat & data → [chat-data.md](../component-library/chat-data.md)
+- Advanced components → [hero-ui.md](../component-library/hero-ui.md)
+- Troubleshooting props → [common-mistakes.md](../component-library/common-mistakes.md)
+
+**NO** → Continue to question 3
+
+### 3. Are you adding a new page or modifying routes?
+
+**YES** → Use **[command-center-project](#command-center-project)**
+
+This skill explains:
+- Project structure (`src/pages/`, `src/dashboards/`, etc.)
+- How to register new pages in the router
+- Route configuration
+- Where different file types live
+
+**NO** → Continue to question 4
+
+### 4. Are you modifying the app shell (header, sidebar, global nav)?
+
+**YES** → Use **[outer-app](#outer-app)**
+
+This skill covers:
+- App wrapper layout
+- Global header component
+- Sidebar navigation
+- Theme/dark mode toggle
+- App-level configuration
+
+**NO** → If none of the above, ask for clarification or check **command-center-builder** as the default.
+
+## Common Workflows
+
+### Workflow 1: Build a New Dashboard from Scratch
+
+1. **[command-center-builder](../command-center-builder/getting-started.md)** — Read STOP and CRITICAL rules first
+2. **[command-center-project](../command-center-project/SKILL.md)** — Understand where to create the page file
+3. **[command-center-builder/page-layout.md](../command-center-builder/page-layout.md)** — Wire up the page and choose layout
+4. **[component-library/when-to-use.md](../component-library/when-to-use.md)** — Choose components from decision matrix
+5. **[component-library](../component-library/SKILL.md)** — Look up exact props for each component
+6. **[command-center-builder/charts-visualization.md](../command-center-builder/charts-visualization.md)** — If using charts, follow MANDATORY rules
+7. **[command-center-builder/completion-checklist.md](../command-center-builder/completion-checklist.md)** — Validate before reporting done
+
+### Workflow 2: Add a Chart to an Existing Dashboard
+
+1. **[command-center-builder/charts-visualization.md](../command-center-builder/charts-visualization.md)** — Read chart requirements
+2. **[component-library/charts.md](../component-library/charts.md)** — Look up D3Chart props and templates
+3. **[component-library/card-components.md](../component-library/card-components.md)** — Look up ChartCard wrapper props
+4. **[command-center-builder/completion-checklist.md](../command-center-builder/completion-checklist.md)** — Validate chart implementation
+
+### Workflow 3: Troubleshoot a Component Error
+
+1. **[component-library/common-mistakes.md](../component-library/common-mistakes.md)** — Check "Do Not" list for common errors
+2. **[component-library](../component-library/SKILL.md)** — Look up the component in the relevant detail file
+3. Verify you're using exact prop names (not guessing)
+4. Check that you imported from `@/components/library` correctly
+
+### Workflow 4: Style or Theme a Dashboard
+
+1. **[command-center-builder/components-styling.md](../command-center-builder/components-styling.md)** — Brand colors, semantic colors, dark mode
+2. **[component-library/ui-primitives.md](../component-library/ui-primitives.md)** — UI primitives for styling consistency
+3. **[command-center-builder/getting-started.md](../command-center-builder/getting-started.md)** — Image requirements
+
+### Workflow 5: Add Global Navigation or Modify App Shell
+
+1. **[outer-app](../outer-app/SKILL.md)** — App shell structure and header/sidebar
+2. **[command-center-project](../command-center-project/SKILL.md)** — Router configuration if adding nav links
+
+## Skill Interaction Rules
+
+### component-library vs command-center-builder
+
+- **component-library** = WHAT (exact props, data shapes, API reference)
+- **command-center-builder** = WHEN & HOW (which component to use, layout patterns, validation rules)
+
+**Use both together:** command-center-builder tells you which component to use, component-library tells you how to use it.
+
+### command-center-project vs outer-app
+
+- **command-center-project** = Dashboard pages and routing
+- **outer-app** = App wrapper and global navigation
+
+**Boundary:** If it's inside `src/dashboards/` → command-center-project. If it's in `App.tsx` or global layout → outer-app.
+
+### When to Read Multiple Skills
+
+Some tasks require multiple skills in sequence:
+
+- **Building a new dashboard** → command-center-builder + component-library + command-center-project
+- **Adding a chart** → command-center-builder + component-library
+- **Modifying navigation** → outer-app + command-center-project
+- **Troubleshooting** → component-library (common-mistakes) first, then command-center-builder
+
+## Critical Reminders
+
+1. **ALWAYS start with command-center-builder/getting-started.md** before building any dashboard
+2. **NEVER guess component prop names** — look them up in component-library
+3. **NEVER hand-roll HTML cards** — use library components only
+4. **ALWAYS run the completion checklist** before reporting done
+5. **Dark mode is MANDATORY** — check all color choices support it
+6. **Images are MANDATORY** — every dashboard needs visuals
+
+## Feature Rule
+
+The **command-center-dashboard-rule.md** feature provides automated validation. It checks:
+- Component usage (library components vs hand-rolled HTML)
+- Dark mode compliance
+- Image presence
+- Chart implementation
+- Navigation structure
+
+This rule runs automatically during validation. See [completion-checklist.md](../command-center-builder/completion-checklist.md) for details.
+
+## File Organization Summary
+
+All skills are split into sub-files (<300 lines each) for easier navigation:
+
+```
+.a4drules/
+├── features/
+│   └── command-center-dashboard-rule.md (50 lines)
+└── skills/
+    ├── command-center-guide/          ← YOU ARE HERE
+    │   └── SKILL.md (this file)
+    ├── component-library/
+    │   ├── SKILL.md (55 lines - routing file)
+    │   ├── when-to-use.md (39 lines)
+    │   ├── card-components.md (253 lines)
+    │   ├── charts.md (64 lines)
+    │   ├── ui-primitives.md (92 lines)
+    │   ├── forms-filters.md (130 lines)
+    │   ├── chat-data.md (184 lines)
+    │   ├── hero-ui.md (211 lines)
+    │   └── common-mistakes.md (25 lines)
+    ├── command-center-builder/
+    │   ├── SKILL.md (46 lines - routing file)
+    │   ├── getting-started.md (127 lines)
+    │   ├── page-layout.md (143 lines)
+    │   ├── components-styling.md (97 lines)
+    │   ├── data-forms-ai.md (43 lines)
+    │   ├── charts-visualization.md (136 lines)
+    │   └── completion-checklist.md (87 lines)
+    ├── command-center-project/
+    │   └── SKILL.md (100 lines)
+    └── outer-app/
+        └── SKILL.md (61 lines)
+```
+
+## Quick Reference Card
+
+| I need to... | Start here |
+|-------------|------------|
+| Build a new dashboard | [command-center-builder/getting-started.md](../command-center-builder/getting-started.md) |
+| Look up a component's props | [component-library/when-to-use.md](../component-library/when-to-use.md) → relevant detail file |
+| Add a new page to routes | [command-center-project](../command-center-project/SKILL.md) |
+| Modify header or sidebar | [outer-app](../outer-app/SKILL.md) |
+| Build a chart | [command-center-builder/charts-visualization.md](../command-center-builder/charts-visualization.md) |
+| Fix a component error | [component-library/common-mistakes.md](../component-library/common-mistakes.md) |
+| Validate before reporting done | [command-center-builder/completion-checklist.md](../command-center-builder/completion-checklist.md) |
+| Understand project structure | [command-center-project](../command-center-project/SKILL.md) |
+
+## Getting Help
+
+If you're unsure which skill to use:
+1. Start with this guide's decision tree
+2. Check the Quick Reference Card above
+3. When in doubt, start with **command-center-builder** for dashboard work
+4. Use **component-library** for any component prop lookups
+
+Remember: **Skills are split for easier navigation, not sequential reading.** Use the decision tree to jump directly to what you need.

package/.a4drules/skills/command-center-project/SKILL.md

@@ -32,10 +32,10 @@ src/
 ├── features/                  # Feature modules (global-search)
 │   └── global-search/         # Search API, components, hooks
 ├── components/
-│   ├── library/               # Component library (.tsx/.jsx - TypeScript migration in progress)
-│   ├── workspace/             # ComponentRegistry (schema renderer)
+│   ├── library/               # Vendored command-center component library (.jsx files)
+│   ├── workspace/             # ComponentRegistry.jsx (schema renderer)
 │   ├── pages/                 # Dashboard pages (CommandCenter.tsx wraps active dashboard)
-│   ├── ui/                    # shadcn/ui components (button, card, dialog, etc.) - TypeScript
+│   ├── ui/                    # shadcn/ui components (button, card, dialog, etc.)
 │   ├── alerts/                # StatusAlert (CVA + Lucide)
 │   └── layouts/               # CardLayout (uses shadcn Card)
 └── stubs/                     # No-op stubs for standalone dev (sdk-data, webapp-experimental, agentforce)
@@ -81,7 +81,7 @@ Configured in both `vite.config.ts` and `tsconfig.json`:
 
 - **Dashboard pages** go in `src/components/pages/`. Wire into `CommandCenter.tsx` by importing and rendering.
 - **Outer app pages** go in `src/pages/` or `src/features/*/pages/`. Wire into `src/routes.tsx`.
-- **TypeScript** preferred for all code (`.tsx`/`.ts`). Core UI components converted to TypeScript. Legacy `.jsx` files being migrated.
+- **TypeScript** for outer app code (`.tsx`/`.ts`). **JSX** for command center library and dashboard pages (`.jsx`).
 - **Component library** is a vendored copy from command-center-starter — not an npm package. Changes sync manually.
 - Vite config has `loader: { '.js': 'jsx' }` in `optimizeDeps` to support the `.js`→JSX library files.
 - **Reset script:** `npm run reset:command-center` wipes custom dashboards and restores blank canvas.