# soroush design system

> A token-driven React component library built on a typed style-prop engine, with a
> markdown companion library. Every component documents its props, token values, and
> defaults in its own README, which is what these pages render.

An MCP server serves this same content to AI tools:
https://mcp.soroush.tech/mcp (or `npx -y @soroush.tech/mcp`).

## Getting started

- [Installation](https://docs.soroush.tech/design-system/getting-started/installation/): install the packages and their peers.
- [Usage](https://docs.soroush.tech/design-system/getting-started/usage/): wrap the app in ThemeProvider and render a component.
- [Theming](https://docs.soroush.tech/design-system/customization/theming/): the Theme type and how createTheme composes one.
- [Customization](https://docs.soroush.tech/design-system/customization/how-to/): override styles through theme.components.

## Components

- [View](https://docs.soroush.tech/design-system/components/view/): The base layout primitive. Renders as `<div>`. All styled-system prop groups are supported: space, layout, color, typography, flexbox, border, and position.
- [Flex](https://docs.soroush.tech/design-system/components/flex/): Extends [`View`](https://docs.soroush.tech/design-system/components/view/). Renders as a `<div>` with `display: flex` and `flex-direction: column` by default.
- [Grid](https://docs.soroush.tech/design-system/components/grid/): Extends [`View`](https://docs.soroush.tech/design-system/components/view/). Renders as a `<div>` with `display: grid`.
- [Paper](https://docs.soroush.tech/design-system/components/paper/): An elevated surface primitive that extends `View`. Adds visual surface styling - shadow via `theme.shadows`, a default `bg="paper"` background, and a default `borderRadius="md"`. Consumers compose `Flex` or `Grid` inside `Paper` for layout.
- [Card](https://docs.soroush.tech/design-system/components/card/): A surface component with an optional title, caption, and variant-based visual treatment. Extends `Paper` - all `Paper`, `Flex`, and space/layout props pass through.
- [Quote](https://docs.soroush.tech/design-system/components/quote/): A `View` with a fixed 2px primary left border - used for terminal readouts and markdown
- [AppBar](https://docs.soroush.tech/design-system/components/app-bar/): Renders as `<header>`. A top-level container for navigation, toolbars, and application headers. Applies a default elevation shadow from the theme and stretches to full width.
- [Drawer](https://docs.soroush.tech/design-system/components/drawer/): A panel that slides in from a screen edge, built on [`Modal`](https://docs.soroush.tech/design-system/components/modal/). It portals, dims the page with a backdrop, traps focus, locks body scroll, and closes on Escape (top modal only) or backdrop click - all inherited from Modal. The panel itself is a [`Paper`](https://docs.soroush.tech/design-system/components/paper/), anchored to the chosen edge and animated with a per-anchor slide that respects `prefers-reduced-motion`. It renders on the `theme.zOrder.drawer` layer - above the app bar, below modals.
- [Sidebar](https://docs.soroush.tech/design-system/components/sidebar/): A collapsible vertical icon rail. Collapsed, it shows icon-only `SidebarItem`s; open, each item's
- [Typography](https://docs.soroush.tech/design-system/components/typography/): Renders as `<p>` by default. The `variant` prop controls both the visual scale and the HTML element. All styled-system prop groups are supported, plus five Typography-specific props.
- [Link](https://docs.soroush.tech/design-system/components/link/): Renders as `<a>`. Composes `Typography` - all typographic scale, color, spacing, and layout props are inherited. Adds `underline`, and defaults `color` to `"primary"` and `variant` to `"inherit"`.
- [Icon](https://docs.soroush.tech/design-system/components/icon/): Renders a themeable SVG icon from the central registry. Consumers pass a `name`; `Icon` owns every `?react` import and maps the name to its component.
- [Image](https://docs.soroush.tech/design-system/components/image/): A styled-system `<img>` primitive. Accepts all layout, space, background, and position props from the theme, plus `objectFit` / `objectPosition` for common image sizing patterns and `borderRadius` for rounded corners.
- [Avatar](https://docs.soroush.tech/design-system/components/avatar/): Displays a user image, initials, or icon in a consistently sized container. Supports three shapes, four preset sizes, an optional ring outline, and automatic image-error fallback. All styles derive from theme tokens.
- [Table](https://docs.soroush.tech/design-system/components/table/): The root of the table family. Renders a `<table>` with collapsed borders and full width, and
- [Button](https://docs.soroush.tech/design-system/components/button/): Renders as `<button>`. Sharp corners, uppercase, bold, tight letter-spacing - matching the Kinetic Architecture aesthetic. Supports three visual variants, six semantic color palettes, three sizes, start/end icon slots, full-width mode, and a loading state with configurable indicator position.
- [ButtonGroup](https://docs.soroush.tech/design-system/components/button-group/): Groups related `Button` immediate children into a visually joined cluster - adjacent borders
- [ToggleButton](https://docs.soroush.tech/design-system/components/toggle-button/): An individual toggle button (text or icon) - usable standalone or inside a `ToggleButtonGroup`.
- [TextInput](https://docs.soroush.tech/design-system/components/text-input/): A theme-aware text input primitive. Supports controlled and uncontrolled usage, multiline (textarea), error and disabled states, and all standard form attributes.
- [Checkbox](https://docs.soroush.tech/design-system/components/checkbox/): A binary toggle control. Supports controlled and uncontrolled usage, six semantic color palettes, two sizes, indeterminate state, and custom icons.
- [Radio](https://docs.soroush.tech/design-system/components/radio/): A single-selection control for use within a group. Supports controlled checked state, six semantic color palettes, two sizes, and custom icons.
- [Switch](https://docs.soroush.tech/design-system/components/switch/): A sliding toggle control. Supports controlled and uncontrolled usage, six semantic color palettes, two sizes, four visual variants, and custom thumb icons.
- [NativeSelect](https://docs.soroush.tech/design-system/components/native-select/): A styled native `<select>` form control. Renders `options` data as `<option>` elements, shows a
- [Select](https://docs.soroush.tech/design-system/components/select/): A form select with a custom, themeable listbox - and a `native` escape hatch. It takes
- [MenuItem](https://docs.soroush.tech/design-system/components/menu-item/): A single option row for [`Select`](https://docs.soroush.tech/design-system/components/select/)'s listbox, rendered as a semantic
- [Form](https://docs.soroush.tech/design-system/components/form/): Renders a `<form>` and provides form-wide field defaults through `FormContext`. It is the **lowest
- [FormControl](https://docs.soroush.tech/design-system/components/form-control/): Groups a label, control, and helper text into one accessible field and shares their state through React context. Works standalone or inside a [`Form`](https://docs.soroush.tech/design-system/components/form/).
- [FormLabel](https://docs.soroush.tech/design-system/components/form-label/): A field label built on [`Typography`](https://docs.soroush.tech/design-system/components/typography/), rendered as a `<label>`. Reads the control `id` and `required` flag from [`FormControl`](https://docs.soroush.tech/design-system/components/form-control/) context so association and the required indicator wire automatically.
- [FormHelperText](https://docs.soroush.tech/design-system/components/form-helper-text/): Helper or error text for a field, built on [`Typography`](https://docs.soroush.tech/design-system/components/typography/) and rendered as a `<p>`. Reads its `id` and error state from [`FormControl`](https://docs.soroush.tech/design-system/components/form-control/) context and registers its presence so the control points `aria-describedby` at it only while it is rendered.
- [Pagination](https://docs.soroush.tech/design-system/components/pagination/): Page-number navigation for paging a list of arbitrary items (e.g. a blog index), with ellipsis
- [CircularProgress](https://docs.soroush.tech/design-system/components/circular-progress/): Renders a circular loading indicator. Supports `indeterminate` (looping) and `determinate` (value-driven) variants. The stroke color is set via CSS `currentColor`; the `color` prop resolves to `theme.palette[color].main`.
- [LinearProgress](https://docs.soroush.tech/design-system/components/linear-progress/): Renders a horizontal loading bar - the linear counterpart of `CircularProgress`. Supports `indeterminate` (looping), `determinate` (value-driven), and `query` (reversed loop) variants, plus a `buffer` mode on top of `determinate`. All fills use CSS `currentColor`; the `color` prop resolves to `theme.palette[color].main`.
- [Skeleton](https://docs.soroush.tech/design-system/components/skeleton/): Displays a low-fidelity placeholder while content loads, reducing layout shift and signalling a loading state. Supports three shapes, two animations (or none), explicit or child-inferred dimensions, and derives all colors from theme tokens.
- [Backdrop](https://docs.soroush.tech/design-system/components/backdrop/): A dimmed, full-viewport scrim rendered behind a modal's content. Built on `View`, so it accepts every `View` prop (background, spacing, layout, event handlers, etc.).
- [Portal](https://docs.soroush.tech/design-system/components/portal/): Renders its children into a DOM node outside the parent component hierarchy - the document body by default. Used by overlay components (Modal, Drawer) so their content escapes ancestor `overflow`/`transform`/stacking contexts.
- [FocusTrap](https://docs.soroush.tech/design-system/components/focus-trap/): Keeps keyboard focus within its children while active. On activation it moves focus inside, cycles `Tab` / `Shift+Tab` at the boundaries, pulls focus back when it escapes, and restores focus to the previously focused element on deactivation. Used by Modal to make overlays keyboard-accessible.
- [Modal](https://docs.soroush.tech/design-system/components/modal/): A low-level, accessible overlay primitive. Portals its content, dims the page with a `Backdrop`, traps focus, locks body scroll, and closes on Escape (top modal only) or backdrop click. Higher-level overlays - such as `Drawer` - are built on top of it.
- [Popover](https://docs.soroush.tech/design-system/components/popover/): Positions floating content next to an anchor, portaled above the page. It is built on
- [Pressable](https://docs.soroush.tech/design-system/components/pressable/): An unstyled clickable surface: button semantics - keyboard activation, focus ring, disabled

## Markdown components

- [Preview](https://docs.soroush.tech/markdown/components/preview/): Renders a markdown **string** with every element mapped to a design-system primitive - headings,
- [Editor](https://docs.soroush.tech/markdown/components/editor/): The source `<textarea>` of the `Markdown` compound.
- [LiveEdit](https://docs.soroush.tech/markdown/components/live-edit/): A preview you write on directly. The markdown document renders exactly like `Preview`, split into
- [Control](https://docs.soroush.tech/markdown/components/control/): The headless root of the `Markdown` compound. It renders **no UI of its own** - it owns the shared
- [Toolbar](https://docs.soroush.tech/markdown/components/toolbar/): The formatting toolbar of the `Markdown` compound. It dispatches actions through `Markdown`
- [CodeBlock](https://docs.soroush.tech/markdown/components/code-block/): A fenced-code surface: a horizontally scrollable, terminal-styled block with a copy-to-clipboard
- [Mermaid](https://docs.soroush.tech/markdown/components/mermaid/): Renders a fenced ` ```mermaid ` block as a diagram. Used by [`Preview`](https://docs.soroush.tech/markdown/components/preview/) for

## styled-system

- [Getting started](https://docs.soroush.tech/styled-system/docs/getting-started/)
- [How it works](https://docs.soroush.tech/styled-system/docs/how-it-works/)
- [Responsive styles](https://docs.soroush.tech/styled-system/docs/responsive-styles/)
- [API](https://docs.soroush.tech/styled-system/docs/api/)
- [Variants](https://docs.soroush.tech/styled-system/docs/variants/)
- [Custom props](https://docs.soroush.tech/styled-system/docs/custom-props/)
- [css prop](https://docs.soroush.tech/styled-system/docs/css/)
- [Theme specification](https://docs.soroush.tech/styled-system/docs/theme-specification/)
- [Theming](https://docs.soroush.tech/styled-system/docs/theming/)
- [Table](https://docs.soroush.tech/styled-system/docs/table/)
- [TypeScript](https://docs.soroush.tech/styled-system/docs/typescript/)
- [Rationale](https://docs.soroush.tech/styled-system/docs/rationale/)
- [Guides overview](https://docs.soroush.tech/styled-system/docs/guides/)
- [Array props](https://docs.soroush.tech/styled-system/docs/guides/array-props/)
- [Array scales](https://docs.soroush.tech/styled-system/docs/guides/array-scales/)
- [Build a Box](https://docs.soroush.tech/styled-system/docs/guides/build-a-box/)
- [Color modes](https://docs.soroush.tech/styled-system/docs/guides/color-modes/)
- [Component types](https://docs.soroush.tech/styled-system/docs/guides/component-types/)
- [Default values](https://docs.soroush.tech/styled-system/docs/guides/default-values/)
- [Exceptions](https://docs.soroush.tech/styled-system/docs/guides/exceptions/)
- [Migrating](https://docs.soroush.tech/styled-system/docs/guides/migrating/)
- [Removing props from HTML](https://docs.soroush.tech/styled-system/docs/guides/removing-props-from-html/)
- [Scale aliases](https://docs.soroush.tech/styled-system/docs/guides/scale-aliases/)
- [Spacing](https://docs.soroush.tech/styled-system/docs/guides/spacing/)
- [Theming guide](https://docs.soroush.tech/styled-system/docs/guides/theming/)
- [Why powers of two](https://docs.soroush.tech/styled-system/docs/guides/why-powers-of-two/)