feat: add a styles guide

STYLES_GUIDE.md

@@ -0,0 +1,109 @@
+# Styles Guide
+
+Use this guide when generating or modifying Excalidraw scenes.
+
+## Core intent
+
+- Always use dark mode.
+- 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.
+
+## Theme
+
+- Use a dark canvas and dark 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.
+
+### 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`
+
+## Layout
+
+- Always 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, overlapping arrows, or labels squeezed into shapes.
+
+### 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.
+
+## Structural guidance
+
+Pick a 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.
+
+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.
+
+## 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.
+- Minimize ambiguous arrows.
+- If a connection has a specific meaning, label it briefly.
+- Prefer fewer, clearer elements over exhaustive coverage.
+
+## Language
+
+- Use terse, technical labels.
+- Assume the reader is a senior engineer maintaining personal notes.
+- Prefer precise nouns and 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`
+- Filler phrases like `leverages`, `enables`, `streamlines`, `orchestrates`
+
+## Visual style
+
+- Use subtle emphasis, not decoration.
+- Reserve accent colors for meaning, not aesthetics alone.
+- 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.
+
+## Creativity rule
+
+Be creative in structure, not flashy in styling.
+
+- Adapt the composition to the 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.
+
+## Hard constraints
+
+- Always dark mode.
+- No bright or white backgrounds.
+- No cluttered layouts.
+- No overlapping labels.
+- No decorative noise.
+- No business or management tone.
+- No generic one-size-fits-all flowchart if the task calls for a better structure.