@soroush.tech/design-system

Your design system. Your tokens. Your rules. A fully typed React component library where nothing is hardcoded - every color, scale, and default belongs to you, not the package.

Tired of forking a component library just to change a color? Every token here is designed to be overridden - theming isn't an afterthought, it's the whole point.

Install

npm i @soroush.tech/design-system

react and react-dom are peer dependencies. Emotion is an internal implementation detail - it ships as a regular dependency, not a peer, so you never install it yourself.

Use it with AI tools

An MCP server serves this library's component inventory, every component's props reference, and the live token contract, so an AI assistant writes against the real API instead of guessing:

claude mcp add --transport http soroush https://mcp.soroush.design/mcp

It also runs locally over stdio (npx -y @soroush.design/mcp). Claude Code users can install the plugin instead, which adds a house-style skill and a UI review agent on top of the same server:

claude plugin marketplace add soroush-tech/design-system
claude plugin install soroush-design-system@soroush-tech

Any other tool can read docs.soroush.tech/llms.txt. See @soroush.design/mcp for the full tool list.

Importing

Import components by subpath, styling primitives from the barrel:

import { Typography } from '@soroush.tech/design-system/Typography'
import { Flex } from '@soroush.tech/design-system/Flex'

Styling primitives (the engine) come from the barrel @soroush.tech/design-system - styled, css, keyframes, the Theme type, styled-system functions, and createShouldForwardProp. The barrel (src/index.ts) is the engine abstraction layer: to swap the CSS-in-JS engine, only that file changes.

import { styled, css, type Theme } from '@soroush.tech/design-system'

ThemeProvider and the theme-value hooks (useTheme, useDefaultProps, withTheme) live at their own subpath:

import { ThemeProvider, useTheme } from '@soroush.tech/design-system/theme'

Style-computation helpers (useStyle, withStyles, StylesConsumer) - resolving a StyleInput/StyleFactory into a CSSObject - live at their own subpath:

import { useStyle } from '@soroush.tech/design-system/style'

Raw engine primitives for building your own global styles - Global, globalStyles, and the SSR-only CacheProvider/styleCache pairing - live at their own subpath, not the barrel:

import { Global, globalStyles, CacheProvider, styleCache } from '@soroush.tech/design-system/engine'

