# clean-design-system

> A quiet, editorial design system for complex search applications.
> 68 independently installable components in TypeScript, styled
> with plain CSS custom properties — no runtime, no CSS framework, no build
> plugin. Light and dark from one attribute. WCAG 2.2 AA contrast and keyboard
> behaviour throughout, checked by axe over every story in CI.

Docs and live examples: https://gitu.github.io/clean-design-system/
Source: https://github.com/gitu/clean-design-system

## Two ways to install

**Copy the source in** (no account needed, and the files become yours):

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/<name>.json

The shadcn CLI installs from any public registry URL. Transitive dependencies
resolve automatically — asking for `date-input` brings the tokens, `cx` and the
seven components a date field is made of. Everything lands under one
`components/ui/cds/` namespace and imports its neighbours relatively, so it works
the same in Vite, Next and Remix. Requires a `components.json` at the project
root; Tailwind is *not* used or required.

**Or as a package** (GitHub Packages — needs a token with `read:packages`, even
though the package is public):

    npm install @gitu/clean-design-system

## Rules that apply to everything

- Wrap the tree in `<ThemeProvider>` and import the stylesheet once. Nothing is
  styled without it.
- Class names are prefixed `cds-`. The reset is wrapped in `:where()`, so it has
  zero specificity and cannot outrank your own CSS or Tailwind.
- Colour comes from `--cds-color-*` custom properties; there are three theme
  blocks (light, `prefers-color-scheme: dark`, and `[data-cds-theme='dark']`)
  kept in sync by a build check.
- Form controls wrapped in `<Field>` inherit their id, `aria-describedby`,
  invalid and required state automatically — do not wire those by hand.
- Every component takes `className` and merges it.
- Charts are the only thing with runtime dependencies (three `@visx/*` packages).
- Self-hosted fonts are optional; the tokens fall back to Georgia and the system
  sans.

## Components

Every component below installs with the command shown. Names are the kebab-cased
component name. Full props for all of them: https://gitu.github.io/clean-design-system/llms-full.txt

### Root

#### ThemeProvider

The root wrapper.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/theme-provider.json

Exports: ThemeProvider, ThemeToggle, useTheme
Depends on: icon, icon-button


### Primitives

#### Avatar

A person, as a picture or as their initials.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/avatar.json

Exports: Avatar

#### Badge

A read-only status marker: pipeline state, document type, embargo flag.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/badge.json

Exports: Badge

#### Button

The system's one button.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/button.json

Exports: Button
Depends on: spinner

#### Callout

An inline status block: what just happened, and what to do about it.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/callout.json

Exports: Callout
Depends on: icon, icon-button

#### Divider

A hairline rule — the main structural device in this system.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/divider.json

Exports: Divider

#### Icon

One glyph from the set, drawn rather than loaded.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/icon.json

Exports: Icon, iconNames

#### IconButton

A square Button carrying an icon and nothing else.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/icon-button.json

Exports: IconButton
Depends on: button, spinner

#### Kbd

Keyboard shortcut hint.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/kbd.json

Exports: Kbd

#### Progress

A determinate or indeterminate progress bar.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/progress.json

Exports: Progress

#### Skeleton

Loading placeholder.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/skeleton.json

Exports: Skeleton

#### Slider

One value along a range.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/slider.json

Exports: Slider
Depends on: field

#### Spinner

An indeterminate wait.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/spinner.json

Exports: Spinner

#### Tag

A value the user put into the interface — an applied filter, a chosen keyword.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/tag.json

Exports: Tag
Depends on: icon


### Forms

#### Calendar

A month grid for picking a day or a span.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/calendar.json

Exports: Calendar
Depends on: icon, icon-button

#### Checkbox

A real <input type="checkbox"> under a drawn box.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/checkbox.json

Exports: Checkbox
Depends on: field, icon

#### DateInput

A date you can type or point at.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/date-input.json

Exports: DateInput
Depends on: button, calendar, field, icon, input

#### DateRangePicker

A button that opens a two-month calendar and reports a span.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/date-range-picker.json

Exports: DateRangePicker
Depends on: button, calendar, icon

#### DateTimeInput

A date and a time, as two fields that behave like one value.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/date-time-input.json

Exports: DateTimeInput
Depends on: calendar, date-input, field, time-input

#### Field

Label, hint, error and the ARIA wiring between them.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/field.json

Exports: Field, FieldContext, useFieldControl

#### FileDrop

A drop target for files.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/file-drop.json

Exports: FileDrop
Depends on: field, icon

#### Input

A single-line text field, with room either side of the text.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/input.json

Exports: Input
Depends on: field

#### MarkdownEditor

A text field for prose, with the markup it accepts made visible.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/markdown-editor.json

Exports: MarkdownEditor
Depends on: field, icon, icon-button, markdown

#### Radio

One option in a mutually exclusive set.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/radio.json

Exports: Radio, RadioGroup

#### SegmentedControl

A small set of mutually exclusive choices shown all at once — sort order, result density, time window.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/segmented-control.json

Exports: SegmentedControl

#### Select

A native <select> with the system's chrome.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/select.json

Exports: Select
Depends on: field, icon

#### Switch

For settings that take effect immediately — "include archived", "live updates".

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/switch.json

Exports: Switch
Depends on: field

#### Textarea

A multi-line text field.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/textarea.json

Exports: Textarea
Depends on: field

#### TimeInput

A time of day, typed, with the round numbers one keystroke away.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/time-input.json

Exports: TimeInput
Depends on: field, icon, input


### Search

#### ActiveFilters

The receipt for what the user has narrowed to.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/active-filters.json

Exports: ActiveFilters
Depends on: tag

#### CommandPalette

