---
icon: 🎨
---

# Design System

How the web app's visual language is defined. Colour is fully specified on its own page, *colour*;
this page is the glossary around it.

**Step** — a position 1–12 in a colour scale. The number *is* the meaning, in both themes; there are no
semantic aliases. See *colour* for the job of each step. _Avoid_: "token" for a step, "shade", "ramp step"

**Scale** — one of the five twelve-step ladders: `gray`, `accent`, `success`, `warning`, `danger`.
_Avoid_: "palette" (that is the swatch set), "ramp"

**Exception** — one of the six named tokens that exist because no step can do their job (`--panel`,
`--on-accent`, `--on-success`, `--on-warning`, `--on-danger`, `--scrim`).

**Seed colour** — a hex a platform picks. `primaryColor` seeds the accent scale (the greys stay neutral); the optional
danger, warning and success colours (`themeColors.status`) each seed their own scale.

**Ramp** — the twelve steps of one scale for both themes, generated from a seed colour by `brandColors.ramp`
(nearest colour family, contrast-checked steps 10 and 11). `brandSeed` writes a chosen colour's ramp on `<html>`
as `--accent-light-N` / `--accent-dark-N` (and the same for danger, warning, success); the CSS defaults are the
generator's output for the stock colours.

**Mark** — a coloured shape carrying no text. A small status dot is step 10; a fill such as a progress bar,
meter or chart series is step 9.

**Swatch** — the twelve-hue *categorical* set (`swatch-1` … `swatch-12`), for "which one is this?"
rather than "what does this mean?" — projects, avatars, chart series. Not a scale.

**Plate** — the light chip a third-party logo sits on. It is a light island, so it stays light in both
themes, because we cannot recolour someone else's artwork. `<LogoPlate>` renders one.

## Gotchas
- **A Radix `Popover` opened from inside a `Dialog` must be `modal`, or the mouse wheel does nothing in it.** The dialog's scroll lock treats the portaled popover as "outside" and cancels wheel events there; `<Popover modal>` installs its own lock that allows scrolling inside the content. `SearchableSelect` and `ModelPickerPopover` do this; a non-modal popover looks fine until it is used in a dialog.
- **`CommandList` (`components/ui/command.tsx`) defaults to `overflow-y-hidden`, so a cmdk list silently cannot scroll.** Every caller must add `overflow-y-auto` (or nest a `ScrollArea`); passing only a `max-h-*` looks fine with few rows and clips the rest. Bit the tiers model picker (2026-10-05).
- **The stock field primitives disagree on shape, so a toolbar that mixes them looks uneven.** `InputWithIcon` is `rounded-md border-gray-6`, `Button` is `rounded-lg` with `gap-2`, and `SelectTrigger` is `rounded-lg border-gray-8 shadow-xs`. In one row, pass `rounded-md` (and `border-gray-6 shadow-none` on the select) so every control matches. A filter toggle shows a `Checkbox` inside a `<label>`, not an icon `Toggle`, so its on/off state is visible (`SelectedOnlyButton`, AI key page, 2026-11-05).
- **Copy to clipboard goes through `clipboardUtils.copy` (`components/custom/clipboard/use-copy-to-clipboard.ts`), never a bare `navigator.clipboard.writeText`.** The write is rejected in an embed's cross-origin iframe without `allow="clipboard-write"`, so fire-and-forget code shows "Copied" with an empty clipboard plus an unhandled rejection (GIT-2054). The helper awaits the write, toasts `Failed to copy to clipboard` once, and returns whether it worked; `useCopyToClipboard` uses it too.
- **`border-dashed` on anything under ~16px renders as a broken squiggle, not a dashed circle.** Browsers cannot fit whole dashes around an 8px `rounded-full`, so a tiny dashed dot reads as a glitch. Use a solid border in a lighter step (`border-gray-7`) for a "placeholder" dot and keep dashed borders for boxes.

- **An irreversible consequence in a confirm dialog goes in the dialog's `warning` slot, not in hand-styled description text.** `ConfirmationDeleteDialog` already has a `warning` prop that renders `Alert variant="warning"` with the triangle icon below the header (embed hostname, billing, connections, Authentication remove-domain), and `MethodConfirmDialog` takes the same `warning` prop. Keep `message`/`description` to one plain sentence. A custom red/amber `<span>` callout in the description looked foreign in review. Both dialogs also take `confirmText` for a type-to-confirm box (Authentication asks for the domain name to remove a verified domain, and `disable` to disable SSO) and `confirmDisabled` to block the action outright. Keep the typed text in `useTypeToConfirm({ open, text })` (next to `TypeToConfirm`): it resets whenever `open` changes, so Cancel, Esc, a parent closing the dialog and a successful confirm all start the next open empty, without wiring a reset into each close path.
- **`ConfirmationDeleteDialog` renders `message` inside `DialogDescription`, a `<p>`.** A select or any other form control placed in the message is invalid nesting and becomes the dialog's `aria-describedby`. A delete flow that needs an input (the tier delete's "Move them to" select) builds its own `Dialog` and keeps only the confirm button's `adminControl` id.
- `styles.css` points the `--shadow-*` theme keys that change per theme at a plain custom property
  (`--shadow-edge: var(--edge)`). Tailwind copies a `--shadow-*` value into the utility literally, so a dark override of
  the theme key itself never lands; the indirection is what lets shadows change per theme.
- `PROJECT_COLOR_PALETTE` in `@activepieces/shared` reads `--swatch-N-on` through JS, not a Tailwind
  class, so grepping for the class says it is dead when it is not.
- Tailwind emits nothing for an unknown utility, and an unresolvable `var()` makes its declaration invalid, so a
  removed colour token never fails the build. Web lint does: `scripts/check-tailwind-classes.mjs` fails on any class
  Tailwind cannot generate and any `var()` that nothing defines.

## Key files

- `packages/web/src/styles.css` — the scales, exceptions, swatches and both theme blocks
- `packages/core/shared/src/lib/core/common/` — `brandColors.ramp`, `cssVariables` and `statusCssVariables` (generate the ramps; `lib/brand-seed.ts` writes them) and
  `swatchUtils`
- `packages/web/src/components/custom/logo-plate.tsx` — the one way to render a third-party logo
- `packages/web/src/lib/syntax-theme.ts` — the one place the code and JSON viewers pick a theme
