FramingUI

Production UI through an MCP-installed design system.

FramingUI is a design system for AI-assisted product teams. Instead of asking an agent to invent UI from scratch, you install FramingUI as an MCP server and give the agent a real component catalog, theme system, layout tokens, quota-backed tool workflow, and validated screen contracts.

The goal is simple: use MCP to build production UI with stronger contracts, fewer hallucinated components, and clearer integration steps.

FramingUI currently ships two runtime lanes: @framingui/ui for web React, and @framingui/react-native for Expo / React Native direct-write workflows. MCP still provides the contract, discovery, and validation layer on top.

What FramingUI Includes

• @framingui/mcp-server: MCP server for discovery, screen workflows, validation, and project setup
• @framingui/ui: React UI components and styles
• @framingui/react-native: React Native runtime primitives and token consumption helpers
• @framingui/core: theme, token, and screen-generation utilities
• @framingui/tokens: token types and references
• @framingui/styled: token-aware styled-components helpers
• @framingui/esbuild-plugin: build-time token compliance checks

Recommended Start

Install the MCP server in your project and let it wire up the design system:

npx -y @framingui/mcp-server@latest init

Then authenticate:

npx @framingui/mcp-server@latest login

Inspect the current account state when needed:

npx @framingui/mcp-server@latest whoami

This setup flow can:

• install @framingui/ui
• configure Tailwind content paths and tailwindcss-animate
• add @import '@framingui/ui/styles'; when using the FramingUI-native style contract
• generate a local framingui-theme module and mount FramingUIProvider in the app root
• register the MCP server in .mcp.json
• generate project guidance for FRAMINGUI-GUIDE.md, CLAUDE.md, and AGENTS.md

Account and Quota

FramingUI is transitioning from template-first licensing to MCP tool-unit plans.

• whoami shows current theme entitlements and the shadow quota snapshot for the active billing window
• shadow quota is visible before hard enforcement so teams can estimate real workflow cost
• legacy theme or template customers keep their existing access during the migration window
• paid plans are moving toward included monthly tool units plus top-up or overage paths

MCP Workflow

The production screen workflow is component-first and validation-first:

1. If the project path is known, call detect-project-context once to store the default platform/runtime for the session
2. preview-theme when theme recipes or defaults matter
3. get-screen-generation-context
4. preview-component for any ambiguous component contract
5. list-icon-libraries before introducing icons
6. validate-screen-definition for web screen-definition work
7. write code directly from the returned contract
8. validate-environment for dependency, style-contract, and code-audit checks

For Expo / React Native projects, start with detect-project-context so downstream discovery tools default to the native path automatically. If project path is unavailable, fall back to platform: "react-native" explicitly. In that path, use @framingui/react-native where the runtime surface exists, then fall back to host primitives or app-local abstractions for the rest.

FramingUI also provides slash-command guidance for common actions such as:

• /screen
• /draft
• /section
• /responsive
• /a11y
• /theme-swap
• /doctor
• /install-check
• /export
• /update

Example MCP Config

{
  "mcpServers": {
    "framingui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@framingui/mcp-server@latest"]
    }
  }
}

Package Usage

Install packages directly when you need them without the guided MCP setup.

Web:

pnpm add @framingui/ui @framingui/core

import '@framingui/ui/styles';
import { FramingUIProvider, Button, Card, CardContent, CardHeader, CardTitle } from '@framingui/ui';
import framinguiTheme from './framingui-theme';

export function ExampleCard() {
  return (
    <FramingUIProvider theme={framinguiTheme}>
      <Card>
        <CardHeader>
          <CardTitle>Ship product UI</CardTitle>
        </CardHeader>
        <CardContent>
          <Button>Open workflow</Button>
        </CardContent>
      </Card>
    </FramingUIProvider>
  );
}

Expo / React Native:

pnpm add @framingui/react-native

import { Button, Screen, TextField } from '@framingui/react-native';

export function SignupScreen() {
  return (
    <Screen width="narrow">
      <TextField label="Email" placeholder="name@example.com" />
      <Button label="Continue" />
    </Screen>
  );
}

Documentation

• GitHub package docs: packages/*/README.md
• MCP server docs: packages/mcp-server/docs
• Product docs: framingui.com/docs

Quality Gates

MCP pipeline checks are split into two lanes:

• pnpm ci:mcp:pr: required pull-request gate for theme authority, screen contract, generation quality, and CSS variable regressions
• pnpm ci:mcp:nightly: heavier browser smoke lane intended for scheduled or manual execution

Status

FramingUI is actively evolving around:

• MCP-native UI generation
• guarded direct-write workflows
• theme-aware component discovery
• production integration checks

License

MIT