---

name: electrical-engineering
description: >
Conventions, defaults, and domain knowledge that electrical
engineers care about — especially in a PCB / hardware-design
context. Read before designing any UI, CLI, or file format that
touches PCB dimensions, trace specs, datasheets, fabrication
files, or EE terminology. The Adom ecosystem is
EE-centric — defaults, unit choices, labels, and vocabulary
should feel native to someone who lives in datasheets.
Trigger words: electrical engineering, EE, PCB, trace width,
clearance, mils, mm, imperial, metric, tscircuit, kicad, fusion
electronics, datasheet, component, copper weight, ohms, stackup,
DRC, BOM, gerber, CPL, pick and place, JLCPCB, Mouser, DigiKey,
silkscreen, pad, via, drill, stencil, reflow.

Electrical Engineering Conventions

Defaults, naming, and domain knowledge for tools / UIs that will be
used by EEs. Getting these right makes Adom tools feel NATIVE to an
engineer who lives in datasheets. Getting them wrong flags the tool
as "clearly not built by someone who does this for a living."

---

1. Units

1a. Primary metric (mm), secondary always available in mils + inches

PCB work in North America is a hybrid world:

• Mechanical / board outline / component dimensions: metric (mm)
  is the standard. tscircuit, KiCad, and Fusion Electronics all
  default to mm.
• Trace widths, pad dimensions, clearances, drill sizes: still
  commonly spec'd in mils (thousandths of an inch). A 10 mil
  trace, a 6 mil / 6 mil trace/space spec, a 0.8 mm pitch BGA with
  31.5 mil pad diameter. Datasheets mix the two all day long.
• Inches: used occasionally for board-level mechanical refs
  (e.g. "fits in a 2-inch enclosure").

In any measurement UI / report / CLI output: primary in mm,
SECONDARY UNITS DEFAULT TO MILS, not "None". Showing the mil
conversion in brackets after every mm value ("2.54 mm (100 mil)") is
non-negotiable polish — American EEs mentally translate the mil
number faster than the mm one, and hiding it adds friction.

Conversion: 1 mil = 0.0254 mm (exactly). Multiply mm by 39.37 to
get mils, divide mils by 39.37 to get mm.

Other useful conversions:

• 1 inch = 25.4 mm = 1000 mils
• 0.1" pitch (common through-hole) = 2.54 mm = 100 mil
• 0.05" pitch = 1.27 mm = 50 mil
• 0.8 mm pitch BGA = 31.5 mil
• 0.5 mm pitch QFP = 19.7 mil

1b. Precision

PCB feature precision scales with the feature type:

Feature	Typical precision
Board dimensions	0.1 mm (~4 mil)
Component placement	0.01 mm (~0.4 mil)
Trace width	0.01 mm or 0.5 mil
Pad dimensions	0.01 mm
Drill sizes	0.05 mm or 1 mil

Show 3 decimal places of mm by default in measurement UIs (equivalent
to 1 mil). User can dial up or down via a precision selector.

---

2. Silkscreen conventions

• Silkscreen must be white (top) and black or off-white on
  a black solder-mask (bottom). Other colours look wrong and cause
  contrast-against-mask problems with fab.
• Minimum text height: 0.8 mm (32 mil) for most fab houses, 1.0
  mm (40 mil) to be safe. Smaller than that and JLCPCB will reject
  the design.
• Line width: 0.15 mm (6 mil) minimum; 0.2 mm (8 mil) safer.
• Reference designators (U1, C3, R_REF): ALWAYS include
  them on the silkscreen next to every component. Engineers debug
  by these references; a board without them is ungoogleable at the
  bench.
• Test points get silk labels: the signal name, not the TP
  number (SCK, MISO, not TP3).

---

3. Reference designator conventions

