Getting Started

Install and set up Fragments UI, an accessible React component library for Next.js and Vite.

Fragments UI is an accessible React component library with design tokens, seed-based theming, and MCP tooling for AI-assisted workflows. Use this setup guide to install the package, configure styles, and start building with components, including 66 documented components, then continue with the Theme Builder and MCP docs.

Prerequisites

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

Install

Install the Fragments UI React component library with your preferred package manager:

npm install @fragments-sdk/ui

Setup Styles

Fragments UI uses CSS custom properties for theming. Import the stylesheet once in your application's entry point. This includes a minimal CSS reset, design tokens, and component styles. No additional font import is required.

import '@fragments-sdk/ui/styles';

Provider Setup

Wrap your app with providers at the application root. ThemeProvider enables theming and dark mode, while TooltipProvider and ToastProvider enable those component features:

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>
  );
}

Note

If using AppShell with a collapsible sidebar, wrap your layout with SidebarProvider as well.

Framework Setup

Vite

Fragments works with Vite out of the box. Import the styles in your entry file and wrap with providers:

import React from 'react';
import ReactDOM from 'react-dom/client';
import '@fragments-sdk/ui/styles';
import { ThemeProvider, ToastProvider } from '@fragments-sdk/ui';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultMode="system">
      <ToastProvider>
        <App />
      </ToastProvider>
    </ThemeProvider>
  </React.StrictMode>
);

Next.js

For Next.js App Router, first add transpilePackages to your Next.js config so the UI package styles load correctly:

const nextConfig = {
  transpilePackages: ['@fragments-sdk/ui'],
};

export default nextConfig;

Then import styles in your root layout and add suppressHydrationWarning to the html element to avoid theme hydration warnings:

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider defaultMode="system">
          <TooltipProvider>
            <ToastProvider>
              {children}
            </ToastProvider>
          </TooltipProvider>
        </ThemeProvider>
      </body>
    </html>
  );
}

Components that use client-side features (dialogs, tooltips, toasts) need the 'use client' directive in the file that renders them. Provider components are already marked as client components. This means pages using these components cannot export Next.js metadata directly — use a separate layout.tsx for metadata instead.

Basic Usage

Import and use components directly. Components use a compound API pattern; sub-components are accessed via dot notation (e.g. Card.Header, Card.Body):

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>
  );
}

Theming

Fragments uses a seed-based theme system for design tokens. Configure a small set of theme seeds (brand, neutral palette, density, radius, plus optional semantic colors), and the library derives 108 CSS custom properties used by components.

Use the ThemeToggle component for a built-in light/dark mode switch, or control the theme programmatically with useTheme:

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

// Built-in toggle component
<ThemeToggle />

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

  return (
    <select value={mode} onChange={(e) => setMode(e.target.value as 'light' | 'dark' | 'system')}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="system">System</option>
    </select>
  );
}

To customize your brand colors, spacing density, and border radius at build time, use the SCSS @use ... with() syntax in your global stylesheet:

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

Start with the 4 core seeds shown above, then add optional semantic color seeds if needed. Try the Theme Builder to preview and export your configuration.

SCSS seeds vs configureTheme()

SCSS seeds (above) set tokens at build time — use this for your base theme. configureTheme() sets tokens at runtime via JS — use this for dynamic themes or when you don't have SCSS. Both set the same CSS custom properties. If using both, SCSS seeds provide defaults and configureTheme() overrides at runtime.

AI Tooling (MCP)

Fragments ships a pre-built component manifest (fragments.json) inside the npm package. When you add the MCP server, AI assistants (Claude, Cursor, VS Code Copilot) can read your installed Fragments component metadata — props, variants, usage guidelines, and composition patterns.

Install the MCP server as a dev dependency:

npm install -D @fragments-sdk/mcp

Then add to your editor's MCP configuration:

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

The MCP server automatically discovers fragments.json from your node_modules — no build step needed. AI assistants can then use 12 Fragments MCP tools, including fragments_discover, fragments_inspect, and fragments_implement to generate component code that matches the library.

Next Steps

Browse Components: Explore 66 component docs, props, and live previews
Theme Builder: Configure theme seeds and preview design tokens
Blocks: Browse 30 pre-built composition patterns (login forms, dashboards, settings pages)
CLI Reference: Build, validate, and manage your design system
MCP Tools: Give AI assistants deep understanding of your components
Accessibility: WCAG 2.2 checks and keyboard navigation