企业官网建设流程全解析

• UI组件
• 前端
• 设计系统

本文基于仓库 docs/intro.md 编写。Material Web（又称 Material Web Components，简称 MWC）是遵循 Google Material Design 指南构建的 Web Components 组件库。读完本文，你将理解 Material 3 设计系统与 Web Components 的关系、MWC 中设计令牌（tokens）的工作原理与定制方法，并掌握用 CDN 或 npm 快速接入 MWC 的实战路径，为后续阅读 组件文档 与 快速上手指南 打下基础。

MWC 组件集合效果演示

什么是 Material？

Material Design 是由 Google 设计师和开发者构建并持续维护的一套设计系统，其构建 Material 应用与组件的完整指南公开发布在 material.io 上。它定义了一整套关于颜色、排版、形状、动效、状态与布局的规范，让不同平台、不同团队的产品能够呈现出统一而和谐的用户体验。

最新的Material 3（Material You）是这套设计系统的当前版本，它着力于打造个性化（personal）、自适应（adaptive）、表现力强（expressive）的体验，其关键能力包括：

• 动态颜色（Dynamic Color）：从用户壁纸等来源提取主色调，自动生成完整的色彩方案，让界面与用户的个人环境产生共鸣；
• 增强的无障碍（Enhanced Accessibility）：在对比度、焦点指示、触摸目标尺寸等方面给出更严格的设计约束；
• 大屏布局基础（Large Screen Layout Foundations）：为平板、桌面、可折叠设备等大屏形态提供布局指导；
• 设计令牌（Design Tokens）：用统一的令牌体系承载设计决策，使主题定制可以声明式、可追溯地完成。

Material Design 应用示例

MWC 正是这一设计系统在 Web 平台上的落地实现。仓库中的令牌源码（如 tokens/_md-sys-color.scss、tokens/_md-sys-shape.scss）与 docs/theming/ 下的主题文档，都是 Material 3 设计语言在代码层面的直接体现。

什么是 Web Components？

Web Components 是一组浏览器原生 Web 标准 API，它允许开发者创建自带封装样式与行为的自定义 HTML 元素。因为底层是浏览器原生能力，MWC 组件天然具有以下优势：

• 框架无关：既可用于 Lit、React、Vue、Svelte 等前端框架，也可用于 Eleventy、WordPress、Ruby on Rails 等服务端渲染环境；
• 样式封装：组件内部样式被 Shadow DOM 隔离，不会意外泄漏或污染页面全局样式；
• 标准交互：组件以标准 HTML 元素的姿态存在，可被浏览器与辅助技术正确识别。

MWC 中的许多组件是浏览器原生元素（如<button>、<input>）的直接替代品（drop-in replacement），也就是说，你可以在几乎不改变 HTML 结构的前提下，把原生表单控件升级为符合 Material 规范的控件。以下对比来自官方文档 docs/intro.md：

<!-- 原生浏览器元素 --> <form> <label> Email <input type="email" name="email" required> </label> <label> Subscribe <input type="checkbox" name="subscribe"> </label> <button type="reset">Reset</button> <button>Submit</button> </form> <!-- Material 元素 --> <form> <md-outlined-text-field label="Email" type="email" name="email" required></md-outlined-text-field> <label> Subscribe <md-checkbox name="subscribe"></md-checkbox> </label> <md-text-button type="reset">Reset</md-text-button> <md-outlined-button>Submit</md-outlined-button> </form>

这个示例展示了 MWC 的核心设计哲学：标签名以md-为前缀，属性（如type、name、required、label）与原生元素保持语义一致，因此迁移成本极低，同时仍可参与表单的原生提交与校验流程。

从源码层面看，每个组件都是通过 Lit 的@customElement装饰器注册的自定义元素。例如 checkbox/checkbox.ts 中定义了<md-checkbox>：

@customElement('md-checkbox') export class MdCheckbox extends Checkbox { static override styles: CSSResultOrNative[] = [styles]; }

而 button/outlined-button.ts 同样以@customElement('md-outlined-button')注册。值得注意的是，组件在内部通过一系列行为 mixin 组装而成，例如 button/internal/button.ts 中的按钮基类：

const buttonBaseClass = mixinDelegatesAria( mixinFormSubmitter(mixinFormAssociated(mixinElementInternals(LitElement))), );

