# Web Awesome 设计系统

## Web Awesome 设计系统界面预览

更改圆角和间距缩放比例、切换示例外观、选择区域，并验证本地工作区名称。

## Web Awesome 设计系统设计参考

Web Awesome 3.14.0 默认主题 CSS，在已安装的程序包中检查。下方的颜色条目是语义别名；保留其调色板引用，不以臆测的十六进制值替代。根据缩放比例计算的像素示例以 16px 根字号和 scale=1 为准。

### 语义化界面表面与文本角色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --wa-color-surface-default | white | 主要示例界面表面。 |
| --wa-color-surface-raised | white | 凸起层。 |
| --wa-color-surface-lowered | var(--wa-color-neutral-95) | 代码读数表面。 |
| --wa-color-surface-border | var(--wa-color-neutral-90) | 容器边界。 |
| --wa-color-text-normal | var(--wa-color-neutral-10) | 常规文本。 |
| --wa-color-text-quiet | var(--wa-color-neutral-40) | 次要文本。 |
| --wa-color-text-link | var(--wa-color-brand-40) | 链接角色。 |
| --wa-color-brand-fill-loud | var(--wa-color-brand-50) | 强品牌色填充。 |
| --wa-color-brand-on-loud | white | 强品牌色填充上的文本。 |
| --wa-color-brand-fill-quiet | var(--wa-color-brand-95) | 克制徽标填充。 |
| --wa-color-brand-on-quiet | var(--wa-color-brand-40) | 克制品牌色填充上的文本。 |
### 间距与形状

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --wa-space-scale | 1 | 间距设计令牌使用的乘数。 |
| --wa-space-xs | calc(var(--wa-space-scale) * 0.5rem) | 默认缩放比例下为 8px。 |
| --wa-space-s | calc(var(--wa-space-scale) * 0.75rem) | 默认缩放比例下为 12px。 |
| --wa-space-m | calc(var(--wa-space-scale) * 1rem) | 默认缩放比例下为 16px。 |
| --wa-space-l | calc(var(--wa-space-scale) * 1.5rem) | 默认缩放比例下为 24px。 |
| --wa-space-xl | calc(var(--wa-space-scale) * 2rem) | 默认缩放比例下为 32px。 |
| --wa-space-2xl | calc(var(--wa-space-scale) * 2.5rem) | 默认缩放比例下为 40px。 |
| --wa-border-radius-scale | 1 | 可缩放圆角使用的乘数。 |
| --wa-border-radius-s | calc(var(--wa-border-radius-scale) * 0.1875rem) | 默认缩放比例下为 3px。 |
| --wa-border-radius-m | calc(var(--wa-border-radius-scale) * 0.375rem) | 默认缩放比例下为 6px。 |
| --wa-border-radius-l | calc(var(--wa-border-radius-scale) * 0.75rem) | 默认缩放比例下为 12px。 |
### 排版

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --wa-font-family-body | ui-sans-serif, system-ui, sans-serif | 正文系统无衬线字体。 |
| --wa-font-family-heading | var(--wa-font-family-body) | 标题字体族别名。 |
| --wa-font-family-code | ui-monospace, monospace | 等宽读数。 |
| --wa-font-size-scale | 1 | 字号缩放乘数。 |
| --wa-font-size-m | calc(1rem * var(--wa-font-size-scale)) | 默认根字号和缩放比例下为 16px。 |
| --wa-font-size-l | round(calc(var(--wa-font-size-m) * 1.125 * 1.125), 1px) | 默认根字号和缩放比例下为 20px。 |
| --wa-font-size-xl | round(calc(var(--wa-font-size-l) * 1.125 * 1.125), 1px) | 默认根字号和缩放比例下为 25px。 |
| --wa-font-size-2xl | round(calc(var(--wa-font-size-xl) * 1.125 * 1.125), 1px) | 默认根字号和缩放比例下为 32px。 |
| --wa-line-height-condensed | 1.2 | 窄体标题/标签。 |
| --wa-line-height-normal | 1.6 | 常规阅读行高。 |
### 表单控件别名

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --wa-form-control-background-color | var(--wa-color-surface-default) | 输入框表面别名。 |
| --wa-form-control-border-color | var(--wa-color-neutral-border-loud) | 输入框边界角色。 |
| --wa-form-control-border-radius | var(--wa-border-radius-m) | 字段圆角别名。 |
| --wa-form-control-label-color | var(--wa-color-text-normal) | 无障碍标签颜色。 |
| --wa-form-control-hint-color | var(--wa-color-text-quiet) | 提示颜色别名。 |
## Web Awesome 设计系统完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## Web Awesome 设计系统：拥有独立组件边界的自定义元素

