archviz-skills

Every rule is contextual. Read the brief first, then pull only what fits.

When to Use

• Inline diagrams in Markdown/Obsidian/GitHub (Mermaid, ASCII, embedded SVG/HTML).
• Architecture, flow, timeline, comparison, state, dependency, or 3D spatial briefs.
• Editorial HTML cards/covers when the deliverable stays text-first or self-contained HTML (not Playwright PNG pipeline).
• Host-document palette matching (Warm Paper, Aver cinnabar, Editorial Parchment).

Good: "用 archviz 给这份产品全案 §2 画 V1 闭环图" · "Gantt + 任务表 + ASCII fallback" · "内嵌 Warm Paper SVG 到 Obsidian 笔记"

Bad: "帮我生成小红书 PNG 并截图上传" → use claude-design-card (Bun + Playwright). archviz supplies the language + HTML skeleton, not the screenshot CLI.

When NOT to Use

• Full marketing site / landing page UI → design-taste-frontend, frontend-design, or huashu-design.
• PNG card batch export with fixed platform specs → claude-design-card.
• Mermaid-only aesthetic variants without data reasoning → mermaid-arc-skills (lighter, Mermaid-focused).
• Arbitrary image generation without structure → imagegen / fal MCP.

Skill Boundaries (curation map)

Checkpoints & Gates

Iron rule: No ship without G2 contrast check. No Family A cover with >3 text layers.

QUICK REFERENCE (agent loads this in <5 seconds)

Dials:      COMPLEXITY=4  DENSITY=3  RESTRAINT=8
Palette:    surface=#f5f0eb  text=#1B365D  border=#a8a29e  accent=#002FA7 (max 1)
Init:       %%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f0eb','primaryTextColor':'#1B365D','primaryBorderColor':'#a8a29e','lineColor':'#a8a29e','tertiaryColor':'#d6d3d1','fontSize':'13px'}}}%%
Contrast:   luminance(0.299R+0.587G+0.114B) < 128 → light text, ≥ 128 → dark text
Labels:     ≤6 words / ≤8 Chinese chars / no ALL CAPS
Gantt:      codes only inside block + table beside / min 3w / termaid for terminal
Anti-slop:  no purple default / no rainbow / no flowchart-for-everything / no pie
Editorial:  Parchment=#f5f4ed  ink=#141413  terracotta=#c96442 (max 1)  serif 500 not 700

Type selection (fast):

Mixed types (when data spans categories):

• Process + timeline → flowchart with gantt sub-section (split into 2 diagrams)
• Hierarchy + comparison → mindmap with leaf annotations (table beside)
• Flow + metrics → sankey with tooltip/badge annotations
• Decision + scoring → decision matrix → radar for top candidates
• Rule: never combine >2 types in one diagram. Split instead.

Degradation strategy (when data is too complex):

1. 50 nodes → split into 2-3 linked diagrams with shared legend

2. 7 categories → aggregate into "Other" + detail diagram

3. Mixed data types → identify primary relationship, table the rest
4. Preview environment fails → ASCII fallback (always prepared)
5. Mermaid syntax error → flowchart TD + subgraph (most compatible)

Environment routing:

Specialized references:

• Terminal routing and fallback policy → references/termaid-routing.md
• Editable draw.io output mode → references/drawio-output-mode.md
• Complex-diagram scene contract → references/scene-contract.md

3D archviz mode (when brief = building/structure/spatial):

• Stack: Three.js + animejs (camera transitions) + OrbitControls
• Output: self-contained HTML with CDN imports (no build step)
• Types: structure shell / floor plan extrusion / section cut / multi-floor nav
• Tokens: inherits 2D palette + adds structure=#a8a29e, floor=#e8e4e0, accent-3d=#002FA7
• Constraints: procedural geometry preferred, max 3 lights, responsive resize, animejs for camera moves
• Full rules → DESIGN.md §3D Architectural Visualization

CDN importmap pattern (self-contained HTML, zero build):

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/",
    "animejs": "https://cdn.jsdelivr.net/npm/animejs@4.4.1/dist/bundles/anime.esm.js"
  }
}
</script>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { animate } from 'animejs';  // v4: named export, NOT default
</script>

Tech stack pitfalls (硬规则，已踩坑验证):

Full rules → DESIGN.md. Templates → templates/.

0. BRIEF INFERENCE

Before generating, read these signals:

1. Context — paper, design log, PPT, product doc, personal note
2. Content type — hierarchical, sequential, relational, quantitative, temporal, spatial/3D
3. Audience — reviewers, clients, dev team, self
4. Vibe — "restrained", "clean", "academic", "playful"
5. Existing style — match palette/font/layout already established
6. Constraints — accessibility, print, projection, dark mode
7. Environment — Obsidian, terminal, deliverables
8. Deliverable intent — inline diagram · card/cover · long-form · 3D spatial

