@fragments-sdk/ui

A component library built on Base UI headless primitives with design tokens, SCSS modules, and full AI agent support. Project home: usefragments.com.

About this repository

This GitHub repository is a read-only mirror of @fragments-sdk/ui. The canonical source lives in a private monorepo and is mirrored here on every push to main.

• Install from npm: pnpm add @fragments-sdk/ui (or npm install @fragments-sdk/ui)
• Docs: usefragments.com
• Issues: file them in this repo — they're triaged by maintainers.
• Contributions: pull requests are not merged from this mirror. Describe proposed changes in an issue; maintainers land them in the canonical repo and the mirror re-syncs automatically.

Install

pnpm add @fragments-sdk/ui
# or: npm install @fragments-sdk/ui

Peer dependencies:

npm install react react-dom

Setup

Quick start (no SCSS) — import the prebuilt CSS in your app entry point. This loads component styles with default tokens:

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

Custom theming (SCSS) — create a .scss file with @use '@fragments-sdk/ui/styles' with (...) to set your seed values, then import both:

import "@fragments-sdk/ui/styles"; // component styles (ui.css)
import "./styles/globals.scss"; // your seed overrides

Next.js users — add transpilePackages to your next.config.js:

// next.config.js
const nextConfig = {
  transpilePackages: ["@fragments-sdk/ui"],
};

Then use components:

import { Button, Card, Input, Grid } from "@fragments-sdk/ui";

function App() {
  return (
    <Card>
      <Grid columns={2} gap="md">
        <Input label="Email" type="email" />
        <Input label="Name" />
      </Grid>
      <Button variant="primary">Submit</Button>
    </Card>
  );
}

Components

