# RandomCodeSpace Design System — Full reference

> Every component with its prop signature and one canonical example. Auto-generated from src/components.ts on every Pages build.

Package: `@ossrandom/design-system` (npm) · `@randomcodespace/design-system` (GitHub Packages)
Live docs: https://randomcodespace.github.io/design-system/docs/

## Boilerplate

```tsx
import { ThemeProvider, ToastRegion } from "@ossrandom/design-system";
import "@ossrandom/design-system/styles.css";

function App() {
  return (
    <ThemeProvider mode="light">
      {/* your UI */}
      <ToastRegion />
    </ThemeProvider>
  );
}
```

## Tokens

- **BrandColor** = | "signal-red" // #E60000 — primary action, live state, errors | "signal-red-700" // #B30000 | "signal-red-900" // #9E0000 | "cod-gray" // #1C1C1C — primary text, ink | "cod-gray-700" // #3D3D3D | "cod-gray-500" // #5A5A5A — secondary text | "cod-gray-300" // #A6A6A6 — tertiary, disabled | "cod-gray-100" // #F5F5F5 — surface | "cod-gray-050" // #FAFAFA | "white"
- **SemanticColor** = | "success" // green-ish via signal-red? we use mono — runtime cod-gray w/ filled dot | "warning" // #D98E2B | "danger" // signal-red | "info" // cod-gray | "neutral"
- **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" | "body-lg" | "body-md" | "body-sm" | "caption" | "overline" | "code"
- **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"

## Theme

### ThemeProvider
Source: `src/components/theme.tsx` · component
Import: `import { ThemeProvider } from "@ossrandom/design-system";`

Props:

- `mode?: ThemeMode`
- `accent?: BrandColor`
- `fontFamily?: { readonly sans: string; readonly mono: string }`
- `children: ReactNode` (required)

Example:

```tsx
(() => {
  function Demo() {
    const { mode, toggle } = useTheme();
    return <Space size="sm">
      <Badge tone="info">{mode}</Badge>
      <Button onClick={toggle}>Toggle theme</Button>
    </Space>;
  }
  return <Demo />;
})()
```

Docs: https://randomcodespace.github.io/design-system/docs/ThemeProvider/

### useTheme
Source: `src/components/theme.tsx` · hook
Import: `import { useTheme } from "@ossrandom/design-system";`

Returns the current theme context: `{ mode, setMode, toggle }`.

Example:

```tsx
(() => {
  function Demo() {
    const { mode, toggle } = useTheme();
    return <Space size="sm">
      <Badge tone="info">{mode}</Badge>
      <Button onClick={toggle}>Switch theme</Button>
    </Space>;
  }
  return <Demo />;
})()
```

Docs: https://randomcodespace.github.io/design-system/docs/useTheme/

## Layout

### Card
Source: `src/components/layout.tsx` · component
Import: `import { Card } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `title?: ReactNode`
- `subtitle?: ReactNode`
- `extra?: ReactNode`
- `footer?: ReactNode`
- `bordered?: boolean`
- `hoverable?: boolean`
- `padding?: SpaceSize`
- `radius?: Radius`
- `shadow?: Shadow`
- `children?: ReactNode`

Example:

```tsx
<Card />
```

Docs: https://randomcodespace.github.io/design-system/docs/Card/

### Space
Source: `src/components/layout.tsx` · component
Import: `import { Space } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `direction?: Direction`
- `size?: SpaceSize`
- `align?: Align`
- `justify?: Justify`
- `wrap?: boolean`
- `split?: ReactNode`
- `children: ReactNode` (required)

Example:

```tsx
<Space>
  <Button>One</Button>
    <Button>Two</Button>
    <Button>Three</Button>
</Space>
```

Docs: https://randomcodespace.github.io/design-system/docs/Space/

### ScrollDiv
Source: `src/components/layout.tsx` · component
Import: `import { ScrollDiv } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `direction?: Axis`
- `height?: number | string`
- `maxHeight?: number | string`
- `width?: number | string`
- `shadow?: boolean`
- `contain?: boolean`
- `thin?: boolean`
- `children: ReactNode` (required)
- `onScroll?: (state: { scrollTop: number; scrollLeft: number; atTop: boolean; atBottom: boolean }) => void;`

Example:

```tsx
<ScrollDiv>
  <p>Scrollable content.</p><p>More content.</p><p>Keep going.</p><p>Done.</p>
