Board as code

A complete board written as code: netlist assertions, ERC and DRC, and a rendered board, with no fabricator and no programmer required.

This is a circuit design spec on Spekkr, published by onyx. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
onyx/board-as-code
Version
0.2.0
Published by
onyx
Updated
14 Nov 2026

Build this spec

Build the spec at https://spekkr.com/onyx/board-as-code/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by onyx.

What does the result look like?

Board as code: hero

What can I customize?

Toolchain kicad uses KiCad files generated from code. code-first uses a named board-as-code tool that still emits a netlist and a PCB the checks can read.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance checks.

    Board as code

    What this builds

    A complete, original board described in code: a schematic or netlist, a layout, silkscreen, and a bill of parts. Tests assert a netlist (named nets are connected as in a file), run ERC and DRC with a documented rule set, and render the board. No fabricator, no assembler, and no programmer are required. This is not a copy of a commercial product's board.

    Read spekkr.inputs.json first. title is in the title block. width and height size the outline. usb and mounts add features. tool is the toolchain.

    Out of scope

    • A board house, a parts order, or a programmer in the checks.
    • A certified radio or a mains-voltage design.
    • A live parts-shop API in the checks.

    Requirements

    Each requirement has an id. Checks name the id they cover.

    R1. Netlist and ERC
    • The generated netlist contains the nets in fixtures/board-nets.json (for example VCC, GND, a signal list). Named pins are on the named nets.
    • ERC is clean for the rule set in the file, or only the documented waived classes remain.
    • If usb is on, the connector's power and ground pins are on VCC and GND as in the file.

    Accept when: every listed pin-to-net assertion holds, and ERC matches the expected clean or waived result.

    R2. Layout, DRC, renders
    • The board outline is width by height within 0.1 mm. If mounts is on, four M3 holes sit at the inset in the file.
    • DRC is clean for the rule set (clearance, track width, drill) in the file, or only documented waivers remain.
    • Renders: schematic (or a netlist plot), front copper and silk, back, and a 3D or isometric view. One command generates, checks, and writes the renders. No fabricator.

    Accept when: outline and holes match, DRC matches, the four renders are written, and a deliberate short in a fixture netlist fails ERC.

    R3. Inputs
    • Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built.
    • Options turn the optional circuits, ports or features in the Inputs table on or off.

    Accept when: an illegal input is refused by name, and the default input set produces the measurements in design.md.

    R4. Checks and report
    • One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md.
    • The command works without a physical board, a lab instrument or a network.

    Accept when: the command passes at the defaults, and fails if a documented value in the netlist or the ROM is corrupted on purpose.

    Verification

    Netlist assertions, ERC, and DRC are run on a board generated from code. The outline and mounting holes are measured. Board renders are written. A deliberate short fails ERC. No fabricator, no parts order, and no programmer are required.

    Definition of done

    • Every acceptance check above runs from one command, and all pass at the person's inputs.
    • A README says how to generate the board, how to run ERC and DRC, and that a fabrication is optional.
    # Board as code
    
    ## What this builds
    
    A complete, original board described in code: a schematic or netlist, a
    layout, silkscreen, and a bill of parts. Tests assert a netlist (named
    nets are connected as in a file), run ERC and DRC with a documented rule
    set, and render the board. No fabricator, no assembler, and no programmer
    are required. This is not a copy of a commercial product's board.
    
    Read `spekkr.inputs.json` first. `title` is in the title block. `width`
    and `height` size the outline. `usb` and `mounts` add features. `tool` is
    the toolchain.
    
    ## Out of scope
    
    - A board house, a parts order, or a programmer in the checks.
    - A certified radio or a mains-voltage design.
    - A live parts-shop API in the checks.
    
    ## Requirements
    
    Each requirement has an id. Checks name the id they cover.
    
    ### R1. Netlist and ERC
    
    - The generated netlist contains the nets in `fixtures/board-nets.json`
      (for example VCC, GND, a signal list). Named pins are on the named nets.
    - ERC is clean for the rule set in the file, or only the documented waived
      classes remain.
    - If `usb` is on, the connector's power and ground pins are on VCC and GND
      as in the file.
    
    Accept when: every listed pin-to-net assertion holds, and ERC matches the
    expected clean or waived result.
    
    ### R2. Layout, DRC, renders
    
    - The board outline is `width` by `height` within 0.1 mm. If `mounts` is
      on, four M3 holes sit at the inset in the file.
    - DRC is clean for the rule set (clearance, track width, drill) in the
      file, or only documented waivers remain.
    - Renders: schematic (or a netlist plot), front copper and silk, back, and
      a 3D or isometric view. One command generates, checks, and writes the
      renders. No fabricator.
    
    Accept when: outline and holes match, DRC matches, the four renders are
    written, and a deliberate short in a fixture netlist fails ERC.
    
    ### R3. Inputs
    
    - Inputs are read from `spekkr.inputs.json`. Values outside the ranges or
      choices in `design.md` are refused before a netlist, a board or a
      testbench is built.
    - Options turn the optional circuits, ports or features in the Inputs
      table on or off.
    
    Accept when: an illegal input is refused by name, and the default input
    set produces the measurements in `design.md`.
    
    ### R4. Checks and report
    
    - One command runs the simulation or the testbench, writes the plots or
      dumps, and compares them to the numbers in `design.md`.
    - The command works without a physical board, a lab instrument or a
      network.
    
    Accept when: the command passes at the defaults, and fails if a documented
    value in the netlist or the ROM is corrupted on purpose.
    
    ## Verification
    
    Netlist assertions, ERC, and DRC are run on a board generated from code.
    The outline and mounting holes are measured. Board renders are written. A
    deliberate short fails ERC. No fabricator, no parts order, and no
    programmer are required.
    
    ## Definition of done
    
    - Every acceptance check above runs from one command, and all pass at the
      person's inputs.
    - A README says how to generate the board, how to run ERC and DRC, and
      that a fabrication is optional.
    

    Open spec.md as plain text

  • design.md Netlist assertions, ERC/DRC rule sets, and board-outline measures.

    Design

    This file fixes the circuits, the timings and the dumps a build must match. The toolchain can vary, as long as the numbers here hold.

    Nets

    The file lists every required net and the pins that must be on it. USB-C, if on, follows the documented power pins only (no high-speed requirement in this version).

    Rules

    ERC and DRC rule files (or a KiCad design-rule set) are shipped. Waivers, if any, are listed by code.

    Outline

    Origin and mounting inset (4 mm from two edges, or as in the file) are fixtures/board-outline.json.

    Inputs

    KeyLabelDefaultNotes
    titleBoard titleA small instrumentDrawn in the silkscreen title block.
    widthBoard width, mm80From 40 to 160.
    heightBoard height, mm50From 30 to 120.
    usbA USB-C power inputonA documented connector and a simple protection network.
    mountsMounting holesonFour holes, M3, at the documented inset.
    toolToolchainkicadkicad uses KiCad files generated from code. code-first uses a named board-as-code tool that still emits a netlist and a PCB the checks can read.

    Acceptance at the defaults

    Millimetres and nets. Default board 80 × 50, two layers, USB-C power and four M3 mounts on. The board is generated from code.

    QuantityValueToleranceSource
    Board size80.00 × 50.000.05Outline
    Thickness1.600.05A 1.6 mm two-layer stack
    Mounting holes4 × M3, inset 3.5 from corners0.10When mounts is on
    USB-C cutout width9.000.10When usb is on
    Minimum copper clearance, track0.20, 0.250.02Except a documented pour neck

    A snapshot of the generated board (SVG or KiCad) is compared to a golden for the default inputs. ERC is clean aside from a documented list. No board house and no physical board are required.

    Screenshots

    These pictures are a board generated from the reference script in reference/board.py, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel.

    FileWhat it shows
    shots/board.pngBoard 80 × 50 mm, two layers, USB-C and four M3 mounts

    How to verify

    1. Run the simulation or the HDL testbench at the defaults, with no physical board.
    2. Compare periods, trip points, register dumps or frames to the acceptance table in this file.
    3. Corrupt one documented value on purpose and confirm the check fails.
    4. Netlist assertions, ERC, and DRC are run on a board generated from code. The outline and mounting holes are measured. Board renders are written. A deliberate short fails ERC. No fabricator, no parts order, and no programmer are required.
    # Design
    
    This file fixes the circuits, the timings and the dumps a build must
    match. The toolchain can vary, as long as the numbers here hold.
    
    ## Nets
    
    The file lists every required net and the pins that must be on it. USB-C,
    if on, follows the documented power pins only (no high-speed requirement
    in this version).
    
    ## Rules
    
    ERC and DRC rule files (or a KiCad design-rule set) are shipped. Waivers,
    if any, are listed by code.
    
    ## Outline
    
    Origin and mounting inset (4 mm from two edges, or as in the file) are
    `fixtures/board-outline.json`.
    
    ## Inputs
    
    | Key | Label | Default | Notes |
    | --- | --- | --- | --- |
    | `title` | Board title | A small instrument | Drawn in the silkscreen title block. |
    | `width` | Board width, mm | 80 | From 40 to 160. |
    | `height` | Board height, mm | 50 | From 30 to 120. |
    | `usb` | A USB-C power input | on | A documented connector and a simple protection network. |
    | `mounts` | Mounting holes | on | Four holes, M3, at the documented inset. |
    | `tool` | Toolchain | kicad | kicad uses KiCad files generated from code. code-first uses a named board-as-code tool that still emits a netlist and a PCB the checks can read. |
    
    ## Acceptance at the defaults
    
    Millimetres and nets. Default board 80 × 50, two layers, USB-C power and
    four M3 mounts on. The board is generated from code.
    
    | Quantity | Value | Tolerance | Source |
    | --- | --- | --- | --- |
    | Board size | 80.00 × 50.00 | 0.05 | Outline |
    | Thickness | 1.60 | 0.05 | A 1.6 mm two-layer stack |
    | Mounting holes | 4 × M3, inset 3.5 from corners | 0.10 | When `mounts` is on |
    | USB-C cutout width | 9.00 | 0.10 | When `usb` is on |
    | Minimum copper clearance, track | 0.20, 0.25 | 0.02 | Except a documented pour neck |
    
    A snapshot of the generated board (SVG or KiCad) is compared to a golden
    for the default inputs. ERC is clean aside from a documented list. No
    board house and no physical board are required.
    
    ## Screenshots
    
    These pictures are a board generated from the reference script in `reference/board.py`, at the default inputs. They are not drawings of a
    product that has not been built or simulated. The first picture is the one Spekkr
    shows on the spec's card. A build may ship its own goldens; those goldens
    are of that build and do not have to match these frames pixel-for-pixel.
    
    | File | What it shows |
    | --- | --- |
    | `shots/board.png` | Board  80 × 50 mm, two layers, USB-C and four M3 mounts |
    
    
    ## How to verify
    
    1. Run the simulation or the HDL testbench at the defaults, with no
    physical board.
    
    2. Compare periods, trip points, register dumps or frames to the
    acceptance table in this file.
    
    3. Corrupt one documented value on purpose and confirm the check fails.
    
    4. Netlist assertions, ERC, and DRC are run on a board generated from
    code. The outline and mounting holes are measured. Board renders are
    written. A deliberate short fails ERC. No fabricator, no parts order, and
    no programmer are required.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Install the simulator or the HDL toolchain named in design.md (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read the inputs into one place. Check: a trivial netlist or testbench runs and writes a file.
    2. Netlist and ERC (R1). Build what R1. Netlist and ERC asks for, to the numbers in design.md. In particular: The generated netlist contains the nets in fixtures/board-nets.json (for example VCC, GND, a signal list). Named pins are on the named nets. Check: the R1. Netlist and ERC acceptance checks pass.
    3. Layout, DRC, renders (R2). Build what R2. Layout, DRC, renders asks for, to the numbers in design.md. In particular: The board outline is width by height within 0.1 mm. If mounts is on, four M3 holes sit at the inset in the file. Check: the R2. Layout, DRC, renders acceptance checks pass.
    4. Inputs (R3). Build what R3. Inputs asks for, to the numbers in design.md. In particular: Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built. Check: the R3. Inputs acceptance checks pass.
    5. Checks and report (R4). Build what R4. Checks and report asks for, to the numbers in design.md. In particular: One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md. Check: the R4. Checks and report acceptance checks pass.
    6. Plots, dumps and goldens. Write the plots or framebuffer dumps named in design.md and compare them to the tables there. Check: every documented period, trip point, opcode or frame matches, within the stated tolerance.
    7. Finish. Write a README that says how to install what is needed, how to change the inputs, and how to run the checks. Run the one command from a clean folder. Check: every item under Definition of done in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Install the simulator or the HDL toolchain named in
    `design.md` (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read
    the inputs into one place.
       Check: a trivial netlist or testbench runs and writes a file.
    
    2. **Netlist and ERC (R1).** Build what `R1. Netlist and ERC` asks for, to
    the numbers in `design.md`. In particular: The generated netlist contains
    the nets in `fixtures/board-nets.json` (for example VCC, GND, a signal
    list). Named pins are on the named nets.
       Check: the `R1. Netlist and ERC` acceptance checks pass.
    
    3. **Layout, DRC, renders (R2).** Build what `R2. Layout, DRC, renders`
    asks for, to the numbers in `design.md`. In particular: The board outline
    is `width` by `height` within 0.1 mm. If `mounts` is on, four M3 holes sit
    at the inset in the file.
       Check: the `R2. Layout, DRC, renders` acceptance checks pass.
    
    4. **Inputs (R3).** Build what `R3. Inputs` asks for, to the numbers in
    `design.md`. In particular: Inputs are read from `spekkr.inputs.json`.
    Values outside the ranges or choices in `design.md` are refused before a
    netlist, a board or a testbench is built.
       Check: the `R3. Inputs` acceptance checks pass.
    
    5. **Checks and report (R4).** Build what `R4. Checks and report` asks
    for, to the numbers in `design.md`. In particular: One command runs the
    simulation or the testbench, writes the plots or dumps, and compares them
    to the numbers in `design.md`.
       Check: the `R4. Checks and report` acceptance checks pass.
    
    6. **Plots, dumps and goldens.** Write the plots or framebuffer dumps
    named in `design.md` and compare them to the tables there.
       Check: every documented period, trip point, opcode or frame matches,
    within the stated tolerance.
    
    7. **Finish.** Write a README that says how to install what is needed, how
    to change the inputs, and how to run the checks. Run the one command from
    a clean folder.
       Check: every item under Definition of done in `spec.md` is true.
    

    Open tasks.md as plain text

  • reference/board.svg A reference outline of the default 80 × 50 mm board. A build should generate KiCad or SVG from code.
  • reference/preview.html A working reference preview of the default view, used to make the listing pictures. A build does not have to start from this file.
  • reference/fonts/fonts.css Webfont faces for the reference preview.
  • reference/fonts/Geist.ttf Geist variable typeface for the reference preview.
  • reference/fonts/GeistMono.ttf Geist Mono variable typeface for the reference preview.
  • reference/fonts/Fraunces.ttf Fraunces variable typeface for the reference preview.
  • reference/fonts/Fraunces-Italic.ttf Fraunces italic variable typeface for the reference preview.

Is it for me?

Tools
KiCad, Python

What does it need?

Agent permissions
shell
Commands it runs
install KiCad or a board-as-code toolchain that can run ERC and DRC install a tool that can render a board view

What changed?

  • 0.2.014 Nov 2026Polished reference preview and new listing shots, including a short loop.
  • 0.1.014 Nov 2026First version.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.