Carbon 设计系统集成 Next.js 示例App Router、SCSS 主题与 carbon/react 的完整落地指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbonCarbon 仓库的examples/nextjs目录提供了一个将 Carbon 设计系统接入 Next.js 应用的完整示例工程。本篇以 examples/nextjs/README.md 为主线完整还原“先构建 monorepo、再运行示例”的标准工作流并结合该示例的真实源码next.config.js、package.json、src/app/layout.js、src/scss/styles.scss逐文件剖析依赖版本、构建配置、全局 SCSS 引入方式与暗色主题切换机制帮助读者掌握 Carbon 在 Next.js App Router 项目中的可复制集成方案。示例工程的文件结构在展开运行步骤前先明确示例目录的组成后文的配置分析均基于这些真实文件examples/nextjs/next.config.js—— Next.js 构建配置strict mode、Turbopack、Sass 选项examples/nextjs/package.json—— 声明carbon/react、next、react等依赖与dev/build/start脚本examples/nextjs/src/app/layout.js—— App Router 根布局负责引入全局 SCSS 与页面元数据examples/nextjs/src/app/page.js—— 首页客户端组件演示引入 Carbon React 组件examples/nextjs/src/scss/styles.scss—— 全局样式入口串联 Carbon 的 reset、grid、layer、themes、theme 与组件样式examples/nextjs/public/—— 静态资源favicon、vercel.svg。运行步骤先构建 monorepo再启动示例README 给出的启动流程分两步且强调了执行顺序——必须先在 carbon 仓库根目录完成构建再进入示例目录启动开发服务器# 第一步在 carbon 仓库根目录 yarn install yarn build这一步会触发仓库根 package.json 中的build脚本其定义是lerna run build --stream --prefix node tasks/generate-repo-structure.mjs即通过 Lerna 依次构建packages/*下的所有工作区包carbon/react的lib/产物与 scss 入口即在此阶段就绪。根 package.json 同时声明了engines.node 20.x与packageManager: yarn4.10.3即该示例依赖的环境前提为 Node 20 与 Yarn 4。# 第二步进入示例目录 cd examples/nextjs yarn install # or npm install yarn dev # or npm run devdev脚本对应 package.json 中的next dev。启动后README 提示在浏览器打开本地地址查看结果文档写的是http://localhost:5173需要注意的是 Next.js 开发服务器默认监听 3000 端口README 后文的 API 路由说明http://localhost:3000/api/hello也印证了 3000 才是实际端口请以next dev终端输出的地址为准。此外 README 说明开发时修改页面文件即可热更新页面会随编辑自动刷新pages/api目录会被映射为/api/*路由。需要指出的是从当前源码结构看该示例已迁移到App Routersrc/app/目录页面入口实际是 src/app/page.js 与 src/app/layout.jsREADME 中pages/index.js的描述属于 create-next-app 模板沿袭下来的旧表述实际开发请以src/app下的文件为准。依赖清单示例锁定了哪些版本package.json 是最小化但完整的依赖声明关键版本如下依赖版本角色carbon/react^1.104.0-rc.0Carbon 的 React 组件库提供Button等组件与carbon/react/scss/*样式入口next^16.2.11Next.js 16启用 App Router 与 Turbopackreact/react-dom^19.2.5React 19sassdevDependency^1.93.2编译全局 SCSS 所需的 Sass 编译器依赖脚本为buildnext build、devnext dev、startnext start三个标准命令。值得注意的是sass被放在 devDependencies示例直接编译 SCSS 源文件而非引用预编译 CSS因此构建链中必须有 Sass。构建配置解读next.config.js 的三个关键点next.config.js 全文如下/** type {import(next).NextConfig} */ const nextConfig { reactStrictMode: true, turbopack: { root: __dirname, }, sassOptions: { quietDeps: true, }, }; module.exports nextConfig;三个配置项对 Carbon 集成各有实质意义reactStrictMode: true在开发模式下对组件做双渲染检查提前暴露副作用与状态更新问题对大量受控组件表单类控件的 Carbon 组件库尤为必要turbopack.root: __dirname显式将构建根目录锚定到示例目录本身。在 carbon 这样的 monorepo 中Next.js 向上查找时可能误判项目根该配置保证 Turbopack 不会越过示例目录去解析上层工作区sassOptions.quietDeps: true抑制来自依赖包node_modules 中的carbon/reactSCSS的废弃警告与冗余输出保持终端日志干净。同仓库的 examples/light-dark-mode/next.config.js 使用了完全一致的sassOptions.quietDeps: true配置说明这是 Carbon 官方示例在 Next.js 中处理 Sass 依赖警告的统一做法。全局样式入口layout.js 如何接入 Carbon SCSSsrc/app/layout.js 是整个示例与 Carbon 样式体系的连接点import ../scss/styles.scss; export const metadata { title: Create Next App, description: Generated by create next app, }; export default function RootLayout({ children }) { return ( html langen head link relicon href/favicon.ico / /head body{children}/body /html ); }这里通过相对路径import ../scss/styles.scss把全局 SCSS 挂到根布局上。App Router 的根布局会在每次导航时保持挂载因此全局样式只需引入一次即可作用于所有页面——这是 Next.js 中引入全局非模块化样式的标准位置。SCSS 集成方案styles.scss 逐行解析src/scss/styles.scss 展示了 Carbon v12 样式体系的最小引入集use carbon/react/scss/reset; use carbon/react/scss/grid; use carbon/react/scss/layer; use carbon/react/scss/themes; use carbon/react/scss/theme; use carbon/react/scss/components/button; body { background: theme.$background; color: theme.$text-primary; } media (prefers-color-scheme: dark) { :root { include theme.theme(themes.$g100); } }每个use都有明确职责可按需增删reset浏览器样式重置保证 Carbon 组件基线一致grid布局网格系统packages/react/scss/grid/下包含_css-grid.scss与_flexbox.scss等模块layer层级/遮罩layer体系是 Tooltip、Modal、Tearsheet 等浮层组件的基础themes/theme主题令牌token与主题混入。theme.$background、theme.$text-primary这类变量来自主题令牌components/button只引入当前用到的Button组件样式体现“按组件按需加载样式”的思路——用到哪个组件就use对应条目。最后一段媒体查询是该示例的点睛之笔在用户系统偏好暗色模式时通过include theme.theme(themes.$g100)将 Carbon 灰阶 100 暗色主题注入:root实现零 JS 的跟随系统暗色切换g100为 Carbon 白/黑双主题对中的暗色侧。这与同仓库 examples/light-dark-mode 示例的方向一致可作为暗色主题接入的参考起点。从源码结构看carbon/react/scss/下的_theme.scss、_themes.scss等文件是构建期生成的转发桩例如 packages/react/scss/_theme.scss 的内容只有一行forward carbon/styles/scss/theme即样式实现的单一真源在carbon/styles包carbon/react提供的是面向 React 场景的再导出入口。理解这一点后排查样式问题时可直接对照carbon/styles的源文件。组件使用page.js 中的第一个 Carbon 组件src/app/page.js 演示了在 App Router 页面中使用 Carbon React 组件use client; import React from react; import { Button } from carbon/react; import Image from next/image; import styles from ../scss/Home.module.css; export default function Home() { return ( div className{styles.container} main className{styles.main} h1 className{styles.title} Welcome to a hrefhttps://nextjs.orgNext.js!/a /h1 p className{styles.description} ButtonHello world/Button /p /main {/* footer 省略 */} /div ); }三个要点use client指令页面使用了交互式 React 组件Button带有点击态因此声明为客户端组件组件按需引入import { Button } from carbon/react只取所需组件与 SCSS 侧“只usebutton 组件样式”的策略相互呼应两种样式体系共存页面局部布局用 CSS ModulesHome.module.css全局基线用 Carbon SCSS二者互不干扰。小结与延伸该示例以不到十个文件演示了 Carbon 接入 Next.js 的完整闭环根 monorepo 先行构建yarn install yarn build→ 示例目录独立安装与next dev启动 →next.config.js中reactStrictModeturbopack.rootsassOptions.quietDeps三件套 → 根布局引入全局 SCSS →styles.scss按模块usereset/grid/layer/themes/theme 与组件样式 → 页面中以use client组件消费carbon/react。在此基础上还可以继续阅读同目录群中 examples/light-dark-modeNext.js 亮暗双主题、examples/custom-themeVite 定制主题以及 docs/guide 下的主题与版本文档进一步扩展主题定制能力。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考