c4-interactive-html

Language: Match the user’s language (中文提问则中文回复).

When this skill applies, the agent MUST analyze the user’s current workspace project (the opened repo), then generate one self-contained HTML file that implements the interactive C4 viewer described below. Do not only describe the HTML—write the file to disk.

Architectural anchors (from design)

L1: The current product/repo is the core system (highlighted, only node that drills to L2).
L2: Containers laid out by layers (interface → application → domain → infrastructure). Only the container that has L3 content shows the drill badge.
L3: Exactly one chosen core container (e.g. main API or main web app) is expanded; others stay at L2 only.
Evidence: Prefer facts from files; in the side panel, state inference basis when uncertain (e.g. “inferred from
```
docker-compose.yml
```
”).

Step 1 · Analyze project architecture

Read enough of the repo to justify the diagram:

Build & package

pom.xml

build.gradle

package.json

go.mod

requirements.txt

Cargo.toml

, etc.

Config & ops

application.yml

docker-compose.yml

Dockerfile

.env

(or

.env.example

)

Entry & layout

App entry points,
```
src/
```
or language-idiomatic structure, notable modules

C4 elements to identify

Level	What to capture
People	End users, admins, operators, integrators—who uses or operates the system
L1 Software system	This system + external dependencies (DB, MQ, 3rd-party APIs, other microservices)
L2 Containers	Deployable/runnable units: web apps, APIs, workers, DB, cache, brokers, etc.
L3 Components	Inside one core container: controllers/services/repositories/modules—only the most important slice

Large or unclear repos: Prefer a representative L3; merge minor pieces into grouped nodes; document scope in node

sub

or side panel.

Step 2 · Build the interactive HTML

Overall design

Theme: Light, professional—white/light gray background, clean typography.
Top bar: Project name + breadcrumb
```
L1 / L2 / L3
```
(each segment clickable to go back to that level).
Legend row: Colored dots for node categories (People / core / external / interface / domain / infra, etc.—align with your
```
legends
```
data).

Three canvases

1) L1 System Context (default)

Layout: People (left), core system (center, highlighted, clickable → L2), external systems (right).
SVG curved edges between nodes; label protocol when known (
```
HTTP
```
,
```
gRPC
```
,
```
MQ
```
,
```
JDBC
```
, etc.).
Only the core system shows a “点击下钻” (or “Drill down ↓”) badge; all other nodes use opacity: 0.5
(dimmed).
Click core → switch canvas to L2.
Click dimmed node → open right panel (relationships + description); do not change level.

2) L2 Containers

Show all internal containers with layer separators and labels, e.g. 接口层 → 应用层 → 领域层 → 基础设施层 (or equivalent for the stack).
SVG edges for calls/data flow.
Only the container that has L3 content: colored border + drill badge +
```
cursor: pointer
```
.
Containers without L3: dimmed (
```
opacity: 0.5
```
), no badge; click opens panel only.
Click drillable container → L3.

3) L3 Components

Components grouped by function; SVG edges for dependencies.
Every node click opens the side panel (no further drill level required).

Right panel

Fixed width 380px, slides in from the right.
Shows: name, level badge (L1/L2/L3), description, related relationships (list of edges touching the node).
ESC or × closes the panel.

Node styling

Drillable: colored border/background treatment + top-right badge “点击下钻 ↓” +
```
cursor: pointer
```
.
Non-drillable:
```
opacity: 0.5
```
, no badge; click → panel only.
Selected: blue glow/shadow; incident edges emphasized; other edges and nodes fade.

Data shape (embed in HTML)

Use one object per level (names may be

L1

L2

L3

level1

—be consistent in JS):

javascript

const L1 = {
  nodes: [
    {
      id: 'unique-id',
      label: '显示名称',
      sub: '描述 / 推断依据',
      c: 'color-key',
      x: 0,
      y: 0,
      w: 180,
      drill: true,
      drillTo: 'L2',
    },
  ],
  edges: [
    { f: 'from-id', t: 'to-id', c: 'color-key', protocol: 'HTTP' },
  ],
  layers: [{ y: 120, label: '层名称', color: '#ccc' }],
  legends: [{ c: 'core', l: '核心系统' }],
};

c
: maps to the palette / CSS class for node category.
protocol
: optional; show on or near the edge if present.
No external JSON fetch—all data inline in the same file.

Color palette (light mode)

Background
```
#f5f7fa
```
, cards
```
#ffffff
```
, hover
```
#f0f2f5
```
Core:
```
#1168BD
```
· Domain/data:
```
#2b8a3e
```
· External/AI:
```
#6f42c1
```
· Interface:
```
#d4620a
```
· Governance:
```
#b8860b
```

Fonts

Allowed external dependency: Google Fonts CDN (e.g. a Latin + CJK-friendly stack). If CDN is undesirable, use a system font stack that supports Chinese: e.g.
```
system-ui, "PingFang SC", "Microsoft YaHei", sans-serif
```
.

Layout quality

Avoid overlapping nodes; keep edge labels readable; use canvas size / coordinates so the diagram fits a typical laptop viewport with scroll as fallback.

Step 3 · Output path

Default: save as <workspace-root>/c4-architecture.html
— the current conversation project directory (Cursor: the workspace folder for a single-folder workspace; Claude Code / other hosts: the project
```
cwd
```
used for analysis). Filename stays
```
c4-architecture.html
```
.
User override (same turn): if the user asks for a path under the project (e.g.
```
docs/c4-architecture.html
```
), honor it relative to the chosen workspace root unless they give an absolute path; create parent directories when safe.
Multi-root workspace: if several folders are open and the user did not specify a project, use the root that was the focus of architecture analysis, or ask which root to use before writing.
Unknown root or not writable: do not silently fall back to
```
~/Downloads
```
or elsewhere. Ask the user for an explicit directory or full file path and state the reason (e.g. permission, ambiguous root).
After writing, confirm the absolute path in the assistant message.

Acceptance checklist (before finishing)

Single file, opens in a normal browser; no npm/build step.
Breadcrumb, legend, L1/L2/L3 behavior, panel, ESC close, selection highlight—all present.
Core system-only drill on L1; single L3 target; dimmed nodes behave as specified.
Chinese labels render correctly (
```
<meta charset="utf-8">
```
+ fonts).
File written to workspace root default (
```
c4-architecture.html
```
) or user-agreed path; absolute path confirmed in reply.

Related doc

See

USAGE.md

in this folder for FAQs (path override, minimal backends, offline fonts).

c4-interactive-html

NPX Install

Tags

SKILL.md Content

c4-interactive-html

Architectural anchors (from design)

Step 1 · Analyze project architecture

Step 2 · Build the interactive HTML

Overall design

Three canvases

Right panel

Node styling

Data shape (embed in HTML)

Color palette (light mode)

Fonts

Layout quality

Step 3 · Output path

Acceptance checklist (before finishing)

Related doc