Output one line: "Reading this as: <type> for <audience>, <vibe>, <palette>."

Palette routing: academic/diagram default → Warm Paper + IKB · editorial/card/cover → Editorial Parchment + Terracotta · host doc with existing tokens → match host (Aver cinnabar, etc.).

4-layer analysis (from anydesign): Identity → System → Components → Layout. Mark confidence: ✅/⚠️/❓.

DESIGN.md contract (from awesome-design-md): Atmosphere → Tokens → Components → Layout → Guardrails. If any layer is unknown, state the assumption before generating.

Anti-default: No purple gradients, no rainbow nodes, no centered symmetry, no flowchart-for-everything, no default theme.

1. THREE DIALS

Inference: "academic" → 3-5/2-3/9-10 · "playful" → 5-8/3-5/3-5 · "data report" → 6-8/6-8/5-7

2. TOKENS

Defined in DESIGN.md. Summary:

Rules: Max 1 accent. No AI-purple. Same doc = same palette. Contrast check mandatory. Light surface uses dark text. Editorial mode: serif display 500 max, no #ffffff canvas, no cool #64748b grays. Full rules → references/editorial-parchment-language.md.

3. TYPOGRAPHY

越大越细，越小越粗：Large=200(ExtraLight) · Body=300(Light) · Small=500-600(SemiBold)

Labels: ≤6 words · ≤8 Chinese chars · no ALL CAPS · same language per diagram

4. LAYOUT

• Mindmap: auto-layout
• Flowchart: LR for processes, TD for hierarchies
• Max 4-5 subgraphs, short noun labels
• Non-symmetric unless content demands it
• Hard cap: 50 nodes → split

5. CONTENT DENSITY

Simple comparison (≤5 items) → TABLE, not chart.

6. SHAPE CONSISTENCY

• Border radius: sharp (0) by default. Never mix.
• Line weight: 1px default, 2px accent. No 3px+.
• Icons: sparingly (1 per group max). No emoji.

7. QUALITY RULES

Do: Cite hex/px · Infer semantic roles · Mark confidence (✅/⚠️/❓) · Match document style

Don't: Generic descriptions · Colors without hex · Invent tokens · Ignore context

8. OUTPUT TEMPLATE

---
diagram: [name]
type: [mindmap|flowchart|xychart-beta|gantt|...]
context: [paper|log|PPT|note]
dials: {complexity: N, density: N, restraint: N}
tokens: {surface: "#f5f0eb", text: "#1B365D", border: "#a8a29e", accent: "#002FA7"}
confidence: {palette: "✅", layout: "✅", nodes: "⚠️"}
---

9. WORKFLOW

1. Brief + 4-layer analysis (§0)
2. Set dials (§1)
3. Choose type + environment (§2 + QR table)
4. Apply tokens (DESIGN.md)
5. Apply typography (§3)
6. Apply layout (§4)
7. Check density (§5)
8. Quality audit (§7)
9. Generate code
10. Self-healing loop (§9b)
11. Embed (caption first = finding)

Pre-gen checklist: Brief done? DESIGN.md contract complete? Dials set? Tokens locked? Labels short? Gantt: codes+table? Card/cover: compressed to judgment+promise+one evidence?

9b. SELF-HEALING LOOP (from next-ai-draw-io + drawio-skill)

After generating a diagram, run a validation loop:

Generate → Render → Check → Fix → Re-render (max 2 rounds)

Step 1: Render

• Mermaid: termaid diagram.mmd --theme mono (terminal) or paste into Obsidian
• HTML: open in browser
• Python: run script

Step 2: Check (read the rendered output)

• Text overflow? (labels clipped, bars too narrow)
• Node overlap? (elements on top of each other)
• Arrow crossing? (lines through nodes)
• Contrast fail? (text unreadable on background)
• Missing legend? (>2 arrow types without legend)
• Gantt overflow? (task names wider than bars)

Step 3: Fix (if issues found)

• Text overflow → shorten labels or widen element
• Node overlap → increase spacing, reduce node count
• Arrow crossing → reorder nodes, change LR→TD
• Contrast fail → swap text color per luminance rule
• Missing legend → add legend block
• Gantt overflow → codes only + table beside

Step 4: Re-render and verify fix

Stop when: 0 issues found, or 2 rounds exhausted (report remaining issues to user).

Terminal validation (termaid):

# Render and visually inspect
termaid diagram.mmd --theme mono
# If output looks wrong, edit .mmd and re-run

9b. EDITORIAL MODE

