freeCodeCamp UIKit

Design system, React component library, and vanilla-JS adapter that power the freeCodeCamp.org platform. Built CSS-first with design tokens and accessibility-tested against the WAI-ARIA Authoring Practices.

UIKit is distributed as a copy-source registry (shadcn-style): components are copied from design.freecodecamp.org into your project's source and tailored there - nothing installs from npm, nothing is packaged. It is built to be equally usable by humans and LLM coding agents: point an agent at design.freecodecamp.org/llms.txt and it can discover, copy, and adapt any component.

Packages

All workspaces are private - they are the source of truth the registry serves, not npm packages.

Workspace	Description
packages/uikit	React component library - 47 components across 8 tiers
packages/uikit-css	Design tokens, base helpers, fonts, brand assets
packages/uikit-js	Vanilla JS runtime - wires data-uikit-* attrs to Zag state machines
packages/uikit-icons	Curated Lucide icon subset, React + sprite
packages/uikit-tailwind	Tailwind preset + plugin mirroring UIKit tokens

Quick start

React - copy the source

1. Install the theme once: copy tokens.css + base.css from /registry/theme.md and import them globally (fonts: see the starter guide).
2. Copy a component from its page - e.g. /components/button.md - into src/ui/<slug>/, and import its CSS once.
3. It is your code now: tailor it freely, recolour by editing token values.

For agents: /llms.txt (index) · /registry/index.json (machine-readable manifest) · /registry/starter.md (bootstrap + AGENTS.md snippet).

import './ui/theme/tokens.css';
import { Button } from './ui/button/Button';
import { Badge } from './ui/badge/Badge';

export default function Example() {
  return (
    <>
      <Button variant='cta'>Start curriculum</Button>
      <Badge tone='success'>Passed</Badge>
    </>
  );
}

Documentation

The docs site (apps/docs) is the canonical reference: live component showcases, real React previews, the design handbook, and brand guide.

pnpm install
pnpm dev:docs

Then open http://localhost:4321.

The site ships at https://design.freecodecamp.org via Cloudflare Pages.

For the full component-by-component reference and how UIKit compares to Catalyst / Ark UI / Headless UI, see docs/components-matrix.md.

Deployment

• Docs site → Cloudflare Pages with Git integration (design.freecodecamp.org, project fcc-design). Pushes to main deploy production. Build output: apps/docs/dist/. See docs/runbooks/deploy-docs.md.
• Registry → the docs site is the registry: component markdown pages and raw source endpoints are generated at docs build time and ship with every docs deploy.

Reporting bugs

Open an issue at https://github.com/freeCodeCamp/UIkit/issues. Include reproduction steps, expected behaviour, and observed behaviour. For visual regressions, attach the Playwright diff PNG from apps/docs/test-results/.

Reporting security issues

Do not open a public issue - follow the disclosure process in SECURITY.md.

Contributing

The freeCodeCamp.org community is possible thanks to thousands of kind volunteers. Read the contributor guide at https://contribute.freecodecamp.org/, then CONTRIBUTING.md for the UIKit-specific workflow.

All contributors are expected to follow the Code of Conduct.

License

Copyright © 2026 freeCodeCamp.org

The content of this repository is bound by the following licenses:

• The computer software is licensed under the BSD-3-Clause license.
• The documentation is licensed under CC BY-NC-SA 4.0.