| Component | Category | Description | | ----------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accordion | Layout | Vertically stacked, collapsible content sections. Use for organizing related content that can be progressively disclosed. | | Alert | Feedback | Contextual feedback messages for user actions or system status. Supports multiple severity levels with optional actions and dismissibility. | | AppShell | Layout | Full layout wrapper integrating sidebar, header, main content, and optional aside panel. Supports three layout modes: default (header on top), sidebar (sidebar full height), and sidebar-floating (rounded main content). | | Avatar | Display | Visual representation of a user or entity | | Badge | Display | Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout. | | Box | Layout | Primitive layout component for applying spacing, backgrounds, and borders. A flexible container for building custom layouts. | | Breadcrumbs | Navigation | Breadcrumb navigation showing the current page location within a hierarchy. Helps users navigate back through parent pages. | | Button | Forms | Interactive element for user actions and form submissions | | ButtonGroup | Forms | Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets. | | Card | Layout | Container for grouping related content | | Chart | Display | Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration. | | Checkbox | Forms | Binary toggle for form fields. Use for options that require explicit submission, unlike Switch which takes effect immediately. | | Chip | Forms | Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group. | | CodeBlock | Display | Syntax-highlighted code display with copy functionality, theming, diff view, and collapsible sections | | Collapsible | Layout | An interactive component that expands/collapses to show or hide content | | ColorPicker | Forms | Color selection control with hex input and visual picker. Displays a swatch that opens a full color picker on click. | | Combobox | Forms | Searchable select input that filters a dropdown list of options as you type. Supports single and multiple selection with chips. | | ConversationList | Ai | Scrollable message container with auto-scroll and history loading | | Dialog | Feedback | Modal overlay for focused user interactions. Use for confirmations, forms, or content requiring full attention. | | EmptyState | Feedback | Placeholder for empty content areas. Provides context, guidance, and actions when no data is available. | | Field | Forms | Compositional form field wrapper providing validation, labels, descriptions, and error messages. Use for advanced form needs beyond baked-in Input/Textarea props. | | Fieldset | Forms | Groups related form fields with an accessible legend. Use to organize forms into logical sections. | | Form | Forms | Form wrapper that handles server-side error distribution to Field components. Pairs with Field for complete form validation. | | Grid | Layout | Responsive grid layout for arranging items in columns with consistent spacing | | Header | Navigation | Composable header with slots for brand, navigation, search, and actions. Supports dropdown nav groups via Header.NavMenu. Designed for use within AppShell with responsive mobile support. | | Icon | Display | Wrapper for Phosphor icons with consistent sizing and semantic colors. Provides standardized icon rendering across the design system. | | Image | Display | Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling. | | Input | Forms | Text input field for single-line user data entry | | Link | Navigation | Styled anchor element for navigation. Supports internal and external links with consistent visual treatment. | | List | Display | Compound component for rendering ordered or unordered lists with consistent styling. Supports bullet, numbered, and icon-prefixed items. | | Listbox | Forms | Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger. | | Loading | Feedback | Versatile loading indicator with multiple variants for showing progress or waiting states | | Markdown | Display | Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more. | | Menu | Feedback | Dropdown menu for actions and commands. Use for contextual actions, overflow menus, or grouped commands. | | Message | Ai | Individual chat message display with role-based styling | | Popover | Feedback | Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context. | | Progress | Feedback | Visual indicator of task completion or loading state. Available in linear and circular variants. | | Prompt | Ai | Multi-line input with toolbar for AI/chat interfaces | | RadioGroup | Forms | Single selection from a list of mutually exclusive options | | ScrollArea | Layout | A styled scrollable container with thin scrollbars and optional fade indicators. | | Select | Forms | Dropdown for choosing from a list of options. Use when there are more than 4-5 choices that would clutter the UI. | | Separator | Layout | Visual divider between content sections. Use to create clear visual boundaries and improve content organization. | | Sidebar | Navigation | Responsive navigation sidebar with collapsible desktop mode and mobile drawer behavior. | | Skeleton | Feedback | Placeholder loading state for content | | Slider | Forms | Range input control for selecting a numeric value within a defined range. Supports labels, value display, and custom step intervals. | | Stack | Layout | Flexible layout component for arranging children in rows or columns with consistent spacing. Supports responsive direction and gap. | | Table | Display | Data table with sorting and row selection. Use for displaying structured data that needs to be scanned, compared, or acted upon. | | Tabs | Navigation | Organize content into switchable panels. Use for related content that benefits from a compact, navigable layout. | | Text | Display | Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements. | | Textarea | Forms | Multi-line text input for longer form content | | Theme | Navigation | Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence. | | ThinkingIndicator | Ai | Animated indicator showing AI is processing | | Toast | Feedback | Brief, non-blocking notification messages | | Switch | Forms | Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly. | | ToggleGroup | Forms | A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options. | | Tooltip | Feedback | Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context. | | VisuallyHidden | Navigation | Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text. |

Fragment Snippet Authoring

All fragment and block previews are authored source snippets, not runtime-serialized JSX.

• Add explicit variant.code (or block code) for every example.
• Keep snippets as full examples: include imports + renderable JSX.
• Use Fragments primitives for layout wrappers (Box, Stack, Text) instead of raw HTML wrappers (div, span, p, headings).
• Do not use inline style={...} in snippets or example renders.
• Do not use alias drift tags (*Root, *2) in snippet code.

Design Tokens

Seed-Based Configuration (Recommended)

Configure ~5 seeds and everything derives automatically using the SCSS @use ... with() syntax:

// styles/globals.scss

// Minimal setup — just your brand color
@use "@fragments-sdk/ui/styles" with (
  $fui-brand: #0066ff
);

// Full customization
@use "@fragments-sdk/ui/styles" with (
  $fui-brand: #0066ff,
  $fui-neutral: "ice",
  $fui-density: "compact",
  $fui-radius-style: "rounded",
  $fui-danger: #dc2626,
  $fui-success: #16a34a
);

Available Seeds

