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 variable | Role | Typical dark fallback | Typical light fallback |
|---|---|---|---|
--orbix-shell-bg | App chrome / outer background | #0b0c0e | #f4f4f5 |
--orbix-surface-bg | Page / input surface background | #101114 | #ffffff |
--orbix-card-bg | Raised block card surface | #16171b | #fafafa |
--orbix-subtle-hover | Hover fill for subtle buttons/rows | rgba(255, 255, 255, 0.06) | rgba(0, 0, 0, 0.05) |
--orbix-surface-border | Card and input border | #2a2b32 | #e4e4e7 |
--orbix-text-primary | Primary body and heading text | #f4f4f5 | #18181b |
--orbix-text-secondary | Secondary labels and captions | #a1a1aa | #52525b |
--orbix-accent | Active accent color (monochrome by default) | #ffffff | #18181b |
--orbix-subtle / --orbix-subtle-bg | Muted fill behind pills or chips | rgba(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-textuses 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():
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'isDarkandisLight— convenience booleansaccent— active accent color stringtokens—{ bg, card, cardHover, subtle, border, text, textMuted, accent }CSS variable references