# Wire Lang — full documentation > Wire Lang is a text-first language for electronic schematics. You describe a > circuit as components, terminals, and nets in a small declarative `.wire` > file, and Wire Lang renders it as a clean, deterministic SVG diagram. The > same source always produces the same diagram. This file is a single-document version of the Wire Lang documentation, intended for large language models and other tools that prefer one plain-text/Markdown source. The canonical website is https://www.wirelang.net/. - Website: https://www.wirelang.net/ - GitHub: https://github.com/eduardozf/wire-lang - npm: https://www.npmjs.com/package/wire-lang (install with `npm install wire-lang`) - License: MIT. ESM-only, Node.js 20+. --- ## Overview Code is text, so AI can read it, write it, and refactor it. Diagrams followed with text formats like Mermaid. Electronic schematics never made that jump and stayed locked inside GUI editors that AI cannot read. Wire Lang is the missing layer between AI and the circuit board: schematics become something an engineer or an assistant can generate, review, and improve as plain text. Wire Lang models a real electrical circuit — components with typed terminals joined by nets — rather than flowchart boxes and arrows. It is a documentation-oriented schematic renderer. It is NOT: - an electrical simulator, - a PCB layout, footprint, or routing tool, - a breadboard layout tool, - a bill-of-materials (BOM) generator, - a visual/GUI editor. The main product reference is Mermaid: a text-first documentation workflow where source blocks render into diagrams. Wire Lang follows that product shape for electronic schematics, but it is not a Mermaid plugin and does not aim for Mermaid syntax compatibility. ### The shortest example ```wire schematic title "LED current limiting circuit" component BT1 Battery voltage=5V component R1 Resistor value=220ohm component D1 LED color=red net VCC: BT1.+, R1.1 connect R1.2, D1.A net GND: D1.C, BT1.- annotation "Current limiting resistor" near R1 ``` `BT1`, `R1`, `D1` are component instances; `Battery`, `Resistor`, `LED` are component types; `VCC`, `GND` are named nets; `connect` makes an anonymous net. Visual wires are renderer output, not the source of truth. --- ## When to use Wire Lang Reach for Wire Lang when the job is generating a schematic SVG from a parts list, documenting an existing circuit as deterministic text, reviewing or refactoring a schematic in code review, or embedding live diagrams in a docs site. Do NOT reach for it for simulation, PCB layout, BOM generation, or GUI editing. Agent loop: discover parts via `GET /api/components` (spec at `/openapi.json`), author `.wire` source, validate with `npx wire check file.wire --json`, then render. Full agent instructions live in `/llms.txt`. --- ## Getting started Requires Node.js 20 or newer. ### 1. Install ```bash npm install wire-lang ``` The `wire-lang` package contains the library API and the `wire` command-line binary. You can also run the CLI without installing it using `npx`. ### 2. Write a `.wire` file Create `led.wire`. Every document begins with `schematic`, then declares components and the nets that connect their terminals. ```wire schematic title "LED current limiting circuit" description "A 5V battery drives a red LED through a 220 ohm resistor." component BT1 Battery voltage=5V component R1 Resistor value=220ohm component D1 LED color=red net VCC: BT1.+, R1.1 connect R1.2, D1.A net GND: D1.C, BT1.- annotation "Current limiting resistor" near R1 render direction=left-to-right ``` ### 3. Render from the CLI ```bash npx wire render led.wire --out led.svg ``` There is no preview server — open the generated `led.svg` directly. Use `wire check` to validate without output, and `wire watch` to re-render on save. ### 4. Render from JavaScript or TypeScript ```ts import { compile, parse, renderSvg } from "wire-lang"; const parsed = parse(source); // public AST, or partial AST + diagnostics const result = compile(source); // { ok, model, diagnostics } const svg = renderSvg(source); // SVG string, or throws WireLangError ``` `parse` / `compile` accept source; `compile` / `renderSvg` also accept the prior stage's output. ### 5. Generate Wire Lang with AI Wire Lang is built for AI-assisted authoring. Diagnostics carry source locations and suggested fixes; the CLI speaks JSON (`wire check led.wire --json`). Install the bundled Agent Skill: ```bash npx skills add eduardozf/wire-lang --skill wire-lang ``` --- ## Syntax reference Wire Lang is declarative. A `.wire` document declares components, the nets that connect their terminals, annotations, and render hints — it never contains coordinates. The language separates the electrical model (components, terminals, nets) from the drawing; visual wires are renderer output. ### Document structure A Wire file is UTF-8, uses the `.wire` extension, and contains exactly one document that starts with the `schematic` document kind, optionally followed by `title` and `description`. Indentation is for readability only. ```wire schematic title "LED current limiting circuit" description "A 5V battery drives a red LED through a 220 ohm resistor." component BT1 Battery voltage=5V component R1 Resistor value=220ohm component D1 LED color=red net VCC: BT1.+, R1.1 connect R1.2, D1.A net GND: D1.C, BT1.- annotation "Current limiting resistor" near R1 render direction=left-to-right ``` ### Components `component [properties...]`. Each instance ID is unique. Types and terminal names come from the standard library (or a local definition). ```wire component R1 Resistor value=220ohm component D1 LED color=red component J1 Header pins=[VCC,GND,SDA,SCL] component U1 IC pins=[1:VCC@left, 2:GND@left, 3:OUT@right, 4:EN@right] ``` Conventional designator prefixes (`R` for resistors, `D` for diodes/LEDs, `C` for capacitors) are recommended; a mismatch is a warning, not an error. Use `IC` for chips that need numbered pins. Each entry in its `pins=[...]` list is `number:name@side`, where the number and `@side` (`left`, `right`, `top`, `bottom`) are optional and an omitted side defaults to `left`. Connect IC pins by name, e.g. `net VCC: U1.VCC, ...`. ### Local component definitions Use a `define component ... end` block for parts not in the standard library. A local definition overrides a standard component of the same name within that document. ```wire define component SoilSensor terminal VCC terminal GND terminal AOUT terminal DOUT symbol module end component S1 SoilSensor ``` Local components without a specialized symbol use `symbol module`, a generic block with the declared terminals. If a local component reuses a built-in symbol with semantic roles, it must map its terminals to those roles: ```wire define component MyLed terminal positive_leg terminal negative_leg symbol led map anode = positive_leg map cathode = negative_leg end end ``` Custom symbol artwork (a drawing language) is outside the current scope. ### Nets A net is a logical electrical connection joining one or more terminals. Named nets: `net : ., ...`. ```wire net VCC: BT1.+, R1.1 net GND: D1.C, BT1.- ``` Repeated declarations of the same net name merge into one logical net: ```wire net VCC: BT1.+ net VCC: R1.1, C1.1 ``` A terminal assigned to two different nets is a fatal error. A floating net (one terminal) is allowed but warns. ### connect — anonymous nets `connect` creates an anonymous net between the listed terminals. This is the idiomatic way to express "draw a wire from X to Y". ```wire connect R1.2, D1.A ``` ### no-connect — intentionally unconnected Mark a terminal as intentionally unconnected with `no-connect`. It renders as a small `X` at the terminal. A terminal cannot be both in a net and `no-connect` — that is a fatal validation error. Repeating a `no-connect` for the same terminal warns. ```wire no-connect U1.7 ``` ### Power nets `VCC`, `5V`, `3V3`, `GND` are conventional power nets. They are NOT magic globals: they create no hidden connections, and `GND` does not auto-add a ground-reference symbol. Connect them explicitly: ```wire component G1 GroundReference net GND: G1.GND, BT1.- ``` Nets render as visual wires by default. To render a net as labels: `render net VCC style=label`. ### Annotations and comments A comment starts with `//`, documents the source, and never appears in the diagram. An annotation is text intentionally drawn in the schematic, placed near a component instance or a named net. ```wire // Source-only comment, never rendered annotation "Status LED" near D1 annotation "Power rail" near net VCC ``` ### Render hints Render hints guide drawing without changing electrical meaning. ```wire render direction=left-to-right render crossings=hop render layout=bus-rail render net VCC style=label render R1 orientation=vertical render U1 anchor=center ``` | Hint | Values | Status | | --------------- | ----------------------------------------------------------------- | ------------------------------- | | `direction` | `left-to-right`, `right-to-left`, `top-to-bottom`, `bottom-to-top`| Honored (default left-to-right) | | `crossings` | `gap`, `hop` | Honored (default gap) | | `layout` | `flow`, `bus-rail` | Honored (default flow) | | net `style` | `wire`, `label` | Honored | | `orientation` | `horizontal`, `vertical` | Honored | | `side` | `left`, `right`, `top`, `bottom` | Accepted, not yet honored | | `anchor` | `center` | Accepted, not yet honored | Wire crossings: by default (`crossings=gap`) wires that cross without a junction dot are simply drawn overlapping. `crossings=hop` opts in to a small semicircular hop on the horizontal wire at each such crossing. Layout modes: the default `flow` layout draws a row of components with per-net rails, following the global `direction`. `render layout=bus-rail` redraws the schematic as a block diagram between a top supply rail and a bottom ground rail, color-coding nets by family and bundling grouped signals into bus trunks. Power rails and buses are inferred from net names and connectivity — no extra syntax is needed. Two-terminal parts that hang off one block (LED chains, buttons, a speaker across an amp's outputs) are placed automatically under or beside the pin that feeds them, flipped so their polarity faces the wire. Bus-rail forces `hop` crossings and a monospace label profile. Per-component orientation: an `orientation` that runs against the flow's natural axis rotates the part 90° — e.g. `render R1 orientation=vertical` draws a vertical resistor in a left-to-right flow. `side` and `anchor` are validated and recorded but emit a `render.not-yet-honored` warning; the bundled layout engine does not position by them yet. `group` statements behave the same way (`group.not-yet-honored`). ### Properties and quantities Properties are written `key=value`. Value kinds: quantity (number + unit), string, boolean, enum. Unit-bearing values normalize to quantities while keeping a display label. ```wire value=220ohm value=220Ω value=10k voltage=5V capacitance=100nF ``` A missing recommended property is a warning, not an error. Unknown properties warn and are preserved in the model for future tooling. ### Standard component library Terminals are written after the instance ID with a dot, e.g. `BT1.+`, `D1.A`, `Q1.C`. `Header` and `IC` terminals come from their `pins=[...]` list. | Type | Terminals | Properties | Symbol | | -------------------- | ------------- | ---------------------------------------------------------------- | ------------------- | | `Resistor` | `1`, `2` | recommended `value` (resistance) | resistor | | `Capacitor` | `1`, `2` | recommended `capacitance` | capacitor | | `PolarizedCapacitor` | `+`, `-` | recommended `capacitance` | polarized-capacitor | | `Inductor` | `1`, `2` | recommended `inductance` | inductor | | `Diode` | `A`, `C` | none | diode | | `LED` | `A`, `C` | optional `color` (red, green, blue, yellow, white, amber) | led | | `NPNTransistor` | `C`, `B`, `E` | none | npn-transistor | | `PNPTransistor` | `C`, `B`, `E` | none | pnp-transistor | | `Battery` | `+`, `-` | recommended `voltage` | battery | | `GroundReference` | `GND` | none | ground-reference | | `SPSTSwitch` | `1`, `2` | optional `state` (open, closed) | spst-switch | | `PushButton` | `1`, `2` | optional `normally` (open, closed) | push-button | | `Header` | from `pins=[...]` | recommended `pins` (pin list) | module | | `FerriteBead` | `1`, `2` | none | ferrite-bead | | `TVSDiode` | `A`, `C` | optional `bidirectional` (boolean) | tvs-diode | | `Speaker` | `+`, `-` | none | speaker | | `Antenna` | `1` | none | antenna | | `TestPoint` | `1` | optional `name` | test-point | | `PTC` | `1`, `2` | none | ptc | | `PowerFlag` | `1` | recommended `name` (rail label) | power-flag | | `IC` | from `pins=[...]` | recommended `pins` (IC pin list) | ic | `PTC` is the resettable-fuse / polyfuse variant. `PowerFlag` draws its `name` (e.g. `5V`, `3V3`, `VBAT`) as a rail flag and is NOT a hidden global net. Standard symbols follow an IEC-style visual profile where practical, with original open-source artwork; Wire Lang does not claim formal IEC 60617 or IEEE 315 compliance. MOSFETs, op-amps, relays, motors, displays, sensors, and complex boards (e.g. Arduino, ESP32) are outside the standard library; use `IC` with named pins for chips, or model other parts as local module-style components. --- ## CLI usage The `wire` command is a thin wrapper around the parser, compiler, and SVG renderer, for developer and AI-agent feedback loops. It ships with the `wire-lang` npm package and needs Node.js 20+. There is no preview server. ### wire check — validate Reports parse, reference, validation, and render-blocking diagnostics WITHOUT producing SVG. ```bash wire check examples/led.wire npx wire check examples/led.wire ``` ### wire render — produce SVG Writes a standalone SVG when rendering can complete; reports diagnostics when it cannot. Output path via `--out`. ```bash wire render examples/led.wire --out led.svg ``` ### wire watch — re-render on change Reruns checking and rendering whenever the input file changes. ```bash wire watch examples/led.wire --out led.svg ``` ### JSON output for agents Add `--json` to `check` or `render` for machine-readable diagnostics with stable codes, severity, message, source range, and suggested fixes. ```bash wire check examples/led.wire --json wire render examples/led.wire --out led.svg --json ``` ### Exit codes - `0` — completed successfully; warnings may be present. - `1` — source has fatal diagnostics, or rendering could not complete. - `2` — CLI usage, file I/O, or configuration problem. --- ## Examples Each example is a complete, valid document. Render with `wire render file.wire --out file.svg`. ### LED current limiter ```wire schematic title "LED current limiting circuit" description "A 5V battery drives a red LED through a 220 ohm resistor." component BT1 Battery voltage=5V component R1 Resistor value=220ohm component D1 LED color=red net VCC: BT1.+, R1.1 connect R1.2, D1.A net GND: D1.C, BT1.- annotation "Current limiting resistor" near R1 render direction=left-to-right ``` ### RC low-pass filter ```wire schematic title "RC low-pass filter" description "A first-order RC low-pass filter between a header input and output." component J1 Header pins=[IN,OUT,GND] component R1 Resistor value=1k component C1 Capacitor capacitance=100nF net IN: J1.IN, R1.1 net OUT: R1.2, C1.1, J1.OUT net GND: C1.2, J1.GND annotation "Cutoff ~1.6 kHz" near net OUT render direction=left-to-right ``` ### Soil sensor module (local component) ```wire schematic title "Soil sensor input" description "A local soil-sensor module wired to a header and a pull-down resistor." define component SoilSensor terminal VCC terminal GND terminal AOUT symbol module end component S1 SoilSensor component R1 Resistor value=10k component J1 Header pins=[VCC,GND,A0] net VCC: J1.VCC, S1.VCC, R1.1 net GND: J1.GND, S1.GND net SENSOR: S1.AOUT, R1.2, J1.A0 render layout=bus-rail ``` ### NPN LED driver ```wire schematic title "NPN LED driver" description "An NPN transistor switches a green LED from a 9V supply, driven through a base resistor." component BT1 Battery voltage=9V component R1 Resistor value=1k component R2 Resistor value=330ohm component Q1 NPNTransistor component D1 LED color=green component J1 Header pins=[IN,GND] component G1 GroundReference net VCC: BT1.+, R2.1 net LEDK: R2.2, D1.A connect D1.C, Q1.C net BASE: J1.IN, R1.1 connect R1.2, Q1.B net GND: Q1.E, BT1.-, J1.GND, G1.GND annotation "Base current limit" near R1 render direction=left-to-right ``` ### Battery LED with push button ```wire schematic title "Battery LED with push button" description "A 3V battery lights a red LED through a current-limiting resistor when the push button is pressed." component BT1 Battery voltage=3V component SW1 PushButton normally=open component R1 Resistor value=220ohm component D1 LED color=red net VCC: BT1.+, SW1.1 connect SW1.2, R1.1 connect R1.2, D1.A net GND: D1.C, BT1.- annotation "Press to light the LED" near SW1 annotation "Current-limiting resistor" near R1 render direction=left-to-right ``` ### Standard symbol coverage (kitchen sink) ```wire schematic title "Switched RLC bench demo" description "A switched 9V rail feeds an RLC network, a PNP low-side driver and an amber LED, with a filtered output header. Exercises a selection of standard symbols." component BT1 Battery voltage=9V component SW1 SPSTSwitch state=closed component BTN1 PushButton normally=open component L1 Inductor inductance=10mH component D1 Diode component R1 Resistor value=1k component R2 Resistor value=4k7 component C1 Capacitor capacitance=100nF component C2 PolarizedCapacitor capacitance=10uF component Q1 PNPTransistor component D2 LED color=amber component J1 Header pins=[VBUS,SIG,GND] component G1 GroundReference net VIN: BT1.+, SW1.1, BTN1.1 net RAIL: SW1.2, BTN1.2, L1.1, R1.1, C2.+, J1.VBUS net MID: L1.2, D1.A, R2.1, Q1.E connect D1.C, C1.1, Q1.B net SIG: R2.2, C1.2, Q1.C, D2.A, J1.SIG net GND: BT1.-, R1.2, C2.-, D2.C, J1.GND, G1.GND annotation "PNP low-side driver" near Q1 annotation "Output filter" near net SIG render direction=left-to-right ``` ### Bus-rail block diagram (IC pins + bus-rail layout) ```wire schematic title "Bus-rail layout demo" description "A sensor and LED driver around an MCU hub, drawn with top and bottom rails, a bundled sensor bus, colored control lines, and a button in the control band." component U1 IC pins=[1:VCC@left, 2:GND@left, 3:SCL@right, 4:SDA@right, 5:INT@right] component U2 IC pins=[1:3V3@left, 2:GND@left, 3:SCL@left, 4:SDA@left, 5:IRQ@left, 6:BTN@left, 7:DRIVE@right, 8:FAULT@right] component U3 IC pins=[1:VIN@left, 2:GND@left, 3:IN@left, 4:FAULT@left, 5:OUT@right] component SW1 PushButton component D1 LED color=green net VCC: U1.VCC, U2.3V3, U3.VIN net GND: U1.GND, U2.GND, U3.GND, SW1.2, D1.C net SCL: U1.SCL, U2.SCL net SDA: U1.SDA, U2.SDA net INT: U1.INT, U2.IRQ net DRIVE: U2.DRIVE, U3.IN net FAULT: U3.FAULT, U2.FAULT net BTN: SW1.1, U2.BTN net LED_OUT: U3.OUT, D1.A render layout=bus-rail ``` --- ## Wire Lang vs Mermaid Wire Lang and Mermaid share a product shape: text goes in, a documentation-friendly diagram comes out, and the source lives in version control. The difference is what the text describes. Mermaid draws generic graphs (boxes and arrows). Wire Lang models a real electrical circuit (components with typed terminals joined by nets) and renders an electronic schematic. Wire Lang is NOT a Mermaid plugin, does not depend on Mermaid, and does not aim for syntax compatibility. Think "Mermaid, but for electronic schematics." | Aspect | Mermaid | Wire Lang | | ------------------- | ----------------------------------------- | -------------------------------------------------------- | | Domain | General diagrams | Electronic schematics | | Primitives | Nodes and edges | Components, terminals, and nets | | Semantics | Visual graph; meaning is up to the author | Electrical model; validated against a component library | | Output | SVG diagram | Standalone, deterministic SVG schematic | | Validation | Syntax-level | Syntax + electrical (unknown parts/terminals, conflicts) | | Authoring feedback | Parse errors | Structured diagnostics with codes, ranges, fixes | | Determinism | Layout may shift between versions | Stable auto-layout: same source → same diagram | Use Mermaid for flowcharts, sequence diagrams, and architecture sketches. Use Wire Lang when the thing you are documenting is an electronic circuit and you want a proper schematic an engineer recognizes and an AI can also generate. --- ## FAQ **What is Wire Lang?** A text-first language for electronic schematics. Describe a circuit as components, terminals, and nets in a `.wire` file; Wire Lang renders a clean, deterministic SVG. It is a documentation-oriented schematic renderer. **How is it different from Mermaid?** Both turn text into diagrams, but Mermaid draws generic boxes and arrows while Wire Lang models a real electrical circuit, validated against a component library. **Does it simulate circuits?** No. No simulation, no PCB or breadboard layout, no BOM. Those are explicit non-goals. **Can it lay out a PCB or breadboard?** No. A Wire Lang document is a logical schematic, not physical placement or routing. **What components are built in?** Resistor, Capacitor, PolarizedCapacitor, Inductor, Diode, Photodiode, SchottkyDiode, ZenerDiode, Potentiometer, Rheostat, LED, NPNTransistor, PNPTransistor, Battery, GroundReference, SPSTSwitch, PushButton, Header, FerriteBead, TVSDiode, Speaker, Antenna, TestPoint, PTC, PowerFlag, and IC (a generic chip with numbered, named pins). **What if I need a part that isn't built in?** For chips, use the built-in `IC` type with named pins. For anything else, define it locally with a `define component ... end` block. MOSFETs, op-amps, and boards like Arduino are modeled this way. **Does it support different layouts?** Yes. The default `flow` layout draws a row of components with per-net rails. `render layout=bus-rail` redraws the schematic as a block diagram between a top supply rail and a bottom ground rail, color-coding nets and bundling grouped signals into bus trunks — power rails and buses are inferred from net names and connectivity. **How does it work with AI?** Schematics are plain text, so assistants can generate and refactor them. The parser returns a partial AST for invalid input, diagnostics carry source locations and suggested fixes, and the CLI emits JSON. A bundled Agent Skill teaches the syntax and component library. **What file format does it use?** `.wire`, UTF-8, one `schematic` document per file. Output is standalone SVG with accessible title/description and stable metadata. **Is there a preview server?** No. Open the generated SVG directly; use `wire watch` to re-render on save. **Is it free and open source?** Yes — MIT-licensed, published on npm as `wire-lang`. **Are the symbols IEC compliant?** They follow an IEC-style visual profile where practical with original artwork, but Wire Lang does not claim formal IEC 60617 or IEEE 315 compliance. ## Browser and Markdown integrations, 0.4.0 Guide: https://www.wirelang.net/docs/integrations/ Use @wire-lang/core for custom editors and diagnostics. Use @wire-lang/browser for asynchronous discovery of pre > code.language-wire blocks after HTML loads. Import wire from https://cdn.jsdelivr.net/npm/@wire-lang/browser@0.4.0/dist/index.js and call await wire.initialize(). Source stays in the DOM, repeated calls do not duplicate diagrams, and errors are returned per block. Call await wire.run() after navigation or content insertion. Compilation still runs on the main thread. @wire-lang/markdown provides remarkWire and rehypeWire for Markdown and MDX. The default browser mode preserves fences; initialize the browser runtime to render them. Use { mode: "static" } to generate inline SVG during the build without a browser runtime. Use one Wire plugin per pipeline. Static errors fail the document build. New standard components: | Component | Terminals | Properties | Symbol | | --- | --- | --- | --- | | Photodiode | A, C | none | photodiode | | SchottkyDiode | A, C | none | schottky-diode | | ZenerDiode | A, C | optional voltage | zener-diode | | Potentiometer | 1, W, 2 | recommended value (resistance) | potentiometer | | Rheostat | 1, 2 | recommended value (resistance) | rheostat | ## jsDelivr CDN Paste this module script inside your site's ``. It loads the latest browser package and waits for the HTML to be ready before rendering Wire blocks. ```html ``` Place your schematic blocks in the page body using the language-wire class: ```html 
schematic
  component R1 Resistor value=220ohm
  component D1 LED color=red
  connect R1.1, D1.A
``` These versionless URLs resolve to the latest version published on npm and will follow future releases. | Package | CDN URL | | --- | --- | | `wire-lang` | | | `@wire-lang/core` | | | `@wire-lang/cli` | | | `@wire-lang/browser` | | | `@wire-lang/markdown` | | For direct browser rendering, use @wire-lang/browser. CDN availability does not make the CLI or Markdown build plugins browser-compatible. Pin a version in production imports for reproducible behavior.