UISandbox

UISandbox

在浏览器中，尽情调整应用的设计。
带上你的应用，挑选风格，微调，然后带走。
_{你自己的应用会在标签页中 1:1 运行，不会向服务发送任何内容，关闭标签页即可撤销所有更改。}

uisandbox.org · npm：uisandbox-mcp · MCP 注册表 · 讨论区 · MIT

你的应用看起来和其他 AI 帮忙构建的应用没什么两样，你却说不出原因。 UISandbox 会在应用旁边打开那些决定其观感的旋钮：颜色、字体、形状和留白。 转动一个旋钮，使用该值的每个位置都会随之变化，呈现在真实应用中，而不是它的模拟稿里。将你看到的效果保存为设计系统，供 Agent 应用。

打开 uisandbox.org。它会从一个 UI 工具包开始，这样在你带入自己的应用之前，就有内容可以调整。

四个步骤

1. 带上你的应用。 编辑器会以 shadcn/ui 的原始样式打开，展示六种风格，另有七种工具包供你选择（Tailwind CSS、daisyUI、Bootstrap、Material 3、Radix Themes、Mantine、Ant Design），每种都以相同的七屏发票应用为基础进行设计。接着选择 在你自己的应用中试用：在开发服务器旁运行 npx uisandbox-mcp open http://localhost:3000，或者让你的 Agent 打开它；你的运行中应用就会实时显示，包括所有屏幕和热重载。没有终端？将 把此屏幕带上 拖到书签栏，然后在浏览器显示的任意屏幕上点击它（例如暂存环境、登录后页面、Lovable 或 v0 预览），也可以导入 zip、文件夹或公开代码仓库。如果你愿意，在工具包上调整的效果也会一并带过来。
2. 挑选风格。 点击屏幕上的 6，即可并排查看六种风格：Classic、Compact、Soft、Sharp、Airy 和 Bold。它们在圆角、间距、层次感和字体上各不相同，但颜色保持不变，这样你比较的是样式，而非配色。将其中一种全尺寸打开，然后选择 选用此风格。这六种风格也列在预设列表中。
3. 微调。 先调整颜色、字体、形状和留白；文字大小、行高、字间距、字重、边框宽度、立体感、动效、灰色调等选项则位于“更多”中。每个旋钮的中心都会显示 ×1 = 与代码中的设置一致。切换深色模式时，会使用你自己的钩子。按住 Space 键即可查看原始效果。
4. 带走成果。 复制给你的 AI 会将设计系统及其应用方法整合成一段内容，供 Claude Code、Cursor、Codex、Lovable 或 v0 使用。在工具包上操作时，导出的 zip 会在你的代码仓库中包含 DESIGN.md、theme.css 和 SKILL.md，并使用该工具包自己的变量名。在你自己的应用上操作时，可以就地修改你的文件，也可以导出 CSS、Tailwind、shadcn、Swift 和 Android 的设计令牌。运行 MCP 服务后，发送给你的 Agent 会直接将结果交给它。

它还会指出屏幕上有哪些典型的 AI 通用风格特征（例如到处使用 Inter 或 Geist、品牌色为靛蓝、用渐变作装饰），这些特征是从页面中测量得出的，并说明哪些可以通过旋钮修正。

通过链接打开

在 uisandbox.org/?load= 后接公开的 GitHub 或 GitLab 仓库 URL，或允许 CORS 的 .zip 直链，即可直接在沙盒中打开：

https://uisandbox.org/?load=https://github.com/edwardtufte/tufte-css
https://uisandbox.org/?load=https://example.com/dist.zip

仓库 URL 会通过本站的仓库路由处理（GitHub 和 GitLab 不会为存档发送 CORS）；.zip URL 则由浏览器直接获取。无论哪种方式，存档都会在标签页中读取，就像拖入的存档一样。

这是你的应用，不是它的预览

CSS 中的每个颜色、圆角、字体、尺寸、间距、行高、字距、字重、边框宽度、时长、渐变角度和阴影字面值，都会变成一个保存相同值的变量，因此页面渲染效果完全不变。 运行时样式也包括在内：由 JavaScript 设置的 style=""、框架追加的 <style>、styled-components、Emotion、Lit 和 Ant 的 cssinjs 中的 insertRule 和 replaceSync、通过同源代理加载的 CDN 样式表，以及 Storybook 等嵌套的同源框架。

如何自行检查

• 检查 1:1 会并排加载未经改动的页面和令牌化后的页面，并比较每个元素的计算样式，也包括 shadow root 和嵌套框架。没有差异，或者明确指出差异所在。
• 覆盖率计量器位于舞台底部，会显示旋钮能控制你所见内容的多少，以及哪些内容不受控制：图片、画布、视频。
• 无法提供帮助时会明确告知。 iOS 和 Android 项目、WordPress 主题以及没有构建步骤的源代码，都会在入口处收到清晰提示。
• 恶意存档无法将工具导航到其他位置、注册自己的 service worker 或注销我们的 service worker，也无法通过 zip-slip 路径将文件偷偷带出导出内容。存档确实能访问工具的 DOM，因为这些框架按设计采用同源方式；但它无法从中获取任何有价值的内容：没有服务器、凭据或状态。请阅读 notes/security.md，并将其部署在独立的来源上。

