1. 组件类型和设计优先级说明
- 组件类型：主按钮（Primary Button），包含默认、悬停、按下（激活）、禁用、加载态。
- 使用场景：页面或模块的首要行动（CTA），例如“提交”“保存”“继续”“购买”等。每个视图中应尽量只存在一个主按钮，避免视觉竞争。
- 设计优先级：
- 视觉一致性：统一色彩、形状、阴影、排版与间距；在不同平台与主题模式（浅色/深色）保持一致体验。
- 可用性：清晰的层级、足够的触控面积、明确的状态反馈、避免布局跳动。
- 可访问性：对比度、键盘可达性、焦点可见、低动画偏好支持、语义与ARIA正确使用。
- 性能优化：使用 GPU 加速的变换、避免重排与重绘、尽量用 CSS 动画、减少 DOM 与状态切换开销。
2. 视觉属性（颜色、字体、间距、尺寸等）
- 色彩（建议以设计令牌/变量管理，支持浅/深色主题）
- 浅色主题
- 背景（默认）：--primary-600
- 文本/图标：--on-primary（通常为白）
- 悬停背景：--primary-700
- 按下背景：--primary-800
- 禁用背景：--primary-300
- 禁用文本：--on-primary-disabled（白的 70% 不透明或灰）
- 焦点环：--focus-ring（高可见度蓝/品牌色）
- 深色主题
- 背景（默认）：--primary-500
- 悬停背景：--primary-600
- 按下背景：--primary-700
- 文本/图标：--on-primary-dark（通常为白）
- 禁用背景：--primary-400（降低饱和度/亮度）
- 焦点环：--focus-ring-dark
- 排版
- 字体族：系统字体栈（-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "PingFang SC", "Microsoft YaHei", sans-serif）
- 字重：600（Semibold）
- 字号：
- S：14px
- M：16px（默认）
- L：16px（大尺寸按钮建议依靠内边距扩大触控面积）
- 行高：1（按钮内文本垂直居中）
- 大小写：句式（首字母大写或按语言规范），避免全大写
- 尺寸与间距（触控最小目标≥44px）
- 高度：
- S：32px（桌面密度）
- M：40px（默认）
- L：48px（移动优先）
- 水平内边距（左右）：
- 最小宽度：64px；自适应文案长度，支持 text-overflow: ellipsis
- 图标与文本间距：8px
- 角半径：8px（可在多产品线中允许 6–12px 的可配置范围）
- 阴影（桌面，提升层级）
- 默认：微弱阴影（例如 0 1px 2px rgba(0,0,0,0.12)）
- 悬停：增强阴影（例如 0 2px 6px rgba(0,0,0,0.16)）
- 按下：减弱阴影（例如 0 1px 2px rgba(0,0,0,0.08)）
- 加载指示
- Spinner 尺寸：16px（随按钮字号缩放，建议使用 em）
- 位置：文本左侧或居中（推荐左侧，保留文本以减少无障碍困扰）
- 动画：旋转 600ms/周；在低动画偏好下禁用或降速
- 内容规范
- 文案简短明确，首要动词+对象（例如“提交表单”）
- 避免多行；超长时省略号处理并提供 tooltip（桌面）
3. 交互状态（默认、悬停、点击、禁用、加载态）
- 默认（rest）
- 背景：--primary-600（浅色主题）
- 文本/图标：--on-primary
- 阴影：弱
- 悬停（hover，桌面）
- 背景：--primary-700
- 阴影：增强
- 条件：仅在设备支持 hover 时启用（@media (hover: hover)）
- 聚焦（focus-visible，键盘）
- 焦点环：2px 实线，outline-offset: 2px，颜色为 --focus-ring
- 背景不变；确保与周围背景对比度≥3:1
- 按下（active/pressed）
- 背景：--primary-800
- 阴影：减弱
- 微动画：transform: scale(0.98) 或 translateY(1px)（在 reduced-motion 下禁用）
- 禁用（disabled）
- 背景：--primary-300（或降低不透明度）
- 文本：--on-primary-disabled
- 阴影：无；鼠标指针：not-allowed；不可聚焦
- 加载（loading）
- 状态：阻止重复点击；显示 spinner；文本保留或替换为“正在…”
- 语义：aria-busy="true"；按钮设置 disabled
- 动效：spinner 旋转；按钮不位移（预留 spinner 空间防止布局跳动）
4. 可访问性考虑（辅助功能、可读性、对比度等）
- 对比度
- 主按钮背景与文本对比度≥4.5:1（WCAG AA）
- 焦点环与周围背景≥3:1
- 禁用态可降低对比度，但文本仍应可辨识
- 键盘与屏幕阅读器
- 使用原生
- 焦点可见：:focus-visible 不移除；严禁用 outline: none 无替代
- 加载态：aria-busy="true"；更新按钮内部的状态文本并设置 aria-live="polite" 以提醒用户“正在提交…”
- 禁用态：使用 disabled 属性（原生不可聚焦）；避免仅使用 aria-disabled
- 动画与动效
- 支持 @media (prefers-reduced-motion: reduce)：禁用或降低动画速率，避免 scale/translate
- 触控目标
- 高度≥44px（移动）；点击区域至少与视觉尺寸一致
- 语言与国际化
- 多语言文案长度可变；文本溢出使用省略号并提供备用提示（桌面）
- 强制高对比模式（Windows）
- @media (forced-colors: active)：使用系统色 ButtonFace/ButtonText；保留焦点环 Highlight
- 图标与可见性
- 图标仅辅助；不可替代文本。加载 spinner 设置 aria-hidden="true"，避免重复朗读
5. 代码实现说明（HTML/CSS/JS示例或组件代码规范）
示例采用 CSS 变量作为设计令牌，支持浅/深色主题与多产品线复用。
<!-- 主按钮：默认（可含图标与加载状态） -->
<button class="btn btn-primary btn--md" type="button" aria-live="polite">
<span class="btn__spinner" aria-hidden="true"></span>
<span class="btn__label">提交</span>
<!-- 可选图标：放在文本左侧
<svg class="btn__icon" aria-hidden="true" ...></svg>
-->
<span class="sr-only" data-status></span> <!-- 用于 aria-live 通知 -->
</button>
/* 设计令牌（示例，可根据品牌调优） */
:root {
/* 浅色主题 */
--primary-300: #A5D3FF;
--primary-500: #2D8CFF;
--primary-600: #1E7AF8;
--primary-700: #136AE0;
--primary-800: #0D58BE;
--on-primary: #FFFFFF;
--on-primary-disabled: rgba(255,255,255,0.7);
--focus-ring: #1E7AF8; /* 或品牌辅助色 */
--shadow-weak: 0 1px 2px rgba(0,0,0,0.12);
--shadow-strong: 0 2px 6px rgba(0,0,0,0.16);
--spinner-size: 1em; /* 随字号缩放 */
--spinner-stroke: 2px;
}
/* 深色主题覆盖（示例） */
@media (prefers-color-scheme: dark) {
:root {
--primary-300: #5FA0E6;
--primary-500: #2D8CFF;
--primary-600: #1E7AF8;
--primary-700: #136AE0;
--primary-800: #0D58BE;
--on-primary: #FFFFFF;
--on-primary-disabled: rgba(255,255,255,0.65);
--focus-ring: #9BC9FF;
}
}
/* 基础按钮样式 */
.btn {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "PingFang SC", "Microsoft YaHei", sans-serif;
font-weight: 600;
line-height: 1;
border: none;
border-radius: 8px;
display: inline-flex;
align-items: center;
justify-content: center;
gap: 8px;
cursor: pointer;
user-select: none;
white-space: nowrap;
text-decoration: none;
transition: background-color 120ms ease, box-shadow 120ms ease, transform 60ms ease;
will-change: background-color, box-shadow, transform;
}
/* 尺寸 */
.btn--sm { font-size: 14px; height: 32px; padding: 0 12px; }
.btn--md { font-size: 16px; height: 40px; padding: 0 16px; }
.btn--lg { font-size: 16px; height: 48px; padding: 0 20px; }
/* 主按钮变体 */
.btn-primary {
background-color: var(--primary-600);
color: var(--on-primary);
box-shadow: var(--shadow-weak);
}
/* 悬停：仅在有 hover 能力设备启用 */
@media (hover: hover) {
.btn-primary:hover:not(:disabled):not([aria-busy="true"]) {
background-color: var(--primary-700);
box-shadow: var(--shadow-strong);
}
}
/* 聚焦可见 */
.btn-primary:focus-visible {
outline: 2px solid var(--focus-ring);
outline-offset: 2px;
}
/* 按下（激活） */
.btn-primary:active:not(:disabled):not([aria-busy="true"]) {
background-color: var(--primary-800);
box-shadow: var(--shadow-weak);
transform: scale(0.98);
}
/* 禁用 */
.btn-primary:disabled {
background-color: var(--primary-300);
color: var(--on-primary-disabled);
box-shadow: none;
cursor: not-allowed;
}
/* 文本溢出处理 */
.btn__label {
overflow: hidden;
text-overflow: ellipsis;
}
/* 预留 spinner 空间，避免布局跳动 */
.btn__spinner {
width: var(--spinner-size);
height: var(--spinner-size);
border-radius: 50%;
border: var(--spinner-stroke) solid rgba(255,255,255,0.35);
border-top-color: currentColor;
display: inline-block;
visibility: hidden; /* 默认不占位可改为 visibility 以保留空间 */
opacity: 0;
transition: opacity 120ms ease, visibility 0s linear 120ms;
}
/* 加载态样式：显示 spinner，禁用交互 */
.btn-primary[aria-busy="true"] {
pointer-events: none;
}
.btn-primary[aria-busy="true"] .btn__spinner {
visibility: visible;
opacity: 1;
animation: spin 600ms linear infinite;
transition: opacity 120ms ease;
}
@keyframes spin {
to { transform: rotate(360deg); }
}
/* 低动画偏好 */
@media (prefers-reduced-motion: reduce) {
.btn { transition: none; }
.btn-primary:active { transform: none; }
.btn__spinner { animation: none; }
}
/* 强制高对比模式兼容（Windows） */
@media (forced-colors: active) {
.btn-primary {
background: ButtonFace;
color: ButtonText;
box-shadow: none;
}
.btn-primary:focus-visible {
outline: 2px solid Highlight;
}
}
// 最小交互逻辑：加载态管理与无障碍提示
function setButtonLoading(btn, isLoading, statusText = '正在提交…') {
if (!(btn instanceof HTMLButtonElement)) return;
const statusNode = btn.querySelector('[data-status]');
const spinner = btn.querySelector('.btn__spinner');
if (isLoading) {
btn.setAttribute('aria-busy', 'true');
btn.disabled = true; // 防止重复点击
if (statusNode) statusNode.textContent = statusText; // aria-live=polite 将提示
if (spinner) spinner.style.visibility = 'visible'; // 如需强制保留空间可在 CSS 中始终可见但透明
} else {
btn.removeAttribute('aria-busy');
btn.disabled = false;
if (statusNode) statusNode.textContent = '';
if (spinner) {
spinner.style.visibility = ''; // 复位
}
}
}
// 使用示例
const submitBtn = document.querySelector('.btn-primary');
submitBtn?.addEventListener('click', async () => {
setButtonLoading(submitBtn, true, '正在提交…');
try {
// 执行异步操作
await new Promise(res => setTimeout(res, 1500));
// 成功后可更新文案或状态
} catch (e) {
// 失败处理：提示错误
} finally {
setButtonLoading(submitBtn, false);
}
});
代码规范与实现要点：
- 语义元素：使用原生
