# Surflane

> A design system for platform development: OKLCH design tokens (@surflane/design-tokens) and accessible React 19 components built on Base UI (@surflane/ui), with tested application patterns. Version 0.23.0.

Install the packages and Base UI: `npm install @surflane/ui @surflane/design-tokens @surflane/css @base-ui/react`. They are ESM-only and need React 19.

- Import the CSS once: `@surflane/ui/all.css` brings every stylesheet in its cascade layer. With Tailwind CSS v4, import it with `layer(components)`.
- Set `data-theme="light"` or `"dark"` on `<html>` before paint. Any element can carry `data-theme` to re-theme its subtree.
- In React Server Components, use flat part names such as `DialogRoot` instead of `Dialog.Root`.
- LineChart, AreaChart, BarChart, DatePicker, Markdown and Tree import from `@surflane/ui/chart`, `/date-picker`, `/markdown` and `/tree`, and need their optional peers: `recharts`, `react-aria-components`, `react-markdown` with `remark-gfm`, and `@headless-tree/core` with `@headless-tree/react` and `@tanstack/react-virtual`. Code highlights only inside `<SyntaxHighlighting>` from `@surflane/ui/syntax-highlighting`, which needs `shiki`.
- `SizeProvider size="small"` resizes a whole composition, including portals.
- Style with tokens through `var(--token-name)`, never raw values. With Tailwind CSS v4, import `@surflane/design-tokens/tailwind.css`.
- To theme, import a preset with the stylesheets, such as `@surflane/design-tokens/themes/stone.css` or `themes/accent-violet.css`, or generate CSS with `createTheme` and `themeCss` from `@surflane/design-tokens/theme-builder`. For shadcn/ui, import `@surflane/design-tokens/shadcn.css`.
- Give each control a name that describes its purpose, connect errors to their controls, and signal state with more than color.

## Docs

