Fragments UI

A customizable React component library with 56+ accessible, themeable components. Built on Base UI headless primitives.

Features

• 56+ Components — Forms, layout, navigation, feedback, data display, and AI patterns
• Accessible — WAI-ARIA compliant with full keyboard navigation
• Seed-Based Theming — Set 5 seed values, get 120+ derived CSS custom properties
• TypeScript — Full type safety and IntelliSense
• Lightweight — Built on Base UI headless primitives
• AI-Ready — MCP server, component metadata, and AI-specific components

Prerequisites

• React 18+ (including React 19)
• Node.js 18+
• TypeScript 5+ (recommended, not required)

Installation

npm install @fragments-sdk/ui

Quick Start

Import the stylesheet once in your app's entry point, then wrap with providers:

import '@fragments-sdk/ui/styles';
import {
  ThemeProvider,
  TooltipProvider,
  ToastProvider,
} from '@fragments-sdk/ui';

function App({ children }) {
  return (
    <ThemeProvider defaultMode="system">
      <TooltipProvider>
        <ToastProvider>
          {children}
        </ToastProvider>
      </TooltipProvider>
    </ThemeProvider>
  );
}

Components use a compound API pattern — sub-components are accessed via dot notation:

import { Button, Card, Input, Stack } from '@fragments-sdk/ui';

function MyComponent() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Welcome</Card.Title>
      </Card.Header>
      <Card.Body>
        <Stack gap="sm">
          <Input placeholder="Enter your name" />
          <Button>Submit</Button>
        </Stack>
      </Card.Body>
    </Card>
  );
}

Components

Layout

AppShell · Box · Grid · Header · Sidebar · Stack · Separator

Forms

Button · ButtonGroup · Checkbox · Combobox · ColorPicker · Field · Fieldset · Form · Input · Listbox · RadioGroup · Select · Slider · Textarea · Toggle · ToggleGroup

Data Display

Accordion · Avatar · Badge · Card · Chart · CodeBlock · Icon · Image · List · Table · Tabs · Text · Tooltip

Feedback

Alert · Dialog · EmptyState · Loading · Menu · Popover · Progress · Prompt · Skeleton · Toast

AI

ConversationList · Message · ThinkingIndicator

View all components →

Theming

Fragments uses a seed-based theme system. Set 4 seed values and the library derives nearly 200 CSS custom properties automatically: color palettes, spacing, typography, shadows, and more.

Configure seeds in your global stylesheet:

// styles/globals.scss
@use '@fragments-sdk/ui/styles' with (
  $fui-brand: #6366f1,
  $fui-neutral: "ice",
  $fui-density: "default",
  $fui-radius-style: "rounded"
);

Use the built-in toggle or control dark/light mode programmatically:

import { ThemeToggle, useTheme } from '@fragments-sdk/ui';

// Built-in toggle component
<ThemeToggle />

// Or control programmatically
const { mode, setMode } = useTheme();

Customize your brand with the Theme Builder.

CLI

The Fragments CLI compiles component metadata into fragments.json — a structured file that powers the MCP server, dev viewer, and AI tooling.

npm install -D @fragments-sdk/cli

fragments init        # Create fragments.config.ts and scaffold .contract.json files
fragments build       # Compile .contract.json files into fragments.json
fragments verify --ci # Run compliance checks in CI

See the CLI Reference for all commands.

MCP Integration

The Model Context Protocol lets AI assistants query your design system in real time — components, props, tokens, blocks, and accessibility rules.

Add the MCP server to your AI tool's config:

{
  "mcpServers": {
    "fragments": {
      "command": "npx",
      "args": ["-y", "@fragments-sdk/mcp@latest"]
    }
  }
}

Tool	Config file
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
VS Code	.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

See the MCP Tools Reference for available tools.

Documentation

Visit usefragments.com for:

• Getting Started
• Component Docs
• Blocks
• Theme Builder
• CLI Reference
• MCP Tools
• Accessibility
• AI Playground

License

• @fragments-sdk/ui — MIT (free for any use)
• @fragments-sdk/cli, @fragments-sdk/mcp, @fragments-sdk/context — FSL-1.1-MIT (free for non-competing use, converts to MIT after 2 years per release)

© Conan McNicholl