</ScrollDiv>
```

Docs: https://randomcodespace.github.io/design-system/docs/ScrollDiv/

### Divider
Source: `src/components/layout.tsx` · component
Import: `import { Divider } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `direction?: Direction`
- `children?: ReactNode`
- `variant?: "solid" | "dashed"`

Example:

```tsx
<Divider />
```

Docs: https://randomcodespace.github.io/design-system/docs/Divider/

### Grid
Source: `src/components/layout.tsx` · component
Import: `import { Grid } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `columns?: number`
- `gap?: SpaceSize`
- `children: ReactNode` (required)

Example:

```tsx
<Grid>
  <Card>One</Card>
    <Card>Two</Card>
    <Card>Three</Card>
</Grid>
```

Docs: https://randomcodespace.github.io/design-system/docs/Grid/

### PageHeader
Source: `src/components/page.tsx` · component
Import: `import { PageHeader } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `title: ReactNode` (required)
- `subtitle?: ReactNode`
- `breadcrumbs?: BreadcrumbProps["items"]`
- `tabs?: TabsProps["items"]`
- `actions?: ReactNode`
- `badge?: ReactNode`
- `avatar?: ReactNode`
- `back?: { readonly label?: string; readonly onClick: () => void }; readonly size?: "xs" | "sm" | "md" | "lg" | "xl"; readonly inlineSubtitle?: boolean; readonly backInline?: boolean;`

Example:

```tsx
<PageHeader title={"Title"} />
```

Docs: https://randomcodespace.github.io/design-system/docs/PageHeader/

### AppShell
Source: `src/components/page.tsx` · component
Import: `import { AppShell } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `header?: ReactNode`
- `sidebar?: ReactNode`
- `footer?: ReactNode`
- `sidebarWidth?: number`
- `sidebarCollapsible?: boolean`
- `children: ReactNode` (required)

Example:

```tsx
<AppShell>
  <div style={{padding:24}}>Main content</div>
</AppShell>
```

Docs: https://randomcodespace.github.io/design-system/docs/AppShell/

## Buttons & actions

### Button
Source: `src/components/buttons.tsx` · component
Import: `import { Button } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `variant?: ButtonVariant`
- `size?: Size`
- `shape?: ButtonShape`
- `loading?: boolean`
- `disabled?: boolean`
- `block?: boolean`
- `iconLeft?: ReactNode`
- `iconRight?: ReactNode`
- `type?: "button" | "submit" | "reset"`
- `children?: ReactNode`
- `onClick?: (e: MouseEvent<HTMLButtonElement>) => void;`

Example:

```tsx
<Button />
```

Docs: https://randomcodespace.github.io/design-system/docs/Button/

### IconButton
Source: `src/components/buttons.tsx` · component
Import: `import { IconButton } from "@ossrandom/design-system";`

Extends: `Omit<ButtonProps, "iconLeft" | "iconRight" | "block" | "children">`

Props:

- `icon: ReactNode` (required)
- `aria-label: string` (required)
- `round?: boolean`

Example:

```tsx
<IconButton icon={<span>★</span>} aria-label={"Example"} />
```

Docs: https://randomcodespace.github.io/design-system/docs/IconButton/

### ButtonGroup
Source: `src/components/buttons.tsx` · component
Import: `import { ButtonGroup } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `children: ReactNode` (required)
- `size?: Size`
- `direction?: Direction`
- `attached?: boolean`

Example:

```tsx
<ButtonGroup>
  <Button>Save</Button>
    <Button>Discard</Button>
</ButtonGroup>
```

Docs: https://randomcodespace.github.io/design-system/docs/ButtonGroup/

## Forms & inputs

### Input
Source: `src/components/inputs.tsx` · component
Import: `import { Input } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `value?: string`
- `defaultValue?: string`
- `placeholder?: string`
- `size?: Size`
- `status?: InputStatus`
- `disabled?: boolean`
- `readOnly?: boolean`
- `invalid?: boolean`
- `prefix?: ReactNode`
- `suffix?: ReactNode`
- `clearable?: boolean`
- `type?: "text" | "email" | "password" | "url" | "search" | "tel"`
- `autoFocus?: boolean`
- `onChange?: (value: string, e: ChangeEvent<HTMLInputElement>) => void; readonly onFocus?: (e: FocusEvent<HTMLInputElement>) => void; readonly onBlur?: (e: FocusEvent<HTMLInputElement>) => void; readonly onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;`

