fix: style guide

STYLES_GUIDE.md

@@ -2,108 +2,211 @@
 
 Use this guide when generating or modifying Excalidraw scenes.
 
+## Author intent (must follow)
+
+- Excalidraw is for free-flow visual thinking: nodes, arrows, curves, boundaries, and hanging labels.
+- Treat this as a diagramming task, not a document-writing task.
+- Prefer visual relationships over long prose.
+- If content starts becoming paragraph-heavy, split it into smaller nodes and explicit connectors.
+- Prioritize flow clarity over text density.
+
 ## Core intent
 
-- Always use dark mode.
+- Always set `scene.appState.theme` to `"dark"`.
+- Always use light-style element colors.
 - Optimize for clarity, technical precision, and fast visual parsing.
-- Tailor the diagram structure to the task itself. Do not default to generic flowcharts.
-- Prefer diagrams that feel like working engineering notes, not slides or business documentation.
+- Tailor structure to the problem. Do not default to generic flowcharts.
+- Prefer diagrams that look like working engineering notes, not slides.
 
 ## Theme
 
-- Use a dark canvas and dark containers by default.
+- Use a light canvas and light containers by default.
 - Keep contrast high enough for comfortable reading.
-- Use a restrained palette. Do not introduce many colors unless the task truly needs them.
+- Use vibrant accent colors with strong readability on light surfaces.
+- Keep color mapping stable: the same logical component/flow must keep the same color across node, connector, and connector label.
+- For subtypes within a flow, use close shades of the same family instead of unrelated hues.
 
 ### Default palette
 
-- Canvas / background: `#0b0f14`
-- Primary surface: `#111827`
-- Secondary surface: `#1f2937`
-- Primary text: `#e5e7eb`
-- Secondary text: `#9ca3af`
-- Primary accent: `#38bdf8`
-- Secondary accent: `#22c55e`
-- Warning / risk: `#f59e0b`
-- Error / destructive path: `#ef4444`
-- Border / connector default: `#475569`
+- Canvas / background: `#f8fafc`
+- Surface: `#ffffff`
+- Muted surface: `#f1f5f9`
+- Text: `#212529`
+- Muted text: `#343a40`
+- Green: `#099268`
+- Pink: `#c2255c`
+- Red: `#ff5d73`
+- Purple: `#6741d9`
+- Blue: `#1971c2`
+- Teal: `#0c8599`
+- Border / connector: `#868e96`
+
+### Extended accent set
+
+- Mint: `#12b886`
+- Cyan: `#1098ad`
+- Indigo: `#364fc7`
+- Violet: `#5f3dc4`
+- Magenta: `#a61e4d`
+- Rose: `#e64980`
+- Slate dark: `#212529`
+- Slate mid: `#495057`
+- Slate light: `#868e96`
 
 ## Layout
 
-- Always keep the layout spacious.
+- Keep the layout spacious.
 - Use consistent alignment and clear grouping.
-- Maintain obvious reading order: usually left-to-right or top-to-bottom.
+- Maintain obvious reading order (usually left-to-right or top-to-bottom).
 - Separate major groups with generous whitespace.
-- Avoid dense clusters, overlapping arrows, or labels squeezed into shapes.
+- Avoid dense clusters and unclear crossings.
 
 ### Spacing defaults
 
-- Between major groups: `120-180px`
-- Between related nodes: `48-72px`
-- Container padding: `24-32px`
-- Keep connector crossings rare. Re-route instead of stacking lines through the middle of the diagram.
+- Between major groups: `160-240px`
+- Between related nodes: `72-120px`
+- Container padding: `48-72px`
+- Keep connector crossings rare. Re-route instead of stacking lines through central content.
+
+### Connector label placement
+
+- Do not place connector labels directly on top of arrow/line strokes.
+- Offset connector labels from the path by at least `16-24px` on the normal axis.
+- Prefer labels slightly to the side of the connector midpoint, not centered on the stroke.
+- If lines still reduce readability, move the label further away.
+- Connector labels must remain clearly associated with their connector.
+- Connector endpoints should stop with a visible gap before node/container borders: `8-16px`.
+- Prefer slight natural curves for connectors (gentle 3-point bends) instead of rigid perfectly straight arrows.
+- Keep curvature subtle; avoid dramatic arcs unless the route needs explicit detouring.
+- Use straight connectors only when they are materially clearer than curved ones.
+
+### Container nesting
+
+- Default to one container level.
+- Maximum nesting depth is two.
+- Use second-level nesting only when needed.
+- Avoid box-within-box-within-box structures unless explicitly required.
+
+## Text fit and sizing
+
+Use explicit sizing so text fits without clipping or cramped boxes.
+
+### Typography defaults
+
+- Body/node text: `20px` Excalidraw monospace (`fontFamily: 3`)
+- Section labels: `24px`
+- Auxiliary notes: `20px` minimum
+- Line height multiplier: `1.25`
+
+### Text length and wrapping
+
+- Target max line length: `22-28` characters.
+- If label text exceeds `28` characters, insert line breaks at phrase boundaries.
+- Keep most labels to `1-2` lines.
+- Hard cap: `3` lines for standard nodes, `4` lines for large containers.
+
+### Box size contract
+
+- Horizontal text padding: `32px` per side (`64px` total)
+- Vertical text padding: `24px` per side (`48px` total)
+- Minimum node size: `260x120`
+- Recommended width bands:
+- Short labels (`<=18` chars): `260-320px`
+- Medium labels (`19-40` chars): `340-460px`
+- Long labels (wrapped): `480-680px`
+
+### Overflow guardrails
+
+- Text must remain fully inside its box at `zoom: 1`.
+- Keep at least `28px` interior clearance from text to borders after render.
+- If text would overflow: increase width first, then height, then split content into multiple nodes.
+- No label overlap is allowed.
+- Bias toward extra whitespace over dense packing.
 
 ## Structural guidance
 
