red-design-mcp 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 red-design-mcp contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,484 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="./assets/banner.svg" alt="red-design-mcp: recreate, reimagine and audit any design" width="100%">
4
+
5
+ <br/>
6
+
7
+ [![npm version](https://img.shields.io/npm/v/red-design-mcp?style=flat-square&color=e11d48&logo=npm&logoColor=white)](https://www.npmjs.com/package/red-design-mcp)
8
+ [![npm downloads](https://img.shields.io/npm/dm/red-design-mcp?style=flat-square&color=e11d48)](https://www.npmjs.com/package/red-design-mcp)
9
+ [![node](https://img.shields.io/node/v/red-design-mcp?style=flat-square&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
10
+ [![license](https://img.shields.io/npm/l/red-design-mcp?style=flat-square&color=2563eb)](./LICENSE)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
12
+ [![PRs welcome](https://img.shields.io/badge/PRs-welcome-22c55e?style=flat-square)](#contributing)
13
+
14
+ ![MCP compatible](https://img.shields.io/badge/MCP-compatible-e11d48?style=flat-square)
15
+ ![36 tools](https://img.shields.io/badge/tools-36-e11d48?style=flat-square)
16
+ ![API key optional](https://img.shields.io/badge/API%20key-optional-22c55e?style=flat-square)
17
+ ![8 workflows](https://img.shields.io/badge/agent%20workflows-8-e11d48?style=flat-square)
18
+ ![14 agents](https://img.shields.io/badge/agents-14-D97757?style=flat-square)
19
+ ![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-D97757?style=flat-square)
20
+ ![Codex](https://img.shields.io/badge/Codex-supported-111827?style=flat-square)
21
+ ![Cursor](https://img.shields.io/badge/Cursor-supported-000000?style=flat-square)
22
+ ![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-supported-D97757?style=flat-square)
23
+
24
+ ### Give your AI tools a designer's eye.
25
+
26
+ Analyze, recreate, reimagine, critique and audit **any design** straight from Claude Code, Codex, Cursor and every other MCP client.
27
+
28
+ [**Quick start**](#quick-start) · [**Tools**](#tools) · [**Examples**](#example-prompts) · [**How it works**](#how-it-works) · [**Roadmap**](#roadmap)
29
+
30
+ </div>
31
+
32
+ ---
33
+
34
+ ## Why red-design-mcp?
35
+
36
+ | | |
37
+ |---|---|
38
+ | **One command** | `npx red-design-mcp install` configures every AI tool it finds. No JSON editing. |
39
+ | **No API key needed** | In host mode your AI tool does the seeing, so there is no second bill and no second key. |
40
+ | **Math, not vibes** | Contrast ratios, palettes, color-blindness simulation, type scales and originality scores are computed in code, so they are exact and repeatable. |
41
+ | **Whole design system in one call** | `generate_design_system` turns a brand color and a mood into palette, light and dark themes, fonts, fluid type, spacing, radii and shadows, with contrast verified. |
42
+ | **Agents included** | 14 agents for Claude Code, Cursor, Codex, Gemini CLI and Copilot (plus AGENTS.md), 8 one-command workflows, and an autonomous `audit_site`. |
43
+ | **Reverse-engineer any website** | Point it at a URL: it reads the live CSS for tokens, lints it, or screenshots the page for the vision tools. |
44
+ | **Security checks (Red Chex)** | Reviews headers, CSP, cookies, leaked secrets and trackers on a live page, then writes the fixes as ready-to-paste config. |
45
+ | **Tools on demand** | Let your AI discover and run only the tools a task needs with `RED_TOOLS=auto`, or pin the groups you want yourself. |
46
+ | **Inspiration dial** | Slide from a faithful rebuild (0) to a wild reinterpretation (100) and get up to 3 variations at once. |
47
+ | **Accessible by default** | Recreations fix contrast, semantics and tap targets unless you say otherwise. |
48
+ | **Any model, any client** | Use Anthropic, OpenAI, Google Gemini, Groq, OpenRouter, a local model through Ollama, or any OpenAI-compatible endpoint. Or let your host model handle it. Works over standard MCP stdio. |
49
+
50
+ ## Quick start
51
+
52
+ ```bash
53
+ npx red-design-mcp install
54
+ ```
55
+
56
+ That's it. The installer detects **Claude Code, Codex, Cursor and Claude Desktop**, adds the server, backs up any config it edits (`.bak`), and never touches your other servers. Restart your AI tool and try:
57
+
58
+ > *"Analyze `./screens/pricing.png` and recreate it in Tailwind."*
59
+
60
+ <details>
61
+ <summary><b>Install options and manual setup</b></summary>
62
+
63
+ <br/>
64
+
65
+ ```bash
66
+ npx red-design-mcp install # auto-detect your tools
67
+ npx red-design-mcp install --client codex,cursor
68
+ npx red-design-mcp install --all # every supported client
69
+ npx red-design-mcp install --print # just show the config snippets
70
+ npx red-design-mcp install --global # use a globally installed binary (offline friendly)
71
+ npx red-design-mcp doctor # check Node, mode and detected clients
72
+ npx red-design-mcp doctor --check # also confirm your model still exists
73
+ npx red-design-mcp agents # install 14 design agents for your AI tools
74
+ ```
75
+
76
+ **Claude Code**
77
+
78
+ ```bash
79
+ claude mcp add --scope user red -- npx -y red-design-mcp
80
+ ```
81
+
82
+ **Codex** (`~/.codex/config.toml`)
83
+
84
+ ```toml
85
+ [mcp_servers.red]
86
+ command = "npx"
87
+ args = ["-y", "red-design-mcp"]
88
+ ```
89
+
90
+ **Cursor, Claude Desktop and any other MCP client**
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "red": { "command": "npx", "args": ["-y", "red-design-mcp"] }
96
+ }
97
+ }
98
+ ```
99
+
100
+ On Windows, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "red-design-mcp"]` (the installer does this for you).
101
+
102
+ </details>
103
+
104
+ ## Tools
105
+
106
+ ### Vision tools
107
+ These look at an image. They run in [host or API-key mode](#two-modes).
108
+
109
+ | Tool | What it does |
110
+ |---|---|
111
+ | `analyze_design` | Image or URL to a structured JSON spec: layout, colors, type, spacing, components, style keywords. |
112
+ | `recreate` | Rebuild a design as **HTML, React or Tailwind**, responsive and accessibility-fixed by default. |
113
+ | `reimagine` | New style, new layout. Preset or custom style, **inspiration dial**, **remix** with a second design, up to **3 variations**. |
114
+ | `extract_tokens` | Pull design tokens and export as **CSS variables, Tailwind config, W3C JSON or Figma (Tokens Studio)**. |
115
+ | `critique_design` | Senior-designer critique: scores for hierarchy, spacing, color, type, consistency and usability, with prioritized fixes and quick wins. |
116
+ | `audit_accessibility` | WCAG 2.2 audit with a score, exact contrast ratios, suggested passing colors, tap targets, focus and labels. |
117
+ | `design_to_prompt` | Turn a design into a ready-to-paste prompt for **v0 / Lovable / Bolt**, an **image model**, or a **dev handoff** spec. |
118
+ | `compare_designs` | Compare two designs: what's the same, what differs, a verdict, and the top 5 changes to **match** or **differentiate**. |
119
+
120
+ ### Autonomous audit
121
+
122
+ | Tool | What it does |
123
+ |---|---|
124
+ | `audit_site` | Give it a URL (or CSS) and it runs a complete audit on its own: extracts the design language, lints quality, checks palette contrast, finds color-blind risks, analyzes the type scale, and ends with a **scored list of the top fixes**. |
125
+
126
+ ### Web tools
127
+ These work on live websites.
128
+
129
+ | Tool | What it does |
130
+ |---|---|
131
+ | `capture_url` | Screenshot any page (desktop or mobile, optional full page). Saves the file so you can pass its path to every vision tool. Needs Google Chrome, or `npx playwright-core install chromium`. |
132
+ | `extract_css_tokens` | Read a site's real stylesheets (or pasted CSS) and extract **colors, fonts, sizes, radii, spacing and shadows**. No screenshot, no key. Export as JSON, CSS, Tailwind, W3C or Figma. |
133
+ | `lint_css` | Score CSS on design quality: contrast, removed focus outlines, tiny text, color and font sprawl, off-grid spacing, missing reduced-motion, and drift from your tokens. |
134
+
135
+ ### Security tools (Red Chex)
136
+ Red Chex is the security and privacy side of red-design-mcp. It is **defensive and passive**: `audit_security` sends one normal request to a public page and inspects what any visitor receives, and nothing is ever exploited or probed. Only check sites and code you own or have permission to review. These are not a substitute for a penetration test.
137
+
138
+ | Tool | What it does |
139
+ |---|---|
140
+ | `audit_security` | Grades one public page (A to F): HTTPS and redirects, HSTS, Content-Security-Policy, clickjacking and other headers, cookie flags, mixed content, forms, third-party scripts without Subresource Integrity, leaked credentials in the markup, trackers, and information disclosure, with a fix for each. |
141
+ | `scan_secrets` | Scans text you pass in (config, `.env` examples, front-end bundles) for API keys, tokens, private keys and passwords in connection strings. Findings show line and kind with a **redacted preview**; a full secret is never returned. |
142
+ | `generate_csp` | Builds a Content-Security-Policy from a page's real markup, with **SHA-256 hashes for inline scripts and styles** so you can avoid `'unsafe-inline'`. Starts in report-only mode. |
143
+ | `generate_security_headers` | Writes the recommended security headers as ready-to-paste config for **Netlify, Cloudflare Pages, Vercel, nginx, Apache, Caddy or Express**. Rejects input that could break out of the config file. |
144
+ | `audit_html` | Static audit of markup for accessibility and quality: `lang`, title, viewport zoom, alt text, unlabeled fields, empty buttons and links, heading order, duplicate ids, and more. |
145
+
146
+ ### Deterministic tools
147
+ These never need a model or a key. Same input, same answer, instantly.
148
+
149
+ | Tool | What it does |
150
+ |---|---|
151
+ | `generate_design_system` | **Brand color + mood in, complete starter system out**: color scales, light and dark semantic themes, font pairing, fluid type, spacing, radii, layered shadows, base styles and verified contrast checks. |
152
+ | `generate_component_states` | Accessible **button CSS** from one color: default, hover, active, focus-visible and disabled for primary, secondary, ghost and danger, every state contrast-checked. |
153
+ | `generate_gradient` | Smooth 2-5 color gradients interpolated in **OKLab** (no muddy middles), with a modern `in oklab` version and a check of white or black text across the whole gradient. |
154
+ | `generate_motion_tokens` | Duration and easing tokens (snappy, balanced, relaxed) with an automatic reduced-motion override. |
155
+ | `generate_layout_system` | Responsive container and column grid with Tailwind, Bootstrap or Material breakpoints. |
156
+ | `generate_form_styles` | Accessible **form CSS**: labels, inputs, placeholder, hover, focus, error and disabled states, help text and checkbox accents, every contrast rule verified. |
157
+ | `generate_favicon` | A crisp **SVG monogram favicon** in your brand color with readable letter contrast, plus the HTML tags. |
158
+ | `generate_chart_palette` | **Data-viz colors** that work for everyone: a colorblind-safe categorical set (up to 8), a sequential ramp with steadily falling lightness, or a diverging palette with a neutral midpoint, each verified. |
159
+ | `generate_palette` | One brand color to a full system: **50-950 scale**, harmony accents, tinted neutrals, semantic colors, and the best label color (white or black) on every primary step and every semantic color. |
160
+ | `simulate_colorblind` | Protanopia, deuteranopia, tritanopia and achromatopsia, plus a flag for pairs that **look different normally but collapse** for color-blind users. |
161
+ | `generate_type_scale` | Modular type scale (minor second to golden ratio) with line heights, optionally **fluid** via CSS `clamp()`. |
162
+ | `check_contrast` | Exact WCAG contrast ratios for any color pairs, with the nearest passing fix. |
163
+ | `convert_tokens` | Convert tokens JSON to CSS, Tailwind, W3C or Figma formats. |
164
+ | `generate_dark_theme` | Turn a light theme's tokens into a dark one (`data-theme` and `prefers-color-scheme`) and re-verify contrast, fixing failures. |
165
+ | `contrast_matrix` | Every text-on-background combination across a set of colors at once, with AA/AAA labels and the best accessible combos. |
166
+ | `suggest_font_pairings` | Curated Google Fonts pairings for 12 moods, with `@import` and fallback stacks ready to paste. |
167
+ | `generate_shadows` | Layered elevation shadows (xs to 2xl), soft or crisp, tinted to your color. |
168
+ | `generate_spacing_scale` | A consistent spacing scale from a 4px or 8px base, in rem or px. |
169
+ | `originality_check` | Compare a source and your new design on palette, type, shape and spacing. Get a similarity score and tips to differentiate. |
170
+
171
+ Anywhere a color is expected you can use hex (`#rgb`, `#rrggbb`, `#rrggbbaa`), `rgb()`, `hsl()`, `hwb()`, `oklch()`, `oklab()` or a CSS color name. Translucent colors are rejected with a clear message, because contrast depends on what is behind them.
172
+
173
+ ## Agents
174
+
175
+ red-design-mcp ships agents on three levels, so you pick how much to delegate.
176
+
177
+ ### 1. Workflow prompts (any MCP client)
178
+ Eight ready-made playbooks that tell your AI exactly which tools to run, in order, and how to report. In Claude Code they appear as slash commands such as `/mcp__red__redesign`.
179
+
180
+ | Workflow | What the agent does |
181
+ |---|---|
182
+ | `redesign` | Capture or analyze, critique, reimagine 3 variations, verify accessibility and originality. |
183
+ | `clone-site` | Extract tokens, capture desktop and mobile, recreate as clean code, lint, check originality. |
184
+ | `design-system` | Generate a full system, buttons, forms and gradient, then write the files into your project. |
185
+ | `accessibility-pass` | Audit, list failures with exact fixes, apply them, re-check. |
186
+ | `brand-refresh` | Extract the current look, build a new palette and fonts, compare old vs new. |
187
+ | `design-review` | Senior-designer verdict plus the top 5 prioritized fixes. |
188
+ | `polish-css` | Lint and fix in a loop until the CSS scores 90 or more. |
189
+ | `security-check` | Audit headers, CSP, cookies and leaked secrets, then generate the fixes (report-only CSP first). |
190
+
191
+ ### 2. Specialist agents for every major AI coding tool
192
+
193
+ Every tool has its own agent format, so one command writes each agent in the native format of the tools you use. There are **14 agents**: 13 specialists for specific tasks, plus a **design lead** that handles everything else.
194
+
195
+ ```bash
196
+ npx red-design-mcp agents # install into the tools it detects
197
+ npx red-design-mcp agents --target claude,codex
198
+ npx red-design-mcp agents --all # every supported tool
199
+ npx red-design-mcp agents --project # into this project instead of your home folder
200
+ npx red-design-mcp agents --only red-design-lead,red-css-polisher
201
+ npx red-design-mcp agents --list # see every agent
202
+ ```
203
+
204
+ Existing files are never overwritten unless you pass `--force`, and replaced files are backed up as `.bak`.
205
+
206
+ | Tool | Installed to | Format | How you use them |
207
+ |---|---|---|---|
208
+ | Claude Code | `~/.claude/agents` | Markdown | Delegated automatically, or `/agents` |
209
+ | Cursor | `~/.cursor/agents` | Markdown | Delegated automatically, or `/agent-name` |
210
+ | Codex | `~/.codex/agents` | TOML | Ask by name: "use red-design-reviewer" |
211
+ | Gemini CLI | `~/.gemini/agents` | Markdown | Delegated automatically, or `@agent-name` |
212
+ | GitHub Copilot | `~/.copilot/agents` (or `.github/agents` with `--project`) | `.agent.md` | Pick it in the agent menu |
213
+ | Windsurf, Zed, OpenCode and others | `AGENTS.md` in your project | Managed block | They follow the role table as instructions |
214
+ | Claude Desktop and other chat apps | No agent files | MCP prompts | Use the [workflows](#1-workflow-prompts-any-mcp-client) above |
215
+
216
+ The `AGENTS.md` block is wrapped in markers, so running the command again refreshes it in place and never touches the rest of your file.
217
+
218
+ **Specialists, each for one kind of task**
219
+
220
+ | Agent | Use it for |
221
+ |---|---|
222
+ | `red-design-reviewer` | Reviewing UI changes for visual quality and accessibility, then fixing and re-checking. |
223
+ | `red-accessibility-fixer` | WCAG fixes: contrast, focus states, tap targets, color-blind-safe colors. |
224
+ | `red-design-system-architect` | Tokens, themes and components from a brand color, wired into your stack. |
225
+ | `red-token-extractor` | Pulling tokens out of a site, CSS or screenshot into your project's format. |
226
+ | `red-ui-recreator` | Turning a screenshot or site into code that fits your project's conventions. |
227
+ | `red-brand-refresher` | Restyling or rebranding while keeping the identity recognizable and original. |
228
+ | `red-site-analyst` | Reverse-engineering a live site's design language (read-only, no edits). |
229
+ | `red-css-polisher` | Linting and cleaning a stylesheet until it scores 90 or more. |
230
+ | `red-theme-builder` | Dark mode, gradients, shadows, motion, layout grids and spacing. |
231
+ | `red-component-designer` | Accessible buttons, forms, input states and favicons. |
232
+ | `red-dataviz-designer` | Color-blind-safe chart and graph palettes. |
233
+ | `red-typography-designer` | Font pairings, type scales and text rhythm. |
234
+ | `red-chex` | Security and privacy checks: headers, CSP, cookies, leaked secrets and trackers, then the fixes. |
235
+
236
+ **The design lead, for everything else.** `red-design-lead` is the generalist. It classifies the task and picks the right specialist. For multi-part work it chains them in a sensible order (extract, then system, then components, then accessibility, then originality). If your tool supports subagents it delegates by name. If not, it follows that specialist's process itself.
237
+
238
+ All agents inherit your tools, so they work with `RED_TOOLS=auto` too: they call `find_tools` and `run_tool` when the full tool list is not loaded.
239
+
240
+ ### 3. Autonomous audit
241
+ `audit_site` is an agent in a single tool call: it runs the whole pipeline itself and returns one scored report.
242
+
243
+ ## One call, a whole design system
244
+
245
+ ```text
246
+ Generate a design system for #2563eb, editorial mood, round corners.
247
+ ```
248
+
249
+ You get one paste-ready stylesheet: font `@import`, light and dark themes, color scales, fluid type, spacing, radii, shadows and accessible base styles, plus a verified checklist:
250
+
251
+ ```text
252
+ ✓ Light: text on background: 13.03:1 (needs 4.5:1)
253
+ ✓ Light: button label on primary: 5.17:1 (needs 4.5:1)
254
+ ✓ Dark: muted text on surface: 5.01:1 (needs 4.5:1)
255
+ ✓ Dark: primary on background (UI): 4.67:1 (needs 3:1)
256
+ ```
257
+
258
+ ## Reverse-engineer any website
259
+
260
+ ```text
261
+ Extract the design tokens from https://example.com and lint its CSS.
262
+ ```
263
+
264
+ ```text
265
+ Capture https://example.com on mobile, then recreate it in Tailwind and fix its accessibility problems.
266
+ ```
267
+
268
+ Typical flow: `extract_css_tokens` (exact values from the CSS) → `capture_url` (what it looks like) → `recreate` or `reimagine` → `audit_accessibility` → `originality_check`.
269
+
270
+ > Some sites style themselves with JavaScript, so their CSS is not in the page. For those, `capture_url` plus the vision tools still works.
271
+
272
+ ## Example prompts
273
+
274
+ ```text
275
+ Analyze ./checkout.png and recreate it as a responsive Tailwind page.
276
+
277
+ Reimagine this dashboard as brutalist, dial 80, and give me 3 variations.
278
+
279
+ Take the layout of ./a.png and the mood of ./b.png and build it in React.
280
+
281
+ Audit ./signup.png for accessibility, then fix every failing color in my code.
282
+
283
+ Generate a triadic palette from #e11d48 as a Tailwind config.
284
+
285
+ Do my status colors work for color-blind users? error #d32f2f, success #2e7d32.
286
+
287
+ Create a fluid type scale: 16px base, perfect fourth.
288
+
289
+ Compare the tokens of the original and my version. Is it too similar?
290
+
291
+ Turn ./hero.png into a prompt I can paste into v0.
292
+
293
+ Compare ./mine.png with ./reference.png and tell me how to make them match.
294
+
295
+ Make a dark theme from my tokens and fix any contrast problems.
296
+
297
+ Suggest font pairings for a luxury skincare brand.
298
+
299
+ Check every text and background combination in my brand colors.
300
+
301
+ Give me accessible button styles for #7c3aed with every state.
302
+
303
+ Make a smooth gradient from #e11d48 to #0ea5e9. Can I put white text on it?
304
+
305
+ Lint this CSS and tell me what to fix first.
306
+ ```
307
+
308
+ ## The inspiration dial
309
+
310
+ `reimagine` takes a `dial` from 0 to 100.
311
+
312
+ | Dial | Behavior |
313
+ |---|---|
314
+ | **0-20** | Faithful. Keep layout and structure, refresh colors, type and polish. |
315
+ | **21-50** | Moderate. Keep the hierarchy, rework the visual language and components. |
316
+ | **51-80** | Bold. Keep purpose and content, rethink layout, composition and style. |
317
+ | **81-100** | Wild. Keep only the purpose. Invent a new layout and identity. |
318
+
319
+ Presets: `minimal` · `brutalist` · `glassmorphism` · `neumorphism` · `retro-futuristic` · `editorial` · `playful` · `luxury` · `dark-mode` · `high-contrast`, or describe your own ("90s arcade meets Swiss design").
320
+
321
+ ## Two modes
322
+
323
+ | | **Host mode** (default) | **API mode** |
324
+ |---|---|---|
325
+ | Setup | Nothing | Set one provider key (see below) |
326
+ | Who looks at the image | Your AI tool (Claude Code, Codex, ...) | The server calls the model you configure |
327
+ | Extra cost | None | Your API usage |
328
+ | Best for | Everyday use inside an AI coding tool | Headless pipelines, automation, or when your host tool can't see images |
329
+
330
+ ### Supported providers
331
+
332
+ | Provider | Set | Default model |
333
+ |---|---|---|
334
+ | Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-5-5` |
335
+ | OpenAI | `OPENAI_API_KEY` | `gpt-6.1-sol` |
336
+ | Google Gemini | `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | `gemini-3.6-flash` |
337
+ | Groq | `GROQ_API_KEY` | `qwen/qwen3.8-27b` |
338
+ | OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-5.5` |
339
+ | Any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, Together, Mistral, ...) | `RED_BASE_URL`, plus `RED_MODEL` and `RED_API_KEY` if needed | you choose |
340
+
341
+ The defaults are the current balanced, image-capable models, checked against each provider's documentation on October 31, 2026. Providers rename and retire models often, so set `RED_MODEL` to use a different one (for example a larger model like `claude-opus-5-5`, or an evergreen alias such as `gemini-flash-latest` or `~anthropic/claude-sonnet-latest` on OpenRouter), and run `npx red-design-mcp doctor --check` to confirm your model still exists. For the vision tools the model must accept images. If several keys are set, the first match in the order above wins, or force one with `RED_PROVIDER` (`anthropic`, `openai`, `google`, `groq`, `openrouter` or `custom`). A custom endpoint always wins when `RED_BASE_URL` is set.
342
+
343
+ ```json
344
+ {
345
+ "mcpServers": {
346
+ "red": {
347
+ "command": "npx",
348
+ "args": ["-y", "red-design-mcp"],
349
+ "env": { "GROQ_API_KEY": "your-key" }
350
+ }
351
+ }
352
+ }
353
+ ```
354
+
355
+ Local model with Ollama (no key needed):
356
+
357
+ ```json
358
+ "env": { "RED_BASE_URL": "http://localhost:11434/v1", "RED_MODEL": "llava" }
359
+ ```
360
+
361
+ Claude Code: `claude mcp add --scope user -e GEMINI_API_KEY=your-key red -- npx -y red-design-mcp`
362
+
363
+ | Variable | Purpose |
364
+ |---|---|
365
+ | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY` | Pick a provider. |
366
+ | `RED_PROVIDER` | Force one provider when several keys are set. |
367
+ | `RED_MODEL` | Override the model name. |
368
+ | `RED_BASE_URL`, `RED_API_KEY` | Use any OpenAI-compatible endpoint. |
369
+ | `RED_MAX_TOKENS` | Cap the reply length (default 16000, which leaves room for model thinking). |
370
+ | `RED_TOOLS` | Load fewer tools. See [Choosing tools](#choosing-tools). |
371
+ | `RED_ALLOW_PRIVATE_URLS` | Set to `1` to let tools fetch or capture `localhost` and private-network addresses. See [Security](#security). |
372
+ | `RED_ALLOWED_DIRS` | Optional list of folders images may be read from (separated by `:` on Mac and Linux, `;` on Windows). See [Security](#security). |
373
+
374
+ `npx red-design-mcp doctor` shows which provider and model are active, and `doctor --check` asks the provider whether that model is still available. Requests that hit a rate limit or a temporary server error are retried once automatically.
375
+
376
+ ## Choosing tools
377
+
378
+ red-design-mcp has 36 tools. Loading all of them is the default, but you can control what your AI sees, or let the AI choose for itself. Set `RED_TOOLS` in your client's `env`.
379
+
380
+ | Mode | `RED_TOOLS` | What happens |
381
+ |---|---|---|
382
+ | Everything | unset, or `all` | All 36 tools load directly. |
383
+ | You choose | `core`, `core,web`, `all,-capture_url` | Only the groups or tools you name load. |
384
+ | The AI chooses | `auto` | Only two small tools load: `find_tools` and `run_tool`. The AI describes its task, gets the matching tools with their parameters, and runs them. |
385
+ | Mixed | `core,auto` | The 9 core tools load directly and the AI discovers the rest on demand. |
386
+
387
+ Groups: `core` (the 9 essentials), `vision`, `web`, `color`, `system`, `components`, `quality`, `security`. Combine groups with commas and exclude a tool with a dash.
388
+
389
+ ```json
390
+ {
391
+ "mcpServers": {
392
+ "red": {
393
+ "command": "npx",
394
+ "args": ["-y", "red-design-mcp"],
395
+ "env": { "RED_TOOLS": "auto" }
396
+ }
397
+ }
398
+ }
399
+ ```
400
+
401
+ **How `auto` works**
402
+
403
+ 1. The AI calls `find_tools` with a plain description, such as "check a website's accessibility".
404
+ 2. It gets the best matches with each tool's parameters.
405
+ 3. It calls `run_tool` with the tool name and arguments.
406
+
407
+ This works in every MCP client, because it does not depend on the client refreshing its tool list. The trade-offs are one extra step per task and arguments passed as a JSON object. Matching is keyword based and tuned for this toolset.
408
+
409
+ `npx red-design-mcp doctor` shows how many tools load directly. The agent workflows chain many tools, so they work best with `all` or `auto`.
410
+
411
+ ## How it works
412
+
413
+ <p align="center">
414
+ <img src="./assets/how-it-works.svg" alt="How red-design-mcp works: you share a design with your AI tool, which calls vision or exact tools in the red-design-mcp server and delivers code, tokens and reports." width="100%">
415
+ </p>
416
+
417
+ 1. **You share a design** (an image, a URL or CSS) with your AI tool.
418
+ 2. **Your AI calls the tools it needs** over MCP.
419
+ 3. **Results come back.** Exact tools return their results directly. Vision tools hand the image and instructions back to your AI tool (host mode, the default), or ask a vision model themselves when you set a provider key.
420
+ 4. **You get code, tokens or reports.**
421
+
422
+ Exact tools never call a model: contrast, palettes, scales and audits are computed in code, so results are repeatable.
423
+
424
+ A typical flow chains the tools: `analyze_design` → `extract_tokens` → `reimagine` → `audit_accessibility` → `originality_check`.
425
+
426
+ ## Security
427
+
428
+ red-design-mcp runs on your machine with your permissions, and its tools are driven by an AI that can be misled by text it reads (prompt injection). These guards limit what a misled prompt can do.
429
+
430
+ - **Images only.** Local files are read only if they are real PNG, JPEG, GIF or WebP images, checked by file extension and by file signature, and at most 20 MB. A text file, key or config cannot be read through the image tools, and symlinks are resolved before the check. To confine reads to specific folders, set `RED_ALLOWED_DIRS` (the capture folder is always allowed).
431
+ - **No internal network.** URLs for image downloads, stylesheet reading and screenshots must resolve to public addresses. Loopback, private ranges, link-local addresses (including the `169.254.169.254` cloud metadata service) and reserved ranges are blocked, and every redirect is re-checked. In screenshots, each page request the browser makes is checked as well.
432
+ - **Your own dev server.** To capture `localhost` or a private address, set `RED_ALLOW_PRIVATE_URLS=1`. Link-local and reserved addresses stay blocked even then.
433
+ - **Size limits.** Downloaded pages and stylesheets are capped at 2 MB, and images at 20 MB.
434
+ - **Safe installs.** `install` never rewrites a config it cannot parse (for example one with comments); it stops without changing anything. When it does edit a config it keeps your formatting, writes atomically, and never overwrites an earlier backup.
435
+
436
+ Limits to know about: the address check happens just before each request, so a hostile DNS server that changes its answer between the check and the connection could in theory slip through. If that matters to you, run the server in a container or on a network without access to anything sensitive. Never put API keys in files you commit; keep them in your AI tool's `env` settings.
437
+
438
+ **Offline or restricted networks.** `npx` downloads the package, so it needs access to the npm registry. Run `npm install -g red-design-mcp` once, then `red-design-mcp install --global` so your tools start the installed binary directly.
439
+
440
+ ## Responsible use
441
+
442
+ red-design-mcp is built to learn from **structure and style**, not to copy someone's brand. Recreations use neutral placeholders instead of logos or trademarked artwork, and `originality_check` helps you confirm your result is genuinely your own. It compares tokens only (not layout or content) and is not legal advice.
443
+
444
+ ## Roadmap
445
+
446
+ - [x] Analyze, recreate and reimagine with dial, remix and variations
447
+ - [x] Design tokens to CSS, Tailwind, W3C and Figma (Tokens Studio)
448
+ - [x] WCAG audit, contrast math and color-blindness simulation
449
+ - [x] Palette generator, fluid type scales and originality check
450
+ - [x] One-command installer and API-key-free host mode
451
+ - [x] Multiple model providers: Anthropic, OpenAI, Gemini, Groq, OpenRouter and any OpenAI-compatible endpoint
452
+ - [x] Complete design-system generator with light and dark themes
453
+ - [x] Agent workflows, 14 agents for five AI tools plus AGENTS.md, and an autonomous site audit
454
+ - [x] Red Chex security agent: header and privacy audit, secret scanner, CSP and security-header generators, HTML audit
455
+ - [x] Capture screenshots from a URL and extract tokens from live CSS
456
+ - [x] CSS design linter
457
+ - [ ] Generate real Figma frames through the Figma API
458
+ - [ ] Hosted HTTP/SSE transport for web clients
459
+ - [ ] Visual diff between a design and its recreation
460
+ - [ ] Storybook and component-library export
461
+ - [ ] Multi-page site crawl for full design-system extraction
462
+
463
+ ## Contributing
464
+
465
+ Contributions are welcome. Open an issue to discuss an idea, or send a PR:
466
+
467
+ ```bash
468
+ git clone <your-fork-url> && cd red-design-mcp
469
+ npm install
470
+ npm test # builds, then runs the automated tests
471
+ npm run inspect # opens the MCP Inspector against your build
472
+ ```
473
+
474
+ Please keep new deterministic tools dependency-free and add a short example prompt to this README.
475
+
476
+ ## License
477
+
478
+ [MIT](./LICENSE) © red-design-mcp contributors
479
+
480
+ <div align="center">
481
+
482
+ <sub>Built for designers who code and developers who care how it looks.</sub>
483
+
484
+ </div>
package/dist/a11y.js ADDED
@@ -0,0 +1,110 @@
1
+ import { SUPPORTED_COLOR_FORMATS, parseColor } from "./colorparse.js";
2
+ export const AUDIT_PROMPT = `You are an accessibility specialist (WCAG 2.2). Audit this design and reply with ONLY valid JSON, no fences:
3
+ {
4
+ "pairs": [ { "element": "primary button label", "foreground": "#hex", "background": "#hex", "large_text": false, "kind": "text" } ],
5
+ "issues": [ { "category": "contrast|tap-target|semantics|focus|text-size|color-only|alt-text|motion", "severity": "high|medium|low", "description": "", "fix": "" } ]
6
+ }
7
+ Rules:
8
+ - List every distinct foreground/background color pair (body text, headings, buttons, links, placeholders, icons, borders of inputs).
9
+ - Estimate hex values as precisely as you can.
10
+ - large_text is true only for text of 24px+ or 18.66px+ bold. Use kind "ui" for icons and component borders.
11
+ - Also report non-contrast issues you can see: small tap targets, tiny text, color-only meaning, missing labels or alt text, weak focus cues.`;
12
+ export { parseColor, SUPPORTED_COLOR_FORMATS } from "./colorparse.js";
13
+ /**
14
+ * Parse any supported opaque color (hex, rgb(), hsl(), hwb(), oklch(), oklab() or a CSS name).
15
+ * Kept under its original name. Translucent colors return null because contrast depends on the background.
16
+ */
17
+ export function hexToRgb(input) {
18
+ const c = parseColor(input);
19
+ return c && c.alpha >= 1 ? c.rgb : null;
20
+ }
21
+ /** Like hexToRgb but explains what went wrong. */
22
+ export function requireColor(input, label) {
23
+ const c = parseColor(input);
24
+ if (!c)
25
+ throw new Error(`"${input}" (${label}) is not a color I can read. Use ${SUPPORTED_COLOR_FORMATS}.`);
26
+ if (c.alpha < 1)
27
+ throw new Error(`"${input}" (${label}) is translucent, so its contrast depends on what is behind it. Pass the final opaque color instead.`);
28
+ return c.rgb;
29
+ }
30
+ function toHex(rgb) {
31
+ return "#" + rgb.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
32
+ }
33
+ function lin(c) {
34
+ const s = c / 255;
35
+ return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
36
+ }
37
+ export function luminance(rgb) {
38
+ return 0.2126 * lin(rgb[0]) + 0.7152 * lin(rgb[1]) + 0.0722 * lin(rgb[2]);
39
+ }
40
+ export function contrastRatio(fg, bg) {
41
+ const a = hexToRgb(fg);
42
+ const b = hexToRgb(bg);
43
+ if (!a || !b)
44
+ return null;
45
+ const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
46
+ return (hi + 0.05) / (lo + 0.05);
47
+ }
48
+ /** Nudge the foreground toward black or white until it reaches the required ratio. */
49
+ export function suggestFix(fg, bg, required) {
50
+ const f = hexToRgb(fg);
51
+ const b = hexToRgb(bg);
52
+ if (!f || !b)
53
+ return undefined;
54
+ const target = contrastRatio("#000000", bg) >= contrastRatio("#ffffff", bg) ? [0, 0, 0] : [255, 255, 255];
55
+ for (let t = 0; t <= 1.0001; t += 0.02) {
56
+ const mixed = f.map((v, i) => v + (target[i] - v) * t);
57
+ const hex = toHex(mixed);
58
+ if ((contrastRatio(hex, bg) ?? 0) >= required)
59
+ return hex;
60
+ }
61
+ return toHex(target);
62
+ }
63
+ export function evaluatePairs(pairs) {
64
+ return pairs.map((p) => {
65
+ requireColor(p.foreground, `${p.element} foreground`);
66
+ requireColor(p.background, `${p.element} background`);
67
+ const ratio = contrastRatio(p.foreground, p.background);
68
+ const isUi = p.kind === "ui";
69
+ const required = isUi || p.large_text ? 3 : 4.5;
70
+ const aaa = isUi ? 3 : p.large_text ? 4.5 : 7;
71
+ const passAA = ratio !== null && ratio >= required;
72
+ return {
73
+ ...p,
74
+ ratio,
75
+ required,
76
+ passAA,
77
+ passAAA: ratio !== null && ratio >= aaa,
78
+ suggestion: !passAA && ratio !== null ? suggestFix(p.foreground, p.background, required) : undefined,
79
+ };
80
+ });
81
+ }
82
+ export function extractJson(raw) {
83
+ const cleaned = raw.replace(/```json|```/g, "").trim();
84
+ const start = cleaned.indexOf("{");
85
+ const end = cleaned.lastIndexOf("}");
86
+ if (start === -1 || end === -1)
87
+ throw new Error("Model did not return JSON.");
88
+ return JSON.parse(cleaned.slice(start, end + 1));
89
+ }
90
+ export function formatReport(results, issues = []) {
91
+ const failing = results.filter((r) => !r.passAA).length;
92
+ let score = 100 - Math.min(40, failing * 8);
93
+ for (const i of issues)
94
+ score -= i.severity === "high" ? 10 : i.severity === "medium" ? 5 : 2;
95
+ score = Math.max(0, score);
96
+ const lines = [`## Accessibility report`, `Score: ${score}/100 (${failing} of ${results.length} color pairs fail WCAG AA)`, ""];
97
+ if (results.length) {
98
+ lines.push("| Element | Colors | Ratio | Needs | AA | Fix |", "|---|---|---|---|---|---|");
99
+ for (const r of results) {
100
+ lines.push(`| ${r.element} | ${r.foreground} on ${r.background} | ${r.ratio ? r.ratio.toFixed(2) : "?"} | ${r.required}:1 | ${r.passAA ? "pass" : "FAIL"} | ${r.suggestion ? `use ${r.suggestion}` : "-"} |`);
101
+ }
102
+ lines.push("");
103
+ }
104
+ if (issues.length) {
105
+ lines.push("### Other issues");
106
+ for (const i of issues)
107
+ lines.push(`- [${i.severity ?? "info"}] ${i.category ?? "general"}: ${i.description ?? ""}${i.fix ? ` Fix: ${i.fix}` : ""}`);
108
+ }
109
+ return lines.join("\n");
110
+ }