@bitsyui/core
One import path for tokens, theme, reset, base defaults, and the Bit styles.
Introduction
Bitsy UI is a framework-free design system: native HTML, tokens, agent-ready, and it works with any stack. One import, no build step, and a few tokens to make it yours.
The shortest credible path
The docs should make adoption obvious before they ask you to inspect architecture details.
- Install
@bitsyui/coreand import it once. - Optionally generate a starter override file with
@bitsyui/cli. - Use the docs controls to verify that appearance and typography can shift without changing structure.
pnpm add @bitsyui/core
pnpm dlx @bitsyui/cli init bitsy.css --dry-run
/* app.css */
@import "@bitsyui/core";Bits
33 Bits, each one native HTML plus a CSS file. Pick one to see its examples and its Guide.
Accordion
Accordion shows and hides headed sections of content, one or many open at a time.
Alert
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.
Avatar
Avatar shows a person or a workspace as a small picture, with their initials as the fallback when there is no image.
Badge
Badge labels an item with a short status or category, such as "Active", "Draft", or "Admin".
Breadcrumb
Breadcrumb shows where the current page sits in the site's hierarchy, as a trail of links back to its parents.
Button
Button is the smallest action Bit in Bitsy.
Card
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.
Checkbox
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.
Dialog
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.
Fieldset
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.
File Upload
File Upload lets people pick one or more files from their device, with an optional drop zone.
Input Group
Input Group adds a prefix, suffix, icon, or button to a single-line field, inside one shared border.
Menu
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.
Number Field
Number Field lets people enter a number, with optional buttons that step it up and down.
Pagination
Pagination lets people move between pages of a long list of results.
Popover
Popover shows rich, non-modal content in a panel anchored to the button that opens it.
Progress
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.
Radio Group
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.
Segmented Control
Segmented Control lets people pick one option from two to five, shown side by side as joined buttons.
Select
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.
Sheet
Sheet runs a side task in a modal panel that slides in from an edge of the screen.
Sidebar
Sidebar gives an app its primary navigation down the side of the screen, in labelled sections and collapsible groups.
Slider
Slider lets people pick a value from a continuous or stepped range by dragging a thumb.
Spinner
Spinner shows that something is loading, inline with text, inside a Button, or over a region.
Stepper
Stepper shows progress through a task with a fixed number of steps, such as checkout or onboarding.
Switch
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.
Table
Table shows rows of data that people compare and scan, such as members, invoices, or deployments, on a native <table>.
Tabs
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.
Text Field
Text Field is the smallest text-entry Bit in Bitsy.
Textarea
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.
Toast
Toast confirms a finished action with a brief message that appears at a screen corner and does not interrupt.
Tooltip
Tooltip names or explains a control in a short label that shows on hover and keyboard focus.
Top Nav
Top Nav gives an app or site a header bar with its brand, its main links, and account actions.
What exists today
Bitsy is still intentionally small. These are the few surfaces that need to stay clear and well-related.
packages/bits
Each Bit keeps its implementation, definition, and Bitsy Guide together in one folder.
@bitsyui/cli
A narrow setup companion that generates a starter stylesheet instead of scaffolding an app.
Docs and Storybook
Docs explain adoption and customization. Storybook remains the validation surface.
How to read the docs
Stay on the shortest route for the job you are actually doing.
For adopters
Start with Setup, then review Tokens, Themes, and Typography.
Browse the Bits to see each contract with live examples.
For contributors
Use Architecture for the workspace split, then continue into README.md, AGENTS.md, and internal/ when the work touches architecture or operating rules.