@smwb/ui-react

TypeScript React component library based on Material Design, with runtime light/dark theming and LESS-based customization. Part of the @smwb design-system monorepo.

The @smwb packages

| Package | What it is | | ------------------------------------------------------------------------ | -------------------------------------------------------------- | | @smwb/ui-react | This package — React components. | | @smwb/ui-solid | SolidJS port, same design system and class names. | | @smwb/ui-styles | Framework-agnostic LESS source + design tokens (smwb-*). | | @smwb/ui-css | Prebuilt aggregate stylesheet (import "@smwb/ui-css"). | | @smwb/ui-mcp-react | MCP server exposing this catalog to AI tools. |

Component catalog

• Storybook (production): https://summerweb.ru/ui-react/
• Storybook (dev): https://summerweb.ru/ui-dev-react/
• Local: npm run storybook → http://localhost:6006

Installation

Published on npm as @smwb/ui-react.

Requirements: Node.js ≥ 20, React and React DOM ≥ 18 (peer dependencies).

npm install @smwb/ui-react

Getting started

import { Button } from "@smwb/ui-react";

function App() {
  return <Button>Hello World</Button>;
}

In ESM builds each imported component pulls in its own CSS automatically (tree-shakeable), including the --smui-* design tokens it reads — nothing else to import for the default theme except the Roboto webfont (see Styles).

Icons

<Icon> renders one of two icon sets under the same name, so switching sets never touches component code:

• smwb SVG set — ~250 contour icons shipped inside the package, one ES module each.
• Google Material Symbols — the webfont this library has always used (<link> it yourself).

import { Icon } from "@smwb/ui-react";

<Icon name="arrow_right_alt" size={24} color="primary" />;

Names are the canonical Material Symbols names, and lookup is forgiving: arrow_right_alt, arrowRightAlt and arrow-right-alt all resolve, as do per-icon aliases (trash → delete, cog → settings, magnifier → search).

Bundling only the icons you use

Icons are not registered by default. Register the handful you render — every other icon is dropped by your bundler:

import { registerIcons } from "@smwb/ui-react";
import { add, close, search } from "@smwb/ui-react/icons";

registerIcons([add, close, search]);

Three icons in, three icons bundled (~0.4 kB). Or skip the registry entirely and pass the definition straight to the prop:

import { arrowRightAlt } from "@smwb/ui-react/icons";

<Icon name={arrowRightAlt} />;

Deep imports work too (@smwb/ui-react/icons/arrowRightAlt), and @smwb/ui-react/icons/all exports registerAllIcons() for docs sites and icon pickers — that one pulls in the whole set on purpose.

Choosing the source

| source | Behaviour | | ---------------- | ------------------------------------------------------------------------ | | auto (default) | smwb SVG when the name is registered, Material Symbols otherwise. | | smwb | Always the SVG set; an unregistered name renders an empty box and warns. | | google | Always the Material Symbols font. |

Set it per icon (<Icon source="google" …>), per subtree, or app-wide:

import { configureIcons, IconProvider } from "@smwb/ui-react";
import { add, close } from "@smwb/ui-react/icons";

configureIcons({ source: "smwb" }); // app-wide default

<IconProvider source="smwb" icons={[add, close]}>
  <App />
</IconProvider>;

Because auto falls back to the font, upgrading changes nothing until you register icons.

Appearance

size takes a pixel number or any CSS length (size="1.5rem"). color takes a semantic token (primary, error, …) and otherwise inherits currentColor. For the SVG set weight maps to the stroke width (400 → 2px, 700 → 3px); fill and grade are Material Symbols axes and are ignored by the contour set.

Custom and overridden icons

An icon is plain data, so your own artwork registers the same way — and re-registering a shipped name replaces it everywhere:

registerIcons({ name: "logo", body: '<circle cx="12" cy="12" r="9"/>' });
registerIcons({ name: "delete", body: "<path d='…'/>" }); // overrides the shipped one