### 采用独立组件边界的自定义元素

> Web Awesome 提供已注册的 HTML 自定义元素，无需依赖 React 应用。导入 wa-input 或 wa-select 后，即可将其放入普通的 HTML 中，并通过文档所述的属性和事件进行控制。此工作台打包了 3.14.0 版本，只使用公开程序包中提供的组件。

页面中可见的控件都是真正的自定义元素，包括其影子根实现。周围的页眉、分区和读数则是原创的 HTML 内容。借助此示例，可以观察哪些样式设置会通过继承的自定义属性跨越组件边界，哪些则属于页面布局。

阅读配套规范

## Web Awesome 设计系统：保留语义颜色别名

### 保持语义化颜色别名完整

默认主题区分凸起、默认和降低层级的界面表面，也区分常规和克制文本，以及多组品牌色填充/对应文本颜色。令牌读数使用降低层级的表面，主要示例使用默认表面，小徽标则将 brand-fill-quiet 与 brand-on-quiet 配对。这些角色在切换外观后仍具有明确含义。

此参考保留 var(--wa-color-neutral-10) 等别名，不会将每个角色都转换为臆测的十六进制值。调色板可以更改，语义映射仍然有效。自定义强品牌色操作时，应同时考虑填充色及其对应的文本颜色。只更改其中一个，可能会导致按钮文字难以辨认。

阅读配套规范

## Web Awesome 设计系统：更改缩放比例，无需逐一重写组件

### 调整比例，无需重写每个组件

圆角选择器只会更改示例上的 --wa-border-radius-scale。缩放比例为 1 时，在 16px 根字号下，默认的小、中、大圆角分别为 3、6 和 12 像素。设为 0 会使这些可缩放圆角变为直角；设为 2 则会使其加倍。胶囊形和圆形令牌是独立概念，不应假定它们也遵循此乘数。

间距选择器会更改 --wa-space-scale。示例的内边距、间隔和读数间距使用官方间距令牌，因此它们的比例关系会一起变化。这并不意味着每个组件的所有尺寸都会缩放：组件控件尺寸遵循各自的令牌关系。编辑面板不受此设置影响，因此在示例变化时仍可稳定对照。

1. 选择“方形”，检查输入框、容器和读数的圆角。

2. 选择“宽松间距”，对比示例中的间隔与保持不变的编辑面板。

3. 恢复默认值，一并还原两个乘数和外观。

阅读配套规范

## Web Awesome 设计系统：排版令牌与自定义标题样式

### 排版令牌与原创标题选择

默认正文字体族为 ui-sans-serif, system-ui, sans-serif。标题字体族沿用正文字体族，代码则使用 ui-monospace。常规行高令牌为 1.6，窄体行高为 1.2。中号字号令牌等于 1rem 乘以 font-size-scale，较大字号则使用取整后的计算值。表格直接展示这些表达式，不隐藏其依赖关系。

工作台本身将标题设为 34px、分节标题设为 23px，并在 700px 的本地断点处缩小页面标题。这些明确属于页面自定义规则。原生字段保留了库的标签和提示样式，便于用户将自定义页面层级与默认组件排版进行比较。

阅读配套规范

## Web Awesome 设计系统：初始值、属性与更改事件