从这段代码可以推断，MWC 的表单类组件借助ElementInternals实现了原生表单关联（form-associated）与表单提交（form-submitter）能力，这就是为什么<md-checkbox>、<md-outlined-button>可以直接放进<form>中工作，并正确参与表单的提交、重置与验证。这正是"原生元素的直接替代品"这一承诺的底层保障。

什么是设计令牌（Tokens）？

设计令牌（Design Tokens）是所有 UI 元素的基础构件。在 Material 3 体系里，颜色、字体、圆角、间距、状态、动效等设计决策都被抽象为命名化的令牌。而在 MWC 中，令牌以CSS 自定义属性（Custom Properties）的形式暴露给使用者，你不需要理解组件内部实现，只需覆盖相应变量即可完成主题定制。

官方文档 docs/intro.md 给出的最小主题定制示例：

:root { --md-sys-color-primary: olive; --md-sys-color-secondary: tomato; --md-ref-typeface-brand: 'Open Sans'; --md-ref-typeface-plain: system-ui; }

上面例子中同时出现了两组令牌，对应 MWC 令牌体系的两大类：

1. 系统令牌（System Tokens）：以--md-sys-为前缀，是组件引用的"语义化"设计决策，例如--md-sys-color-primary（主色）、--md-sys-color-secondary（次色）。修改它们会联动影响所有引用这些令牌的组件；
2. 参考令牌（Reference Tokens）：以--md-ref-为前缀，是最底层的原始设计值，例如--md-ref-typeface-brand（品牌字体）与--md-ref-typeface-plain（正文/界面字体）。

源码中的令牌实现

令牌并非文档中的"纸面规范"，在仓库中它们被真实地实现并校验。以 tokens/_md-sys-color.scss 为例，该文件定义了系统颜色令牌的完整集合，并通过values-light()/values-dark()两个函数分别产出亮色与暗色主题：

• 支持的令牌包括primary、on-primary、primary-container、surface、surface-container、surface-variant、error、error-container、outline、outline-variant、secondary、tertiary以及对应的on-*、-fixed、-dim等共 50 余项，覆盖了 Material 3 色彩体系的核心角色；
• 每个令牌最终都会被包装为var(--md-sys-color-<token>, <默认值>)的形式输出，这意味着即使你没有定义任何自定义属性，组件也有可用的回退默认值；一旦你在:root或组件作用域内覆盖同名变量，新值便会生效。

类似地，tokens/_md-ref-typeface.scss 定义了参考字体令牌，支持brand、plain、weight-bold、weight-medium、weight-regular五项，输出为--md-ref-typeface-*系列自定义属性。这两处实现都调用了 tokens/internal/_validate.scss 的validate.values()做令牌名校验，从构建期就保证令牌命名的一致性与向后兼容性。

组件级令牌：更精细的定制粒度

除了全局的系统/参考令牌，每个组件还拥有自己的组件令牌（Component Tokens），前缀形如--md-filled-button-*、--md-checkbox-*。以 tokens/_md-comp-filled-button.scss 为例，填充按钮支持包括container-color（容器颜色）、container-elevation（容器海拔/阴影层级）、container-shape（圆角）、label-text-color/label-text-font/label-text-size/label-text-weight（标签文本的色、字体、字号、字重）、icon-color、icon-size、hover-state-layer-color、pressed-state-layer-color等数十个令牌，并且区分了disabled-*、focus-*、hover-*、pressed-*等不同交互状态。

这意味着你既可以用--md-sys-color-*做全局换肤，也可以在单个组件上做精细微调，例如只让某一个按钮变绿：

md-filled-button.accept { --md-filled-button-container-color: green; --md-filled-button-label-text-color: white; }

这种"全局系统令牌 + 组件级令牌"的分层设计，正是 Material 3 设计令牌体系在工程上的精髓：改动一处令牌，所有消费它的组件同步更新，主题定制从此变得可声明、可追溯、可维护。想深入了解令牌的分组与语义，可以继续阅读 docs/theming/color.md、docs/theming/typography.md 与 docs/theming/shape.md。

如何开始使用 MWC

理解了"Material 3 + Web Components + Tokens"这三块基石后，就可以动手实践了。仓库提供了两条接入路径，完整细节见 docs/quick-start.md。

方式一：CDN 快速原型（零构建）

对于快速原型验证，官方推荐使用 esm.run 这一 CDN 服务，无需安装 npm 包和配置构建工具。通过 import map 将@material/web映射到 CDN 地址，再导入聚合入口即可：

