前端UI组件设计系统【免费下载链接】cosscoss.com/ui is the official design system of Cal.com项目地址https://gitcode.com/gh_mirrors/or/coss点击查看免费下载本篇技术指南围绕 coss 仓库GitHub 加速计划 / or / coss的根 README.md 展开系统讲解 coss.com/ui 这一 Cal.com 官方设计系统的仓库结构与多应用协作机制、三套 Next.js 应用间的环境变量配置、基于 Turborepo 与 Bun 的开发构建工作流以及 coss ui 组件库「复制粘贴即可拥有」的组件理念、Particles 组件生态与混合开源许可策略。读完本文你将能够从零配置并启动该 monorepo 的本地开发环境理解组件注册表registry的运作方式并掌握向 coss ui 贡献 Particles 组件的规范流程。一、项目定位Cal.com 官方设计系统coss.com/ui前身为 Origin UI是 Cal.com 的官方设计系统Official Cal.com Design System。它不只是一套静态组件演示站点而是一个承载了多个产品与应用的完整生态仓库主站www、组件库与文档站ui、历史遗留组件origin以及共享组件包packages/ui共同构成了这个 monorepo 的全部内容。从定位上看coss ui 是一套**「开箱即用的精美、可访问、可组合」的 React 组件集合其核心理念是让开发者把组件代码复制、粘贴到自己项目中并完全拥有**copy, paste, and own而不是通过 npm 依赖黑盒引用。该组件库将作为 Cal.com 逐步采纳的标准组件库采用开源共建的方式面向所有希望构建「美观、可靠用户界面」的开发者开放。二、仓库架构Apps and Packages根 README.md 明确列出了本仓库的五大组成模块结合各目录下的 package.json 可以进一步确认其技术栈与职责划分目录职责技术栈要点来自各自 package.jsonapps/www/coss.com 主站Next.js 16.2.5 React 19.2.6 Tailwind CSS 4依赖coss/uiworkspace 内部包许可为 AGPLv3apps/ui/coss ui 组件库与文档站基于 Fumadocs 文档框架端口 4000含组件注册表构建脚本许可为 MITapps/origin/收购前的 Origin UI 组件遗留快照Radix UI / shadcn 风格组件端口 4001依赖radix-ui、react-aria等许可为 MITpackages/ui/共享 UI 组件包coss/ui导出 base-ui / components / hooks / lib / shared / fonts / globals.css 等多个子路径packages/typescript-config/TypeScript 共享配置coss/typescript-config提供 base / nextjs / react-library 三套配置整个仓库100% 使用 TypeScript包管理器为Bun根 package.json 中packageManager声明为bun1.3.1engines要求bun 1.3.1工作区通过workspaces: [apps/*, apps/examples/*, packages/*]声明。从源码结构看apps/ui/承担着设计系统「中枢」的角色其registry/目录下不仅有ui/基础组件、particles/复合组件还包含base-ui/如csp-provider.ts、direction-provider.ts、merge-props.ts、use-render.ts与hooks/如use-copy-to-clipboard.ts、use-media-query.ts、lib/等辅助模块共同支撑组件注册表的生成。而packages/ui/则通过子路径导出./base-ui/*、./components/*、./shared/*等向 www、ui 等应用提供共享能力。三、环境变量配置三应用互联的命脉由于这是一个多 Next.js 应用互相链接的 monorepo导航与跳转能否正常工作取决于环境变量是否配置正确。根 README 明确指出无论是本地开发还是生产部署都必须为每个应用配置对应的环境变量。3.1 配置方式与位置在本地开发时需要分别在每个 app 目录下创建.env.local文件写入各自对应的变量。所有变量均以NEXT_PUBLIC_前缀导出意味着它们会在浏览器端被内联注入因此只适合存放公开的 URL 信息不应放置任何密钥。3.2 www 应用端口 3000在apps/www/.env.local中www 主站需要知道其他应用的地址# apps/www/.env.local NEXT_PUBLIC_APP_URLhttp://localhost:3000 NEXT_PUBLIC_COSS_UI_URLhttp://localhost:4000/uiNEXT_PUBLIC_APP_URL主站自身地址端口 3000与 apps/www/package.json 中next dev默认端口一致NEXT_PUBLIC_COSS_UI_URL指向 ui 应用在 4000 端口的/ui路径。3.3 ui 应用端口 4000在apps/ui/.env.local中ui 文档站需要同时知道主站与遗留 origin 站的地址# apps/ui/.env.local NEXT_PUBLIC_APP_URLhttp://localhost:4000/ui NEXT_PUBLIC_COSS_URLhttp://localhost:3000 NEXT_PUBLIC_ORIGIN_URLhttp://localhost:4001NEXT_PUBLIC_APP_URLui 应用自身地址注意是http://localhost:4000/ui即带/ui路径前缀与 apps/ui/package.json 中next dev --port 4000、next start --port 4000对应NEXT_PUBLIC_COSS_URL指向 www 主站3000 端口NEXT_PUBLIC_ORIGIN_URL指向 origin 遗留组件站4001 端口。3.4 origin 应用端口 4001在apps/origin/.env.local中遗留组件站需要同时链接回主站与 ui 站# apps/origin/.env.local NEXT_PUBLIC_APP_URLhttp://localhost:4001/origin NEXT_PUBLIC_COSS_URLhttp://localhost:3000 NEXT_PUBLIC_COSS_UI_URLhttp://localhost:4000/ui三个应用共同形成一个互相导航的环www ↔ ui ↔ origin任何一个变量缺失或端口不一致都会导致对应导航入口 404 或跳转失效。3.5 Turborepo 的自动缓存失效根 README 特别提示Turborepo 已配置为监听.env*文件的变更因此当这些变量被修改时Turborepo 会自动使相关任务缓存失效并重新执行无需手动清理。这一定义可以在 turbo.json 中得到印证——build任务的inputs明确包含$TURBO_DEFAULT$与.env*即环境文件是构建输入的组成部分。四、开发与构建工作流Bun Turborepo根 package.json 将根命令委托给 Turborepoturbo run ...根 turbo.json 定义了统一的任务管线build / dev / lint / typecheck / clean。4.1 构建全部应用与包bun run build等价于对所有工作区执行turbo run build。build任务通过dependsOn: [^build]保证依赖拓扑序先构建上游依赖包再构建应用产物输出到.next/**排除.next/cache。4.2 构建指定应用bun run build --filterwww bun run build --filterui bun run build --filterorigin--filter是 Turborepo 的过滤语法可精确定位某个应用或包单独构建。由于www、ui应用都依赖 workspace 内的coss/ui与coss/typescript-config构建时 Turborepo 会先构建这些依赖包再执行目标应用的next build。4.3 启动开发环境bun run dev一次启动全部应用的开发服务器。如需单独开发某个应用bun run dev --filterwww bun run dev --filterui bun run dev --filterorigin注意各应用的端口分配见 apps/ui/package.json 与 apps/origin/package.jsonui 固定在4000端口、origin 固定在4001端口、www 使用 Next.js 默认的3000端口——这与上文环境变量中的 URL 一一对应切勿随意改动端口否则需要同步修改.env.local。dev任务在 turbo.json 中标记为persistent: true常驻进程并禁用缓存。4.4 质量保障管线除构建与开发外根 package.json 还提供bun run lint # turbo run lint各包执行 biome lint bun run typecheck # turbo run typecheck各包执行 tsc --noEmit bun run format # biome format --write . bun run test # bun test --pass-with-no-tests当前允许无测试通过根 biome.json 是共享的 Biome 2.x 配置同时接管格式化2 空格缩进、行宽 80、双引号与 Lint启用 recommended 规则并按需关闭了 a11y 等部分规则开启了nursery.useSortedClasses的类名排序提示。lint与typecheck任务在 turbo.json 中同样通过dependsOn保证按依赖顺序执行并启用缓存。五、coss ui 组件库Base UI Tailwind CSS 的组合根 README 用专门一节介绍了 coss ui 的设计哲学coss ui是一套精美设计、可访问且可组合的 React 组件集合构建于 [Base UI] 之上、以 [Tailwind CSS] 进行样式设计其设计目标就是让你能够「复制、粘贴并拥有」。5.1 为什么选择 Base UI团队认为Base UI 是现代 Web 应用的最佳基础它提供强大且无样式的原语unstyled primitivescoss ui 在其之上注入了一套「开箱即用」的设计系统。这一判断直接体现在依赖关系上——apps/ui/package.json 与 packages/ui/package.json 均依赖base-ui/react1.8.0且apps/ui/registry/default/base-ui/下存放了基于 Base UI 二次封装的底层模块。5.2 组件注册表Registry机制coss ui 的组件采用shadcn 风格的 registry 模式分发。根 apps/ui/registry.json超过 1.2 万行记录了完整的组件清单与元信息顶层ui条目列出了全部54 个coss/*注册依赖如coss/accordion、coss/alert-dialog、coss/button、coss/calendar、coss/checkbox、coss/combobox、coss/dialog、coss/drawer、coss/form、coss/menu、coss/select、coss/sidebar、coss/slider、coss/tabs、coss/tooltip等每个组件条目包含name、type: registry:ui、对应的files如registry/default/ui/accordion.tsx以及可选依赖与cssVars如 alert 组件分别定义了 light / dark 两套语义色变量destructive、info、success、warning及其-foreground变体。源码侧apps/ui/registry/default/ui/ 存放 54 个基础组件实现apps/ui/registry/下的registry-ui.ts、registry-particles.ts、registry-hooks.ts、registry-styles.ts等文件则负责把组件注册表聚合输出最终通过 apps/ui/package.json 中的registry:buildtsx ./scripts/build-registry.mts与registry:validate-deps等脚本完成生成与依赖校验。5.3 Particles新一代复合组件根 README 明确指出当前活跃开发聚焦于基于 coss ui 原语构建的新一代 Particles 组件。从目录结构看apps/ui/registry/default/particles/ 已沉淀了大量 Particles 实例覆盖 button41 个、input19 个、calendar25 个、select23 个、slider23 个、tabs15 个、field18 个、input-group28 个等品类命名遵循p-{组件名}-{序号}.tsx的约定。每个 Particle 导出名为Particle的标准组件可由文档站直接渲染展示见 apps/ui/CONTRIBUTING.md。六、Origin UI 收购遗留组件的去留根 README 说明了一个重要的历史背景本仓库同时以遗留快照legacy snapshot形式收录了Origin UI组件。Origin UI 是收购前的一套基于 Radix、shadcn 风格的组件集合收购后仍可继续使用但支持与维护有限活跃开发已全面转向基于 coss ui 原语的新 Particles 组件。这一点在 apps/origin/package.json 中得到印证其依赖栈以radix-ui、react-aria-components、dnd-kit/*、cmdk、react-day-picker等经典库为主且包名仍为origin构建脚本还包含shadcn buildregistry:build呈现典型的收购前 shadcn 风格组件栈特征。相比之下新栈apps/ui与packages/ui已全面转向 Base UI 原语体系。七、参与贡献向 coss ui 添加 Particles根 README 邀请开发者通过 bug 报告、新特性或文档更新等方式参与改进并指向 apps/ui/CONTRIBUTING.md 获取详细指引。结合该贡献指南向 coss ui 贡献新 Particles 的核心流程如下命名Particle 文件名遵循p-{component}-{N}.tsx格式其中component为组件名多词组件用连字符如alert-dialog、input-group、number-fieldN为同品类内的递增序号例如p-button-1.tsx、p-pagination-1.tsx创建文件在registry/default/particles/目录下按上述规则创建文件导出标准组件文件内导出名为Particle的组件以便文档站与 Particles 页面统一渲染展示。八、开源许可策略混合双许可根 LICENSE 声明本仓库默认采用AGPLv3.0许可但根据 LICENSING.md 采用混合许可策略MITapps/origin/与apps/ui/目录沿用其原始 MIT 许可AGPLv3除上述两目录外的其他所有目录遵循 GNU Affero General Public License v3.0。这一安排与各目录 package.json 中的license字段完全一致apps/ui、apps/origin为 MITapps/www、packages/ui及根项目为 AGPL-3.0-or-later在企业或商业场景中选用组件前请务必核对目标目录的许可类型。九、致谢与生态依赖根 README 向四个关键生态项目致谢它们构成了 coss ui 的技术底座Tailwind CSS提供驱动设计系统的 utility-first 样式框架仓库中为 Tailwind CSS v4见各应用 postcss 配置Base UI提供构成组件基础的可访问原语shadcn/ui启发了「复制粘贴」的组件分发哲学Fumadocs提供支撑组件文档的文档框架apps/ui/package.json 中依赖fumadocs-core、fumadocs-mdx配合rehype-pretty-code与 Shiki 完成代码高亮。从组件生态、文档体系到贡献流程coss.com/ui 已经形成了完整的设计系统闭环——无论你是想直接复用其组件、以「复制粘贴」方式集成到自己的 React 项目还是希望参与 Cal.com 官方设计系统的共建本文涉及的仓库结构、环境变量、构建命令与组件注册表机制都是你上手的第一份地图。赞分享前端UI组件设计系统【免费下载链接】cosscoss.com/ui is the official design system of Cal.com项目地址https://gitcode.com/gh_mirrors/or/coss点击查看免费下载相关推荐POLAR-14B-v0.2韩国AI新星14亿参数韩语大模型完全解析POLAR 14B v0.2韩国AI新星14亿参数韩语大模型完全解析 POLAR 14B v0.2是由韩国Plateer公司AI实验室开发的韩语大语言模型Love Iwara收藏功能使用教程打造你的个性化视频库Love Iwara收藏功能使用教程打造你的个性化视频库 Love Iwara作为一款功能强大的第三方Iwara客户端为用户提供了完善的收藏功能让你可以轻移动开发桌面应用音视频视频用 ollama-python 做 AI 简历筛选800 份投递如何 10 分钟排完序用 ollama python 做 AI 简历筛选800 份投递如何 10 分钟排完序 周五下午四点邮箱又进了 800 份投递初筛名单却要在周末前交。把这人工智能本地部署上一篇如何高效使用 Palworld 存档编辑工具3种简单方法完整指南下一篇如何用WindowResizer打破Windows窗口限制终极窗口尺寸控制指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
