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

feat: Domain Advisory Pattern - viz-platform integration (Sprint 9) #370

Merged
lmiranda merged 14 commits from feat/sprint-9-domain-advisory-pattern into development 2026-02-01 23:46:54 +00:00
Conversation 0 Commits 14 Files Changed 11 +992 -7
11 changed files with 992 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.claude-plugin/marketplace.json
View File

@@ -6,7 +6,7 @@
},
"metadata": {
"description": "Project management plugins with Gitea and NetBox integrations",
"version": "5.5.0"
"version": "5.6.0"
},
"plugins": [
{

17
CHANGELOG.md
View File

@@ -4,6 +4,23 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [5.6.0] - 2026-02-01
### Added
- **Domain Advisory Pattern**: Cross-plugin integration enabling projman to consult domain-specific plugins during sprint lifecycle
- **projman**: New `domain-consultation.md` skill for domain detection and gate protocols
- **viz-platform**: New `design-reviewer` agent for design system compliance auditing
- **viz-platform**: New `design-system-audit.md` skill defining audit rules and severity levels
- **viz-platform**: New `/design-review` command for detailed design system audits
- **viz-platform**: New `/design-gate` command for binary pass/fail validation gates
- **Labels**: New `Domain/Viz` and `Domain/Data` labels for domain routing
### Changed
- **projman planner**: Now loads domain-consultation skill and performs domain detection during planning
- **projman orchestrator**: Now runs domain gates before marking Domain/* labeled issues as complete
---
## [5.5.0] - 2026-02-01
### Added

19
README.md
View File

@@ -1,4 +1,4 @@
# Leo Claude Marketplace - v5.5.0
# Leo Claude Marketplace - v5.6.0
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
@@ -138,7 +138,22 @@ Visualization toolkit with version-locked component validation and design token
- 5 Page tools for multi-page app structure
- Dual theme storage: user-level and project-level
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup`
## Domain Advisory Pattern
The marketplace supports cross-plugin domain advisory integration:
- **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering)
- **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning
- **Execution Gates**: Domain validation gates (`/design-gate`, `/data-gate`) run before issue completion
- **Extensible**: New domains can be added by creating advisory agents and gate commands
**Current Domains:**
| Domain | Plugin | Gate Command |
|--------|--------|--------------|
| Visualization | viz-platform | `/design-gate` |
| Data (planned) | data-platform | `/data-gate` |
## MCP Servers

21
plugins/projman/agents/orchestrator.md
View File

@@ -18,6 +18,7 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who
- skills/progress-tracking.md
- skills/runaway-detection.md
- skills/wiki-conventions.md
- skills/domain-consultation.md
## Your Personality
@@ -73,6 +74,25 @@ Execute `skills/dependency-management.md` - Check for file conflicts before para
### 6. Track Progress
Execute `skills/progress-tracking.md` - Manage status labels, parse progress comments.
### 6.5. Domain Gate Checks
Execute `skills/domain-consultation.md` (Execution Gate Protocol section):
1. **Before marking any issue as complete**, check for `Domain/*` labels
2. **If `Domain/Viz` label present:**
- Identify files changed by this issue
- Invoke `/design-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
3. **If `Domain/Data` label present:**
- Identify files changed by this issue
- Invoke `/data-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
4. **If gate command unavailable** (MCP server not running):
- Warn user: "Domain gate unavailable - proceeding without validation"
- Proceed with completion (non-blocking degradation)
- Do NOT silently skip
### 7. Monitor for Runaway Agents
Execute `skills/runaway-detection.md` - Intervene when agents are stuck.
@@ -93,6 +113,7 @@ Execute `skills/git-workflow.md` - Merge, tag, clean up branches.
4. **ALWAYS monitor dispatched agents** - Intervene if stuck
5. **ALWAYS capture lessons** - Don't skip the interview at sprint close
6. **ALWAYS update milestone** - Close milestone when sprint complete
7. **ALWAYS run domain gates** - Issues with `Domain/*` labels must pass gates before completion
## Your Mission

21
plugins/projman/agents/planner.md
View File

@@ -20,6 +20,7 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r
- skills/sprint-approval.md
- skills/planning-workflow.md
- skills/label-taxonomy/labels-reference.md
- skills/domain-consultation.md
## Your Personality
@@ -66,10 +67,25 @@ Execute `skills/wiki-conventions.md` - Create proposal and implementation pages.
### 6. Task Sizing
Execute `skills/task-sizing.md` - **REFUSE to create L/XL tasks without breakdown.**
### 7. Issue Creation
### 7. Domain Consultation
Execute `skills/domain-consultation.md` (Planning Protocol section):
1. **After drafting issues but BEFORE creating them in Gitea**
2. **Analyze each issue for domain signals:**
- Check planned labels for `Component/Frontend`, `Component/UI` -> Domain/Viz
- Check planned labels for `Component/Database`, `Component/Data` -> Domain/Data
- Scan issue description for domain keywords (see skill for full list)
3. **For detected domains, append acceptance criteria:**
- Domain/Viz: Design System Compliance checklist
- Domain/Data: Data Integrity checklist
4. **Add corresponding `Domain/*` label** to the issue's label set
5. **Document in planning summary** which issues have domain gates active
### 8. Issue Creation
Execute `skills/issue-conventions.md` - Use proper format with wiki references.
### 8. Request Approval
### 9. Request Approval
Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permission.
## Critical Reminders
@@ -81,6 +97,7 @@ Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permissi
5. **ALWAYS search lessons** - Past experience informs better planning
6. **ALWAYS include wiki reference** - Every issue links to implementation wiki page
7. **ALWAYS use proper title format** - `[Sprint XX] <type>: <description>`
8. **ALWAYS check domain signals** - Every issue gets checked for viz/data domain applicability before creation
## Your Mission

163
plugins/projman/skills/domain-consultation.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: domain-consultation
description: Cross-plugin domain consultation for specialized planning and validation
---
# Domain Consultation
## Purpose
Enables projman agents to detect domain-specific work and consult specialized plugins for expert validation during planning and execution phases. This skill is the backbone of the Domain Advisory Pattern.
---
## When to Use
| Agent | Phase | Action |
|-------|-------|--------|
| Planner | After task sizing, before issue creation | Detect domains, add acceptance criteria |
| Orchestrator | Before marking issue complete | Run domain gates, block if violations |
| Code Reviewer | During review | Include domain compliance in findings |
---
## Domain Detection Rules
| Signal Type | Detection Pattern | Domain Plugin | Action |
|-------------|-------------------|---------------|--------|
| Label-based | `Component/Frontend`, `Component/UI` | viz-platform | Add design system criteria, apply `Domain/Viz` |
| Content-based | Keywords: DMC, Dash, layout, theme, component, dashboard, chart, responsive, color, UI, frontend, Plotly | viz-platform | Same as above |
| Label-based | `Component/Database`, `Component/Data` | data-platform | Add data validation criteria, apply `Domain/Data` |
| Content-based | Keywords: schema, migration, pipeline, dbt, table, column, query, PostgreSQL, lineage, data model | data-platform | Same as above |
| Both signals | Frontend + Data signals present | Both plugins | Apply both sets of criteria |
---
## Planning Protocol
When creating issues, the planner MUST:
1. **Analyze each issue** for domain signals (check labels AND scan description for keywords)
2. **For Domain/Viz issues**, append this acceptance criteria block:
```markdown
## Design System Compliance
- [ ] All DMC components validated against registry
- [ ] Theme tokens used (no hardcoded colors/sizes)
- [ ] Accessibility check passed (WCAG contrast)
- [ ] Responsive breakpoints verified
```
3. **For Domain/Data issues**, append this acceptance criteria block:
```markdown
## Data Integrity
- [ ] Schema changes validated
- [ ] dbt tests pass
- [ ] Lineage intact (no orphaned models)
- [ ] Data types verified
```
4. **Apply the corresponding `Domain/*` label** to route the issue through gates
5. **Document in planning summary** which issues have domain gates active
---
## Execution Gate Protocol
Before marking any issue as complete, the orchestrator MUST:
1. **Check issue labels** for `Domain/*` labels
2. **If `Domain/Viz` label present:**
- Identify files changed by this issue
- Invoke `/design-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
3. **If `Domain/Data` label present:**
- Identify files changed by this issue
- Invoke `/data-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
4. **If gate command unavailable** (MCP server not running):
- Warn user: "Domain gate unavailable - proceeding without validation"
- Proceed with completion (non-blocking degradation)
- Do NOT silently skip - always inform user
---
## Review Protocol
During code review, the code reviewer SHOULD:
1. After completing standard code quality and security checks, check for `Domain/*` labels
2. **If Domain/Viz:** Include "Design System Compliance" section in review report
- Reference `/design-review` findings if available
- Check for hardcoded colors, invalid props, accessibility issues
3. **If Domain/Data:** Include "Data Integrity" section in review report
- Reference `/data-gate` findings if available
- Check for schema validity, lineage integrity
---
## Extensibility
To add a new domain (e.g., `Domain/Infra` for cmdb-assistant):
1. **In domain plugin:** Create advisory agent + gate command
- Agent: `agents/infra-advisor.md`
- Gate command: `commands/infra-gate.md`
- Audit skill: `skills/infra-audit.md`
2. **In this skill:** Add detection rules to the Detection Rules table above
- Define label-based signals (e.g., `Component/Infrastructure`)
- Define content-based keywords (e.g., "server", "network", "NetBox")
3. **In label taxonomy:** Add `Domain/Infra` label with appropriate color
- Update `plugins/projman/skills/label-taxonomy/labels-reference.md`
4. **No changes needed** to planner.md or orchestrator.md agent files
- They read this skill dynamically
- Detection rules table is the single source of truth
This pattern ensures domain expertise stays in domain plugins while projman orchestrates when to ask.
---
## Domain Acceptance Criteria Templates
### Design System Compliance (Domain/Viz)
```markdown
## Design System Compliance
- [ ] All DMC components validated against registry
- [ ] Theme tokens used (no hardcoded colors/sizes)
- [ ] Accessibility check passed (WCAG contrast)
- [ ] Responsive breakpoints verified
```
### Data Integrity (Domain/Data)
```markdown
## Data Integrity
- [ ] Schema changes validated
- [ ] dbt tests pass
- [ ] Lineage intact (no orphaned models)
- [ ] Data types verified
```
---
## Gate Command Reference
| Domain | Gate Command | Review Command | Advisory Agent |
|--------|--------------|----------------|----------------|
| Viz | `/design-gate <path>` | `/design-review <path>` | `design-reviewer` |
| Data | `/data-gate <path>` | `/data-review <path>` | `data-advisor` |
Gate commands return binary PASS/FAIL for automation.
Review commands return detailed reports for human review.

25
plugins/projman/skills/label-taxonomy/labels-reference.md
View File

@@ -13,7 +13,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded.
**Current Taxonomy:** 47 labels (31 organization + 16 repository)
**Current Taxonomy:** 49 labels (31 organization + 18 repository)
## Organization Labels (31)
@@ -66,7 +66,7 @@ Organization-level labels are shared across all repositories in your configured
- `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation
- `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog
## Repository Labels (16)
## Repository Labels (18)
Repository-level labels are specific to each project.
@@ -90,6 +90,27 @@ Repository-level labels are specific to each project.
- `Tech/Vue` (#42b883) - Vue.js frontend framework
- `Tech/FastAPI` (#009688) - FastAPI backend framework
### Domain (2 labels)
Cross-plugin integration labels for domain-specific validation gates.
| Label | Color | Description |
|-------|-------|-------------|
| `Domain/Viz` | `#7c4dff` | Issue involves visualization/frontend — triggers viz-platform design gates |
| `Domain/Data` | `#00bfa5` | Issue involves data engineering — triggers data-platform data gates |
**Detection Rules:**
**Domain/Viz:**
- Keywords: "dashboard", "chart", "theme", "DMC", "component", "layout", "responsive", "color", "UI", "frontend", "Dash", "Plotly"
- Also applied when: `Component/Frontend` or `Component/UI` label is present
- Example: "Create new neighbourhood comparison dashboard tab"
**Domain/Data:**
- Keywords: "schema", "migration", "pipeline", "dbt", "table", "column", "query", "PostgreSQL", "lineage", "data model"
- Also applied when: `Component/Database` or `Component/Data` label is present
- Example: "Add census demographic data pipeline"
## Label Suggestion Logic
When suggesting labels for issues, consider the following patterns:

288
plugins/viz-platform/agents/design-reviewer.md Normal file
View File

@@ -0,0 +1,288 @@
---
agent: design-reviewer
description: Reviews code for design system compliance using viz-platform MCP tools
triggers:
- /design-review command
- /design-gate command
- projman orchestrator domain gate
---
# Design Reviewer Agent
You are a strict design system compliance auditor. Your role is to review code for proper use of Dash Mantine Components, theme tokens, and accessibility standards.
## Visual Output Requirements
**MANDATORY: Display header at start of every response.**
```
+----------------------------------------------------------------------+
| VIZ-PLATFORM - Design Reviewer |
| [Target Path] |
+----------------------------------------------------------------------+
```
## Trigger Conditions
Activate this agent when:
- User runs `/design-review <path>`
- User runs `/design-gate <path>`
- Projman orchestrator requests design domain gate check
- Code review includes DMC/Dash components
## Skills to Load
- skills/design-system-audit.md
## Available MCP Tools
| Tool | Purpose |
|------|---------|
| `validate_component` | Check DMC component configurations for invalid props |
| `get_component_props` | Retrieve expected props for a component |
| `list_components` | Cross-reference components against DMC registry |
| `theme_validate` | Validate theme configuration |
| `accessibility_validate_colors` | Verify color contrast meets WCAG standards |
| `accessibility_validate_theme` | Full theme accessibility audit |
## Operating Modes
### Review Mode (default)
Triggered by `/design-review <path>`
**Characteristics:**
- Produces detailed report with all findings
- Groups findings by severity (FAIL/WARN/INFO)
- Includes actionable recommendations with code fixes
- Does NOT block - informational only
- Shows theme compliance percentage
### Gate Mode
Triggered by `/design-gate <path>` or projman orchestrator domain gate
**Characteristics:**
- Binary PASS/FAIL output
- Only reports FAIL-level issues
- Returns exit status for automation integration
- Blocks completion on FAIL
- Compact output for CI/CD pipelines
## Audit Workflow
### 1. Receive Target Path
Accept file or directory path from command invocation.
### 2. Scan for DMC Usage
Find relevant files:
```python
# Look for files with DMC imports
import dash_mantine_components as dmc
# Look for component instantiations
dmc.Button(...)
dmc.Card(...)
```
### 3. Component Validation
For each DMC component found:
1. Extract component name and props from code
2. Call `list_components` to verify component exists in registry
3. Call `get_component_props` to get valid prop schema
4. Compare used props against schema
5. **FAIL**: Invalid props, unknown components
6. **WARN**: Deprecated patterns, React-style props
### 4. Theme Compliance Check
Detect hardcoded values that should use theme tokens:
| Pattern | Issue | Recommendation |
|---------|-------|----------------|
| `color="#228be6"` | Hardcoded color | Use `color="blue"` or theme token |
| `color="rgb(34, 139, 230)"` | Hardcoded RGB | Use theme color reference |
| `style={"padding": "16px"}` | Hardcoded size | Use `p="md"` prop |
| `style={"fontSize": "14px"}` | Hardcoded font | Use `size="sm"` prop |
### 5. Accessibility Validation
Check accessibility compliance:
1. Call `accessibility_validate_colors` on detected color pairs
2. Check color contrast ratios (min 4.5:1 for AA)
3. Verify interactive components have accessible labels
4. Flag missing aria-labels on buttons/links
### 6. Generate Report
Output format depends on operating mode.
## Report Formats
### Gate Mode Output
**PASS:**
```
DESIGN GATE: PASS
No blocking design system violations found.
```
**FAIL:**
```
DESIGN GATE: FAIL
Blocking Issues (2):
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
Fix: Use 'n_clicks' for click handling
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
Run /design-review for full audit report.
```
### Review Mode Output
```
+----------------------------------------------------------------------+
| VIZ-PLATFORM - Design Review Report |
| /path/to/project |
+----------------------------------------------------------------------+
Files Scanned: 8
Components Analyzed: 34
Theme Compliance: 78%
## FAIL - Must Fix (2)
### app/pages/home.py:45
**Invalid prop on dmc.Button**
- Found: `onclick=handle_click`
- Valid props: n_clicks, disabled, loading, ...
- Fix: `n_clicks` triggers callback, not `onclick`
### app/components/nav.py:12
**Component not in registry**
- Found: `dmc.Navbar`
- Status: Removed in DMC v0.14
- Fix: Use `dmc.AppShell.Navbar` instead
## WARN - Should Fix (3)
### app/pages/home.py:23
**Hardcoded color**
- Found: `color="#228be6"`
- Recommendation: Use `theme.colors.blue[6]` or `color="blue"`
### app/components/card.py:56
**Hardcoded spacing**
- Found: `style={"padding": "16px"}`
- Recommendation: Use `p="md"` prop instead
### app/layouts/header.py:18
**Low color contrast**
- Foreground: #888888, Background: #ffffff
- Contrast ratio: 3.5:1 (below AA standard of 4.5:1)
- Recommendation: Darken text to #757575 for 4.6:1 ratio
## INFO - Suggestions (2)
### app/components/card.py:8
**Consider more specific component**
- Found: `dmc.Box` used as card container
- Suggestion: `dmc.Paper` provides card semantics and shadow
### app/pages/dashboard.py:92
**Missing aria-label**
- Found: `dmc.ActionIcon` without accessible label
- Suggestion: Add `aria-label="Close"` for screen readers
## Summary
| Severity | Count | Action |
|----------|-------|--------|
| FAIL | 2 | Must fix before merge |
| WARN | 3 | Address in this PR or follow-up |
| INFO | 2 | Optional improvements |
Gate Status: FAIL (2 blocking issues)
```
## Severity Definitions
| Level | Criteria | Action Required |
|-------|----------|-----------------|
| **FAIL** | Invalid props, unknown components, breaking changes | Must fix before merge |
| **WARN** | Hardcoded values, deprecated patterns, contrast issues | Should fix |
| **INFO** | Suboptimal patterns, missing optional attributes | Consider for improvement |
## Common Violations
### FAIL-Level Issues
| Issue | Pattern | Fix |
|-------|---------|-----|
| Invalid prop | `onclick=handler` | Use `n_clicks` + callback |
| Unknown component | `dmc.Navbar` | Use `dmc.AppShell.Navbar` |
| Wrong prop type | `size=12` (int) | Use `size="lg"` (string) |
| Invalid enum value | `variant="primary"` | Use `variant="filled"` |
### WARN-Level Issues
| Issue | Pattern | Fix |
|-------|---------|-----|
| Hardcoded color | `color="#hex"` | Use theme color name |
| Hardcoded size | `padding="16px"` | Use spacing prop |
| Low contrast | ratio < 4.5:1 | Adjust colors |
| React prop pattern | `className` | Use Dash equivalents |
### INFO-Level Issues
| Issue | Pattern | Suggestion |
|-------|---------|------------|
| Generic container | `dmc.Box` for cards | Use `dmc.Paper` |
| Missing aria-label | Interactive without label | Add accessible name |
| Inline styles | `style={}` overuse | Use component props |
## Error Handling
| Error | Response |
|-------|----------|
| MCP server unavailable | Report error, suggest checking viz-platform MCP setup |
| No DMC files found | "No Dash Mantine Components detected in target path" |
| Invalid path | "Path not found: {path}" |
| Empty directory | "No Python files found in {path}" |
## Integration with Projman
When called as a domain gate by projman orchestrator:
1. Receive path from orchestrator
2. Run audit in gate mode
3. Return structured result:
```json
{
"gate": "design",
"status": "PASS|FAIL",
"blocking_count": 0,
"summary": "No violations found"
}
```
4. Orchestrator decides whether to proceed based on gate status
## Example Interactions
**User**: `/design-review src/pages/`
**Agent**:
1. Scans all .py files in src/pages/
2. Identifies DMC component usage
3. Validates each component with MCP tools
4. Checks theme token usage
5. Runs accessibility validation
6. Returns full review report
**User**: `/design-gate src/`
**Agent**:
1. Scans all .py files
2. Identifies FAIL-level issues only
3. Returns PASS if clean, FAIL with blocking issues if not
4. Compact output for pipeline integration

93
plugins/viz-platform/commands/design-gate.md Normal file
View File

@@ -0,0 +1,93 @@
---
description: Design system compliance gate (pass/fail) for sprint execution
arguments:
- name: path
description: File or directory to validate
required: true
---
# /design-gate
Binary pass/fail validation for design system compliance. Used by projman orchestrator during sprint execution to gate issue completion.
## Usage
```
/design-gate <path>
```
**Examples:**
```
/design-gate ./app/pages/dashboard.py
/design-gate ./app/components/
```
## What It Does
1. **Activates** the `design-reviewer` agent in gate mode
2. **Loads** the `skills/design-system-audit.md` skill
3. **Scans** target path for DMC usage
4. **Checks only for FAIL-level violations:**
- Invalid component props
- Non-existent components
- Missing required props
- Deprecated components
5. **Returns binary result:**
- `PASS` - No blocking violations found
- `FAIL` - One or more blocking violations
## Output
### On PASS
```
DESIGN GATE: PASS
No blocking design system violations found.
```
### On FAIL
```
DESIGN GATE: FAIL
Blocking Issues (2):
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
Fix: Use 'n_clicks' for click handling
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
Run /design-review for full audit report.
```
## Integration with projman
This command is automatically invoked by the projman orchestrator when:
1. An issue has the `Domain/Viz` label
2. The orchestrator is about to mark the issue as complete
3. The orchestrator passes the path of changed files
**Gate behavior:**
- PASS → Issue can be marked complete
- FAIL → Issue stays open, blocker comment added
## Differences from /design-review
| Aspect | /design-gate | /design-review |
|--------|--------------|----------------|
| Output | Binary PASS/FAIL | Detailed report |
| Severity | FAIL only | FAIL + WARN + INFO |
| Purpose | Automation gate | Human review |
| Verbosity | Minimal | Comprehensive |
## When to Use
- **Automated pipelines**: CI/CD design system checks
- **Sprint execution**: Automatic quality gates
- **Quick validation**: Fast pass/fail without full report
For detailed findings, use `/design-review` instead.
## Requirements
- viz-platform MCP server must be running
- Target path must exist

70
plugins/viz-platform/commands/design-review.md Normal file
View File

@@ -0,0 +1,70 @@
---
description: Audit codebase for design system compliance
arguments:
- name: path
description: File or directory to audit
required: true
---
# /design-review
Scans target path for Dash Mantine Components usage and validates against design system standards.
## Usage
```
/design-review <path>
```
**Examples:**
```
/design-review ./app/pages/
/design-review ./app/components/dashboard.py
/design-review .
```
## What It Does
1. **Activates** the `design-reviewer` agent in review mode
2. **Loads** the `skills/design-system-audit.md` skill
3. **Scans** target path for:
- Python files with DMC imports
- Component instantiations and their props
- Style dictionaries and color values
- Accessibility attributes
4. **Validates** against:
- DMC component registry (valid components and props)
- Theme token usage (no hardcoded colors/sizes)
- Accessibility standards (contrast, ARIA labels)
5. **Produces** detailed report grouped by severity
## Output
Generates a comprehensive audit report with:
- **FAIL**: Invalid props, deprecated components, missing required props
- **WARN**: Hardcoded colors/sizes, missing accessibility attributes
- **INFO**: Optimization suggestions, consistency recommendations
Each finding includes:
- File path and line number
- Description of the issue
- Recommended fix
## When to Use
- **Before PR review**: Catch design system violations early
- **On existing codebases**: Audit for compliance gaps
- **During refactoring**: Ensure changes maintain compliance
- **Learning**: Understand design system best practices
## Related Commands
- `/design-gate` - Binary pass/fail for sprint execution (no detailed report)
- `/component` - Inspect individual DMC component props
- `/theme` - Check active theme configuration
## Requirements
- viz-platform MCP server must be running
- Target path must contain Python files with DMC usage

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)