soldermaskdocs

design.json

A design is the circuit a board is built from: its parts, its nets and what the model assumed. The design model writes it, and you can write one yourself.

The command line reads one with --design. The app reads one with Open a file on the projects page, or Import a file in the workbench.

The MCP tools check a design against soldermask/schema.py, and no object in it may carry a field the schema does not name. The command line and the app read the file leniently, and refuse only what they cannot build.

{
  "summary": "5V to 3.3V LDO breakout with a power indicator LED.",
  "board": { "name": "ldo-breakout", "width_mm": 25, "height_mm": 20 },
  "components": [
    { "ref": "U1", "kind": "ic", "search": "AMS1117-3.3", "package": "SOT-223", "value": "3.3V", "purpose": "regulator" },
    { "ref": "C1", "kind": "capacitor", "search": "10uF ceramic", "package": "0805", "value": "10uF", "purpose": "input bulk" },
    { "ref": "D1", "kind": "led", "search": "green LED 0603", "package": "0603", "value": "green", "purpose": "power indicator" },
    { "ref": "R1", "kind": "resistor", "search": "1k resistor", "package": "0603", "value": "1k", "purpose": "LED current limit" },
    { "ref": "J1", "kind": "connector", "search": "2.54mm pin header 2 pin", "package": "HDR-1x2", "value": "", "purpose": "input" }
  ],
  "nets": [
    { "name": "GND", "kind": "ground", "voltage_v": 0, "current_a": null,
      "connections": [ { "ref": "U1", "pin": "GND" }, { "ref": "C1", "pin": "2" }, { "ref": "J1", "pin": "2" } ] },
    { "name": "VIN", "kind": "power", "voltage_v": 5, "current_a": 0.5,
      "connections": [ { "ref": "J1", "pin": "1" }, { "ref": "U1", "pin": "VI" }, { "ref": "C1", "pin": "1" } ] },
    { "name": "+3V3", "kind": "power", "connections": [ { "ref": "U1", "pin": "VO" }, { "ref": "R1", "pin": "1" } ] },
    { "name": "LED_K", "kind": "signal", "connections": [ { "ref": "R1", "pin": "2" }, { "ref": "D1", "pin": "1" } ] }
  ],
  "assumptions": [ "Input is 5V from the header." ],
  "decisions": [],
  "unsupported": []
}

Fields

FieldRules
summaryOne sentence
board.nameA short slug
board.width_mm, board.height_mmBetween 10 and 150
board.size_askedOptional. true when the prompt sets the size: dimensions, a form factor or an enclosure. The sizer then never cuts the board smaller.
components[].refUnique: R1, C1, U1, J1, D1, SW1
components[].kindic, module, resistor, capacitor, led, diode, transistor, connector, switch, crystal or inductor
components[].searchWhat to buy: a manufacturer part number if you are sure it exists, otherwise a short description. It is searched against the parts catalogue.
components[].packageOne of the supported packages, or FROM_PART
components[].lcscOptional. The LCSC code of the exact part to order, such as C6186.
components[].value10k, 100nF, or an empty string for parts without a value
components[].purposeWhy the part is on the board, in a few words
nets[].nameGND, +3V3, VBUS, SDA and so on
nets[].kindground, power or signal
nets[].voltage_vNominal volts against ground for a power or ground net. null for a signal, or when unknown.
nets[].current_aSteady amps a power net carries, or null
nets[].connectionsAt least two, each a ref and a pin
assumptions[]Choices the prompt did not specify
decisions[]At most two design choices, each with a question and 2 or 3 options of {label, detail, recommended}
unsupported[]What the prompt asked for that could not be done, and anything the model is unsure of. It is published with the board.

Notes on the fields that matter most:

  • module is a pre-built board, such as an ESP32 or another radio, a radar or a GPS. It gets the same rail, ground and decoupling checks as an ic.
  • search must name a part. A net name here finds nothing, and the part is dropped.
  • FROM_PART is for a part with no standard package. Its footprint and pin names then come from the vendor's CAD data, so search must name that exact part.
  • lcsc orders that code as chosen, without searching again. The default design backend, claude-code, may set it only to a code it looked up in the same turn. Any other code is removed before the build, and the build says which. The other backends never write it.
  • voltage_v feeds Ohm's law. Without it, the LED resistor, dissipation and capacitor rating checks cannot run.
  • current_a sets the track width (by IPC-2221) and the via count. Leave it null rather than guess: a null net routes at the board's signal track, 0.127 mm with Lightcycle or A*.
  • The heat check holds the copper to each declared current. A run whose rise reaches 20 °C is a gap, and a rise of 100 °C fails the board. See Copper too narrow for its current.
  • Differential pairs are found by net name, such as USB_DP and USB_DN, D+ and D-, or CANH and CANL. Each is laid as a pair. See Differential pairs.

Pin names

PartWhat pin holds
Two-terminal part1 or 2
Diode or LEDA for the anode, K for the cathode. The pad comes from the ordered part's own symbol. A bare 1 is read as the anode.
IC or moduleThe datasheet's function name, such as GND or VO. Never a pin number.
Multi-unit partThe unit and the pin, such as A.+ or B.-

constraints

The constraints block records what a person decided about their own board. The model never writes it.

