# Floracat Architecture Diagram

> Create or revise standalone HTML/SVG architecture diagrams, runtime flow diagrams, sequence diagrams, and PPT-like technical visuals. Use when a user wants human-readable publication-ready diagrams instead of Mermaid, or wants help improving node layout, arrow accuracy, spacing, overlap handling, Chinese labels, or overall visual style for architecture and flow charts.

- Skill: `floracat526/floracat-architecture-diagram` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add floracat526/floracat-architecture-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/floracat526/floracat-architecture-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: floracat526 (https://skillmd.com/u/floracat526)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/floracat526/floracat-architecture-diagram

---


# Architecture Diagram HTML/SVG

Use this skill to produce standalone HTML files with embedded SVG diagrams that feel like clean presentation slides rather than code-first diagrams.

## Output Form

- Default to a standalone HTML file with embedded SVG.
- Prefer sectioned “deck” structure when there are multiple diagrams on one page.
- Use SVG, not Mermaid, for final publication-quality layout control.
- Make the result readable without zooming and understandable by non-engineers.

## Visual Style

- Use a PPT-like information design style: warm background, panel cards, soft shadows, rounded nodes, restrained colors.
- Prefer clear Chinese labels when the audience is Chinese-speaking; keep only essential English technical terms.
- Use a small set of semantic colors and keep them consistent across sections.
- Keep arrowheads understated; do not make lines or markers visually aggressive.
- Favor balanced spacing over dense packing. The page should feel edited, not auto-generated.

## Diagram Building Workflow

1. Identify the user-facing purpose of each diagram.
2. Reduce the system into a few layers or stages before drawing.
3. Choose the simplest SVG structure that fits:
   - layered architecture
   - runtime flow
   - sequence/timing flow
   - subsystem drill-down
4. Place groups first, then nodes, then arrows, then notes.
5. After layout is stable, localize labels and tighten wording.
6. Do a dedicated arrow and overlap review before finishing.

## Node Rules

- Give every node one clear responsibility.
- Keep titles short; if a title is long, widen the node before shrinking text.
- Use subtitle lines for detail; keep them short and scannable.
- Avoid mixing multiple abstraction levels inside one node.
- Align sibling nodes rigorously.
- Treat text fitting as a hard constraint, not a cosmetic preference.
- Prefer expanding node width or height before reducing font size.
- Keep explicit inner padding so text never touches the node border.
- If a label is still too long, split it into multiple lines instead of forcing a single line.
- Keep title and subtitle blocks vertically separated; do not let subtitle lines crowd the title baseline.

## Text Fitting Guardrails

- Titles should usually fit within 1 to 2 lines.
- Subtitle/detail text should usually fit within 1 to 3 short lines.
- If a node needs more than 3 detail lines, simplify the wording or enlarge the node.
- Use centered `text-anchor="middle"` only when the node is visually symmetric; otherwise use left-aligned text with consistent left padding.
- For multi-line text, use explicit `tspan` line breaks and check the last line against the bottom padding.
- Never solve overflow by aggressively shrinking text first. The preferred order is:
  1. shorten wording
  2. widen or heighten the node
  3. split into lines
  4. only then reduce font size slightly

## Overflow Prevention Procedure

Use this procedure whenever a node contains more than a very short label.

1. Decide the node's usable text width first.
   - Reserve horizontal padding on both sides before placing any text.
   - As a default heuristic, keep at least 18 to 24px padding on each side for medium cards.
2. Estimate whether the label is likely to overflow.
   - If the text is more than roughly one short phrase in Chinese, assume wrapping will be needed.
   - If the node title or detail sentence feels visually dense, wrap proactively rather than waiting for collision.
3. Split long text into semantic chunks, not arbitrary character fragments.
   - Break at phrase boundaries such as commas, pauses, or logical halves.
   - Avoid a final orphan line with only a few characters unless the wording makes that unavoidable.
4. Increase node height to match the wrapped text block.
   - Add height for every extra line.
   - Preserve top padding, line spacing, and bottom padding after wrapping.
5. Re-check surrounding arrows.
   - A taller node changes routing. After resizing, reroute nearby arrows so they still terminate cleanly on the edge.

## Default Node Text Layout

When there is no better local reason to do otherwise, use this rhythm:

- Title block near the top with clear top padding
- 8 to 14px vertical gap between title and first detail line
- Detail lines spaced evenly with explicit `tspan`
- Bottom padding large enough that the last line does not feel trapped

If a node contains both a title and multiple detail lines, prefer a slightly taller node over a cramped compact node.

## Arrow Rules

- Every arrow must start and end on a node edge, not inside a node.
- Prefer straight lines first. Add bends only to avoid collisions or ambiguity.
- When two arrows connect the same pair of areas, offset them vertically or horizontally.
- Use solid lines for primary runtime/data flow.
- Use dashed lines only for support, configuration, feedback, optional linkage, or on-demand reads.
- If arrows are long, shorten or reroute them so the direction remains obvious.
- Do not let text sit on top of an arrow.
- Do not let an arrow run through a node body, even briefly.
- Route arrows around nodes with a clear gap instead of clipping through corners.
- When an arrow passes near a label, move the label or reroute the arrow; do not rely on luck.
- Keep arrow stems visually outside the node fill area. The first visible segment should begin at the border, not under the node.
- If an arrow and a node are close, shorten the arrow and move the marker closer to the target edge instead of drawing a long intrusive line.

## SVG Layering Rules

- Draw large background groups first.
- Draw arrows beneath nodes whenever possible.
- Draw node fills and borders above arrows.
- Draw text above both nodes and arrows.
- If an arrow must pass behind a node, the node should fully mask the line so no segment appears inside the node body.

## Editing Rules

- When refining an existing SVG, inspect coordinates instead of making semantic guesses.
- If a user reports overlap, fix geometry directly: move nodes, widen boxes, reroute paths, or adjust text anchors.
- If a user questions arrow meaning, verify the actual system relationship in code/docs first, then correct the line.
- Prefer explicit labels over decorative complexity.
- After every substantial change, do one dedicated pass only for text overflow and node padding.
- After that, do a separate pass only for arrow routing and line-node collisions.
- If multiple nodes have long text, standardize the wrapping style across the whole diagram instead of fixing only one offending node.

## Diagram-Specific Guidance

### Overall Architecture

- Separate access surfaces, control plane/runtime, capability subsystems, and state/config areas.
- Use enclosing groups to show ownership or subsystem boundaries.
- Keep cross-group arrows sparse and precise.

### Runtime Flow

- Emphasize the main path first.
- Put configuration, session state, and plugin/runtime support below the main path as supporting layers.
- Use wording that reads like product behavior, not source code names, unless the source name is important.

### Sequence Diagram

- Reduce participants to the minimum needed to explain the flow.
- Name participants by role, not by file/module, unless implementation detail is the point.
- Use loops only where a real repeated interaction exists.
- Move loop labels close to the loop arrow.

## Final Review Checklist

Before finishing, read [references/review-checklist.md](references/review-checklist.md) and verify every item.