WizerdBaChe/diagram-audience-fit / reference-impl/skills/audience-fit
audience-fit
VerifiedPost-production audience-adaptation pass (受眾調校) for anything a NON-BUILDER reads: (A) turn an engineering-voiced deliverable (report, summary HTML, README, release notes) into a reader-facing version in a NEW file, or draw a NEW diagram for a non-builder reader (README flow, promo image, audience page) even with no original; (B) write or fix UI copy (設定頁、狀態列、錯誤訊息) from the user's stance, not the engine's. Trigger on 「使用者導向」「白話版」「寫給非工程師看」「UI 文案」「這段太工程」「AI味」 "rewrite for end users"; OFFER once, unprompted, after any skill produces a deliverable whose primary consumer is not its builder. NOT machine-read docs (phase logs, specs), NOT layout/theming (→ artifact-design), NOT technical docs from code (→ engineering:documentation), NOT task/flow/state evaluation 「走得通嗎」「停用還是隱藏」 (→ ux-walkthrough; findings hand off both ways).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.2 KB |
| references/de-ai-flavor.md | markdown | 4.9 KB |
| references/honest-data-readability.md | markdown | 21.1 KB |
| references/presentational-view.md | markdown | 12.8 KB |
| references/project-info-for-general-readers.md | markdown | 18.7 KB |
| references/ui-copy-stance.md | markdown | 9.4 KB |
references/presentational-view.md
View on GitHub# Presentational view — the A1 rendering profile
> Loaded by audience-fit Mode A1 (same-spec audience re-render). Born from
> round-1 G-6 (2026-08-30); rewritten the same day after G-7 — the first
> A1 render copied the WRONG feature of its archetype and was rejected.
## What the archetypes teach — and what they must not
The user-supplied examples (a paper's classification figure; a public
"Life OS"-style architecture map) teach exactly one thing: **turning
concrete program behaviour into few, reader-named, truthful nodes** —
每個節點是讀者語言的名字+一行角色,元素數量極少,內容全部為真。
They are NOT layout templates. Copying the layered card-grid produced
「完全平級」rows that read as grade-classification — a summary table, and
harder to read than a diagram (user rejection, 2026-08-30). Re-analyse
layout per artifact; never transplant it.
## Rules
- **R1 One page, one reader question** — usually 「這系統是什麼、現在
健康嗎」. Anything answering a different question goes elsewhere.
- **R2 Nodes AND edges — a diagram, not a card grid — on a counted
budget.** An architecture view keeps node 感: boxes joined by drawn
flows, where every arrow states a real call/feed relationship and
position encodes flow in one consistent direction. A layout where
adjacency substitutes for connection is a table wearing a diagram's
clothes. Aggregate the engineering model to capability-level nodes, then
draw the edges that actually exist between them. Two dials, declared
before drawing (diagram-authoring Step 1 close-line):
- *Count dial* — the ladder is calibrated from the accepted A1 renders,
not borrowed: 「全景」 one page = the standing tier — the four accepted
owner views (ccfg / claude-home / mfp-f3 / mfp-f5, 2026-08-30 … 09-05)
hold 11–24 named nodes, 12–27 connectors, 4–14 edge labels; target
≤ 18 nodes / ≤ 24 connectors, hard ceiling 24 / 27 (the largest
accepted, mfp-f3, sits there and reads as the limit, not the norm).
「精簡」 inset / slide panel = ≤ 9 nodes [assumed — no accepted
instance yet; calibrate at the first one]. Over the ceiling → cut in
the R12 order, never squeeze type (R3) or spacing (R10).
- *Wording dial* — who reads: 「owner」 = 白話名稱 + one-line role, no
file names or paths (R3 as written); 「operator/同事」 = the same, plus
the canonical name in parentheses on at most one line per node. The
dial changes text, never the node set.
- **R3 Author-controlled text.** Node text = 白話名稱 (+ English term
where needed) + at most one sub-line role. Line breaks are chosen by
the author — fixed canvas / explicit tspans — never left to auto-wrap:
meaningless CJK mid-word breaks are a named defect. No file names, no
module paths, no evidence codes.
- **R4 Status is first-class and honest**: 未驗收 / 已知缺陷 / 等裁決 as
markers anchored ON the affected nodes (footnote style ①② with a
caption list is fine). Truth markers may MERGE under aggregation, never
disappear — an aggregated node is as unverified as its most-unverified
member. **A marker carried by most nodes is not a marker**: when one
status value covers the majority of the view's nodes, it no longer
discriminates — mark only the exceptions and state the common status
once in the caption ("all other nodes: 未驗收"). If the common status
conflates two axes (built? vs. verified this run?), split the axes
before choosing what counts as an exception. *detect:* count nodes per
status value before rendering; any value on > 50 % of nodes → render it
as the caption default, not as per-node markers. Second incident
(external, 2026-10-04): an outside reader's AI cloned the layered
card-grid template rejected at the top of this file; 70–72 % of nodes on
each page carried the same 「部分/半套」 label and the reader could find
nothing to stop on (analysis kept locally, not shipped).
- **R5 Aggregation carries its mapping**: a collapsed table (node →
canonical elements → **cut**: what R12 removed at which rung, or 「—」)
lives in the page. The presentational view carries NO completeness
claim — the canonical model does; the footer says so. The cut column is
how a reader learns what the page does not show without opening the
canonical page.
- **R6 Flows show the happy path plus NAMED side-states.** Never draw a
transition or edge the system does not have; simplification is
omission, never invention (whitelist truth).
- **R7 No imported chrome, and no pictures at all.** No icons, logos,
brand marks or pictograms on nodes or groups, no decorative metrics,
and no SaaS/Tailwind card aesthetic — uniform rounded-corner cards in
soft-bordered grids are a named user rejection. A node is identified by
its text and its relations; meaning is carried by edges, position and
words. The reference look is the plainness of a paper figure. Excuse
answered: "a product logo is identity, not decoration" — the reader
finds a node by its name, and a picture spends the attention the
relations need (owner ruling 2026-11-05).
- **R8 Carrier parity**: same carrier as the original (HTML → HTML,
PPTX → PPTX); the reader gets the same KIND of artifact.
- **R9 Visual venue sampling** (B-4 applied to the visual register):
before importing any external style, inherit the CANONICAL artifact's
already-accepted visual vocabulary — its color and shape semantics,
simplified (e.g. keep 藍=模組/膠囊=外部/琥珀=資料/綠=狀態/橘虛框=
未驗收 from the source audit page). The canonical is usually the one
visual venue the user has already accepted.
- **R10 Snap or separate — the near-coincidence band is forbidden.** The
eye reads exact coincidence as structure, clear difference as intent,
and near-coincidence as ERROR. This governs every geometric relation,
not just one: parallel runs are either bundled on one shared path or
≥ ~20px apart (measured failure: 2px, read as one smudged line);
centers are either on the same anchor line or a whole column apart
(measured failure: child 40px off its parent's centerline, and the two
edges touching it turned almost-but-not-vertical); an edge is
axis-straight, an orthogonal elbow, or clearly diagonal (≈30° or more)
— never almost-straight; an endpoint touches the border it points at or
keeps a uniform marker gap — never a stray 2px short; an arrowhead's tip
IS the endpoint and its terminal run is longer than the marker (about
1.5× its length), or the head reads squeezed against the border
(2026-11-03, README pipeline). Both round-1
visual defects (G-8, G-9) were instances of this one band.
- **R11 Positions derive from named anchors — no per-element numbers.**
Declare the column centerlines, row baselines, and border ports ONCE
(a comment block inside the artifact) and derive every node center and
edge endpoint from them; alignment then holds by construction, and an
edit moves a column, not a box. Hand-picked local coordinates are how
the near-coincidence band gets entered by accident — each raw number is
an unchecked collision bet (270/334 happened to be clean; that was
luck, not design). A group box is derived the same way: from its
members' bounds plus one fixed pad, never given numbers of its own;
nest one level at most (re-borrow ledger B-23).
Before delivery, run the closing sweep as a
checklist, not a glance: every edge's dx/dy classified against R10's
three allowed kinds, every parallel pair's gap, every endpoint's border
contact, every label's clearance.
- **R12 Fixed cut order — when the R2 ceiling is exceeded, cut in this
order and nowhere else** (borrowed as structure from diagram-design's
degrade ladder, 2026-09-05; rungs re-derived from R3–R6): (1) role
sub-lines on leaf nodes → (2) edge labels that carry no status and
resolve no direction ambiguity → (3) merge sibling leaves into their
parent (truth markers merge, R4) → (4) drop leaf nodes with one edge and
no marker → (5) split into a second page with its own reader question
(R1). NEVER cut: a status marker (R4), an edge between surviving nodes
(R6), the mapping table (R5). Every cut is a row in the R5 cut column
with its rung number; a cut nobody can find in the table is an
invention by omission.
- **R13 A crossing never reads as a join.** Two edges that only pass
each other cross with a line hop (small semicircle on the HORIZONTAL
segment, the vertical stays continuous); edges that really connect meet
at a filled junction dot; a bare "+" is not drawn. This is a reading-ease
rule, not a precision check, so D-071 does not exempt it: a non-builder
cannot tell "passes" from "joins" any better than a builder. Hops and
dots come from the shared plan, never a second hand-written copy:
`hopEdges(edges)` in `tools/archdiag/hops.mjs` takes the page's own
`{id, pts}` orthogonal edges and returns path data, dots and
`hop-no-room` problems; a problem is a reroute (R10 spacing), never a
squeezed hop. A dotted remark line crosses nothing (a hop on it is
invisible). Excuse answered: "it has only one crossing" — one misread
join is still a wrong arrow. Owner ruling 2026-11-01.
- **R14 Default visual vocabulary — every mark carries a meaning.** R9's
inherited vocabulary wins; this default fills the case R9 leaves empty
(no canonical, no host-page images). Nothing is added for looks alone:
a colour, weight or line style that encodes nothing is cut. Owner ruling
2026-11-05; re-borrow ledger B-19–B-22.
- *One reading path* (B-19): the one path the reader should follow takes
the page's single accent colour and numbered steps on its edges; every
other edge stays neutral. The accent never doubles as an R4 status
colour. Under the canvas, a step list gives each
number one plain sentence, opening with the node labels it joins
(one term per thing). A page with no single path draws no accent.
- *Few edge kinds, dual-coded* (B-20): at most four kinds (e.g. main
path / call / event-or-async / build-and-deploy), each told apart by
colour AND line style; the legend lists only the kinds drawn.
- *Two text registers* (B-21): the node name and its R3 role line differ
by weight and size (role smaller, lighter, a second face allowed), so
name and role never read as one sentence.
- *Spacing budget* (B-22): neighbouring nodes on one row or column sit at
least one node width apart; an edge label fits on its segment with
≥ 14px clear at each end, or the nodes move (R10), never the label onto
a node.
- **R15 A line stays near its relation.** A group box tells a non-builder
"these belong together", so a line between two members that leaves the
box reads as an outward link, and a line that wanders away from its
target outside every box sends the reader round the page; a line leaving
a box to reach something outside it is honest. Owner ruling 2026-11-07
(「出框的重點…是否壓住其他呈現以及是否跳脫關係」, option 乙). The closing
sweep catches both, never the eye alone: the page's own geometry through
`clearanceWarnings()` (`tools/archdiag/clearance.mjs`) gives L16
(own-box exit, backtrack outside every box; a loop back to an earlier
step against the flow is exempt) and L17 (detour ratio > 3). A hit is a
move of nodes or a reroute, never an accepted warning. Excuse answered:
"the long way avoids a crossing" — R13's hop makes a crossing cheap to
read; a detour is not.
- **R16 Two kinds of line never share one run.** Lines into or out of one
node may merge into one track only when they look the same; a merged run
is drawn once, so a dashed warn line merged with a solid data line loses
its dash and the reader sees one kind of flow. Reported from outside
2026-11-11. The closing sweep catches it through
`clearanceWarnings()`: L10 `fan-mixed` compares the drawn stroke, dash and
marker. A hit is a reroute, never an accepted warning.
## Boundary (D-071, user ruling 2026-10-23)
A presentational view belongs to audience-fit, rendering included; the
skills are split by consumer and share tools. diagram-authoring serves
builder-level consumers and never gains a presentational view type. The
relation is data plus tools: this skill reads diagram-authoring's
structural model as input (R5 maps to its element ids), and past roughly
18 nodes (R-3, 2026-09-05) it may call a shared renderer under `tools/`
directly. Precision checks — completeness gates, gap tables — are NOT
applied here: a presentational view carries no completeness claim, so it
does not need the instrument that proves one; the canonical audit does.
Geometry asserts are not completeness checks and DO apply: R10/R11 and the
endpoint / edge-through-node asserts of diagram-authoring
`skills/diagram-authoring/references/notation-precision.md` §4, with a known-bad control.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |