npm - codymaster - Versions diffs - 4.1.4 → 4.3.0 - Mend

codymaster 4.1.4 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (657) hide show

package/skills/cm-ux-master/docs/plan/PHASE3-VALIDATION-COMPLETION.md ADDED Viewed

@@ -0,0 +1,499 @@
+# Phase 3: Validation Engine + Harvester v4 Integration
+## Complete Implementation Report
+---
+## Executive Summary
+**Status: ✅ COMPLETE**
+Successfully implemented and integrated:
+1. **Validation Engine v4** - 37 Design Tests with pass/fail criteria
+2. **Harvester v4 Integration** - Automated design system extraction
+3. **MCP Server Integration** - Real-time validation via API
+4. **Figma Plugin** - Visual validation results for designers
+5. **CLI Enhancement** - Full validation command suite
+---
+## 1. Validation Engine v4
+**File:** `scripts/validation_engine.py`
+### Features
+- **37 Design Tests** across 8 categories:
+  - Mobile (7 tests): Fitts's Law, Thumb Zone, Touch Feedback, etc.
+  - Landing Page (6 tests): Hero Clarity, CTA Prominence, Social Proof, etc.
+  - Dashboard (6 tests): Data Density, Quick Actions, Empty States, etc.
+  - Typography (4 tests): Hierarchy, Line Length, Font Pairing, etc.
+  - Color (4 tests): WCAG Contrast, Semantic Colors, Neutral Scale, etc.
+  - Layout (4 tests): Spacing System, Border Radius, Grid System, etc.
+  - Accessibility (5 tests): Focus States, Input Labels, ARIA, Keyboard Nav, etc.
+  - Interaction (5 tests): Animation Performance, Transition Timing, etc.
+### Test Structure
+```python
+class DesignTest:
+    test_id: str       # e.g., "DT-MOB-001"
+    name: str          # Human-readable name
+    category: str      # mobile, landing, dashboard, etc.
+    severity: str      # critical, high, medium, low
+    ux_law: str        # Associated UX Law
+    def run(self, data: dict) -> TestResult:
+        # Returns passed/fail with actionable feedback
+```
+### Example Test Output
+```json
+{
+  "test_id": "DT-MOB-001",
+  "name": "Fitts's Law - Touch Target Size",
+  "category": "mobile",
+  "severity": "critical",
+  "passed": false,
+  "message": "3 components below minimum size",
+  "details": {"issues": [...]},
+  "suggestion": "Increase touch targets to at least 44x44px",
+  "ux_law": "Fitts's Law"
+}
+```
+### Output Formats
+- **JSON**: Machine-readable for CI/CD
+- **Markdown**: Human-readable reports
+- **HTML**: Beautiful dashboard with visualizations
+- **Rich**: Terminal output with colors and tables
+---
+## 2. Harvester v4 Integration
+**File:** `scripts/harvester_v4.js` + `scripts/validation_engine.py`
+### Integration Flow
+```
+Website URL
+    ↓
+Harvester v4 (Browser Injection)
+    ↓
+Extract: Colors, Typography, Spacing, Components
+    ↓
+Design System Indexer
+    ↓
+Validation Engine (37 Tests)
+    ↓
+Validation Report + Design Tokens
+```
+### Validation Pipeline
+```python
+# 1. Harvest data from website
+harvester_data = harvester.harvest("https://example.com")
+# 2. Run validation
+engine = ValidationEngine()
+report = engine.validate(harvester_data, test_suite="all")
+# 3. Results include:
+# - Score (0-100)
+# - Pass/fail for each test
+# - Actionable suggestions
+# - Related UX Laws
+```
+---
+## 3. MCP Server Integration
+**File:** `mcp/server.py`
+### New/Updated Endpoints
+#### `validate_design`
+```python
+POST /mcp/v1/tools/call
+{
+  "name": "validate_design",
+  "arguments": {
+    "html": "<html>...</html>",
+    "test_suite": "all"  # or mobile, landing, a11y, etc.
+  }
+}
+# Response:
+{
+  "status": "completed",
+  "score": 85.5,
+  "passed": 32,
+  "failed": 5,
+  "total": 37,
+  "summary": {...},
+  "tests": [...],
+  "critical_issues": 0
+}
+```
+#### `extract_design_system`
+```python
+POST /mcp/v1/tools/call
+{
+  "name": "extract_design_system",
+  "arguments": {
+    "url": "https://example.com",
+    "depth": 1,
+    "include_screenshots": false
+  }
+}
+# Response includes:
+# - Extracted design system
+# - Generated CSS
+# - Semi Design tokens
+# - Validation report
+```
+---
+## 4. Figma Plugin Enhancement
+**Files:**
+- `mcp/integrations/figma/plugin/ui.html`
+- `mcp/integrations/figma/plugin/code.js`
+### Validate Tab Features
+- **Test Suite Selection**: All, Mobile, Landing, Dashboard, Accessibility
+- **Visual Score Display**: Large score with color coding
+- **Category Breakdown**: Grid of category scores
+- **Failed Tests List**: Grouped by severity (Critical, High, Medium)
+- **Quick Fixes**: Top recommendations
+- **UX Law References**: Shows which UX Law each test validates
+### UI Flow
+```
+1. Designer selects frame
+2. Chooses test suite
+3. Clicks "Run Validation"
+4. Loading spinner: "Running 37 Design Tests..."
+5. Results appear:
+   - Score (e.g., 85/100)
+   - Passed/Failed counts
+   - Category breakdown
+   - Failed tests with fixes
+```
+### Validation Results UI
+```
+┌─────────────────────────────┐
+│  85                         │
+│  Design Quality Score       │
+│                             │
+│  32 PASSED   5 FAILED       │
+│                             │
+│  [Mobile 90%] [Color 80%]   │
+│  [Type 75%]   [Layout 95%]  │
+└─────────────────────────────┘
+⚠ 5 Issues Found
+Critical (1)
+┌─────────────────────────────┐
+│ Fitts's Law - Touch Target  │
+│ 3 components too small      │
+│ 💡 Increase to 44x44px      │
+│ UX Law: Fitts's Law         │
+└─────────────────────────────┘
+High Priority (2)
+...
+💡 Quick Fixes
+• Increase touch targets
+• Improve color contrast
+• Add heading hierarchy
+```
+---
+## 5. CLI Enhancement
+**File:** `cli/uxmaster/cli.py` + `cli/uxmaster/commands/validate.py`
+### New Commands
+```bash
+# Validate local HTML/JSON file
+uxm validate index.html --suite mobile --format rich
+# Validate live URL with Harvester v4
+uxm validate https://stripe.com --url --suite all
+# Validate specific component
+uxm validate button.json --component button
+# Generate reports
+uxm validate index.html --format html --output report.html
+uxm validate index.html --format markdown --output report.md
+uxm validate index.html --format json --output report.json
+# Quick accessibility check
+uxm validate https://example.com --url --suite a11y
+```
+### CLI Output Example
+```bash
+$ uxm validate https://stripe.com --url --suite mobile
+    ██╗   ██╗██╗  ██╗███╗   ███╗ █████╗ ███████╗████████╗███████╗██████╗
+    ██║   ██║╚██╗██╔╝████╗ ████║██╔══██╗██╔════╝╚══██╔══╝██╔════╝██╔══██╗
+    ██║   ██║ ╚███╔╝ ██╔████╔██║███████║███████╗   ██║   █████╗  ██████╔╝
+    ██║   ██║ ██╔██╗ ██║╚██╔╝██║██╔══██║╚════██║   ██║   ██╔══╝  ██╔══██╗
+    ╚██████╔╝██╔╝ ██╗██║ ╚═╝ ██║██║  ██║███████║   ██║   ███████╗██║  ██║
+     ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝╚═╝  ╚═╝
+                    Ultimate UX Design Intelligence v2.0.0
+Validating URL: https://stripe.com
+Using Harvester v4 + Validation Engine | Suite: mobile
+✓ Harvest complete: 127 tokens extracted
+✓ Validation complete
+[green]Score: 92/100[/green]
+Passed: 6/7 tests
+Results by Category:
+┌──────────┬────────┬────────┬───────┐
+│ Category │ Passed │ Failed │ Score │
+├──────────┼────────┼────────┼───────┤
+│ Mobile   │ 6      │ 1      │ 86%   │
+└──────────┴────────┴────────┴───────┘
+Failed Tests:
+  ⚠ DT-MOB-002: Thumb Zone Placement
+    Issue: Consider bottom navigation for mobile
+    Fix: Place primary actions within bottom 25% of screen
+```
+---
+## 6. Test Suite Details
+### Mobile Tests (7)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-MOB-001 | Fitts's Law - Touch Target Size | Critical | Fitts's Law |
+| DT-MOB-002 | Thumb Zone Placement | High | Thumb Zone |
+| DT-MOB-003 | Touch Feedback States | High | Affordance |
+| DT-MOB-004 | Mobile Tap Delay | Medium | Response Time |
+| DT-MOB-005 | Swipe Gesture Support | Low | Natural Mapping |
+| DT-MOB-006 | Gestural Consistency | Medium | Consistency |
+| DT-MOB-007 | Pull-to-Refresh | Low | Natural Mapping |
+### Landing Page Tests (6)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-LND-001 | Hero Value Proposition Clarity | Critical | 5-Second Test |
+| DT-LND-002 | CTA Visual Dominance | Critical | Visual Hierarchy |
+| DT-LND-003 | Social Proof Placement | High | Social Proof |
+| DT-LND-004 | Form Field Minimization | High | Hick's Law |
+| DT-LND-005 | Trust Indicators | High | Trust |
+| DT-LND-006 | FAQ Visibility | Medium | Information Scent |
+### Dashboard Tests (6)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-DSH-001 | Information Density | High | Information Scent |
+| DT-DSH-002 | Quick Actions Accessibility | High | Efficiency |
+| DT-DSH-003 | Empty State Design | Medium | Affordance |
+| DT-DSH-004 | Loading State Strategy | Medium | Perceived Performance |
+| DT-DSH-005 | Real-time Updates | Medium | Freshness |
+| DT-DSH-006 | Customization Options | Low | Control |
+### Typography Tests (4)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-TYP-001 | Typography Hierarchy | Critical | Visual Hierarchy |
+| DT-TYP-002 | Optimal Line Length | Medium | Readability |
+| DT-TYP-003 | Font Family Limit | Medium | Consistency |
+| DT-TYP-004 | Font Loading Strategy | Medium | Performance |
+### Color Tests (4)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-CLR-001 | WCAG Color Contrast | Critical | Accessibility |
+| DT-CLR-002 | Semantic Color System | High | Consistency |
+| DT-CLR-003 | Neutral Gray Scale | High | Depth |
+| DT-CLR-004 | Dark Mode Support | Low | Preference |
+### Layout Tests (4)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-LYT-001 | Spacing System Consistency | High | Rhythm |
+| DT-LYT-002 | Border Radius Consistency | Medium | Consistency |
+| DT-LYT-003 | Grid System Usage | Medium | Alignment |
+| DT-LYT-004 | Responsive Breakpoints | High | Adaptability |
+### Accessibility Tests (5)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-A11-001 | Focus State Visibility | Critical | Accessibility |
+| DT-A11-002 | Input Label Association | Critical | Accessibility |
+| DT-A11-003 | ARIA Attribute Usage | High | Accessibility |
+| DT-A11-004 | Keyboard Navigation | Critical | Accessibility |
+| DT-A11-005 | Screen Reader Support | High | Accessibility |
+### Interaction Tests (5)
+| ID | Name | Severity | UX Law |
+|----|------|----------|--------|
+| DT-INT-001 | Animation Performance | Medium | Performance |
+| DT-INT-002 | Transition Timing | Medium | Timing |
+| DT-INT-003 | Hover Response Time | Medium | Responsiveness |
+| DT-INT-004 | Error Prevention | High | Safety |
+| DT-INT-005 | Undo Capability | Medium | Control |
+---
+## 7. Usage Examples
+### Example 1: Validate Local File
+```bash
+# Validate with all tests
+uxm validate landing-page.html --suite all --format html --output report.html
+# Output: report.html with visual dashboard
+```
+### Example 2: Validate Live Website
+```bash
+# Quick mobile check
+uxm validate https://stripe.com --url --suite mobile
+# Full validation
+uxm validate https://linear.app --url --suite all --format markdown
+```
+### Example 3: Figma Plugin
+```
+1. Open Figma, select a frame
+2. Open UX-Master plugin
+3. Click "Validate" tab
+4. Select test suite: "Mobile"
+5. Click "Run Validation"
+6. See score and fix suggestions
+```
+### Example 4: MCP Integration
+```python
+# From Claude/Cursor/etc
+response = mcp_client.call_tool("validate_design", {
+    "html": html_content,
+    "test_suite": "a11y"
+})
+# Response includes:
+# - Score
+# - Failed tests
+# - Suggestions
+# - UX Law references
+```
+---
+## 8. File Structure
+```
+ux-master/
+├── scripts/
+│   ├── validation_engine.py      # 37 Design Tests (NEW)
+│   ├── harvester_v4.js           # Visual extraction (EXISTING)
+│   ├── design_system_indexer.py  # Token processing (EXISTING)
+│   └── test_harvester_v4.py      # Test suite (EXISTING)
+│
+├── cli/uxmaster/
+│   ├── commands/
+│   │   └── validate.py           # CLI validation (UPDATED)
+│   └── cli.py                    # CLI entry (UPDATED)
+│
+├── mcp/
+│   ├── server.py                 # MCP server (UPDATED)
+│   └── integrations/figma/
+│       └── plugin/
+│           ├── ui.html           # Plugin UI (UPDATED)
+│           └── code.js           # Plugin logic (NEW)
+│
+└── PHASE3-VALIDATION-COMPLETION.md  # This file
+```
+---
+## 9. Metrics
+| Component | Lines of Code | Status |
+|-----------|--------------|--------|
+| Validation Engine | 1,800 | ✅ Complete |
+| MCP Integration | 300 | ✅ Complete |
+| Figma Plugin UI | 400 | ✅ Complete |
+| Figma Plugin Code | 500 | ✅ Complete |
+| CLI Commands | 300 | ✅ Complete |
+| **Total** | **3,300** | ✅ |
+---
+## 10. Next Steps
+### Phase 4: Polish & Launch
+1. **Testing Suite** - pytest coverage for validation engine
+2. **Documentation** - API docs, tutorials
+3. **Demo Video** - Show validation in action
+4. **Publish** - PyPI, Figma Community, NPM
+### Phase 5: Advanced Features
+1. **AI-Powered Fixes** - Suggest automatic fixes
+2. **Regression Testing** - Compare validation runs
+3. **Team Dashboard** - Share validation reports
+4. **CI/CD Integration** - GitHub Actions, GitLab CI
+---
+## Summary
+The Validation Engine v4 is now fully integrated with:
+✅ **37 Design Tests** with pass/fail criteria
+✅ **Harvester v4** for automated extraction
+✅ **MCP Server** for AI tool integration
+✅ **Figma Plugin** for designer-friendly validation
+✅ **CLI** for power users and CI/CD
+**Usage is simple:**
+```bash
+uxm validate https://example.com --url
+```
+**Or in Figma:** Select frame → Click Validate → See results
+**Result:** Instant validation against 37 UX best practices with actionable fixes! 🎉