From 5152cda1610ae23fe5ae5602bf7b240abf331eb1 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Fri, 30 Jan 2026 16:59:26 -0500 Subject: [PATCH] refactor(viz-platform): extract skills and slim commands Extract shared knowledge from 10 commands into 7 reusable skills: - mcp-tools-reference.md: All viz-platform MCP tool signatures - theming-system.md: Theme tokens, CSS variables, color palettes - accessibility-rules.md: WCAG contrast, color-blind safe palettes - dmc-components.md: DMC categories, validation, common props - responsive-design.md: Breakpoints, mobile-first, grid config - chart-types.md: Plotly chart types, export formats, resolution - layout-templates.md: Dashboard templates, filter types All commands now reference skills via "Skills to Load" section. Commands reduced from 1396 lines total to 427 lines (69% reduction). Co-Authored-By: Claude Opus 4.5 --- .../commands/accessibility-check.md | 135 ++----------- plugins/viz-platform/commands/breakpoints.md | 180 +----------------- plugins/viz-platform/commands/chart-export.md | 106 ++--------- plugins/viz-platform/commands/chart.md | 83 ++------ plugins/viz-platform/commands/component.md | 151 +-------------- plugins/viz-platform/commands/dashboard.md | 118 ++---------- .../viz-platform/commands/initial-setup.md | 163 ++-------------- plugins/viz-platform/commands/theme-css.md | 99 +--------- plugins/viz-platform/commands/theme-new.md | 106 +---------- plugins/viz-platform/commands/theme.md | 54 +----- .../skills/accessibility-rules.md | 64 +++++++ plugins/viz-platform/skills/chart-types.md | 59 ++++++ plugins/viz-platform/skills/dmc-components.md | 97 ++++++++++ .../viz-platform/skills/layout-templates.md | 70 +++++++ .../skills/mcp-tools-reference.md | 159 ++++++++++++++++ .../viz-platform/skills/responsive-design.md | 104 ++++++++++ plugins/viz-platform/skills/theming-system.md | 104 ++++++++++ 17 files changed, 770 insertions(+), 1082 deletions(-) create mode 100644 plugins/viz-platform/skills/accessibility-rules.md create mode 100644 plugins/viz-platform/skills/chart-types.md create mode 100644 plugins/viz-platform/skills/dmc-components.md create mode 100644 plugins/viz-platform/skills/layout-templates.md create mode 100644 plugins/viz-platform/skills/mcp-tools-reference.md create mode 100644 plugins/viz-platform/skills/responsive-design.md create mode 100644 plugins/viz-platform/skills/theming-system.md diff --git a/plugins/viz-platform/commands/accessibility-check.md b/plugins/viz-platform/commands/accessibility-check.md index e1cd65f..86e116e 100644 --- a/plugins/viz-platform/commands/accessibility-check.md +++ b/plugins/viz-platform/commands/accessibility-check.md @@ -4,19 +4,19 @@ description: Validate color accessibility for color blind users # Accessibility Check +## Skills to Load +- skills/mcp-tools-reference.md +- skills/accessibility-rules.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Accessibility Check │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Accessibility Check | ++------------------------------------------------------------------+ ``` -Then proceed with the accessibility validation. - -Validate theme or chart colors for color blind accessibility, checking contrast ratios and suggesting alternatives. +Validate theme or chart colors for color blind accessibility. ## Usage @@ -28,129 +28,18 @@ Validate theme or chart colors for color blind accessibility, checking contrast - `target` (optional): "theme" or "chart" - defaults to active theme -## Examples - -``` -/accessibility-check -/accessibility-check theme -/accessibility-check chart -``` - ## Tool Mapping -This command uses the `accessibility_validate_colors` MCP tool: - ```python accessibility_validate_colors( - colors=["#228be6", "#40c057", "#fa5252"], # Colors to check + colors=["#228be6", "#40c057"], check_types=["deuteranopia", "protanopia", "tritanopia"], - min_contrast_ratio=4.5 # WCAG AA standard + min_contrast_ratio=4.5 ) -``` - -Or validate a full theme: -```python -accessibility_validate_theme( - theme_name="corporate" -) -``` - -## Workflow - -1. **User invokes**: `/accessibility-check theme` -2. **Tool analyzes**: Theme color palette -3. **Tool simulates**: Color perception for each deficiency type -4. **Tool checks**: Contrast ratios between color pairs -5. **Tool returns**: Issues found and alternative suggestions - -## Color Blindness Types - -| Type | Affected Colors | Population | -|------|-----------------|------------| -| **Deuteranopia** | Red-Green (green-blind) | ~6% males, 0.4% females | -| **Protanopia** | Red-Green (red-blind) | ~2.5% males, 0.05% females | -| **Tritanopia** | Blue-Yellow | ~0.01% total | - -## Output Example - -```json -{ - "theme_name": "corporate", - "overall_score": "B", - "issues": [ - { - "type": "contrast", - "severity": "warning", - "colors": ["#fa5252", "#40c057"], - "affected_by": ["deuteranopia", "protanopia"], - "message": "Red and green may be indistinguishable for red-green color blind users", - "suggestion": "Use blue (#228be6) instead of green to differentiate from red" - }, - { - "type": "contrast_ratio", - "severity": "error", - "colors": ["#fab005", "#ffffff"], - "ratio": 2.1, - "required": 4.5, - "message": "Insufficient contrast for WCAG AA compliance", - "suggestion": "Darken yellow to #e6a200 for ratio of 4.5+" - } - ], - "recommendations": [ - "Add patterns or shapes to distinguish data series, not just color", - "Include labels directly on chart elements", - "Consider using a color-blind safe palette" - ], - "safe_palettes": { - "categorical": ["#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377", "#BBBBBB"], - "sequential": ["#FEE0D2", "#FC9272", "#DE2D26"], - "diverging": ["#4575B4", "#FFFFBF", "#D73027"] - } -} -``` - -## WCAG Contrast Standards - -| Level | Ratio | Use Case | -|-------|-------|----------| -| AA (normal text) | 4.5:1 | Body text, labels | -| AA (large text) | 3:1 | Headings, 14pt+ bold | -| AAA (enhanced) | 7:1 | Highest accessibility | - -## Color-Blind Safe Palettes - -The tool can suggest complete color-blind safe palettes: - -### IBM Design Colors -Designed for accessibility: -``` -#648FFF #785EF0 #DC267F #FE6100 #FFB000 -``` - -### Tableau Colorblind 10 -Industry-standard accessible palette: -``` -#006BA4 #FF800E #ABABAB #595959 #5F9ED1 -#C85200 #898989 #A2C8EC #FFBC79 #CFCFCF -``` - -### Okabe-Ito -Optimized for all types of color blindness: -``` -#E69F00 #56B4E9 #009E73 #F0E442 #0072B2 -#D55E00 #CC79A7 #000000 +accessibility_validate_theme(theme_name="corporate") ``` ## Related Commands -- `/theme-new {name}` - Create accessible theme from the start -- `/theme-validate {name}` - General theme validation +- `/theme-new {name}` - Create accessible theme - `/chart {type}` - Create chart (check colors after) - -## Best Practices - -1. **Don't rely on color alone** - Use shapes, patterns, or labels -2. **Test with simulation** - View your visualizations through color blindness simulators -3. **Use sufficient contrast** - Minimum 4.5:1 for text, 3:1 for large elements -4. **Limit color count** - Fewer colors = easier to distinguish -5. **Use semantic colors** - Blue for information, red for errors (with icons) diff --git a/plugins/viz-platform/commands/breakpoints.md b/plugins/viz-platform/commands/breakpoints.md index 02d9a9f..62e0166 100644 --- a/plugins/viz-platform/commands/breakpoints.md +++ b/plugins/viz-platform/commands/breakpoints.md @@ -4,19 +4,19 @@ description: Configure responsive breakpoints for dashboard layouts # Configure Breakpoints +## Skills to Load +- skills/mcp-tools-reference.md +- skills/responsive-design.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Breakpoints │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Breakpoints | ++------------------------------------------------------------------+ ``` -Then proceed with the configuration. - -Configure responsive breakpoints for a layout to support mobile-first design across different screen sizes. +Configure responsive breakpoints for mobile-first design across screen sizes. ## Usage @@ -28,178 +28,16 @@ Configure responsive breakpoints for a layout to support mobile-first design acr - `layout_ref` (required): Layout name to configure breakpoints for -## Examples - -``` -/breakpoints my-dashboard -/breakpoints sales-report -``` - -## Tool Mapping - -This command uses the `layout_set_breakpoints` MCP tool: - -```python -layout_set_breakpoints( - layout_ref="my-dashboard", - breakpoints={ - "xs": {"cols": 1, "spacing": "xs"}, # < 576px (mobile) - "sm": {"cols": 2, "spacing": "sm"}, # >= 576px (large mobile) - "md": {"cols": 6, "spacing": "md"}, # >= 768px (tablet) - "lg": {"cols": 12, "spacing": "md"}, # >= 992px (desktop) - "xl": {"cols": 12, "spacing": "lg"} # >= 1200px (large desktop) - }, - mobile_first=True -) -``` - ## Workflow 1. **User invokes**: `/breakpoints my-dashboard` 2. **Agent asks**: Which breakpoints to customize? (shows current settings) 3. **Agent asks**: Mobile column count? (xs, typically 1-2) 4. **Agent asks**: Tablet column count? (md, typically 4-6) -5. **Agent applies**: Breakpoint configuration +5. **Agent applies**: Breakpoint configuration via `layout_set_breakpoints` 6. **Agent returns**: Complete responsive configuration -## Breakpoint Sizes - -| Name | Min Width | Common Devices | -|------|-----------|----------------| -| `xs` | 0px | Small phones (portrait) | -| `sm` | 576px | Large phones, small tablets | -| `md` | 768px | Tablets (portrait) | -| `lg` | 992px | Tablets (landscape), laptops | -| `xl` | 1200px | Desktops, large screens | - -## Mobile-First Approach - -When `mobile_first=True` (default), styles cascade up: -- Define base styles for `xs` (mobile) -- Override only what changes at larger breakpoints -- Smaller CSS footprint, better performance - -```python -# Mobile-first example -{ - "xs": {"cols": 1}, # Stack everything on mobile - "md": {"cols": 6}, # Two-column on tablet - "lg": {"cols": 12} # Full grid on desktop -} -``` - -When `mobile_first=False`, styles cascade down: -- Define base styles for `xl` (desktop) -- Override for smaller screens -- Traditional "desktop-first" approach - -## Grid Configuration per Breakpoint - -Each breakpoint can configure: - -| Property | Description | Values | -|----------|-------------|--------| -| `cols` | Grid column count | 1-24 | -| `spacing` | Gap between items | xs, sm, md, lg, xl | -| `gutter` | Outer padding | xs, sm, md, lg, xl | -| `grow` | Items grow to fill | true, false | - -## Common Patterns - -### Dashboard (Charts & Filters) -```python -{ - "xs": {"cols": 1, "spacing": "xs"}, # Full-width cards - "sm": {"cols": 2, "spacing": "sm"}, # 2 cards per row - "md": {"cols": 3, "spacing": "md"}, # 3 cards per row - "lg": {"cols": 4, "spacing": "md"}, # 4 cards per row - "xl": {"cols": 6, "spacing": "lg"} # 6 cards per row -} -``` - -### Data Table -```python -{ - "xs": {"cols": 1, "scroll": true}, # Horizontal scroll - "md": {"cols": 1, "scroll": false}, # Full table visible - "lg": {"cols": 1} # Same as md -} -``` - -### Form Layout -```python -{ - "xs": {"cols": 1}, # Single column - "md": {"cols": 2}, # Two columns - "lg": {"cols": 3} # Three columns -} -``` - -### Sidebar Layout -```python -{ - "xs": {"sidebar": "hidden"}, # No sidebar on mobile - "md": {"sidebar": "collapsed"}, # Icon-only sidebar - "lg": {"sidebar": "expanded"} # Full sidebar -} -``` - -## Component Span - -Control how many columns a component spans at each breakpoint: - -```python -# A chart that spans full width on mobile, half on desktop -{ - "component": "sales-chart", - "span": { - "xs": 1, # Full width (1/1) - "md": 3, # Half width (3/6) - "lg": 6 # Half width (6/12) - } -} -``` - -## DMC Grid Integration - -This maps to Dash Mantine Components Grid: - -```python -dmc.Grid( - children=[ - dmc.GridCol( - children=[chart], - span={"base": 12, "sm": 6, "lg": 4} # Responsive span - ) - ], - gutter="md" -) -``` - -## Output - -```json -{ - "layout_ref": "my-dashboard", - "breakpoints": { - "xs": {"cols": 1, "spacing": "xs", "min_width": "0px"}, - "sm": {"cols": 2, "spacing": "sm", "min_width": "576px"}, - "md": {"cols": 6, "spacing": "md", "min_width": "768px"}, - "lg": {"cols": 12, "spacing": "md", "min_width": "992px"}, - "xl": {"cols": 12, "spacing": "lg", "min_width": "1200px"} - }, - "mobile_first": true, - "css_media_queries": [ - "@media (min-width: 576px) { ... }", - "@media (min-width: 768px) { ... }", - "@media (min-width: 992px) { ... }", - "@media (min-width: 1200px) { ... }" - ] -} -``` - ## Related Commands - `/dashboard {template}` - Create layout with default breakpoints -- `/layout-set-grid` - Configure grid without responsive settings - `/theme {name}` - Theme includes default spacing values diff --git a/plugins/viz-platform/commands/chart-export.md b/plugins/viz-platform/commands/chart-export.md index d2eab1a..0f25060 100644 --- a/plugins/viz-platform/commands/chart-export.md +++ b/plugins/viz-platform/commands/chart-export.md @@ -4,19 +4,19 @@ description: Export a Plotly chart to PNG, SVG, or PDF format # Export Chart +## Skills to Load +- skills/mcp-tools-reference.md +- skills/chart-types.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Chart Export │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Chart Export | ++------------------------------------------------------------------+ ``` -Then proceed with the export. - -Export a Plotly chart to static image formats for sharing, embedding, or printing. +Export a Plotly chart to static image formats. ## Usage @@ -26,101 +26,17 @@ Export a Plotly chart to static image formats for sharing, embedding, or printin ## Arguments -- `format` (required): Output format - one of: png, svg, pdf - -## Examples - -``` -/chart-export png -/chart-export svg -/chart-export pdf -``` +- `format` (required): png, svg, or pdf ## Tool Mapping -This command uses the `chart_export` MCP tool: - ```python -chart_export( - figure=figure_json, # Plotly figure JSON from chart_create - format="png", # Output format: png, svg, pdf - width=1200, # Optional: image width in pixels - height=800, # Optional: image height in pixels - scale=2, # Optional: resolution scale factor - output_path=None # Optional: save to file path -) +chart_export(figure=figure_json, format="png", width=1200, height=800, scale=2) ``` -## Workflow - -1. **User invokes**: `/chart-export png` -2. **Agent asks**: Which chart to export? (if multiple charts in context) -3. **Agent asks**: Image dimensions? (optional, uses chart defaults) -4. **Agent exports**: Chart with `chart_export` tool -5. **Agent returns**: Base64 image data or file path - -## Output Formats - -| Format | Best For | File Size | -|--------|----------|-----------| -| `png` | Web, presentations, general use | Medium | -| `svg` | Scalable graphics, editing | Small | -| `pdf` | Print, documents, archival | Large | - -## Resolution Options - -### Width & Height -Specify exact pixel dimensions: -```python -chart_export(figure, format="png", width=1920, height=1080) -``` - -### Scale Factor -Increase resolution for high-DPI displays: -```python -chart_export(figure, format="png", scale=3) # 3x resolution -``` - -Common scale values: -- `1` - Standard resolution (72 DPI) -- `2` - Retina/HiDPI (144 DPI) -- `3` - Print quality (216 DPI) -- `4` - High-quality print (288 DPI) - -## Output Options - -### Return as Base64 -Default behavior - returns base64-encoded image data: -```python -result = chart_export(figure, format="png") -# result["image_data"] contains base64 string -``` - -### Save to File -Specify output path to save directly: -```python -chart_export(figure, format="png", output_path="/path/to/chart.png") -# result["file_path"] contains the saved path -``` - -## Requirements - -This tool requires the `kaleido` package for rendering: -```bash -pip install kaleido -``` - -Kaleido is a cross-platform library that renders Plotly figures without a browser. - -## Error Handling - -Common issues: -- **Kaleido not installed**: Install with `pip install kaleido` -- **Invalid figure**: Ensure figure is valid Plotly JSON -- **Permission denied**: Check write permissions for output path +Requires `kaleido` package: `pip install kaleido` ## Related Commands - `/chart {type}` - Create a chart - `/theme {name}` - Apply theme before export -- `/dashboard` - Create layout containing charts diff --git a/plugins/viz-platform/commands/chart.md b/plugins/viz-platform/commands/chart.md index 5f98443..47ecbf3 100644 --- a/plugins/viz-platform/commands/chart.md +++ b/plugins/viz-platform/commands/chart.md @@ -4,18 +4,18 @@ description: Create a Plotly chart with theme integration # Create Chart +## Skills to Load +- skills/mcp-tools-reference.md +- skills/chart-types.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Chart Builder │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Chart Builder | ++------------------------------------------------------------------+ ``` -Then proceed with the chart creation. - Create a Plotly chart with automatic theme token application. ## Usage @@ -26,73 +26,16 @@ Create a Plotly chart with automatic theme token application. ## Arguments -- `type` (required): Chart type - one of: line, bar, scatter, pie, area, histogram, box, heatmap, sunburst, treemap - -## Examples - -``` -/chart line -/chart bar -/chart scatter -/chart pie -``` +- `type` (required): line, bar, scatter, pie, area, histogram, box, heatmap, sunburst, treemap ## Tool Mapping -This command uses the `chart_create` MCP tool: - ```python -chart_create( - chart_type="line", - data_ref="df_sales", # Reference to loaded DataFrame - x="date", # X-axis column - y="revenue", # Y-axis column - color=None, # Optional: column for color grouping - title="Sales Over Time", # Optional: chart title - theme=None # Optional: theme name to apply -) +chart_create(chart_type="line", data_ref="df", x="date", y="value", theme=None) ``` -## Workflow +## Related Commands -1. **User invokes**: `/chart line` -2. **Agent asks**: Which DataFrame to use? (list available with `list_data` from data-platform) -3. **Agent asks**: Which columns for X and Y axes? -4. **Agent asks**: Any grouping/color column? -5. **Agent creates**: Chart with `chart_create` tool -6. **Agent returns**: Plotly figure JSON ready for rendering - -## Chart Types - -| Type | Best For | -|------|----------| -| `line` | Time series, trends | -| `bar` | Comparisons, categories | -| `scatter` | Correlations, distributions | -| `pie` | Part-to-whole relationships | -| `area` | Cumulative trends | -| `histogram` | Frequency distributions | -| `box` | Statistical distributions | -| `heatmap` | Matrix correlations | -| `sunburst` | Hierarchical data | -| `treemap` | Hierarchical proportions | - -## Theme Integration - -Charts automatically inherit colors from the active theme: -- Primary color for main data -- Color palette for multi-series -- Font family and sizes -- Background colors - -Override with explicit theme: -```python -chart_create(chart_type="bar", ..., theme="my-dark-theme") -``` - -## Output - -Returns Plotly figure JSON that can be: -- Rendered in a Dash app -- Saved as HTML/PNG -- Embedded in a layout component +- `/chart-export {format}` - Export chart to image +- `/theme {name}` - Apply theme to charts +- `/dashboard` - Create layout with charts diff --git a/plugins/viz-platform/commands/component.md b/plugins/viz-platform/commands/component.md index 66ef550..6386706 100644 --- a/plugins/viz-platform/commands/component.md +++ b/plugins/viz-platform/commands/component.md @@ -4,19 +4,19 @@ description: Inspect Dash Mantine Component props and validation # Inspect Component +## Skills to Load +- skills/mcp-tools-reference.md +- skills/dmc-components.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Component Inspector │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Component Inspector | ++------------------------------------------------------------------+ ``` -Then proceed with the inspection. - -Inspect a Dash Mantine Component's available props, types, and defaults. +Inspect a DMC component's props, types, and defaults. ## Usage @@ -28,145 +28,14 @@ Inspect a Dash Mantine Component's available props, types, and defaults. - `name` (required): DMC component name (e.g., Button, Card, TextInput) -## Examples - -``` -/component Button -/component TextInput -/component Select -/component Card -``` - ## Tool Mapping -This command uses the `get_component_props` MCP tool: - ```python get_component_props(component="Button") +list_components(category="inputs") +validate_component(component="Button", props={"variant": "filled"}) ``` -## Output Example - -```json -{ - "component": "Button", - "category": "inputs", - "props": { - "children": { - "type": "any", - "required": false, - "description": "Button content" - }, - "variant": { - "type": "string", - "enum": ["filled", "outline", "light", "subtle", "default", "gradient"], - "default": "filled", - "description": "Button appearance variant" - }, - "color": { - "type": "string", - "default": "blue", - "description": "Button color from theme" - }, - "size": { - "type": "string", - "enum": ["xs", "sm", "md", "lg", "xl"], - "default": "sm", - "description": "Button size" - }, - "radius": { - "type": "string", - "enum": ["xs", "sm", "md", "lg", "xl"], - "default": "sm", - "description": "Border radius" - }, - "disabled": { - "type": "boolean", - "default": false, - "description": "Disable button" - }, - "loading": { - "type": "boolean", - "default": false, - "description": "Show loading indicator" - }, - "fullWidth": { - "type": "boolean", - "default": false, - "description": "Button takes full width" - } - } -} -``` - -## Listing All Components - -To see all available components: - -```python -list_components(category=None) # All components -list_components(category="inputs") # Just input components -``` - -### Component Categories - -| Category | Components | -|----------|------------| -| `inputs` | Button, TextInput, Select, Checkbox, Radio, Switch, Slider, etc. | -| `navigation` | NavLink, Tabs, Breadcrumbs, Pagination, Stepper | -| `feedback` | Alert, Notification, Progress, Loader, Skeleton | -| `overlays` | Modal, Drawer, Tooltip, Popover, Menu | -| `typography` | Text, Title, Code, Blockquote, List | -| `layout` | Container, Grid, Stack, Group, Space, Divider | -| `data` | Table, Badge, Card, Paper, Timeline | - -## Validating Component Usage - -After inspecting props, validate your usage: - -```python -validate_component( - component="Button", - props={ - "variant": "filled", - "color": "blue", - "size": "lg", - "children": "Click me" - } -) -``` - -Returns: -```json -{ - "valid": true, - "errors": [], - "warnings": [] -} -``` - -Or with errors: -```json -{ - "valid": false, - "errors": [ - "Invalid prop 'colour' for Button. Did you mean 'color'?", - "Prop 'size' expects one of ['xs', 'sm', 'md', 'lg', 'xl'], got 'huge'" - ], - "warnings": [ - "Prop 'fullwidth' should be 'fullWidth' (camelCase)" - ] -} -``` - -## Why This Matters - -DMC components have many props with specific type constraints. This tool: -- Prevents hallucinated prop names -- Validates enum values -- Catches typos before runtime -- Documents available options - ## Related Commands - `/chart {type}` - Create charts diff --git a/plugins/viz-platform/commands/dashboard.md b/plugins/viz-platform/commands/dashboard.md index 531d227..08bef6e 100644 --- a/plugins/viz-platform/commands/dashboard.md +++ b/plugins/viz-platform/commands/dashboard.md @@ -4,19 +4,19 @@ description: Create a dashboard layout with the layout-builder agent # Create Dashboard +## Skills to Load +- skills/mcp-tools-reference.md +- skills/layout-templates.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Dashboard Builder │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Dashboard Builder | ++------------------------------------------------------------------+ ``` -Then proceed with the dashboard creation. - -Create a dashboard layout structure with filters, grids, and sections. +Create a dashboard layout with filters, grids, and sections. ## Usage @@ -26,102 +26,16 @@ Create a dashboard layout structure with filters, grids, and sections. ## Arguments -- `template` (optional): Layout template - one of: basic, sidebar, tabs, split - -## Examples - -``` -/dashboard # Interactive layout builder -/dashboard basic # Simple single-column layout -/dashboard sidebar # Layout with sidebar navigation -/dashboard tabs # Tabbed multi-page layout -/dashboard split # Split-pane layout -``` +- `template` (optional): basic, sidebar, tabs, split ## Agent Mapping -This command activates the **layout-builder** agent which orchestrates multiple tools: +Activates **layout-builder** agent which orchestrates: +- `layout_create` - Create base layout structure +- `layout_add_filter` - Add filter components +- `layout_set_grid` - Configure responsive grid -1. `layout_create` - Create the base layout structure -2. `layout_add_filter` - Add filter components (dropdowns, date pickers) -3. `layout_set_grid` - Configure responsive grid settings -4. `layout_add_section` - Add content sections +## Related Commands -## Workflow - -1. **User invokes**: `/dashboard sidebar` -2. **Agent asks**: What is the dashboard purpose? -3. **Agent asks**: What filters are needed? -4. **Agent creates**: Base layout with `layout_create` -5. **Agent adds**: Filters with `layout_add_filter` -6. **Agent configures**: Grid with `layout_set_grid` -7. **Agent returns**: Complete layout structure - -## Templates - -### Basic -Single-column layout with header and content area. -``` -┌─────────────────────────────┐ -│ Header │ -├─────────────────────────────┤ -│ │ -│ Content │ -│ │ -└─────────────────────────────┘ -``` - -### Sidebar -Layout with collapsible sidebar navigation. -``` -┌────────┬────────────────────┐ -│ │ Header │ -│ Nav ├────────────────────┤ -│ │ │ -│ │ Content │ -│ │ │ -└────────┴────────────────────┘ -``` - -### Tabs -Tabbed layout for multi-page dashboards. -``` -┌─────────────────────────────┐ -│ Header │ -├──────┬──────┬──────┬────────┤ -│ Tab1 │ Tab2 │ Tab3 │ │ -├──────┴──────┴──────┴────────┤ -│ │ -│ Tab Content │ -│ │ -└─────────────────────────────┘ -``` - -### Split -Split-pane layout for comparisons. -``` -┌─────────────────────────────┐ -│ Header │ -├──────────────┬──────────────┤ -│ │ │ -│ Left │ Right │ -│ Pane │ Pane │ -│ │ │ -└──────────────┴──────────────┘ -``` - -## Filter Types - -Available filter components: -- `dropdown` - Single/multi-select dropdown -- `date_range` - Date range picker -- `slider` - Numeric range slider -- `checkbox` - Checkbox group -- `search` - Text search input - -## Output - -Returns a layout structure that can be: -- Used with page tools to create full app -- Rendered as a Dash layout -- Combined with chart components +- `/breakpoints {layout}` - Configure responsive breakpoints +- `/chart {type}` - Add charts to layout diff --git a/plugins/viz-platform/commands/initial-setup.md b/plugins/viz-platform/commands/initial-setup.md index ce8680b..077b01c 100644 --- a/plugins/viz-platform/commands/initial-setup.md +++ b/plugins/viz-platform/commands/initial-setup.md @@ -1,178 +1,45 @@ --- -description: Interactive setup wizard for viz-platform plugin - configures MCP server and theme preferences +description: Interactive setup wizard for viz-platform plugin --- # Viz-Platform Setup Wizard ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Setup Wizard │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Setup Wizard | ++------------------------------------------------------------------+ ``` -Then proceed with the setup. +Sets up viz-platform with DMC validation and theming. -This command sets up the viz-platform plugin with Dash Mantine Components validation and theming. - -## Important Context - -- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools -- **MCP tools won't work until after setup + session restart** -- **DMC version detection is automatic** based on installed package - ---- +**Note:** Uses Bash/Read/Write tools - NOT MCP tools. Restart session after setup. ## Phase 1: Environment Validation -### Step 1.1: Check Python Version - +Check Python 3.10+ and DMC installation: ```bash python3 --version +python3 -c "import dash_mantine_components as dmc; print(dmc.__version__)" ``` -Requires Python 3.10+. If below, stop setup and inform user. - -### Step 1.2: Check DMC Installation - -```bash -python3 -c "import dash_mantine_components as dmc; print(f'DMC {dmc.__version__}')" 2>/dev/null || echo "DMC_NOT_INSTALLED" -``` - -If DMC is not installed, inform user: -``` -Dash Mantine Components is not installed. Install it with: - pip install dash-mantine-components>=0.14.0 -``` - ---- - ## Phase 2: MCP Server Setup -### Step 2.1: Locate Viz-Platform MCP Server - +Locate and create venv if missing: ```bash -# If running from installed marketplace -ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/viz-platform/ 2>/dev/null || echo "NOT_FOUND_INSTALLED" - -# If running from source -ls -la ~/claude-plugins-work/mcp-servers/viz-platform/ 2>/dev/null || echo "NOT_FOUND_SOURCE" +cd /path/to/mcp-servers/viz-platform && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt ``` -### Step 2.2: Check Virtual Environment - -```bash -ls -la /path/to/mcp-servers/viz-platform/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING" -``` - -### Step 2.3: Create Virtual Environment (if missing) - -```bash -cd /path/to/mcp-servers/viz-platform && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate -``` - ---- - ## Phase 3: Theme Preferences (Optional) -### Step 3.1: Ask About Theme Setup - -Use AskUserQuestion: -- Question: "Do you want to configure a default theme for your projects?" -- Header: "Theme" -- Options: - - "Yes, set up a custom theme" - - "No, use Mantine defaults" - -**If user chooses "No":** Skip to Phase 4. - -### Step 3.2: Choose Base Theme - -Use AskUserQuestion: -- Question: "Which base color scheme do you prefer?" -- Header: "Colors" -- Options: - - "Light mode (default)" - - "Dark mode" - - "System preference (auto)" - -### Step 3.3: Choose Primary Color - -Use AskUserQuestion: -- Question: "What primary color should be used for buttons and accents?" -- Header: "Primary" -- Options: - - "Blue (default)" - - "Indigo" - - "Violet" - - "Other (I'll specify)" - -### Step 3.4: Create System Theme Config - -```bash -mkdir -p ~/.config/claude -cat > ~/.config/claude/viz-platform.env << 'EOF' -# Viz-Platform Configuration -# Generated by viz-platform /initial-setup - -VIZ_PLATFORM_COLOR_SCHEME= -VIZ_PLATFORM_PRIMARY_COLOR= -EOF -chmod 600 ~/.config/claude/viz-platform.env -``` - ---- +Ask user about color scheme and primary color. Save to `~/.config/claude/viz-platform.env`. ## Phase 4: Validation -### Step 4.1: Verify MCP Server +Verify MCP server loads, display summary, prompt session restart. -```bash -cd /path/to/mcp-servers/viz-platform && .venv/bin/python -c "from mcp_server.server import VizPlatformMCPServer; print('MCP Server OK')" -``` +## Related Commands -### Step 4.2: Summary - -``` -╔════════════════════════════════════════════════════════════╗ -║ VIZ-PLATFORM SETUP COMPLETE ║ -╠════════════════════════════════════════════════════════════╣ -║ MCP Server: ✓ Ready ║ -║ DMC Version: [Detected version] ║ -║ DMC Tools: ✓ Available (3 tools) ║ -║ Chart Tools: ✓ Available (2 tools) ║ -║ Layout Tools: ✓ Available (5 tools) ║ -║ Theme Tools: ✓ Available (6 tools) ║ -║ Page Tools: ✓ Available (5 tools) ║ -╚════════════════════════════════════════════════════════════╝ -``` - -### Step 4.3: Session Restart Notice - ---- - -**⚠️ Session Restart Required** - -Restart your Claude Code session for MCP tools to become available. - -**After restart, you can:** -- Run `/component {name}` to inspect component props -- Run `/chart {type}` to create a chart -- Run `/dashboard {template}` to create a dashboard layout -- Run `/theme {name}` to apply a theme -- Run `/theme-new {name}` to create a custom theme - ---- - -## Tool Summary - -| Category | Tools | -|----------|-------| -| DMC Validation | list_components, get_component_props, validate_component | -| Charts | chart_create, chart_configure_interaction | -| Layouts | layout_create, layout_add_filter, layout_set_grid, layout_get, layout_add_section | -| Themes | theme_create, theme_extend, theme_validate, theme_export_css, theme_list, theme_activate | -| Pages | page_create, page_add_navbar, page_set_auth, page_list, page_get_app_config | +- `/component {name}` - Inspect component props +- `/chart {type}` - Create a chart diff --git a/plugins/viz-platform/commands/theme-css.md b/plugins/viz-platform/commands/theme-css.md index 945e68a..c305d7d 100644 --- a/plugins/viz-platform/commands/theme-css.md +++ b/plugins/viz-platform/commands/theme-css.md @@ -4,19 +4,19 @@ description: Export a theme as CSS custom properties # Export Theme as CSS +## Skills to Load +- skills/mcp-tools-reference.md +- skills/theming-system.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Theme CSS Export │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Theme CSS Export | ++------------------------------------------------------------------+ ``` -Then proceed with the export. - -Export a theme's design tokens as CSS custom properties for use outside Dash. +Export a theme's design tokens as CSS custom properties. ## Usage @@ -28,94 +28,13 @@ Export a theme's design tokens as CSS custom properties for use outside Dash. - `name` (required): Theme name to export -## Examples - -``` -/theme-css dark -/theme-css corporate -/theme-css my-brand -``` - ## Tool Mapping -This command uses the `theme_export_css` MCP tool: - ```python theme_export_css(theme_name="corporate") ``` -## Output Example - -```css -:root { - /* Colors */ - --mantine-color-scheme: light; - --mantine-primary-color: indigo; - --mantine-color-primary-0: #edf2ff; - --mantine-color-primary-1: #dbe4ff; - --mantine-color-primary-2: #bac8ff; - --mantine-color-primary-3: #91a7ff; - --mantine-color-primary-4: #748ffc; - --mantine-color-primary-5: #5c7cfa; - --mantine-color-primary-6: #4c6ef5; - --mantine-color-primary-7: #4263eb; - --mantine-color-primary-8: #3b5bdb; - --mantine-color-primary-9: #364fc7; - - /* Typography */ - --mantine-font-family: Inter, sans-serif; - --mantine-heading-font-family: Inter, sans-serif; - --mantine-font-size-xs: 0.75rem; - --mantine-font-size-sm: 0.875rem; - --mantine-font-size-md: 1rem; - --mantine-font-size-lg: 1.125rem; - --mantine-font-size-xl: 1.25rem; - - /* Spacing */ - --mantine-spacing-xs: 0.625rem; - --mantine-spacing-sm: 0.75rem; - --mantine-spacing-md: 1rem; - --mantine-spacing-lg: 1.25rem; - --mantine-spacing-xl: 2rem; - - /* Border Radius */ - --mantine-radius-xs: 0.125rem; - --mantine-radius-sm: 0.25rem; - --mantine-radius-md: 0.5rem; - --mantine-radius-lg: 1rem; - --mantine-radius-xl: 2rem; - - /* Shadows */ - --mantine-shadow-xs: 0 1px 3px rgba(0, 0, 0, 0.05); - --mantine-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1); - --mantine-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1); - --mantine-shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1); - --mantine-shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1); -} -``` - -## Use Cases - -### External CSS Files -Include the exported CSS in non-Dash projects: -```html - -``` - -### Design Handoff -Share design tokens with designers or other teams. - -### Documentation -Generate theme documentation for style guides. - -### Other Frameworks -Use Mantine-compatible tokens in React, Vue, or other projects. - -## Workflow - -1. **User invokes**: `/theme-css corporate` -2. **Tool exports**: Theme tokens as CSS -3. **User can**: Save to file or copy to clipboard +Use cases: external CSS, design handoff, documentation, other frameworks. ## Related Commands diff --git a/plugins/viz-platform/commands/theme-new.md b/plugins/viz-platform/commands/theme-new.md index 96a18c7..8cdd317 100644 --- a/plugins/viz-platform/commands/theme-new.md +++ b/plugins/viz-platform/commands/theme-new.md @@ -4,18 +4,18 @@ description: Create a new custom theme with design tokens # Create New Theme +## Skills to Load +- skills/mcp-tools-reference.md +- skills/theming-system.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · New Theme │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - New Theme | ++------------------------------------------------------------------+ ``` -Then proceed with the theme creation. - Create a new custom theme with specified design tokens. ## Usage @@ -28,99 +28,11 @@ Create a new custom theme with specified design tokens. - `name` (required): Name for the new theme -## Examples - -``` -/theme-new corporate -/theme-new dark-blue -/theme-new brand-theme -``` - ## Tool Mapping -This command uses the `theme_create` MCP tool: - ```python -theme_create( - name="corporate", - primary_color="indigo", - color_scheme="light", - font_family="Inter, sans-serif", - heading_font_family=None, # Optional: separate heading font - border_radius="md", # xs, sm, md, lg, xl - spacing_scale=1.0, # Multiplier for spacing - colors=None # Optional: custom color palette -) -``` - -## Workflow - -1. **User invokes**: `/theme-new corporate` -2. **Agent asks**: Primary color preference? -3. **Agent asks**: Light or dark color scheme? -4. **Agent asks**: Font family preference? -5. **Agent creates**: Theme with `theme_create` -6. **Agent validates**: Theme with `theme_validate` -7. **Agent activates**: New theme is ready to use - -## Theme Properties - -### Colors -- `primary_color`: Main accent color (blue, indigo, violet, etc.) -- `color_scheme`: "light" or "dark" -- `colors`: Custom color palette override - -### Typography -- `font_family`: Body text font -- `heading_font_family`: Optional heading font - -### Spacing -- `border_radius`: Component corner rounding -- `spacing_scale`: Multiply default spacing values - -## Mantine Color Palette - -Available primary colors: -- blue, cyan, teal, green, lime -- yellow, orange, red, pink, grape -- violet, indigo, gray, dark - -## Custom Color Example - -```python -theme_create( - name="brand", - primary_color="custom", - colors={ - "custom": [ - "#e6f7ff", # 0 - lightest - "#bae7ff", # 1 - "#91d5ff", # 2 - "#69c0ff", # 3 - "#40a9ff", # 4 - "#1890ff", # 5 - primary - "#096dd9", # 6 - "#0050b3", # 7 - "#003a8c", # 8 - "#002766" # 9 - darkest - ] - } -) -``` - -## Extending Themes - -To create a theme based on another: - -```python -theme_extend( - base_theme="dark", - name="dark-corporate", - overrides={ - "primary_color": "indigo", - "font_family": "Roboto, sans-serif" - } -) +theme_create(name="corporate", primary_color="indigo", color_scheme="light", font_family="Inter") +theme_validate(theme_name="corporate") ``` ## Related Commands diff --git a/plugins/viz-platform/commands/theme.md b/plugins/viz-platform/commands/theme.md index 86383f5..7ebad84 100644 --- a/plugins/viz-platform/commands/theme.md +++ b/plugins/viz-platform/commands/theme.md @@ -4,18 +4,18 @@ description: Apply an existing theme to the current context # Apply Theme +## Skills to Load +- skills/mcp-tools-reference.md +- skills/theming-system.md + ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🎨 VIZ-PLATFORM · Apply Theme │ -└──────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------+ +| VIZ-PLATFORM - Apply Theme | ++------------------------------------------------------------------+ ``` -Then proceed with the theme activation. - Apply an existing theme to activate its design tokens. ## Usage @@ -28,52 +28,16 @@ Apply an existing theme to activate its design tokens. - `name` (required): Theme name to activate -## Examples - -``` -/theme dark -/theme corporate-blue -/theme my-custom-theme -``` - ## Tool Mapping -This command uses the `theme_activate` MCP tool: - ```python theme_activate(theme_name="dark") +theme_list() # List available themes ``` -## Workflow - -1. **User invokes**: `/theme dark` -2. **Tool activates**: Theme becomes active for subsequent operations -3. **Charts/layouts**: Automatically use active theme tokens - -## Built-in Themes - -| Theme | Description | -|-------|-------------| -| `light` | Mantine default light mode | -| `dark` | Mantine default dark mode | - -## Listing Available Themes - -To see all available themes: - -```python -theme_list() -``` - -Returns both built-in and custom themes. - ## Theme Effects -When a theme is activated: -- New charts inherit theme colors -- New layouts use theme spacing -- Components use theme typography -- Callbacks can read active theme tokens +When activated, new charts/layouts automatically use theme tokens. ## Related Commands diff --git a/plugins/viz-platform/skills/accessibility-rules.md b/plugins/viz-platform/skills/accessibility-rules.md new file mode 100644 index 0000000..9b97a1f --- /dev/null +++ b/plugins/viz-platform/skills/accessibility-rules.md @@ -0,0 +1,64 @@ +# Accessibility Rules + +## WCAG Contrast Standards + +| Level | Ratio | Use Case | +|-------|-------|----------| +| AA (normal text) | 4.5:1 | Body text, labels | +| AA (large text) | 3:1 | Headings, 14pt+ bold | +| AAA (enhanced) | 7:1 | Highest accessibility | + +## Color Blindness Types + +| Type | Affected Colors | Population | +|------|-----------------|------------| +| **Deuteranopia** | Red-Green (green-blind) | ~6% males, 0.4% females | +| **Protanopia** | Red-Green (red-blind) | ~2.5% males, 0.05% females | +| **Tritanopia** | Blue-Yellow | ~0.01% total | + +## Color-Blind Safe Palettes + +### IBM Design Colors +``` +#648FFF #785EF0 #DC267F #FE6100 #FFB000 +``` + +### Tableau Colorblind 10 +``` +#006BA4 #FF800E #ABABAB #595959 #5F9ED1 +#C85200 #898989 #A2C8EC #FFBC79 #CFCFCF +``` + +### Okabe-Ito +``` +#E69F00 #56B4E9 #009E73 #F0E442 #0072B2 +#D55E00 #CC79A7 #000000 +``` + +### Safe Palette Categories + +```json +{ + "categorical": ["#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377", "#BBBBBB"], + "sequential": ["#FEE0D2", "#FC9272", "#DE2D26"], + "diverging": ["#4575B4", "#FFFFBF", "#D73027"] +} +``` + +## Best Practices + +1. **Don't rely on color alone** - Use shapes, patterns, or labels +2. **Test with simulation** - View through color blindness simulators +3. **Use sufficient contrast** - Minimum 4.5:1 for text, 3:1 for large elements +4. **Limit color count** - Fewer colors = easier to distinguish +5. **Use semantic colors** - Blue for information, red for errors (with icons) + +## Accessibility Scoring + +| Grade | Description | +|-------|-------------| +| A | Excellent - All WCAG AAA standards met | +| B | Good - WCAG AA standards met with minor warnings | +| C | Acceptable - WCAG AA met but improvements recommended | +| D | Poor - Some WCAG AA failures | +| F | Failing - Major accessibility issues | diff --git a/plugins/viz-platform/skills/chart-types.md b/plugins/viz-platform/skills/chart-types.md new file mode 100644 index 0000000..de1c7b1 --- /dev/null +++ b/plugins/viz-platform/skills/chart-types.md @@ -0,0 +1,59 @@ +# Chart Types Reference + +## Available Chart Types + +| Type | Best For | +|------|----------| +| `line` | Time series, trends | +| `bar` | Comparisons, categories | +| `scatter` | Correlations, distributions | +| `pie` | Part-to-whole relationships | +| `area` | Cumulative trends | +| `histogram` | Frequency distributions | +| `box` | Statistical distributions | +| `heatmap` | Matrix correlations | +| `sunburst` | Hierarchical data | +| `treemap` | Hierarchical proportions | + +## Theme Integration + +Charts automatically inherit from active theme: +- Primary color for main data +- Color palette for multi-series +- Font family and sizes +- Background colors + +Override with explicit theme: +```python +chart_create(chart_type="bar", ..., theme="my-dark-theme") +``` + +## Export Formats + +| Format | Best For | File Size | +|--------|----------|-----------| +| `png` | Web, presentations, general use | Medium | +| `svg` | Scalable graphics, editing | Small | +| `pdf` | Print, documents, archival | Large | + +## Resolution Options + +### Scale Factor +- `1` - Standard resolution (72 DPI) +- `2` - Retina/HiDPI (144 DPI) +- `3` - Print quality (216 DPI) +- `4` - High-quality print (288 DPI) + +## Export Requirements + +Requires `kaleido` package: +```bash +pip install kaleido +``` + +## Output + +Charts return Plotly figure JSON that can be: +- Rendered in a Dash app +- Saved as HTML/PNG/SVG/PDF +- Embedded in a layout component diff --git a/plugins/viz-platform/skills/dmc-components.md b/plugins/viz-platform/skills/dmc-components.md new file mode 100644 index 0000000..7db04a2 --- /dev/null +++ b/plugins/viz-platform/skills/dmc-components.md @@ -0,0 +1,97 @@ +# Dash Mantine Components Reference + +## Component Categories + +| Category | Components | +|----------|------------| +| `inputs` | Button, TextInput, Select, Checkbox, Radio, Switch, Slider, etc. | +| `navigation` | NavLink, Tabs, Breadcrumbs, Pagination, Stepper | +| `feedback` | Alert, Notification, Progress, Loader, Skeleton | +| `overlays` | Modal, Drawer, Tooltip, Popover, Menu | +| `typography` | Text, Title, Code, Blockquote, List | +| `layout` | Container, Grid, Stack, Group, Space, Divider | +| `data` | Table, Badge, Card, Paper, Timeline | + +## Common Props + +Most components share these props: + +| Prop | Type | Description | +|------|------|-------------| +| `size` | xs, sm, md, lg, xl | Component size | +| `radius` | xs, sm, md, lg, xl | Border radius | +| `color` | string | Theme color name | +| `variant` | string | Style variant | +| `disabled` | boolean | Disable interaction | + +## Component Validation + +Why validation matters: +- Prevents hallucinated prop names +- Validates enum values +- Catches typos before runtime +- Documents available options + +### Validation Response + +```json +{ + "valid": true, + "errors": [], + "warnings": [] +} +``` + +With errors: +```json +{ + "valid": false, + "errors": [ + "Invalid prop 'colour' for Button. Did you mean 'color'?", + "Prop 'size' expects one of ['xs', 'sm', 'md', 'lg', 'xl'], got 'huge'" + ], + "warnings": [ + "Prop 'fullwidth' should be 'fullWidth' (camelCase)" + ] +} +``` + +## Grid System + +DMC Grid with responsive spans: + +```python +dmc.Grid( + children=[ + dmc.GridCol( + children=[chart], + span={"base": 12, "sm": 6, "lg": 4} + ) + ], + gutter="md" +) +``` + +## Button Example + +```json +{ + "component": "Button", + "props": { + "variant": { + "type": "string", + "enum": ["filled", "outline", "light", "subtle", "default", "gradient"], + "default": "filled" + }, + "color": { + "type": "string", + "default": "blue" + }, + "size": { + "type": "string", + "enum": ["xs", "sm", "md", "lg", "xl"], + "default": "sm" + } + } +} +``` diff --git a/plugins/viz-platform/skills/layout-templates.md b/plugins/viz-platform/skills/layout-templates.md new file mode 100644 index 0000000..c27a9e5 --- /dev/null +++ b/plugins/viz-platform/skills/layout-templates.md @@ -0,0 +1,70 @@ +# Layout Templates + +## Available Templates + +### Basic +Single-column layout with header and content area. +``` ++-----------------------------+ +| Header | ++-----------------------------+ +| | +| Content | +| | ++-----------------------------+ +``` + +### Sidebar +Layout with collapsible sidebar navigation. +``` ++--------+--------------------+ +| | Header | +| Nav +--------------------+ +| | | +| | Content | +| | | ++--------+--------------------+ +``` + +### Tabs +Tabbed layout for multi-page dashboards. +``` ++-----------------------------+ +| Header | ++------+------+------+--------+ +| Tab1 | Tab2 | Tab3 | | ++------+------+------+--------+ +| | +| Tab Content | +| | ++-----------------------------+ +``` + +### Split +Split-pane layout for comparisons. +``` ++-----------------------------+ +| Header | ++--------------+--------------+ +| | | +| Left | Right | +| Pane | Pane | +| | | ++--------------+--------------+ +``` + +## Filter Types + +Available filter components: +- `dropdown` - Single/multi-select dropdown +- `date_range` - Date range picker +- `slider` - Numeric range slider +- `checkbox` - Checkbox group +- `search` - Text search input + +## Output + +Layout structures can be: +- Used with page tools to create full app +- Rendered as a Dash layout +- Combined with chart components diff --git a/plugins/viz-platform/skills/mcp-tools-reference.md b/plugins/viz-platform/skills/mcp-tools-reference.md new file mode 100644 index 0000000..868315e --- /dev/null +++ b/plugins/viz-platform/skills/mcp-tools-reference.md @@ -0,0 +1,159 @@ +# Viz-Platform MCP Tools Reference + +## Tool Categories + +| Category | Tools | +|----------|-------| +| DMC Validation | `list_components`, `get_component_props`, `validate_component` | +| Charts | `chart_create`, `chart_configure_interaction`, `chart_export` | +| Layouts | `layout_create`, `layout_add_filter`, `layout_set_grid`, `layout_set_breakpoints` | +| Themes | `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate` | +| Pages | `page_create`, `page_add_navbar`, `page_set_auth` | +| Accessibility | `accessibility_validate_colors`, `accessibility_validate_theme`, `accessibility_suggest_alternative` | + +## DMC Validation Tools + +### list_components +```python +list_components(category=None) # All components +list_components(category="inputs") # Filter by category +``` + +### get_component_props +```python +get_component_props(component="Button") +``` + +### validate_component +```python +validate_component( + component="Button", + props={"variant": "filled", "color": "blue"} +) +``` + +## Chart Tools + +### chart_create +```python +chart_create( + chart_type="line", + data_ref="df_sales", + x="date", + y="revenue", + color=None, + title="Sales Over Time", + theme=None +) +``` + +### chart_export +```python +chart_export( + figure=figure_json, + format="png", # png, svg, pdf + width=1200, + height=800, + scale=2, + output_path=None +) +``` + +## Layout Tools + +### layout_create +```python +layout_create( + name="my-dashboard", + template="sidebar" # basic, sidebar, tabs, split +) +``` + +### layout_add_filter +```python +layout_add_filter( + layout_ref="my-dashboard", + filter_type="dropdown", # dropdown, date_range, slider, checkbox, search + options={} +) +``` + +### layout_set_grid +```python +layout_set_grid( + layout_ref="my-dashboard", + cols=12, + spacing="md" +) +``` + +### layout_set_breakpoints +```python +layout_set_breakpoints( + layout_ref="my-dashboard", + breakpoints={ + "xs": {"cols": 1, "spacing": "xs"}, + "sm": {"cols": 2, "spacing": "sm"}, + "md": {"cols": 6, "spacing": "md"}, + "lg": {"cols": 12, "spacing": "md"}, + "xl": {"cols": 12, "spacing": "lg"} + }, + mobile_first=True +) +``` + +## Theme Tools + +### theme_create +```python +theme_create( + name="corporate", + primary_color="indigo", + color_scheme="light", + font_family="Inter, sans-serif", + heading_font_family=None, + border_radius="md", + spacing_scale=1.0, + colors=None +) +``` + +### theme_extend +```python +theme_extend( + base_theme="dark", + name="dark-corporate", + overrides={"primary_color": "indigo"} +) +``` + +### theme_validate +```python +theme_validate(theme_name="corporate") +``` + +### theme_export_css +```python +theme_export_css(theme_name="corporate") +``` + +### theme_activate +```python +theme_activate(theme_name="dark") +``` + +## Accessibility Tools + +### accessibility_validate_colors +```python +accessibility_validate_colors( + colors=["#228be6", "#40c057", "#fa5252"], + check_types=["deuteranopia", "protanopia", "tritanopia"], + min_contrast_ratio=4.5 +) +``` + +### accessibility_validate_theme +```python +accessibility_validate_theme(theme_name="corporate") +``` diff --git a/plugins/viz-platform/skills/responsive-design.md b/plugins/viz-platform/skills/responsive-design.md new file mode 100644 index 0000000..5f60f6c --- /dev/null +++ b/plugins/viz-platform/skills/responsive-design.md @@ -0,0 +1,104 @@ +# Responsive Design + +## Breakpoint Sizes + +| Name | Min Width | Common Devices | +|------|-----------|----------------| +| `xs` | 0px | Small phones (portrait) | +| `sm` | 576px | Large phones, small tablets | +| `md` | 768px | Tablets (portrait) | +| `lg` | 992px | Tablets (landscape), laptops | +| `xl` | 1200px | Desktops, large screens | + +## Mobile-First Approach + +When `mobile_first=True` (default), styles cascade up: +- Define base styles for `xs` (mobile) +- Override only what changes at larger breakpoints +- Smaller CSS footprint, better performance + +```python +{ + "xs": {"cols": 1}, # Stack everything on mobile + "md": {"cols": 6}, # Two-column on tablet + "lg": {"cols": 12} # Full grid on desktop +} +``` + +When `mobile_first=False`, styles cascade down (desktop-first). + +## Grid Configuration + +Each breakpoint can configure: + +| Property | Description | Values | +|----------|-------------|--------| +| `cols` | Grid column count | 1-24 | +| `spacing` | Gap between items | xs, sm, md, lg, xl | +| `gutter` | Outer padding | xs, sm, md, lg, xl | +| `grow` | Items grow to fill | true, false | + +## Common Patterns + +### Dashboard (Charts & Filters) +```python +{ + "xs": {"cols": 1, "spacing": "xs"}, + "sm": {"cols": 2, "spacing": "sm"}, + "md": {"cols": 3, "spacing": "md"}, + "lg": {"cols": 4, "spacing": "md"}, + "xl": {"cols": 6, "spacing": "lg"} +} +``` + +### Data Table +```python +{ + "xs": {"cols": 1, "scroll": true}, + "md": {"cols": 1, "scroll": false}, + "lg": {"cols": 1} +} +``` + +### Form Layout +```python +{ + "xs": {"cols": 1}, + "md": {"cols": 2}, + "lg": {"cols": 3} +} +``` + +### Sidebar Layout +```python +{ + "xs": {"sidebar": "hidden"}, + "md": {"sidebar": "collapsed"}, + "lg": {"sidebar": "expanded"} +} +``` + +## Component Span + +Control how many columns a component spans: + +```python +{ + "component": "sales-chart", + "span": { + "xs": 1, # Full width (1/1) + "md": 3, # Half width (3/6) + "lg": 6 # Half width (6/12) + } +} +``` + +## CSS Media Queries + +Generated for each breakpoint: +```css +@media (min-width: 576px) { ... } +@media (min-width: 768px) { ... } +@media (min-width: 992px) { ... } +@media (min-width: 1200px) { ... } +``` diff --git a/plugins/viz-platform/skills/theming-system.md b/plugins/viz-platform/skills/theming-system.md new file mode 100644 index 0000000..4d3affd --- /dev/null +++ b/plugins/viz-platform/skills/theming-system.md @@ -0,0 +1,104 @@ +# Theming System + +## Design Tokens + +Themes define design tokens for consistent styling across components. + +### Theme Properties + +| Category | Properties | +|----------|------------| +| Colors | `primary_color`, `color_scheme`, `colors` | +| Typography | `font_family`, `heading_font_family` | +| Spacing | `border_radius`, `spacing_scale` | + +### Color Scheme +- `light` - Light background, dark text +- `dark` - Dark background, light text + +### Border Radius Scale +| Size | Value | +|------|-------| +| xs | 0.125rem | +| sm | 0.25rem | +| md | 0.5rem | +| lg | 1rem | +| xl | 2rem | + +## Mantine Color Palette + +Available primary colors: +- blue, cyan, teal, green, lime +- yellow, orange, red, pink, grape +- violet, indigo, gray, dark + +Each color has 10 shades (0-9), where 5 is the primary shade. + +## Custom Color Definition + +```python +colors={ + "custom": [ + "#e6f7ff", # 0 - lightest + "#bae7ff", # 1 + "#91d5ff", # 2 + "#69c0ff", # 3 + "#40a9ff", # 4 + "#1890ff", # 5 - primary + "#096dd9", # 6 + "#0050b3", # 7 + "#003a8c", # 8 + "#002766" # 9 - darkest + ] +} +``` + +## CSS Custom Properties + +Exported themes use Mantine CSS variable naming: + +```css +:root { + /* Colors */ + --mantine-color-scheme: light; + --mantine-primary-color: indigo; + --mantine-color-primary-0: #edf2ff; + --mantine-color-primary-5: #5c7cfa; + --mantine-color-primary-9: #364fc7; + + /* Typography */ + --mantine-font-family: Inter, sans-serif; + --mantine-font-size-xs: 0.75rem; + --mantine-font-size-md: 1rem; + + /* Spacing */ + --mantine-spacing-xs: 0.625rem; + --mantine-spacing-md: 1rem; + + /* Border Radius */ + --mantine-radius-sm: 0.25rem; + --mantine-radius-md: 0.5rem; + + /* Shadows */ + --mantine-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1); + --mantine-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1); +} +``` + +## Theme Inheritance + +Create themes based on existing ones: +```python +theme_extend( + base_theme="dark", + name="dark-corporate", + overrides={"primary_color": "indigo"} +) +``` + +## Built-in Themes + +| Theme | Description | +|-------|-------------| +| `light` | Mantine default light mode | +| `dark` | Mantine default dark mode |