### 初始值、属性与变更事件

每个选择器都包含具有稳定值的 wa-option 子元素。默认选项使用 selected，与当前组件指南中关于初始选择的说明一致。运行时更改通过 value 属性读取选择器的值。主题控件会监听 change 事件并更新 CSS 自定义属性；它们不会从渲染后的选项标签中解析文本。

区域选择器是一个普通的示例字段，不会控制外部存储服务。所选值会显示在本地操作消息中。界面不会假装选择欧洲就能分配存储空间。当逼真的组件演示使用产品术语时，这一区分很重要。

阅读配套规范

## Web Awesome 设计系统：通过令牌和文档说明的部件进行样式设置

### 通过令牌和文档说明的部件设置样式

普通后代选择器无法随意访问组件的 shadow tree。此示例使用继承的主题变量，使字段背景、文本和圆角与周围的 HTML 保持协调。这是受支持的样式设置方式，而不是试图定位内部生成的标记。

如需进行组件专属的更改，请查阅该组件文档中说明的 CSS 自定义属性和 CSS 部件。全局 input 选择器不一定能更改 wa-input 的内部输入框。反过来，在公共祖先上放置主题类或变量，则可能有意影响多个后代自定义元素，因此必须谨慎选择作用范围。

阅读配套规范

## Web Awesome 设计系统：升级、验证与本地结果

### 升级、验证与本地效果

从页面的角度来看，组件注册是异步的。此示例会等待所用 API 对应的 customElements.whenDefined，然后等待选择器更新后再读取初始值。这样可以避免在元素尚未从未知的 HTML 标签升级为组件类时，就对其应用默认值。

工作区操作会在 wa-input 上使用 setCustomValidity 和 reportValidity。去除首尾空格后不足两个字符的名称会被拒绝；发生 input 事件时，自定义错误会清除，以便用户修正后重试。“稍后邀请”按钮处于原生组件的禁用状态。状态文本只会显示本地应用的名称，完整代码不包含创建工作区或分配资源的请求。

- 通过 label 属性提供无障碍标签。

- 提示会在错误发生前说明名称的限制。

- 禁用的操作按钮仍会显示其用途，但不可交互。

阅读配套规范

## Web Awesome 设计系统：导入主题和所用组件

### 导入主题及所用组件

在 Vite 原生应用中安装 @awesome.me/webawesome@3.14.0，并使用提供的 main.js 作为入口。必须引入默认主题样式表；此示例刻意不加载更完整的原生重置样式或工具类包，因为页面布局已由 CSS 明确定义。导入语句会注册标记中使用的五种组件类型。

npm dist 模块适用于打包工具。dist-cdn 发行包适用于直接通过浏览器加载模块，因为其依赖项的打包方式不同。不要将 dist 导入语句复制到普通 script 标签中，并假定裸模块依赖能够解析。需要外部资源的组件必须按文档说明设置基础路径；此示例不使用用户提供的图标资源，并已打包以供离线运行。

阅读配套规范

## Web Awesome 设计系统：公开组件与明确的主题边界

### 公开组件与清晰的主题边界

工作台演示了默认主题和公开组件。部分 Web Awesome 组件、模式和设计资源属于 Pro 产品，因此页面不会暗示安装公开包即可解锁目录中的所有内容。在将某个组件列为共享设计系统的必需依赖之前，应先确认其可用性。

可复用的产品主题应说明更改了哪些变量、变量的作用范围，以及如何检查两种外观模式。实时工作台是这一流程的简要示例：读者可以查看确切的变量更改，并比较由此呈现的原生组件，而不必依赖与实际界面脱节的调色板图片。

阅读配套规范

## Web Awesome 设计系统组件示例

### 自定义元素工作台标记

将原生 wa-select、wa-option、wa-input、wa-switch 和 wa-button 与普通语义化 HTML 组合使用。

