FramingUI Themes Without Config File Changes

Every new project starts with the same ritual: edit tailwind.config.js, define CSS variables for light and dark mode, manually sync TypeScript types, and pray nothing breaks when the designer tweaks a color next week.

This setup tax eats hours before you write a single line of UI. FramingUI eliminates it.

The Three-Source Problem

Traditional theme setup forces you to maintain three separate sources of truth simultaneously.

The Tailwind config holds raw color values. A separate CSS variables file maps those values to semantic names. TypeScript declaration files try to keep autocomplete in sync with both. When your designer changes a single brand color, you touch all three files—and hope you didn't miss anything.

The configuration looks substantial and feels productive, but it produces only one outcome: a fragile system where a typo in any of the three files causes silent failures or broken styles.

How FramingUI Works Instead

FramingUI connects your project through a single runtime contract. One command wires everything together:

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

This detects your framework (Next.js or Vite), installs @framingui/ui and tailwindcss-animate, adds the CSS import to your global stylesheet, mounts FramingUIProvider in your app root, creates a local framingui-theme module, and registers the MCP server in .mcp.json. Ten steps, one command.

The resulting runtime contract is explicit and minimal:

• @import '@framingui/ui/styles' appears exactly once in your global stylesheet
• FramingUIProvider mounts exactly once at the app root
• A local framingui-theme module passes your theme configuration to the provider
• tailwindcss-animate is installed for overlay animations

Change the theme by updating the framingui-theme module. Everything downstream updates automatically.

Tokens as CSS Variables

FramingUI exposes design tokens as CSS custom properties—not JavaScript objects with hardcoded hex values. Your theme file contains references like var(--background-page) and var(--foreground-accent), not { background: '#ffffff' }.

This matters for how AI generates code. When Claude queries your design system through the MCP server, it retrieves actual CSS variable names with semantic meaning—not raw color values to guess from. The model asks what token applies to a primary button background and gets a definitive answer. No approximation, no hallucination.

Adding a Theme Without Config Files

Suppose you want to switch from the default square-minimalism theme to dark-boldness. With traditional setup, you'd update Tailwind, CSS variables, and TypeScript declarations. With FramingUI, you update one value in your framingui-theme module.

FramingUI ships six production themes: classic-magazine, dark-boldness, minimal-workspace, neutral-workspace, pebble, and square-minimalism. Each is fully licensed and accessible through the MCP server after authentication.

framingui-mcp login

Authentication uses an API key stored in ~/.framingui/credentials.json. Once authenticated, Claude Code can preview themes, list components, and generate screen blueprints using whichever licensed theme your project references.

What the MCP Server Provides

The MCP server exposes 16 tools to Claude Code and other MCP-compatible editors. The tools cover four categories: blueprint and theme exploration, icon library browsing, the four-step screen generation workflow, and environment validation.

The screen generation workflow is what makes FramingUI distinct from copy-paste approaches:

1. get-screen-generation-context — queries matching templates and components for a natural-language description
2. validate-screen-definition — validates the structured screen definition JSON before generation
3. generate_screen — produces React component code from a validated definition
4. validate-environment — confirms your project has the required packages and Tailwind configuration

The environment validation step is worth noting specifically. It checks for the runtime contract conditions—global stylesheet import, provider mount, theme module, animate package—rather than just checking whether packages are installed. A project can have the right packages and still fail at runtime if the wiring is wrong.

For Tailwind v4 Projects

Tailwind v4 projects do not need manual @source entries for @framingui/ui. The @import '@framingui/ui/styles' line carries the scanning contract internally. Adding extra source entries will not break anything, but they're unnecessary and should be omitted to keep configuration minimal.

If button padding or dialog animations look wrong after installation, check the runtime contract first before investigating packages. The four conditions—stylesheet import, provider mount, theme module, animate package—cover the majority of runtime issues.

The Install Path

For a new project, the full setup sequence is:

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

Restart Claude Code. Ask it to generate a screen. The MCP server handles the rest.

For existing projects that only need the React components without the MCP workflow:

pnpm add @framingui/ui @framingui/core @framingui/tokens tailwindcss-animate

Theme setup shouldn't be the hardest part of building a product. FramingUI makes it the fastest.