Nware Soma UI components for the Nware platform
Cortex thinks, Axon acts — Soma is what you see.
Vanilla zero-dependency JS and Sass-authored CSS, designed for
server-rendered pages: markup uses static soma-*
classes, behaviour attaches via auto-init on
DOMContentLoaded or the imperative
Soma.* API. Delivered as a flatpack
(dist/soma.css + dist/soma.js /
soma.umd.cjs). Start with
Getting started.
Three themes (light, dark, high-contrast), three density modes
(comfortable, cosy, compact) and RTL all switch via attributes on
<html>; cycle them with the corner buttons.
Every component page pairs a captioned live demo of each variant
with syntax-highlighted HTML/CSS/JS code blocks (hover a block
for its copy button). The machine-readable contract is
llms.txt, rendered for humans
on the reference page.
About the name
Soma is the neuron's cell body: the visible
integrating center that receives what the dendrites carry in and
hands the result to the axon. That is the library's role in the
Nware ecosystem, whose sandbox units are literally called
neurons, and whose siblings are Cortex
and Axon: Cortex thinks, Axon acts — Soma
is what you see. Pronunciation: SOH-mə
(IPA /ˈsoʊmə/), two syllables, stress on the
first.
The name takes one canonical form per surface:
| Form | Value |
|---|---|
| Prose | Nware Soma |
| npm | @nware/soma |
| CSS prefix | soma- |
| JS API | Soma.* |
Who Soma is for
The docs and component surface are designed for two audiences in parallel:
Human developers
Frontend and full-stack engineers building on the Nware platform
(nware-portal and its plugins), or on any
server-rendered app that wants a modern UI without a React or
Vue rewrite. Every component page has a Summary,
When to use, captioned live Examples for every
variant, copy-paste HTML, a CSS classes table,
and the JavaScript API, plus
Integration for wiring Soma into
a living app, docs search, and the one-page
kitchen sink.
AI coding agents
Claude Code, Codex, Gemini, and similar coding assistants use
this sandbox as their reference surface when generating code
that targets Soma. A machine-readable
llms.txt at the site root
indexes every component's markup contract, JS API, events,
design-token vocabulary, and the rules agents must follow.
The reference page renders the
same file for human review.
Both audiences share the same rule: use
Soma.* and soma-* only. Soma is
greenfield: there are no aliases, no legacy spellings, and no
compatibility layer, so the canonical names are the whole
vocabulary.
Foundations
Components
Every component has a dedicated page: summary, when to use, captioned live examples with code blocks, CSS classes, and the JavaScript API.
Guides
Component matrix
The full component surface at a glance. Since is the
release that introduced the component — everything to date
lands in 0.1.0, the first release (in
preparation). Kind: CSS =
markup-only (no behaviour to attach), CSS + JS = styled
markup plus attached behaviour, JS = the component builds its own
DOM and exists only through its API. Auto-init is the
literal selector wired up on DOMContentLoaded —
"imperative" components are created by calling their API.
| Component | Kind | JS API | Auto-init | Since |
|---|---|---|---|---|
| Avatars | CSS | — | — | 0.1.0 |
| Badges | CSS | — | — | 0.1.0 |
| Banners | CSS + JS | Soma.banner | .soma-banner (wires the optional .soma-banner-close) | 0.1.0 |
| Buttons | CSS | — | — | 0.1.0 |
| Charts | CSS | — | — | 0.1.0 |
| Combobox | JS | Soma.combobox | imperative | 0.1.0 |
| Date picker | CSS + JS | Soma.datePicker / Soma.dateRange | .soma-date-picker-input | 0.1.0 |
| Dialogs | CSS + JS | Soma.dialog2 | imperative | 0.1.0 |
| Diff | CSS | — | — | 0.1.0 |
| Drawer | CSS + JS | Soma.drawer | imperative | 0.1.0 |
| Dropdowns | CSS + JS | Soma.dropdown2 | .soma-dropdown2-trigger[aria-controls] | 0.1.0 |
| Dropzone | CSS + JS | Soma.dropzone | .soma-dropzone (containing a file input) | 0.1.0 |
| Empty states | CSS | — | — | 0.1.0 |
| Expander | CSS + JS | Soma.expander | .soma-expander-trigger[aria-controls] | 0.1.0 |
| Filter chips | CSS | — | — | 0.1.0 |
| Forms | CSS | — | — | 0.1.0 |
| Icons | CSS | — | — | 0.1.0 |
| Inline dialog | CSS + JS | Soma.inlineDialog | .soma-inline-dialog-trigger[aria-controls] | 0.1.0 |
| Key-value list | CSS | — | — | 0.1.0 |
| Labels | CSS | — | — | 0.1.0 |
| List group | CSS | — | — | 0.1.0 |
| Log viewer | CSS | — | — | 0.1.0 |
| Messages | CSS + JS | Soma.message + .create | .soma-message (close wiring) | 0.1.0 |
| Meter | CSS | — | — | 0.1.0 |
| Navbar | CSS + JS | Soma.responsiveNavbar | .soma-navbar[data-soma-responsive] | 0.1.0 |
| Navigation | CSS + JS | Soma.breadcrumbs | .soma-breadcrumbs[data-soma-collapse] | 0.1.0 |
| Command palette | JS | Soma.palette | imperative | 0.1.0 |
| Page | CSS | — | — | 0.1.0 |
| Page header | CSS | — | — | 0.1.0 |
| Page layout | CSS | — | — | 0.1.0 |
| Progress | CSS + JS | Soma.progress | imperative | 0.1.0 |
| Quicksearch | CSS + JS | Soma.quicksearch | .soma-quicksearch | 0.1.0 |
| RESTful table | CSS + JS | Soma.restfulTable | imperative | 0.1.0 |
| Select | CSS + JS | Soma.select2 | imperative | 0.1.0 |
| Shell | CSS + JS | Soma.sidebarResize (imperative) | [data-soma-sidebar-toggle], .soma-sidebar-group-toggle[aria-controls] | 0.1.0 |
| Skeleton | CSS | — | — | 0.1.0 |
| Spinner | CSS + JS | Soma.spinner / Soma.spinnerStop | imperative | 0.1.0 |
| Stat tiles | CSS | — | — | 0.1.0 |
| Tables | CSS + JS | Soma.sortableTable | table.soma-table-sortable | 0.1.0 |
| Tabs | CSS + JS | Soma.tabs | .soma-tabs:not(.soma-tabs-disabled) | 0.1.0 |
| Timeline | CSS | — | — | 0.1.0 |
| Toasts | JS | Soma.toast | imperative | 0.1.0 |
| Toolbar | CSS | — | — | 0.1.0 |
| Tooltips | CSS + JS | Soma.tooltip | [data-soma-tip] (the CSS-only data-soma-tooltip needs no JS) | 0.1.0 |
| Tree | CSS + JS | Soma.tree | .soma-tree | 0.1.0 |
| Typography | CSS | — | — | 0.1.0 |
| Widgets | CSS | — | — | 0.1.0 |
Beyond components, the library-level APIs are
Soma.theme (Themes),
Soma.i18n (i18n) and
Soma.shortcuts (Keyboard
shortcuts).