Basecoat UI MCP

Basecoat UI MCP

适用于 Basecoat UI 的离线 Model Context Protocol 服务（呈现 shadcn/ui 风格，无需打包或依赖 React）。
为 Astro、Next.js、HTML 和 Tailwind CSS 4 精选模板、宏布局、节奏令牌和静态验证。

该服务为 AI 编码 Agent 提供确定性的离线注册表，无需客户端抓取文档。它通过本地 stdio 运行，运行时网络请求为零，响应大小限制为 < 2 KB，并提供有界的词法／启发式静态源代码验证。宿主应用仍负责渲染、数据访问、身份验证、会话、凭据、OAuth、验证码及其他运行时行为。

安装

需要 Node.js 22.14.0 或更高版本。

按客户端快速开始

Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "${workspaceFolder}"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}

Claude Code（CLI）

claude mcp add basecoat-ui -- npx -y @intellmedia/basecoat-ui-mcp --project-root $(pwd)

通用 npx（无需安装）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}

npm

npm install --global @intellmedia/basecoat-ui-mcp

将该服务添加到 MCP 客户端。为宿主应用使用绝对路径，以确保设计上下文和持久会话归属于预期项目：

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "basecoat-ui-mcp",
      "args": ["--project-root", "/absolute/path/to/your/application"]
    }
  }
}

也可以直接调用编译后的入口：

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "node",
      "args": [
        "/absolute/path/to/node_modules/@intellmedia/basecoat-ui-mcp/dist/server/stdio.js",
        "--project-root",
        "/absolute/path/to/your/application"
      ]
    }
  }
}

发布的包包含预构建的 dist/ 和位于 src/semantics/ 下的不可变语义快照。 服务启动时会读取该快照，不会在已安装的包内写入数据。包契约测试会先进行构建，创建并解压实际的 npm tarball，将解压后的包目录树设为只读，在网络断路器下启动其 dist/server/stdio.js，完成 MCP 初始化和工具列表请求，然后关闭连接。源代码检出内容不包含 dist/。

从源代码构建

git clone https://github.com/zygiu-zygis/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm ci
npm run build
npm start -- --project-root /absolute/path/to/your/application

--project-root 的优先级高于 BASECOAT_PROJECT_ROOT，而后者的优先级高于启动目录。所选目录是宿主项目目录，而不是 MCP 安装目录。该服务仅通过 stdio 提供服务。

项目根目录配置

配置的根目录控制以下两项：

• basecoat://project/context 会从该目录读取 DESIGN.md。
• 持久化宏会话存储在 <project-root>/.basecoat/designer/ 下。
• .basecoat/rhythm.json 是可选的严格覆盖配置。它必须位于项目根目录下真实的 .basecoat 目录中，且为不超过 65,536 UTF-8 字节的常规非符号链接文件，并且解析后的路径必须位于该根目录内；文件缺失或被拒绝时，将保持打包的配置不变。匹配的映射 ID 会原位替换，并保留打包顺序。

只会使用该特定目录。服务不会遍历父目录。请将 .basecoat/ 保留在宿主项目中；如果设计会话属于你的工作流，请备份该目录。MCP 服务绝不会写入宿主应用的源文件。

Basecoat MCP 工具

该服务提供 22 个离线 MCP 工具，分为六个架构层：项目设置与配置、意图驱动的布局编排、主题感知型图表、组件检索、宏观设计图谱和语义状态契约。每个工具结果都是一个有大小限制的 MCP 数据包，最多 1,999 个 UTF-8 字节。较大的结果集使用游标；响应不会在 JSON 中途截断。

完整的 MCP 工具表

