@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-systemreact 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.
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).
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.
Component inventory
Layout & surfaces
| Component | Purpose |
|---|---|
View |
Styled div primitive — the base building block |
Flex |
View with flexbox defaults |
Grid |
CSS grid container |
Paper |
Elevated surface with background and shadow |
Card |
Content container built on Paper |
Quote |
Bordered quote / terminal-panel surface on View |
AppBar |
Top application bar |
Drawer |
Slide-in side panel |
Content & data display
| Component | Purpose |
|---|---|
Typography |
Text with variant → element mapping — the reference implementation for all components |
Link |
Anchor with theme-aware styling |
Icon |
Icon renderer |
Image |
Image with styled-system props |
Avatar |
User/entity avatar |
Table |
Compound data table — exports TableContainer, TableHead, TableBody, TableFooter, TableRow, TableCell, TablePagination, TablePaginationActions, TableSortLabel, and TableControl from @soroush.tech/design-system/Table |
Inputs & forms
| Component | Purpose |
|---|---|
Button, ButtonGroup, ToggleButton |
Actions and toggles |
TextInput |
Text field |
Checkbox, Radio, Switch |
Selection controls |
NativeSelect |
Platform <select> |
Select |
Custom select built on Popover + MenuItem |
MenuItem |
Option row for Select's listbox |
Form, FormControl, FormLabel, FormHelperText |
Form composition and labeling |
Pagination |
Page navigation control |
Feedback
| Component | Purpose |
|---|---|
CircularProgress, LinearProgress |
Determinate/indeterminate progress indicators |
Skeleton |
Loading placeholder with pulse/wave animations |
Backdrop |
Dimmed overlay behind modal surfaces |
Overlay & behavior primitives
| Component | Purpose |
|---|---|
Portal |
Renders children into a DOM node outside the parent hierarchy |
FocusTrap |
Keeps focus inside a subtree |
Modal |
Dialog primitive composing Portal, Backdrop, and FocusTrap |
Popover |
Anchored floating surface built on Modal |
ThemeProvider |
Supplies the theme and global styles to the app |
Theme tokens
Components never hardcode colors or sizes — props resolve against scales on the Theme object:
| Group | Scales |
|---|---|
| Color | palette (main/light/dark/contrastText per color) · text · background · border · colorScheme |
| Typography | typography (variant map) · fonts · fontSizes · fontWeights · lineHeights · letterSpacings |
| Space & shape | space · sizes · radii · borderWidths · shadows |
| Component scales | avatar (size steps) · skeleton (wave highlight) |
| Layering & effects | zOrder (appBar/drawer/modal) · blur · logoFilter · portraitBlend · portraitOpacity |
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.
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:
| Key | Fallback | Drives |
|---|---|---|
size / compactSize |
'md' / 'sm' |
sized components / dense table actions |
color / neutralColor |
'primary' / 'default' |
accent controls / toggle controls |
textColor / accentTextColor |
'initial' / 'primary' |
body text / icons + input labels |
bg / surfaceBg / inputBg |
'default'/'paper'/'terminal' |
switch track / paper surfaces / inputs |
borderRadius / surfaceRadius |
'md' / 'sq' |
grouped controls / surfaces |
avatarSize / borderColor / borderWidth |
'md' / 'primary' / 'thin' |
avatars and rings |
iconSize |
'lg' |
Icon default glyph size (theme.icon) |
buttonVariant / switchVariant |
'contained' / 'outside' |
Button / Switch visual variants |
inputVariant |
'default' |
TextInput, Select, NativeSelect frames |
avatarVariant / cardVariant |
'circular' / 'paper' |
Avatar shape / Card treatment |
linkUnderline |
'always' |
Link underline behavior |
paginationVariant / paginationShape |
'text' / 'circular' |
Pagination items |
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 ComponentNameThen 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/.