Claudian 样式体系模块化 CSS、确定性构建与 Obsidian 主题集成规范【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudian本文以 Claudian 的 CSS 风格指南为核心系统讲解该 Obsidian 插件中src/style/目录的模块化组织方式、根styles.css的确定性构建流程、按钮与表单控件的强制基线样式以及与 Obsidian 宿主环境集成时的主题检测、层级和滚动布局陷阱。读完后你可以准确地把新样式模块挂入构建链、按 BEM-lite 规范命名选择器并避免在 Obsidian 宿主环境中出现样式泄漏。样式体系总览按 UI 所有权划分目录风格指南明确规定src/style/包含模块化 CSS最终构建为根目录的styles.css。各目录的职责划分如下区域职责base/变量、容器原语、动画以及全局可见性行为components/可复用的聊天界面如消息、输入框、标签页、导航、历史/会话管理、状态、上下文、引用和工具输出toolbar/输入区和 provider 选项控制组件features/与具名功能工作流耦合的样式如上下文、diff、内联编辑、命令等modals/模态框专属布局settings/共享设置外壳和 provider 设置模块accessibility.css跨功能的可访问性适配index.css完整的模块清单与确定性构建顺序指南给出一条关键决策原则按 UI 所有权选择目录而不是按选择器恰好出现在哪个屏幕上。共享的视觉原语放入components/行为相关behavior-specific的选择器留在其所属的功能目录中。当前 src/style/index.css 实际注册了 40 余个模块从base/variables.css开始依次经过 components、toolbar、features、modals、settings最后以base/visibility.css收尾。架构边界CSS 不是状态源风格指南中的 Boundaries 一节定义了四条硬性边界这也是理解整个样式架构的前提TypeScript 拥有语义与生命周期状态。CSS 可以渲染 class 和 data 属性但不能被当作状态转换的真相源source of truth。功能样式不得把 provider 行为泄漏进共享选择器。provider 变体必须使用由 UI 配置显式提供的 provider class 或 data 属性。对 Obsidian 宿主选择器的覆盖保持窄范围。当 Claudian 容器能够限定作用域时禁止全局重定义宿主 class。根styles.css是生成产物永远不要直接编辑它。第 2 条在源码中可以得到印证src/style/base/variables.css 为每个 provider 定义了独立的品牌色 token如--claudian-brand-claude、--claudian-brand-codex、--claudian-brand-opencode等并通过data-provider属性把别名 token--claudian-brand指向对应 provider 的值.claudian-container[data-providerclaude] { --claudian-brand: var(--claudian-brand-claude); --claudian-brand-rgb: var(--claudian-brand-claude-rgb); }也就是说provider 差异被封装在 CSS 自定义属性层面共享组件只需引用--claudian-brand无需感知具体 provider——这正是provider 变体用显式 data 属性这条边界规则的具体落地方式。构建链styles.css如何被生成构建命令指南的 Build Rules 一节给出了三条规则npm run build:css构建根styles.cssnpm run dev和npm run build都会触发 CSS 构建每一个新模块都必须注册进index.css否则 CSS 构建应当失败。对照 package.json 中的 scripts 可以确认这一链路的实际形态build:css执行node scripts/build-css.mjsdev被定义为npm run build:css node esbuild.config.mjs即每次启动 esbuild 监听前先构建 CSSbuild执行node scripts/build.mjs production该脚本内部同样会先调用 scripts/build-css.mjs 再运行 esbuild 生产构建。构建产物会随插件一起被安装esbuild.config.mjs 中的copyToObsidian插件在构建结束后把main.js、manifest.json和styles.css三个文件复制到OBSIDIAN_VAULT环境变量指向的 vault 下的.obsidian/plugins/claudian目录——这说明根styles.css是插件分发的核心产物之一不要手改生成物的规则由此更加严格。构建脚本的工作机制scripts/build-css.mjs 并非简单地拼接目录而是实现了指南中未注册模块必须让构建失败的强制约束。其核心逻辑解析模块顺序build-css.mjs 的getModuleOrder用正则/^\s*import\s(?:url\()?[]\)?\s*;/gm扫描src/style/index.css按import出现顺序取出模块清单。index.css文件顶部也注释了这一约定CSS module order. scripts/build-css.mjs reads these import lines.。逐模块拼接每个被引入的文件会以注释头模块相对路径包裹后追加到输出最终在文件头部写入/* Claudian Plugin Styles */ /* Built from src/style/ modules */标识并写入根styles.css。三类错误都会使构建以退出码 1 失败build-css.mjs非法import路径逃出src/style/目录解析后以..开头或不以.css结尾缺失文件import指向的文件不存在未登记文件脚本递归遍历src/style/下所有.css文件排除index.css任何未被index.css引入的文件都会触发 Unlisted CSS files 错误。第三条是整个体系的关键防线新增一个.css文件却忘记注册构建不会静默忽略而是直接报错。这保证了index.css与实际文件集合永远一致。确定性顺序与无!important约定index.css 的结尾两行值得注意/* Utilities imported last to preserve cascade priority without importance flags */ import ./base/visibility.css;可见性工具类被刻意放在所有模块之后靠级联顺序cascade order而非优先级标记取胜。这与 stylelint.config.mjs 中唯一启用的规则declaration-no-important: [true]形成呼应——项目级 lint 直接禁止!important开发者只能通过调整模块注册顺序来控制层叠优先级。这一约束配合npm run lint:css即stylelint src/style/**/*.css在 CI 和日常开发中持续生效。命名与 token 约定指南的 Conventions 一节规定Claudian 自有 class 一律使用.claudian-前缀共享的 Obsidian 宿主选择器和通用状态 class 可以保留无前缀形式推荐BEM-lite命名.claudian-{block}、.claudian-{block}-{element}、.claudian-{block}--{modifier}使用 Obsidian 的 CSS 变量如--background-*、--text-*、--interactive-*让样式自动适配宿主主题代码块使用var(--font-monospace)。从 src/style/base/variables.css 的结构还可以看到 token 的层次.claudian-container作用域内定义品牌色、错误色--claudian-error、压缩提示色--claudian-compact等语义 token并按 provider 拆分为独立命名 token 后通过data-provider别名聚合。body.theme-light .claudian-container下还有一组浅色主题的覆写例如--claudian-brand-codex在浅色主题下从#d0d0d0变为#000000说明深色/浅色适配是通过重定义 token 完成的而不是在组件里写:root级别的主题分支。基础元素规则按钮与表单控件的强制基线指南的 Specific Element Rules 一节要求所有 Claudian 自有的下列元素实例都必须使用规定的基线样式偏离只允许通过显式的语义修饰符或 surface 修饰符实现选择器顺序、嵌套层级和继承自 Obsidian 的样式都不构成豁免。按钮完整规则继承自指南所有按钮静止态使用border: 0、background: transparent、box-shadow: none、color: var(--text-muted)Hover 与focus-visible使用color: var(--text-normal)同时保持无边框、透明背景、无 box shadow如需填充式filledhover 或 focus 表面必须使用显式修饰符禁用态按钮使用color: var(--text-faint)和cursor: default且不得保留任何 hover、focus 或 active 强调按钮内 SVG 继承currentColor其宽高由按钮的基线选择器声明需要不同图标尺寸时必须使用显式修饰符必须把完整的基线样式应用到 Claudian 按钮 class 的 hover、focus、active、disabled 全部选择器上确保 Obsidian 无法在任何状态下恢复原生按钮外观native button chrome。最后一条点明了规则动机Obsidian 宿主 CSS 可能给button元素应用默认样式如果只写静止态基线交互态下宿主样式会回潮因此在每个状态选择器上重复声明基线是强制要求而非冗余。输入框与文本域所有独立standaloneinput/textarea 使用min-width: 0、border: 1px solid var(--background-modifier-border)、background: var(--background-modifier-form-field)、box-shadow: none、color: var(--text-normal)以及继承的 UI 字体Hover 保持基线边框、背景与 box shadowFocus 使用outline: none和border-color: var(--interactive-accent)且不得引入浏览器或 Obsidian 的 box shadowPlaceholder 使用color: var(--text-muted)禁用控件使用color: var(--text-faint)和cursor: default嵌入在包装器wrapper中的 input/textarea 在所有交互状态下使用border: 0、background: transparent、box-shadow: none边框、背景、圆角和焦点处理完全归包装器所有textarea 默认resize: none和overflow-y: auto需要可拖拽调整的 textarea 必须使用显式修饰符并限定尺寸Error、warning、只读及语义模式处理必须通过显式修饰符或作用域内的自定义属性实现并且要覆写所有受影响的交互状态。Obsidian 集成陷阱Gotchas指南末尾的 Gotchas 一节记录了四条与宿主环境直接相关的坑主题检测Obsidian 使用body.theme-dark和body.theme-light标识当前主题。主题相关的 token 覆写如 variables.css 中的body.theme-light .claudian-container选择器都依赖这一约定。模态框层级模态框的z-index必须大于1000才能盖在 Obsidian UI 之上。会话管理器布局的作用域持久会话管理器的布局规则必须限定在.claudian-session-sidebar或.claudian-wide-session-layout之下单面板历史菜单虽然共享条目原语item primitives但必须保留自己的尺寸、tab 状态标签和操作按钮。滚动所有权与min-height: 0会话管理器的 pinned 列表与会话列表是相互独立的滚动主体independent scroll owners。必须让min-height: 0沿 flex 祖先链保持传递否则 sticky 头部和有限高度区域会裁剪clip或叠压overlap内容。这是 flex 布局中经典的滚动容器陷阱flex 子项默认的min-height: auto会阻止其收缩到内容高度以下导致内部滚动失效。验证与维护路径整条风格指南不是仅靠约定执行而是有多层可验证的机制兜底构建期scripts/build-css.mjs 对未登记模块、非法导入和缺失文件三类问题硬失败见上文构建链一节Lint 期package.json 中lint:css脚本执行stylelint src/style/**/*.css且 stylelint.config.mjs 启用了declaration-no-important从工具层面保证无!important、靠级联顺序控优先级的约定测试期tests/integration/build/build.test.ts 以集成测试验证构建脚本转发参数时不会把参数当作 shell 命令执行防止命令注入保证构建链路在自动化环境下可信入口约定src/style/CLAUDE.md 通过AGENTS.md引用形式指向 src/style/AGENTS.md即本指南全文供编码代理在该目录下工作时加载同样的样式约束。小结Claudian 的样式体系可以用三句话概括目录按 UI 所有权划分、index.css是唯一的模块注册表且未登记即构建失败、CSS 只负责渲染而状态永远归 TypeScript 所有。在此之上按钮与表单控件的强制基线、.claudian-前缀与 BEM-lite 命名、data-providertoken 别名机制以及针对 Obsidian 主题检测、模态框z-index和 flex 滚动链的专项注意事项共同构成了一套可以在 Obsidian 宿主环境中长期维护的样式规范。新增样式模块时的标准动作是在正确的所有权目录下创建文件在 index.css 中按语义位置注册import运行npm run build:css与npm run lint:css确认通过。【免费下载链接】claudianAn Obsidian plugin that embeds Claude Code/Codex as an AI collaborator in your vault项目地址: https://gitcode.com/GitHub_Trending/cl/claudian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考