hyperui:diagram — Archify draws, hyperui remembers

Archify (MIT) is the engine: its IR, validator, renderer and viewer. This skill picks the type, keeps the diagram in the user's repo, links it to the spec, publishes it and exports Mermaid. Layout and markup are never restated here: Archify's own skill text is the manual.

0. Before anything

• Resolve the project root with ${CLAUDE_PLUGIN_ROOT}/scripts/profile.sh root and use it (absolute paths) for .hyperui/ and for every repo read/write. If <root>/.hyperui/profile.md is missing, invoke the hyperui skill first (it onboards and routes); otherwise read profile.md and state.md and never re-ask what they hold. With several roots (profile.sh roots), work in the repo the request or the touched file belongs to, with that repo's .hyperui/ (rules: ${CLAUDE_PLUGIN_ROOT}/references/workspace.md). Profile fields used: archetype (tone, §6), conversation_language (reply), product_languages[0] (label language and meta.locale: en es ar ko zh-CN zh-TW when Archify ships it, else en; identifiers stay English).
• Engine: "${CLAUDE_PLUGIN_ROOT}/scripts/archify.sh" ensure locates Archify (<project>/.claude/skills/archify, then ~/.claude/skills/archify), installs it when missing (tell the user in one line first) and updates it (bounded; offline keeps the installed version and says so). It prints archify <version> at <ARCHIFY>: keep that root, read <ARCHIFY>/SKILL.md (Type router, Native diagram authoring, Delivery) and the schema + example it names for the type. Every Archify command below is archify.sh run <args>.
• Read what already describes the system before inventing it: brief.md, .hyperui/spec/<topic>/02-design.md, decisions.md, existing .hyperui/diagrams/*.json, then the repo (README, entry points, services, queues, schema). Every component names something that exists or is marked new in the spec. Diagrams live in <root>/.hyperui/diagrams/<name>.{json,html,mmd}.

1. Pick the type by signals — say it in one line, never ask

Ambiguous → run guide "<scenario>" --json. Two types at once (architecture + happy-path sequence is the usual pair) → two files. spec's design phase for a backend + UI, multi-service or new-platform change always asks for architecture + sequence.

2. Procedure — one pass, then at most two focused repairs

1. Name and scope. <name> = <topic>-<type> slug (checkout-architecture, order-lifecycle); title in product_languages[0], one line; a system that does not read in one view → two files, said in one line.
2. Author the Archify IR at <root>/.hyperui/diagrams/<name>.json per <ARCHIFY>/SKILL.md and the type's schema + example: meta.output: "<name>.html", meta.locale (§0), meta.quality_profile: "showcase", fresh ids, labels that mean something, no meta.animation (Live motion is Archify's default), automatic routes first — explicit geometry only for a repair.
3. Validate: run validate <type> <ir> --json. Exit 0 → step 5.
4. Repair, focused and bounded. Archify's diagnostics name the element and print measured fixes (Suggested fix: set labelAt [x, y] or set labelDy 24 (below), widen component "x" so the sublabel keeps …): apply exactly the suggested value to the named element and its direct neighbourhood, nothing else moves. Re-run. Two repairs maximum; still failing → step 5 with the gap declared: the reply lists the remaining diagnostics, design.md records gap: <diagnostics> on the diagram's line, and the care line omits diagram validated. Never a silent gap, never a third loop.
5. Deliver: run deliver <type> <ir> <root>/.hyperui/diagrams/<name>.html --json (refuses while errors remain; relay its update.noticeText once per task when update.noticeRequired is true). Chrome available and visual review asked for → run finalize <type> <ir> <html> --browser-check --json instead. Then node "${CLAUDE_PLUGIN_ROOT}/scripts/diagram-check.mjs" mermaid <ir> writes <name>.mmd (architecture, workflow, sequence, dataflow, lifecycle; other types print "no Mermaid export").
6. Show it. Artifact tool present → publish <name>.html (title = meta.title, icon diagram); a change to an existing diagram republishes to the same url. No Artifact tool (headless -p, evals, subagents) → the .html path and one line "open it in a browser". Browser tool present → one 1280 light capture into <root>/.hyperui/evidence/<date>/ per skills/design/references/browser-verify.md; otherwise Archify's automated checks are the evidence.
7. Memory. design.md ## Diagrams: <name> · <type> · .hyperui/diagrams/<name>.json · <artifact url or html path> · validated <date> (<n> repairs), one line per diagram, updated in place. state.md artifacts: gets diagrams/<name>.html: <url> (replaced on republish), iterations: = repairs. A spec in progress → JSON path + url under ## Diagrams in 02-design.md too. Settled decisions (a boundary, a queue) → decisions.md.

3. Iterating — change what was named, keep the rest still

"Add the queue between API and worker", "move the cache", "rename the gateway": edit the existing .json — add, remove or move only the named elements, keep every other position, re-validate (same two-repair budget), re-deliver, republish to the same url. A new view is a new file, not a rewrite; never regenerate from scratch for a small change. A .json in hyperui's pre-0.14 shape (nodes with row/col, groups, edges): architecture → node "${CLAUDE_PLUGIN_ROOT}/scripts/diagram-check.mjs" migrate <old.json> <new.json>, then step 3 onwards; other old types are re-authored in Archify IR (the script says so).

4. Mermaid — export and fast path, never the source

• The .mmd (structure, not layout; not validated) serves READMEs, PRs and chat. Fast path: destination is a README, PR body or chat answer, or the system has ≤ 6 nodes and no boundaries → fenced mermaid block inline, IR + .mmd still written, no deliver or artifact unless asked.
• Pasted Mermaid ("make this pretty"): Archify reads Mermaid natively — follow the "Mermaid input" section of <ARCHIFY>/SKILL.md (topology and meaning in, fresh Archify IR out), then the normal procedure. The user's Mermaid is never edited.

5. Headless, subagents and other specialists

Headless and subagents have no Artifact and no browser: steps 5–7 still run, the reply gives paths. spec calls this skill in its design phase and links the JSON in 02-design.md; critique, patterns and build read .hyperui/diagrams/*.json as Archify IR (components/boundaries/connections, participants/messages, states/transitions): ids that match the code, sublabel = technology.

6. Tone per archetype (reply in conversation_language)

• non-tech: the artifact link first, then ONE line saying what the picture shows, then the choice. No diagnostics, no px, no file paths unless headless. dev: link or path, the type chosen and why in one line, the component count and the repairs made, the exports. senior: link/path, counts, remaining diagnostics verbatim; nothing else unless asked.
• Every delivery ends with the root §9 care line — diagram validated only when deliver (or finalize) exited 0, plus a11y and dark mode (Archify's viewer), sources cited when the diagram cites the spec or repo files — then the §9 consent line when telemetry is unasked, then the choice prompt (root §9; numbered list as the LAST thing when headless): add or change something in the diagram (Recommended) · export PNG / Mermaid for the README · a second view (sequence of the main path, lifecycle of <entity>) · stop here.
• state.md: phase unchanged, next: the chosen option, last_updated: today. With consent: "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry.sh" event unit_closed diagram outcome=<continue|fix|stop> iterations=<repairs>.

7. Hard rules

• Archify's IR is the only source of truth; the HTML and the .mmd are derived and never edited by hand. Labels mean something (protocol, action, data asset, mechanism); deleting a label is never a spacing fix — move it, then shorten it.
• A boundary around one component needs a stated isolation fact; external actors stay outside every boundary. No company-specific names in the skill (the user's component names belong to the user's repo). No explainer type from here (spec/doc pages cover it).
• The delivered HTML is ~800 KB (Archify's viewer and runtime travel inside it): say so once per project and, when the repo is public, suggest ignoring .hyperui/diagrams/*.html in git while keeping the .json and .mmd.

Sources

Cite only URLs that are listed in a skill/reference or that you opened this session; never construct or guess a URL.

• Archify (MIT), the engine: https://github.com/tt-a1i/archify · installed skill text, schemas and examples at <ARCHIFY> (from archify.sh ensure), usually ~/.claude/skills/archify/ · attribution in NOTICE · superseded method study: docs/research/archify-diagram-method.md.
• Mermaid syntax (flowchart, sequenceDiagram, stateDiagram-v2): https://mermaid.js.org/intro/syntax-reference.html · browser evidence rule: ${CLAUDE_PLUGIN_ROOT}/skills/design/references/browser-verify.md · WCAG 2.2 contrast and focus: https://www.w3.org/WAI/WCAG22/quickref/