```
<main class="token-workbench"><header><p class="eyebrow">WEB AWESOME / TOKEN WORKBENCH</p><h1>See the theme cross the component boundary.</h1><p>Change a scoped token and inspect native custom elements alongside ordinary HTML.</p></header><div class="workbench-grid"><section class="controls"><h2>Theme controls</h2><wa-select id="radius" label="Corner scale"><wa-option value="0">Square / 0</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="2">Rounder / 2</wa-option></wa-select><wa-select id="spacing" label="Spacing scale"><wa-option value="0.8">Compact / 0.8</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="1.25">Relaxed / 1.25</wa-option></wa-select><wa-switch id="dark">Dark appearance</wa-switch><wa-button id="reset" appearance="outlined">Restore defaults</wa-button><p class="hint">These controls change only the specimen. The editing controls keep their original dimensions.</p></section><section id="specimen" class="specimen" aria-label="Theme specimen"><div class="sample-head"><span class="badge">COMPONENT PREVIEW</span><span class="hint">Free components</span></div><h2>Your next workspace</h2><p class="hint">Form labels, field borders and actions inherit semantic tokens through the shadow boundary.</p><wa-input id="workspace" label="Workspace name" hint="Use at least two characters." value="Field notes"></wa-input><wa-select id="region" label="Storage region"><wa-option value="europe" selected>Europe</wa-option><wa-option value="america">North America</wa-option><wa-option value="asia">Asia Pacific</wa-option></wa-select><div class="sample-actions"><wa-button id="create" variant="brand">Apply name locally</wa-button><wa-button disabled>Invite later</wa-button></div><p id="result" role="status">No workspace is created by this specimen.</p><div class="token-readout"><code id="values">--wa-border-radius-scale: 1;<br>--wa-space-scale: 1;</code></div></section></div><footer>Native Web Awesome 3.14.0. The surrounding workbench is original HTML/CSS.</footer></main>
```

代码参考

- 初始选项通过 wa-option 上的 selected 属性进行选择。

- 仅使用免费组件。

### 完整的导入语句和令牌控制

注册组件，等待组件完成升级，修改作用域内的自定义属性，并应用本地有效性状态。

```
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
import './style.css';
const $=id=>document.getElementById(id);function update(){const s=$('specimen');s.style.setProperty('--wa-border-radius-scale',$('radius').value);s.style.setProperty('--wa-space-scale',$('spacing').value);s.classList.toggle('wa-dark',$('dark').checked);s.classList.toggle('wa-light',!$('dark').checked);$('values').textContent=`--wa-border-radius-scale: ${$('radius').value};\n--wa-space-scale: ${$('spacing').value};`;}
Promise.all(['wa-select','wa-switch','wa-input','wa-button'].map(x=>customElements.whenDefined(x))).then(async()=>{await Promise.all([...document.querySelectorAll('wa-select')].map(e=>e.updateComplete));for(const id of ['radius','spacing','dark'])$(id).addEventListener('change',update);$('reset').addEventListener('click',()=>{$('radius').value='1';$('spacing').value='1';$('dark').checked=false;update()});$('create').addEventListener('click',()=>{const field=$('workspace');field.setCustomValidity(field.value.trim().length<2?'Use at least two non-space characters.':'');if(!field.reportValidity())return;$('result').textContent=`Applied “${field.value.trim()}” in the ${$('region').value} specimen. No workspace or storage allocation was created.`});$('workspace').addEventListener('input',()=>$('workspace').setCustomValidity(''));update()});
```

代码参考

- whenDefined 可避免读取尚未升级的自定义元素 API。

- 代码仅导入实际使用的组件。

### 作用域内的示例 CSS

普通的 HTML 会使用与原生自定义元素继承自同一主题的变量。