Example:

```tsx
<Input />
```

Docs: https://randomcodespace.github.io/design-system/docs/Input/

### NumberInput
Source: `src/components/inputs.tsx` · component
Import: `import { NumberInput } from "@ossrandom/design-system";`

Extends: `Omit<InputProps, "value" | "defaultValue" | "onChange" | "type">`

Props:

- `value?: number`
- `defaultValue?: number`
- `min?: number`
- `max?: number`
- `step?: number`
- `precision?: number`
- `onChange?: (value: number) => void;`

Example:

```tsx
<NumberInput />
```

Docs: https://randomcodespace.github.io/design-system/docs/NumberInput/

### PinInput
Source: `src/components/inputs.tsx` · component
Import: `import { PinInput } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `length: 4 | 6 | 8` (required)
- `value?: string`
- `mask?: boolean`
- `autoFocus?: boolean`
- `placeholder?: string`
- `onChange?: (value: string) => void; readonly onComplete?: (value: string) => void;`

Example:

```tsx
<PinInput length={6} />
```

Docs: https://randomcodespace.github.io/design-system/docs/PinInput/

### Textarea
Source: `src/components/inputs.tsx` · component
Import: `import { Textarea } from "@ossrandom/design-system";`

Extends: `Omit<InputProps, "type" | "prefix" | "suffix" | "clearable">`

Props:

- `rows?: number`
- `autoResize?: boolean`
- `maxLength?: number`
- `showCount?: boolean`

Example:

```tsx
<Textarea />
```

Docs: https://randomcodespace.github.io/design-system/docs/Textarea/

### Select<V extends string | number = string>
Source: `src/components/selects.tsx` · component
Import: `import { Select } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `options: readonly SelectOption<V>[]` (required)
- `value?: V`
- `defaultValue?: V`
- `placeholder?: string`
- `searchable?: boolean`
- `clearable?: boolean`
- `disabled?: boolean`
- `status?: InputStatus`
- `size?: Size`
- `onChange?: (value: V, option: SelectOption<V>) => void;`

Example:

```tsx
<Select options={[
    { label: "us-east-1", value: "us-east-1" },
    { label: "eu-central-1", value: "eu-central-1" },
    { label: "ap-south-1", value: "ap-south-1" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Select/

### Combobox<V extends string | number = string>
  extends Omit<SelectProps<V>, "value" | "defaultValue" | "onChange">
Source: `src/components/selects.tsx` · component
Import: `import { Combobox } from "@ossrandom/design-system";`

Props:

- `value?: readonly V[]`
- `defaultValue?: readonly V[]`
- `multi?: true`
- `maxItems?: number`
- `creatable?: boolean`
- `onChange?: (values: readonly V[]) => void;`

Example:

```tsx
<Combobox />
```

Docs: https://randomcodespace.github.io/design-system/docs/Combobox/

### Checkbox
Source: `src/components/form-controls.tsx` · component
Import: `import { Checkbox } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `checked?: boolean`
- `defaultChecked?: boolean`
- `indeterminate?: boolean`
- `disabled?: boolean`
- `label?: ReactNode`
- `description?: ReactNode`
- `onChange?: (checked: boolean) => void;`

Example:

```tsx
<Checkbox />
```

Docs: https://randomcodespace.github.io/design-system/docs/Checkbox/

