MCP Apps 主题系统详解明暗模式自适应 CSS 变量完全参考【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps如果你正在开发运行在 AI 聊天机器人里的MCP Apps界面主题系统是你绕不开的一课用户切换到深色模式时你的应用必须立刻跟着变暗且无需重新加载页面。MCP Apps 协议通过一套明暗模式自适应 CSS 变量如--color-background-primary、light-dark()函数和data-theme属性让宿主应用Host把自己的配色、字体、字号下发给嵌入的 App实现无缝的明暗模式切换。为什么 MCP Apps 需要一套主题系统MCP App 通常以沙箱 iframe的形式嵌入到宿主应用如 Claude 等 AI 客户端的对话流中。你的 App 不是独立网站而是住在别人家里——所以配色不能自己说了算宿主的品牌色、明暗偏好必须由 App 跟随明暗模式要实时切换用户在聊天窗口一键切深色你的 UI 毫秒级响应字体字号要对齐宿主有自己的字体体系App 复用后视觉才统一。MCP Apps 协议的解法是宿主把主题令牌Theme Tokens打包成一个 CSS 变量对象通过 Host Context 传给 AppApp 把这些变量写到根元素上CSS 里用var()引用即可。主题数据流从宿主到你的 App整个机制的核心类型定义在 src/spec.types.ts 中export type McpUiTheme light | dark;主题相关的三类数据都携带在McpUiHostContext宿主上下文里见 src/spec.types.ts字段类型作用themelight \| dark宿主当前的明暗偏好styles.variablesMcpUiStyles一组 CSS 变量颜色、字体、圆角、阴影styles.css.fontsstringfont-face/import字体 CSS数据流可以概括为一条链路宿主偏好变化时比如用户切换深色模式SDK 会触发hostcontextchanged事件你的 App 重新应用一遍即可——无刷新、毫秒级。快速上手3 个函数搞定明暗模式自适应SDK 在 src/styles.ts 中提供了 3 个开箱即用的函数覆盖了 90% 的主题需求一键设置当前明暗主题applyDocumentTheme(dark)会同时做两件事src/styles.ts给html设置data-themedark属性 → 你的 CSS 可以用[data-themedark]选择器设置color-scheme属性 →light-dark()函数和原生控件滚动条、下拉框自动适配。getDocumentTheme()则负责读取当前主题且兼容 Tailwind 的classdark约定src/styles.ts。一键注入宿主 CSS 变量applyHostStyleVariables(ctx.styles.variables)把宿主下发的每个变量逐个写到根元素上src/styles.ts。之后你的样式表就能这样写body { background-color: var(--color-background-primary); color: var(--color-text-primary); } .card { border: 1px solid var(--color-border-primary); border-radius: var(--border-radius-md); box-shadow: var(--shadow-sm); }一键加载宿主字体applyHostFonts(css)把宿主提供的字体 CSS 注入为style标签且保证只注入一次src/styles.ts。完整的连接后应用 变化时重新应用写法可直接参考官方模式文档 docs/patterns.mdfunction applyHostContext(ctx: McpUiHostContext) { if (ctx.theme) applyDocumentTheme(ctx.theme); if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.styles?.variables ?? ctx.styles.variables); if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts); } app.onhostcontextchanged applyHostContext; app.connect().then(() { const ctx app.getHostContext(); if (ctx) applyHostContext(ctx); });CSS 变量完整清单颜色、字体、圆角、阴影协议为宿主可下发的变量定义了完整清单McpUiStyleVariableKeysrc/spec.types.ts所有变量均为可选——宿主可以只下发子集。分类速查如下颜色类共 5 组语义色分组变量前缀典型成员用途背景色--color-background-*primary / secondary / tertiary / inverse / ghost / info / danger / success / warning / disabled页面、卡片、状态提示背景文本色--color-text-*同上正文、辅助文字、状态文字边框色--color-border-*同上分割线、卡片描边聚焦环--color-ring-*primary / inverse / info / danger…输入框 focus 光圈状态语义info / danger / success / warning各分组内均含提示、报错、成功、警告字体与排版类变量示例值说明--font-sans/--font-monosystem-ui, sans-serif正文字体 / 等宽字体族--font-weight-normal ~ bold400 / 500 / 600 / 700四级字重--font-text-{xs,sm,md,lg}-size0.75rem ~ 1.125rem正文四档字号--font-heading-{xs ~ 3xl}-size0.75rem ~ 2.25rem标题七档字号--font-*-line-height1.1 ~ 1.5对应字号的行高尺寸与效果类变量说明--border-radius-{xs,sm,md,lg,xl,full}2px → 9999px 六级圆角--border-width-regular常规边框宽度1px--shadow-{hairline,sm,md,lg}从发丝线阴影到大投影官方示例中的完整取值可参考 examples/basic-host/src/host-styles.ts。明暗模式自适应的三种写法由浅入深写法一data-theme属性选择器最直白的方式自己为每个颜色写两套[data-themelight] { --bg-color: #ffffff; } [data-themedark] { --bg-color: #1a1a1a; } body { background: var(--bg-color); }适合变量少、需要精确控制每个色值的场景。写法二light-dark()函数推荐现代浏览器的 CSS 函数一份变量同时声明亮色和暗色值浏览器根据color-scheme自动选边。SDK 的applyDocumentTheme正是为此服务——它同时设置了color-scheme让light-dark()立即生效。官方宿主示例就是这样定义全部配色的examples/basic-host/src/host-styles.ts--color-background-primary: light-dark(#ffffff, #1a1a1a); /* 亮色值, 暗色值 */ --color-text-primary: light-dark(#1f2937, #f3f4f6); --color-ring-danger: light-dark(#dc2626, #ef4444);这是 MCP Apps 推荐的声明式方案宿主只需一份变量表就能同时覆盖明暗两套 UI。写法三JS 监听主题变化做条件渲染当某些逻辑而不只是 CSS依赖主题时用 React HookuseDocumentTheme()即可响应式拿到light | dark它内部用MutationObserver监听根元素的data-theme属性变化主题一变组件自动重渲染src/react/useDocumentTheme.ts。function ThemedButton() { const theme useDocumentTheme(); return button style{{ background: theme dark ? #333 : #fff }}点击我/button; }React 项目一个 Hook 全自动应用主题如果你用 React 写 MCP Appsrc/react/useHostStyles.ts 提供了三档 HookHook职责useHostStyleVariables应用styles.variablestheme含color-scheme保证light-dark()生效useHostFonts应用styles.css.fonts字体 CSSuseHostStyles上面两者的合体通常只需这一个function MyApp() { const { app } useApp({ appInfo: { name: MyApp, version: 1.0.0 }, capabilities: {}, }); // 一个 Hook变量 主题 字体全部自动应用 useHostStyles(app, app?.getHostContext()); return ( div style{{ background: var(--color-background-primary) }} 跟随宿主主题明暗秒切换 /div ); }两个细节帮你避坑传第二个参数app?.getHostContext()连接完成时的初始主题/变量会在挂载瞬间就应用避免白屏闪烁一帧亮色再变暗Hook 同时监听hostcontextchanged事件宿主后续切主题时自动重新应用卸载时自动解绑。配套示例src/react/useHostStyles.examples.tsx、src/react/useDocumentTheme.examples.tsx。宿主视角如何为 App 提供主题如果你是写宿主应用Host而非 App主题管理同样有现成参考——官方 basic-host 示例的 examples/basic-host/src/theme.ts 实现了一个迷你主题管理器初始化用window.matchMedia((prefers-color-scheme: dark))读取系统明暗偏好作为初始值应用document.documentElement.setAttribute(data-theme, theme)colorScheme theme响应系统切换监听prefers-color-scheme的change事件自动跟随操作系统通知 App主题变化后经 Host Context 下发触发 App 侧的hostcontextchanged。再搭配一份light-dark()变量表examples/basic-host/src/host-styles.ts宿主与 App 就完成了双向适配。最佳实践清单✅优先使用宿主下发的变量var(--color-*)而不是硬编码色值宿主没下发的变量再写默认值兜底var(--font-sans, system-ui, sans-serif)✅声明式双主题用light-dark()它比手写两套[data-theme]选择器更省一半代码✅记得设置color-schemeSDK 已帮你做否则原生滚动条、表单控件在暗色下会是刺眼的白色✅React 项目直接用useHostStyles(app, app?.getHostContext())别手动管理addEventListener/removeEventListener⚠️所有变量都是可选的Recordkey, string | undefined写 CSS 时给var()提供 fallback⚠️ 主题只可能是light | dark二值协议未定义第三态不要依赖跟随系统这种中间值。总结MCP Apps 的主题系统 McpUiTheme二值主题 语义化 CSS 变量表 light-dark()自适应宿主通过McpUiHostContext下发theme与styles.variablesApp 用 src/styles.ts 三个函数React 用useHostStyles把它们落到根元素你的 CSS 全部引用var(--color-xxx)明暗切换自动完成、零刷新。想继续深入建议按顺序阅读协议规范 specification/2026-01-26/apps.mdx、模式手册 docs/patterns.md、可运行示例 examples/basic-server-react/ 与 examples/basic-host/。【免费下载链接】ext-appsOfficial repo for spec SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考