Signal Versioning

This page explains how Signal changes over time, and how to add your own styles without breaking anything.

v1 only grows

The version is in the address: /plugin-kit/v1/. Inside v1, new components and options can appear, but what exists keeps working. A change that would break a plugin needs a new version, v2, at a new address.

So a plugin that loads /plugin-kit/v1/kit.js keeps working when the server upgrades.

Never bundle the kit

Your Broadcast server serves the kit. Always load it from /plugin-kit/v1/:

Do not copy kit.js or kit.css into your plugin.
Do not import it in dist/main.js. That code runs on the server, with no page.

A page that loads the shared kit gets fixes with each Broadcast upgrade, and it matches the app. A copy goes out of date, and it stops matching.

The kit files are public and hold no data. A browser can keep them for 5 minutes, so a server upgrade can take that long to reach an open page.

Add your own CSS

Often you need nothing extra. If you do, use a file in ui/, and load it after kit.css:

<link rel="stylesheet" href="/plugin-kit/v1/kit.css">
<link rel="stylesheet" href="style.css">

Use the tokens, so that your styles match:

.poll-note {
  padding: var(--sg-3);
  border: 1px solid var(--sg-border);
  border-radius: var(--sg-radius);
  background: var(--sg-surface);
  color: var(--sg-muted);
}

Tokens

Token	Use
`--sg-bg`	The page background
`--sg-surface`	Cards
`--sg-border`, `--sg-border-strong`	Lines
`--sg-text`, `--sg-muted`	Text and quiet text
`--sg-accent`, `--sg-accent-hover`, `--sg-accent-soft`	The accent
`--sg-success`, `--sg-success-soft`	Success, and its pale background
`--sg-warning`, `--sg-warning-soft`	Warning
`--sg-danger`, `--sg-danger-hover`, `--sg-danger-soft`	Danger
`--sg-info`, `--sg-info-soft`	Information
`--sg-neutral-soft`	A grey background
`--sg-radius`, `--sg-radius-lg`	8px and 10px
`--sg-font`, `--sg-mono`	Text and code fonts
`--sg-1` to `--sg-6`	Spacing: 4, 8, 12, 16, 24 and 32px
`--sg-motion`	The speed of small changes

Two helper classes are safe to use on your own tags: sg-help for small quiet text, and sg-muted for quiet text.

What is safe

Safe	Not safe
Your own class names, with a prefix such as `poll-`	Changing `--sg-accent`, so your plugin has its own color
`var(--sg-...)` in your own rules	Styling the kit’s inner elements. They can change in v1
Your own layout around components	Overriding a component’s look

Names that start with sg- or --sg- belong to the kit, so do not make your own.

What the sandbox blocks

Your page runs under strict rules. Signal works within them, and your own code must too.

Blocked	Do this
Inline `<script>`	Use `ui/app.js`
`onclick="..."`	Use `addEventListener`
Inline `<style>`	Use `ui/style.css`
`style="..."` in HTML, or with `setAttribute("style", ...)`	Use a class. In code, `node.style.color = "..."` works
`fetch` and all other network calls	Use `sg.pageData`, and `fetch` in `dist/main.js`
Scripts, styles and fonts from another site	Put the file in `ui/` or `assets/`
`window.confirm`, `window.alert`	Use `sg.confirm` and `sg.toast`
`window.open` and links to a new window	Use `sg-link external` or `sg.openExternal`
Cookies and `localStorage`	Use `sg.call("store.set", ...)`
Normal form posts	Use `sg-form`

Plugin Pages explains why.