@aidex/admin-theme

Installation

pnpm add @aidex/admin-theme

npm install @aidex/admin-theme

The shared design-token foundation for the Aidex AI Control Center UI — @aidex/admin-elements, @aidex/admin-react, and the Angular/Vue hosting packages all style themselves entirely through the CSS custom properties this package defines. CSS-first by design: no components, no build step, no theme-detection JavaScript, and no runtime theme manager (no setTheme(), no getTheme(), no media-query listener, no localStorage).

Usage

Import the stylesheet once, globally, in your application:

import '@aidex/admin-theme/tokens.css';

<link rel="stylesheet" href="node_modules/@aidex/admin-theme/dist/tokens.css" />

That's the entire integration step. Every @aidex/admin-elements Shadow DOM root and every @aidex/admin-react component reads these tokens via var(--aidex-*, <fallback>) — CSS custom properties inherit through open Shadow DOM boundaries by default, so no additional wiring is needed on either package's side. Omitting this import still renders correctly: every consuming rule ships its own literal fallback value, matching the token's light-mode default.

Theme (light / dark / system)

Tokens are defined for three states, "system" (the OS/browser preference) being the unconfigured default:

• Light — the :root baseline, always active unless overridden.
• Dark via system preference — @media (prefers-color-scheme: dark), applied automatically when the OS/browser prefers dark and no explicit override is set.
• Dark via explicit override — set data-theme="dark" on a document ancestor (typically <html>) to force dark regardless of system preference; data-theme="light" forces light the same way.

<html data-theme="dark">
  <!-- forces dark regardless of OS preference -->
</html>

Choosing and persisting a theme (a toggle UI, localStorage, syncing with prefers-color-scheme) is an application-level concern — this package only supplies the tokens the data-theme attribute selects between, not a theme manager.

Programmatic access

import { ADMIN_THEME_TOKENS } from '@aidex/admin-theme';
import type { AdminThemeToken } from '@aidex/admin-theme';

ADMIN_THEME_TOKENS; // readonly ['--aidex-surface', '--aidex-text', ...]

ADMIN_THEME_TOKENS exists for the rare case where a consumer needs to read or set a token's value programmatically (e.g. element.style.setProperty(name, value), or building a var(${name}) string) without hardcoding the token-name spelling. It's kept in sync with tokens.css by this package's own tests — a parity check, not a second source of truth to trust independently of the CSS file.

Token categories

Every token lives in the --aidex-* namespace and is named for what it means (surface, text, semantic state), never for which component will use it:

| Category | Tokens | |---|---| | Surfaces | --aidex-surface, --aidex-surface-elevated, --aidex-surface-muted, --aidex-surface-input | | Text | --aidex-text, --aidex-text-secondary, --aidex-text-muted, --aidex-text-inverse | | Borders | --aidex-border, --aidex-border-subtle, --aidex-border-strong | | Brand / accent | --aidex-accent, --aidex-accent-hover, --aidex-accent-subtle | | Semantic states | --aidex-success, --aidex-warning, --aidex-danger, --aidex-info (each with a low-emphasis -subtle pairing for badges/chips) | | Focus | --aidex-focus-ring | | Operational status | --aidex-neutral, --aidex-active | | Typography | --aidex-font-sans, --aidex-font-mono, --aidex-font-size-sm/-base/-lg, --aidex-line-height-base | | Spacing (4px base unit) | --aidex-space-1 through --aidex-space-6 | | Radius / border width | --aidex-radius-sm/-md/-lg, --aidex-border-width | | Elevation | --aidex-shadow-sm, --aidex-shadow-md | | Overlay | --aidex-scrim (theme-invariant — a backdrop dim reads correctly over either theme) |

Semantic-state tokens are deliberately never the only signal a status uses in the packages that consume them — every consuming component pairs a token with a text label, not color alone.

Design notes

• Restrained by design, not by oversight. The typography scale stops at three sizes (sm/base/lg); the spacing scale is a single 4px-based progression; elevation is two steps. Consuming packages have evaluated whether a gap is genuine before proposing a new token — see @aidex/admin-react's and @aidex/admin-elements' own typography evaluation notes.
• No component styling lives here. This package draws no borders, no buttons, no cards — it only names and values CSS custom properties. Layout, component structure, and which tokens a given element actually uses are entirely @aidex/admin-elements'/@aidex/admin-react's concern.