BEPs 应用主题化设计指南：BAML 反馈应用（app-beps）的语义 Token 与暗色模式体系

编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载导读本文基于 THEMING.md 系统讲解 BAML Enhancement Proposals 反馈应用typescript2/app-beps的设计系统包括单一事实来源single source of truth的语义色彩 Token、Shiki 双主题语法高亮、Tailwind CSS v4 主题扩展以及基于localStorage的暗色模式切换机制。阅读后你将掌握该应用的换肤原理并能直接沿用其规范为组件新增主题能力或二次开发设计系统。设计原则为什么用语义 Token 而不是硬编码颜色BEPs 应用的主题体系建立在三条核心原则上详见 THEMING.md单一事实来源所有颜色只定义在 globals.css 的 CSS 自定义属性中组件不得自行定义色值语义化命名代码中一律使用muted、foreground、code-bg等语义名而非gray-900这类原始色名这样切换亮/暗主题时组件无需任何改动可访问性暗色模式使用更高对比度的取值尤其是代码区块保证可读性。这套体系在 globals.css 中由三部分构成:root亮色与.dark暗色两套 CSS 变量加上theme inline块将变量映射为 Tailwind 主题色。主题变量采用hsl分量格式如222.2 84% 4.9%由theme inline中的hsl(var(--background))组合成最终颜色既保留了 HSL 的可调性又能在custom-variant dark配合下通过.dark类切换。颜色 Token 全表与组件用法THEMING.md 给出了核心 Token 的语义对照表以下结合 globals.css 中的真实取值完整展开TokenLight实际值Dark实际值Use语义用途background0 0% 100%纯白222.2 14% 4%略暖深色页面背景、主体表面foreground222.2 84% 4.9%210 40% 98%高对比亮色正文文字card0 0% 100%222.2 14% 6%抬升的深色卡片、弹层、浮层card-foreground222.2 84% 4.9%210 40% 98%卡片内文字popover/popover-foreground同 card同 card弹出层及其文字primary222.2 47.4% 11.2%深色210 40% 98%亮色按钮、链接、强调primary-foreground210 40% 98%222.2 47% 11.2%主色之上的文字secondary/secondary-foreground210 40% 96.1%217.2 32.6% 17.5%次要表面muted210 40% 96.1%浅灰217.2 32.6% 17.5%深灰次级表面、代码工具条muted-foreground215.4 16.3% 46.9%灰文字215 20% 75%更亮的灰次要文字、说明文字accent/accent-foreground同 secondary同 secondary强调背景destructive0 84.2% 60.2%0 62.8% 30.6%危险操作border214.3 31.8% 91.4%217.2 32.6% 17.5%边框input/ring同 border / 前景色同 border /215 20% 75%输入框边框 / 焦点环code-bg210 40% 96.1%222.2 14% 9%代码块背景code-fg222.2 84% 4.9%210 40% 95%代码块文字code-border214.3 31.8% 91.4%217.2 32.6% 22%代码块边框注意暗色模式下code-bg为222.2 14% 9%、code-fg为210 40% 95%比普通muted表面更深、文字更亮正是文档强调的暗色模式更高对比度可访问性设计。组件中的推荐写法THEMING.md 明确要求组件优先使用语义 Token// 推荐语义 Token div classNamebg-card text-card-foreground border border-border / code classNamebg-code-bg text-code-fg border border-code-border / // 避免硬编码颜色 div classNamebg-white dark:bg-gray-900 / // 应改用 bg-card div classNamebg-gray-50 dark:bg-gray-800 / // 应改用 bg-muted在仓库中这套规范已被广泛执行例如 users/page.tsx 用bg-cardborder渲染用户卡片、用bg-muted渲染头像占位profile/page.tsx 同样使用bg-mutedtext-muted-foreground。全局还统一了默认边框色——globals.css 中的* { border-color: var(--color-border); }让未显式指定颜色的边框自动跟随主题。代码块体系Shiki 双主题高亮与语义 Token 回退Shiki 双主题输出THEMING.md 规定语法高亮统一走 Shiki配置位于 shiki-themes.tsexport const SHIKI_THEMES { light: github-light, dark: github-dark-high-contrast, // 对比度高于默认 github-dark } as const;暗色模式刻意选择github-dark-high-contrast高对比变体以保证可读性。Shiki 会输出同时包含两套配色--shiki-dark-*变量的 HTML由 globals.css 中的.dark .shiki规则接管当html元素挂上.dark类时强制切换到暗色变量。实际渲染由 shiki-code-block.tsx 完成客户端调用codeToHtml(code, { lang, themes: SHIKI_THEMES })生成双主题 HTML并通过dangerouslySetInnerHTML注入组件还内置了语言别名映射如py → python、baml → typescript、行号注入data-line.line-number以及一键复制按钮。值得注意的两点实现细节加载/失败回退高亮过程中先渲染占位态若codeToHtml抛错则回退为转义后的纯文本precode两种回退都复用code-bg/code-fg/code-border语义 Tokenshiki-code-block.tsx保证即使高亮失败代码块依然跟随主题字体对齐为改善 Unicode 图表的对齐.bep-shiki-code设置了从--font-geist-mono到DejaVu Sans Mono、Noto Sans Mono、Liberation Mono再到 Menlo/Consolas/Monaco 的完整等宽字体回退链并显式关闭连字globals.css。非 Shiki 代码的语义 Token对于行内代码、ProseMirror 编辑器内容、回退pre等不经过 Shiki 的场景文档要求同样使用语义 Tokencode classNamebg-code-bg text-code-fg border border-code-border / pre classNamebg-code-bg text-code-fg /这一约定在 globals.css 的.ProseMirror样式中落地pre与code分别使用hsl(var(--code-bg))背景与--font-geist-mono等宽字体且嵌套的pre code会去除自身背景避免双重填充。MDX 编辑器CodeMirror的暗色适配由于 MDX 编辑器的 CodeMirror 默认是亮色主题globals.css 提供了成体系的暗色覆盖编辑区、滚动区、行号槽gutters全部改用code-bg/code-fg/code-border选区、光标、当前行高亮、工具栏与语言选择器也同步替换并显式覆盖 CodeMirror 内部的--basePageBg/--baseBase/--baseText变量确保编辑器在暗色下不再白屏刺眼。扩展主题新增 Token 的标准三步流程THEMING.md 给出的扩展流程可直接套用在 globals.css 的:root和.dark中分别添加新变量在theme inline块中注册为 Tailwind 主题色通过bg-token、text-token等工具类使用。文档示例:root { --custom: 200 50% 50%; } .dark { --custom: 200 50% 60%; } theme inline { --color-custom: hsl(var(--custom)); }该示例与现有--code-bg等的定义方式完全一致注册后即可直接写bg-custom。仓库当前版本基于 Tailwind CSS v4见 package.json 中tailwindcss: ^4与tailwindcss/postcss: ^4theme inline正是 v4 将运行时 CSS 变量映射为主题色工具类的推荐写法配合custom-variant dark (:is(.dark *))globals.cssdark:前缀只需.dark祖先即可生效无需依赖prefers-color-scheme。theme inline中还注册了基于--radius: 0.5rem派生的radius-sm/md/lg/xl以及 Geist 字体变量--font-sans/--font-mono说明同一机制也可用于扩展圆角与字体体系。暗色模式切换beps-theme 存储键与防闪烁初始化主题偏好存储在localStorage的beps-theme键下取值light、dark、system键名常量定义在 theme.tsexport const THEME_STORAGE_KEY beps-theme;运行时切换逻辑theme-toggle.tsx 实现了完整的切换组件getStoredTheme()读取beps-theme非法值一律回退为systemresolveTheme()在system时通过window.matchMedia((prefers-color-scheme: dark))解析出实际亮/暗applyTheme()在document.documentElement即html上移除并重新添加light/dark类同时设置root.style.colorScheme让原生滚动条、表单控件跟随主题组件还监听系统主题变化事件仅当存储值为system时实时跟随系统切换界面是固定在右下角的Select下拉框Sun/Moon/Monitor三个图标选项按钮本身也使用bg-background/90、backdrop-blur等语义类。首屏防闪烁脚本由于layout.tsx中的ThemeToggle是客户端组件若等到水合后再应用主题首屏会出现亮暗闪烁。因此 layout.tsx 通过next/script的strategybeforeInteractive注入一段内联脚本在 React 水合之前就读取beps-theme非法值回退system解析后直接对html添加light/dark类并设置colorScheme。脚本注释明确要求与theme-toggle.tsx中的逻辑保持同步layout.tsxhtml同时带suppressHydrationWarning以避免服务端与客户端类名不一致的告警。最小改造清单把既有组件迁移到语义主题结合以上机制将任何硬编码颜色的组件迁移到本设计系统只需四步把bg-white/bg-gray-*等替换为bg-card、bg-muted、bg-background把text-gray-*替换为text-foreground、text-muted-foreground、text-card-foreground边框使用border-border代码内容统一code-bg/code-fg/code-border若需新增语义色按上文三步流程在 globals.css 中登记组件端零改动即可获得双主题支持。相关参考文件设计文档 THEMING.md、主题变量与 Shiki 覆盖 globals.css、主题键 theme.ts、Shiki 主题配置 shiki-themes.ts、切换组件 theme-toggle.tsx、首屏初始化 layout.tsx、代码块渲染 shiki-code-block.tsx。赞分享编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载相关推荐BEPS模型生态系统碳交换模拟的技术解析与应用指南BEPS模型生态系统碳交换模拟的技术解析与应用指南 项目概述与核心价值 BEPSBiosphere atmosphere Exchange ProcessJSS主题系统设计构建支持暗黑模式的响应式应用JSS主题系统设计构建支持暗黑模式的响应式应用 JSSJavaScript Style Sheets作为CSS in JS解决方案其主题系统为构建灵活多前端UI组件Win11Debloat暗色模式启用系统级和应用级黑暗主题全攻略Win11Debloat暗色模式启用系统级和应用级黑暗主题全攻略 引言为什么需要系统级暗色模式 你是否还在忍受Windows 11刺眼的白色界面夜间使用桌面应用CLI上一篇FlashAttention突破瓶颈如何实现92%资源利用率的终极指南下一篇为android-reverse-engineering-skill安装Java JDK 17全平台完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考