Building Fragments: From Zero to 67 Components

Fragments started with a question: what would a component library look like if it was designed for AI from day one?

Not AI-generated — AI-native. A library where every component carries enough metadata that an AI assistant can use it correctly without ever seeing the documentation website.

Starting with Base UI

The foundation is Base UI — headless, accessible primitives from the MUI team. This was a deliberate choice:

• Accessibility out of the box — ARIA patterns, keyboard navigation, and focus management handled at the primitive level
• No style opinions — Full control over the design token system
• Composition-friendly — Compound component patterns that map cleanly to metadata

Building on Base UI meant I could focus on the parts that make Fragments unique: the token system, the metadata layer, and the MCP integration.

Seed-based theming

Most design systems require you to configure dozens of individual tokens. Fragments takes a different approach — you provide 4 seed values, and the system derives ~200 CSS custom properties:

configureTheme({
  brand: '#6366f1',
  neutral: 'ice',
  density: 'default',
  radiusStyle: 'rounded',
});

From these seeds, the system generates surface colors, text colors, border colors, shadows, spacing scales, and semantic colors — all with automatic light and dark mode support.

The metadata layer

Every component has a .contract.json file co-located next to its source. These contracts are:

• Machine-readable — AI agents parse them directly via MCP
• Human-useful — They serve as living documentation
• Build-validated — The CLI checks contracts against source code

This dual-purpose approach means the metadata never goes stale — it's part of the build pipeline.

What I learned

Building 67 components as a solo engineer taught me that the hard part isn't the components — it's the system around them. The token derivation, the CLI tooling, the MCP integration, the governance engine. The components are almost the easy part when the infrastructure is right.

The compound effect is real: once the first 20 components were solid, the next 47 came faster because the patterns, tokens, and tooling were established.