| Seed | Type | Default | Description | | ------------------- | ------ | ----------- | ------------------------------------------------------- | | $fui-brand | Color | #18181b | Primary brand color - derives accent, focus rings, etc. | | $fui-neutral | String | "stone" | Neutral palette for surfaces, text, borders | | $fui-density | String | "default" | Spacing density scale | | $fui-radius-style | String | "default" | Corner radius style | | $fui-danger | Color | #ef4444 | Error/danger semantic color | | $fui-success | Color | #22c55e | Success semantic color | | $fui-warning | Color | #f59e0b | Warning semantic color | | $fui-info | Color | #3b82f6 | Info semantic color |

Neutral Palettes

| Name | Description | | ------- | ------------------------------------------------------------- | | stone | Cool gray neutrals (balanced, professional) — default | | mono | Near-black/product chrome neutrals for Resend-style dark apps | | ice | Cool blue-tinted grays (crisp, technical) | | earth | Warm brown-tinted grays (natural, grounded) | | sand | Warm tan-tinted grays (organic, approachable) | | fire | Warm red-tinted grays (bold, energetic) |

Density Presets

| Name | Base Unit | Feel | | --------- | --------- | ----------------------------------- | | compact | 6px | Tighter spacing, smaller elements | | default | 7px | Balanced, current visual appearance | | relaxed | 8px | More spacious layout |

Radius Styles

| Name | Feel | | --------- | --------------------------------- | | sharp | No rounding (technical, precise) | | subtle | Minimal rounding (modern minimal) | | default | Balanced rounding (current) | | rounded | More prominent (friendly) | | pill | Maximum rounding (playful, soft) |

Individual Token Overrides (Backward Compatible)

You can still override individual tokens directly:

@use "@fragments-sdk/ui/tokens" as *;

.custom {
  padding: $fui-space-4;
  border-radius: $fui-radius-md;
  color: var(--fui-text-primary);
}

Breakpoints

@use "@fragments-sdk/ui/mixins" as *;

.responsive {
  @include breakpoint-md {
    grid-template-columns: repeat(2, 1fr);
  }
  @include breakpoint-lg {
    grid-template-columns: repeat(3, 1fr);
  }
}

| Token | Value | | -------------------- | ------ | | $fui-breakpoint-sm | 640px | | $fui-breakpoint-md | 768px | | $fui-breakpoint-lg | 1024px | | $fui-breakpoint-xl | 1280px |

Migration Guide

Existing code continues to work. The seed system is fully backward compatible:

• Existing @use '@fragments-sdk/ui/tokens' imports work unchanged
• Individual variable overrides ($fui-color-accent: #blue) still work
• CSS variable usage (var(--fui-color-accent)) works
• Component APIs remain the same
• Visual appearance is unchanged with default seeds

To migrate to seeds (optional):

1. Instead of overriding many individual tokens, set seed values:

   // Before: many individual overrides
   $fui-color-accent: #0066ff;
   $fui-color-accent-hover: #0052cc;
   $fui-bg-secondary: #f1f5f9;
   // ...many more
   
   // After: just seeds
   @use "@fragments-sdk/ui/styles" with (
     $fui-brand: #0066ff,
     $fui-neutral: "ice"
   );

2. Dark mode, hover states, and derived colors are computed automatically

AI Agent Support

This package ships a fragments.json file that describes every component's props, usage guidelines, accessibility rules, and code examples. AI agents can access this data through the @fragments-sdk/mcp server.

Setup with Claude Code

1. Install both packages:

npm install @fragments-sdk/ui @fragments-sdk/mcp

2. Add the MCP server to your Claude Code settings (~/.claude/settings.json):

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

The MCP server automatically discovers fragments.json from the installed @fragments-sdk/ui package. No configuration needed.

Or use the CLI to set up everything at once:

npx @fragments-sdk/cli setup --mcp

Composition Blocks

The library includes composition blocks — named patterns showing how components wire together for common use cases:

• Login Form — Email/password authentication form
• Confirm Dialog — Destructive action confirmation
• Card Grid — Responsive auto-fill card layout
• Form Layout — Two-column form with Grid
• Dashboard Layout — Featured card with metrics grid
• Settings Page — Settings sections with cards and controls

Access blocks via the MCP server's blocks tool or context.

License

MIT