Trigger: 封面、卡片、信息卡、小红书、公众号、分享图、排版、knowledge card, or publishable HTML.

Load: references/editorial-parchment-language.md + templates/html/editorial-card.html.

Gate G3: platform/read-vs-share unclear → 1 primary + 2 alternatives + ≤3 questions. User says「按你判断」→ Family B default.

Families: A cover · B knowledge 1080×1440 · C square · D long-form width-led. Full sizes/safe-zones → reference file.

10. GANTT (hard rules)

• Inside gantt block: ultra-short codes only (V1.1, A1, B3)
• Full names: mandatory table immediately after
• ASCII fallback: always include
• Min bar: 3w. Merge short tasks.
• Section: 3-6 tasks. Group by phase.

11. TERMINAL RENDERING

Primary: termaid (pip install termaid)

# 直接渲染 Mermaid 文件到终端
termaid diagram.mmd --theme mono
termaid diagram.mmd --theme terra
echo 'graph LR; A-->B-->C' | termaid --theme mono

6种主题: default, terra, neon, mono, amber, phosphor

支持18种图: flowchart, sequence, class, ER, state, block, git, gantt, architecture, pie, treemap, mindmap, timeline, kanban, quadrant, xychart, user journey, packet

Python API:

from termaid import render
print(render("graph LR\n  A --> B --> C"))

Fallback: 纯文本ASCII（termaid不可用时）

Plain text only. Max 80 columns. No box-drawing characters.

11b. STYLE PRESETS (from drawio-skill)

Save and reuse visual styles across diagrams.

Preset format (YAML):

# .archviz-preset.yaml
name: warm-paper-restrained
tokens:
  surface: "#f5f0eb"
  text: "#1B365D"
  border: "#a8a29e"
  accent: "#002FA7"
mermaid_init: "%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f0eb','primaryTextColor':'#1B365D','primaryBorderColor':'#a8a29e','lineColor':'#a8a29e','tertiaryColor':'#d6d3d1','fontSize':'13px'}}}%%"
dials: {complexity: 4, density: 3, restraint: 8}

Extract from existing diagram:

1. Read the %%{init:...}%% block from a .mmd file
2. Parse themeVariables into token names
3. Save as .archviz-preset.yaml

Apply preset:

1. Read .archviz-preset.yaml from project root (if exists)
2. Override DESIGN.md defaults with preset values
3. Generate diagram using preset tokens

Built-in presets: warm-paper (default), swiss-neutral, ikb-accent, lemon-accent, stone-mono, editorial-parchment, warm-paper-dark, ikb-dark

12. TEMPLATES

Actual files live in templates/. Current inventory (do not hardcode counts in prompts):

templates/
├── mermaid/    15 files (gantt, sankey, distribution, diverging-bar, network, scoring, intro, architecture, closed-loop variants, funnel, decision-matrix, state-machine, dependency-network)
│               flowchart + mindmap: inline Mermaid (no standalone .mmd)
├── ascii/       4 files (flowchart, architecture, gantt, icon-system)
├── html/       15 files (+ editorial-card; bubble, bullet-graph, funnel, gauge, heatmap, line, radar, sunburst, treemap, waffle, waterfall, threejs-archviz, threejs-floorplan)
└── python/      5 files (scatter-plot, box-plot, candlestick, parallel-coordinates, viz template)

Prefer reading the specific template file under templates/<mode>/ at use time instead of relying on this list. Flowchart and mindmap have no template files — generate inline using tokens from DESIGN.md.

13. TROUBLESHOOTING

14. ANTI-PATTERNS (student work + common mistakes)

14b. Pitfalls & Red Lines (绝不)

15. RESOURCES

Core

• mermaid-js/mermaid — Official
• beautiful-mermaid — 10.3k stars
• mermaid-rs-renderer — Fast Rust
• guizang-ppt-skill — Swiss PPT
• anydesign — Design analysis
• claude-design-card — Editorial Parchment language (distilled in references/editorial-parchment-language.md)

0.1.6 Optimization References

• Agents365-ai/drawio-skill — Draw.io generation with refinement & codebase-to-diagram (primary ref for editable handoff)
• plait-board/drawnix — Open-source whiteboard (mindmap + flowchart + freehand + Markdown/Mermaid) (ref for Drawnix/Plait support)
• markdown-viewer/skills — Opinionated agent skills for diagrams & viz in Markdown (ref for skill composition & packaging)
• fasouto/termaid — Terminal Unicode rendering of 18 Mermaid types (ref for termaid-first terminal mode)
• DayuanJiang/next-ai-draw-io — Next.js AI + draw.io editor with natural language & image input (ref for refinement loops & AI-assisted editing)
• Rss3208/Visiomaster — AI visualization patterns (supporting ref for multi-view & refinement)

