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
| Field | Rules |
|---|---|
summary | One sentence |
board.name | A short slug |
board.width_mm, board.height_mm | Between 10 and 150 |
board.size_asked | Optional. true when the prompt sets the size: dimensions, a form factor or an enclosure. The sizer then never cuts the board smaller. |
components[].ref | Unique: R1, C1, U1, J1, D1, SW1 |
components[].kind | ic, module, resistor, capacitor, led, diode, transistor, connector, switch, crystal or inductor |
components[].search | What to buy: a manufacturer part number if you are sure it exists, otherwise a short description. It is searched against the parts catalogue. |
components[].package | One of the supported packages, or FROM_PART |
components[].lcsc | Optional. The LCSC code of the exact part to order, such as C6186. |
components[].value | 10k, 100nF, or an empty string for parts without a value |
components[].purpose | Why the part is on the board, in a few words |
nets[].name | GND, +3V3, VBUS, SDA and so on |
nets[].kind | ground, power or signal |
nets[].voltage_v | Nominal volts against ground for a power or ground net. null for a signal, or when unknown. |
nets[].current_a | Steady amps a power net carries, or null |
nets[].connections | At 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:
moduleis 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 anic.searchmust name a part. A net name here finds nothing, and the part is dropped.FROM_PARTis for a part with no standard package. Its footprint and pin names then come from the vendor's CAD data, sosearchmust name that exact part.lcscorders 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_vfeeds Ohm's law. Without it, the LED resistor, dissipation and capacitor rating checks cannot run.current_asets the track width (by IPC-2221) and the via count. Leave itnullrather than guess: anullnet 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_DPandUSB_DN,D+andD-, orCANHandCANL. Each is laid as a pair. See Differential pairs.
Pin names
| Part | What pin holds |
|---|---|
| Two-terminal part | 1 or 2 |
| Diode or LED | A 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 module | The datasheet's function name, such as GND or VO. Never a pin number. |
| Multi-unit part | The 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.
| Key | What it holds | Read by |
|---|---|---|
pinned | Part → {x, y}, plus optional rot (0, 90, 180, 270), side (front or back) and by (human or import) | The placer |
edges | Part → left, right, top or bottom: a side decided, a position not | The placer |
keepouts | Rectangles {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 |
sheet | Part → {x, y} on the schematic, plus optional rot and by | The schematic layout |
tracks | Copper you drew: net, layer (F.Cu or B.Cu), pts and an optional width | The router |
vias | Where your copper changes layer: net, x, y | The router |
wires | Net → the y of its lane on the schematic | The schematic layout |
rules | How the board is built. See below. | The whole build |
board | fixed: 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: backmirrors 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. Withoutwidth, the net's own width is used.vias: kept apart fromtracks, 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:truefor four M3, a count for that many M3, or{count, screw}with M2, M2.5, M3 or M4.falseor0asks for none. One goes at each corner, two on a diagonal. See Mounting holes.board.size:compact,balanced(the default) orroomy. 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 setssides: 1.board.layers: 2, the default, or 4. Four layers are signal, ground plane, signal and signal.SOLDERMASK_PLANES=gnd+powermakes the third a power plane instead. A prompt that asks for a four-layer board setslayers: 4. See Four layers.
rules
| Key | Values | What it does |
|---|---|---|
router | lightcycle (the default) or krt | Which router lays the copper first. See Choosing which goes first. |
seed | 0 to 10000; 1 when unset | The anneal seed. The same design, pins and seed give the same placement. |
pour | true (default) or false | false routes ground as tracks instead of pouring it |
precedent | true (default) or false | false stops a similar corpus board seeding the anneal. It is still listed. |
mark | true (default) or false | false leaves the maker's mark off the silkscreen, the Gerber, the .kicad_pcb and the viewer |
min_track_mm | More than 0, at most 5 | The 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
freeroutingis still read. Lightcycle routes it, and the gaps say freerouting is retired. min_track_mmcan 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
constraintskey. - A pin for a part the design no longer has is ignored.