Fragments UI Setup

Set up the @fragments-sdk/ui component library -- from install to rendering your first component.

1. Detect project environment

Confirm the project has a package.json. If not, ask if the user wants to initialize one.
Detect the package manager from lock files:
- bun.lockb or bun.lock -> bun
- pnpm-lock.yaml -> pnpm
- yarn.lock -> yarn
- Otherwise -> npm
Detect the framework and its version:
- React / Next.js / Remix / Vite+React
- Vue / Nuxt (note: @fragments-sdk/ui requires React -- suggest the Vue adapter or confirm the user wants to add React)
- Check the TypeScript version -- @fragments-sdk/ui requires TS 5.0+

2. Install the UI package

First check if @fragments-sdk/ui is already available:

In a monorepo with workspace dependencies (look for "workspace:*" or "workspace:^" in package.json), the package may already be linked. If so, skip the install step.
Also check parent directories for pnpm-workspace.yaml or a workspaces field.

If not already installed:

<package-manager> add @fragments-sdk/ui

Also install the icon library if not present:

<package-manager> add @phosphor-icons/react

3. Set up the CSS import

Add the Fragments UI stylesheet to the app's entry point. Detect the right file:

Next.js App Router -- app/layout.tsx:

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

Next.js Pages -- pages/_app.tsx:

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

Vite + React -- src/main.tsx:

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

Remix -- app/root.tsx:

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

The stylesheet must be imported before any app-level CSS so tokens are available for overrides.

4. Configure the FragmentsProvider

Wrap the app root with the provider. Detect the right location:

Next.js App Router -- app/layout.tsx (or a dedicated app/providers.tsx):

In Next.js App Router, the provider must be in a Client Component because it uses React context.

tsx

'use client';

import { FragmentsProvider } from '@fragments-sdk/ui';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <FragmentsProvider theme="dark">
      {children}
    </FragmentsProvider>
  );
}

Then use it in the root layout:

tsx

import '@fragments-sdk/ui/styles.css';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Vite + React -- src/main.tsx or src/App.tsx:

tsx

import { FragmentsProvider } from '@fragments-sdk/ui';

function App() {
  return (
    <FragmentsProvider theme="dark">
      {/* app content */}
    </FragmentsProvider>
  );
}

Ask the user which theme to default to: "dark", "light", or "system".

5. Create a sample component

Create a simple component to verify the setup works. Place it based on the project structure:

tsx

import { Button, Card, Stack, Text } from '@fragments-sdk/ui';
import { Rocket } from '@phosphor-icons/react';

export function Welcome() {
  return (
    <Card variant="outlined" padding="lg">
      <Stack gap="md">
        <Text as="h2" size="lg" weight="semibold">
          Fragments UI is ready
        </Text>
        <Text size="sm" color="tertiary">
          You can now use any component from the design system.
        </Text>
        <Button>
          <Rocket size={14} weight="bold" />
          Get started
        </Button>
      </Stack>
    </Card>
  );
}

Render it somewhere visible and confirm it displays correctly.

6. Set up the MCP server (optional)

If $ARGUMENTS contains --with-mcp, or ask the user: "Want to add the Fragments MCP server for AI-assisted development?"

If yes:

Read .claude/settings.json if it exists. Merge the Fragments MCP server into the existing mcpServers object -- do NOT overwrite any existing servers. If the file doesn't exist, create it.

The resulting mcpServers should include:

json

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

This enables the AI agent to discover components, generate UI, inspect props, check performance, and validate governance -- all from within the conversation.

Explain the key tools now available:

mcp__fragments__fragments_discover -- find the right component for any use case
mcp__fragments__fragments_implement -- get everything needed to build a feature in one call
mcp__fragments__fragments_inspect -- deep dive into any component's props and examples
mcp__fragments__fragments_blocks -- find pre-built composition patterns

7. Update .gitignore

Add .agents/ to .gitignore if not already present (this is where installed skills live). Create .gitignore if needed.

8. Configure module resolution (if needed)

If the project uses TypeScript with an older moduleResolution setting, ensure it can resolve @fragments-sdk/ui subpath exports:

json

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

This is required for imports like @fragments-sdk/ui/styles.css to resolve correctly. Projects using "moduleResolution": "node" may fail to find subpath exports.

9. Confirm completion

Summarize what was done:

@fragments-sdk/ui and @phosphor-icons/react installed
CSS imported in the app entry point
FragmentsProvider wrapping the app with chosen theme
Sample component created and rendering
MCP server configured (if chosen)

Mention related skills:

The fragments-ui skill loads automatically with best practices, token reference, and patterns
/fragments-cloud-setup to add design governance and cloud dashboard

Common mistakes

CRITICAL: CSS import after app styles

Importing @fragments-sdk/ui/styles.css after app-level CSS causes tokens to be overridden. Components may appear unstyled or use wrong colors.

Wrong -- app CSS loaded first:

import './globals.css';
import '@fragments-sdk/ui/styles.css';

Correct -- Fragments CSS loaded first:

import '@fragments-sdk/ui/styles.css';
import './globals.css';

HIGH: FragmentsProvider in a Server Component (Next.js App Router)

FragmentsProvider uses React context, which requires a Client Component. Placing it directly in layout.tsx without 'use client' causes a runtime error.

Wrong:

tsx

// app/layout.tsx -- Server Component by default
import { FragmentsProvider } from '@fragments-sdk/ui';

export default function RootLayout({ children }) {
  return (
    <html><body>
      <FragmentsProvider>{children}</FragmentsProvider>
    </body></html>
  );
}

Correct -- extract to a Client Component:

tsx

// app/providers.tsx
'use client';
import { FragmentsProvider } from '@fragments-sdk/ui';

export function Providers({ children }: { children: React.ReactNode }) {
  return <FragmentsProvider theme="dark">{children}</FragmentsProvider>;
}

HIGH: Missing FragmentsProvider entirely

All Fragments components require the provider for theming and context. Without it, components render without tokens and may appear broken or unstyled.

Wrong:

tsx

import { Button } from '@fragments-sdk/ui';

export default function App() {
  return <Button>Click me</Button>; // no provider ancestor
}

Correct:

tsx

import { FragmentsProvider, Button } from '@fragments-sdk/ui';

export default function App() {
  return (
    <FragmentsProvider theme="dark">
      <Button>Click me</Button>
    </FragmentsProvider>
  );
}

MEDIUM: Monorepo double-install

Installing @fragments-sdk/ui in a sub-package when the workspace root already provides it causes duplicate React instances and broken hooks.

If pnpm-workspace.yaml, yarn workspaces, or npm workspaces exist, check the root node_modules first before installing.

@fragments-sdk/skills