01 Web Awesome 设计系统界面预览 更改圆角和间距缩放比例、切换示例外观、选择区域,并验证本地工作区名称。
原生 Web Awesome 3.14.0 自定义元素和默认主题,本地打包。·
实现参考 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 版本,只使用公开程序包中提供的组件。
页面中可见的控件都是真正的自定义元素,包括其影子根实现。周围的页眉、分区和读数则是原创的 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。示例的内边距、间隔和读数间距使用官方间距令牌,因此它们的比例关系会一起变化。这并不意味着每个组件的所有尺寸都会缩放:组件控件尺寸遵循各自的令牌关系。编辑面板不受此设置影响,因此在示例变化时仍可稳定对照。
选择“方形”,检查输入框、容器和读数的圆角。 选择“宽松间距”,对比示例中的间隔与保持不变的编辑面板。 恢复默认值,一并还原两个乘数和外观。 阅读配套规范
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 类,不要更改页面的其他内容。确保可见的令牌读数与原生控件保持同步,并保留标签。请将此工作台用作检查工具,而非设备管理界面。 Web Awesome 3.14.0 公共组件和默认主题。布局选择为原创设计;本地名称应用不会创建工作区或存储数据。