Styrox

AI-native design token engine with auto-discovery component registry.

Styrox is a layered SCSS design system that uses CSS @layer cascade management, a 3-tier token architecture, and a component registry that auto-discovers what's available at build time. Built for AI-assisted development with MCP server support (coming soon).

Quick Start

npm install styrox

# See what's available
npx styrox status

# Scaffold a theme in your project
npx styrox init

# Add a new component
npx styrox add tooltip

What's Inside

Token System (3-tier)

Tokens flow in one direction: Primitives > Semantics > Component tokens. No skipping tiers.

--primitive-color-blue-600          # Raw value
    |
--semantic-color-brand-default      # Intent mapping
    |
--component-button-primary-bg       # Component API

Primitives (raw values):

• Color (5 palettes, 50+ shades), Spacing (18 steps), Radius (9 values), Typography (families, sizes, weights, line-heights)

Semantics (intent mappings):

• Color (brand, surface, text, border, feedback, interactive), Spacing (layout, component, inline, stack), Typography (by role), Radius, Size, Shadow

Component tokens (public theming API):

• Each component exposes --component-{name}-* variables. Override these to theme.

Layer System

@layer tokens, base, utilities, components, themes, page, adapters;

| Layer | Purpose | |-------|---------| | tokens | CSS custom properties (:root blocks) | | base | Browser reset + root variables | | utilities | Atomic helper classes | | components | Structural component styles | | themes | [data-theme] overrides | | page | Runtime page-scoped overrides | | adapters | Framework bridges (PrimeNG, Angular) |

Components

| Component | Status | Adapters | |-----------|--------|----------| | Button | Stable | PrimeNG v17 | | Badge | Stable | PrimeNG v17 | | Card | Stable | PrimeNG v17 |

More components ship as minor version bumps. The registry picks them up automatically.

Themes

• Light (default)
• Dark ([data-theme="dark"])

CLI

styrox status

Shows all available components, tokens, adapters, layers, and themes.

styrox status              # Human-readable
styrox status --json       # Machine-readable (for tooling)

styrox init

Scaffolds a theme folder in your project with override files.

styrox init
styrox init --adapter primeng

styrox add <component>

Scaffolds a new component with the correct file structure and naming conventions. Auto-registers it in the component registry.

styrox add tooltip

Creates:

scss/components/tooltip/
  _index.scss
  _tooltip.variables.scss    # Component tokens (theming API)
  _tooltip.scss              # Structural styles (BEM)

styrox build-registry

Regenerates registry.json from the current file structure. Run after manually adding or removing components.

Component Registry

The registry auto-discovers components, tokens, adapters, layers, and themes from the file structure. No manual lists to maintain.

How it works:

• A component is registered if scss/components/{name}/_index.scss exists
• Status is derived from file completeness (or overridden via _meta.json)
• Tokens are scanned from scss/tokens/_*.scss files
• Adapters are scanned from scss/adapters/{framework}/v{N}/ folders

Status tags:

• stable - all required files present, production-ready
• beta - functional but may change
• wip - in progress (override via _meta.json: {"status": "wip"})

Output: registry.json - consumed by CLI, MCP server, Playground, and AI tooling.

Adding Components

Every component follows the same structure:

scss/components/{name}/
  _index.scss                    # Imports variables + styles
  _{name}.variables.scss         # @layer components { :root { --component-{name}-* } }
  _{name}.scss                   # @layer components { .ds-{name} { ... } }

Rules:

1. Structural styles reference ONLY --component-* tokens (never primitives/semantics directly)
2. Variables file maps semantic tokens to component tokens
3. Class prefix: .ds-{name}, BEM modifiers: .ds-{name}--{modifier}, elements: .ds-{name}__{element}
4. All styles wrapped in @layer components { }

Adding an adapter:

scss/adapters/{framework}/v{N}/_{name}.scss

Each adapter file exports a @mixin styles() wrapped in @layer adapters { }.

Architecture

styrox
  scss/                    # Source SCSS
    tokens/                # 3-tier token files
    base/                  # Reset + root contract
    utilities/             # Atomic helpers
    components/            # Auto-discovered components
    themes/                # Light/dark theme overrides
    adapters/              # Framework bridges
    config/                # Build config (adapter versions)
    _layer-order.scss      # Layer declaration (single source of truth)
  src/                     # TypeScript tooling
    registry/              # Auto-discovery scanner + generator
    cli/                   # CLI commands
  registry.json            # Auto-generated manifest
  dist/
    css/                   # Compiled CSS output
    *.js                   # Compiled CLI + registry API

Programmatic API

import { generateRegistry, scanComponents, scanTokens } from 'styrox';

// Full registry
const registry = generateRegistry('/path/to/project');

// Individual scans
const components = scanComponents('/path/to/project');
const tokens = scanTokens('/path/to/project');

License

MIT