Keyboard-first launcher for actions, saved searches and navigation.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/command-palette.json

Exports: CommandPalette
npm dependencies: react-dom
Depends on: icon, kbd, spinner

#### FacetGroup

One collapsible dimension in the filter sidebar — Section, Author, Year.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/facet-group.json

Exports: FacetGroup
Depends on: icon, input

#### FacetItem

One selectable value inside a FacetGroup.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/facet-item.json

Exports: FacetItem
Depends on: checkbox

#### Highlight

Marks query terms inside a snippet.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/highlight.json

Exports: Highlight

#### Pagination

Page numbers, with the ends always reachable.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/pagination.json

Exports: Pagination
Depends on: icon

#### RangeFilter

A two-ended bound for numeric or date facets.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/range-filter.json

Exports: RangeFilter
Depends on: button, input

#### ResultCard

One search result.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/result-card.json

Exports: ResultCard
Depends on: highlight

#### ResultList

The results column: rules between rows, placeholders while loading, and an empty slot.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/result-list.json

Exports: ResultList
Depends on: skeleton

#### ResultMeta

The line that tells someone whether their search worked: how many, which slice they are looking at, and how long it took.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/result-meta.json

Exports: ResultMeta

#### SearchInput

The primary search field.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/search-input.json

Exports: SearchInput
Depends on: icon, kbd, spinner

#### SortControl

Sort field plus direction.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/sort-control.json

Exports: SortControl
Depends on: icon, select


### Charts

#### AreaChart

Quantity over time, as filled bands.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/area-chart.json

Exports: AreaChart
Depends on: chart

#### BarChart

Categorical comparison, grouped or stacked, in either orientation.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/bar-chart.json

Exports: BarChart
npm dependencies: @visx/scale
Depends on: chart, chart-tooltip

#### ChartFrame

The titled region a chart sits in — Panel, but with the slots a chart actually needs: a legend, a drill-down trail, a source note and a data table.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chart-frame.json

Exports: ChartFrame
Depends on: icon

#### ChartGroup

Links several charts so they share a hover, a filter, a hidden-series set and a zoom window.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chart-group.json

Exports: ChartGroup, ChartGroupContext, ChartHoverContext
Depends on: chart

#### ChartLegend

The key, and the control for hiding series.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chart-legend.json

Exports: ChartLegend

#### ChartTooltip

The readout beside the crosshair.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chart-tooltip.json

Exports: ChartTooltip

#### LineChart

A time series.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/line-chart.json

Exports: LineChart
Depends on: chart

#### Sparkline

A word-sized chart, for a table cell or the corner of a stat tile.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/sparkline.json

Exports: Sparkline
npm dependencies: @visx/scale, @visx/shape
Depends on: chart


### Prose

#### Markdown

A deliberately small Markdown subset, rendered as React elements.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/markdown.json

Exports: Markdown


### Data

#### DataTable

A dense, ruled table.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/data-table.json

Exports: DataTable
Depends on: checkbox, icon, skeleton

#### EmptyState

A zero-result state.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/empty-state.json

Exports: EmptyState


### Layout

#### AppShell

The page frame for a search application: masthead, filter column, results, optional detail pane.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/app-shell.json

Exports: AppShell

#### Breadcrumbs

Path back up through a collection, an archive, or a folder tree.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/breadcrumbs.json

Exports: Breadcrumbs

#### ConfirmPopover

A confirmation anchored to the thing being confirmed.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/confirm-popover.json

Exports: ConfirmPopover
Depends on: button, popover, stack

#### Dialog

A centred modal, for a decision or a short form.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/dialog.json

Exports: Dialog
npm dependencies: react-dom
Depends on: icon, icon-button

#### Disclosure

A summary row that opens.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/disclosure.json

Exports: Disclosure
Depends on: icon

#### Drawer

A slide-over panel: filters on narrow screens, a result's detail view beside the list, a bulk-edit form.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/drawer.json

Exports: Drawer
npm dependencies: react-dom
Depends on: icon, icon-button

#### Menu

A dropdown of actions, anchored to whatever opens it.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/menu.json

Exports: Menu

#### NavList

The navigation for an application with more than one page.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/nav-list.json

Exports: NavList

#### Panel

A titled region.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/panel.json

Exports: Panel

#### Popover

Arbitrary content anchored to a control — a short form, a set of choices, a confirmation.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/popover.json

Exports: Popover

#### Stack

The layout primitive for glue between components.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/stack.json

Exports: Stack

#### Tabs

Result scopes, document sections, saved views.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/tabs.json

Exports: Tabs

#### Toast

Announces what just happened, without stealing focus.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/toast.json

Exports: ToastProvider, useToast
npm dependencies: react-dom
Depends on: icon, icon-button

#### Toolbar

A row of controls above or below a content region.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/toolbar.json

Exports: Toolbar


### Assistant

#### Chat

The assistant family: transcript, messages, tool calls, artefacts, files, diffs, images and question sets.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chat.json

Exports: ChatArtifact, ChatComposer, ChatDiff, ChatFile, ChatImage, ChatMarkdown, ChatMessage, ChatQuestion, ChatThread, ChatToolCall
Depends on: avatar, button, dialog, icon, input, markdown, spinner, tabs


### Internal

#### Chart

Internal chart machinery — scales, axes, the SVG surface, the keyboard cursor. Installed as a dependency of the charts; not used directly.

    npx shadcn@latest add https://gitu.github.io/clean-design-system/r/chart.json

Exports: CartesianChart, ChartAxis, ChartGrid, ChartSrTable, ChartSurface
npm dependencies: @visx/curve, @visx/scale, @visx/shape
Depends on: chart-group, chart-tooltip