Web 组件系统 · 新资源

Web Awesome 设计系统.

检查 Web Awesome 在原生自定义元素中的实际语义令牌,包括作用域内的圆角和间距调整、Shadow DOM 样式、选择控件行为和输入验证。

OpenDesign 指南9 个章节37 条参考条目原始应用指南
01

Web Awesome 设计系统界面预览

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

限定范围的设计令牌工作台打开完整示例
原生 Web Awesome 3.14.0 自定义元素和默认主题,本地打包。· 实现参考
02

Web Awesome 设计系统设计参考

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

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

来源
名称 / 规则值 / 配置用途
--wa-color-surface-defaultwhite主要示例界面表面。
--wa-color-surface-raisedwhite凸起层。
--wa-color-surface-loweredvar(--wa-color-neutral-95)代码读数表面。
--wa-color-surface-bordervar(--wa-color-neutral-90)容器边界。
--wa-color-text-normalvar(--wa-color-neutral-10)常规文本。
--wa-color-text-quietvar(--wa-color-neutral-40)次要文本。
--wa-color-text-linkvar(--wa-color-brand-40)链接角色。
--wa-color-brand-fill-loudvar(--wa-color-brand-50)强品牌色填充。
--wa-color-brand-on-loudwhite强品牌色填充上的文本。
--wa-color-brand-fill-quietvar(--wa-color-brand-95)克制徽标填充。
--wa-color-brand-on-quietvar(--wa-color-brand-40)克制品牌色填充上的文本。

间距与形状

来源
名称 / 规则值 / 配置用途
--wa-space-scale1间距设计令牌使用的乘数。
--wa-space-xscalc(var(--wa-space-scale) * 0.5rem)默认缩放比例下为 8px。
--wa-space-scalc(var(--wa-space-scale) * 0.75rem)默认缩放比例下为 12px。
--wa-space-mcalc(var(--wa-space-scale) * 1rem)默认缩放比例下为 16px。
--wa-space-lcalc(var(--wa-space-scale) * 1.5rem)默认缩放比例下为 24px。
--wa-space-xlcalc(var(--wa-space-scale) * 2rem)默认缩放比例下为 32px。
--wa-space-2xlcalc(var(--wa-space-scale) * 2.5rem)默认缩放比例下为 40px。
--wa-border-radius-scale1可缩放圆角使用的乘数。
--wa-border-radius-scalc(var(--wa-border-radius-scale) * 0.1875rem)默认缩放比例下为 3px。
--wa-border-radius-mcalc(var(--wa-border-radius-scale) * 0.375rem)默认缩放比例下为 6px。
--wa-border-radius-lcalc(var(--wa-border-radius-scale) * 0.75rem)默认缩放比例下为 12px。

排版

来源
名称 / 规则值 / 配置用途
--wa-font-family-bodyui-sans-serif, system-ui, sans-serif正文系统无衬线字体。
--wa-font-family-headingvar(--wa-font-family-body)标题字体族别名。
--wa-font-family-codeui-monospace, monospace等宽读数。
--wa-font-size-scale1字号缩放乘数。
--wa-font-size-mcalc(1rem * var(--wa-font-size-scale))默认根字号和缩放比例下为 16px。
--wa-font-size-lround(calc(var(--wa-font-size-m) * 1.125 * 1.125), 1px)默认根字号和缩放比例下为 20px。
--wa-font-size-xlround(calc(var(--wa-font-size-l) * 1.125 * 1.125), 1px)默认根字号和缩放比例下为 25px。
--wa-font-size-2xlround(calc(var(--wa-font-size-xl) * 1.125 * 1.125), 1px)默认根字号和缩放比例下为 32px。
--wa-line-height-condensed1.2窄体标题/标签。
--wa-line-height-normal1.6常规阅读行高。

表单控件别名

来源
名称 / 规则值 / 配置用途
--wa-form-control-background-colorvar(--wa-color-surface-default)输入框表面别名。
--wa-form-control-border-colorvar(--wa-color-neutral-border-loud)输入框边界角色。
--wa-form-control-border-radiusvar(--wa-border-radius-m)字段圆角别名。
--wa-form-control-label-colorvar(--wa-color-text-normal)无障碍标签颜色。
--wa-form-control-hint-colorvar(--wa-color-text-quiet)提示颜色别名。
03

Web Awesome 设计系统完整指南

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

DESIGN-web-awesome.md

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

下载指南

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

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

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

摘自本 OpenDesign 指南

页面中可见的控件都是真正的自定义元素,包括其影子根实现。周围的页眉、分区和读数则是原创的 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/[email protected],并使用提供的 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 组合使用。

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 属性进行选择。
  • 仅使用免费组件。

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

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

javascript
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 会使用与原生自定义元素继承自同一主题的变量。

css
*{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 根文档。

html
<!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。
04

Web Awesome 设计系统 AI Agent 配置

实现起点

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

javascript
// Create a Vite vanilla project, then install:
// npm install @awesome.me/[email protected]
// 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.

适用于你项目的提示词

Agent 提示词
使用 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 类,不要更改页面的其他内容。确保可见的令牌读数与原生控件保持同步,并保留标签。请将此工作台用作检查工具,而非设备管理界面。
05

Web Awesome 设计系统来源与范围

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