From 6eeb4a4e9aabcc1e1c01312fee9960aabda7f395 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sun, 1 Feb 2026 18:05:39 -0500 Subject: [PATCH 1/2] feat(projman): add domain-consultation skill for cross-plugin integration Add the core skill that enables projman agents to detect and consult domain-specific plugins (viz-platform, data-platform) during sprint lifecycle. Includes domain detection rules, planning protocol, execution gate protocol, review protocol, and extensibility guidelines. Closes #356 Co-Authored-By: Claude Opus 4.5 From 557bf6115b0621b82e957bc086ec2bf65c5c3272 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sun, 1 Feb 2026 18:06:21 -0500 Subject: [PATCH 2/2] feat(viz-platform): add design-system-audit skill Add comprehensive design system audit skill that provides: - What to check: component prop validity, theme token usage, accessibility compliance, responsive design - Common violation patterns at FAIL/WARN/INFO severity levels - Scanning strategy for finding DMC components in Python files - Report template for audit output - MCP tool integration patterns Closes #357 Co-Authored-By: Claude Opus 4.5 --- .../skills/design-system-audit.md | 280 ++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 plugins/viz-platform/skills/design-system-audit.md diff --git a/plugins/viz-platform/skills/design-system-audit.md b/plugins/viz-platform/skills/design-system-audit.md new file mode 100644 index 0000000..985dc85 --- /dev/null +++ b/plugins/viz-platform/skills/design-system-audit.md @@ -0,0 +1,280 @@ +--- +name: design-system-audit +description: Design system compliance rules and violation patterns for viz-platform audits +--- + +# Design System Audit + +## Purpose + +Defines what to check, how to classify violations, and common patterns for design system compliance auditing of Dash Mantine Components (DMC) code. + +--- + +## What to Check + +### 1. Component Prop Validity + +| Check | Tool | Severity | +|-------|------|----------| +| Invalid prop names (typos) | `validate_component` | FAIL | +| Invalid prop values | `validate_component` | FAIL | +| Missing required props | `validate_component` | FAIL | +| Deprecated props | `get_component_props` | WARN | +| Unknown props | `validate_component` | WARN | + +### 2. Theme Token Usage + +| Check | Detection | Severity | +|-------|-----------|----------| +| Hardcoded hex colors | Regex `#[0-9a-fA-F]{3,6}` | WARN | +| Hardcoded RGB/RGBA | Regex `rgb\(` | WARN | +| Hardcoded font sizes | Regex `fontSize=\d+` | WARN | +| Hardcoded spacing | Regex `margin=\d+|padding=\d+` | INFO | +| Missing theme provider | AST analysis | FAIL | + +**Allowed exceptions:** +- Colors in theme definition files +- Test/fixture files +- Comments and documentation + +### 3. Accessibility Compliance + +| Check | Tool | Severity | +|-------|------|----------| +| Color contrast ratio < 4.5:1 (AA) | `accessibility_validate_colors` | WARN | +| Color contrast ratio < 3:1 (large text) | `accessibility_validate_colors` | WARN | +| Missing aria-label on interactive | Manual scan | WARN | +| Color-only information | `accessibility_validate_theme` | WARN | +| Focus indicator missing | Manual scan | INFO | + +### 4. Responsive Design + +| Check | Detection | Severity | +|-------|-----------|----------| +| Fixed pixel widths > 600px | Regex `width=\d{3,}` | INFO | +| Missing breakpoint handling | No `visibleFrom`/`hiddenFrom` | INFO | +| Non-responsive layout | Fixed Grid columns | INFO | + +--- + +## Common Violations + +### FAIL-Level Violations + +```python +# Invalid prop name (typo) +dmc.Button(colour="blue") # Should be 'color' + +# Invalid enum value +dmc.Button(size="large") # Should be 'lg' + +# Missing required prop +dmc.Select(data=[...]) # Missing 'id' for callbacks + +# Invalid component name +dmc.Buttons(...) # Should be 'Button' + +# Wrong case +dmc.Button(fullwidth=True) # Should be 'fullWidth' + +# React patterns in Dash +dmc.Button(onClick=fn) # Should use 'id' + callback +``` + +### WARN-Level Violations + +```python +# Hardcoded colors +dmc.Text(color="#ff0000") # Use theme token +dmc.Button(style={"color": "red"}) # Use theme token + +# Hardcoded font size +dmc.Text(style={"fontSize": "14px"}) # Use 'size' prop + +# Poor contrast +dmc.Text(color="gray") # Check contrast ratio + +# Inline styles for colors +dmc.Container(style={"backgroundColor": "#f0f0f0"}) + +# Deprecated patterns +dmc.Button(variant="subtle") # Check if still supported +``` + +### INFO-Level Violations + +```python +# Fixed widths +dmc.Container(w=800) # Consider responsive + +# Missing responsive handling +dmc.Grid.Col(span=6) # Consider span={{ base: 12, md: 6 }} + +# Optimization opportunity +dmc.Stack([dmc.Text(...) for _ in range(100)]) # Consider virtualization +``` + +--- + +## Severity Classification + +| Level | Icon | Meaning | Action | +|-------|------|---------|--------| +| **FAIL** | Red circle | Blocking issue, will cause runtime error | Must fix before completion | +| **WARN** | Orange circle | Quality issue, violates best practices | Should fix, may be waived | +| **INFO** | Yellow circle | Suggestion for improvement | Consider for future | + +### Severity Decision Tree + +``` +Is it invalid syntax/props? + YES -> FAIL + NO -> Does it violate accessibility standards? + YES -> WARN + NO -> Does it use hardcoded styles? + YES -> WARN + NO -> Is it a best practice suggestion? + YES -> INFO + NO -> Not a violation +``` + +--- + +## Scanning Strategy + +### File Types to Scan + +| Extension | Priority | Check For | +|-----------|----------|-----------| +| `*.py` | High | DMC component usage | +| `*.dash.py` | High | Layout definitions | +| `theme*.py` | High | Theme configuration | +| `layout*.py` | High | Layout structure | +| `components/*.py` | High | Custom components | +| `callbacks/*.py` | Medium | Component references | + +### Scan Process + +1. **Find relevant files** + ``` + glob: **/*.py + filter: Contains 'dmc.' or 'dash_mantine_components' + ``` + +2. **Extract component usages** + - Parse Python AST + - Find all `dmc.*` calls + - Extract component name and kwargs + +3. **Validate each component** + - Call `validate_component(name, props)` + - Record violations with file:line reference + +4. **Scan for patterns** + - Hardcoded colors (regex) + - Inline styles (AST) + - Fixed dimensions (regex) + +5. **Run accessibility checks** + - Extract color combinations + - Call `accessibility_validate_colors` + +--- + +## Report Template + +``` +Design System Audit Report +========================== +Path: +Files Scanned: N +Timestamp: YYYY-MM-DD HH:MM:SS + +Summary +------- +FAIL: N blocking violations +WARN: N quality warnings +INFO: N suggestions + +Findings +-------- + +FAIL Violations (must fix) +-------------------------- +[file.py:42] Invalid prop 'colour' on Button + Found: colour="blue" + Expected: color="blue" + Docs: https://mantine.dev/core/button + +[file.py:58] Invalid size value on Text + Found: size="huge" + Expected: One of ['xs', 'sm', 'md', 'lg', 'xl'] + +WARN Violations (should fix) +---------------------------- +[theme.py:15] Hardcoded color detected + Found: color="#ff0000" + Suggestion: Use theme color token (e.g., color="red") + +[layout.py:23] Low contrast ratio (3.2:1) + Found: Text on background + Required: 4.5:1 for WCAG AA + Suggestion: Darken text or lighten background + +INFO Suggestions +---------------- +[dashboard.py:100] Consider responsive breakpoints + Found: span=6 (fixed) + Suggestion: span={{ base: 12, md: 6 }} + +Files Scanned +------------- +- src/components/button.py (3 components) +- src/layouts/main.py (8 components) +- src/theme.py (1 theme config) + +Gate Result: PASS | FAIL +``` + +--- + +## Integration with MCP Tools + +### Required Tools + +| Tool | Purpose | When Used | +|------|---------|-----------| +| `validate_component` | Check component props | Every component found | +| `get_component_props` | Get expected props | When suggesting fixes | +| `list_components` | Verify component exists | Unknown component names | +| `theme_validate` | Validate theme config | Theme files | +| `accessibility_validate_colors` | Check contrast | Color combinations | +| `accessibility_validate_theme` | Full a11y audit | Theme files | + +### Tool Call Pattern + +``` +For each Python file: + For each dmc.Component(...) found: + result = validate_component( + component_name="Component", + props={extracted_props} + ) + if result.errors: + record FAIL violation + if result.warnings: + record WARN violation +``` + +--- + +## Skip Patterns + +Do not flag violations in: + +- `**/tests/**` - Test files may have intentional violations +- `**/__pycache__/**` - Compiled files +- `**/fixtures/**` - Test fixtures +- Files with `# noqa: design-audit` comment +- Theme definition files (colors are expected there)