Browse the whole set in Storybook under UI/Base/Icon → All Icons — click any icon to copy its name. The set is generated from icons/data/*.json in the repo (npm run icons:generate).

Styles

Three ways to get the CSS, pick one:

1. Auto-injected per-component CSS (default, ESM) — import components and their styles come along, plus one shared sheet that defines the --smui-* tokens. Tree-shaken: you only ship CSS for what you use. The Roboto webfont is not included (@smwb/ui-css loads it from Google Fonts): <link> it yourself, or set --smui-fontFamily to your own font.
2. Full prebuilt stylesheet — one file with every component, from @smwb/ui-css (recommended for CJS or when you need a fixed global cascade order):

   import "@smwb/ui-css";

   Optional CSS reset: import "@smwb/ui-styles/normalize.css";.
3. Custom LESS bundle compiled from @smwb/ui-styles — see Theming.

Headless entry (compile one LESS bundle yourself)

For apps that compile a single themed LESS bundle instead of per-chunk CSS injection:

import "@smwb/ui-styles/normalize.css";
import "@smwb/ui-styles/components.less";
import { Button, TextField } from "@smwb/ui-react/headless";

Selective LESS bundle (only the components you use)

Compile a minimal stylesheet from @smwb/ui-styles:

@import (less) "node_modules/@smwb/ui-styles/less/headless-base.less";
@import (less) "node_modules/@smwb/ui-styles/less/components/button/button.entry.less";
@import (less) "node_modules/@smwb/ui-styles/less/components/textField/textField.entry.less";

• headless-base.less = foundation tokens + :root / dark CSS variables (import once).
• One *.entry.less per component (each resolves LESS variables via _prelude.less).
• A component's required entries and their dependencies are listed by the MCP tool get_component_props (see @smwb/ui-mcp-react) under each component's styles block.
• Import <name>.entry.less, never the bare components/<name>/<name>.less.

TanStack Table adapter

import { ReactTable } from "@smwb/ui-react/react-table";

Targets @tanstack/react-table v8. See Storybook → Connects / react-table.

• Install @tanstack/react-table and react-dnd in your app: the adapter imports both. Only draggableColumns needs react-dnd's DndProvider around it.
• It renders the root entry's own Table components, not copies: their CSS comes along as with any component, and configureIcons / IconProvider apply to its icons. It has no headless variant, so it brings that CSS next to @smwb/ui-react/headless too.
• In a selective LESS bundle, add less/connects/rt/table.entry.less (the column resizer) to the table's entries.

Charts (ECharts)

import { Chart } from "@smwb/ui-react/chart";

<Chart
  label="Works opened by week"
  summary="12 works opened last week, 9 the week before."
  height={240}
  option={(palette) => ({
    xAxis: { type: "category", data: weeks },
    yAxis: { type: "value" },
    series: [{ type: "bar", data: opened, itemStyle: { color: palette.primary } }],
  })}
/>;

A separate entry point: echarts (5.4+ or 6) is an optional peer — install it in your app; the root package never reaches it. ECharts loads in the browser when the first chart mounts; until then, and on the server, a skeleton of the chart's height holds its place. The colours come from the theme's CSS variables (series from --smwb-chart-series-1 … -12), and the chart redraws when the theme switches (data-theme on <html>) or its box resizes; at zero size (a hidden tab) it waits. For a smaller bundle pass loader={() => import("./my-echarts")}, a module that registers only the charts you use with echarts/core. See Storybook → Data Display / Chart.

Customization and theming

Pick the shallowest layer that solves the task:

| Goal | Approach | Rebuild CSS? | | -------------------------------------------- | ------------------------------------------------------ | ------------ | | Toggle light/dark, tweak a few colors live | CSS variables --smui-* + data-theme | No | | One component instance looks different | Component props (color, size, variant, …) | No | | New brand, density, or defaults library-wide | LESS overrides via theme.config on @smwb/ui-styles | Yes |

Full token catalogs and recipes: AI_THEMING.md (runtime + props), AI_LESS_OVERRIDES.md (compile-time LESS).

Light and dark mode

Tokens are exposed on :root and :root[data-theme="dark"] as --smui-* (see Runtime overrides for how your values take precedence).

import { useTheme, Theme } from "@smwb/ui-react";

function ThemeToggle() {
  const { theme, setTheme } = useTheme(); // persists + syncs <html data-theme>
  return (
    <button type="button" onClick={() => setTheme(theme === Theme.dark ? Theme.light : Theme.dark)}>
      {theme === Theme.dark ? "Light" : "Dark"}
    </button>
  );
}

Or set the attribute yourself (<html data-theme="dark">). Without it, useTheme follows prefers-color-scheme.

Runtime overrides (no rebuild)

:root {
  --smui-primaryColor: #00695c;
  --smui-radius-md: 2px;
}
.settings-panel {
  --smui-space-md: 8px;
} /* scoped, cascades */

How an override meets the library's own value depends on where the tokens come from:

• Auto-injected CSS declares them at zero specificity (:where(:root), :where(:root[data-theme="dark"])): your override wins whatever order the stylesheets load in, and a :root override holds in dark mode too.
• @smwb/ui-css or your own LESS compile declares them on :root and :root[data-theme="dark"]: load your overrides after that stylesheet. In dark mode the library's dark values still beat a plain :root override.

Either way, :root[data-theme="dark"] { … } sets dark-only values.

Prefer --smui-* tokens over targeting internal .smwb-* classes (implementation detail).

Per-component appearance (props)

<Button variant="outlined" color="primary" size="large">Save</Button>
<FloatingButton color="success" size="large" />
<Message type="error" variant="filled" />

Compile-time overrides (theme.config)

For library-wide changes, add a theme.config (see theme.config.example) and compile @smwb/ui-styles/components.less:

// theme.config
@theme: "summer"; // or "material"
@themesFolder: "node_modules/@smwb/ui-styles/less/themes";

@primaryColor: @md-teal-600;
@smui-spacing-unit: 8px;
@smui-radius-md: 2px;

lessc -rp=/ ./node_modules/@smwb/ui-styles/less/components.less ./src/app.css

theme.config is imported last, so your reassignments win. Token catalog and rules: AI_LESS_OVERRIDES.md.

MCP server (component catalog for AI tools)

The catalog is exposed to AI assistants by a separate package, @smwb/ui-mcp-react — a stdio MCP server (no HTTP port). Tools:

| Tool | Purpose | | ---------------------- | --------------------------------------------------------------- | | search_components | Find components by name, id, description, or prop keywords | | get_component_props | Full metadata for one component (props + required LESS imports) | | search_customization | Global theming options and per-component customization | | get_customization | What and how to customize a component or global topic |

Run it from npm:

npx -y @smwb/ui-mcp-react

Cursor (.cursor/mcp.json) or Claude Desktop config:

{
  "mcpServers": {
    "smwb-ui-react": {
      "command": "npx",
      "args": ["-y", "@smwb/ui-mcp-react"]
    }
  }
}

Documentation for AI assistants

| File | Topic | | ------------------------------------------------ | ------------------------------------------------------------------------------------- | | AI_THEMING.md | Runtime theming: --smui-* variables, useTheme, color / size / variant props | | AI_LESS_OVERRIDES.md | Compile-time LESS overrides: token catalog, theme.config, custom stylesheet |

License

MIT