excalidraw-box
Code Issues

fix: style guide

Browse Source
This commit is contained in:
ruinivist
2026-05-31 15:49:46 +00:00
parent 0d9dd742b2
commit b3e79d839e
1 changed files with 151 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
STYLES_GUIDE.md
+151 -48
View File
@@ -2,108 +2,211 @@
Use this guide when generating or modifying Excalidraw scenes. 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 ## 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. - Optimize for clarity, technical precision, and fast visual parsing.
- Tailor the diagram structure to the task itself. Do not default to generic flowcharts. - Tailor structure to the problem. Do not default to generic flowcharts.
- Prefer diagrams that feel like working engineering notes, not slides or business documentation. - Prefer diagrams that look like working engineering notes, not slides.
## Theme ## 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. - 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 ### Default palette
- Canvas / background: `#0b0f14` - Canvas / background: `#f8fafc`
- Primary surface: `#111827` - Surface: `#ffffff`
- Secondary surface: `#1f2937` - Muted surface: `#f1f5f9`
- Primary text: `#e5e7eb` - Text: `#212529`
- Secondary text: `#9ca3af` - Muted text: `#343a40`
- Primary accent: `#38bdf8` - Green: `#099268`
- Secondary accent: `#22c55e` - Pink: `#c2255c`
- Warning / risk: `#f59e0b` - Red: `#ff5d73`
- Error / destructive path: `#ef4444` - Purple: `#6741d9`
- Border / connector default: `#475569` - 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 ## Layout
- Always keep the layout spacious. - Keep the layout spacious.
- Use consistent alignment and clear grouping. - 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. - Separate major groups with generous whitespace.
- Avoid dense clusters, overlapping arrows, or labels squeezed into shapes. - Avoid dense clusters and unclear crossings.
### Spacing defaults ### Spacing defaults
- Between major groups: `120-180px` - Between major groups: `160-240px`
- Between related nodes: `48-72px` - Between related nodes: `72-120px`
- Container padding: `24-32px` - Container padding: `48-72px`
- Keep connector crossings rare. Re-route instead of stacking lines through the middle of the diagram. - 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 ## 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. - Flows/lifecycles: sequence or pipeline layouts
- For layered systems: use stacked layers with strict boundaries. - Layered systems: stacked layers with strict boundaries
- For ownership and containment: use nested containers. - Ownership/containment: nested containers
- For stateful behavior: use a state-machine style layout. - Stateful behavior: state-machine style
- For dependencies: use directional dependency graphs with grouping by subsystem. - Dependencies: directional graphs grouped by subsystem
- For comparisons or migrations: use side-by-side before/after layouts. - Comparisons/migrations: side-by-side layouts
Do not force every task into boxes with arrows. Do not force every task into boxes with arrows when a better structure exists.
If the task is better represented as layers, phases, states, interfaces, call paths, or boundaries, use that structure instead.
## Logical coherence ## Logical coherence
- Every element should have a reason to exist. - Every element must have a reason to exist.
- Group by actual system boundaries, not by visual symmetry alone. - Group by real system boundaries, not visual symmetry alone.
- Make relationships explicit: data flow, control flow, ownership, lifecycle, or dependency. - Make relationships explicit: data flow, control flow, ownership, lifecycle, dependency.
- Minimize ambiguous arrows. - Minimize ambiguous arrows.
- If a connection has a specific meaning, label it briefly. - If a connection has specific meaning, label it briefly.
- Prefer fewer, clearer elements over exhaustive coverage. - Prefer fewer, clearer elements over exhaustive clutter.
## Language ## Language
- Use terse, technical labels. - Use terse, technical labels.
- Assume the reader is a senior engineer maintaining personal notes. - Use short phrases, not full sentences.
- Prefer precise nouns and verbs. - 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. - 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 ### Avoid
- Business speak - Business speak
- Marketing language - Marketing language
- Vague labels like `Platform`, `Service Layer`, `System`, `Magic` - Vague labels like `Platform`, `Service Layer`, `System`, `Magic`
- Ambiguous shorthand like `edge`, `core`, `backend`, `worker` without qualifiers
- Filler phrases like `leverages`, `enables`, `streamlines`, `orchestrates` - 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 ## Visual style
- Use subtle emphasis, not decoration. - Use subtle emphasis, not decoration.
- Reserve accent colors for meaning, not aesthetics alone. - 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. - Use container fills and border weight to show hierarchy.
- Keep shapes simple and consistent unless the task benefits from a different visual treatment. - Keep shapes simple and consistent unless variation materially helps.
- Prefer readable structure over visual novelty, but avoid generic boilerplate layouts.
## Creativity rule ## Creativity rule
Be creative in structure, not flashy in styling. 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. - Use framing, grouping, and flow intentionally.
- Make the diagram feel specific to the task at hand. - Make the diagram feel specific to the task.
- Avoid producing the same generic flowchart structure for unrelated problems.
## 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 ## Hard constraints
- Always dark mode. - Always set `scene.appState.theme` to `"dark"`.
- No bright or white backgrounds. - 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 cluttered layouts.
- No overlapping labels. - 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 decorative noise.
- No business or management tone. - No business/management tone.
- No generic one-size-fits-all flowchart if the task calls for a better structure. - No generic one-size-fits-all flowchart when a better structure is appropriate.