qgraphflow 0.0.6

package/skills/q-flow/references/visual-contract.md

@@ -0,0 +1,54 @@
+# Diagram composition
+
+Composition and colour contract for Viewer development and audits. The authoring rules a graph author needs are summarised in [graph-common.md](graph-common.md); Viewer implementation and interaction checks live in [viewer-development.md](viewer-development.md#viewer-visual-and-interaction-contract).
+
+- Initial canvas budgets are 2400×1600 graph units for architecture / er / deployment / class / usecase / dataflow, 1600×2400 for flowchart / state, and content-adaptive for sequence. These are starting budgets, not minimum borders, export resolutions or aspect-ratio requirements. Preserve full text and type semantics; expand for spacing and routes, keep small graphs compact, and never shrink text or add empty padding to match a ratio. Start with 64 units between peers and 80–96 between layers; expand only the affected label/port corridor. Keep 24 around labels and below measured group headings, with 32 at group sides. Wrap complete long labels instead of spreading every node; sequence messages constrain their own participant span and measured row height. Budgets alone do not rearrange existing geometry.
+- Edge labels sit on their own line in every type except sequence: centred on the segment with the most clearance from both endpoints, backed by the canvas colour so the line reads as interrupted by its label. Sequence messages keep their names above the arrow.
+- Keep full text at 20/16/14px. Minimum clearances: nodes 48px; labels to nodes/labels 24px; labels to unrelated edges 6px; below measured group heading 24px, other insets 32px; sibling groups 48px; parallel channels 24px; straight endpoint segments 12px, ER 28px. Readable point crossings, including nonplanar graphs, are allowed. Prefer fewer repeated crossings between the same pair and reject long collinear overlaps. Layout generation also removes crossings that a different order would avoid: while a candidate still crosses, a bounded search (`REFINE_*` in `compile-layout.mjs`) swaps the ports of the crossing relations within a node side, the side a decision branch or actor relation leaves on, sibling node order and fold lanes, and keeps a swap only when the candidate scores better, so only the crossings a topology forces remain (a full 3×3 mesh keeps 9). Authors never need to reorder edges or add hints for this. Canvas ratios are informational; never remove relationships or shrink text to pass.
+- `adaptive-v2`: generation defaults to `--layout auto` and accepts semantic inputs without positions or sizes. Declare real ownership with node `groupId` and group `parentId`; color `module` is not ownership. Optional node `layout.rank` / `layout.order`, graph `layout.primaryPath` / `layout.participantOrder` express existing order only. `--layout preserve` checks existing geometry without rearranging it. Ambiguous old containment requires an explicit author decision. `--input-only` checks semantics; source, geometry and browser rendering have separate statuses. `--force` only permits replacing outputs and never bypasses quality checks. A layered shape more than 10% outside the accepted width/height band 1/1.6–1.6 is folded by cutting its layer sequence: top-down layouts into columns when too tall, left-to-right layouts into rows when too wide, each segment keeping its reading direction and continuing at the start of the next (never with declared ranks, nor for state charts with branches or loops). The fewest segments that pass the gate within 10% of the band win; folds that would cover foreign nodes or fail the gate are dropped for the next.
+- Make the requested question answerable from the first reading view. Use one clear path, real component/responsibility names, and action/message/data names on edges. Keep boundaries behind nodes and labels clear of group headings.
+- Emphasize the actual business center through a valid `business` kind or `core`/`business` tag. The Viewer supplies cool-neutral Slate surfaces, Iris core/interaction, Cyan data, and Red explicit failures. Cards stay near-white; identity and emphasis live on the frame, the icon chip and a soft ring, never in the text. Do not add color fields or invent a `core` kind.
+- Color supplements labels and notation. A collection may reuse a non-empty `module` name across views so the Viewer can give its cards one identity: a saturated icon chip with a white glyph, a matching 1.5px frame, a faint wash, and the color of every relationship that leaves the card. The business center adds a soft Iris ring behind its frame; an explicit failure keeps a Red frame and ring over any module; data keeps its glyph and a Cyan frame only when it has no module. Module color never replaces node shapes, labels, relationship symbols or evidence styles, and authors never provide literal colors. Framework/inference edges retain dashed evidence styling unless a diagram's notation determines its line style. Preserve exact protocols, multiplicities, guards, and source anchors.
+- Size individual boxes and corridors for complete text; uniformly enlarging the layout cancels readability gains when fitted. Follow the dimensions, automatic lanes, endpoint clearances, and route-hint rules in [graph-schema.md](graph-schema.md#routing-and-spacing). Move nodes before adding route hints; no route may enter a node interior.
+- On desktop, the Viewer fits the whole diagram on opening, reset, view switching and fullscreen entry. Mobile sequence diagrams (≤700px) start with a readable local view at zoom ≥.75; explicit fit always shows the whole drawing. Scale each complete authored node without hiding fields, members, subtitles or other text at lower zoom. Zoom, pan and the minimap reach detail. SVG/PNG exports cover the full diagram; graph data must retain complete content.
+- Author from the requested domain's own evidence. Preview models, facts, and source paths are examples only.
+
+## Color rules for all nine types
+
+- Boundaries are containers, not information: large system, deployment and sequence boundaries use one neutral Slate surface with a 1px hairline, no colored accent, and directly nested boundaries step one surface apart. Nested fills do not accumulate; labels and `alt`/`opt`/`loop`/`par` remain the source of meaning. Ordinary cards keep a faint (5%, dark 9%) wash of their chip color; ER/class headers take a 10% (dark 16%) wash while dense field/member rows stay neutral. Do not recolor nodes merely because they connect: shared module identity and call/return pairs must remain consistent.
+- Reuse the exact `module` name for the same evidenced domain across views. Its name selects a stable theme slot, independent of view order or unrelated module additions/removals. The eight identity scales (Blue, Orange, Teal, Crimson, Violet, Grass, Plum, Indigo) use Radix step 9 for chips and washes and step 10 for frames and lines, sit clear of the Cyan / Red role strokes and can repeat; names, shapes and line notation remain mandatory. Aim for 4–6 meaningful categories in one reading region rather than inventing a module for every node. This is authoring guidance, not a node or palette limit.
+- Keep identity, explicit failure and interaction separate. A failure frame/edge wins over module color; its chip may still identify ownership. Ordinary relationships wear the color of the card they leave; sequence call/return pairs keep their shared pair color and executions. Selection adds a temporary outline without changing semantic color. Decision diamonds, `alt`, FK references, negative guards and terminal states are not automatically failures or successes.
+- Use discrete colors for categories. Do not imply magnitude, security levels, trust zones or data classifications with a gradient unless the source and schema explicitly model that meaning. Do not add literal color fields.
+- Use theme-specific tones and shared page/export styling. Normal diagram text must reach 4.5:1 and meaningful strokes 3:1 against their actual rendered surface; opacity matters. Keep group fills distinct from card fills and retain at least 3:1 edge contrast on them; saturated large-area fills and permanent colored glows are excluded. Nine region tones may repeat in larger diagrams; labels retain meaning. Color never substitutes for readable names, PK/FK, multiplicities, guards, dash patterns, arrow shapes or call IDs; inspect grayscale readability as well.
+
+| Type | Color emphasis |
+| --- | --- |
+| Architecture | Near-white cards with a module chip, frame and faint wash; relationships wear the source card's color; the business center adds a soft Iris ring, text stays ink. |
+| Flowchart | Pale module/semantic process and decision fills; explicit failure paths only use the failure accent. |
+| Sequence | Same color and C number for each call/return pair and its execution; neutral hairline fragments, nested one surface apart, operators and guards as the only distinction. |
+| ER | Module-washed headers inside a module frame, neutral field rows, readable PK/FK/UK text; FK is a reference, not a warning. |
+| Deployment | Module chips and frames on components inside neutral boundaries; do not infer environment or trust from a color. |
+| Class | Module-washed headers inside a module frame, neutral members; retain relationship symbols. |
+| State | Lifecycle-toned state bodies (the `core` state green, a dead end slate, a `failure`-tagged state red, the rest warm to cool by distance from the initial state, lines keep the module color), optional entry/do/exit compartment, arc self-transitions and open-arrow transitions; trigger, amber `[guard]` and muted `/ action` stay distinguishable; ink initial dot and final ring, no success inferred from them. |
+| Use case | Evidenced capability domains share a frame color; the system boundary is a neutral hairline container. |
+| Data flow | Evidenced domain identity on processes and stores; preserve named data flows and directions. |
+
+## Notation by type
+
+Read the row for the selected type; its legal kinds and required fields are in the schema.
+
+| Type | Composition and routing |
+| --- | --- |
+| Architecture | Entry points → core responsibilities → collaborators; explicit ownership/runtime boundaries. Separate cross-layer fan-out and fan-in. |
+| Flowchart | Pill start/end, processes, decision diamonds, I/O and subprocess shapes. Keep the main path top-to-bottom, continuing at the top of the next column when the chart folds; give success and alternative branches separate left/right corridors and route feedback outside. |
+| Sequence | Aligned participants/actors, lifelines, activation bars with nested executions, and numbered messages. Explicitly pair calls with dashed returns; nest `loop → alt` and `opt → par`. Keep self-messages outside lifelines and multiline labels clear of adjacent strokes; do not depict asynchronous callbacks as synchronous waits. |
+| ER | Entity headers and complete PK/FK/UK fields, with cardinalities at both ends. Separate multiple relationships and reserve symbol clearance. |
+| Deployment | Devices, nodes, containers and artifacts inside host/cluster/network boundaries. Show physical placement; keep cross-container labels clear. |
+| Class | Name/stereotype, attributes and methods; separate inheritance triangles, composition/aggregation diamonds and multiplicities. |
+| State | Initial dot, final double circle, states, choices and guarded transitions. Separate failure/cancellation paths, parallel transitions and self-loops. |
+| Use case | Actors, elliptical capabilities and a system boundary. Distinguish actor associations from labeled `include`/`extend` links. |
+| Data flow | External entities, processes and data stores. Name information on each directional flow and separate shared producer/consumer corridors. |
+
+For a requested collection, author every view from the same verified domain vocabulary, use the canonical nine-type order, and validate the whole collection before generation. A failure in one view blocks delivery of the collection.
+
+Nodes, routes, arrows and stroke widths scale together. Sequence screen dash periods have a 6 CSS px minimum to avoid low-DPI aliasing; baseline, mask and phase share this adjustment. Static SVG/PNG exports retain graph-unit notation.