feat(viz-platform): complete Sprint 1 - plugin structure and tests
Sprint 1 - viz-platform Plugin completed (13/13 issues): - Commands: 7 files (initial-setup, chart, dashboard, theme, theme-new, theme-css, component) - Agents: 3 files (theme-setup, layout-builder, component-check) - Documentation: README.md, claude-md-integration.md - Tests: 94 tests passing (68-99% coverage) - CHANGELOG updated with completion status Closes: #178, #179, #180, #181, #182 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
196
plugins/viz-platform/README.md
Normal file
196
plugins/viz-platform/README.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# viz-platform Plugin
|
||||
|
||||
Visualization tools with Dash Mantine Components validation, Plotly charts, and theming for Claude Code.
|
||||
|
||||
## Features
|
||||
|
||||
- **DMC Validation**: Prevent prop hallucination with version-locked component registry
|
||||
- **Chart Creation**: Plotly charts with automatic theme token application
|
||||
- **Layout Builder**: Dashboard layouts with filters, grids, and responsive design
|
||||
- **Theme System**: Create, extend, and export design tokens
|
||||
|
||||
## Installation
|
||||
|
||||
This plugin is part of the leo-claude-mktplace. Install via:
|
||||
|
||||
```bash
|
||||
# From marketplace
|
||||
claude plugins install leo-claude-mktplace/viz-platform
|
||||
|
||||
# Setup MCP server venv
|
||||
cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/viz-platform
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### System-Level (Optional)
|
||||
|
||||
Create `~/.config/claude/viz-platform.env` for default theme preferences:
|
||||
|
||||
```env
|
||||
VIZ_PLATFORM_COLOR_SCHEME=light
|
||||
VIZ_PLATFORM_PRIMARY_COLOR=blue
|
||||
```
|
||||
|
||||
### Project-Level (Optional)
|
||||
|
||||
Add to project `.env` for project-specific settings:
|
||||
|
||||
```env
|
||||
VIZ_PLATFORM_THEME=my-custom-theme
|
||||
DMC_VERSION=0.14.7
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/initial-setup` | Interactive setup wizard for DMC and theme preferences |
|
||||
| `/component {name}` | Inspect component props and validation |
|
||||
| `/chart {type}` | Create a Plotly chart |
|
||||
| `/dashboard {template}` | Create a dashboard layout |
|
||||
| `/theme {name}` | Apply an existing theme |
|
||||
| `/theme-new {name}` | Create a new custom theme |
|
||||
| `/theme-css {name}` | Export theme as CSS |
|
||||
|
||||
## Agents
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
| `theme-setup` | Design-focused theme creation specialist |
|
||||
| `layout-builder` | Dashboard layout and filter specialist |
|
||||
| `component-check` | Strict component validation specialist |
|
||||
|
||||
## Tool Categories
|
||||
|
||||
### DMC Validation (3 tools)
|
||||
Prevent invalid component props before runtime.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `list_components` | List available components by category |
|
||||
| `get_component_props` | Get detailed prop specifications |
|
||||
| `validate_component` | Validate a component configuration |
|
||||
|
||||
### Charts (2 tools)
|
||||
Create Plotly charts with theme integration.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `chart_create` | Create a chart (line, bar, scatter, pie, etc.) |
|
||||
| `chart_configure_interaction` | Configure chart interactivity |
|
||||
|
||||
### Layouts (5 tools)
|
||||
Build dashboard structures with filters and grids.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `layout_create` | Create a layout structure |
|
||||
| `layout_add_filter` | Add filter components |
|
||||
| `layout_set_grid` | Configure responsive grid |
|
||||
| `layout_add_section` | Add content sections |
|
||||
| `layout_get` | Retrieve layout details |
|
||||
|
||||
### Themes (6 tools)
|
||||
Manage design tokens and styling.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `theme_create` | Create a new theme |
|
||||
| `theme_extend` | Extend an existing theme |
|
||||
| `theme_validate` | Validate theme configuration |
|
||||
| `theme_export_css` | Export as CSS custom properties |
|
||||
| `theme_list` | List available themes |
|
||||
| `theme_activate` | Set the active theme |
|
||||
|
||||
### Pages (5 tools)
|
||||
Create full Dash app configurations.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `page_create` | Create a page structure |
|
||||
| `page_add_navbar` | Add navigation bar |
|
||||
| `page_set_auth` | Configure authentication |
|
||||
| `page_list` | List pages |
|
||||
| `page_get_app_config` | Get full app configuration |
|
||||
|
||||
## Component Validation
|
||||
|
||||
The key differentiator of viz-platform is the component registry system:
|
||||
|
||||
```python
|
||||
# Before writing component code
|
||||
get_component_props("Button")
|
||||
# Returns: all valid props with types, enums, defaults
|
||||
|
||||
# After writing code
|
||||
validate_component("Button", {"variant": "filled", "color": "blue"})
|
||||
# Returns: {valid: true} or {valid: false, errors: [...]}
|
||||
```
|
||||
|
||||
This prevents common DMC mistakes:
|
||||
- Prop typos (`colour` vs `color`)
|
||||
- Invalid enum values (`size="large"` vs `size="lg"`)
|
||||
- Wrong case (`fullwidth` vs `fullWidth`)
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
/component Button
|
||||
# → Shows all Button props with types and defaults
|
||||
|
||||
/theme-new corporate
|
||||
# → Creates theme with brand colors
|
||||
|
||||
/chart bar
|
||||
# → Creates bar chart with theme colors
|
||||
|
||||
/dashboard sidebar
|
||||
# → Creates sidebar layout with filters
|
||||
|
||||
/theme-css corporate
|
||||
# → Exports theme as CSS for external use
|
||||
```
|
||||
|
||||
## Cross-Plugin Integration
|
||||
|
||||
viz-platform works seamlessly with data-platform:
|
||||
|
||||
1. **Load data** with data-platform: `/ingest sales.csv`
|
||||
2. **Create chart** with viz-platform: `/chart line` using the data_ref
|
||||
3. **Build layout** with viz-platform: `/dashboard` with filters
|
||||
4. **Export** complete dashboard structure
|
||||
|
||||
## Chart Types
|
||||
|
||||
| Type | Best For |
|
||||
|------|----------|
|
||||
| `line` | Time series, trends |
|
||||
| `bar` | Comparisons, categories |
|
||||
| `scatter` | Correlations, distributions |
|
||||
| `pie` | Part-to-whole |
|
||||
| `area` | Cumulative trends |
|
||||
| `histogram` | Frequency distributions |
|
||||
| `box` | Statistical distributions |
|
||||
| `heatmap` | Matrix correlations |
|
||||
| `sunburst` | Hierarchical data |
|
||||
| `treemap` | Hierarchical proportions |
|
||||
|
||||
## Layout Templates
|
||||
|
||||
| Template | Best For |
|
||||
|----------|----------|
|
||||
| `basic` | Simple dashboards, reports |
|
||||
| `sidebar` | Navigation-heavy apps |
|
||||
| `tabs` | Multi-page dashboards |
|
||||
| `split` | Comparisons, master-detail |
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10+
|
||||
- dash-mantine-components >= 0.14.0
|
||||
- plotly >= 5.18.0
|
||||
- dash >= 2.14.0
|
||||
Reference in New Issue
Block a user