Skip to content
Xng UI
Docs CDK Components Tools Contribute About

Styles

@xngui/styles
@xngui/styles

CSS primitives → semantic roles → states. TypeScript token steps in @xngui/core.

Overview

Token Pipeline

Tokens flow from raw primitives to semantic roles your components consume. Each step builds on the previous — follow the order when authoring custom CSS.

Best path for most apps: primitives → semantic light & dark → scale & states. Add field and component layers only when you need them.

Primitives

primitives/--x-primary-500: oklch(0.58 0.12 212);

Semantic Light

semantic/light.css--x-primary: var(--x-primary-500);

Semantic Dark

semantic/dark.css.dark { --x-primary: var(--x-primary-400); }

Scale

scale/--x-control-height: var(--x-size-height-md);

Field

field.css.x-field[data-look="outline"] { … }

States

states/.x-focusable:focus-visible { outline: … }

Components

libs/components/**--x-button-height: var(--x-control-height);

Dark semantic tokens pair with runtime appearance — see the Themes doc for light / dark / system mode.

Imports

Toggle optional entry points to build your stylesheet. Foundation is required; everything else layers on top for resets, Tailwind utilities, or icons.

styles.css
@import '@xngui/styles';
@import '@xngui/styles/base';
@import '@xngui/styles/tailwind';
Foundation Primitives Semantic Roles States And ScrollbarStart here for every app — primitives, semantic roles, states, and scrollbar styling in one import.
    • Optional CSS reset for a clean slate before design tokens.Optional CSS reset for a clean slate before design tokens. Not required when you already normalize base styles.
    • Token Backed Bg Text And Border UtilitiesRecommended when you use Tailwind — token-backed background, text, and border utilities aligned with the design system.
    • Icon font for icon componentsOptional icon font for icon components. Skip if you load icons another way or use inline SVG only.

    Related docs

    Appearance mode, runtime palette switching, and CSS @import presets live on the Themes foundation doc.

    Control scale

    Control scale

    Map size tiers and density to shared control height, padding, and radius tokens. Size and density types in core.

    styles.css
    @import '@xngui/styles/scale';

    Density at size md

    Padding and gap only — type size stays at md.

    compact
    standard
    comfortable

    Size tiers at standard density

    Height, type, and icon scale — orthogonal to density.

    --x-size-height-xs
    --x-size-height-sm
    --x-size-height-md
    --x-size-height-lg
    --x-size-height-xl

    Colors

    All swatches on this page are live — they reflect palette {palette} in {mode} mode. Switch presets on the Themes doc or the navbar theme picker.

    Palette CSS imports

    Primitive palette overrides ship as optional CSS files under @xngui/styles/themes — one file per preset, imported after the foundation layer.

    Use CSS @import when your brand palette is fixed. Use XPaletteService when users pick presets in the app.

    CSS @import

    Fixed palette at build time

    • Zero JS — bundler ships only the theme file you import
    • Best for production apps with a known brand color

    Runtime service

    User-selectable presets

    • XPaletteService injects a :root block via <style id="x-palette">
    • Persists the user’s choice across reloads
    Themes
    styles.css
    @import '@xngui/styles';@import '@xngui/styles/themes/nature/ocean';* Primitives only — pair with XThemeService for light  dark semantics. *

    Semantic Roles

    Theme slots per role — solid, text, border, hover, and subtle fills components consume.

    Brand

    --x-primary
    Background--x-primary
    Text--x-primary-foreground
    Border--x-primary-border
    Hover--x-primary-hover
    Subtle--x-primary-subtle

    Secondary

    --x-secondary
    Background--x-secondary
    Text--x-secondary-foreground
    Border--x-secondary-border
    Hover--x-secondary-hover
    Subtle--x-secondary-subtle

    Accent

    --x-accent
    Background--x-accent
    Text--x-accent-foreground
    Border--x-accent-border
    Hover--x-accent-hover
    Subtle--x-accent-subtle

    Neutral

    --x-neutral
    Background--x-neutral
    Text--x-neutral-foreground
    Border--x-neutral-border
    Hover--x-neutral-hover
    Subtle--x-neutral-subtle

    Success

    --x-success
    Background--x-success
    Text--x-success-foreground
    Border--x-success-border
    Hover--x-success-hover
    Subtle--x-success-subtle

    Warning

    --x-warning
    Background--x-warning
    Text--x-warning-foreground
    Border--x-warning-border
    Hover--x-warning-hover
    Subtle--x-warning-subtle

    Danger

    --x-danger
    Background--x-danger
    Text--x-danger-foreground
    Border--x-danger-border
    Hover--x-danger-hover
    Subtle--x-danger-subtle

    Info

    --x-info
    Background--x-info
    Text--x-info-foreground
    Border--x-info-border
    Hover--x-info-hover
    Subtle--x-info-subtle

    Primitive Ramps

    Primitive ramps swap with the active palette — OKLCH steps 50–950 for one-off tints and bindings.

    --x-white
    --x-black

    Brand

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Secondary

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Accent

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Neutral

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Success

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Warning

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Danger

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Info

    50
    100
    200
    300
    400
    500
    600
    700
    800
    900
    950

    Surfaces Chrome

    Neutral page chrome — grouped by surface role. Fills and foregrounds track the active palette and appearance mode.

    Page

    Base canvas and default body text

    --x-background
    --x-foreground

    Card

    Elevated surfaces — containers, panels, and tiles

    --x-card
    --x-card-foreground
    --x-card-border
    --x-card-hover

    Popover

    Floating layers — menus, dialogs, and tooltips

    --x-popover
    --x-popover-foreground

    Muted

    De-emphasized fills and secondary copy.

    --x-muted
    --x-muted-foreground

    Borders & inputs

    Dividers, control outlines, and focus rings

    --x-border
    --x-input
    --x-ring

    Selection

    Active and highlighted item chrome

    --x-selected
    --x-selected-foreground

    Typography

    Type Scale

    Font sizes with paired line heights — steps match the text size union.

    • Aa — xs --x-text-xs
    • Aa — sm --x-text-sm
    • Aa — md --x-text-md
    • Aa — lg --x-text-lg
    • Aa — xl --x-text-xl
    • Aa — 2xl --x-text-2xl
    • Aa — 3xl --x-text-3xl

    Font Weights

    Thin through black — each step maps to a --x-weight-* token.

    • Aa — thin --x-weight-thin
    • Aa — extralight --x-weight-extralight
    • Aa — light --x-weight-light
    • Aa — normal --x-weight-normal
    • Aa — medium --x-weight-medium
    • Aa — semibold --x-weight-semibold
    • Aa — bold --x-weight-bold
    • Aa — extrabold --x-weight-extrabold
    • Aa — black --x-weight-black

    Spacing

    Spacing Scale

    4px-based gap and margin steps — same scale Tailwind uses.

    • 0.25rem · 4px--x-spacing-1
    • 0.5rem · 8px--x-spacing-2
    • 0.75rem · 12px--x-spacing-3
    • 1rem · 16px--x-spacing-4
    • 1.5rem · 24px--x-spacing-6
    • 2rem · 32px--x-spacing-8
    • 3rem · 48px--x-spacing-12
    • 4rem · 64px--x-spacing-16

    Radius Shadow

    Border Radius

    Corner tiers from xs through full — use on cards, chips, and inputs.

    • xs--x-radius-xs0.125rem · 2px
    • sm--x-radius-sm0.25rem · 4px
    • md--x-radius-md0.375rem · 6px
    • lg--x-radius-lg0.5rem · 8px
    • xl--x-radius-xl0.75rem · 12px
    • 2xl--x-radius-2xl1rem · 16px
    • full--x-radius-full9999px · —

    Shadows

    Elevation shadows from subtle chrome to floating overlays.

    Shadow stepsmmdlgxl2xl
    • 2xs--x-shadow-2xs
    • xs--x-shadow-xs
    • sm--x-shadow-sm
    • md--x-shadow-md
    • lg--x-shadow-lg
    • xl--x-shadow-xl
    • 2xl--x-shadow-2xl

    Z Index

    Stacking Layers

    Isometric stack — wider layers sit below; each step up narrows, shifts, and floats above the last.

    • toast--x-z-toastz-index 50
    • fab--x-z-fabz-index 40
    • modal--x-z-modalz-index 40
    • overlay--x-z-overlayz-index 30
    • sticky--x-z-stickyz-index 20
    • dropdown--x-z-dropdownz-index 10

    Motion

    Motion Composer

    Preview runs much slower so you can study each curve — duration stays on your selection; recipe values stay exact.

    transition: transform var(--x-duration-normal) var(--x-ease-in-out);200ms · cubic-bezier(0.4, 0, 0.2, 1)

    Duration Lanes

    Easing Curves

    States

    Live Samples

    Click a selector chip to highlight its live sample below — same order, same state id.

    • Disabled[disabled], [aria-disabled="true"], [data-disabled], [data-state="disabled"], .x-disabledDisabled Usage
    • Readonly[readonly], .x-readonlyVisible Not Editable
      Readonly
    • Invalid[aria-invalid="true"], .x-invalidError Border Ring
      Invalid Field
    • Loading[aria-busy="true"], .x-loadingSpinner No Dimming
    • Focus.x-focusable:focus-visibleShared Focus Ring
    • Selected.x-selectedPressed Active Look

    Tailwind

    Role Utilities

    Optional Tailwind bridge maps tokens to bg-*, text-*, and border-* utilities per semantic role.

    Background

    Brandbg-primary
    Secondarybg-secondary
    Accentbg-accent
    Neutralbg-neutral
    Successbg-success
    Warningbg-warning
    Dangerbg-danger
    Infobg-info
    bg-primary-300
    bg-secondary-400
    bg-danger-200
    bg-neutral-100

    Text

    Brandtext-primary
    Secondarytext-secondary
    Accenttext-accent
    Neutraltext-neutral
    Successtext-success
    Warningtext-warning
    Dangertext-danger
    Infotext-info
    text-primary-600
    text-secondary-500
    text-danger-400
    text-neutral-700

    Border

    Brandborder-primary
    Secondaryborder-secondary
    Accentborder-accent
    Neutralborder-neutral
    Successborder-success
    Warningborder-warning
    Dangerborder-danger
    Infoborder-info
    border-primary-300
    border-accent-500
    border-danger-400
    border-neutral-300