soltana-ui
v0.1.0
Published
A CSS-first design system inspired by classical architecture and precious materials. Features neumorphic, glassmorphic, and hybrid relief systems with a 3-tier configuration model.
Downloads
14
Maintainers
scottdraper8Readme
soltana-ui
CSS-first design system with a 3-tier orthogonal configuration model: Theme × Relief × Finish.
Documentation • Component Gallery • Playground
Features
- 3-tier orthogonal architecture — Compose theme (color), relief (shadow model), and finish (surface treatment) independently
- Per-element composition — Apply tier configurations globally or per-element via utility classes
- Runtime registration — Register custom themes, reliefs, and finishes at runtime
- 16 accessible enhancers — Modals, tabs, tooltips, accordions, carousels, color pickers, date pickers, and more
- CSS-first philosophy — All rendering stays in CSS; JS only handles behavior and injects runtime-computed values
Installation
npm install soltana-uiQuick Start
HTML + CDN
<!DOCTYPE html>
<html data-theme="dark" data-relief="glassmorphic" data-finish="frosted">
<head>
<link rel="stylesheet" href="https://unpkg.com/soltana-ui/dist/soltana-ui.css" />
</head>
<body>
<button class="btn btn-primary">Hello Soltana</button>
<script type="module">
import { loadSoltanaFonts } from 'https://unpkg.com/soltana-ui';
loadSoltanaFonts();
</script>
</body>
</html>Import CSS + JS
import 'soltana-ui/css';
import { loadSoltanaFonts, initModals, initTooltips } from 'soltana-ui';
loadSoltanaFonts();
initModals();
initTooltips();Using SCSS Source
@use 'soltana-ui/scss' as soltana;The 3-Tier Model
| Tier | Options | Global Activation | Per-Element Class |
| ---------- | ---------------------------------------------------- | ----------------------------------- | ---------------------- |
| Theme | dark, light, sepia, auto | <html data-theme="dark"> | .theme-dark |
| Relief | flat, glassmorphic, skeuomorphic, neumorphic | <html data-relief="glassmorphic"> | .relief-glassmorphic |
| Finish | matte, frosted, tinted, glossy | <html data-finish="frosted"> | .finish-frosted |
<!-- Global tier activation -->
<html data-theme="dark" data-relief="neumorphic" data-finish="matte">
<!-- Per-element tier override -->
<div class="card theme-light relief-flat finish-glossy">Mixed tier configuration</div>
</html>Runtime Registration
import { registerTheme, registerRelief, registerFinish } from 'soltana-ui';
// Register a custom theme from seed colors
registerTheme({
name: 'ocean',
seedColors: {
primary: '#0ea5e9',
secondary: '#06b6d4',
accent: '#3b82f6',
},
});
// Register a custom relief
registerRelief({
name: 'lifted',
tokens: {
'--shadow-near': '0 4px 8px rgba(0,0,0,0.2)',
'--shadow-far': '0 12px 24px rgba(0,0,0,0.3)',
},
});PostCSS Tree-Shaking
Remove unused tier CSS in production:
// postcss.config.mjs
import soltanaTreeshake from 'soltana-ui/postcss';
export default {
plugins: [
soltanaTreeshake({
keep: ['dark', 'light', 'glassmorphic', 'neumorphic', 'frosted', 'matte'],
}),
],
};Ecosystem
| Package | Purpose |
| ----------------------------------- | -------------------------------------------------------------- |
| @soltana-ui/tokens | Token compiler — outputs Mermaid themes, DTCG JSON, agent docs |
| @soltana-ui/react | React bindings — useSoltana() hook, SoltanaProvider |
| @soltana-ui/mermaid | Mermaid theme bridge for diagram synchronization |
Documentation
- Full Documentation
- Component Gallery — Live interactive previews of all components
- Playground — Experiment with tier combinations
- Component Reference — CSS class reference for all components
- AI Agent Reference — Machine-readable reference for AI agents
License
MIT License - see LICENSE file for details.