Make Your Design System AI-Native

We've all been there. You fire up an AI agent, give it a vague prompt like "build me a dashboard, make it look nice", and a minute later you're staring at something that technically works but looks like three different apps stitched together.

The buttons don't match. The spacing is off. The dreaded purple and blue gradient is everywhere. You asked for a dashboard and got a Frankenstein UI.

AI Slop is real

The first greenfield features and screens AI helps you build are fine. They might even look good. However, once a codebase gets larger it becomes increasingly difficult for AI to know exactly how to write things consistently.

Those stat cards that AI created for you on the dashboard are different from the stat cards on the reports page. That cool button that AI wrote for you has been hardcoded 23 different times across multiple pages. The more this happens across components and pages, the more design drift occurs. It's a maintenance nightmare and a design system killer. This lack of design consistency cheapens a brand and your users' perception.

Skills and agents can help mitigate this to an extent, or some resolve to just context dumping rules into each prompt. Skills and agents definitely have their place, but they are simply tools that attempt to guide AI agents in the right direction. They are not enforcement agents.

Introducing Fragments: Metadata That Lives With the Code

Better prompts won't fix this.

If AI is writing your UI, it needs real, queryable context about your components. That context also has to live with the code itself, otherwise it goes stale and becomes yet another doc nobody updates.

In Fragments, every component ships with a .fragment.tsx file:

import { defineFragment } from '@fragments-sdk/cli/core';

export default defineFragment({
  meta: {
    name: 'Button',
    description: 'Interactive element for user actions and form submissions',
    category: 'forms',
    status: 'stable',
    tags: ['action', 'button', 'form', 'interactive'],
  },
  usage: {
    when: [
      'Triggering an action (save, submit, delete)',
      'Form submission',
      'Opening dialogs or menus',
    ],
    whenNot: [
      'Simple navigation (use Link)',
      'Toggling state (use Switch or Checkbox)',
    ],
    guidelines: [
      'Only one primary button per section',
      'Use danger variant for destructive actions',
    ],
    accessibility: [
      'Button text should describe the action',
      'Icon-only buttons need aria-label',
    ],
  },
});

The meta block tells AI what the component is and if it's actually ready to use. The usage block tells it when to use it and when not to. You can also define props (with types/defaults), variants, relationships to other components, and composition patterns.

Every component in the library has one of these files, right next to the component source. Change the component, update the fragment. No random Notion page required.

MCP Tools: A Query Layer for AI Agents

Fragment files are the source of truth. MCP is how AI actually reads them. Fragments ships with 9 MCP tools:

Without MCP, AI guesses from training data. With MCP, it queries your design system on each decision. Huge difference.

Seed-Based Theming: 4 Values, Not 500

Most token systems make you manage hundreds of values, which means hundreds of ways for AI to get it wrong.

Fragments does the opposite. You set 4 seed values and a derivation engine generates everything else:

@use '@fragments-sdk/ui/styles' with (
  $fui-brand: #6366f1,          // Your brand color
  $fui-neutral: "ice",           // Neutral palette: stone | ice | earth | sand | fire
  $fui-density: "default",       // Spacing: compact | default | relaxed
  $fui-radius-style: "rounded"   // Corners: sharp | subtle | default | rounded | pill
);

From those 4 seeds, Fragments generates nearly 200 CSS custom properties: full color palettes (with hover/active/focus states), surface layers, text hierarchy, borders, spacing scales, typography, shadows, border radii, focus rings, and WCAG-compliant contrast-safe variants for both light and dark modes.

So instead of AI picking between 12 class names that kinda look right, it uses the exact token from your system.

When design says "make corners rounder", you change one value ($fui-radius-style: "rounded" → "pill") and the whole system updates. Want a warm neutral palette? Change "ice" to "sand". Done. You can try this in the theme builder to see how just 4 values transform an entire system.

Getting Started

Install the component library, then initialize Fragments:

npm install @fragments-sdk/ui
npx @fragments-sdk/cli init

You get 60+ production-ready components, seed-based theming, and fragment metadata for every component.

Run npx @fragments-sdk/cli dev to browse props, usage guidance, a11y results, and relationships locally.

Connect your AI assistant via MCP:

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

Drop that in Claude Desktop, Cursor, VS Code, Windsurf, or Claude Code.

Then ask for something like "build a settings form" and watch it use your components instead of inventing new ones.

What's Next

Design systems were always about consistency.

The old assumption was that humans were the only ones reading the docs. That's not true anymore.

Fragments makes your system understandable to both humans and AI.

We're building toward "bring your own design system" so you can point Fragments at your existing library and get MCP tools, audits, and local preview without a rewrite.

We have many other items on the roadmap, so stay tuned.

Until next time.

Browse the components, try the theme builder, and connect the MCP server if you want to see the difference yourself.