personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(viz-platform): add design-system-audit skill

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-02-01 18:06:21 -05:00
parent 6eeb4a4e9a
commit 557bf6115b
1 changed files with 280 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
plugins/viz-platform/skills/design-system-audit.md Normal file
View File

@@ -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: <scanned-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)