你的文件不会离开浏览器

沙盒背后没有服务器，没有账户、Cookie 或分析功能。文件会在标签页中读取，并由同源上的 service worker 提供给框架；导出也在此完成。唯一的例外是公开仓库 URL，它会通过 uisandbox.org 获取其 zip。不会存储任何内容。

从终端或 Agent 使用

npx uisandbox-mcp open                       # inside your project: finds the build, opens the sandbox
npx uisandbox-mcp open http://localhost:3000 # your running dev server, live, hot reload included

同一引擎也以 MCP 服务的形式运行（mcp/README.md）：load 一个构建产物、zip 或运行中的开发服务，在用户的浏览器中open真实沙盒，使用 wait_for_send 等待用户转动旋钮，使用 set 设置旋钮，使用 export 导出任意格式，使用 verify 执行 1:1 检查，并截取screenshot。使用 npx -y uisandbox-mcp 将它添加到任意 MCP 客户端。

Claude Code 插件（技能和服务合二为一）： /plugin marketplace add Ideelab/uisandbox，然后运行 /plugin install uisandbox@uisandbox， 再说 “在 UISandbox 中打开这个应用”。单独的技能见 skills/uisandbox/SKILL.md。

运行

pnpm install
pnpm dev        # http://localhost:5190
pnpm test       # vitest, node:test for the audit and the kit engine
pnpm build      # dist/: static; public/_headers rides along
pnpm holdouts   # every fixture zip through the real app in headless Chromium (below)

http://localhost:5190/?load=<zip-url> 可通过 URL 加载 zip（同源或启用 CORS）。

使用真实构建产物测试

pnpm holdouts 会让 fixtures/ 中的每个存档（来自公开仓库的真实构建产物，已加入 gitignore；notes/decisions.md 说明了各自的来源）通过应用执行加载、检查 1:1、覆盖率和宿主检查。判定结果会与 scripts/holdouts.expect.json 比对；预期为 ok 的 fixture 若未通过，整个运行就会失败。可使用 --only <name>、--record、--base <url>。

pnpm kits:build 会从每个 kit 自身的包构建八个 kit 入口， pnpm kits:gates 会检查它们的检测、导出和实时桥接。

工作原理

src/
  sandbox/
    rewrite.ts     their CSS and HTML: literals replaced by var(--us-vN), byte-preserving
    table.ts       the substitution sheet: one entry per (kind, value), with its sites
    mapping.ts     knob to their values, RELATIVE to the baseline (identity at rest)
    baseline.ts    the knobs on the stand of THEIR code
    directions.ts  the six looks of Pick a look and Preset
    tells.ts       the AI tells, measured on the screen
    verify.ts      the 1:1 check: raw against identity, computed styles per element
    coverage.ts    the reach meter
    live.ts        runtime style="" and <style> get the same rewrite
    scheme.ts      their dark mode: the hooks in their CSS, switched
  kits/engine/     the kit doors and the design system + skill export, per kit
  public/sw.js     serves a sandbox document's URLs from the page; /__ext/ proxies CDN CSS
  app/ panel/ tokens/ export/ state/ audit/
notes/             decisions (numbered), traps, lessons, security, roadmap

部署

一个源站，一个 Cloudflare Worker（worker/index.mjs、wrangler.jsonc）：从 dist/ 提供静态资源，为 ?load= 提供 SPA 回退，将 http 重定向到 https、将 www 重定向到裸域，以及通过 /__repo/ 路由获取公开代码仓库的 zip 文件（不存储文件、仅允许同源调用方、设有速率限制）。public/_headers 会确保 sw.js 不被缓存，并设置安全标头。部署命令为 pnpm build && npx wrangler deploy。源站上不要放置其他内容：沙盒框架有意采用同源设计。

贡献

你能提供的最有用的内容，是一个无法正常工作的构建版本。请参阅 CONTRIBUTING.md，了解对重写器的修改必须通过的 1:1 门槛，以及如何针对真实构建运行测试。

作者

我是 Alexander Kaan，致力于为用户界面构建开源工具。UISandbox 源自我此前制作的设计系统生成器：我可以把一套完成的工具包交给别人，却无法向他们展示自己的应用在其中会是什么样子。这个项目补上了另一半。

我一路上的每个决定，以及踩过的每个坑，都记录在 notes/decisions.md 中，包括那些后来不得不撤销的决定。 欢迎提交问题和拉取请求。

---

由 Alexander Kaan 在 Ideelab 制作 · MIT