Pkf SVG

pkf-svg

Visual discipline for controlled SVG, widgets, architecture/topology maps, and Visual Core experiments. It owns composition, semantic color, geometry, safety, and a11y — not PKF persistence or memory placement.

Production boundary (tell the truth)

• PKF v1.1 keeps no prismer-svg production authoring element: SVG travels as a reviewed static asset or a trusted host surface only.
• PKF v1.2 CONTROLLED prismer-svg (docs/pkf209 03 D19) is ACTIVATED (2026-08-18): it may be authored inside PKF source. The production reader validates against the frozen whitelist — script, foreignObject, on*, external href, animation and canvas overflow are hard structure failures (stable svg-* codes), not soft conventions. Never author free/raw SVG in any version.
• In PKF, author diagrams with <prismer-diagram format="mermaid">; use Mermaid erDiagram|flowchart|sequenceDiagram|xychart-beta as appropriate.
• Author data charts with prismer-data views chart-bar|chart-line|chart-pie; the production reader renders them with d3.
• Mermaid renders classic today. D19 proposes host-only handDrawn|neo top-right menu toggles; the workspace host (DiagramView) ships this radiogroup — keyboard reachable, persisted per workspace, source never carries look. Other hosts may not offer the toggle, so do not rely on non-classic look.
• Mermaid actor/entity/class colors SHOULD use the semantic ramps below. Implemented status (D19 §7): the workspace reader's resolveMermaidTheme consumes this exact 9×7 table for themeVariables by diagram family — sequence actor = blue (system), sequence alt/opt branch frame + activation = amber (attention/reversible), note/signal = gray (annotation), erDiagram entity = teal (approved), classDiagram box = purple (control), flowchart nodes = blue (system). Honest limits: flowchart decision diamonds share node colors (mermaid has no diamond-specific themeVariables), and mermaid 11.x does not consume attributeBackgroundColorOdd/Even for erDiagram attribute rows. Unknown diagram types keep the accent palette fallback.
• Apply the SVG rules below for any trusted SVG/widget surface, and for prismer-svg authored in PKF source (v1.2 activated). Otherwise use Mermaid, d3, semantic HTML/prose, or a reviewed static asset.

Scenario routing

• ERD/database schema → Mermaid erDiagram, never hand-drawn.
• Sequential process/decision tree → Mermaid flowchart; ≤5 flow nodes.
• Statistical data → d3 chart view; tables → markdown table, not a figure.
• Controlled SVG/widget → structural, illustrative, or multi-cluster topology only when Mermaid/data surfaces cannot express the intended hierarchy.
• Loops/cycles → stepper with an explicit wrap-back cue, never a decorative ring.

Quality floor: 680×480 topology reference

• Use a 680×480 reference canvas for dense topology; preserve the safe area x=40..640 and keep the bottom-most element at least 20px above the edge.
• Build at least 3 information layers: figure → container → node or status. Containers express bounded contexts; nodes express actors/services/resources; status annotations never compete with the primary topology.
• Provide accessible <title> and <desc> in any trusted SVG surface, plus visible labels. Accessibility text must explain the same relationships.
• Use 0.5px default strokes, boundary-anchored connectors, symmetric padding, and named geometry constants. Nothing clips or floats outside its owner.
• Maintain stable density: consistent node heights, spacing rhythm, label lengths, and connector clearance across peer clusters.

Validator quality floors (stable svg-* rejections)

The frozen whitelist audit also rejects objectively unreadable figures: svg-too-sparse (<3 visible shapes), svg-monochrome (<2 distinct shape fills, backdrop excluded), svg-contrast (text vs container below the 3.0 WCAG large-text floor), svg-text-overflow (label width outside x∈[40, width-40]), svg-stroke-floor (authored stroke-width <0.5), svg-unlabeled (zero visible labels). Each message names the element to fix — repair, never argue.

Copy-first authoring loop

1. copy the skeleton below into ONE `prismer-svg` element (wrapper carries
   width/height/viewBox; the markup inside is the <svg> block)
2. replace labels, coordinates and colors — ramp hexes from the table only
3. run `pkf_svg_check({"svg":"<complete svg markup>"})` and fix every svg-*
   error (one round: each diagnostic names the element/attribute to change)
4. only then `pkf_validate` the complete PKF and persist

pkf_svg_check is a pure local tool: write → check → fix without spending a persist round. If the runtime does not offer it, fall back to pkf_validate on the whole document.

Skeleton — 680×480, three layers (copy verbatim)

