@streamiq/themes

Optional CSS design tokens and small JS helpers for theme switching in Streamq apps.

No CSS-in-JS runtime — primary consumption is plain .css files via subpath exports.

Stable 1.0.x. Standalone — no @streamiq/* dependencies.

Install

npm install @streamiq/themes

Architecture

@streamiq/themes
├── css/                          Final `.css` bundles
│   ├── base.css                  Dark palette on :root (default)
│   ├── light.css                 Light preset (data-streamq-theme="light")
│   ├── high-contrast.css         High-contrast preset
│   └── player.css                Player-specific overrides
│
├── default/src/                  Token primitives composed into base.css
│   ├── tokens.css                Color / spacing / radius tokens
│   ├── motion.css                Transition durations / easings
│   └── typography.css            Font scale tokens
│
└── src/                          Tiny JS surface
    ├── index.ts                  Public exports
    ├── applyTheme.ts             applyTheme / injectThemeStylesheet / removeTheme
    ├── createTheme.ts            createTheme / themeToCSS
    ├── presets.ts                darkTheme / lightTheme / highContrastTheme
    └── theme.types.ts            StreamqTheme / StreamqTokens / CreateThemeOptions

Theme switching is attribute-driven — no runtime CSS injection required for the built-in presets. JS helpers exist for apps that need to generate themes dynamically.

CSS usage

import '@streamiq/themes/css/base.css';   // default dark palette on :root
import '@streamiq/themes/css/light.css';   // light preset

Switch theme via root attribute:

import { STREAMQ_THEME_ATTR, DEFAULT_THEME_ID } from '@streamiq/themes';

document.documentElement.setAttribute(STREAMQ_THEME_ATTR, 'light');
// omit attribute or use 'dark' for base.css defaults

Style your app with var(--streamq-*) tokens defined in the CSS files.

Subpath exports

| Path | Contents | |------|----------| | @streamiq/themes | JS helpers + presets | | @streamiq/themes/css/base.css | Dark :root palette | | @streamiq/themes/css/light.css | Light preset | | @streamiq/themes/default/tokens.css | Token primitives | | @streamiq/themes/default/motion.css | Motion tokens | | @streamiq/themes/default/typography.css | Typography tokens |

JavaScript API

| Export | Purpose | |--------|---------| | STREAMQ_THEMES_PACKAGE | Package id | | STREAMQ_THEME_ATTR | 'data-streamq-theme' — DOM attribute name | | DEFAULT_THEME_ID | 'dark' | | createTheme | Build a theme object from options | | themeToCSS | Convert theme → CSS string | | applyTheme | Apply theme to DOM element | | injectThemeStylesheet | Inject generated CSS | | removeTheme | Remove applied theme | | darkTheme, lightTheme, highContrastTheme | Built-in presets |

Types

| Type | Purpose | |------|---------| | StreamqTheme | Theme object shape | | StreamqTokens | Token map | | StreamqThemeId | 'dark' \| 'light' \| 'high-contrast' \| (string & {}) | | CreateThemeOptions | Factory options |

Dynamic theme example

import {
  applyTheme,
  createTheme,
  injectThemeStylesheet,
} from '@streamiq/themes';

const brand = createTheme({
  id: 'brand',
  tokens: { color: { primary: '#FF6500' } },
});

injectThemeStylesheet(brand);
applyTheme(document.documentElement, 'brand');

Token categories (CSS)

Variables follow --streamq-* naming:

| Category | Examples | |----------|----------| | Colors | --streamq-color-primary, --streamq-color-surface, --streamq-color-text, --streamq-color-border | | Controls | button, slider, focus ring | | Progress | track, played, buffered | | Overlays | scrim, error, loading | | Subtitles | background, text shadow | | Spacing / radius / typography | --streamq-space-*, --streamq-radius-* |

See css/base.css for the full token list.

Bundle size

| Budget | Limit | |--------|-------| | Full JS bundle | 150 B gzipped | | Default theme id import | 80 B |

CSS is loaded statically; size is whatever your bundler picks up.

Scripts

pnpm run build
pnpm run typecheck
pnpm run test
pnpm run lint

License

MIT