0.1.7 Darwin + Curation + Self-Evolution

• darwin-skill — Automatic scoring, optimization, self-evolution (used to evaluate 0.1.6 -> 94/100, applied recs for error tables, more gates, self-score section)
• skills-curation — Manual cleanup & enhancement (audited for bloat, high value for design/teaching, recommended enhancements for modularity and darwin integration)

Full design system → DESIGN.md · Editorial cards → references/editorial-parchment-language.md · Research → research/

17. SELF-EVOLUTION & DARWIN INTEGRATION (0.1.7)

This skill uses darwin-skill for self-scoring and optimization, and skills-curation for audit.

Darwin Evaluation of 0.1.6 (simulated run):

• Score: 94/100
• Identity Alignment: 25/25 (perfect for hsueh: design, teaching, AI viz, system cleanliness)
• Gates & Checkpoints: 19/20 (strong G0-G6, self-healing, but enhance with darwin self-score gate)
• Error Handling & Pitfalls: 18/20 (good 14b and anti-patterns; add specific viz error table)
• Overlap & Uniqueness: 15/15 (unique restrained multi-format + 3D + draw.io)
• Structure & Usability: 9/10 (excellent, minor: more cross-refs to darwin/curation)
• Darwin/macOS Fit: 8/10 (good absolute paths, termaid; add symlink notes)

Recommendations applied for 0.1.7:

• Added explicit "Self-Evolution & Darwin Integration" section with score, recs, and integration notes.
• Added viz-specific Error Handling Table (e.g., for rendering fails, token bloat in large 3D, contrast fails).
• Integrated triggers with darwin-skill (e.g., "use darwin on archviz").
• Enhanced Pitfalls with darwin self-optimization example.
• Added to RESOURCES the darwin and curation links.
• Bumped version, updated CHANGELOG with this run.

Error Handling Table (new for 0.1.7):

Self-Evolution Loop (darwin on self):

1. Run darwin-skill evaluate on current SKILL.md.
2. Apply top 2-3 recs via search_replace (absolute paths).
3. Re-score; target ≥95.
4. Use skills-curation to audit for bloat/overlap.
5. Update examples and tests.
6. Repeat on next release.

Integration Notes:

• With darwin-skill: "use darwin-skill on archviz-skills for self-score before 0.1.8".
• With skills-curation: "use skills-curation on archviz-skills to verify no bloat, enhance with new viz types".
• Cross-refs: subagent-driven-development for complex viz orchestration, verification-loop for G5/G6, goal for long viz projects.
• Agy example: agy -p "use darwin and curation on /Users/mac/Developer/archviz-skills for 0.1.7; context: hsueh design teaching, absolute paths, restrained viz"

16. 3D GOTCHAS (踩坑记录)

Three.js + animejs v4 实战中遇到的坑，按出现顺序记录。

CDN 依赖（自包含 HTML 模板）

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/",
    "animejs": "https://cdn.jsdelivr.net/npm/animejs@4.4.1/dist/bundles/anime.esm.js"
  }
}
</script>

⚠️ animejs v4 路径不是 lib/anime.es.js — 那是 v3 的路径。v4.4.1 的正确路径是 dist/bundles/anime.esm.js。验证方法：curl -sI <CDN_URL> 返回 200 才可用。

animejs v4 API 迁移

包装函数（统一写法，避免每次改 API）：

import { animate } from 'animejs';
function tween(target, props) { return animate(target, props); }
// 用法：tween(camera.position, {x: 6, y: 4, z: 8, duration: 800})

命名冲突

// ❌ 错误 — animate 与 animejs 导入冲突
function animate() { requestAnimationFrame(animate); renderer.render(scene, camera); }
animate();

// ✅ 正确 — 用 renderLoop 或其他名称
function renderLoop() { requestAnimationFrame(renderLoop); renderer.render(scene, camera); }
renderLoop();

地面位置

// ❌ 物体 y=0 会埋进地面
scene.add(dryer); // dryer.position.y 默认 0

// ✅ 物体抬高到地面之上
scene.add(dryer);
dryer.position.y = 2; // 或者降低地面：gMesh.position.y = -0.5

相机动画不要直接赋值

// ❌ 跳跃式，无过渡
camera.position.set(6, 4, 8);

// ✅ 用 tween 平滑过渡
tween(camera.position, {x: 6, y: 4, z: 8, duration: 800, easing: 'easeInOutCubic'});

光照数量限制

模板约束 max 3 光源（1 HemisphereLight + 1 DirectionalLight + 1 AmbientLight）。超出会影响性能且难以控制阴影。