<head> <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" rel="stylesheet"> <script type="importmap"> { "imports": { "@material/web/": "https://esm.run/@material/web/" } } </script> <script type="module"> import '@material/web/all.js'; import {styles as typescaleStyles} from '@material/web/typography/md-typescale-styles.js'; document.adoptedStyleSheets.push(typescaleStyles.styleSheet); </script> </head> <body> <h1 class="md-typescale-display-medium">Hello Material!</h1> <form> <p class="md-typescale-body-medium">Check out these controls in a form!</p> <md-checkbox></md-checkbox> <div> <md-radio name="group"></md-radio> <md-radio name="group"></md-radio> <md-radio name="group"></md-radio> </div> <md-outlined-text-field label="Favorite color" value="Purple"></md-outlined-text-field> <md-outlined-button type="reset">Reset</md-outlined-button> </form> </body>

这段示例同时演示了 MWC 的两个常用能力：

• 聚合导入：@material/web/all.js一次性注册全部组件（其内容见 all.ts，包含按钮、复选框、芯片、对话框、列表、菜单、进度条、单选、选择器、标签页、文本域等约 30 个组件变体）；
• 排版样式：通过 typography/md-typescale-styles.ts 导出的md-typescale-*工具类（如display-medium、body-medium）快速应用 Material 3 字阶（Type Scale）。

方式二：npm 安装 + 按需引入（生产推荐）

正式项目推荐通过 npm 安装并只引入用到的组件，以控制产物体积：

npm install @material/web

然后从@material/web/<component>/<component-variant>.js导入所需组件定义：

// index.js import '@material/web/button/filled-button.js'; import '@material/web/button/outlined-button.js'; import '@material/web/checkbox/checkbox.js';

在 HTML 中直接使用对应标签：

<script type="module" src="./index.js"></script> <label> Material 3 <md-checkbox checked></md-checkbox> </label> <md-outlined-button>Back</md-outlined-button> <md-filled-button>Next</md-filled-button>

这里有两个易混淆的聚合入口值得注意：

• all.ts：导入并导出全部组件，文件头注释明确警告它仅用于原型与开发构建，生产环境应只引入实际使用的组件；
• common.ts：导入并导出常用组件子集（如 filled/outlined/text 按钮、checkbox、dialog、menu、tabs 等），体积比all.js更小，同样标注为原型与开发构建用途。

两个文件的源码注释都强调同一件事：生产环境请按需 import 单个组件，这也是 MWC 保持按需加载、控制包体大小的关键实践。关于体积的具体数据可查看 docs/size.md。

生产构建与浏览器支持

MWC 的组件源码使用裸模块标识符（bare module specifiers），在 import map 尚未全面普及的当下，生产构建需要借助打包工具解析这些标识符。官方在 docs/quick-start.md 中推荐使用 Rollup 完成这一工作：

npm install rollup @rollup/plugin-node-resolve npx rollup -p @rollup/plugin-node-resolve index.js -o bundle.js

<script src="./bundle.js"></script>

关于运行环境，docs/support.md 明确说明 MWC 目标支持每个版本发布时最新的两个大版本浏览器，并给出了当前支持矩阵：Chrome 120+、Edge 120+、Firefox 119+、Safari 16.4+（更早版本的 Safari 可能需要配合ElementInternalspolyfill 使用）。

结语：从入门到组件实战

MWC 的价值可以概括为一句话：用浏览器原生的 Web Components 标准，把 Material 3 设计系统（含动态颜色、设计令牌、无障碍规范）变成开箱即用的 HTML 标签。本文梳理了它的三大基石——Material 3 设计系统、Web Components 封装标准、以及以 CSS 自定义属性形式存在的设计令牌体系，并通过 docs/intro.md 中的表单对比示例、令牌定制示例，配合仓库中的组件注册代码与令牌 SCSS 实现，展示了从"理解原理"到"动手定制"的完整路径。

接下来可以按以下顺序继续深入：

1. 阅读 docs/quick-start.md 完成安装与构建；
2. 浏览 docs/components/ 下的组件文档（按钮 docs/components/button.md、复选框 docs/components/checkbox.md、对话框 docs/components/dialog.md 等）逐个掌握每个组件的 API 与示例；
3. 进入 docs/theming/ 学习颜色、形状、排版的深度主题定制；
4. 查看 docs/roadmap.md 了解项目演进方向，结合 docs/support.md 确认你的目标浏览器兼容性。

• UI组件
• 前端
• 设计系统