/pkf-svg

name: pkf-svg
scope: common
description: 'Design controlled SVG, visual widgets, topology and Visual Core explainers with semantic color, safe geometry, accessibility, and bounded complexity. Use for an explicitly supported SVG/widget surface or to plan PKF visuals. PKF v1.1 has no production inline-SVG authoring surface (diagrams are Mermaid, data charts are d3); v1.2 controlled prismer-svg (pkf209 D19) is activated for PKF source authoring within the frozen validator whitelist.'
metadata:
  nativeReplaces: [architecture-diagram]
  aliases:
    - pkf-visual

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