UI Keeper

The local-first frontend quality and verification layer for AI coding agents (Cursor, OpenCode, Claude Code, Windsurf, Codex).

Read the Complete Usage & Setup Guide (USAGE.md)

What is UI Keeper?

AI coding assistants generate React and Tailwind code rapidly, but frequently introduce silent frontend quality degradation:

• Design System Drift: Hardcoding arbitrary colors (#1e293b) or off-grid pixel values (p-[18px], m-[13px]) instead of adhering to project tokens.

• Component Duplication & Primitive Monoliths: Rebuilding raw primitive tags (<button className="...">, <input ...>) rather than reusing existing catalog components (e.g. Button, Input, Dialog).

• Repeated Inline JSX: Copy-pasting complex composite JSX structures (e.g., status badges or metric cards) instead of extracting reusable components.

• Tailwind Class Bloat & Conflicts: Adding contradictory classes (flex block, text-left text-center, p-4 px-6).

• Accessibility & Contrast Violations: Low-contrast text combinations failing WCAG 2.1 AA ($< 4.5:1$), unlabelled inputs, or missing image alt attributes.

UI Keeper solves this by providing a comprehensive static analysis, design token extraction, component discovery, and automated verification layer accessible via the Model Context Protocol (MCP) and a high-performance CLI.

Related MCP server: vibecraft-mcp

Key Capabilities

graph TD
    Agent[AI Agent: Cursor / OpenCode / Claude] -->|MCP JSON-RPC| UIKeeper[UI Keeper Engine]
    UIKeeper -->|Extract| DS[Design Tokens & Catalog]
    UIKeeper -->|Analyze| AST[TypeScript AST Scanner]
    AST -->|Audit| Rules[7 Static UI Quality Rules]
    Rules -->|Verify| Loop[Detect -> Fix -> Re-audit Loop]
    Loop -->|Report| Score[UI Health Score: 0-100%]

1. Dynamic Design Token & Theme Extractor

• Discovers and extracts tokens across CSS files (globals.css, token.css, theme.css).

• Full support for Tailwind CSS v3 (tailwind.config.ts/js) and Tailwind CSS v4 (@import "tailwindcss", @theme, @utility, @plugin).

• Extracts colors (hex, rgb, hsl, oklch), 4px spacing scale, typography, radii, shadows, and breakpoints.

2. Component Catalog Scanner

• Scans .tsx/.jsx files across components/, src/components/, app/components/, ui/, src/ui/.

• Extracts exported component names, prop types, variants, and categories (button, card, input, modal, navigation, layout, feedback, typography).

• Prevents agents from reinventing already existing components.

3. 7 Built-in Static UI Quality Rules

4. Auto-Fix with Verification Loop

Applies automated fixes and immediately verifies them:

1. Detect: Audits the file and records baseline issue count.

2. Fix: Applies high-confidence token substitutions and class optimizations.

3. Re-audit: Re-analyzes the modified file.

4. Decision: Keeps changes only if total issues decrease; automatically reverts on regression.

5. UI Health Score (0-100%) & Letter Grade

Calculates a weighted UI Health Score:

• Token Adoption (35%): Adherence to colors, radii, and 4px spacing grid.

• Component Reuse (35%): Catalog usage and absence of monolithic JSX duplicates.

• Code Cleanliness (30%): Absence of class conflicts and WCAG contrast violations.

• Outputs an overall score with letter grade (A+, A, B, C, D, F) and actionable recommendations.

Available MCP Tools

UI Keeper exposes 10 standardized MCP tools compatible with any MCP client:

Monorepo Architecture

The repository is structured as a modular TypeScript monorepo:

ui-keeper/
├── packages/
│   ├── core/           # @ui-keeper/core (Domain schemas, AST scanners, token parsers, 7 audit rules, auto-fix loop)
│   ├── cli/            # @ui-keeper/cli (Command-line tool: init, analyze, audit, fix, score, generate, hook)
│   └── local-mcp/      # @ui-keeper/local-mcp (Local Stdio MCP server for direct filesystem access)
└── apps/
    └── remote-mcp/     # @ui-keeper/remote-mcp (Cloudflare Workers edge MCP server built with Hono)

Getting Started & Usage

For full step-by-step installation, client configuration (OpenCode, Cursor, Claude, Windsurf), CLI references, and Git pre-commit hook setups, read USAGE.md.