-Pick a structure that matches the content.
+Pick the structure that matches the content.
 
-- For flows and request lifecycles: use a sequence or pipeline layout.
-- For layered systems: use stacked layers with strict boundaries.
-- For ownership and containment: use nested containers.
-- For stateful behavior: use a state-machine style layout.
-- For dependencies: use directional dependency graphs with grouping by subsystem.
-- For comparisons or migrations: use side-by-side before/after layouts.
+- Flows/lifecycles: sequence or pipeline layouts
+- Layered systems: stacked layers with strict boundaries
+- Ownership/containment: nested containers
+- Stateful behavior: state-machine style
+- Dependencies: directional graphs grouped by subsystem
+- Comparisons/migrations: side-by-side layouts
 
-Do not force every task into boxes with arrows.
-If the task is better represented as layers, phases, states, interfaces, call paths, or boundaries, use that structure instead.
+Do not force every task into boxes with arrows when a better structure exists.
 
 ## Logical coherence
 
-- Every element should have a reason to exist.
-- Group by actual system boundaries, not by visual symmetry alone.
-- Make relationships explicit: data flow, control flow, ownership, lifecycle, or dependency.
+- Every element must have a reason to exist.
+- Group by real system boundaries, not visual symmetry alone.
+- Make relationships explicit: data flow, control flow, ownership, lifecycle, dependency.
 - Minimize ambiguous arrows.
-- If a connection has a specific meaning, label it briefly.
-- Prefer fewer, clearer elements over exhaustive coverage.
+- If a connection has specific meaning, label it briefly.
+- Prefer fewer, clearer elements over exhaustive clutter.
 
 ## Language
 
 - Use terse, technical labels.
-- Assume the reader is a senior engineer maintaining personal notes.
-- Prefer precise nouns and verbs.
+- Use short phrases, not full sentences.
+- Assume the reader is a senior engineer.
+- Prefer concrete nouns/verbs.
 - Use concrete system terms: API, worker, queue, WAL, cache, AST, token, retry loop, reconciliation pass.
-- Keep text brief. Most labels should be one line.
 
 ### Avoid
 
 - Business speak
 - Marketing language
 - Vague labels like `Platform`, `Service Layer`, `System`, `Magic`
+- Ambiguous shorthand like `edge`, `core`, `backend`, `worker` without qualifiers
 - Filler phrases like `leverages`, `enables`, `streamlines`, `orchestrates`
 
+### Naming specificity
+
+- Prefer concrete component names over abstract layer names.
+- Label the actual technology/runtime boundary when known.
+- Example: use `caddy router` or `reverse proxy (caddy :80)` instead of `edge`.
+- Example: use `bun http api (:3000)` instead of `backend`.
+
 ## Visual style
 
 - Use subtle emphasis, not decoration.
 - Reserve accent colors for meaning, not aesthetics alone.
+- Keep color mapping stable for each logical subsystem/flow.
 - Use container fills and border weight to show hierarchy.
-- Keep shapes simple and consistent unless the task benefits from a different visual treatment.
-- Prefer readable structure over visual novelty, but avoid generic boilerplate layouts.
+- Keep shapes simple and consistent unless variation materially helps.
 
 ## Creativity rule
 
 Be creative in structure, not flashy in styling.
 
-- Adapt the composition to the problem.
+- Adapt composition to the specific problem.
 - Use framing, grouping, and flow intentionally.
-- Make the diagram feel specific to the task at hand.
-- Avoid producing the same generic flowchart structure for unrelated problems.
+- Make the diagram feel specific to the task.
+
+## Dark mode persistence
+
+- Treat dark mode as a persisted app-state requirement only.
+- At create/update time, `scene.appState.theme` must be `"dark"`.
+- Do not rely on UI defaults or post-hoc toggles.
+- Theme and element colors are separate controls:
+- `theme: "dark"` is required.
+- Keep element colors in a light-style palette.
+- Do not manually invert colors.
+- Do not use dark canvas/surface colors for theme compliance.
 
 ## Hard constraints
 
-- Always dark mode.
-- No bright or white backgrounds.
+- Always set `scene.appState.theme` to `"dark"`.
+- Always use light-mode element colors.
+- No manual color inversion.
+- Default to one container level; max two unless explicitly needed.
+- No tight text boxes.
 - No cluttered layouts.
 - No overlapping labels.
+- No label text with connector strokes running through glyphs.
+- No connector endpoint flush against a box border; keep a visible gap.
+- No inconsistent color mapping for the same logical subsystem/flow.
 - No decorative noise.
-- No business or management tone.
-- No generic one-size-fits-all flowchart if the task calls for a better structure.
+- No business/management tone.
+- No generic one-size-fits-all flowchart when a better structure is appropriate.