# Bitsy UI

> A framework-free design system: native HTML, design tokens, and small Bits that work in any stack. No React, Tailwind, or build step is required. Bits style native elements through `data-bitsy-*` hooks and read only semantic tokens.

## Quick start

Fastest, no build step: link one file. `@bitsyui/core/flat/bitsy.css` is the whole foundation plus every Bit, with no `@import`.

```html
<link rel="stylesheet" href="node_modules/@bitsyui/core/flat/bitsy.css">
```

Load less: link `flat/core.css` (foundation only), then `flat/bits/<bit>.css` for each Bit the page uses. Each flat file declares the layer order itself, so link order does not matter.

Own the files: `npx @bitsyui/cli add <bit>` copies a Bit's flat CSS (and its init script, if it has one) into `bitsy/bits/<bit>/`. Pass `--dir` to change the folder, `--list` to see every Bit, or `--all`. Link the copied CSS after `flat/core.css` (or a `bitsy init` stylesheet), and call `init()` once for Bits that ship a script.

Tune tokens: `npx @bitsyui/cli init bitsy.css` writes a starter stylesheet that imports `@bitsyui/core` and sets type, radius, elevation, and theme choices.

## Rules for agents

- Prefer native elements (`<button>`, `<dialog>`, `<input>`) with the Bit's `data-bitsy-*` hooks. Read the Bit's Guide before writing markup.
- Style with semantic tokens (`--bitsy-color-*`, `--bitsy-space-*`, `--bitsy-radius-*`). Do not use utility classes or hard-coded values.
- Do not add JavaScript where a native feature works. Only Bits listed with a Script line need `init()`.
- Do not rename `data-bitsy-*` hooks or token names.

## Bits

- [Alert](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/alert/bitsy-guide.md): Alert shows a message about the page or the task at hand, such as a saved change, a warning before an action, or an error that blocks progress, with an optional title, actions, and a status tone.
  - Install: `npx @bitsyui/cli add alert` or link `@bitsyui/core/flat/bits/alert.css`
  - Root hook: `data-bitsy-alert`
- [Avatar](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/avatar/bitsy-guide.md): Avatar shows a person or a workspace as a small picture, with their initials as the fallback when there is no image.
  - Install: `npx @bitsyui/cli add avatar` or link `@bitsyui/core/flat/bits/avatar.css`
  - Root hook: `data-bitsy-avatar`
- [Badge](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/badge/bitsy-guide.md): Badge labels an item with a short status or category, such as "Active", "Draft", or "Admin".
  - Install: `npx @bitsyui/cli add badge` or link `@bitsyui/core/flat/bits/badge.css`
  - Root hook: `data-bitsy-badge`
- [Button](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/button/bitsy-guide.md): Button is the smallest action Bit in Bitsy.
  - Install: `npx @bitsyui/cli add button` or link `@bitsyui/core/flat/bits/button.css`
  - Root hook: `data-bitsy-button`
- [Card](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/card/bitsy-guide.md): Card groups one self-contained piece of content into a bounded surface with an optional header, a body, and an optional footer of actions, so it reads as one unit among others.
  - Install: `npx @bitsyui/cli add card` or link `@bitsyui/core/flat/bits/card.css`
  - Root hook: `data-bitsy-card`
- [Checkbox](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/checkbox/bitsy-guide.md): Checkbox lets a person turn one independent option on or off, such as agreeing to terms, or choose any number of options from a list.
  - Install: `npx @bitsyui/cli add checkbox` or link `@bitsyui/core/flat/bits/checkbox.css`
  - Root hook: `data-bitsy-checkbox`
- [Dialog](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/dialog/bitsy-guide.md): Dialog interrupts the page with one focused task or confirmation in a modal window, keeps focus and screen-reader context inside it until it closes, and returns focus to where the person was.
  - Install: `npx @bitsyui/cli add dialog` or link `@bitsyui/core/flat/bits/dialog.css`
  - Root hook: `data-bitsy-dialog`
- [Fieldset](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/fieldset/bitsy-guide.md): Fieldset groups related fields under one name, such as "Shipping address" or "Notification channels", with optional group help text and a group-level error, so the group is understood as one unit.
  - Install: `npx @bitsyui/cli add fieldset` or link `@bitsyui/core/flat/bits/fieldset.css`
  - Root hook: `data-bitsy-fieldset`
- [Menu](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/menu/bitsy-guide.md): Menu opens a short list of actions from a button, anchored to it, so a screen can offer secondary actions such as "Duplicate", "Export", and "Delete" without showing a button for each.
  - Install: `npx @bitsyui/cli add menu` or link `@bitsyui/core/flat/bits/menu.css`
  - Root hook: `data-bitsy-menu`
  - Script: `import { init } from "@bitsyui/bits/menu/init"; init();`
- [Progress](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/progress/bitsy-guide.md): Progress shows how far a task has got, such as an upload or a setup checklist, or that a task is still working when its length is unknown.
  - Install: `npx @bitsyui/cli add progress` or link `@bitsyui/core/flat/bits/progress.css`
  - Root hook: `data-bitsy-progress`
- [Radio Group](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/radio-group/bitsy-guide.md): Radio Group lets a person pick exactly one option from a small set of options that are all visible at once, such as a plan, a delivery speed, or a notification frequency.
  - Install: `npx @bitsyui/cli add radio-group` or link `@bitsyui/core/flat/bits/radio-group.css`
  - Root hook: `data-bitsy-radio-group`
- [Select](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/select/bitsy-guide.md): Select lets a person pick one option from a list that is too long to show as radios, in a compact control that matches Text Field in size and style, such as a country, a time zone, or a role.
  - Install: `npx @bitsyui/cli add select` or link `@bitsyui/core/flat/bits/select.css`
  - Root hook: `data-bitsy-select`
- [Switch](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/switch/bitsy-guide.md): Switch turns one setting on or off and the change takes effect right away, such as enabling notifications or dark mode in a settings list.
  - Install: `npx @bitsyui/cli add switch` or link `@bitsyui/core/flat/bits/switch.css`
  - Root hook: `data-bitsy-switch`
- [Table](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/table/bitsy-guide.md): Table shows rows of data that people compare and scan, such as members, invoices, or deployments, on a native <table>.
  - Install: `npx @bitsyui/cli add table` or link `@bitsyui/core/flat/bits/table.css`
  - Root hook: `data-bitsy-table-scroll`
- [Tabs](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/tabs/bitsy-guide.md): Tabs shows one of several related panels in the same space, with a row of tabs that names each panel and shows which one is active, so people can switch views without leaving the page.
  - Install: `npx @bitsyui/cli add tabs` or link `@bitsyui/core/flat/bits/tabs.css`
  - Root hook: `data-bitsy-tabs`
  - Script: `import { init } from "@bitsyui/bits/tabs/init"; init();`
- [Text Field](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/text-field/bitsy-guide.md): Text Field is the smallest text-entry Bit in Bitsy.
  - Install: `npx @bitsyui/cli add text-field` or link `@bitsyui/core/flat/bits/text-field.css`
  - Root hook: `data-bitsy-text-field`
- [Textarea](https://github.com/bitsyui/bitsyui/blob/main/packages/bits/textarea/bitsy-guide.md): Textarea collects one multi-line text value, such as a message, a description, or notes, with a clear label, optional supporting text, and explicit disabled, readonly, or invalid states.
  - Install: `npx @bitsyui/cli add textarea` or link `@bitsyui/core/flat/bits/textarea.css`
  - Root hook: `data-bitsy-textarea`