From 9475e0e1a4e2b90f22d6462a32a47449bd788418 Mon Sep 17 00:00:00 2001 From: acebear17 <121527825+acebear17@users.noreply.github.com> Date: Sun, 1 Nov 2026 02:27:40 +0000 Subject: [PATCH] Docs/design approach 10063 (#10409) * claim: #10063 * docs: add a design approach and workflows chapter to the user guide (#10063) Adds guide/design-approach.md after the window tour: the parametric idea, principles for designs that change well, the timeline and rollback marker, bodies vs components and occurrences, common workflows with links, a term map for users of other CAD software, and where to find help. * docs: match the chapter to the app's labels and sketch colours (#10063) Checked in the web app (0.29.0): the timeline strip is headed History, the toolbar shows New Sketch and Parameters for Create Sketch and Change Parameters, and fully constrained geometry turns white in the default dark theme rather than dark. * docs: tighten the design approach chapter's wording (#10063) The glossary covers most, not all, of the chapter's terms; Redo moves forward; the timeline is shown as the History strip; Report a bug drafts a report for the user to file and sends nothing itself. --- docs/book/src/SUMMARY.md | 1 + docs/book/src/guide/design-approach.md | 126 +++++++++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 docs/book/src/guide/design-approach.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index de0960efc..9f261a2fd 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 000000000..08931f95d --- /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).