# Signal Versioning

> How Signal versions work, why the kit is never bundled, how to add your own CSS safely with --sg- tokens, and what the sandbox blocks.

Source: https://sendbroadcast.net/docs/signal-versioning

> Coming in Broadcast 3.0. Until then, this page applies only to the Upcoming (edge) build.

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`:

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

Use the tokens, so that your styles match:

```css
.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 `