- [Framework setup](https://surflane.page/docs/frameworks.md): install, CSS imports, theme, Tailwind CSS v4, Server Components, Next.js, React Router, Astro, and Vite
- [Design tokens](https://surflane.page/tokens.md): every token with its dark and light values
- [Full documentation](https://surflane.page/llms-full.txt): every page below in one file

## Foundations

- [Layout](https://surflane.page/foundations/layout.md): Sets containers, grids, spacing, and component sizes.
- [Visual hierarchy](https://surflane.page/foundations/hierarchy.md): Orders planes, elevation, lines, and points from structure to detail.
- [Layers](https://surflane.page/foundations/layers.md): Sets the stacking order of app chrome, dialogs, popups, and tooltips.
- [Color](https://surflane.page/foundations/color.md): Defines color roles, contrast minimums, and how palettes are built.
- [Typography](https://surflane.page/foundations/typography.md): Sets typefaces, type roles, line length, and Korean text rules.
- [Iconography](https://surflane.page/foundations/iconography.md): Sets icon sizes, stroke, direction, and accessible names.
- [Themes](https://surflane.page/foundations/themes.md): Applies light or dark to a page or region, and builds custom themes.
- [Interaction states](https://surflane.page/foundations/interaction.md): Defines how controls show hover, press, focus, selection, and pending work.
- [Motion](https://surflane.page/foundations/motion.md): Sets durations, easing, and reduced motion for every transition.
- [Accessibility](https://surflane.page/foundations/accessibility.md): Sets the WCAG 2.2 AA baseline that every screen meets.
- [Content and localization](https://surflane.page/foundations/content.md): Sets interface wording and the formats of numbers and dates.

## Components

- [Button](https://surflane.page/components/button.md): Runs an action with a clear label.
- [Input](https://surflane.page/components/input.md): Accepts short text and identifiers.
- [Select](https://surflane.page/components/select.md): Picks one option from a fixed list.
- [NativeSelect adapter](https://surflane.page/components/native-select.md): Connects existing HTML option markup to the shared Select.
- [Field](https://surflane.page/components/field.md): Connects a label, help text, error, and value.
- [Fieldset](https://surflane.page/components/fieldset.md): Groups related inputs under a legend.
- [Form](https://surflane.page/components/form.md): Reports validation and submission results.
- [Textarea](https://surflane.page/components/textarea.md): Accepts multi-line descriptions.
- [Checkbox](https://surflane.page/components/checkbox.md): Selects any number of independent options.
- [Checkbox Group](https://surflane.page/components/checkbox-group.md): Connects multiple selections to a select-all checkbox.
- [Radio Group](https://surflane.page/components/radio-group.md): Selects one of several mutually exclusive options.
- [Switch](https://surflane.page/components/switch.md): Toggles a setting that applies immediately.
- [Toggle](https://surflane.page/components/toggle.md): Switches between pressed and unpressed states.
- [Toggle Group](https://surflane.page/components/toggle-group.md): Selects tool modes and display options.
- [Segmented control](https://surflane.page/components/segmented-control.md): Chooses one value from a few, such as a period or a side.
- [Theme switch](https://surflane.page/components/theme-switch.md): Chooses light, dark or the device setting, and remembers it.
- [Combobox](https://surflane.page/components/combobox.md): Searches a list of options and selects one.
- [Autocomplete](https://surflane.page/components/autocomplete.md): Browses suggestions while keeping the typed text.
- [Number Field](https://surflane.page/components/number-field.md): Controls a numeric range with increment and decrement.
- [Slider](https://surflane.page/components/slider.md): Adjusts a value within a range.
- [OTP Field](https://surflane.page/components/otp-field.md): Accepts a one-time code split into separate slots.
- [Date / time picker](https://surflane.page/components/date-picker.md): Accepts dates, times, and ranges in locale-specific formats.
- [Time range picker](https://surflane.page/components/time-range-picker.md): Picks the span back from now a monitoring screen shows and how often it refreshes.
- [File upload](https://surflane.page/components/file-upload.md): Explains file limits and upload status.
- [Popover](https://surflane.page/components/popover.md): Offers secondary tasks next to the trigger.
- [Menu](https://surflane.page/components/menu.md): Collects the actions for the current context.
- [Context Menu](https://surflane.page/components/context-menu.md): Opens actions on right-click or long press, with a visible menu fallback.
- [Tooltip](https://surflane.page/components/tooltip.md): Shows a short supplementary description on focus and hover.
- [Preview Card](https://surflane.page/components/preview-card.md): Previews a link's destination.
- [Dialog](https://surflane.page/components/dialog.md): Opens a standalone task that needs full attention.
- [Alert Dialog](https://surflane.page/components/alert-dialog.md): Asks for an explicit response before an action that can lose data.
- [Sheet](https://surflane.page/components/sheet.md): Opens a detail panel anchored to one side.
- [Drawer](https://surflane.page/components/drawer.md): Opens a task panel that closes with a swipe.
- [Tabs](https://surflane.page/components/tabs.md): Switches between panels in the same context.
- [Accordion](https://surflane.page/components/accordion.md): Expands details linked to their headings.
- [Collapsible](https://surflane.page/components/collapsible.md): Collapses and expands one section's details.
- [Navigation Menu](https://surflane.page/components/navigation-menu.md): Navigates related pages hierarchically.
- [Menubar](https://surflane.page/components/menubar.md): Navigates several action menus in one row.
- [Toolbar](https://surflane.page/components/toolbar.md): Groups related tools for keyboard navigation.
- [Link](https://surflane.page/components/link.md): Navigates to a clear destination.
- [Breadcrumbs](https://surflane.page/components/breadcrumbs.md): Shows the current location and its parent path.
- [Pagination](https://surflane.page/components/pagination.md): Pages through large result sets.
- [Bottom navigation](https://surflane.page/components/bottom-navigation.md): Puts a phone's main destinations along the bottom edge.
- [Avatar](https://surflane.page/components/avatar.md): Shows images for users and groups, with a fallback.
- [Badge / Status](https://surflane.page/components/badge.md): Shows status with color, icon, and text together.
- [Description list](https://surflane.page/components/description-list.md): Shows a resource's properties as terms and their values.
- [Timeline](https://surflane.page/components/timeline.md): Shows events in time order, such as a deploy history or an audit log.
- [Kbd](https://surflane.page/components/kbd.md): Writes a key or shortcut the way this platform does.
- [Card / Surface](https://surflane.page/components/card.md): Groups only related information on a single surface.
- [Table](https://surflane.page/components/table.md): Compares information in aligned rows and columns.
- [Code block](https://surflane.page/components/code.md): Displays long identifiers and code with a copy action.
- [Syntax highlighter](https://surflane.page/components/syntax-highlighter.md): Renders code in each language safely and legibly.
- [Markdown](https://surflane.page/components/markdown.md): Renders documents, code, and tables in a shared reading style.
- [List](https://surflane.page/components/list.md): Keeps repeated content and its actions aligned.
- [Stat](https://surflane.page/components/stat.md): Shows a key figure with its change and what it covers.
- [Tree view](https://surflane.page/components/tree.md): Navigates nested resources with the keyboard.
- [Scroll Area](https://surflane.page/components/scroll-area.md): Adds horizontal and vertical scrolling within a layout.
- [Separator](https://surflane.page/components/separator.md): Draws a full-width or inset boundary.
- [Progress](https://surflane.page/components/progress.md): Shows how much of a task is complete, or that it's running.
- [Meter](https://surflane.page/components/meter.md): Shows a measurement within a known range.
- [Toast](https://surflane.page/components/toast.md): Announces task results without blocking the flow.
- [Data state](https://surflane.page/components/data-state.md): Shows loading, an error with a retry, empty and stale data around any content.
- [Banner](https://surflane.page/components/banner.md): Tells everyone about a state of the whole product, across the app shell.
- [Inline message](https://surflane.page/components/inline-message.md): Explains information, warnings, and errors in the current context.
- [Spinner](https://surflane.page/components/spinner.md): Indicates progress for short tasks.
- [Skeleton](https://surflane.page/components/skeleton.md): Shows the content's structure while it loads.
- [Empty state](https://surflane.page/components/empty-state.md): Explains why there are no results and what to do next.

## Charts

- [Line chart](https://surflane.page/charts/line-chart.md): Draws values over time as lines, with units, a legend, and an alternative table.
- [Area chart](https://surflane.page/charts/area-chart.md): Fills amounts over time from zero, stacked into their total.
- [Bar chart](https://surflane.page/charts/bar-chart.md): Compares amounts per period or category as bars from zero, stacked into their total.
- [Scatter chart](https://surflane.page/charts/scatter-chart.md): Plots two measures per item, with reference lines that split it into quadrants.
- [Sparkline](https://surflane.page/charts/sparkline.md): Draws a small trend line inside a card or a table cell.
- [Bar list](https://surflane.page/charts/bar-list.md): Ranks named values with bars in proportion to the largest.
- [Proportion bar](https://surflane.page/charts/proportion-bar.md): Splits one bar into the parts of a whole, with a legend of their shares.
- [Diverging bar](https://surflane.page/charts/diverging-bar.md): Draws a signed value from a center line, a rise one way and a fall the other.

## Patterns

- [App shell / Sidebar](https://surflane.page/patterns/app-shell.md): Frames content with collapsible navigation, brand and theme on top, account below.
- [Page header](https://surflane.page/patterns/page-header.md): Aligns and spaces the breadcrumb, title, description, and actions.
- [Search / filter bar](https://surflane.page/patterns/filter-bar.md): Connects search, filters, applied state, and reset.
- [Data table](https://surflane.page/patterns/data-table.md): Connects selection, sorting, filters, column settings, and pagination.
- [Resource list](https://surflane.page/patterns/resource-list.md): Connects item padding, hover areas, status, and detail links.
- [Inline confirmation](https://surflane.page/patterns/inline-confirmation.md): Confirms a lightweight action next to the control that triggered it.
- [Form workflow](https://surflane.page/patterns/form-workflow.md): Connects input, validation, server errors, and pending and success states.
- [Async job / Run detail](https://surflane.page/patterns/async-job.md): Connects queued, running, canceled, and partially failed states to build logs.
- [Documentation page](https://surflane.page/patterns/documentation.md): Organizes body text, table of contents, code, callouts, and language switching.
- [Command search](https://surflane.page/patterns/command-search.md): Connects quick navigation, commands, and search results from the keyboard.
- [Error / permission / offline](https://surflane.page/patterns/error-recovery.md): Explains failures, restricted access, lost connections, and recovery paths.
- [Responsive navigation](https://surflane.page/patterns/responsive-navigation.md): Collapses and expands desktop navigation on mobile.
- [Dashboard](https://surflane.page/patterns/dashboard.md): Lays out data panels on a responsive grid with their titles, states and refreshes.

## Optional

- [Token catalog (JSON)](https://surflane.page/design-tokens.json): token names, values per theme, aliases, and source lines
- [Changelog](https://github.com/Ashon/surflane/blob/main/CHANGELOG.md): release notes
- [Source](https://github.com/Ashon/surflane): repository, examples, and tests