Spec Style Guide

This document defines the structure every primitive / constraint / modify-op / workflow spec MUST follow. It exists so:

1. The reader scans 20 specs and finds the same information in the same place.
2. The author isn't paralysed by "what should I write?" — the template answers that.
3. We don't repeat OnShape/SolidWorks/COMSOL's mistake of "tree-of-menu-items" documentation. Each spec is behavior-first, not menu-first.

Tone: terse, declarative, technical. No marketing. Assume the reader is a commissioning engineer who has used at least one parametric CAD before. Two paragraphs of context max per section.

Length: aim for 1–2 pages rendered. If a section is huge, it's probably two features dressed as one.

File layout

docs/spec/
  SPEC-STYLE-GUIDE.md            ← you are here
  index.md                        ← entry point
  primitives/
    node.md
    segment.md
    arc.md
    circle.md
    spline.md
    rect.md
    polygon.md
    fillet.md
    crossing.md
    frame.md
  constraints/
    geometric.md                  ← single file with one section per kind
    dimensional.md
  modify/
    move.md
    rotate.md
    mirror.md
    copy-and-array.md
    trim.md
    delete.md
  workflow/
    motorscript.md
    parameters-and-smart-dim.md
    save-load-and-tabs.md
    selection-snapping-palette.md
  figures/                        ← captured screenshots later (PNG)

Required sections (per spec)

Every spec MUST have these 9 H2 sections in this order. If a section is genuinely N/A, write **N/A** and a one-line reason. Don't skip silently.

1. Identity

Single sentence. "A <feature> is …". Define the term so the rest of the spec doesn't equivocate.

2. When to use it

When does the user reach for this? 2-4 bullets. Concrete scenarios, not abstract capabilities.

3. Inputs

How does the user trigger this? List the surfaces:

• Tool button (which toolbar slot + icon)
• Keyboard shortcut (if wired — cross-check with Canvas/index.tsx tool dispatch around line 2716)
• MotorScript builtin (function signature)
• Command Palette (Cmd+K name)
• Context menu (if available)

If a surface isn't supported, list it as "not yet wired" so the gap is visible.

4. State machine

Numbered list. Each step:

• Click N / Action: what's required (a point in space? a snap target? a modifier key?)
• Preview after step N: what the user sees on canvas during this step (ephemeral rendering)
• Cancel options: what aborts mid-flow (Esc? right-click? another tool selection?)

Final step is always Finalize (Enter, right-click, or auto on Nth click — be explicit).

5. Committed state

After finalize, what's added to scene.geometry? Bullet list with exact types (cross-ref scene-model.ts interfaces). Include:

• New entities (Node[], Segment[], Spline[], RectFeature, etc.)
• Constraints auto-emitted (e.g. polygon creates equal + distance constraints)
• MotorScript statement(s) generated (reverse-codegen path) — cite the function in codegen.ts

6. Constraints / interactions

Which constraints does this primitive accept? Use a 2-column table:

Constraint	Behavior on this primitive
horizontal	applies to segment.n0—n1; locks y1=y0
...	...

Plus: what does this primitive do when participating in a fillet? a crossing? a trim? Cross-ref related primitives.

7. Failure modes

What does the editor do for degenerate input?

• Zero-length segment / coincident endpoints
• Collinear arc points
• Self-intersecting spline
• Empty selection on a tool that needs a selection
• Solver divergence with this primitive present

State the contract: what's the user-visible result (no-op? toast? red constraint pill? rollback)?

8. Figures

Markdown image placeholders with explicit captions. Authors don't take screenshots — they specify what to capture. Format:

![alt-text](../figures/<spec>-<n>.png)
*Figure N: <one-sentence description of what's in the frame>. Capture conditions: <empty scene, one segment AB at known coords, hover over feature X>.*

Conventions:

• One figure per state-machine step that's visually meaningful (don't capture identical-looking states).
• One figure for "committed final state".
• One figure for "with related constraints applied" if relevant.
• One figure for the failure-mode if visible (e.g., red conflict pill).
• Coordinates: use round numbers (0, 5, 10, etc.) so figures are reproducible.

Authors can use ASCII-art diagrams in place of figure placeholders for simple geometry when a real screenshot would be overkill:

   A•───────────•B       (after click 1, line preview from A to cursor)
   ╱
  ╳  cursor

9. Known bugs

List any known caveats or surface bugs that affect this feature, one bullet per item. If no bugs known: None known.

---

Cross-reference conventions

Link to source code: commands.ts:NN (file:line). Always prefer line refs over "search for X".

Link to other specs: relative path. [Segment](./segment.md), [horizontal constraint](../constraints/geometric.md#horizontal).

What NOT to include

• Marketing prose ("powerful", "intuitive", "industry-leading")
• Why we built it (history goes in commit messages, not spec)
• Roadmap / "coming soon" features (those go to index.md backlog)
• Comparison to other CAD tools (mention only where the behaviour intentionally mirrors a known precedent — e.g. "F3 toggles snap, Solvespace precedent")
• Code listings longer than 3 lines — link to the file:line instead

Author checklist (before commit)

• [ ] All 9 sections present (N/A where genuinely absent)
• [ ] Identity sentence is 1 sentence, not 3
• [ ] State machine numbered and every step has a "preview after" description
• [ ] At least 2 figure placeholders OR 1 ASCII diagram
• [ ] Every code reference is file:line
• [ ] No prose longer than the longest scientific paragraph in the doc
• [ ] Renders cleanly in GitHub markdown preview
• [ ] Adds an entry under index.md

---

End of style guide.