martin65536/liquid-glass-webgl/charts

Beautiful Charts

Quick Setup

bash "$SKILL_DIR/setup.sh"    # Interactive environment check + install

Make every chart and diagram look professionally designed, not AI-generated.

Architecture

Loading order: Read this file → choose framework → read template file → start coding.

Each template file contains its own framework-specific rules (spacing, connectors, color details). This file contains only routing decisions and universal rules that apply to ALL charts.

Part 1: Routing

⚠️ Format Constraint Rule (HIGHEST PRIORITY)

When the user specifies an output format/tool, you MUST comply. Never substitute.

🚫 FORBIDDEN: Mermaid Code Screenshot

NEVER take a screenshot of raw Mermaid source code and deliver it as the "diagram image". This is the worst possible outcome — the user gets neither usable code nor a visual diagram. When the user requests Mermaid format:

1. MUST output the Mermaid code in a fenced code block (```mermaid)
2. SHOULD also render the code into a visual diagram image (via mermaid-cli or Playwright + mermaid.js)
3. If rendering fails, deliver the code block and tell the user to paste it into mermaid.live

Format Specified vs Auto-Upgrade Conflict

When the user specifies Mermaid but content triggers auto-upgrade conditions (>8 nodes, CJK-heavy, etc.):

1. User choice wins — still use Mermaid, deliver code block + rendered image
2. Proactively guide — after delivery, suggest the user try without specifying Mermaid for better layout quality
3. Never silently switch to Playwright+CSS when user explicitly asked for Mermaid

When a specified tool hits rendering difficulties (e.g., mermaid CDN fails):

• ✅ Output raw mermaid code text, tell user to view at mermaid.live
• ❌ Secretly switch to another framework
• ❌ Screenshot the code text as an "image"

Routing Decision Tree

1. Structural Diagrams

🔴 Flowchart Default: Phased Vertical (HIGHEST PRIORITY)

When the user asks to "generate/create a XXX flowchart/流程图" without specifying format, the DEFAULT layout is Phased Vertical (Layout C in `references/playwright-css.md`).

This is because nearly all real-world processes (manufacturing, legal proceedings, project management, business operations, cooking recipes, etc.) have natural phases/stages. Layout C produces the most professional, readable result.

Flowchart routing priority:

1. User specified Mermaid/markdown → follow user choice (Format Constraint Rule)
2. ≤6 nodes AND no phases AND short text → Mermaid (simple flowchart)
3. Everything else → Playwright + CSS, Layout C (Phased Vertical) → references/playwright-css.md

Phase detection — treat as "has phases" when ANY is true:

• Content has numbered sections (一、二、三 or 1. 2. 3. or Phase 1/Stage 1)
• Process can be grouped by time/stage/role (e.g., "preparation → execution → review")
• Total steps ≥ 5 (almost always groupable into 2+ phases)
• Process involves multiple roles/departments
• Process has clear start/end with intermediate stages

⚠️ When in doubt, default to Layout C. A phased layout with only 1 phase still looks professional. A Grid layout with phases looks like a mess.

Other Structural Diagrams

• Simple flowchart (≤6 nodes, truly flat, no phases): Mermaid
• Complex flowchart (>6 nodes / CJK-heavy / branches / phases): Playwright + CSS Layout C → references/playwright-css.md
• Mind map / tree / org chart: Playwright + CSS → references/mindmap-css.md
• Relationship / network diagram: ECharts graph
• Center-radial analysis (SWOT / BSC / Porter's Five Forces / PEST): Playwright + CSS → references/radial-grid.md

2. Data Charts (matplotlib / seaborn)

• Standard bar/line/scatter/heatmap/radar/pie: matplotlib
• Regression/distribution/boxplot: Seaborn

3. Interactive Charts / Dashboards

• Data dashboard / candlestick / real-time: ECharts
• Fully custom interactive: D3.js

Default Strategy

One scene, one tool — don't hesitate:

Mermaid Auto-Upgrade Rules

Mermaid's dagre/elk layout estimates CJK widths incorrectly. Auto-switch to Playwright+CSS when ANY condition is met:

If staying with Mermaid: padding: 32, nodeSpacing: 80, rankSpacing: 80. Node text ≤ 10 CJK chars/line, wrap with <br>, quote all text A["text"].

Large Dataset Rendering

Part 2: Universal Rules

These rules apply to ALL charts regardless of framework. Framework-specific rules live in each template file.

7 Core Rules

1. Zero overlap. No element may cover another's text. Overlap = information loss = task failure. Post-generation: verify every element has clear separation.

1. Hierarchy over uniformity. Primary nodes larger/bolder than secondary. Annotation nodes smaller/muted. Spacing between groups > within groups. If every box looks identical, the layout has failed.

1. Low-saturation palette. 70% background/neutral, 20% secondary, 10% accent (one highlight only). No high-saturation large fills. Saturated colors only on borders (2px), text, and small elements.

1. Insight first. Titles express conclusions, not field names. Remove non-essential elements: top/right borders, grid lines, tick marks, legend box borders. If removing it doesn't reduce understanding, it shouldn't exist.

1. Label clarity over label method. The goal is zero overlap — choose the method that achieves it for each chart type. Direct labels, legends, and leader lines are all valid; what matters is that nothing overlaps.

🚫 FORBIDDEN: Any Text Overlapping Any Other Element

No label, legend, annotation, or title may overlap any other visual element. This is the single most common matplotlib defect. Both direct labels AND legends can cause overlap — neither is inherently safe.

Anti-overlap decision tree:

1. Check if direct labels fit — if all labels have enough space (bar tops, line endpoints, large pie slices), label directly. No legend needed.
2. If some labels would collide (small pie slices, dense scatter points, clustered bars) → use legend outside plot area instead of forcing labels into tight spaces.
3. Mixed approach — label the major items directly, group small items into "其他" or use leader lines + legend for the small ones.

Pie chart specific (the worst offender):

• Slices < 5%: MUST use leader lines (wedgeprops + texts manual repositioning, or matplotlib.patches.ConnectionPatch) to pull labels outside. Do NOT rely on autopct alone — it places text inside/near the slice.
• Multiple small adjacent slices: use bbox_to_anchor legend outside, NOT direct labels
• labeldistance=1.25 minimum to keep labels outside the pie
• When >2 slices are < 5%, consider grouping all < 3% into "其他（X项）"
• Use adjustText library to auto-resolve label collisions when available

Legend placement (when legend is needed):

• Place legend outside the plot area using bbox_to_anchor
• Suggested starting positions:
• Bar/line/scatter: right side outside (bbox_to_anchor=(1.02, 1), loc='upper left')
• Pie: right side outside (bbox_to_anchor=(1.1, 0.5), loc='center left')
• Radar: below chart (bbox_to_anchor=(0.5, -0.15), loc='upper center')
• Heatmap: no legend needed (colorbar suffices)

🔧 Mandatory: auto-adjust legend to prevent overlap. Copy this snippet after placing any legend:

# ── Auto-adjust legend position to prevent overlap ──
fig.canvas.draw()  # must render first to get bboxes
legend = ax.get_legend()
if legend:
    renderer = fig.canvas.get_renderer()
    # Try shifting up to 5 times to resolve overlap
    for _ in range(5):
        leg_bb = legend.get_window_extent(renderer).transformed(ax.transAxes.inverted())
        has_overlap = False
        for text in ax.texts + [ax.title] + ax.get_xticklabels() + ax.get_yticklabels():
            if not text.get_text():
                continue
            txt_bb = text.get_window_extent(renderer).transformed(ax.transAxes.inverted())
            if leg_bb.overlaps(txt_bb):
                has_overlap = True
                break
        if not has_overlap:
            break
        # Move legend further outside (direction depends on current loc)
        bbox = legend.get_bbox_to_anchor().transformed(ax.transAxes.inverted())
        x0, y0 = bbox.x0, bbox.y0
        # Heuristic: if legend is below center, move down; if right of center, move right
        if y0 < 0.5:
            legend.set_bbox_to_anchor((x0, y0 - 0.08), transform=ax.transAxes)
        else:
            legend.set_bbox_to_anchor((x0 + 0.08, y0), transform=ax.transAxes)
        fig.canvas.draw()

• After placing legend: always call plt.tight_layout() or fig.subplots_adjust() to ensure legend is not clipped

🚫 FORBIDDEN:

• loc='best' — matplotlib's "best" frequently overlaps data
• loc='upper right' / loc='lower right' on line/bar charts — high collision risk
• Direct labels on pie slices < 5% without leader lines
• Any text placement without verifying zero overlap

1. Font discipline. Max 2 fonts. Chinese: SimHei/PingFang SC. Always explicitly set fonts in code. Font size follows hierarchy (title 18-24px → body 13-15px → annotation 11-13px). Never go below 10px floor. When text overflows: condense text → enlarge canvas → last resort: shrink font (but never below floor).