notque/vexjoy-agent / skills/frontend/frontend
frontend
UnverifiedFrontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.
references/html-artifact-refs/shape-diagram-illustration.md
View on GitHub# Shape: Diagram & Illustration
> **Shape**: diagram | **Signal words**: architecture, flowchart, sequence, data-flow, figure sheet
> CSS layout classes: `templates/shapes/diagram.css` (injected by assemble-template.py)
---
## Core Principle
Diagrams are STRUCTURAL. Communicate relationships through spatial positioning, connection lines, and labeled nodes. Interactive features (click-to-expand, hover-to-highlight) reveal detail without cluttering the primary view.
---
## Layout Patterns
| Layout | Use When | Structure |
|---|---|---|
| Single diagram + legend | One flowchart or architecture diagram | Full-width SVG, legend below |
| Figure sheet | Multiple illustrations for a blog post | 2-3 column grid of labeled SVG panels |
| Sequence diagram | Message passing between actors | Full-width SVG with lifelines, vertical flow |
| Annotated diagram + callout panel | Complex system with numbered callouts | Diagram left (70%), callout list right (30%) |
| Stacked diagrams | Before/after or layer views | Vertical stack with section headings |
---
## SVG Construction Rules
| Element | Pattern | Notes |
|---|---|---|
| viewBox | `0 0 720 320` (standard) or `720 480` (tall) | Fixed coordinates; CSS scales to container |
| Rendering | Flat, no gradients | Clean, technical aesthetic |
| Stroke | `1.5` for boxes, `2` for emphasis | Consistent weight |
| Corner radius | `rx="10"` | Matches `--radius-md` |
| Labels | `font-size="11"`, `font-family="var(--font-mono)"` | Monospace for technical |
| Node fill | `color-mix(in srgb, <color> 10%, var(--bg-page))` | Tinted background |
| Node stroke | Full semantic color | `var(--color-info)`, `var(--color-primary)`, etc. |
| Sync arrow | Solid line + `marker-end` | Gray stroke |
| Async arrow | Dashed `stroke-dasharray="6 4"` | Info/blue stroke |
| Grouping box | Dashed stroke `<rect>`, low-opacity fill | Groups related nodes |
| Accessibility | `role="img"` + `aria-label` on every `<svg>` | Required |
**Arrowhead markers:** Define in `<defs>` block. Standard (gray), accent (primary), async (info).
---
## Key CSS Classes (from templates/shapes/diagram.css)
| Class | Purpose |
|---|---|
| `.diagram-container` | Bordered surface with horizontal scroll fallback |
| `.diagram-legend` | Flex-wrap legend below diagram |
| `.figure-grid` | Auto-fit grid for figure sheets |
| `.figure-panel` | Bordered card with SVG + figcaption + copy button |
| `.copy-svg-btn` | Appears on hover, copies SVG markup |
| `.diagram-node` | Clickable SVG group with hover/focus states |
| `.node-detail-panel` | Detail panel for clicked nodes |
| `.callout-dot` | Numbered SVG circles for annotated diagrams |
---
## Interaction Patterns
- **Click-to-expand:** Clicking a node shows detail below the diagram (`aria-live="polite"`)
- **Hover-to-highlight:** Dim unrelated elements, highlight connected paths
- **Copy SVG:** Button copies serialized SVG for reuse in other documents
- **Callout panel:** Click numbered dots to highlight matching callout entry
---
## Diagram Type Templates
| Type | Key Elements |
|---|---|
| Flowchart | Horizontal nodes + arrows, labeled edges |
| Architecture | Layer groups (dashed boxes), nodes within layers, cross-layer arrows |
| Sequence | Actor headers, dashed lifelines, activation bars, solid/dashed messages |
| Data flow | Nodes with port labels, directional arrows, async (dashed) for queues |
---
## Common Mistakes
| Mistake | Fix |
|---|---|
| External image references in SVG | All content inline -- no `<image href>` |
| No legend | Always include legend mapping colors to categories |
| Nodes without text labels | Every node needs a text label, not just color |
| SVG not responsive | Use `viewBox` + CSS `width: 100%` + `min-width` for horizontal scroll |
| Missing keyboard support for clickable nodes | Add `tabindex="0"` + `role="button"` + Enter/Space handler |
| Hover-only interactions | Provide click alternative; hover is not available on touch |
---
## Accessibility
- Every `<svg>` has `role="img"` and descriptive `aria-label`
- Interactive nodes: `tabindex="0"`, `role="button"`, `aria-label`
- Enter/Space activates focused nodes
- Color not sole indicator: all nodes have text labels
- Legend always present
- `prefers-reduced-motion` disables SVG transitions
- Detail panel uses `aria-live="polite"` for dynamic updates
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |