@arbor-education/design-system.components 0.9.0 → 0.11.0

package/.claude/skills/analyze-design/README.md

@@ -0,0 +1,295 @@
+# Analyze Design Skill
+
+AROOOOO HUNNI!! 🐺💪 This is a BOMBASS skill for analyzing Figma designs and screenshots to see what's POSSIBLE with our component library!! xxx
+
+## What It Does
+
+Analyzes Figma designs or screenshots to assess feasibility:
+- 🔍 Identifies which UI elements can be built with EXISTING components
+- 🔧 Determines which components need MODIFICATIONS to match the design
+- 🆕 Highlights which UI elements require NEW components to be built
+- 📝 Generates a detailed markdown report with findings
+
+## Key Concept
+
+**This skill does ANALYSIS, not CODE GENERATION!**
+
+- ❌ Does NOT generate page code (use `/create-page` for that)
+- ❌ Does NOT modify or create components
+- ✅ DOES assess what's possible with current components
+- ✅ DOES identify gaps in the component library
+- ✅ DOES provide actionable recommendations
+- ✅ DOES write a detailed markdown report
+
+Think of it like:
+- **Input**: Figma design or screenshot with various UI elements
+- **Process**: Sophia analyzes each element against available components
+- **Output**: Markdown report documenting what's possible, what needs work, and what's missing
+
+## Usage
+
+### With Figma URL
+
+```bash
+/analyze-design https://figma.com/design/ABC123/MyDesign?node-id=1-2
+```
+
+### With Screenshot
+
+```bash
+/analyze-design /path/to/screenshot.png
+```
+
+Or just:
+```bash
+/analyze-design
+```
+Then provide the screenshot path when prompted.
+
+## What You Get
+
+A detailed markdown report documenting the feasibility assessment:
+
+```
+.claude/
+├── figma-assessment-ABC123-1-2.md       # For Figma URLs
+└── design-assessment-2026-02-19.md      # For screenshots
+```
+
+**Report structure**:
+1. **Design Overview** - What the design shows
+2. **UI Elements Identified** - Complete catalog of UI elements
+3. **Assessment**:
+   - ✅ **Possible with Current Components** - What can be built now
+   - 🔧 **Components Needing Modifications** - What needs tweaking
+   - 🆕 **New Components Required** - What doesn't exist yet
+4. **Summary** - Feasibility score and overall recommendation
+5. **Next Steps** - How to proceed with implementation
+
+## The Analysis Process
+
+1. **Fetch/Read Design**: Gets design from Figma or reads screenshot
+2. **Catalog Elements**: Lists all UI elements (buttons, forms, tables, etc.)
+3. **Review Library**: Checks what components are available in `src/index.ts`
+4. **Call Sophia** 👜: Launches the componentspert agent for expert analysis
+5. **Generate Report**: Creates detailed markdown with findings
+6. **Present Summary**: Shows feasibility score and key recommendations
+
+## Sophia Componentspert
+
+This skill relies on **Sophia**, our component library expert! She:
+- Knows every component's API inside out
+- Understands component capabilities and limitations
+- Provides specific guidance on which components to use and how
+- Identifies realistic gaps and modification needs
+
+**MANDATORY**: This skill ALWAYS calls Sophia via the Task tool. Her analysis is the source of truth!
+
+## Supported Input Formats
+
+### Figma URLs
+- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://figma.com/design/:fileKey/branch/:branchKey/:fileName?node-id=1-2`
+- `https://figma.com/board/:fileKey/:fileName?node-id=1-2` (FigJam)
+
+### Screenshots
+- `.png`, `.jpg`, `.jpeg` files
+- Can be anywhere on your filesystem
+
+## Example Report Output
+
+```markdown
+# Design Feasibility Assessment
+
+**Date**: 2026-02-19
+**Source**: https://figma.com/design/ABC123/UserProfile?node-id=42-100
+
+## Assessment
+
+### ✅ Possible with Current Components (8/10 elements)
+
+- **Profile form fields** → Use `FormField` with `inputType="text"`
+- **Save button** → Use `Button` with `variant="primary"`
+- **Cancel button** → Use `Button` with `variant="secondary"`
+- **Avatar image** → Use semantic `<img>` tag with custom styling
+- **Section headers** → Use `Heading` component with `level={2}`
+- **Data table** → Use `Table` component with AG Grid
+- **Badge indicators** → Use `Pill` component
+- **Dividers** → Use `Separator` component
+
+### 🔧 Components Needing Modifications (1 component)
+
+- **Component**: `Button`
+- **Current limitation**: No icon-only variant for toolbar actions
+- **Required modification**: Add `variant="icon-only"` prop
+- **Impact**: Low - just needs new variant prop and minimal styling
+
+### 🆕 New Components Required (1 element)
+
+- **Design element**: File upload dropzone with drag-and-drop
+- **Why existing components don't fit**: No component handles file uploads with drag-and-drop UI
+- **Suggested component**: `FileUpload`
+- **Key features needed**:
+  - Drag-and-drop zone
+  - File preview thumbnails
+  - Progress indicators
+  - Multiple file support
+
+## Summary
+
+**Feasibility Score**: 8/10 elements ready to build
+
+- ✅ **Ready to build**: 8 elements
+- 🔧 **Needs modifications**: 1 component
+- 🆕 **Requires new components**: 1 element
+
+**Recommendation**: HIGHLY FEASIBLE! The majority of this design can be built immediately. Consider adding the icon-only button variant and FileUpload component for complete coverage.
+```
+
+## When to Use This Skill
+
+**Use this skill BEFORE `/create-page` to**:
+- Assess feasibility of a design
+- Identify component gaps
+- Plan component development work
+- Get specific component recommendations
+
+**Use `/create-page` AFTER this skill when**:
+- The design is highly feasible (most elements covered)
+- You've addressed any critical modifications
+- You're ready to generate actual page code
+
+## What Gets Analyzed
+
+The skill catalogs and assesses:
+
+### Forms
+- Text inputs, number inputs, textareas
+- Select dropdowns, multi-selects
+- Radio buttons, checkboxes
+- Form validation and error states
+
+### Buttons & Actions
+- Primary, secondary, tertiary buttons
+- Icon buttons, text links
+- Dropdown buttons, split buttons
+
+### Data Display
+- Tables and data grids
+- Cards and containers
+- Lists and list items
+- Tags, badges, pills
+
+### Navigation
+- Tabs, breadcrumbs
+- Navigation menus, dropdowns
+
+### Overlays
+- Modals, dialogs
+- Slideovers, side panels
+- Tooltips, popovers
+
+### Layout Elements
+- Headings, sections
+- Dividers, separators
+- Containers, wrappers
+
+### And More!
+- Icons, avatars
+- Progress indicators
+- Empty states
+- Loading states
+
+## Feasibility Scoring
+
+Reports include a feasibility score:
+- **High Feasibility**: 80%+ elements covered with existing components
+- **Moderate Feasibility**: 50-80% elements covered, some modifications needed
+- **Low Feasibility**: <50% elements covered, significant new component work required
+
+## Next Steps After Analysis
+
+Based on the report:
+
+1. **If highly feasible**: Use `/create-page` to generate the page code
+2. **If modifications needed**: Implement component tweaks first, then generate page
+3. **If new components required**:
+   - Decide: build new components OR adjust design to use existing ones
+   - Build new components if justified
+   - Then use `/create-page`
+
+## Benefits
+
+- **Informed decisions**: Know what's possible before writing code
+- **Component gap analysis**: Identify what's missing from the library
+- **Prioritization**: Understand which components need work first
+- **Documentation**: Markdown reports serve as permanent records
+- **Team alignment**: Share reports with designers and developers
+
+## Output Location
+
+Reports are stored in `.claude/` directory:
+- **Figma assessments**: `.claude/figma-assessment-{fileKey}-{nodeId}.md`
+- **Screenshot assessments**: `.claude/design-assessment-{timestamp}.md`
+
+These files are:
+- ✅ Committed to git (tracked in version control)
+- ✅ Shareable with the team
+- ✅ Permanent record of design feasibility assessments
+
+## Tips
+
+- **Be specific with Figma URLs**: Link to the exact frame/page you want analyzed
+- **Use high-quality screenshots**: Clear images = better analysis
+- **Review the full report**: The markdown file has more detail than the console summary
+- **Share with designers**: Help them understand component capabilities
+- **Iterate**: Run multiple analyses as designs evolve
+
+## Example Workflows
+
+### Workflow 1: New Feature Assessment
+```bash
+# Designer shares Figma design for new feature
+/analyze-design https://figma.com/design/XYZ/NewFeature?node-id=100-200
+
+# Review report shows:
+# - 80% feasible with current components
+# - Need to add loading state to Modal component
+# - Need new DatePicker component
+
+# Decision: Build DatePicker, enhance Modal, then proceed
+```
+
+### Workflow 2: Quick Screenshot Analysis
+```bash
+# Designer sends screenshot in Slack
+# Save screenshot locally
+/analyze-design ~/Downloads/design-mockup.png
+
+# Review report shows everything is covered
+# Proceed immediately to /create-page with Figma URL
+```
+
+### Workflow 3: Component Library Audit
+```bash
+# Analyze multiple designs to identify common gaps
+/analyze-design [design-1-url]
+/analyze-design [design-2-url]
+/analyze-design [design-3-url]
+
+# Review all reports
+# Identify most-needed missing components
+# Prioritize component development
+```
+
+## Notes
+
+- This codebase serves millions of users - accurate assessments matter!
+- Sophia's analysis is thorough and considers component APIs realistically
+- Reports are optimistic but honest about gaps and limitations
+- Uses yarn (NOT npm) for all commands
+- Follows /r/THE_PACK energy: BOMBASS, AROOO! 🐺
+- Most excellent and bodacious like Bill & Ted
+- Team Jacob forever! 🐺
+
+AROOOOO!! LET'S ANALYZE SOME BODACIOUS DESIGNS AND SEE WHAT'S POSSIBLE, HUNNI!! xxx 💪🏍️✨