Documentation

PIDSTACK symbols are typed React components that share one props API, plus plain SVG files and a JSON manifest.

Quick start

1. Free: download the starter pack or install single symbols with the shadcn CLI (no key needed).
2. Pro: create a license key in your account, then install any symbol or a whole set.
3. Import the stylesheet once and put a theme on any ancestor.

import { PumpCentrifugal } from "@/components/pidstack/pump-centrifugal"
import "@/components/pidstack/pidstack.css"

export function FeedPump() {
  return (
    <div data-theme="night">
      <PumpCentrifugal state="running" label="P-101" size="medium" />
    </div>
  )
}

shadcn registry

Every symbol is a registry item at https://pidstack.com/r/<id>.json. Items depend on pidstack-core (the shared frame and stylesheet), which the CLI installs automatically.

npx shadcn@latest add "https://pidstack.com/r/pump-centrifugal.json"

Pro items need a license key, as a query parameter or, better, as a header through a namespaced registry in components.json:

{
  "registries": {
    "@pidstack": {
      "url": "https://pidstack.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${PIDSTACK_LICENSE_KEY}" }
    }
  }
}

export PIDSTACK_LICENSE_KEY=psk_...
npx shadcn@latest add @pidstack/valve-control @pidstack/tank-vertical

npx shadcn@latest add "https://pidstack.com/r/valve-control.json?api_key=$PIDSTACK_LICENSE_KEY"

The public index (names and tiers, no code) is at https://pidstack.com/r/registry.json. Without a key, Pro items answer 401; with a key but no active plan they answer 403.

License keys

• Keys look like psk_abc123def4_…. The first part is a public id shown in your account; the rest is secret.
• We store only a salted SHA-256 hash, so a key is shown once, when you create it. Lost keys cannot be recovered: revoke and create a new one.
• Up to five active keys per account. Revoking takes effect immediately.
• Keys work while your plan is active. When a subscription ends, Pro items stop resolving; files you already installed keep working.
• Keep keys out of source control: use an environment variable or your CI secret store.

MCP server

AI coding assistants can search the catalog and fetch component code through the Model Context Protocol endpoint https://pidstack.com/mcp (Streamable HTTP, stateless). Tools: search_symbols, get_symbol, list_sets. Free symbols work without a key.

claude mcp add --transport http pidstack https://pidstack.com/mcp --header "Authorization: Bearer $PIDSTACK_LICENSE_KEY"

{
  "mcpServers": {
    "pidstack": {
      "url": "https://pidstack.com/mcp",
      "headers": { "Authorization": "Bearer psk_..." }
    }
  }
}

States and themes

Themes: day, bright, dusk, night, set with data-theme on any ancestor. Colours come only from CSS variables (--sym-line, --sym-state-running and so on), so you can map them to your own design tokens.

Common props: state, size (regular, medium, large), label, value, orientation (0, 90, 180, 270), onSelect and selected (turn the symbol into a keyboard-accessible button), ariaLabel.

Full engine (Pro)

Registry symbols have fixed geometry per state, which keeps each file small. For live values inside gauges, setpoints and zones, upright text on rotated symbols and motion, install the parametric engine for a set:

npx shadcn@latest add @pidstack/pidstack-engine-gauges

SVG files and manifest

The ZIP downloads include one SVG file per symbol and manifest.json with ids, names, tags, categories, sizes and connection ports on the 24 px grid. SVG files use the same CSS variables with day-theme fallbacks, so they render on their own and can be themed in any framework.

About standards

Symbols are drawn from scratch and follow common conventions such as ISA 5.1, ISO 10628, IEC 60617 and IEEE 315. The reference on each symbol page names the meaning a symbol stands for; no standard text or figure is reproduced. Check your diagrams against the standards that apply to your project.