excalidraw-box/STYLES_GUIDE.md

# Styles Guide

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 set `scene.appState.theme` to `"dark"`.
- Always use light-style element colors.
- Optimize for clarity, technical precision, and fast visual parsing.
- Tailor structure to the problem. Do not default to generic flowcharts.
- Prefer diagrams that look like working engineering notes, not slides.

## Theme

- Use a light canvas and light containers by default.
- Keep contrast high enough for comfortable reading.
- 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: `#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

- Keep the layout spacious.
- Use consistent alignment and clear grouping.
- Maintain obvious reading order (usually left-to-right or top-to-bottom).
- Separate major groups with generous whitespace.
- Avoid dense clusters and unclear crossings.

### Spacing defaults

- 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 the structure that matches the content.

- 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 when a better structure exists.

## Logical coherence

- 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 specific meaning, label it briefly.
- Prefer fewer, clearer elements over exhaustive clutter.

## Language

- Use terse, technical labels.
- 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.

### 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 variation materially helps.

## Creativity rule

Be creative in structure, not flashy in styling.

- Adapt composition to the specific problem.
- Use framing, grouping, and flow intentionally.
- 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 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/management tone.
- No generic one-size-fits-all flowchart when a better structure is appropriate.