Prefix	Kind
U	IC / chip (semiconductor with >2 pins)
Q	Transistor (single transistor, BJT or MOSFET)
D	Diode (incl. LED, Zener, Schottky)
R	Resistor
C	Capacitor
L	Inductor
Y, X	Crystal / oscillator
J, P	Connector (J for receptacle/jack, P for plug)
SW, S	Switch
BT	Battery
F	Fuse
FB	Ferrite bead
MP	Mounting post / mechanical part
TP	Test point
MC	Machine contact (Adom Molecule convention)
JP	Jumper / solder bridge
AE	Antenna

Follow this in any auto-naming, validation, or search the tool does.
When a tscircuit GLB mesh is named Box0 but we need to report it
human-readably, walk the ref-designator map from circuit.json
(source_component.name) and use THAT, not the mesh name.

---

4. Common chip packages / sizes

When a UI needs to describe a chip package visually or validate
footprint choice:

Package	Pin pitch	Typical pin count	Body
0201	—	2	0.6 × 0.3 mm
0402	—	2	1.0 × 0.5 mm
0603	—	2	1.6 × 0.8 mm
0805	—	2	2.0 × 1.25 mm
1206	—	2	3.2 × 1.6 mm
SOT-23	0.95 mm	3	2.9 × 1.3 mm
SOT-23-5	0.95 mm	5	2.9 × 1.6 mm
SOIC-8	1.27 mm	8	5.0 × 4.0 mm
SOIC-14	1.27 mm	14	8.7 × 4.0 mm
SSOP-20	0.65 mm	20	7.2 × 5.3 mm
TSSOP-20	0.65 mm	20	6.5 × 4.4 mm
QFN-32	0.5 mm	32	5 × 5 mm
QFN-48	0.4 mm	48	7 × 7 mm
QFP-100	0.5 mm	100	14 × 14 mm
LQFP-64	0.5 mm	64	10 × 10 mm

Useful when a tool needs to say "looks like an LQFP-64" based on
bounding-box dimensions.

---

5. Process / DFM defaults

Default fabrication minimums for hobbyist-accessible fab houses
(JLCPCB, PCBWay standard process):

Spec	Min value	Units
Trace width	0.127	mm (5 mil)
Trace spacing	0.127	mm (5 mil)
Drill diameter	0.3	mm (12 mil)
Via annular ring	0.15	mm (6 mil) per side
Pad-to-edge clearance	0.5	mm (20 mil)
Silk-to-pad clearance	0.15	mm (6 mil)
Mask opening expansion	0.05	mm per side

Use these as DRC defaults; let the user tighten them for a premium
process if desired.

---

6. BOM / supplier part numbers

