```
### Alert Dialog Component
Base class: `.alert-dialog`
Description: Constrained-width modal variant for confirmations and destructive actions. Reuses the existing modal backdrop/overlay patterns.
Tier-aware: yes
Variants: `alert-dialog-icon-danger`, `alert-dialog-icon-info`, `alert-dialog-icon-warning`
Children: `alert-dialog-actions`, `alert-dialog-body`, `alert-dialog-icon`, `alert-dialog-title`
```html
…
…
…
```
### Badge, Pill, and Tag Components
Base class: `.avatar`
Description: Badge, Pill, and Tag Components
Tier-aware: yes
Variants: `avatar-`, `avatar-cameo`, `avatar-group`, `badge`, `badge-`, `badge-pill`, `badge-primary`, `chip`, `chip-`, `close`, `separator`, `separator-label`, `separator-thick`, `separator-vertical`, `tag`
```html
New
```
### Button Components
Base class: `.btn`
Description: Base button uses --relief-* variables for automatic relief switching. Semantic variants (primary, danger, success) override as needed.
Tier-aware: yes
Variants: `btn-`, `btn-danger`, `btn-ghost`, `btn-group`, `btn-outline`, `btn-primary`, `btn-secondary`, `btn-success`, `fab`, `fab-bottom-left`, `fab-bottom-right`, `fab-controlled`, `fab-extended`, `fab-label`, `fab-lg`, `fab-sm`
Children: `btn-icon`
```html
```
### Callout & Blockquote Components
Base class: `.callout`
Description: Left-bordered content boxes for documentation, tips, warnings, and quotes.
Tier-aware: yes
Variants: `blockquote`, `blockquote-footer`, `callout-`, `callout-important`, `callout-note`, `callout-tip`
Children: `callout-content`, `callout-title`
```html
…
…
```
### Card Components
Base class: `.card`
Description: Base cards use --relief-* variables for automatic relief switching. Beveled variant overrides as needed.
Tier-aware: yes
Variants: `card-beveled`, `card-flat`, `card-hover`, `card-image`
Children: `card-body`, `card-footer`, `card-header`
```html
Title
Content
```
### Carousel Component
Base class: `.carousel`
Description: Horizontal slide container with navigation buttons and indicator dots.
Tier-aware: yes
Variants: `carousel-next`, `carousel-prev`
Children: `carousel-dot`, `carousel-dots`, `carousel-slide`, `carousel-track`
```html
Slide 1
Slide 2
```
### Close Button
Base class: `.close`
Description: Reusable dismiss trigger for alerts, toasts, drawers, and modals. X rendered via ::before/::after rotated lines (no icon dependency).
Sizes: `close-lg`, `close-sm`
```html
…
```
### Code Components
Base class: `.code`
Description: Styled inline code spans and preformatted code blocks. Complements the base `code` and `pre` element styles in _typography.scss.
Tier-aware: yes
Variants: `code-block`, `code-block-numbered`, `code-block-sm`, `code-line`
```html
…
```
### Collapsible Component
Base class: `.collapsible`
Description: Single-panel expand/collapse. Simpler than accordion — no item grouping.
Tier-aware: yes
Variants: `collapsible-bordered`
Children: `collapsible-content`, `collapsible-trigger`
```html
Content
```
### Color Picker Component
Base class: `.color-picker`
Description: HSV color selection with 2D area, hue slider, optional alpha, and swatches.
Tier-aware: yes
Variants: `color-picker-area-thumb`, `color-picker-slider-thumb`, `color-picker-swatch`
Children: `color-picker-alpha`, `color-picker-area`, `color-picker-hue`, `color-picker-input`, `color-picker-popup`, `color-picker-preview`, `color-picker-swatches`, `color-picker-trigger`
```html
```
### Combobox / Autocomplete Component
Base class: `.combobox`
Description: Text input with filterable dropdown list. Tier-aware surfaces for the dropdown popup.
Tier-aware: yes
Children: `combobox-empty`, `combobox-input`, `combobox-listbox`, `combobox-option`
```html
```
### Form Input Components
Base class: `.input`
Description: Text inputs, selects, textareas, checkboxes, radios, and input groups.
Tier-aware: yes
Variants: `checkbox`, `file-input`, `file-input-lg`, `file-input-sm`, `form-validated`, `input-`, `input-group`, `input-help`, `input-number`, `input-number-step`, `radio`, `range`, `range-lg`, `range-sm`, `select`, `textarea`
Sizes: `input-lg`, `input-sm`
Children: `input-label`
```html
```
### Layout Components
Base class: `.app-layout`
Description: Reusable application layout primitives: sidebar, header, footer, and grid shell. Consumed by the docs site and available to all consumers. Uses BEM naming (__nav, __link, etc.) for sidebar children — intentional for multi-element structures where parent/child coupling must be explicit.
Variants: `app-header`, `page-footer`, `sidebar`
Children: `sidebar__chevron`, `sidebar__link`, `sidebar__list`, `sidebar__nav`, `sidebar__section--expanded`, `sidebar__section-header`
```html
…
…
…
```
### List & Accordion Components
Base class: `.accordion`
Description: Styled lists and collapsible accordion panels.
Tier-aware: yes
Variants: `accordion-flush`, `list`, `list-bordered`, `list-flush`, `list-hover`, `list-item`
Children: `accordion-body`, `accordion-header`, `accordion-item`
```html
Title
Content
```
### Menu Components
Base class: `.popover`
Description: Popovers and dropdown menus. Scope: This file provides styles for dropdown menus (.dropdown) and generic popovers (.popover). Context menus are NOT included here — they are handled by the contextmenu enhancer with its own activation mechanism and positioning logic.
Tier-aware: yes
Variants: `dropdown`, `dropdown-divider`, `dropdown-end`, `dropdown-header`, `dropdown-item`, `dropdown-menu`, `dropdown-toggle`, `popover-bottom`, `popover-left`, `popover-right`, `popover-top`
Sizes: `popover-lg`, `popover-sm`
Children: `popover-body`, `popover-header`
```html
```
### Scroll Area Component
Base class: `.scroll-area`
Description: Custom scrollbar container with tier-aware thumb colors. Extends the base scrollbar styling for component-level opt-in.
Variants: `scroll-area-hidden`
Sizes: `scroll-area-sm`
```html
```
### Segmented Control Component
Base class: `.segmented-control`
Description: Tier-aware segmented toggle consuming --relief-*, --finish-*, and --accent-* tokens. Inline group of mutually exclusive options.
Uses BEM naming (__option) for the child elements — intentional for multi-element structures where parent/child coupling must be explicit.
Tier-aware: yes
Sizes: `segmented-control-lg`, `segmented-control-sm`
Children: `segmented-control-icon`, `segmented-control__option`
```html
…
…
```
### Table Components
Base class: `.row-bg`
Description: Data tables with striping, hover, modifiers, and relief-aware styling.
Tier-aware: yes
Variants: `row-overlay`, `table`, `table-bordered`, `table-compact`, `table-fixed`, `table-inlay`, `table-panel`, `table-relaxed`, `table-responsive`, `table-scroll`
```html
```
### Toggle Component
Base class: `.toggle`
Description: Tier-aware toggle switch consuming --relief-*, --finish-*, and --state-* tokens. Renders as a track with a sliding thumb pseudo-element. ARIA: use role="switch" with aria-checked and tabindex="0".
Tier-aware: yes
```html
```
### Tree View Component
Base class: `.tree`
Description: Hierarchical tree structure with expandable branches and selectable nodes.
Tier-aware: yes
Variants: `tree-branch`, `tree-indent`, `tree-leaf`, `tree-node-content`
Children: `tree-node`, `tree-toggle`
```html
Folder
File
```
---
## Utilities
### layout
Display, flexbox, grid, and positioning (responsive)
- **display**: block, contents, flex, grid, hidden, inline, inline-block, inline-flex, inline-grid
- **flex**: flex-1, flex-auto, flex-col, flex-col-reverse, flex-initial, flex-none, flex-nowrap, flex-row, flex-row-reverse, flex-wrap, grow, grow-0, shrink, shrink-0
- **grid**: cols: grid-cols-{1-12}, span: col-span-{1-12}, rows: grid-rows-{1-6}, row_span: row-span-{1-6}, special: col-span-full
- **position**: absolute, bottom-0, fixed, inset-0, left-0, relative, right-0, static, sticky, top-0
- **alignment**: items-baseline, items-center, items-end, items-start, items-stretch, justify-around, justify-between, justify-center, justify-end, justify-evenly, justify-start, self-auto, self-center, self-end, self-start, self-stretch
- **text_align**: text-center, text-justify, text-left, text-right
- **aspect**: aspect-auto, aspect-photo, aspect-portrait, aspect-ratio, aspect-ratio-photo, aspect-ratio-square, aspect-ratio-video, aspect-ratio>iframe, aspect-ratio>img, aspect-ratio>video, aspect-square, aspect-video, aspect-wide
- **z_index**: z-0, z-10, z-20, z-30, z-40, z-50, z-auto, z-drawer, z-dropdown, z-modal, z-popover, z-skip-link, z-toast, z-tooltip
- **order**: order-first, order-last, order-none
- **misc**: container, invisible, visible
### sizing
Width, height, and max-width (responsive)
- **width_fractions**: w-fit, w-full, w-max, w-min, w-px, w-screen
- **width_fixed**: pattern: w-{step}, range: 0–96
- **height_fractions**: h-fit, h-full, h-max, h-min, h-px, h-screen
- **height_fixed**: pattern: h-{step}, range: 0–96
- **min_height**: min-h-0, min-h-full, min-h-screen
- **max_width**: max-w-2xl, max-w-3xl, max-w-4xl, max-w-5xl, max-w-6xl, max-w-7xl, max-w-full, max-w-lg, max-w-md, max-w-prose, max-w-sm, max-w-xl, max-w-xs
### spacing
Padding, margin, and gap utilities (responsive)
- **padding**: pattern: p-{step}, axes: px,py, dirs: pt,pr,pb,pl, range: 0–64
- **margin**: pattern: m-{step}, axes: mx,my, dirs: mt,mr,mb,ml, range: 0–64
- **gap**: pattern: gap-{step}, axes: gap-x,gap-y, range: 0–24
- **auto**: ml-auto, mr-auto, mx-auto
### typography
Font size, weight, tracking, and text utilities
- **sizes**: text-2xl, text-2xs, text-3xl, text-4xl, text-5xl, text-base, text-lg, text-sm, text-xl, text-xs
- **weights**: font-black, font-bold, font-extrabold, font-light, font-medium, font-regular, font-semibold
- **families**: font-display, font-mono, font-sans, font-serif
- **letter_spacing**: tracking-display, tracking-elegant, tracking-inscriptional, tracking-normal, tracking-refined, tracking-tight, tracking-tighter, tracking-wide, tracking-wider, tracking-widest
- **line_height**: leading-loose, leading-none, leading-normal, leading-relaxed, leading-snug, leading-tight
### visual
Borders, backgrounds, shadows, opacity, transitions, transforms, animations
- **backgrounds**: bg-accent, bg-accent-secondary, bg-error, bg-error-subtle, bg-fixed, bg-gradient-accent, bg-info, bg-info-subtle, bg-mesh, bg-success, bg-success-subtle, bg-surface, bg-surface-1, bg-surface-2, bg-surface-3, bg-surface-4, bg-warning, bg-warning-subtle
- **borders**: border, border-0, border-2, border-accent, border-b, border-l, border-r, border-strong, border-subtle, border-t
- **border_radius**: rounded, rounded-2xl, rounded-3xl, rounded-full, rounded-lg, rounded-md, rounded-none, rounded-sm, rounded-xl
- **shadows**: shadow, shadow-2xl, shadow-inner, shadow-lg, shadow-md, shadow-none, shadow-sm, shadow-xl
- **opacity**: pattern: opacity-{0-100}, values: opacity-0,opacity-10,opacity-100,opacity-20,opacity-25,opacity-30,opacity-40,opacity-5,opacity-50,opacity-60,opacity-70,opacity-75,opacity-80,opacity-90,opacity-95
- **transitions**: duration-fast, duration-normal, duration-slow, duration-slower, ease-in, ease-in-out, ease-out, transition, transition-all, transition-none
- **transforms**: -rotate-1, -rotate-12, -rotate-180, -rotate-2, -rotate-3, -rotate-45, -rotate-6, -rotate-90, -skew-x-1, -skew-x-12, -skew-x-2, -skew-x-3, -skew-x-6, -skew-y-1, -skew-y-12, -skew-y-2, -skew-y-3, -skew-y-6, -translate-x-1, -translate-x-10, -translate-x-12, -translate-x-16, -translate-x-1\/2, -translate-x-2, -translate-x-20, -translate-x-24, -translate-x-3, -translate-x-32, -translate-x-4, -translate-x-40, -translate-x-48, -translate-x-5, -translate-x-6, -translate-x-64, -translate-x-8, -translate-x-full, -translate-y-1, -translate-y-10, -translate-y-12, -translate-y-16, -translate-y-1\/2, -translate-y-2, -translate-y-20, -translate-y-24, -translate-y-3, -translate-y-32, -translate-y-4, -translate-y-40, -translate-y-48, -translate-y-5, -translate-y-6, -translate-y-64, -translate-y-8, -translate-y-full, rotate-0, rotate-1, rotate-12, rotate-180, rotate-2, rotate-3, rotate-45, rotate-6, rotate-90, scale-0, scale-100, scale-105, scale-110, scale-125, scale-150, scale-50, scale-75, scale-90, scale-95, skew-x-1, skew-x-12, skew-x-2, skew-x-3, skew-x-6, skew-y-1, skew-y-12, skew-y-2, skew-y-3, skew-y-6, translate-x-0, translate-x-1, translate-x-10, translate-x-12, translate-x-16, translate-x-1\/2, translate-x-2, translate-x-20, translate-x-24, translate-x-3, translate-x-32, translate-x-4, translate-x-40, translate-x-48, translate-x-5, translate-x-6, translate-x-64, translate-x-8, translate-x-full, translate-y-0, translate-y-1, translate-y-10, translate-y-12, translate-y-16, translate-y-1\/2, translate-y-2, translate-y-20, translate-y-24, translate-y-3, translate-y-32, translate-y-4, translate-y-40, translate-y-48, translate-y-5, translate-y-6, translate-y-64, translate-y-8, translate-y-full
- **animations**: animate-bounce, animate-none, animate-ping, animate-pulse, animate-spin
### Responsive
Breakpoint prefix before class: `md:flex-col`
Covered: display, flex, grid, gap, padding, margin, sizing, text-align
---
## JavaScript API
### Initialization
```js
import { initSoltana } from "soltana-ui";
const sol = initSoltana({ theme: "dark", relief: "glassmorphic", finish: "frosted" });
```
### Instance Methods
- `getState()` → SoltanaConfig
- `setTheme(name)` — Switch active theme
- `setRelief(name)` — Switch active relief
- `setFinish(name)` — Switch active finish
- `setOverrides(record)` — Inject CSS custom properties
- `removeOverrides(keys)` — Remove CSS custom property overrides
- `registerTheme(name, options)` — Runtime theme from seed colors
- `registerRelief(name, options)` — Runtime relief from token map
- `registerFinish(name, options)` — Runtime finish from token map
- `reinitEnhancers()` — Destroy and re-create JS enhancers
- `reset()` — Reset all tiers to defaults
- `destroy()` — Tear down instance and remove all attributes
### Enhancers
- `initAccordions` — [data-sol-accordion] — Enhance all [data-sol-accordion] elements with expand/collapse behavior,
- `initCarousels` — [data-sol-carousel] — Enhance all [data-sol-carousel] elements with slide navigation,
- `initCollapsibles` — [data-sol-collapsible] — Enhance all [data-sol-collapsible] elements with expand/collapse behavior.
- `initColorPickers` — [data-sol-color-picker] — Enhance all [data-sol-color-picker] elements with interactive
- `initComboboxes` — [data-sol-combobox] — Enhance all [data-sol-combobox] elements with filtering, keyboard
- `initContextMenus` — [data-sol-context-menu] — Enhance all [data-sol-context-menu] elements with right-click
- `initDatePickers` — [data-sol-date-picker] — Enhance all [data-sol-date-picker] elements with calendar popup behavior.
- `initDrawers` — [data-sol-drawer] — Enhance all [data-sol-drawer] elements with open/close, focus trapping,
- `initDropdowns` — [data-sol-dropdown] — Enhance all [data-sol-dropdown] elements with toggle, click-away,
- `initHoverCards` — [data-sol-hover-card] — Enhance all [data-sol-hover-card] elements with hover-triggered
- `initModals` — [data-sol-modal] — Enhance all [data-sol-modal] elements with open/close, focus trapping,
- `initScrollAreas` — [data-sol-scroll-area] — Enhance all [data-sol-scroll-area] elements with auto-hiding
- `initTabs` — [data-sol-tabs] — Enhance all [data-sol-tabs] elements with tab switching, keyboard
- `initToasts` — [data-sol-toast-container] — Enhance all [data-sol-toast-container] elements with ARIA attributes
- `initTooltips` — [data-sol-tooltip] — Enhance all [data-sol-tooltip] elements with positioned tooltips.
- `initTrees` — [data-sol-tree] — Enhance all [data-sol-tree] elements with expand/collapse and
### Imperative APIs
- `testSingletonBehavior` — Verifies that re-calling an enhancer init function does not duplicate listeners.
- `mockBoundingClientRect` — Mocks getBoundingClientRect on an HTML element with default positioning values.
- `showToast` — Programmatically show a toast notification.
- `dismissToast` — Dismiss a specific toast element.
### Events
Event: `soltana:change` on `document.documentElement`
Detail types: theme, relief, finish, overrides, reset, destroy
### PostCSS Plugin
`soltanaTreeshake({ themes, reliefs, finishes })` — strips unused tier rulesets.
### Font Loading
`loadSoltanaFonts(url?)` — injects Google Fonts link for Cinzel, Cinzel Decorative, Raleway, JetBrains Mono.
---
## Integrations
### @soltana-ui/mermaid
Mermaid theme bridge for Soltana UI.
| Export | Kind | Description |
|--------|------|-------------|
| `buildConfig` | function | Ordered palette props read from the active CSS theme. */ |
| `MermaidConfig` | type | Ordered palette props read from the active CSS theme. */ |
| `initSoltanaMermaid` | function | Minimal Mermaid API surface accepted via dependency injection. */ |
| `autoSync` | function | Minimal Mermaid API surface accepted via dependency injection. */ |
| `MermaidLike` | type | Minimal Mermaid API surface accepted via dependency injection. */ |
Static themes: dark, light, sepia
### @soltana-ui/react
React bindings for Soltana UI — useSoltana() hook and SoltanaProvider. ESM-only.
| Export | Kind | Description |
|--------|------|-------------|
| `useSoltana` | function | * Initialize and manage the Soltana design system within a React component. |
| `useSoltanaContext` | function | * Consume the Soltana context. Throws if used outside a ``. |
| `SoltanaProvider` | component | |
| `SoltanaContextValue` | type | |
| `SoltanaProviderProps` | type | |
| `useAccordions` | function | |
| `useDropdowns` | function | |
| `useDrawers` | function | |
| `useToasts` | function | |
| `useCollapsibles` | function | |
| `useComboboxes` | function | |
| `useHoverCards` | function | |
| `useContextMenus` | function | |
| `useCarousels` | function | |
| `useScrollAreas` | function | |
| `useDatePickers` | function | |
| `useColorPickers` | function | |
| `useTrees` | function | |
| `showToast` | function | |
| `dismissToast` | function | |
| `ToastOptions` | type | |
| `ToastType` | type | |
| `ToastPosition` | type | |
---
## Patterns
### Tier Compositions
| Theme | Relief | Finish | Use case |
|-------|--------|--------|----------|
| dark | glassmorphic | frosted | Modern overlay panels |
| sepia | skeuomorphic | matte | Vintage document UIs |
| light | neumorphic | matte | Soft minimal dashboards |
| dark | flat | glossy | High-contrast data displays |
### Responsive Layouts
- Mobile-first stack: `flex flex-col md:flex-row gap-4`
- Card grid: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6`
- Centered: `flex items-center justify-center min-h-screen`
### Common HTML
```html
…
…
…
```
---
## Accessibility
### Utility Classes
- `.sr-only` — Visually hidden, accessible to screen readers
- `.skip-link` — Skip navigation link
- `.focus-ring` — Visible focus indicator
### Features
- `prefers-reduced-motion`: disables animations
- `prefers-contrast`: increases border contrast
- All interactive components have visible focus states
- Enhancers add ARIA attributes and keyboard navigation