<svg viewBox="0 0 680 480" role="img" aria-label="Skeleton: two clusters with one orthogonal edge">
<title>Skeleton: two clusters, one orthogonal edge</title>
<desc>Copyable 680x480 skeleton in three layers: backdrop (neutral canvas plus figure title), edges (orthogonal connectors), nodes (clusters, node rects, labels). Replace labels, coordinates and ramp colors.</desc>
<g id="sk-backdrop">
<rect x="0" y="0" width="680" height="480" rx="12" fill="#F1EFE8" stroke="#B4B2A9" stroke-width="0.5"></rect>
<text x="40" y="32" font-size="13" font-weight="500" fill="#2C2C2A">Figure title — replace</text>
</g>
<g id="sk-edges">
<line x1="248" y1="170" x2="432" y2="170" stroke="#5F5E5A" stroke-width="0.5"></line>
<circle cx="248" cy="170" r="2.5" fill="#5F5E5A"></circle>
<circle cx="432" cy="170" r="2.5" fill="#5F5E5A"></circle>
<text x="340" y="158" font-size="11" fill="#444441" text-anchor="middle">relates</text>
</g>
<g id="sk-nodes">
<rect x="40" y="72" width="208" height="196" rx="10" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="56" y="94" font-size="12" font-weight="500" fill="#0C447C">Cluster A · blue · system</text>
<rect x="56" y="106" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="64" y="127" font-size="12" fill="#0C447C">Node label one</text>
<rect x="56" y="152" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="64" y="173" font-size="12" fill="#0C447C">Node label two</text>
<rect x="432" y="72" width="208" height="196" rx="10" fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"></rect>
<text x="448" y="94" font-size="12" font-weight="500" fill="#085041">Cluster B · teal · ready</text>
<rect x="448" y="106" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#0F6E56" stroke-width="0.5"></rect>
<text x="456" y="127" font-size="12" fill="#085041">Node label one</text>
<rect x="448" y="152" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#0F6E56" stroke-width="0.5"></rect>
<text x="456" y="173" font-size="12" fill="#085041">Node label two</text>
</g>
<text x="40" y="452" font-size="11" fill="#444441">Fallback caption — describe the same relationships in words.</text>
</svg>

Layer contract: sk-backdrop (neutral canvas + figure title), sk-edges (orthogonal connectors between clusters), sk-nodes (cluster frames, node rects, labels). Safe area x=40..640; bottom-most element ≥20px above y=480.

Fragments — cluster / node / orthogonal edge

Each fragment is standalone-valid; copy the inner layer you need into the skeleton and re-check with pkf_svg_check after editing.

<svg viewBox="0 0 240 150" role="img" aria-label="Cluster frame fragment">
<title>Cluster frame fragment</title>
<desc>One bounded-context frame with a title row and one node slot.</desc>
<rect x="0" y="0" width="240" height="150" rx="8" fill="#F1EFE8"></rect>
<rect x="40" y="24" width="160" height="96" rx="10" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="52" y="44" font-size="12" font-weight="500" fill="#0C447C">Cluster · context</text>
<rect x="52" y="56" width="136" height="30" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="60" y="76" font-size="12" fill="#0C447C">Node label</text>
</svg>

<svg viewBox="0 0 240 150" role="img" aria-label="Node and status fragment">
<title>Node and status fragment</title>
<desc>One node rect plus a status chip from a second ramp family.</desc>
<rect x="0" y="0" width="240" height="150" rx="8" fill="#F1EFE8"></rect>
<rect x="40" y="28" width="136" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="52" y="49" font-size="12" fill="#0C447C">Node label</text>
<rect x="40" y="72" width="136" height="22" rx="5" fill="#FAEEDA" stroke="#854F0B" stroke-width="0.5"></rect>
<text x="52" y="87" font-size="11" font-weight="500" fill="#633806">attention note</text>
</svg>

<svg viewBox="0 0 300 120" role="img" aria-label="Orthogonal edge fragment">
<title>Orthogonal edge fragment</title>
<desc>Two nodes joined by an orthogonal polyline with endpoint dots and a label.</desc>
<rect x="0" y="0" width="300" height="120" rx="8" fill="#F1EFE8"></rect>
<rect x="40" y="40" width="80" height="36" rx="6" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
<text x="52" y="62" font-size="12" fill="#0C447C">source</text>
<polyline points="120,58 160,58 160,80 204,80" fill="none" stroke="#5F5E5A" stroke-width="0.5"></polyline>
<rect x="204" y="62" width="80" height="36" rx="6" fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"></rect>
<text x="216" y="84" font-size="12" fill="#085041">target</text>
<text x="160" y="48" font-size="11" fill="#444441" text-anchor="middle">relates</text>
</svg>

Semantic ramp hex table (host tokens — hex only, never CSS variables)

Light mode = 50 fill + 600 stroke + 800 title; dark = 800 fill + 200 stroke

• 100 title (same table, different usage). The svg-monochrome floor requires ≥2 distinct families among shape fills.