• LCSC (JLCPCB's storefront) part numbers look like C12345 —
  always the most complete supply for JLCPCB assembly.
• Digi-Key part numbers look like 296-1234-5-ND or
  STM32F103RBT6-ND.
• Mouser part numbers look like 511-STM32F103RBT6.
• Manufacturer part number (MPN) is the canonical identifier —
  e.g. STM32F103RBT6. Always carry MPN in BOM regardless of
  which supplier you link to.

A tscircuit component may carry multiple:

supplierPartNumbers={{
  jlcpcb: ["C1519043"],
  digikey: ["iCE40HX1K-VQ100CR-ND"],
  mouser: ["576-ICE40HX1K-VQ100CR"],
}}

Note the array syntax — tscircuit requires lists, not bare
strings.

---

7. Net / signal naming conventions

• Power rails: VCC, VDD, VBUS (USB), +5V, +3V3,
  +1V2. Always prefix voltage with + and write the decimal as
  V (e.g. 3V3 not 3.3).
• Ground: GND, AGND (analog), DGND (digital), PGND
  (power return).
• Differential pairs: suffix _P / _N (positive / negative)
  or + / − (USB-style USB_DP / USB_DM).
• Clock signals: CLK, SCLK, SCK, MCLK, XTAL1 / XTAL2
  for crystal pads.
• SPI: SCK, MOSI, MISO, CS / SS.
• I²C: SDA, SCL.
• UART: TXD, RXD, or TX/RX.
• Reset: RESET, nRESET / RESET_N (active-low).

---

8. 3D board viewer conventions (pads, board, chip)

Any viewer that renders PCB pads together with a 3D chip (alignment
checkers, InstaPCB previews, molecule review tools) must follow the
mechanical convention every EE expects. Get this wrong and the scene
looks "weird" even when the numbers are right.

8a. Z=0 is the top copper layer of the board

• Pad TOP surface = z=0. The top of the copper pad sits exactly at
  z=0. Pads extend DOWNWARD into the board (negative z), not upward.
  Real copper is ~35 µm (0.035 mm) thick; rendering 0.05 mm is a fine
  compromise between realism and visibility.
• Chip sits ON the pads. For an SMD component, the chip's seat
  plane (lowest point of the body / leads that touches the board)
  lands at z=0.
• Thru-hole leads pass THROUGH the board. Leads exit the bottom of
  a standard 1.6 mm FR4 board at z ≈ −1.6 mm.

8a.i. Read the offset — it tells you the GLB's origin convention

Before flagging a non-zero seat-Δz as "broken", check whether it
matches one standard board thickness. 1.6 mm is the default FR4
thickness (also 0.8 / 1.0 / 1.2 / 2.0 mm for specialty runs). Common
interpretations of the number chipMinZ:

chipMinZ	Mount type	Meaning
≈ 0	SMD	GLB origin at TOP of board. Chip seated on pads ✓
≈ +1.6 mm	SMD	GLB origin at BOTTOM of board. Workable — assembly offsets chip by −1.6 mm
≈ −1.6 mm	thru-hole	Leads clear a standard 1.6 mm board ✓
≈ 0	thru-hole	GLB uses origin-at-bottom convention too — chip seat at top-of-slab, leads at bottom
anything else	either	Probably legit floating / sinking — flag it

Different CAD tools bake different conventions: KiCad and tscircuit
usually export with z=0 at the top copper; Fusion 360 / SolidWorks
exports often put z=0 at the bottom of the board model, so the chip
ends up at +board_thickness above ground. Neither is wrong — they
just need an offset at assembly time.

8a.ii. Auto-align for display on convention mismatch

A diagnostic viewer should:

1. Measure the raw chipMinZ before any display tweak.
2. Auto-shift the chip's wrapper transform so the chip visually
   seats on the pads for SMD parts (not thru-hole). Showing a chip
   floating 1.6 mm in air when we know this is a convention offset
   is misleading — it draws the engineer's eye to the wrong thing.
3. Report both the raw offset ("was +1.595") AND the shift
   applied, with an explanation of WHY, in the HUD.
4. Expose a provenance panel listing every pipeline step — source
   file names, parsed pad count, hidden glTF nodes, wrapper scaling,
   raw bbox, applied shift — so the engineer can audit how the
   numbers were arrived at.
5. Never auto-shift for thru-hole — those leads genuinely dip
   below z=0 and the viewer shouldn't hide that.

This replaces the earlier "never auto-correct" rule with a narrower
one: never auto-correct silently. Auto-aligning for display is
fine when we can attribute the shift to a known convention and show
the attribution next to the aligned view.

8b. Only one set of pads on screen

When loading a GLB that bakes in its own demo PCB (InstaPCB-style
test fixtures that carry board_pad / board_PCB / board_fr4 /
board_soldermask / board_silkscreen meshes inside the chip GLB),
hide those baked-in meshes before rendering so the only pads on
screen are the ones from the real KiCad footprint. Two competing pad
sets in the same scene are the #1 source of "this viewer looks
wrong" feedback — and the baked-in pads almost never match the real
footprint anyway.

Match by the mesh's OWN name AND by ancestor names. glTF exporters
often wrap meaningful mesh names (board_pad, board_PCB) under
cryptic node names (=>[0:1:1:3]), so ancestor-only filters miss
them.

8c. No auto-correction in a diagnostic viewer

If a chip is floating 0.4 mm above its pads, do NOT silently translate
it down to touch. The engineer is signing off on the STEP model
being correct; hiding the offset defeats the purpose of the check.
Surface the Δz in a HUD with colour-coded acceptance bands (green /
yellow / red) and let the engineer decide. This rule applies to
every diagnostic view — see app-creator §7e.

8d. Always annotate pin 1 — and bake it into the GLB once it's verified

Pin 1 is the canonical reference corner for every chip. Datasheets
mark it with a dot, chamfer, notch, or silk triangle. Any 3D viewer
that shows a chip on pads MUST give pin 1 a bright, unmistakable
overlay (red ring, beam, or arrow) so alignment against the chip's
pin-1 marker is a one-look check. Relying on "you can see the
marker in the GLB texture" is not good enough at zoom / angle.

Persist the registration into the chip GLB itself. After the
engineer has visually verified pin-1 alignment via an overlay,
bake a small red hemispherical dot (~1 mm diameter, IC-convention)
onto the chip's top surface at the corner nearest pin 1 — NOT
directly above the pin-1 pad, that's not the manufacturer
convention. Save the result as <stem>-pin1.glb next to the source.
Every downstream tool (board preview, molecule review, InstaPCB)
then renders the mark automatically. The chip becomes
self-identifying on every future project; no engineer has to guess
"which corner is pin 1?" during layout, rework, or bench debug.

Pairing rules:

• The footprint .kicad_mod must have a silk-screen pin-1 marker on
  F.SilkS near pin 1 (circle or triangle ~0.5 mm). KiCad's library
  ships this on nearly every footprint; verify on custom ones.
• Board silk flows the footprint's silk into gerbers automatically —
  nothing new to do here once (1) and (2) are in place.

8e. Never align a chip to a wrong-family footprint

A QFN-24 GLB on an LQFP-48 footprint cannot physically be assembled
and any resulting "alignment" view is a lie. 3D alignment viewers
must parse both filenames for package family + pin count and
refuse to render a mismatched pair. Family aliases:

Same family
LQFP / TQFP / QFP
QFN / DFN
TSSOP / SSOP / SOIC / SOP / SO
DIP / PDIP
SOT / SOD
BGA / CSP

The refusal should surface in both the CLI (fail before binding the
port) and the browser (blocking error banner). Rendering one
anyway is worse than failing because a screenshot of it will travel
and mislead someone downstream.

8e. Z-up world, right-handed

Adom's 3D convention (shared with KiCad, Fusion Electronics, and the
InstaPCB pipeline) is Z-up, right-handed: +X right, +Y back,
+Z up. Pads are in the XY plane; chip bodies rise in +Z. GLBs
loaded from tscircuit / KiCad / Fusion follow the "1 GLB unit = 1
meter" convention, so scale by 1000 to land in mm-space alongside
the footprint.

---

9. Checklist — every new EE-touching tool

• Units: primary mm, secondary MILS by default (not None)?
• Mil conversion shown in brackets wherever mm is displayed?
• Ref-designator naming convention respected in labels and
  auto-generated names?
• Silkscreen min-size / min-line rules enforced at DRC?
• DFM defaults match JLCPCB standard process?
• BOM exports include MPN as first-class column, not just
  supplier-specific?
• Net naming follows the standard prefixes (VCC, GND,
  differential _P/_N)?
• Reference designators use the canonical prefixes (U/Q/D/R/C/L/…)?
• 3D viewer: pad TOP at z=0, chip sits on pads, no auto-correct?
• 3D viewer: baked-in demo PCB meshes from GLB hidden before render?
• 3D viewer: pin 1 called out with a bright overlay, not just texture?
• 3D viewer: package-family + pin-count mismatch blocked (CLI + UI)?
• 3D viewer: pin-1 registration can be baked into the chip GLB once verified so it persists across every future use of the chip?