Skip to content

Theming ​

Make your plugin's panel look like part of Omniscio, in the user's own theme, with no extra code.

Your panel runs in its own document, so it cannot read Omniscio's stylesheet. Instead, Omniscio sets a set of CSS custom properties on your page's :root before your first paint, and updates them in place whenever the user switches light/dark mode, accent colour, font or corner style. Style with these and your panel follows the user's theme automatically.

Use the tokens, not theme.get()

Omniscio.theme.get() is a fixed placeholder (it always answers mode: 'dark'). The CSS tokens on this page are the real, live theme.

Always present ​

These are set on every plugin page, in every theme.

TokenValueUse it for
--surface-50colour (hex)The page background end of the scale
--surface-100colour (hex)Raised panels, cards
--surface-200colour (hex)Hover backgrounds, subtle fills
--surface-300colour (hex)Borders and dividers
--surface-400colour (hex)Strong borders, disabled text
--surface-500colour (hex)Placeholder and hint text
--surface-600colour (hex)Secondary text
--surface-700colour (hex)Body text on light surfaces
--surface-800colour (hex)Emphasised text
--surface-900colour (hex)Headings, primary text
--surface-950colour (hex)The text end of the scale
--accent-rgbR G B (three numbers)The user's accent colour: rgb(var(--accent-rgb)), or with transparency rgb(var(--accent-rgb) / 0.15)

The surface scale flips with the theme: --surface-50 is always the background end and --surface-950 the text end, in light and dark mode alike. So background: var(--surface-50); color: var(--surface-900); reads well in both.

Present when the theme provides them ​

Omniscio sends each of these only when it can resolve it, and drops one that is malformed, so always give a fallback: var(--panel-radius, 8px).

TokenValueUse it for
--surface-50-rgbR G BThe same scale as three numbers, for transparency: rgb(var(--surface-50-rgb) / 0.8)
--surface-100-rgbR G B
--surface-200-rgbR G B
--surface-300-rgbR G B
--surface-400-rgbR G B
--surface-500-rgbR G B
--surface-600-rgbR G B
--surface-700-rgbR G B
--surface-800-rgbR G B
--surface-900-rgbR G B
--surface-950-rgbR G B
--status-agent-rgbR G BSomething running or working
--status-agent-strong-rgbR G BThe same, for text or icons on a light fill
--status-needs-you-rgbR G BSomething waiting for the user
--status-needs-you-strong-rgbR G BThe same, stronger
--status-error-rgbR G BErrors and failures
--status-error-strong-rgbR G BThe same, stronger
--status-ready-rgbR G BDone, healthy, ready
--status-question-rgbR G BA question for the user (fill)
--status-question-text-rgbR G BA question for the user (text)
--status-approval-rgbR G BSomething awaiting approval
--status-ember-400-rgbR G BWaiting on capacity (light)
--status-ember-500-rgbR G BWaiting on capacity
--status-ember-600-rgbR G BWaiting on capacity (strong)
--font-family-bodyfont stackBody text
--font-family-brandfont stackHeadings that carry the Omniscio look
--font-family-monofont stackCode, ids, numbers in tables
--app-font-sizelengthThe user's base font size
--panel-radiuslengthCorner radius of cards and panels
--on-accent-colorcolourText drawn on top of the accent colour
--on-accent-text-shadowshadowText shadow for text on the accent colour
--on-accent-icon-shadowshadowShadow for icons on the accent colour
--btn-accent-fillR G BFill of a primary button
--panel-bgcolourThe theme's panel fill — a translucent white in Glassmorphism, solid in flat themes. Paint it over your own surface colour so a panel reads as glass: background-image: linear-gradient(var(--panel-bg), var(--panel-bg))
--panel-bg-hovercolourThe panel fill on hover
--panel-border-colorcolourThe panel hairline. Carries the -color suffix because several plugins already define a panel-border property of their own
--app-glow-1colourFirst background-wash colour. transparent in every theme that paints no wash, so painting it is always safe
--app-glow-2colourSecond background-wash colour

A name that is not on this page is never set, so var() on it silently falls back (or resolves to nothing). Don't invent token names.

Starter stylesheet ​

Copy this into your panel's <style> and build from it. It uses only the tokens above, with fallbacks that match the dark theme for the instant before tokens arrive.

css
:root {
  color-scheme: light dark;
}

body {
  margin: 0;
  padding: 16px;
  background: var(--surface-50, #09090b);
  color: var(--surface-900, #f4f4f5);
  font-family: var(--font-family-body, system-ui, sans-serif);
  font-size: var(--app-font-size, 14px);
}

h1,
h2 {
  font-family: var(--font-family-brand, var(--font-family-body, system-ui, sans-serif));
  color: var(--surface-950, #fafafa);
}

.card {
  background: var(--surface-100, #18181b);
  border: 1px solid var(--surface-300, #3f3f46);
  border-radius: var(--panel-radius, 8px);
  padding: 12px;
}

.muted {
  color: var(--surface-600, #a1a1aa);
}

button.primary {
  background: rgb(var(--btn-accent-fill, var(--accent-rgb, 99 102 241)));
  color: var(--on-accent-color, #ffffff);
  text-shadow: var(--on-accent-text-shadow, none);
  border: 0;
  border-radius: var(--panel-radius, 8px);
  padding: 6px 12px;
  cursor: pointer;
}

button.primary:hover {
  filter: brightness(1.08);
}

.badge-error {
  color: rgb(var(--status-error-strong-rgb, 239 68 68));
  background: rgb(var(--status-error-rgb, 239 68 68) / 0.12);
  border-radius: 999px;
  padding: 2px 8px;
}

code {
  font-family: var(--font-family-mono, ui-monospace, monospace);
}

Animations ​

Two plugin panels can each define an animation with the same name, and the browser keeps only one. Prefix your @keyframes names with your plugin id (@keyframes my-plugin-pulse) so yours is never replaced.

Omniscio Plugin SDK