{
  "constraints": {
    "pinned":   { "J1": { "x": 4.0, "y": 22.5, "rot": 90, "by": "human" } },
    "edges":    { "J1": "left" },
    "keepouts": [ { "x": 0, "y": 0, "w": 8, "h": 47, "why": "antenna" } ],
    "sheet":    { "U1": { "x": 2400, "y": 1800 } },
    "tracks":   [ { "net": "SDA", "layer": "F.Cu", "width": 0.25,
                    "pts": [[7.0, 6.0], [7.0, 12.0], [13.0, 18.0]], "by": "human" } ],
    "vias":     [ { "net": "SDA", "x": 13.0, "y": 18.0, "by": "human" } ],
    "wires":    { "SDA": -1350 },
    "rules":    { "min_track_mm": 1.0, "router": "krt", "seed": 3, "pour": false, "precedent": true, "mark": true },
    "board":    { "fixed": true, "sides": 1, "layers": 4 }
  }
}

Dragging a part on the board writes a pin here. It does not change board.json. The next build reads the pin, never moves that part, and places everything else around it.

Board positions are in mm with y up. Sheet positions are in mils.

KeyWhat it holdsRead by
pinnedPart → {x, y}, plus optional rot (0, 90, 180, 270), side (front or back) and by (human or import)The placer
edgesPart → left, right, top or bottom: a side decided, a position notThe placer
keepoutsRectangles {x, y, w, h} with an optional why. (x, y) is the lower-left corner.The placer, the router, the pour and the KiCad file
sheetPart → {x, y} on the schematic, plus optional rot and byThe schematic layout
tracksCopper you drew: net, layer (F.Cu or B.Cu), pts and an optional widthThe router
viasWhere your copper changes layer: net, x, yThe router
wiresNet → the y of its lane on the schematicThe schematic layout
rulesHow the board is built. See below.The whole build
boardfixed: true stops the board growing or being cut down. size sets how tight a roomy board is cut. sides: 1 keeps parts on one side. layers: 4 builds on four copper layers. mounting_holes drills holes at the corners.The placer and the router

What each one does:

  • pinned: a pinned part is never moved, turned, centred or seated at an edge. side: back mirrors the footprint onto the back copper, which is what F writes.
  • edges: the part is pulled to that edge, seated flush with it, and a connector opens off the board. A part not at its edge is a gap. See Parts at an edge you choose.
  • keepouts: no part goes on the rectangle, and no track, via, pad or pour goes there on any copper layer. A part left inside is a gap, and a pad inside fails the verdict. See Areas you keep clear. A module's antenna keepout comes from its footprint, not from here.
  • sheet: overrides the schematic's column layout for that symbol. The wires are redrawn around it.
  • tracks: handed to the router as copper it may not move. A track that stops short is a start: the router finishes the net around it. Without width, the net's own width is used.
  • vias: kept apart from tracks, because a via belongs to a net and a point, not to either track that meets it.
  • wires: stores the lane, not the drawn line. A lane still meets its pins after the next build moves a symbol.
  • board.fixed: fixes the size only. The parts still move. Use it for a board that must fit an enclosure or a mounting pattern.
  • board.mounting_holes: true for four M3, a count for that many M3, or {count, screw} with M2, M2.5, M3 or M4. false or 0 asks for none. One goes at each corner, two on a diagonal. See Mounting holes.
  • board.size: compact, balanced (the default) or roomy. A prompt that asks for a small or a roomy board sets it. See When the board is too big.
  • board.sides: the default, 2, lets the placer put out-of-reach surface-mount parts on the back when the front is full and the board cannot grow. A prompt that asks for one side sets sides: 1.
  • board.layers: 2, the default, or 4. Four layers are signal, ground plane, signal and signal. SOLDERMASK_PLANES=gnd+power makes the third a power plane instead. A prompt that asks for a four-layer board sets layers: 4. See Four layers.

rules

KeyValuesWhat it does
routerlightcycle (the default) or krtWhich router lays the copper first. See Choosing which goes first.
seed0 to 10000; 1 when unsetThe anneal seed. The same design, pins and seed give the same placement.
pourtrue (default) or falsefalse routes ground as tracks instead of pouring it
precedenttrue (default) or falsefalse stops a similar corpus board seeding the anneal. It is still listed.
marktrue (default) or falsefalse leaves the maker's mark off the silkscreen, the Gerber, the .kicad_pcb and the viewer
min_track_mmMore than 0, at most 5The narrowest track any routed net may use
  • router: if the router you name cannot run, the other routes the board and the gaps list says why. With neither installed, the board is placed and not routed.
  • An older design that names freerouting is still read. Lightcycle routes it, and the gaps say freerouting is retired.
  • min_track_mm can only widen a track. A net's width is the largest of the board's signal track, what IPC-2221 asks for its current, and this floor. So a rail that needs 1.4 mm still gets 1.4 mm under a 1.0 mm floor.
  • Over 5 mm, a track is really a plane: ask for a pour instead.

rules is where "make the traces wide enough to solder by hand" lands. It is a choice about how the board is built, so it is a constraint, not a design field.

The floor is not a DRC rule

The KiCad project's min_track_width stays at the fab's limit. Otherwise the pipeline's own thermal spokes would fail DRC. A net routed narrower than asked is reported by ses.width_report() instead.

How constraints are kept

  • The design schema does not contain this block, so a model cannot write it.
  • workspace.constrain() puts the project's own constraints over any design it is handed, whether from a fork, a file or a model. A file's block is kept only when the project has none.
  • It then adds what the prompt asks for: one side, four layers, a router, a board size or mounting holes.
  • A design with no constraints writes no constraints key.
  • A pin for a part the design no longer has is ignored.

On this page