工具名称	层级	描述	模式
basecoat_setup_config	设置与配置	生成框架样板、Tailwind CSS 4 导入语句、OKLCH 变量和防闪烁深色模式脚本	只读
basecoat_page_architect	意图快速通道	规划完整的布局脚手架，包含容器网格契约和明确的插槽拓扑	只读
basecoat_compose_stack	意图快速通道	将可组合的组件栈组装为标准外壳（sidebar-01..16、topbar、inset、split），并填充插槽	只读
basecoat_rules_enforcer	意图快速通道	强制执行 Tailwind v4、FSM 状态契约、语义令牌和仪表板规则等技术约束	只读
basecoat_creative_director	意图快速通道	提供 Kanso 极简主义、4px/8px 光学节奏、密度配置、字体阶梯和对比度搭配	只读
basecoat_component_syntax	意图快速通道	提供可直接复制粘贴的 HTML/Astro 组件标记，包含预配置的 FSM 状态变体和内联 SVG 图标	只读
basecoat_list_charts	图表与数据可视化	按关键字搜索，列出并筛选 7 个类别中的 56 个主题感知型图表蓝图	只读
basecoat_get_chart_blueprint	图表与数据可视化	获取使用语义 CSS 令牌（--chart-1..5）的图表 HTML，以及适用于 5 个框架的挂载脚本	只读
basecoat_quality_inspector	质量与审计	审查 HTML/Astro 标记，提供评分（0-100）、字母等级、语法违规、无障碍缺失项和自动修复建议	只读
search_components	组件	根据意图和/或查询，在 62 个精选组件中搜索最多 8 条精简组件摘要	只读
get_component_details	组件	获取适用于 Astro 或 HTML 的精简组件模板、依赖项和组合指南	只读
get_component_html	组件	获取任意精选组件的 HTML 标记模板和依赖项	只读
validate_composition	静态分析	对最多 256 KiB 的标记进行静态检查，查找迁移错误、节奏、FSM 绑定和无障碍问题	只读
validate_markup	静态分析	验证 HTML/Astro 标记的语法、结构、地标顺序和语义约束	只读
search_macro_blocks	宏图谱	按查询、角色、系列或标签，在 84 个区块及其别名中搜索已批准的宏布局区块	只读
get_macro_block	宏图谱	获取已编译宏区块蓝图的某个部分（清单、结构、插槽、端口、规则等）	只读
begin_design	宏图谱	在 .basecoat/designer/ 下创建持久化且经哈希验证的设计会话，并固定配置文件和注册表修订版本	变更（幂等）
get_design_context	宏图谱	读取聚焦的设计会话视图（sessions、overview、decisions、graph、rules、focus、next）	只读
apply_design_patch	宏图谱	使用 expectedRevision 和幂等 operationId 应用原子图变更	变更（幂等）
validate_design	宏图谱	验证草稿或完整设计图，返回诊断总数和分页问题	只读
get_rhythm_rules	语义与令牌	读取生效的语义节奏配置和按系列划分的已批准实用类，支持项目本地覆盖	只读
get_fsm_recipe	语义与状态	读取有限状态机的交互状态、事件、转换、守卫和操作	只读

Intent-Driven Design Layer (Fast Path)

