# RandomCodeSpace Design System

> Strongly-typed React component library — 58 components across 9 categories (51 core + 7 charts). Bricolage Grotesque on Cod Gray, Signal Red accent, single CSS file, zero core runtime deps. Built for self-hosted developer tooling.

## Install

```bash
npm install @ossrandom/design-system
# or, from GitHub Packages mirror (different scope):
npm install @randomcodespace/design-system
```

Charts ship at the `@ossrandom/design-system/charts` subpath and pull heavier peer deps (`uplot`, `d3-hierarchy`, `cytoscape`, `@deck.gl/core` + `@deck.gl/layers`). Install only the ones the charts you render require — see the Charts section below.

## Usage

```tsx
import { ThemeProvider, Button, toast } from "@ossrandom/design-system";
import { Chart, ServiceMap } from "@ossrandom/design-system/charts";
import "@ossrandom/design-system/styles.css";

<ThemeProvider mode="light">
  <Button onClick={() => toast.show({ title: "Saved" })}>Save</Button>
</ThemeProvider>
```

## Components

### Theme

- [ThemeProvider](https://randomcodespace.github.io/design-system/docs/ThemeProvider/) — 4 props
- [useTheme](https://randomcodespace.github.io/design-system/docs/useTheme/) — hook

### Layout

- [Card](https://randomcodespace.github.io/design-system/docs/Card/) — 10 props
- [Space](https://randomcodespace.github.io/design-system/docs/Space/) — 7 props
- [ScrollDiv](https://randomcodespace.github.io/design-system/docs/ScrollDiv/) — 9 props
- [Divider](https://randomcodespace.github.io/design-system/docs/Divider/) — 3 props
- [Grid](https://randomcodespace.github.io/design-system/docs/Grid/) — 3 props
- [PageHeader](https://randomcodespace.github.io/design-system/docs/PageHeader/) — 8 props
- [AppShell](https://randomcodespace.github.io/design-system/docs/AppShell/) — 6 props

### Buttons & actions

- [Button](https://randomcodespace.github.io/design-system/docs/Button/) — 11 props
- [IconButton](https://randomcodespace.github.io/design-system/docs/IconButton/) — 3 props
- [ButtonGroup](https://randomcodespace.github.io/design-system/docs/ButtonGroup/) — 4 props

### Forms & inputs

- [Input](https://randomcodespace.github.io/design-system/docs/Input/) — 14 props
- [NumberInput](https://randomcodespace.github.io/design-system/docs/NumberInput/) — 7 props
- [PinInput](https://randomcodespace.github.io/design-system/docs/PinInput/) — 6 props
- [Textarea](https://randomcodespace.github.io/design-system/docs/Textarea/) — 4 props
- [Select<V extends string | number = string>](https://randomcodespace.github.io/design-system/docs/Select/) — 10 props
- [Combobox<V extends string | number = string>
  extends Omit<SelectProps<V>, "value" | "defaultValue" | "onChange">](https://randomcodespace.github.io/design-system/docs/Combobox/) — 6 props
- [Checkbox](https://randomcodespace.github.io/design-system/docs/Checkbox/) — 7 props
- [RadioGroup<V extends string | number = string>](https://randomcodespace.github.io/design-system/docs/RadioGroup/) — 7 props
- [Switch](https://randomcodespace.github.io/design-system/docs/Switch/) — 7 props
- [Slider](https://randomcodespace.github.io/design-system/docs/Slider/) — 10 props
- [DatePicker](https://randomcodespace.github.io/design-system/docs/DatePicker/) — 8 props
- [DateRangePicker](https://randomcodespace.github.io/design-system/docs/DateRangePicker/) — 3 props
- [FileUpload](https://randomcodespace.github.io/design-system/docs/FileUpload/) — 7 props
- [FormField](https://randomcodespace.github.io/design-system/docs/FormField/) — 7 props

### Data display

- [Badge](https://randomcodespace.github.io/design-system/docs/Badge/) — 6 props
- [StatusDot](https://randomcodespace.github.io/design-system/docs/StatusDot/) — 3 props
- [Table<T extends object>](https://randomcodespace.github.io/design-system/docs/Table/) — 3 props
- [Stat](https://randomcodespace.github.io/design-system/docs/Stat/) — 5 props
- [Avatar](https://randomcodespace.github.io/design-system/docs/Avatar/) — 6 props
- [Timeline](https://randomcodespace.github.io/design-system/docs/Timeline/) — 2 props

### Navigation

- [Tabs<K extends string = string>](https://randomcodespace.github.io/design-system/docs/Tabs/) — 6 props
- [Menu<K extends string = string>](https://randomcodespace.github.io/design-system/docs/Menu/) — 5 props
- [Breadcrumb](https://randomcodespace.github.io/design-system/docs/Breadcrumb/) — 3 props
- [Pagination](https://randomcodespace.github.io/design-system/docs/Pagination/) — 8 props
- [Steps](https://randomcodespace.github.io/design-system/docs/Steps/) — 5 props

### Feedback

- [Alert](https://randomcodespace.github.io/design-system/docs/Alert/) — 7 props
- [Modal](https://randomcodespace.github.io/design-system/docs/Modal/) — 9 props
- [Drawer](https://randomcodespace.github.io/design-system/docs/Drawer/) — 2 props
- [Progress](https://randomcodespace.github.io/design-system/docs/Progress/) — 6 props
- [Skeleton](https://randomcodespace.github.io/design-system/docs/Skeleton/) — 5 props
- [Spin](https://randomcodespace.github.io/design-system/docs/Spin/) — 3 props
- [Tooltip](https://randomcodespace.github.io/design-system/docs/Tooltip/) — 4 props
- [toast](https://randomcodespace.github.io/design-system/docs/toast/) — 0 props
- [ToastRegion](https://randomcodespace.github.io/design-system/docs/ToastRegion/) — 0 props

### Content

- [Chat](https://randomcodespace.github.io/design-system/docs/Chat/) — 4 props
- [CodeBlock](https://randomcodespace.github.io/design-system/docs/CodeBlock/) — 8 props
- [Markdown](https://randomcodespace.github.io/design-system/docs/Markdown/) — 4 props
- [Terminal](https://randomcodespace.github.io/design-system/docs/Terminal/) — 7 props
- [RichTextEditor](https://randomcodespace.github.io/design-system/docs/RichTextEditor/) — 8 props

### Charts (subpath)

Subpath: `@ossrandom/design-system/charts`

- [Chart](https://randomcodespace.github.io/design-system/docs/Chart/) — 10 props
- [Sparkline](https://randomcodespace.github.io/design-system/docs/Sparkline/) — 7 props
- [Donut](https://randomcodespace.github.io/design-system/docs/Donut/) — 7 props
- [RadialGauge](https://randomcodespace.github.io/design-system/docs/RadialGauge/) — 6 props
- [UptimeBar](https://randomcodespace.github.io/design-system/docs/UptimeBar/) — 5 props
- [Treemap](https://randomcodespace.github.io/design-system/docs/Treemap/) — 6 props
- [ServiceMap](https://randomcodespace.github.io/design-system/docs/ServiceMap/) — 6 props

## Tokens

Strongly-typed unions exposed as TypeScript types and CSS custom properties:

- `BrandColor` = | "signal-red" // #E60000 — primary action, live state, errors | "signal-red-…
- `SemanticColor` = | "success" // green-ish via signal-red? we use mono — runtime cod-gray w/ fi…
- `ThemeMode` = "light" | "dark"
- `SpaceSize` = "xs" | "sm" | "md" | "lg" | "xl" | number
- `Radius` = "none" | "sm" | "md" | "lg" | "pill" | "circle" | number
- `Shadow` = "none" | "sm" | "md" | "lg" | "overlay"
- `FontFamily` = "sans" | "mono"
- `FontWeight` = 400 | 500 | 600 | 700
- `TypeScale` = | "display-xl" | "display-lg" | "display-md" | "h1" | "h2" | "h3" | "h4" | "b…
- `Size` = "xs" | "sm" | "md" | "lg"
- `Density` = "comfortable" | "default" | "compact"
- `Direction` = "horizontal" | "vertical"
- `Axis` = "x" | "y" | "both"
- `Align` = "start" | "center" | "end" | "baseline" | "stretch"
- `Justify` = "start" | "center" | "end" | "between" | "around" | "evenly"

## Optional

- [Full API reference (every prop signature + example)](https://randomcodespace.github.io/design-system/llms-full.txt)
- [Live docs with previews](https://randomcodespace.github.io/design-system/docs/)
- [Playground](https://randomcodespace.github.io/design-system/docs/playground/)
- [Source code](https://github.com/RandomCodeSpace/design-system)