```
*{box-sizing:border-box}body{margin:0;font-family:var(--wa-font-family-body);font-size:16px;line-height:var(--wa-line-height-normal);color:var(--wa-color-text-normal);background:#f5f6f8}.token-workbench{max-width:1100px;margin:auto;padding:32px}header{max-width:740px;margin-bottom:28px}h1{font-size:34px;line-height:1.15;letter-spacing:-.03em}h2{font-size:23px;line-height:1.25}.eyebrow{font-size:11px;letter-spacing:.12em;font-weight:700}.workbench-grid{display:grid;grid-template-columns:300px minmax(0,1fr);gap:24px}.controls{display:flex;flex-direction:column;gap:20px;padding:24px;background:white;border:1px solid #d9dde3;border-radius:12px}.controls h2{margin:0}.hint,footer{color:var(--wa-color-text-quiet);font-size:14px}.specimen{background:var(--wa-color-surface-default);color:var(--wa-color-text-normal);border:1px solid var(--wa-color-surface-border);border-radius:var(--wa-border-radius-l);padding:var(--wa-space-xl);display:flex;flex-direction:column;gap:var(--wa-space-l)}.specimen h2,.specimen p{margin:0}.sample-head,.sample-actions{display:flex;align-items:center;flex-wrap:wrap;gap:var(--wa-space-s)}.sample-head{justify-content:space-between}.badge{font-size:10px;letter-spacing:.09em;font-weight:700;background:var(--wa-color-brand-fill-quiet);color:var(--wa-color-brand-on-quiet);padding:4px 8px;border-radius:var(--wa-border-radius-s)}.token-readout{background:var(--wa-color-surface-lowered);padding:var(--wa-space-m);border-radius:var(--wa-border-radius-m);font:13px/1.7 var(--wa-font-family-code);white-space:pre-wrap;overflow-wrap:anywhere}#result{font-size:13px}footer{margin-top:20px}@media(max-width:700px){.token-workbench{padding:20px 16px}.workbench-grid{grid-template-columns:1fr}.controls{padding:20px}h1{font-size:28px}.specimen{padding:var(--wa-space-l)}}
```

代码参考

- 工作台标题和布局断点为原创设计。

### 完整的 index.html 文档

适用于所提供的 main.js 和样式表的 Vite 根文档。

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Web Awesome token workbench</title></head><body><main class="token-workbench"><header><p class="eyebrow">WEB AWESOME / TOKEN WORKBENCH</p><h1>See the theme cross the component boundary.</h1><p>Change a scoped token and inspect native custom elements alongside ordinary HTML.</p></header><div class="workbench-grid"><section class="controls"><h2>Theme controls</h2><wa-select id="radius" label="Corner scale"><wa-option value="0">Square / 0</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="2">Rounder / 2</wa-option></wa-select><wa-select id="spacing" label="Spacing scale"><wa-option value="0.8">Compact / 0.8</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="1.25">Relaxed / 1.25</wa-option></wa-select><wa-switch id="dark">Dark appearance</wa-switch><wa-button id="reset" appearance="outlined">Restore defaults</wa-button><p class="hint">These controls change only the specimen. The editing controls keep their original dimensions.</p></section><section id="specimen" class="specimen" aria-label="Theme specimen"><div class="sample-head"><span class="badge">COMPONENT PREVIEW</span><span class="hint">Free components</span></div><h2>Your next workspace</h2><p class="hint">Form labels, field borders and actions inherit semantic tokens through the shadow boundary.</p><wa-input id="workspace" label="Workspace name" hint="Use at least two characters." value="Field notes"></wa-input><wa-select id="region" label="Storage region"><wa-option value="europe" selected>Europe</wa-option><wa-option value="america">North America</wa-option><wa-option value="asia">Asia Pacific</wa-option></wa-select><div class="sample-actions"><wa-button id="create" variant="brand">Apply name locally</wa-button><wa-button disabled>Invite later</wa-button></div><p id="result" role="status">No workspace is created by this specimen.</p><div class="token-readout"><code id="values">--wa-border-radius-scale: 1;<br>--wa-space-scale: 1;</code></div></section></div><footer>Native Web Awesome 3.14.0. The surrounding workbench is original HTML/CSS.</footer></main>
<script type="module" src="/main.js"></script></body></html>
```

代码参考

- 创建一个 Vite 原生项目，并使用上文提供的完整 main.js 和 style.css。

## Web Awesome 设计系统 AI Agent 配置

### 实现起点

完整的 main.js、CSS 和 body 示例可在打包工具中重现此工作台。离线演示是一个 esbuild 包，其中内联了主题 CSS。无需 React 提供方。

```
// Create a Vite vanilla project, then install:
// npm install @awesome.me/webawesome@3.14.0
// index.html: paste the complete workbench markup in body,
// then add <script type="module" src="/main.js"></script>.
// main.js: use the complete imports and token-controls example above.
// style.css: use the complete scoped specimen CSS above.

