Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Docs/design approach 10063 (#10409)

acebear179475e0e1a4e2
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index de0960efcd..9f261a2fd1 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -6,6 +6,7 @@
- [Getting started](guide/getting-started.md)
- [A tour of the window](guide/ui-tour.md)
+- [How a design is built](guide/design-approach.md)
- [Sketching and constraints](guide/sketching.md)
- [Equation curves](guide/equation-curves.md)
- [Solid features](guide/features.md)
diff --git a/docs/book/src/guide/design-approach.md b/docs/book/src/guide/design-approach.md
new file mode 100644
index 0000000000..08931f95d9
--- /dev/null
+++ b/docs/book/src/guide/design-approach.md
@@ -0,0 +1,126 @@
+# How a design is built
+
+SolidCraft is a parametric, history-based modeller. You don't shape geometry directly: you
+describe the steps that make it, and SolidCraft computes the result from those steps. Change a
+step or a value and everything after it is computed again. This page explains that idea and the
+usual ways of working with it. The pages after it cover each tool in detail; the
+[glossary](../reference/glossary.md) defines most of the terms used here.
+
+## The idea in one paragraph
+
+A **design** holds a **timeline**: an ordered list of **features**. Most parts start with a
+**sketch**, a 2D drawing on a plane, held in shape by **constraints** and **dimensions**. A
+feature such as Extrude or Revolve turns the sketch's closed regions into a solid **body**; later
+features add to it, cut into it or finish it (holes, fillets, shells). Every dimension and feature
+input is a **parameter**, so a size can be changed at any time, and the timeline rebuilds from the
+first feature that uses it.
+
+```text
+sketch (plane + constraints + dimensions)
+ └─ feature (extrude, revolve, …) → body
+ └─ more features (holes, fillets, patterns, shell, …)
+ └─ change a parameter → the timeline rebuilds
+```
+
+## Principles that make a design easy to change
+
+- **Capture intent, not just shape.** A hole "centred on the face" or "10 mm from that edge" stays
+ right when the part grows; a hole placed by eye doesn't. Use constraints and dimensions for what
+ matters, and name the important values as parameters (type `width = 40` in any value box: see
+ [Parameters and expressions](parameters.md)).
+- **Fully constrain sketches.** Under-constrained sketch geometry is drawn blue and the Sketch
+ Palette shows how many degrees of freedom are left; once none are, the geometry changes colour
+ (white in the default dark theme) and the status reads **Fully constrained** (see
+ [Sketching and constraints](sketching.md)). A fully constrained sketch changes only the way you
+ tell it to.
+- **Keep sketches simple, let features do the work.** A rectangle and an extrude, then a fillet, is
+ easier to change than one sketch that draws the rounded outline. Holes, patterns, mirrors,
+ fillets and chamfers are features of their own for the same reason.
+- **Build in a sensible order.** The base shape first, then the features that add and cut, then
+ the finishing features (fillets, chamfers, shell, draft). Features depend on the ones before
+ them, so an early change ripples forward.
+- **Sketch on stable references.** An origin plane (XY, XZ, YZ, or Top, Front, Right) or a
+ construction plane changes less than a face that a later edit may remove.
+
+## The timeline is the design
+
+The [timeline](ui-tour.md), the **History** strip along the bottom of the window, lists every
+feature in the order it is computed. Each feature can be edited (double-click), suppressed,
+renamed, reordered when nothing it depends on moves after it, and deleted; deleting asks first
+when other features depend on it.
+
+Drag the **rollback marker** back to see the design as it was at an earlier step. Features after
+the marker are kept, not deleted, and a new feature is added at the marker. This is how you add
+something early in the design (a sketch the later features should use) without rebuilding the rest.
+
+The timeline is not the undo history: Undo and Redo move back and forth through what you did; the
+timeline is what the design is made of.
+
+## Bodies and components
+
+A **body** is one connected solid or surface shape. A design can hold many bodies, and features
+can make a new body, join or cut existing ones, or intersect them.
+
+A **component** groups bodies, sketches and construction geometry, with its own origin, and can be
+placed more than once; each placement is an **occurrence**. Editing a component changes every
+occurrence of it; moving an occurrence moves only that copy. The **active component** (the radio
+button in the [browser](ui-tour.md)) receives new sketches and features.
+
+Two ways of working follow from this:
+
+- **One part, several bodies.** For a single part, or a few parts that are designed against each
+ other, model bodies in one design. Bodies are quick to make and to combine, split or cut with each
+ other.
+- **Components and joints.** When parts are separate pieces (they move, repeat, or go on a bill of
+ materials), make them components: **New Component**, or **Create Components from Bodies** to turn
+ bodies you already modelled into components. Then connect them with **joints** (rigid, revolute,
+ slider, cylindrical, pin-slot, planar, ball) and drive the motion. See
+ [Components and joints](assemblies.md).
+
+Starting with bodies and turning them into components later is a common path: it keeps the early
+design quick and makes the assembly when its structure is clear.
+
+## Common workflows
+
+| You want to | Start with | Read |
+|---|---|---|
+| Model a part from scratch | **New Sketch** (Create Sketch) on an origin plane, constrain and dimension it, Extrude or Revolve | [Sketching](sketching.md), [Solid features](features.md) |
+| Make a design you can resize | User parameters, added with **Parameters** (Change Parameters), used in sketch dimensions and feature inputs | [Parameters and expressions](parameters.md) |
+| Build an assembly | Bodies turned into components, or New Component, then joints | [Components and joints](assemblies.md) |
+| Design a bent sheet part | A base flange from a sketch, then flanges, hems and folds under a sheet metal rule | [Sheet metal](sheet-metal.md) |
+| Design a plastic enclosure | A shelled body, then bosses, lip and groove, snap fits, ribs | [Plastic parts](plastic.md) |
+| Work on a part from another program | Open a STEP, IGES, 3MF, STL or OBJ file as a new design | [Import and export](files.md) |
+| Script a design or hand it to an agent | Commands in a script for `solidcraft-cli`, or the MCP server | [Getting started](getting-started.md#cli), [MCP](mcp.md) |
+
+Everything you click is a **command** with named parameters, and the toolbar, scripts, the CLI and
+AI agents all run the same commands. A design built in the window can be turned into a script with
+`solidcraft-cli script`, which rebuilds it without the window (designs with components or joints
+are not supported there yet).
+
+## Terms if you come from another CAD program
+
+Other programs use other words for the same ideas. SolidCraft uses one term for each:
+
+| SolidCraft | You may know it as |
+|---|---|
+| timeline (shown as the History strip) | history, feature tree |
+| rollback marker | rollback bar, end-of-part marker |
+| browser | model tree, feature tree, design tree |
+| body | solid body, surface body |
+| component | part, sub-assembly |
+| occurrence | instance, component instance |
+| design | document, model, part file, assembly file |
+
+The full list, with what each term must not be confused with, is in the
+[glossary](../reference/glossary.md).
+
+## Finding help
+
+- **Help (?) › Documentation** in the title bar opens this manual.
+- **Help (?) › Keyboard Shortcuts** lists the shortcuts; see also
+ [Keyboard shortcuts](shortcuts.md).
+- The [command reference](../reference/commands.md) describes every command and its parameters.
+- **Report a bug**, in the title bar, drafts an issue report with the details the maintainers
+ need, for you to review and file on GitHub; the app doesn't send anything itself.
+- Questions and ideas: the [Discord](https://discord.gg/FtU4NQNVDH) and the
+ [issue tracker](https://github.com/tangency-labs/solidcraft/issues).