# freeCodeCamp UIKit

Dark-first, token-driven, framework-agnostic component library,
distributed as a copy-source registry: components are copied into your
project source (shadcn-style) and tailored there - NOT installed from npm.

## Start here

- [Starter guide](https://design.freecodecamp.org/registry/starter.md) - bootstrap a project: theme, fonts, directory layout, AGENTS.md snippet.
- [Theme](https://design.freecodecamp.org/registry/theme.md) - tokens.css + base.css. Required by every component. Edit token values to recolour; keep token names.
- [Machine index](https://design.freecodecamp.org/registry/index.json) - every item, its files (raw URLs) and dependencies, as JSON.

## Components

Each page contains install steps, props and the full source (.tsx + .css) to copy.

- [Alert](https://design.freecodecamp.org/components/alert.md) - An in-page live region that surfaces info, success, warning, or danger messages with the correct ARIA role out of the box.
- [AuthLayout](https://design.freecodecamp.org/components/auth-layout.md) - Centered card shell for auth flows - login, signup, forgot-password, magic-link. Optional brand lockup above the card, optional footer below, optional background pattern for a little texture.
- [Avatar](https://design.freecodecamp.org/components/avatar.md) - Square user badge. Image by default, two-letter initials fallback, optional status dot. Three sizes locked to the type scale.
- [Badge](https://design.freecodecamp.org/components/badge.md) - A compact coloured tag for statuses, counts, and metadata. Polymorphic via `variant`, semantic-free by default.
- [Breadcrumb](https://design.freecodecamp.org/components/breadcrumb.md) - Hierarchical trail of links with the current page marked via aria-current. Compound API plus a CSS pseudo-element separator so the visible slash never reaches the accessibility tree.
- [Button](https://design.freecodecamp.org/components/button.md) - The primary action primitive. Gold CTA by default, three sizes, six variants, polymorphic via a single `variant` prop.
- [Callout](https://design.freecodecamp.org/components/callout.md) - A flagged prose block for tips, notes, warnings, and cautions - the Markdown admonition we reach for inside long-form docs.
- [Card](https://design.freecodecamp.org/components/card.md) - A compound surface with optional header, body, and footer slots. Reach for Card when a block of content needs its own visual frame.
- [Checkbox](https://design.freecodecamp.org/components/checkbox.md) - A native checkbox with an optional paired label. Owns the `type='checkbox'` attribute so consumers never have to set it.
- [Close button](https://design.freecodecamp.org/components/close-button.md) - The small × affordance for dismissing panels, toasts, and modals. Defaults to `aria-label='Close'` so every dismiss target stays labelled.
- [Combobox](https://design.freecodecamp.org/components/combobox.md) - Text input paired with a filterable option list - the marquee Wave 2 component. Sync filter, custom item renderers, and a data-uikit-combobox adapter that boots the vanilla runtime for server-rendered pages.
- [CommandPalette](https://design.freecodecamp.org/components/command-palette.md) - Keyboard-driven launcher. Search input + grouped filterable list + shortcut badges. Arrow keys navigate, Enter selects, Escape closes.
- [DataTable](https://design.freecodecamp.org/components/data-table.md) - Structured tabular display with sortable columns, row selection, loading skeletons, and an empty-state slot. Caller owns sort and selection state; columns accept string-key or function accessors.
- [DescriptionList](https://design.freecodecamp.org/components/description-list.md) - Semantic dl/dt/dd pair with mono terminal terms and Lato body details. Two layouts - vertical grid for metadata panels, inline for compact key/value strips.
- [Divider](https://design.freecodecamp.org/components/divider.md) - Horizontal or vertical rule. Solid by default, dashed for the terminal-native version. Renders `<hr role="separator">`.
- [Dropdown](https://design.freecodecamp.org/components/dropdown.md) - A menu button pattern with keyboard navigation and outside-click dismiss. Pair `<Dropdown.Toggle>` with `<Dropdown.Menu>` / `<Dropdown.Item>`.
- [EmptyState](https://design.freecodecamp.org/components/empty-state.md) - Centered placeholder for empty lists, empty search results, and zero-state dashboards. Optional icon, title, description, and action slots.
- [Fieldset](https://design.freecodecamp.org/components/fieldset.md) - Semantic field grouping with legend. Native fieldset + legend styled to the terminal shell - the right container for any cluster of related form controls.
- [Form control](https://design.freecodecamp.org/components/form-control.md) - A label-plus-control compound that threads `id` / `htmlFor` / `aria-describedby` across its slots. Wraps Input, Textarea, or a custom field.
- [Form group](https://design.freecodecamp.org/components/form-group.md) - A vertical cluster for a single control plus its label, help, and error text. Pairs with `<FormControl>` and `<HelpBlock>`.
- [FormStepper](https://design.freecodecamp.org/components/form-stepper.md) - Numbered multi-step wizard. Progress header + render-prop body. Caller owns the current step; completed steps are backward-navigable, upcoming steps are gated.
- [Heading](https://design.freecodecamp.org/components/heading.md) - Section and page headings. Level and visual size decoupled so you can honour document outline without sacrificing composition.
- [Help block](https://design.freecodecamp.org/components/help-block.md) - The help / success / error microcopy line that sits beneath a form control. Three tones, one primitive.
- [Hotspots](https://design.freecodecamp.org/components/hotspots.md) - Clickable regions overlaid on a background image, diagram, or SVG. Quiz mode compares the pick to a target and surfaces feedback plus a hint after repeated misses.
- [Image](https://design.freecodecamp.org/components/image.md) - A responsive `<img>` primitive with a required `alt` contract. Pair with a `<figure>` + `<figcaption>` compound when the image needs a caption.
- [Input](https://design.freecodecamp.org/components/input.md) - The baseline single-line text control. Forwards every native input prop, adds an `invalid` flag that syncs `aria-invalid`.
- [Link](https://design.freecodecamp.org/components/link.md) - The styled anchor primitive. Wraps `<a>` with the UIKit hover/focus ring and a `block` flag for full-width link rows.
- [Listbox](https://design.freecodecamp.org/components/listbox.md) - Scrollable single- or multi-select list. Ships a React layer for controlled state and a data-uikit-listbox adapter with full keyboard navigation and type-ahead for the vanilla runtime.
- [Modal](https://design.freecodecamp.org/components/modal.md) - An accessible dialog with backdrop, focus trap, and escape-to-close. Controlled component - you own the `open` state.
- [Navbar](https://design.freecodecamp.org/components/navbar.md) - Top-of-page chrome with start, center, and end slots. Responsive collapse at the md breakpoint (768 px) so the center band wraps below the start and end rows on narrow screens.
- [Pagination](https://design.freecodecamp.org/components/pagination.md) - Page navigator for tabular and paged content. Ships a React layer for app code and a data-uikit-pagination adapter for the vanilla runtime - both speak the same DOM contract so the layers stay swappable.
- [Panel](https://design.freecodecamp.org/components/panel.md) - A lightweight surface for grouping related controls or metadata - the same BEM surface Card uses, but without header/footer ceremony.
- [Radio](https://design.freecodecamp.org/components/radio.md) - Native radio input with label wrapper and RadioGroup context for single-choice selection. Pairs with Fieldset for semantic grouping.
- [Select](https://design.freecodecamp.org/components/select.md) - Native HTML select restyled to fit the terminal shell. A real <select> - no portal, no popover, no Combobox. Chevron is an inlined Lucide glyph.
- [Sidebar](https://design.freecodecamp.org/components/sidebar.md) - Vertical navigation rail with section eyebrows, icon + label items, and active-state highlighting. Compound component - Sidebar + SidebarSection + SidebarItem.
- [SidebarLayout](https://design.freecodecamp.org/components/sidebar-layout.md) - Page-scale chrome - optional header row on top of a sidebar + main grid. The aside column collapses at the md breakpoint (≤ 768 px) so mobile screens stay single-column.
- [Skeleton](https://design.freecodecamp.org/components/skeleton.md) - Loading placeholder with shimmer. Rect by default, circle for avatars, text for stacked line bars. Renders `<div role="status" aria-busy="true">`.
- [Spacer](https://design.freecodecamp.org/components/spacer.md) - Explicit whitespace as a component. Step 0–8 maps onto the token scale, any other number is treated as raw pixels.
- [StackedLayout](https://design.freecodecamp.org/components/stacked-layout.md) - Page-scale chrome for top-nav pages - optional header, flex-grow main, optional footer. Use for marketing pages, articles, and any view that doesn't need a persistent side rail.
- [Switch](https://design.freecodecamp.org/components/switch.md) - A toggle for binary settings that take effect immediately. Behaves like a checkbox under the hood, styled as a pill.
- [Table](https://design.freecodecamp.org/components/table.md) - The semantic table primitive. Pair with `<DataTable>` when sortable columns + zebra striping are needed; reach for raw `<Table>` for simple tabular data.
- [Tabs](https://design.freecodecamp.org/components/tabs.md) - A keyboard-accessible tab panel with `<Tab eventKey>` children and an optional controlled `activeKey`. Arrow keys move focus; Enter activates.
- [Text](https://design.freecodecamp.org/components/text.md) - Body-copy primitive. Polymorphic element, token-driven size scale, Lato by default, terminal semantics for tone.
- [Textarea](https://design.freecodecamp.org/components/textarea.md) - Native textarea with terminal styling, an opt-in monospace variant, and an auto-resize mode that grows the control with its content.
- [Tile matcher](https://design.freecodecamp.org/components/tile-matcher.md) - Data-driven memory / matching game for interactive curricula. Builds a deck from pairs, flips tiles to reveal, and fires callbacks on match and completion.
- [Toast](https://design.freecodecamp.org/components/toast.md) - Transient notifications. `info`, `success`, `warning`, and `danger` variants. Shares a single <Toaster /> provider per app and fires via `toaster.create(...)`.
- [Toggle button](https://design.freecodecamp.org/components/toggle-button.md) - A button that remembers its pressed state. Reach for it when the same control must flip between "on" and "off" without leaving the row.
- [Tooltip](https://design.freecodecamp.org/components/tooltip.md) - A keyboard-friendly hint that surfaces on hover or focus. Renders as a CSS-only bubble - no portal, no JS, no third-party runtime.

## Other registry items

- [Theme](https://design.freecodecamp.org/registry/theme.md) - Design tokens (colors, type, spacing, motion) + shared base helpers. Every component depends on this. Dark by default; add .light-palette to opt into light mode.
- [Icons](https://design.freecodecamp.org/registry/icons.md) - Curated Lucide subset: Icon React component + icon map. Copy Icon.tsx and a subset of icons.ts, or grab raw SVGs per icon.
- [Vanilla JS runtime](https://design.freecodecamp.org/registry/vanilla.md) - Framework-free behaviours bound via data-uikit-* attributes (dialog, combobox, listbox, pagination, toast), powered by Zag state machines. Alternative to the React components for plain HTML.
- [Tailwind preset](https://design.freecodecamp.org/registry/tailwind.md) - Optional Tailwind (>=4) preset + plugin mirroring the UIKit tokens as utilities. Components do not require Tailwind.
- [Progress (HTML-only)](https://design.freecodecamp.org/registry/html-progress.md) - BEM progress bar pattern with no React counterpart. Copy the CSS and use the .progress / .progress__bar classes directly.
- [useAsyncComboboxItems](https://design.freecodecamp.org/registry/use-async-combobox-items.md) - Debounced + cancellable async item loading for the Combobox component.
- [HotspotShapes](https://design.freecodecamp.org/registry/hotspot-shapes.md) - Shape helpers (rect, circle, polygon) for the Hotspots game component.

## Human surfaces

- [Landing](https://design.freecodecamp.org/) - overview + quickstart.
- [Playground](https://design.freecodecamp.org/playground) - every component, paired code.
- [Handbook](https://design.freecodecamp.org/handbook) - design philosophy, tokens, brand, install, CDN, Tailwind, recipes, contributing.

## Concatenated dump

- [llms-full.txt](https://design.freecodecamp.org/llms-full.txt) - every component page incl. full source, single file.