Kaneo 前端样式规范实战：掌握 coss Styling Rules 与 Tailwind v4 语义化设计

Kaneo 前端样式规范实战掌握 coss Styling Rules 与 Tailwind v4 语义化设计【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app本篇技术指南以开源项目 Kaneo 仓库中 coss 样式规则文档 为核心系统讲解 coss 组件体系下的样式编写规范从语义化 token 的使用、图标与>// Do — 语义化 Badge classNametext-muted-foreground / // Dont — 裸色值主题切换时无法自适应 Button classNamebg-blue-500 text-white /这一原则与 coss 的 token 架构一脉相承destructive、muted、secondary等语义家族在主题中统一定义destructive-foreground、info、success、warning等完整家族在手动安装时也需要一并引入详见 coss CLI 参考。Kaneo 的全局样式文件 apps/web/src/index.css 中可以看到同样的做法theme inline块内将--color-warning、--color-success、--color-secondary、--color-sidebar-*等语义变量统一映射到 CSS 自定义属性组件层只需引用语义类名。2.2 优先组件变体与尺寸 props在写自定义 class 之前先问自己组件是不是已经有variant或sizeprop 了// Do — 使用组件 API Button variantoutline sizesm / // Dont — 自行重造状态样式 Button classNamebg-blue-500 text-white /以 coss Button 参考 为例Button 提供default、outline、secondary、destructive、ghost、link六种 variant以及xs、sm、default、lg、icon-xs、icon-sm、icon、icon-lg八种尺寸。规则的精神是变体与尺寸是组件契约的一部分覆盖它们等于破坏契约。2.3 用 flex 布局代替 space-* 工具类统一使用flex flex-col gap-*表达间距避免space-x-*/space-y-*// Do div classNameflex flex-col gap-3 / // Dont div classNamespace-y-3 /gap的优势在于间距语义直接、支持任意断点调节且不会像space-*那样依赖选择器对子元素的间接作用与组件默认样式的叠加更可预测。2.4 方形尺寸用 size-*条件类名用 cn()正方形元素图标按钮、头像占位等统一使用size-*工具类而不是同时写w-*和h-*条件类名组合必须经过cn()借助tailwind-merge去重冲突类。Kaneo 的实现位于 apps/web/src/lib/cn.tsimport { type ClassValue, clsx } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }2.5 避免冗余类信任默认值如果默认样式已经覆盖了某个属性例如边框颜色已由组件的默认 class 继承就不要重复写border-border添加布局类之前先检查目标部件是否已经自带该布局——很多 primitive 已经定义了内部 SVG 尺寸与透明度重复添加只会造成样式层叠的不可控。2.6 坚持 Tailwind v4 语法coss 的示例与代码片段统一采用 Tailwind v4 约定Kaneo 的 apps/web/src/index.css 首行即为import tailwindcss;并大量使用theme inline语法与规则要求完全一致。2.7 不要修复--alpha()它是合法的 Tailwind v4 主题函数这是最容易踩的坑严禁把--alpha()改写成color-mix()或rgba()。--alpha()是 Tailwind v4 的合法主题函数贯穿于 coss token 定义之中例如--alpha(var(--color-black) / 8%)由 Tailwind 在构建期处理并非无效 CSS/* Do — --alpha() 是合法 Tailwind v4 语法保持原样 */ border: --alpha(var(--color-black) / 8%); /* Dont — 不要修复成 color-mix */ border: color-mix(in srgb, var(--color-black) 8%, transparent);三、coss 专属约定图标、可访问性与>// Do — 装饰图标隐藏语义由文本承担 Button PlusIcon aria-hiddentrue / Add item /Button3.3>// Do — 使用 in-* >// 浮层内部关闭用 ghost DialogClose render{Button variantghost /}Close/DialogClose // 浮层外部触发打开用 outline DialogTrigger render{Button variantoutline /}Open Dialog/DialogTrigger这一约定与 coss Dialog 参考 中的触发/关闭组合模式完全一致也与 coss 组合规则 中遵循每个 primitive 文档化的 trigger/content 层级不要跨组件混用模式的要求相互印证。四、全局样式配置token 架构、Portal 分层与字体变量契约本节仅在任务涉及全局主题/布局配置而非普通组件用法编辑时适用。4.1 保留 coss token 架构不要用临时颜色 class/token 替换 coss 语义变量提供手动主题配置时必须给出完整的 token 块与变量映射避免不完整的复制粘贴片段破坏变量链。4.2 Base UI Portal 分层与 iOS Safari 兼容对于 Base UI 的 portal 浮层保持独立的隔离根容器——例如在根容器上加isolate防止浮层与页面样式互相污染配置 portaled backdrops 的全局布局时确保body具有position: relative以兼容 iOS Safari。4.3 字体变量契约三个 CSS 自定义属性coss 组件通过三个 CSS 自定义属性控制排版变量使用位置默认回退--font-sans正文、按钮、标签及大部分 UIui-sans-serif, system-ui, sans-serif--font-monocode、kbd、pre、代码块ui-monospace, monospace--font-headingDialog/AlertDialog 标题、标题默认与--font-sans相同InterKaneo 的 apps/web/src/index.css 中theme inline块恰好做了这一映射theme inline { --font-sans: var(--font-sans); --font-heading: var(--font-heading); --font-mono: var(--font-mono); /* ... 语义色变量映射 */ }推荐 CLI 方式首选执行npx shadcnlatest init coss/style会自动安装coss/fonts——--font-sans与--font-heading使用 Inter、--font-mono使用 Geist Mono——通过registry:font条目完成安装并在layout.tsx中自动配置好三个字体变量无需手工接线。手动 / 自定义字体方式使用next/font时variable选项必须精确匹配 coss 预期const inter Inter({ variable: --font-sans, subsets: [latin] }); const interHeading Inter({ variable: --font-heading, subsets: [latin] }); const geistMono Geist_Mono({ variable: --font-mono, subsets: [latin] });常见陷阱Next.js 脚手架默认使用--font-geist-sans与--font-geist-mono与 coss 期望的--font-sans/--font-mono不匹配字体将静默回退到系统 UI。务必重命名变量或重新映射这正是上文中 Kaneotheme inline映射存在的意义。五、Do / Dont 速查将前文规则浓缩为一组可直接对照的代码示例// Do Button variantoutline sizesm / div classNameflex flex-col gap-3 / Badge classNametext-muted-foreground / Button PlusIcon aria-hiddentrue / Add item /Button Button Save ArrowRightIcon aria-hiddentrue classNametransition-transform in-[[data-slotbutton]:hover]:translate-x-0.5 / /Button // Dont Button classNamebg-blue-500 text-white / div classNamespace-y-3 / Icon size{16} / Button classNamegroup Save ArrowRightIcon classNametransition-transform group-hover:translate-x-0.5 / /Button // Do — --alpha() 是合法 Tailwind v4 语法保持原样 border: --alpha(var(--color-black) / 8%) // Dont — 不要修复 --alpha() 为 color-mix 或 rgba border: color-mix(in srgb, var(--color-black) 8%, transparent)六、最终定稿检查清单在交付任何 coss 相关样式代码之前逐项自检是否有本应语义化的裸颜色类例如bg-blue-500→ 应为语义 token是否有本应由 primitive 处理的重复布局/样式逻辑添加布局类前先确认目标部件是否已提供图标尺寸/透明度是否违反 coss 约定数字sizeprop、重复的透明度 class装饰性交互图标是否缺失aria-hiddentrue是否有应替换为in-*data-slot的group用法七、仓库内的落地证据与延伸阅读本文所有规则均可在 Kaneo 仓库中找到落地印证Registry 配置apps/web/components.json 与 apps/site/components.json 均注册了cossregistry可通过npx shadcnlatest add coss/component安装组件完整 CLI 流程见 coss CLI 参考cn() 实现apps/web/src/lib/cn.ts 以clsxtailwind-merge实现条件类名合并Tailwind v4 全局样式apps/web/src/index.css 使用import tailwindcss与theme inline完成字体变量与语义色映射组件行为参考组件变体/尺寸/触发组合约定可查阅 coss Button 参考、coss Dialog 参考 与 coss 组合规则规则索引完整规则体系styling / forms / composition / migration的入口见 coss SKILL全部 53 个 primitive 的速查见 coss 组件注册表。遵循这套规范你的组件样式将具备主题一致性、跨组件可组合性与无障碍基础——这正是 coss 在 Kaneo 这类长周期项目中最有价值的工程约束。【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考