Skip to Content
OrbixDocs
Block SDK · Guides

Match the Orbix theme

Style blocks with host --orbix-* CSS variables and read active theme metadata with useOrbixTheme.

Orbix supports four dark themes (obsidian, midnight, titanium, oled) and four light themes (paper, ivory, frost, sand), plus user-chosen accent colors. Blocks that hardcode dark hex backgrounds look out of place as soon as a user switches to paper or ivory.

Styling with --orbix-* CSS variables

The Orbix workspace sets CSS custom properties on :root whenever the user changes themes. Reference these variables in inline styles or CSS stylesheets, and always include a fallback value (var(--orbix-card-bg, #16171b)) so your block also renders cleanly in unit tests and the standalone dev playground.

Core tokens available across environments

The nine tokens below are set by both the Orbix host workspace and the standalone @orbixdocs/sdk/dev playground:

CSS variableRoleTypical dark fallbackTypical light fallback
--orbix-shell-bgApp chrome / outer background#0b0c0e#f4f4f5
--orbix-surface-bgPage / input surface background#101114#ffffff
--orbix-card-bgRaised block card surface#16171b#fafafa
--orbix-subtle-hoverHover fill for subtle buttons/rowsrgba(255, 255, 255, 0.06)rgba(0, 0, 0, 0.05)
--orbix-surface-borderCard and input border#2a2b32#e4e4e7
--orbix-text-primaryPrimary body and heading text#f4f4f5#18181b
--orbix-text-secondarySecondary labels and captions#a1a1aa#52525b
--orbix-accentActive accent color (monochrome by default)#ffffff#18181b
--orbix-subtle / --orbix-subtle-bgMuted fill behind pills or chipsrgba(255, 255, 255, 0.04)rgba(0, 0, 0, 0.03)

Additional host-only tokens

Inside the full Orbix workspace, PreferencesEngine also sets:

  • Surfaces & borders: --orbix-bg, --orbix-card, --orbix-card-hover, --orbix-border, --orbix-border-hover, --orbix-topbar-bg
  • Typography: --orbix-text, --orbix-text-muted, --orbix-text-dim, --orbix-text-body, --orbix-text-placeholder, --orbix-font
  • Accent variants: --orbix-accent-hover, --orbix-accent-fg, --orbix-on-accent, --orbix-accent-text, --orbix-accent-subtle, --orbix-accent-border

Differences in HTML / polyglot frames and the dev harness

  • Standalone dev harness (@orbixdocs/sdk/dev): Injects only the 9 core variables above across 4 themes (obsidian, paper, ivory, frost). Any reference to --orbix-card-hover, --orbix-text-dim, or --orbix-accent-text uses your CSS fallback in the harness.
  • HTML / polyglot frames (OrbixHtmlFrame): Injects --orbix-bg, --orbix-surface-bg, --orbix-card-bg, --orbix-card-hover, --orbix-subtle, --orbix-text-primary, --orbix-text-secondary, --orbix-text-dim, --orbix-surface-border, --orbix-border-hover, --orbix-accent, --orbix-font, and --orbix-mono, not --orbix-text-muted, --orbix-shell-bg, or --orbix-accent-text.

Reading theme state in JavaScript (useOrbixTheme)

When rendering <canvas>, SVG charts, or third-party components that need resolved color values or a light/dark boolean in JavaScript, call useOrbixTheme():

src/ThemedStatusBlock.tsx
import {
  defineBlock,
  useOrbixTheme,
  type BlockRenderProps,
} from '@orbixdocs/sdk';

export default defineBlock({
  manifest: {
    id: 'acme.theme-aware-card',
    name: 'Theme Aware Card',
    version: '1.0.0',
    sdk: '^3.0.0',
  },
  component(_props: BlockRenderProps) {
    const { themeId, isDark, accent, tokens } = useOrbixTheme();

    return (
      <div
        style={{
          padding: 16,
          borderRadius: 12,
          background: 'var(--orbix-card-bg, #16171b)',
          border: '1px solid var(--orbix-surface-border, #2a2b32)',
          color: 'var(--orbix-text-primary, #f4f4f5)',
          fontFamily: 'var(--orbix-font, inherit)',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'space-between',
        }}
      >
        <div>
          <div style={{ fontWeight: 600 }}>Active theme: {themeId}</div>
          <div
            style={{
              fontSize: 12,
              color: 'var(--orbix-text-secondary, #a1a1aa)',
            }}
          >
            Mode: {isDark ? 'dark' : 'light'} · Border token: {tokens.border}
          </div>
        </div>

        <span
          style={{
            display: 'inline-block',
            width: 12,
            height: 12,
            borderRadius: '50%',
            background: accent,
          }}
        />
      </div>
    );
  },
});

useOrbixTheme() returns:

  • themeId — 'obsidian' | 'midnight' | 'titanium' | 'oled' | 'paper' | 'ivory' | 'frost' | 'sand'
  • resolvedMode — 'dark' | 'light'
  • isDark and isLight — convenience booleans
  • accent — active accent color string
  • tokens — { bg, card, cardHover, subtle, border, text, textMuted, accent } CSS variable references

On this page