Metadata-Version: 2.4
Name: ultimate-ui-design-promcp
Version: 1.0.2
Summary: Token-first UI design pipeline as a ProMCP-native server (triadic can_do/read_*/do_* over FastMCP): design intelligence, extraction, token generation, contrast, motion, and audit for React/Tailwind v4 + shadcn and Flutter (iOS/Android).
Author: Alejandro Andrade
License: MIT
Project-URL: Homepage, https://github.com/alexlqi/ultimate-ui-design-promcp
Project-URL: Repository, https://github.com/alexlqi/ultimate-ui-design-promcp
Project-URL: Author, https://github.com/alexlqi
Keywords: mcp,promcp,fastmcp,design-tokens,ui,tailwind,shadcn,flutter,wcag,apca
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: promcp<0.4,>=0.3.0
Requires-Dist: fastmcp<4,>=3.4
Provides-Extra: extract
Requires-Dist: playwright>=1.40; extra == "extract"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# ultimate-ui-design

An MCP server that turns **design tokens into real, consistent UI** — for the web, Android,
iOS, and email — straight from your AI assistant (Claude Code, Claude Desktop, or any MCP client).

You describe what you want ("a calm fintech dashboard, dark-mode first"); the server walks the
model through a disciplined, token-first pipeline and can write the actual theme files to your
project. Colors, spacing, and type all flow from one source of truth — so nothing is hardcoded,
contrast is checked for you, and the output is the same every time you run it.

> Looking for how it's built internally? See **[ARCHITECTURE.md](ARCHITECTURE.md)**.

---

## What you get

- **Four build targets ("paradigms"), one workflow**
  - `web` — React + Tailwind v4 + shadcn/ui
  - `flutter-material` — Flutter / Material 3 (Android)
  - `flutter-cupertino` — Flutter / Cupertino · HIG (iOS)
  - `email` — bulletproof responsive HTML email (Outlook/Gmail/Apple Mail · dark mode · CAN-SPAM)
- **Tokens as the single source of truth** — one design decision generates deterministic,
  diff-able theme files. Same input → same output, every time.
- **Accessibility built in** — every color pair is checked (WCAG 2.1 + APCA) automatically.
- **Extract from any live site** — point it at a public URL and it reads the *computed* styles
  into a token spec you can reuse.
- **Design audit** — run your components against the live Web Interface Guidelines and get
  `file:line` findings.
- **Safe by design** — the model can generate and preview everything, but only **one** action
  ever writes to disk, and it's reversible.

---

## Install

There's nothing to clone and no Python packages to manage. The one prerequisite is
[**uv**](https://docs.astral.sh/uv/) — a single self-contained binary that pulls Python,
`promcp`, and `fastmcp` into an isolated, cached environment for you:

```bash
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

That's the only thing you install. Everything else is handled by `uvx` at launch.

---

## Connect it to your client

### Claude Code (recommended)

One command — `uvx` fetches the package and all its dependencies automatically:

```bash
claude mcp add uidesign -- uvx ultimate-ui-design-promcp
```

Or just **ask Claude Code to do it for you**:

> Add the ultimate-ui-design MCP server with `uvx ultimate-ui-design-promcp`.

### Claude Desktop (or any client using an `mcpServers` config)

```json
{
  "mcpServers": {
    "ultimate-ui-design": {
      "command": "uvx",
      "args": ["ultimate-ui-design-promcp"]
    }
  }
}
```

Restart your client and the tools appear automatically. On first launch `uvx` downloads and
caches the package; subsequent starts are instant.

### Optional — live-site token extraction

The `read_extracted_design_system` tool (reading tokens from a public website) needs Playwright.
Pull it in via the `extract` extra and do the one-time browser download:

```bash
uvx --from "ultimate-ui-design-promcp[extract]" ultimate-ui-design-promcp
# then, once, to fetch the headless browser binary:
uvx --from "ultimate-ui-design-promcp[extract]" playwright install chromium
```

Everything else works without it.

<details>
<summary>Run from source instead (for development)</summary>

```bash
pip install "promcp>=0.3.0,<0.4" "fastmcp>=3.4,<4"
python server.py   # stdio
# register: claude mcp add uidesign -- python /absolute/path/to/server.py
```
</details>

---

## Using it

The easiest way to start is the built-in **`design_pipeline`** prompt. Just tell it your brief
and which paradigm you're targeting:

> **design_pipeline** — brief: *"A calm, trustworthy fintech dashboard, dark-mode first"*,
> paradigm: *web*

The assistant then runs the full token-first flow for you:

1. **Preflight** — checks your toolchain is ready for the chosen paradigm.
2. **Design decision** — picks a pattern, palette, type scale, spacing, and effects.
3. **Validate** — sanity-checks the token spec before anything is written.
4. **Tokens** — generates the theme files (and verifies contrast) — still in memory.
5. **Write** — persists the files to your project (the one step that touches disk).
6. **Components + motion** — builds UI that consumes *only* tokens, in every state.
7. **Audit** — reviews the result against current UI guidelines.

Prefer a review pass on existing UI? Use the **`audit_only`** prompt and point it at your
component files.

You can also just talk to it naturally — "generate a light+dark theme for this brand color and
write it into `./theme`" — and it will pick the right tools.

---

## Your design in one spec

Everything comes from a small JSON token spec. Colors are sRGB hex so contrast can be verified:

```jsonc
{
  "name": "fintech",
  "light": {
    "bg": "#ffffff", "fg": "#0a0a0a",
    "brand": "#2f6bff", "on-brand": "#ffffff",
    "muted-fg": "#6b7280", "border": "#e5e7eb", "danger": "#d92d20"
  },
  "dark": {
    "bg": "#0b0c0e", "fg": "#fafafa",
    "brand": "#5b8bff", "on-brand": "#08101f",
    "muted-fg": "#9ca3af", "border": "#26282c", "danger": "#f97066"
  }
}
```

Only `bg`, `fg`, and `brand` are required — fill in the rest as your design grows.

---

## What it generates

| Paradigm | Output |
|---|---|
| `web` | CSS variables, Tailwind v4 theme, shadcn/ui theme, DTCG tokens |
| `flutter-material` | `app_theme_material.dart` — seeded Material 3 `ColorScheme`, 8-dp grid, `ThemeExtension` |
| `flutter-cupertino` | `app_theme_cupertino.dart` — `CupertinoThemeData`, 44-pt touch targets, token scope |
| `email` | `email.html` — bulletproof responsive newsletter: XHTML + VML for Outlook, MSO ghost tables, VML button, `prefers-color-scheme` + `[data-ogsc]` dark mode, CAN-SPAM/GDPR footer, <102 KB (no Gmail clip) |

All web/Flutter/email outputs can coexist in the same project.

---

## FAQ

**Will it overwrite my files?**
Writing is the only action that changes disk, it's opt-in, and it's reversible — the write
reports exactly which files it created so they can be removed if you change your mind.

**Do I need Playwright?**
Only for the "extract tokens from a live website" feature. Everything else works without it.

**Can I use it without the prompts?**
Yes. The prompts are just a guided path; you can ask for any single step (generate tokens,
check contrast, audit a file) directly.

---

Author: Alejandro Andrade ([@alexlqi](https://github.com/alexlqi)).