// Minimum registration pattern used by this example:
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
// Do not duplicate these imports if using the complete main.js above.
```

### 适用于你项目的提示词

```
使用 Web Awesome 3.14.0 作用域令牌工作台，并注册所提供的 wa-select、wa-option、wa-input、wa-button 和 wa-switch 元素。读取初始选项前，请等待组件定义完成并等待 updateComplete。仅在示例区域应用 --wa-border-radius-scale 和 --wa-space-scale，并切换该区域的 wa-light/wa-dark 类，不要更改页面的其他内容。确保可见的令牌读数与原生控件保持同步，并保留标签。请将此工作台用作检查工具，而非设备管理界面。
```

## Web Awesome 设计系统来源与范围

Web Awesome 3.14.0 公共组件和默认主题。布局选择为原创设计；本地名称应用不会创建工作区或存储数据。

- 安装 npm/dist 与 dist-cdn，以及必需的主题。

- 设计令牌 主题令牌类别。

- 自定义 自定义属性与 Shadow DOM 边界。

- Select 选项、值和初始选中项。

- 输入 验证 API。

- Switch 布尔型自定义元素。

## Web Awesome 设计系统相关资源

### Ariakit

Ariakit 提供无样式的 React 组件，具有明确的共享状态和可组合的无障碍部件。其组合框将输入的文本与提交的选择分离，使其对搜索驱动的选择器很有用；下面的参考查找器通过分组和不可用结果演示了这种区别。

### Bits UI

Bits UI 提供无头 Svelte 组件，通过原生部件和 Svelte 5 状态进行组合。示例将派生的混合状态复选框、可独立展开的手风琴面板和基于 portal 的评审对话框组合在一起，并附上完整的样式配置。

### Bootstrap

通过实际的间距比例、语义化颜色、响应式网格和组件 API 使用 Bootstrap 5.3.8。体验可用的预约表单、错误摘要、表格筛选器、模态框和色彩模式切换，然后复用文档中的代码。


- [实现参考](https://webawesome.com/docs/customizing)
- [来源](https://webawesome.com/docs/tokens/)
- [阅读配套规范](https://webawesome.com/docs/usage)
- [阅读配套规范](https://webawesome.com/docs/tokens/)
- [阅读配套规范](https://webawesome.com/docs/customizing)
- [阅读配套规范](https://webawesome.com/docs/components/select/)
- [阅读配套规范](https://webawesome.com/docs/components/input/)
- [阅读配套规范](https://webawesome.com/docs/)
- [代码参考](https://webawesome.com/docs/components/select/)
- [代码参考](https://webawesome.com/docs)
- [代码参考](https://webawesome.com/docs/customizing)
- [代码参考](https://webawesome.com/)
- [安装 npm/dist 与 dist-cdn，以及必需的主题。](https://webawesome.com/docs/)
- [设计令牌 主题令牌类别。](https://webawesome.com/docs/tokens/)
- [自定义 自定义属性与 Shadow DOM 边界。](https://webawesome.com/docs/customizing)
- [Select 选项、值和初始选中项。](https://webawesome.com/docs/components/select/)
- [输入 验证 API。](https://webawesome.com/docs/components/input/)
- [Switch 布尔型自定义元素。](https://webawesome.com/docs/components/switch/)