1. basecoat_setup_config - 框架和样式配置生成器。为 6 个目标（astro、vanilla、nextjs、sveltekit、vite、htmx）输出可直接使用的样板代码、8 套美学风格包（vega、nova、maia、lyra、mira、luma、sera、rhea）、完整的 OKLCH @theme inline 代码块，以及同步的 <head> 内联暗色模式脚本。
2. basecoat_page_architect - 按 intent、recipe 或 block 查询配方（src/macros/authoring/recipes/*.json）和宏代码块（src/macros/authoring/blocks/*.json）。提供完整的布局脚手架，包含明确的 data-slot 标记、语义化 HTML 骨架、网格结构和响应式容器。全面支持 5 种仪表盘页面类型：
   • 高管仪表盘（workspace-dashboard、executive-dashboard）- KPI 统计卡片、收入图表和近期活动。
   • 电商概览（ecommerce-overview）- 销售指标、收入分析、热门产品卡片和订单摘要。
   • 分析工作区（analytics-workspace）- 筛选工具栏、时间序列交互式图表和队列分析明细。
   • 数据表详情（workspace-detail、data-table-detail）- 带搜索和筛选功能的分页数据表，以及滑出式检查抽屉。
   • 设置分屏（workspace-settings、settings-split-screen）- 双栏响应式布局，包含垂直分区导航和表单控件。 支持密度控制（compact 适用于高密度企业工具，comfortable 适用于标准界面）。
3. basecoat_compose_stack - 将 7 个类别（shell-stacks、header-stacks、kpi-stacks、chart-stacks、table-stacks、overlay-stacks、form-stacks）中的 45 个预构建组件堆栈动态组合到标准外壳（sidebar-01..sidebar-16、topbar-shell、inset-shell、split-shell）中，并自动填充插槽。
4. basecoat_rules_enforcer - 对 tailwind-v4、fsm-contracts、tokens、semantic-html 和 dashboard-patterns 强制执行严格的技术约束：
   • MET-01：KPI 数字必须使用 text-2xl/text-3xl 和 tabular-nums，并包含语义化趋势指示器。
   • TBL-01：数据表必须使用 <div class="overflow-x-auto"> 包裹，包含带粘滞模糊效果的 <thead class="sticky top-0 bg-background/90 backdrop-blur">，且数字单元格必须右对齐。
   • FRM-01：输入控件必须使用 <div class="field"> 包裹，并关联 <label class="label" for="id">。
   • NAV-01：页眉必须使用紧凑的 h-12 或 h-14（禁止使用过大的 h-16）。
   • TW4-01：拒绝已弃用的 Tailwind v3 工具类（bg-opacity-*、flex-shrink-*、@tailwind 指令）。
   • TOK-01：拒绝任意方括号尺寸（w-[327px]）和硬编码十六进制颜色（#ff0000、bg-[#123456]）。
   • FSM-01：对交互式原语（dialog、dropdown-menu、accordion、tabs）强制执行有限状态机契约。
5. basecoat_creative_director - 提供侘寂极简主义和 Basecoat 设计智能：
   • 密度配置：compact（p-4 gap-4、页眉 h-12、表格 py-2）、standard（p-6 gap-4/gap-6、页眉 h-14、表格 py-3）和 comfortable（p-6 md:p-8、页眉 h-14）。
   • 数学化的 4px/8px 视觉节奏网格和字体阶梯（所有指标和数字表格单元格均使用 tabular-nums）。
   • 通过细微的 1px 卡片环形效果营造层次，且不与 border 工具类冲突。
   • 符合 WCAG 2.1 AA 标准的配色（对比度 >= 4.5:1）和 APCA（$L_c \ge 60$）令牌配对。
6. basecoat_component_syntax - 从 src/registry/components.json 提供可复制粘贴的 HTML 或 Astro 组件标记，包含预配置的 FSM 状态变体（default、active、loading、disabled、open、closed、open/closed）、经过验证的内联 SVG 操作图标（plus、edit、trash、search、chevron-down、check、external-link）和复合组件模式：
   • metric-card（metrics-summary、kpi-card）- 统计卡片，包含使用 tabular-nums 的数字和趋势徽标。
   • data-table（datatable）- 带粘滞表头的表格，使用 overflow-x-auto 包裹，且数字单元格右对齐。
   • sidebar-shell（sidebar-dashboard-shell）- 桌面端粘滞导航，在 md 以下断点处使用响应式飞出菜单。
7. basecoat_quality_inspector - 根据仪表盘审查规则审计 HTML/Astro 组合：table-overflow-wrapper、kpi-metric-tabular-nums、table-numeric-alignment、a11y-focus-ring（标记未搭配焦点可见环的 outline-none）、任意颜色/尺寸违规，以及 WCAG/APCA 对比度配对。返回 score（0-100）、字母 grade（A-F）、结构化问题和可执行的 autoFixSuggestions。

主题感知图表与数据可视化

8. basecoat_list_charts - 在 7 个类别（area、bar、line、pie、radar、radial、tooltip）中发现并筛选 56 个主题感知图表蓝图，支持关键词 search / query、布局占用（layoutFootprint）、requiredTokens 和变体摘要。
9. basecoat_get_chart_blueprint - 获取图表容器 HTML（chart-container、role="img"、无障碍 <table class="sr-only"> 回退，以及包含 bg-background/95 backdrop-blur-sm 的玻璃拟态工具提示标记）、CSS 令牌（var(--chart-1) 至 var(--chart-5)、var(--color-border)、var(--color-muted-foreground)）、客户端 options、layoutFootprint，以及 5 种框架（vanilla、astro、react、vue、svelte）的框架挂载代码，并可选覆盖 themeTokens。接受 chartId 或别名 id（默认值为 area-default）。已直接集成到 dashboard-01 和 svg-area-chart（data-chart-id="area-interactive"）中。通过 node scripts/ingest-shadcn-charts.mjs 确定性生成。

组件工具

• search_components 在 62 个精选组件中最多返回 8 条精简的 {id, name, intent} 摘要，且绝不返回标记。intent 和 query 均为可选；空搜索会返回空列表。
• get_component_details 返回一个 Astro 或 HTML 模板，并附带依赖项和组合指导。对于超大条目会拒绝处理。theme-toggle 会解析为 theme-switcher。
• get_component_html 返回任意精选组件的 HTML 标记模板及依赖项（environment 默认为 html）。
• validate_composition 静态检查最多 256 KiB（262,144 UTF-8 字节）的 HTML 或 Astro 源码，并最多返回 24 个问题（包括 WCAG 2.1 / APCA 令牌对比度、任意尺寸、对话框焦点陷阱和 aria-controls 绑定）。传入 code 或 html，以及可选的 semanticProfile 或 densityProfile（comfortable|compact）。它不会渲染、执行、解析应用模块，也不会认证浏览器运行时的无障碍性。
• validate_markup 根据 Basecoat 指南静态验证 HTML/Astro 源码语法、容器标签、地标顺序和语义约束。

宏工具

宏层是本项目精心设计的、针对项目的组合系统，涵盖 Shell、身份验证流程、数据工作区、插槽、端口、规则和配方。它会编译为固定版本的注册表快照。这些布局契约并非由 shadcn 或 MCP 自动提供。

1. search_macro_blocks - 按查询、角色、系列或标签，在 84 个区块及其别名中查找兼容的蓝图区块。
2. get_macro_block - 读取区块的某个部分，例如 manifest、structure、slots、ports、rules、dependencies 或 provenance。
3. begin_design - 创建持久化设计会话，并固定其配置和注册表修订版本。加载时会对固定的注册表进行哈希验证。
4. get_design_context - 读取会话列表或 overview、graph、rules、focus 和 next 等聚焦视图。
5. apply_design_patch - 使用 expectedRevision 和幂等的 operationId 应用原子图变更。已提交的变更始终会返回成功确认；如果可选载荷过大，可能会省略，并附带 truncated: true。
6. validate_design - 验证草稿或完整设计图，并分页显示诊断信息。

设计会话持久化在 <project-root>/.basecoat/designer/ 下。注册表修订版本以内容寻址；即使软件包快照发生变化，会话仍会继续使用其固定的修订版本。设计快照采用 d:<designId>@<revision> 形式。

精选区块蓝图（84 个区块及其别名，包括已翻译的 shadcn/ui v4 区块）：

• 标准 Shell 和侧边栏：sidebar-01 至 sidebar-16、sidebar-dashboard-shell、sidebar-inset-shell、sidebar-collapsible-icon、sidebar-mobile-flyout、sidebar-nav、topbar-shell、topbar-nav、app-shell、page-header。
• 仪表盘和工作区：dashboard-01 至 dashboard-07、dashboard-workspace、dashboard-main、dashboard-activity、analytics、analytics-workspace、ecommerce-overview、tasks、tasks-table-workspace、mail、mail-workspace。
• 指标和数据表格：metrics-summary、data-table-rich、data-table、data-table-detail-layout、data-workspace、data-bulk-actions、data-filters、data-pager、products、billing、settings。
• 表单和身份验证：login-01 至 login-05、signup-01 至 signup-05、otp-01 至 otp-05、form-field-group、forms、form-section、authentication、auth-sign-in、auth-sign-up、auth-split-screen、auth-recovery、auth-reset。
• 图表和反馈：svg-area-chart、empty-state、error-boundary、newsletter-waitlist、pricing-tiers、segmented-toggle、detail-drawer-panel、product-detail-layout、settings-workspace。

多区块配方（11 个页面配方）：

• workspace-dashboard - 完整的分析仪表盘（KPI 卡片、活动图表、记录表格）。
• ecommerce-overview - 电商运营仪表盘，包含订单指标和产品亮点。
• analytics-workspace - 分析仪表盘，包含时间序列图表和群组视图。
• workspace-settings - 应用 Shell，包含导航、页眉和设置工作区标签页。
• workspace-detail / tasks-table-workspace - 数据表格工作区，带有滑出式详情检查抽屉。
• mail-workspace - 多窗格电子邮件客户端布局，包含收件箱列表和详情视图。
• auth-flow - 登录卡片与注册卡片之间的双向身份验证流程。
• auth-split-flow - 分屏身份验证框架，将登录和注册与主视觉媒体相结合。
• data-records - 记录页面，包含筛选器、表格和分页器。
• marketing-pricing - 三档定价表，搭配新闻简报／候补名单横幅。

语义工具

语义层提供编译后的节奏配置和有限状态机方案：

1. get_rhythm_rules - 按配置和类别筛选条件，访问已批准的间距、字体、表面、边框和布局模式。
2. get_fsm_recipe - 读取 dialog、navigation（collapsible-navigation）、auth-flow 和 tabs 的交互状态、事件、转换、守卫条件和操作。

语义工具使用与宏工具相同的有限分页。每条节奏记录都会将语义令牌 ID 与其已批准的 Tailwind 工具类分开。将工具类放入 class；在设计元数据和 Agent 推理中保留语义 ID。来自 <project-root>/.basecoat/rhythm.json 的项目覆盖会反映在有效内容引用和修订版本中。FSM 方案是结构元数据，而非运行时实现。

端到端示例

仪表盘页面可以按以下顺序进行：

get_design_context(view="sessions")
begin_design(designId="admin", profile="app-default", operationId="begin-admin")
get_rhythm_rules(profile="default", family="density")
search_macro_blocks(q="shell", limit=8)
apply_design_patch(
  designId="admin",
  expectedRevision=0,
  operationId="add-dashboard",
  operations=[{ op: "instantiate_recipe",
               recipe: "workspace-dashboard",
               pagePrefix: "admin" }]
)
get_design_context(view="overview", designId="admin")
get_macro_block(idOrRef="app-shell", section="structure", designId="admin")
get_fsm_recipe(recipe="dialog", section="transitions")

在宿主项目中实现选定的组件叶节点，然后使用 apply_design_patch(record_written) 记录已完成的区域。最后，对生成的 Astro 或 HTML 源码运行 validate_design(mode="complete") 和 validate_composition。发生冲突或重启后，重新读取会话，并使用返回的修订版本和游标。

将 templates/cursor/basecoat-designer.mdc 复制到宿主项目的 .cursor/rules，为 Agent 提供指导。MCP 服务不会写入使用方应用的源文件。

审计或重新设计现有 UI

无需设计会话。读取 basecoat://design/theming 和 basecoat://design/rhythm，对每个要更改的控件调用 get_component_details，然后对渲染后的布局源码（包括 <head> 脚本和 <style>）运行 validate_composition。主题规则：

• theme-strategy-mixed - @media (prefers-color-scheme: dark) 与 .dark 类策略结合使用（深色令牌会泄漏到浅色模式）。
• theme-storage-key - 主题脚本使用非 Basecoat themeMode 的键进行持久化，从而创建第二个解析器，并导致其与 window.basecoat.theme 不一致。

部署前，在操作系统启用深色偏好且 localStorage 为空的情况下，检查浅色和深色截图。

源码适配和离线导入

宏导入器有意采用本地优先策略。它接受已检出或以其他方式保存在本地的 shadcn 风格 registry-item.json、经过审核的映射以及本地依赖锁定文件：

npm run import:blocks -- \
  --item=/path/to/registry-item.json \
  --mapping=/path/to/mapping.json \
  --lock=/path/to/dependency-lock.json \
  --dry-run

此命令不会获取实时 shadcn registry 项目、安装程序包、执行上游代码，也不会发起运行时网络请求。遇到未知、未锁定或明确不受支持的依赖项时，会生成诊断信息，而非猜测。省略的 OAuth、验证码、会话、凭据和其他应用功能会作为待办事项报告。导入器只会生成经过整理的结构块；宿主应用必须实现运行时行为。

映射和由此产生的来源信息明确界定了边界：shadcn 风格源码是输入参考，而布局契约、插槽、端口、规则和方案则是由本项目的宏层整理并拥有的适配内容。它们并非 shadcn 或 MCP 提供的功能。上游刷新是单独的维护者编写操作，绝不会由 MCP 服务执行。

Basecoat MCP 资源

该服务公开 8 个权威 MCP 资源，涵盖三支柱 Skill Vault、核心设计系统契约、多框架集成指南，以及实时宿主项目信息：

完整 MCP 资源表

资源 URI	类别	描述	MIME 类型
basecoat://skills/core	技能库	Basecoat UI 核心设计理念、Kanso 极简主义和基础组件用法	text/markdown
basecoat://skills/dashboard	技能库	全面的仪表板架构、布局模式、页面类型、侧边栏配置和审查清单	text/markdown
basecoat://skills/charts	技能库	适配主题的图表蓝图、CSS 令牌映射（--chart-1..5）、ApexCharts 配置和多框架集成	text/markdown
basecoat://skills/files/*	技能库	动态文件访问资源，可读取 96 个文件的技能库中的单个文档和参考 Markdown 文件	text/markdown
basecoat://design/rhythm	设计系统	内容层级、4px/8px 视觉间距节奏、排版阶梯、密度配置和结构构成规则	text/markdown
basecoat://design/theming	主题与深色模式	Basecoat OKLCH 令牌约定、8 种官方样式包（Vega..Rhea）、基于类的深色模式（themeMode 解析器）和无闪烁引导	text/markdown
basecoat://integration/frameworks	集成指南	生产环境集成指南，涵盖 Astro、Next.js、Express、Vite、Tailwind CSS 4 的设置以及与框架无关的 HTML	text/markdown
basecoat://project/context	项目上下文	按需实时读取宿主项目的 DESIGN.md（限制为 6,000 UTF-8 字节）	application/json

• basecoat://skills/core 提供使用 Basecoat CSS 构建简洁、极简界面的基础指南，包括设计理念、原子化样式原则和组件构建。
• basecoat://skills/dashboard 提供企业级仪表板架构、导航模式、数据展示规范、表单布局和无障碍检查清单。
• basecoat://skills/charts 提供完整指南，介绍如何在 5 种框架中使用纯 Basecoat CSS 颜色令牌（var(--chart-1) 到 var(--chart-5)），构建适配主题的 ApexCharts 和 SVG 数据可视化。
• basecoat://skills/files/* 支持在 96 个文件的技能库（skills/basecoat、skills/basecoat-dashboard、skills/basecoat-charts）中动态查找和检索任意指定的 Markdown 文件。
• basecoat://design/rhythm 提供内容层级、间距、排版、组件系列和结构构成规则。
• basecoat://design/theming 提供 Basecoat 令牌约定、全部 8 种官方样式包（Vega、Nova、Maia、Lyra、Mira、Luma、Sera、Rhea）、通过 window.basecoat.theme（themeMode 键）实现的基于类的深色模式、无闪烁引导，以及表单控件和自动填充的注意事项。重新设置现有 UI 样式或对其进行审查前，请先阅读此资源。
• basecoat://integration/frameworks 提供 Astro、Next.js、Express、Vite、Tailwind CSS 4（包括 @import "basecoat-css/vega"; 等样式包导入）、按需引入 Basecoat JavaScript 以及原生对话框的设置指南。
• basecoat://project/context 按需读取已配置的宿主项目 DESIGN.md。输出上限为 6,000 UTF-8 字节，并会尽可能在换行符或句子边界处截断。符号链接和非普通文件将被拒绝。

推荐流程：

1. 读取节奏和项目上下文资源。
2. 确定内容层级和布局。
3. 搜索摘要，然后仅请求所选组件的详细信息。
4. 连接生产资源时，读取集成资源。
5. 验证最终源码。

最小化 HTML 示例

宿主应用会提供已编译的 Tailwind 和 Basecoat 样式表：

<link rel="stylesheet" href="/assets/basecoat.css">
<button type="button" class="btn" data-variant="default">Save changes</button>

页眉控件组（样式预设选择器 + 主题切换器）

<div class="flex items-center gap-2">
  <select id="style-variant-select" class="select h-8 w-28 text-sm leading-none" aria-label="Style pack">
    <option value="vega">Vega</option>
    <option value="nova">Nova</option>
    <option value="maia">Maia</option>
    <option value="lyra">Lyra</option>
    <option value="mira">Mira</option>
    <option value="luma">Luma</option>
    <option value="sera">Sera</option>
    <option value="rhea">Rhea</option>
  </select>
  <button type="button" aria-label="Toggle dark mode" data-tooltip="Toggle dark mode" data-side="bottom" onclick="window.basecoat.theme.toggle()" class="btn size-8" data-variant="outline" data-size="icon">
    <span class="hidden dark:block" aria-hidden="true"><svg class="lucide lucide-sun size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2m-7.07-2.93 1.41-1.41m11.32-11.32 1.41-1.41M2 12h2m16 0h2m-2.93 7.07-1.41-1.41M6.34 6.34 4.93 4.93"/></svg></span>
    <span class="block dark:hidden" aria-hidden="true"><svg class="lucide lucide-moon size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"/></svg></span>
  </button>
</div>

Basecoat 1.x 使用带有 data-variant 和 data-size 的 btn。交互式组件会列出宿主必须加载的细粒度 JavaScript 模块。

宏驱动的仪表板生成

该 MCP 服务提供了一套完善的宏布局（search_macro_blocks），让已连接的大模型能够开箱即用地按预期组装复杂布局（例如 Shadcn 仪表板）。

• 布局中立性：支持侧边栏架构（sidebar-dashboard-shell、sidebar-inset-shell）和顶部栏架构（topbar-shell、topbar-nav）。
• 严格验证：validate_composition 工具可确保生成的布局符合 Basecoat CSS 主题契约、严格的间距节奏刻度（0、2、4、6、8、12）以及恰当的地标可访问性要求。
• Agent 指引：鼓励大模型使用 search_macro_blocks 查找 shell（布局包装器），并使用 dashboard-main 或 dashboard-workspace 填充 main 容器，从而确保确定性、像素级精准地复刻 Shadcn/ui，且不产生 React 运行时产物。

注册表与排除项

签入的注册表包含 62 个精选组件：涵盖所有 57 个适配为纯 Basecoat CSS（不含 React）的 shadcn/ui New York v4 基元，以及具有明确 FSM 状态契约的 Basecoat 扩展（theme-switcher、segmented-toggle、svg-area-chart、native-select）：

accordion、alert、alert-dialog、aspect-ratio、avatar、badge、breadcrumb、button、button-group、calendar、card、carousel、chart、checkbox、collapsible、combobox、command、context-menu、data-table、date-picker、dialog、drawer、dropdown-menu、empty、field、form、hover-card、input、input-group、input-otp、item、kbd、label、menubar、native-select、navigation-menu、pagination、popover、progress、radio-group、resizable、scroll-area、segmented-toggle、select、separator、sheet、sidebar、skeleton、slider、sonner、spinner、svg-area-chart、switch、table、tabs、textarea、theme-switcher、toast、toggle、toggle-group、tooltip

完整目录统计

• 62 个精选组件：包括全部 57 个 shadcn/ui new-york-v4 原语，以及 Basecoat 扩展；提供经过验证的 HTML/Astro 标记模板、无需打包 React，以及有限状态机（FSM）契约。
• 84 个宏块和别名：涵盖 sidebar-01..16、dashboard-01..07、login-01..05、signup-01..05、otp-01..05、mail、tasks、forms、products、analytics、billing 和 settings 的布局蓝图。
• 11 个页面配方：端到端的多页面布局图（workspace-dashboard、ecommerce-overview、analytics-workspace、workspace-settings、workspace-detail、tasks-table-workspace、mail-workspace、auth-flow、auth-split-flow、data-records、marketing-pricing）。
• 45 个可组合组件栈：涵盖 7 个类别（shell-stacks、header-stacks、kpi-stacks、chart-stacks、table-stacks、overlay-stacks、form-stacks），可将插槽内容填充到规范外壳中。
• 56 个主题感知图表蓝图：涵盖 7 个类别（area、bar、line、pie、radar、radial、tooltip），映射到 CSS 令牌（var(--chart-1) 至 var(--chart-5)），并提供 5 个框架的挂载方案（vanilla、astro、react、vue、svelte）。
• 3 大支柱技能库中的 96 个 Markdown 文件：分布于 skills/basecoat（核心基础和 57 个组件指南）、skills/basecoat-dashboard（仪表板架构、区块模式和审计清单）以及 skills/basecoat-charts（ApexCharts 蓝图和令牌映射）。

维护快照记录了 41 个已发现的上游组件。现在，全部 57 个 shadcn/ui 原语都已精选，并配有模板、依赖项和状态契约。Slider 使用 basecoat-css/range，而非 slider 模块。

运行时不包含网络客户端、远程文档依赖、前端框架运行时、远程媒体分析或随附的宿主资源。生成的模板不得使用 basecoat-css/all；必须显式导入每个控制器。搜索结果不包含标记，新发现的组件绝不会自动晋升，JSON 或 HTML 也绝不会被截断以适应响应预算。

Astro 和静态 HTML 用例

在 Astro 中，使用 Vite 集成资源处理 Tailwind CSS 4、CSS 顺序、选择性控制器导入、原生 <dialog> 接线以及 ClientRouter 钩子。在静态 HTML 中，将列出的已构建控制器文件从 basecoat-css 复制到宿主应用的资源目录，并保持依赖顺序。图表模板需要宿主提供 Chart.js。

维护者只能通过明确指定不可变的提交来源来刷新固定版本的 Basecoat 快照，例如 npm run sync -- --ref <40-character-commit-sha>。 这是唯一使用 HTTPS 的命令。它会在更改注册表之前验证架构、导出项、声明、响应预算、版本方向和原子替换。它不会刷新 shadcn 映射或宏块。

开发与验证

使用 npm ci 安装依赖，然后运行针对性检查：

npm run check
npm pack --dry-run
npm audit --omit=dev

npm run check 会进行类型检查、验证两个已编译快照、构建并运行 Node 测试套件，以及检查分支差异中的空白错误。测试套件还会离线测试打包后的只读 MCP bin。npm pack --dry-run 会检查软件包文件允许列表，但不会保留 tarball。 npm audit --omit=dev 会根据 npm 公告数据库检查生产依赖，因此需要网络访问。维护者可以通过以下方式验证固定版本的 Basecoat 源码：

为提供发布一致性证据，请在每次获准发布前后运行本地例程：

npm run release:check -- --phase=pre-release --write=tmp/release-pre.json
npm run release:check -- --phase=post-release --write=tmp/release-post.json

该例程会根据当前仓库元数据发现各个界面，比较本地权威值，并记录 current、expected、correction、status 和 verification。它会检查软件包标识、服务清单一致性、stdio 传输、已公布的功能、安装元数据，以及克制的可发现性文案。它绝不会发出网络请求或进行外部写入；GitHub、npm、MCP Registry 以及目录／索引修正仍明确属于经批准的手动操作。请勿将徽章、下载量、上游引用或搜索结果摘要视为发布依据。

npm run sync -- --ref <40-character-commit-sha> --check

同步命令是唯一的网络边界。宏编写变更需要运行 npm run compile:blocks；请审查生成的 src/macros/registry.snapshot.json，然后运行 npm run compile:blocks:check。

贡献

1. 从默认分支创建一个范围明确的分支。
2. 使组件模板、宏契约和文档与已检入的源码保持一致。
3. 运行 npm run typecheck、npm run compile:semantics:check、npm run compile:blocks:check 和 npm run test。
4. 软件包内容或元数据发生变更时，运行 npm pack --dry-run。
5. 在拉取请求中说明行为变更、输出限制的影响，以及宿主应用所需的任何工作。

请勿添加 GitHub Actions 工作流。上游注册表刷新和宏编写属于由维护者审核的变更，而非服务启动任务。

故障排查

• 服务已启动，但读取了错误的项目： 设置绝对路径的 --project-root 或 BASECOAT_PROJECT_ROOT。默认回退到进程启动目录。
• 无法使用 DESIGN.md： 在配置的根目录下放置一个普通文件。不会跟随父目录和符号链接。
• 源码检出无法启动： 运行 npm start 前先运行 npm run build。
• 宏结果中包含游标： 使用该游标请求下一页；请勿拼接或解析不完整的 JSON。注册表、设计或有效节奏版本发生变化后，先前的游标会失效。
• 应用确认中包含 truncated: true： 变更已提交；请重新读取上下文或验证工具以获取被省略的详细信息。
• 导入器诊断提及 OAuth、captcha 或不受支持的依赖项： 在宿主应用或经审核的映射中实现或解决相关问题。导入器不会猜测运行时行为。
• 设计补丁发生冲突： 重新读取 get_design_context，使用其当前版本，并发送一个新的唯一 operationId。

有关运行时边界、持久化、数据包限制和同步策略，请参阅 ARCHITECTURE.md。请在 issue tracker 中报告可复现的缺陷。

作者、许可证与上游署名

由 Žygimantas Jasiulionis / Intellmedia 在 MIT License 下创建并维护。

Basecoat UI 是 Ronan Berder 开发的独立 MIT 许可项目。改编的模板和元数据保留了 THIRD_PARTY_NOTICES.md 中完整的 Basecoat 声明。Basecoat 改编了 shadcn/ui 的设计模式；声明保留了该项目的署名。此处未随附任何 Basecoat CSS 或 shadcn 源码。