### RadioGroup<V extends string | number = string>
Source: `src/components/form-controls.tsx` · component
Import: `import { RadioGroup } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `name: string` (required)
- `options: readonly RadioOption<V>[]` (required)
- `value?: V`
- `defaultValue?: V`
- `direction?: Direction`
- `disabled?: boolean`
- `onChange?: (value: V) => void;`

Example:

```tsx
<RadioGroup name={"Ada Lovelace"} options={[
    { label: "Small", value: "sm" },
    { label: "Medium", value: "md" },
    { label: "Large", value: "lg" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/RadioGroup/

### Switch
Source: `src/components/form-controls.tsx` · component
Import: `import { Switch } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `checked?: boolean`
- `defaultChecked?: boolean`
- `size?: Size`
- `disabled?: boolean`
- `loading?: boolean`
- `label?: ReactNode`
- `onChange?: (checked: boolean) => void;`

Example:

```tsx
<Switch />
```

Docs: https://randomcodespace.github.io/design-system/docs/Switch/

### Slider
Source: `src/components/form-controls.tsx` · component
Import: `import { Slider } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `value?: number | readonly [number, number]`
- `defaultValue?: number | readonly [number, number]`
- `min?: number`
- `max?: number`
- `step?: number`
- `marks?: Readonly<Record<number, ReactNode>>`
- `range?: boolean`
- `disabled?: boolean`
- `tooltip?: "always" | "hover" | "never"`
- `onChange?: (value: number | readonly [number, number]) => void;`

Example:

```tsx
<Slider />
```

Docs: https://randomcodespace.github.io/design-system/docs/Slider/

### DatePicker
Source: `src/components/form-controls.tsx` · component
Import: `import { DatePicker } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `value?: Date`
- `defaultValue?: Date`
- `min?: Date`
- `max?: Date`
- `format?: string`
- `placeholder?: string`
- `disabled?: boolean`
- `disabledDates?: (date: Date) => boolean; readonly onChange?: (date: Date | null) => void;`

Example:

```tsx
<DatePicker />
```

Docs: https://randomcodespace.github.io/design-system/docs/DatePicker/

### DateRangePicker
Source: `src/components/form-controls.tsx` · component
Import: `import { DateRangePicker } from "@ossrandom/design-system";`

Extends: `Omit<DatePickerProps, "value" | "defaultValue" | "onChange">`

Props:

- `value?: DateRange`
- `defaultValue?: DateRange`
- `onChange?: (range: DateRange | null) => void;`

Example:

```tsx
<DateRangePicker />
```

Docs: https://randomcodespace.github.io/design-system/docs/DateRangePicker/

### FileUpload
Source: `src/components/form-controls.tsx` · component
Import: `import { FileUpload } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `accept?: string`
- `multiple?: boolean`
- `maxSize?: number`
- `maxFiles?: number`
- `disabled?: boolean`
- `variant?: "drop-zone" | "button" | "picture-card"`
- `onUpload?: (files: readonly File[]) => void | Promise<void>; readonly onError?: (error: { code: "size" | "type" | "count"; message: string }) => void;`

Example:

```tsx
<FileUpload />
```

Docs: https://randomcodespace.github.io/design-system/docs/FileUpload/

### FormField
Source: `src/components/form-controls.tsx` · component
Import: `import { FormField } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `label?: ReactNode`
- `hint?: ReactNode`
- `error?: ReactNode`
- `required?: boolean`
- `optional?: boolean`
- `htmlFor?: string`
- `children: ReactNode` (required)

Example:

```tsx
<FormField>
  <Input placeholder="us-east-1" />
</FormField>
```

Docs: https://randomcodespace.github.io/design-system/docs/FormField/

## Data display

### Badge
Source: `src/components/badges.tsx` · component
Import: `import { Badge } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `tone?: BadgeTone`
- `size?: Size`
- `children: ReactNode` (required)
- `icon?: ReactNode`
- `closable?: boolean`
- `onClose?: () => void;`

Example:

```tsx
<Badge>
  live
</Badge>
```

Docs: https://randomcodespace.github.io/design-system/docs/Badge/

### StatusDot
Source: `src/components/badges.tsx` · component
Import: `import { StatusDot } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `status: "running" | "degraded" | "failed" | "idle" | "live" | "stopped"` (required)
- `label?: ReactNode`
- `pulse?: boolean`

Example:

```tsx
<StatusDot status="running" />
```

Docs: https://randomcodespace.github.io/design-system/docs/StatusDot/

### Table<T extends object>
Source: `src/components/data-display.tsx` · component
Import: `import { Table } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `columns: readonly TableColumn<T>[]` (required)
- `data: readonly T[]` (required)
- `rowKey: keyof T | ((row: T) => string | number); readonly density?: Density; readonly bordered?: boolean; readonly striped?: boolean; readonly stickyHeader?: boolean; readonly loading?: boolean; readonly empty?: ReactNode; readonly selection?: "none" | "single" | "multi"; readonly selectedKeys?: readonly (string | number)[]; readonly onSelectionChange?: (keys: readonly (string | number)[]) => void; readonly onSort?: (key: string, dir: "asc" | "desc") => void; readonly onRowClick?: (row: T, index: number) => void;` (required)

Example:

```tsx
<Table columns={[
    { key: "id", title: "ID", dataKey: "id" },
    { key: "region", title: "Region", dataKey: "region" },
    { key: "cpu", title: "CPU", dataKey: "cpu", render: (v) => v + "%" },
  ]} data={[
    { id: "svc_001", region: "us-east-1", cpu: 42 },
    { id: "svc_002", region: "eu-central-1", cpu: 73 },
    { id: "svc_003", region: "ap-south-1", cpu: 18 },
  ]} rowKey={"id"} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Table/

### Stat
Source: `src/components/data-display.tsx` · component
Import: `import { Stat } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `label: ReactNode` (required)
- `value: ReactNode` (required)
- `unit?: ReactNode`
- `delta?: { readonly value: number; readonly direction: "up" | "down"; readonly tone?: "good" | "bad" | "neutral" }`
- `sparkline?: readonly number[]`

Example:

```tsx
<Stat label={"Label"} value={0} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Stat/

### Avatar
Source: `src/components/data-display.tsx` · component
Import: `import { Avatar } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `src?: string`
- `alt?: string`
- `initials?: string`
- `size?: Size | number`
- `shape?: "circle" | "square"`
- `status?: StatusDotProps["status"]`

Example:

```tsx
<Avatar />
```

Docs: https://randomcodespace.github.io/design-system/docs/Avatar/

### Timeline
Source: `src/components/data-display.tsx` · component
Import: `import { Timeline } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `items: readonly TimelineItem[]` (required)
- `mode?: "left" | "right" | "alternate"`

Example:

```tsx
<Timeline items={[
    { title: "v0.1.0 released", time: "4m ago" },
    { title: "Build #128 passed", time: "12m ago" },
    { title: "PR #42 merged", time: "1h ago" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Timeline/

## Navigation

### Tabs<K extends string = string>
Source: `src/components/navigation.tsx` · component
Import: `import { Tabs } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `items: readonly TabItem<K>[]` (required)
- `value?: K`
- `defaultValue?: K`
- `variant?: "line" | "card" | "segment" | "pill"`
- `size?: Size`
- `onChange?: (key: K) => void; readonly scrollable?: boolean;`

Example:

```tsx
<Tabs items={[
    { key: "overview", label: "Overview" },
    { key: "logs", label: "Logs" },
    { key: "settings", label: "Settings" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Tabs/

### Menu<K extends string = string>
Source: `src/components/navigation.tsx` · component
Import: `import { Menu } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `items: readonly (MenuItem<K> | { readonly type: "separator" } | { readonly type: "label"; readonly label: ReactNode })[]` (required)
- `selectedKeys?: readonly K[]`
- `defaultSelectedKeys?: readonly K[]`
- `mode?: "horizontal" | "vertical" | "inline"`
- `onSelect?: (key: K) => void;`

Example:

```tsx
<Menu items={[
    { key: "edit", label: "Edit" },
    { key: "duplicate", label: "Duplicate" },
    { key: "delete", label: "Delete", danger: true },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Menu/

### Breadcrumb
Source: `src/components/navigation.tsx` · component
Import: `import { Breadcrumb } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `items: readonly BreadcrumbItem[]` (required)
- `separator?: ReactNode`
- `maxItems?: number`

Example:

```tsx
<Breadcrumb items={[
    { label: "Services", href: "#" },
    { label: "API gateway", href: "#" },
    { label: "Settings" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Breadcrumb/

### Pagination
Source: `src/components/navigation.tsx` · component
Import: `import { Pagination } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `total: number` (required)
- `pageSize: number` (required)
- `current: number` (required)
- `siblings?: number`
- `showJumper?: boolean`
- `showSizeChanger?: boolean`
- `pageSizeOptions?: readonly number[]`
- `onChange?: (page: number, pageSize: number) => void;`

Example:

```tsx
<Pagination total={120} pageSize={20} current={1} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Pagination/

### Steps
Source: `src/components/navigation.tsx` · component
Import: `import { Steps } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `items: readonly StepItem[]` (required)
- `current: number` (required)
- `direction?: Direction`
- `size?: Size`
- `onChange?: (index: number) => void;`

Example:

```tsx
<Steps items={[
    { title: "Plan" },
    { title: "Build" },
    { title: "Deploy" },
  ]} current={1} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Steps/

## Feedback

### Alert
Source: `src/components/feedback.tsx` · component
Import: `import { Alert } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `severity: "info" | "success" | "warning" | "danger"` (required)
- `title?: ReactNode`
- `children?: ReactNode`
- `closable?: boolean`
- `icon?: ReactNode | false`
- `action?: ReactNode`
- `onClose?: () => void;`

Example:

```tsx
<Alert severity={"info"} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Alert/

### Modal
Source: `src/components/feedback.tsx` · component
Import: `import { Modal } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `open: boolean` (required)
- `title?: ReactNode`
- `description?: ReactNode`
- `size?: Size | "fullscreen"`
- `closeOnEsc?: boolean`
- `closeOnBackdrop?: boolean`
- `footer?: ReactNode`
- `children?: ReactNode`
- `onClose: () => void;` (required)

Example:

```tsx
(() => {
  function Demo() {
    const [open, setOpen] = React.useState(false);
    return <>
      <Button onClick={() => setOpen(true)}>Open modal</Button>
      <Modal
        open={open}
        onClose={() => setOpen(false)} title="Open me">
        <p>Body content.</p>
      </Modal>
    </>;
  }
  return <Demo />;
})()
```

Docs: https://randomcodespace.github.io/design-system/docs/Modal/

### Drawer
Source: `src/components/feedback.tsx` · component
Import: `import { Drawer } from "@ossrandom/design-system";`

Extends: `Omit<ModalProps, "size">`

Props:

- `placement?: "left" | "right" | "top" | "bottom"`
- `width?: number | string`

Example:

```tsx
<Drawer />
```

Docs: https://randomcodespace.github.io/design-system/docs/Drawer/

### Progress
Source: `src/components/feedback.tsx` · component
Import: `import { Progress } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `value: number` (required)
- `indeterminate?: boolean`
- `variant?: "linear" | "circular"`
- `size?: Size`
- `tone?: "neutral" | "danger" | "warning"`
- `showValue?: boolean`

Example:

```tsx
<Progress value={0} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Progress/

### Skeleton
Source: `src/components/feedback.tsx` · component
Import: `import { Skeleton } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `variant?: "text" | "rect" | "circle"`
- `width?: number | string`
- `height?: number | string`
- `lines?: number`
- `animated?: boolean`

Example:

```tsx
<Skeleton />
```

Docs: https://randomcodespace.github.io/design-system/docs/Skeleton/

### Spin
Source: `src/components/feedback.tsx` · component
Import: `import { Spin } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `size?: Size`
- `tone?: "neutral" | "danger"`
- `label?: ReactNode`

Example:

```tsx
<Spin />
```

Docs: https://randomcodespace.github.io/design-system/docs/Spin/

### Tooltip
Source: `src/components/feedback.tsx` · component
Import: `import { Tooltip } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `content: ReactNode` (required)
- `placement?: "top" | "right" | "bottom" | "left" | "auto"`
- `delay?: number`
- `children: ReactNode` (required)

Example:

```tsx
<Tooltip
  content={"A short tooltip"}
>
  <Button>Hover me</Button>
</Tooltip>
```

Docs: https://randomcodespace.github.io/design-system/docs/Tooltip/

### toast
Source: `src/components/feedback.tsx` · component
Import: `import { toast } from "@ossrandom/design-system";`

Example:

```tsx
(() => {
  function Demo() {
    return <Space size="sm">
      <Button onClick={() => toast.show({ title: "Saved", severity: "success" })}>Success</Button>
      <Button onClick={() => toast.show({ title: "Heads up", severity: "info" })}>Info</Button>
      <Button onClick={() => toast.show({ title: "Failed", severity: "danger" })}>Danger</Button>
    </Space>;
  }
  return <><Demo /><ToastRegion /></>;
})()
```

Docs: https://randomcodespace.github.io/design-system/docs/toast/

### ToastRegion
Source: `src/components/feedback.tsx` · component
Import: `import { ToastRegion } from "@ossrandom/design-system";`

Example:

```tsx
(() => {
  function Demo() {
    return <Space size="sm">
      <Button onClick={() => toast.show({ title: "Saved", severity: "success" })}>Success</Button>
      <Button onClick={() => toast.show({ title: "Heads up", severity: "info" })}>Info</Button>
      <Button onClick={() => toast.show({ title: "Failed", severity: "danger" })}>Danger</Button>
    </Space>;
  }
  return <><Demo /><ToastRegion /></>;
})()
```

Docs: https://randomcodespace.github.io/design-system/docs/ToastRegion/

## Content

### Chat
Source: `src/components/chat.tsx` · component
Import: `import { Chat } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `messages: readonly ChatMessage[]` (required)
- `streaming?: boolean`
- `placeholder?: string`
- `onSend?: (text: string, attachments: readonly File[]) => void | Promise<void>; readonly onStop?: () => void; readonly suggestions?: readonly string[];`

Example:

```tsx
<Chat messages={[
    { role: "user", content: "Deploy v0.2.0?" },
    { role: "assistant", content: "Running checks…" },
    { role: "tool", content: "All checks passed." },
    { role: "assistant", content: "Proceeding with deploy." },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Chat/

### CodeBlock
Source: `src/components/code.tsx` · component
Import: `import { CodeBlock } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `code: string` (required)
- `language?: CodeLanguage`
- `filename?: string`
- `showLineNumbers?: boolean`
- `highlightLines?: readonly number[]`
- `copyable?: boolean`
- `wrap?: boolean`
- `onCopy?: () => void;`

Example:

```tsx
<CodeBlock code="…" />
```

Docs: https://randomcodespace.github.io/design-system/docs/CodeBlock/

### Markdown
Source: `src/components/code.tsx` · component
Import: `import { Markdown } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `source: string` (required)
- `variant?: "default" | "compact"`
- `allowHtml?: boolean`
- `components?: Readonly<Partial<Record<"h1" | "h2" | "h3" | "p" | "code" | "a" | "blockquote", (props: { children: ReactNode }) => ReactNode>>>; readonly onLinkClick?: (href: string) => void;`

Example:

```tsx
<Markdown source="…" />
```

Docs: https://randomcodespace.github.io/design-system/docs/Markdown/

### Terminal
Source: `src/components/code.tsx` · component
Import: `import { Terminal } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `title?: string`
- `lines: readonly TerminalLine[]` (required)
- `streaming?: boolean`
- `height?: number | string`
- `searchable?: boolean`
- `tabs?: readonly { readonly key: string; readonly label: string; readonly active?: boolean }[]`
- `onInput?: (cmd: string) => void; readonly onTabChange?: (key: string) => void;`

Example:

```tsx
<Terminal lines={[
    { kind: "command", content: "$ pnpm deploy --env=prod" },
    { kind: "output", content: "→ Building…" },
    { kind: "output", content: "✓ Deployed v0.2.0" },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Terminal/

### RichTextEditor
Source: `src/components/code.tsx` · component
Import: `import { RichTextEditor } from "@ossrandom/design-system";`

Extends: `BaseProps`

Props:

- `value?: string`
- `defaultValue?: string`
- `placeholder?: string`
- `toolbar?: "full" | "compact" | "inline" | "none"`
- `slashMenu?: boolean`
- `bubbleMenu?: boolean`
- `mentionsSource?: (query: string) => Promise<readonly { id: string; label: string }[]>; readonly collab?: { readonly room: string`
- `user: { id: string; name: string; color?: string } }; readonly minHeight?: number | string; readonly maxLength?: number; readonly readOnly?: boolean; readonly onChange?: (markdown: string) => void;` (required)

Example:

```tsx
<RichTextEditor user={() => {}} />
```

Docs: https://randomcodespace.github.io/design-system/docs/RichTextEditor/

## Charts (subpath)

### Chart
Source: `src/charts/Chart.tsx` · component
Import: `import { Chart } from "@ossrandom/design-system/charts";`
Peer deps (install on demand): `uplot (canvas, default)`, `@deck.gl/core + @deck.gl/layers (webgl/webgpu)`

Extends: `BaseProps`

Props:

- `type?: ChartType`
- `timestamps: readonly number[]` (required)
- `series: readonly ChartSeries[]` (required)
- `height?: number`
- `showGrid?: boolean`
- `showLegend?: boolean`
- `xLabel?: string`
- `yLabel?: string`
- `engine?: RenderEngine`
- `onPointClick?: (point: ChartPoint, seriesIndex: number) => void;`

Example:

```tsx
<Chart timestamps={[]} series={[]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Chart/

### Sparkline
Source: `src/charts/Sparkline.tsx` · component
Import: `import { Sparkline } from "@ossrandom/design-system/charts";`
Peer deps: none (zero-dep render path)

Extends: `BaseProps`

Props:

- `data: readonly number[]` (required)
- `width?: number`
- `height?: number`
- `stroke?: string`
- `fill?: string`
- `showArea?: boolean`
- `strokeWidth?: number`

Example:

```tsx
<Sparkline data={[
    { id: "svc_001", region: "us-east-1", cpu: 42 },
    { id: "svc_002", region: "eu-central-1", cpu: 73 },
    { id: "svc_003", region: "ap-south-1", cpu: 18 },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Sparkline/

### Donut
Source: `src/charts/Donut.tsx` · component
Import: `import { Donut } from "@ossrandom/design-system/charts";`
Peer deps: none (zero-dep render path)

Extends: `BaseProps`

Props:

- `segments: readonly DonutSegment[]` (required)
- `size?: number`
- `thickness?: number`
- `centerLabel?: ReactNode`
- `centerValue?: ReactNode`
- `showLegend?: boolean`
- `onSegmentClick?: (segment: DonutSegment, index: number) => void;`

Example:

```tsx
<Donut segments={[]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Donut/

### RadialGauge
Source: `src/charts/Donut.tsx` · component
Import: `import { RadialGauge } from "@ossrandom/design-system/charts";`
Peer deps: none (zero-dep render path)

Extends: `BaseProps`

Props:

- `value: number` (required)
- `max?: number`
- `size?: number`
- `thickness?: number`
- `label?: ReactNode`
- `tone?: "neutral" | "good" | "warning" | "bad"`

Example:

```tsx
<RadialGauge value={0} />
```

Docs: https://randomcodespace.github.io/design-system/docs/RadialGauge/

### UptimeBar
Source: `src/charts/UptimeBar.tsx` · component
Import: `import { UptimeBar } from "@ossrandom/design-system/charts";`
Peer deps: none (zero-dep render path)

Extends: `BaseProps`

Props:

- `cells: readonly UptimeCell[]` (required)
- `height?: number`
- `gap?: number`
- `cellRadius?: number`
- `onCellHover?: (cell: UptimeCell | null, index: number) => void;`

Example:

```tsx
<UptimeBar cells={[]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/UptimeBar/

### Treemap
Source: `src/charts/Treemap.tsx` · component
Import: `import { Treemap } from "@ossrandom/design-system/charts";`
Peer deps (install on demand): `d3-hierarchy`

Extends: `BaseProps`

Props:

- `data: TreemapNode` (required)
- `height?: number`
- `padding?: number`
- `maxDepth?: number`
- `engine?: RenderEngine`
- `valueFormat?: (value: number) => string; readonly onNodeClick?: (node: TreemapNode) => void; readonly onNodeHover?: (node: TreemapNode | null) => void;`

Example:

```tsx
<Treemap data={[
    { id: "svc_001", region: "us-east-1", cpu: 42 },
    { id: "svc_002", region: "eu-central-1", cpu: 73 },
    { id: "svc_003", region: "ap-south-1", cpu: 18 },
  ]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/Treemap/

### ServiceMap
Source: `src/charts/ServiceMap.tsx` · component
Import: `import { ServiceMap } from "@ossrandom/design-system/charts";`
Peer deps (install on demand): `cytoscape + cytoscape-cose-bilkent (canvas)`, `@deck.gl/core + @deck.gl/layers + d3-force (webgl)`

Extends: `BaseProps`

Props:

- `nodes: readonly ServiceNode[]` (required)
- `edges: readonly ServiceEdge[]` (required)
- `height?: number`
- `layout?: "cose-bilkent" | "circle" | "grid" | "concentric" | "breadthfirst"`
- `engine?: RenderEngine`
- `onNodeClick?: (node: ServiceNode) => void; readonly onEdgeClick?: (edge: { source: string; target: string }) => void;`

Example:

```tsx
<ServiceMap nodes={[]} edges={[]} />
```

Docs: https://randomcodespace.github.io/design-system/docs/ServiceMap/