Global (retyped against this package's Theme) applies app-wide CSS and should render inside ThemeProvider so it resolves against the active theme. globalStyles(theme) is the base reset this package owns - box-sizing, margin/table resets, and theme-driven body colors - compose it into your own Global styles array alongside your app's own concerns (font-family, webfont loading, and anything else app-specific stay entirely app policy).

The component catalog - every component as data, for tools that place and write components (a design tool's palette, a source writer) - lives at its own subpath and loads in plain Node (docs):

import { catalog } from '@soroush.tech/design-system/catalog'

SSR critical-CSS extraction (e.g. with @emotion/server) is a separate, opt-in concern most apps never need - that's what CacheProvider and its paired styleCache instance are for.

Under a strict Content Security Policy, bring your own cache with the response's nonce - createCache({ key: 'app', nonce }) from @emotion/cache, given to CacheProvider above ThemeProvider - and every style tag the engine inserts carries it. The shipped styleCache has no nonce.

The Emotion packages are regular dependencies of this package, not peers, on purpose: nothing of Emotion is on the public surface, so an app installs nothing extra and has no version to keep in step. An app that brings its own @emotion/react of another major gets two copies - the components keep working, as they style through their own copy and ThemeProvider - at the cost of the duplicate in the bundle and Emotion's one-time development warning.

Component inventory

Layout & surfaces

Content & data display

Inputs & forms

Navigation & menus

Feedback

Transitions

Overlay & behavior primitives

Theme tokens

Components never hardcode colors or sizes - props resolve against scales on the Theme object:

Prop types are derived from the interface (keyof Theme['text']), so adding a token to themes.ts propagates everywhere automatically. See design-system.md for the full scale table and the palette rules.

Theming

The theme belongs to you - the package only ships defaults. This section is the overview; the full guides are docs/theming.md and docs/customization.md.

One theme, yours

ThemeProvider provides exactly one theme - the built-in dark theme when you pass nothing. Bring one theme, or as many as you like: switching between them is your state, not the provider's.

import { ThemeProvider } from '@soroush.tech/design-system/theme'
import { baseTheme, createTheme } from '@soroush.tech/design-system/theme'

// Zero-config: the built-in `baseTheme`.
<ThemeProvider>{app}</ThemeProvider>

// Your theme - written from scratch or extended from the base.
const brand = createTheme(baseTheme, { palette: { primary: { main: '#00ff88' } } })
<ThemeProvider theme={brand}>{app}</ThemeProvider>

// Mode switching is app policy - own the state and pass the active theme:
const [isDark, setIsDark] = useState(true)
<ThemeProvider theme={isDark ? brandDark : brandLight}>{app}</ThemeProvider>

createTheme(base, overrides) (exported from @soroush.tech/design-system/theme) is the merge primitive: plain objects recurse, arrays (shadows, fontSizes) and functions replace wholesale, undefined values are ignored - keys are added or replaced, never removed.

Breakpoints and layout

theme.breakpoints are Material 3's window classes, each a range from its start until the next: xs 0-599px (compact, the base), sm 600-839 (medium), md 840-1199 (expanded), lg 1200-1599 (large), xl 1600+ (extra-large). Responsive props use them by name or position - p={{ xs: 2, md: 4 }}, p={[2, 3, 4]} - and cqSm-style keys write container queries; theme.breakpoints.up('md') and its siblings write queries for hand-written styles. Everything is CSS, so pages work with JavaScript off. theme.layout holds the layout tokens per class (columns, margins, gutters, side panels, top bar); Grid and Flex apply the column grid with layout / layout={{ lg: { columns: 16 } }}, and apps place AppBar, Sidebar and Drawer themselves. The full guide is the Breakpoints and layout section of the theming guide.

Component defaults

Components carry visible literal fallbacks (size = 'md', variant = 'outside', ...) resolved through themeDefault(theme, key, fallback) - so every default, including behavioral variants, is overridable via the optional theme.defaults map or the provider's defaults prop:

The built-in themes carry no defaults - the literals apply. A theme with entirely different size or palette keys stays valid by pointing the keys at its own tokens:

<ThemeProvider defaults={{ size: 'compact', color: 'brand', switchVariant: 'inside' }}>

Per-component customization (theme.components)

Customize one component for the whole app - default prop values, per-slot CSS, and new variant values - without wrapping or forking:

const brand = createTheme(baseTheme, {
  components: {
    Button: {
      // Buttons default to sm + rounded; explicit props and ButtonGroup still win.
      defaultProps: { size: 'sm', shape: 'rounded' },

      // Per-slot CSS merged after Button's own styles - the theme wins the cascade,
      // but per-instance props (m, p, width, ...) still beat the theme.
      styleOverrides: {
        root: ({ theme, ownerState }) => ({
          letterSpacing: theme.letterSpacings.wide,
          ...(ownerState.variant === 'contained' && { textTransform: 'none' }),
        }),
        label: { fontStyle: 'italic' },
      },

      // A new variant value - register it first so it typechecks:
      // declare module '@soroush.tech/design-system/theme' { interface ButtonVariants { dashed: true } }
      variants: [
        {
          props: { variant: 'dashed' },
          style: ({ theme }) => ({
            backgroundColor: 'transparent',
            border: `${theme.borderWidths.thin} dashed ${theme.border.primary}`,
          }),
        },
      ],
    },
  },
})

Style callbacks receive { theme, ownerState }, where ownerState is the styled root's resolved props (after group context, defaultProps, and theme.defaults). defaultProps sits in the standard precedence chain: explicit prop → group context → defaultProps → theme.defaults.* → the component's literal fallback. variants arrays are replaced wholesale by createTheme, never merged.

Your own components can join the same mechanism: create their roots with this package's styled(tag, { name: 'MyWidget', slot: 'root' }) and register the name by augmenting ThemeComponents. Zero-config themes pay nothing - the resolver bails out on the first check when theme.components is absent.

Extending tokens (declaration merging)

Every scale is an open interface declared on @soroush.tech/design-system/theme, so you can add palette colors, tokens, or whole scales - and every component prop union (color, bg, size, ...) widens automatically:

import type { PaletteEntry } from '@soroush.tech/design-system/theme'

declare module '@soroush.tech/design-system/theme' {
  interface ThemePalette {
    brand: PaletteEntry // new palette color
  }
  interface ThemeBackground {
    tertiary: string // new background token
  }
  interface Theme {
    elevations: Record<'low' | 'mid' | 'high', string> // whole new scale
  }
}

Then supply the values with createTheme and use the new keys:

const brandDark = createTheme(baseTheme, {
  palette: { brand: { main: '#00ff88', light: '#66ffb2', dark: '#00b25f', contrastText: '#000' } },
  background: { tertiary: '#101418' },
  elevations: { low: '0 1px 2px', mid: '0 2px 6px', high: '0 6px 18px' },
})

<ThemeProvider theme={brandDark}>
  <Button color="brand" />
  <View bg="tertiary" />
</ThemeProvider>

Notes: new object-valued keys (like a PaletteEntry) must be supplied complete - components read .main/.contrastText at runtime; and TypeScript cannot verify at runtime that an augmented token was actually supplied, so always pair an augmentation with the matching override.

Adding a component

Scaffold with the skill - it reads the live Typography files and design-system.md so output matches the codebase:

/new_theme_component ComponentName

Then work through the checklist at the bottom of design-system.md.

The library takes inspiration from Material UI - its component vocabulary and prop conventions will feel familiar - but it is written entirely in house. It is not a clone or a fork: every component is built from scratch on our own engine and token system, and the API is free to diverge wherever it serves its consumers better.

Release notes

Per-version notes for every published release live in release-notes/.