设计令牌与组件清单

PVQ-UI 设计令牌与组件清单（模块文档 / 组件 API 说明）

状态：组件 API 人类可读说明（库 1.2.0）机器可读唯一真源：site/inc/components.json（官网画廊数据驱动，新增组件只改 JSON，画廊自动出现）。本文件引用 JSON，不再手抄示例。用途：人类查阅组件 API / 设计令牌；判断"某组件是否已存在"以 components.json 为准。关联：《PVQ-UI项目规则.md》（铁律，§2.3 定义 JSON 为唯一真源）、《PVQ-UI组件库开发方案.md》§3.5（架构）、《组件提取对照表.md》（旧→新映射）、《PVQ-UI组件库调用手册.md》（插件实操）

0. 文档地位

本文件是 pvq-ui 组件 API 的人类可读说明；机器可读的唯一真源是 site/inc/components.json（含组件 id / 名称 / 层 / 稳定性 / 示例 HTML，官网画廊遍历它渲染）。
任何"这个组件库有没有 / 叫什么类"的问题，以 components.json 为准；它里面没有的，才进入"新增组件"流程（先文档 → 再代码，见《PVQ-UI项目规则》§1）。本文件的示例仅作阅读参考，真值随 JSON 同步。
稳定性标记：stable（承诺不破坏改）/ experimental（接口可能调整，引用建议锁版本）。首版基线全部 stable。

1. 当前库版本

1.2.0。在 1.1.2 基础上新增删除按钮二次确认（data-pvq-confirm，破坏性操作防护，1.2.0 新增）。1.1.x 演进：1.1.0 选择器 Select、1.1.1 Tabs 胶囊化、1.1.2 Tabs 淡边框对齐 pvq-wp。旧插件名仅在《组件提取对照表.md》§6 作为迁移映射出现。
旧插件名（.pvq-btn-primary、.pvq-card-header、.pvq-connection-status 等）不在本表，仅在《组件提取对照表.md》§6 作为迁移映射出现。

2. 设计令牌（`:root` 全集，base 层 `pvq-ui.css`）

取值以 wolai admin-settings.css:11-62 为基线；标注【合并】的为从 pvq-wp / threads 吸收（库首版新增）。库是纯令牌提供方，不假设 --pvq-theme-* 存在。令牌只加不删（见《项目规则》§2.4）。

2.1 主色系（森林绿）

令牌	值	说明
`--pvq-primary`	`#608062`	主色
`--pvq-primary-hover`	`#4f6b51`	主色 hover
`--pvq-primary-light`	`rgba(96,128,98,0.08)`	主色浅底
`--pvq-primary-soft`	`rgba(96,128,98,0.12)`	主色柔底
`--pvq-primary-glow`	`rgba(96,128,98,0.20)`	主色辉光（focus / 阴影）
`--pvq-primary-gradient`	`linear-gradient(135deg,#608062,#7a9e7c)`	主色渐变
`--pvq-primary-gradient-hover`	`linear-gradient(135deg,#4f6b51,#6b8e6d)`	主色渐变 hover

2.2 语义色

令牌	值	说明
`--pvq-success`	`#4a8c5c`	成功
`--pvq-success-light`	`rgba(74,140,92,0.08)`	成功浅底
`--pvq-danger`	`#c45454`	危险
`--pvq-danger-light`	`rgba(196,84,84,0.08)`	危险浅底
`--pvq-warning`	`#c49a2e`	警告
`--pvq-warning-light`	`rgba(196,154,46,0.08)`	警告浅底
`--pvq-info`	`#5a8a9a`	信息
`--pvq-info-light`	`rgba(90,138,154,0.08)`	信息浅底

2.3 中性色

令牌	值	说明
`--pvq-bg`	`#f4f5f2`	页面背景
`--pvq-surface`	`#ffffff`	卡片 / 表面
`--pvq-surface-hover`	`#fafaf8`	表面 hover
`--pvq-border`	`#dfe3dc`	边框
`--pvq-border-light`	`#eaecea`	浅边框 / 分隔
`--pvq-text`	`#1e2a1f`	主文本
`--pvq-text-secondary`	`#5c6b5e`	次文本
`--pvq-text-muted`	`#94a396`	弱文本

2.4 圆角

令牌	值
`--pvq-radius-sm`	`8px`
`--pvq-radius`	`12px`
`--pvq-radius-lg`	`16px`
`--pvq-radius-xl`	`20px`
`--pvq-radius-pill`【合并 pvq-wp】	`999px`

2.5 阴影

令牌	值
`--pvq-shadow-sm`	`0 1px 3px rgba(30,42,31,0.04)`
`--pvq-shadow`	`0 2px 8px rgba(30,42,31,0.06)`
`--pvq-shadow-md`	`0 4px 20px rgba(30,42,31,0.08)`
`--pvq-shadow-lg`	`0 8px 32px rgba(30,42,31,0.12)`
`--pvq-shadow-primary`	`0 4px 16px rgba(96,128,98,0.25)`

2.6 缓动与过渡

令牌	值
`--pvq-ease`	`cubic-bezier(0.4,0,0.2,1)`
`--pvq-ease-bounce`	`cubic-bezier(0.34,1.56,0.64,1)`
`--pvq-ease-magnet`	`cubic-bezier(0.34,1.3,0.55,1)`
`--pvq-ease-smooth`	`cubic-bezier(0.25,0.1,0.25,1)`
`--pvq-transition`	`all 0.25s var(--pvq-ease)`
`--pvq-transition-fast`	`all 0.15s var(--pvq-ease)`
`--pvq-transition-slow`	`all 0.4s var(--pvq-ease-smooth)`

2.7 尺寸补充

令牌	值	说明
`--pvq-input-h`【合并 threads】	`40px`	输入控件高度基准

3. 组件清单（按层）

层说明：pvq-ui(base) 全场景；pvq-ui-admin / pvq-ui-editor / pvq-ui-frontend 为场景层，依赖 base。

3.1 Base 层（`pvq-ui.css`）

按钮 Button · `stable`

类：.pvq-btn
修饰符：--primary --secondary --danger --warning --ghost --sm --icon
组合：.pvq-btn-group（按钮组，右对齐）
删除按钮：复用 .pvq-btn--danger + fa-trash 图标；破坏性操作建议加 data-pvq-confirm 二次确认（见下「删除按钮二次确认」）

示例：

<button class="pvq-btn pvq-btn--primary"><i class="fas fa-save"></i> 保存</button>
<div class="pvq-btn-group">
  <button class="pvq-btn pvq-btn--secondary">取消</button>
  <button class="pvq-btn pvq-btn--primary">保存</button>
</div>
<!-- 删除按钮：文字版 / 图标-only 版 / 小号版 -->
<button class="pvq-btn pvq-btn--danger"><i class="fas fa-trash"></i> 删除</button>
<button class="pvq-btn pvq-btn--danger pvq-btn--icon"><i class="fas fa-trash"></i></button>
<button class="pvq-btn pvq-btn--danger pvq-btn--sm"><i class="fas fa-trash"></i> 删除</button>

删除按钮二次确认（破坏性操作防护）· `stable`（1.2.0 新增行为）

行为：给任意按钮加 data-pvq-confirm="确认文案"，库 JS 接管二次确认，避免误触删除 / 整页表单提交。任意 .pvq-btn（不限于 danger）均可加。
交互（库 JS，捕获阶段 preventDefault + stopPropagation，见下「WordPress 注意」）：
1. 首次点击：仅进入「确认态」——按钮就地变为实色危险红（.pvq-btn--armed）+ 文案替换为确认语（如「确定删除？」），不触发原行为；设 3 秒自动取消。
2. 确认态内再次点击：恢复外观并放行原行为（表单提交 / 插件自有 click 监听照常执行）。
3. 超时（3s）/ 按 Esc / 点击页面其它处：自动取消，恢复原样。
修饰符：.pvq-btn--armed（确认态实色红，库自动加 / 去，插件勿手写）。

示例：

<button class="pvq-btn pvq-btn--danger" data-pvq-confirm="确定删除该项？">
  <i class="fas fa-trash"></i> 删除
</button>

WordPress 注意：若按钮位于 WP <form> 内（如 upload.php），首次点击由库在捕获阶段 preventDefault，避免整页重载；确认态内第二次点击才放行。插件无需额外处理。
设计意图：破坏性操作统一防护，各插件不重复造轮子；纯 data-* 增强，不破坏既有按钮样式与提交逻辑。

卡片 Card · `stable`

类：.pvq-card
子元素：.pvq-card__header .pvq-card__icon .pvq-card__icon--{primary,success,warning,info,danger} .pvq-card__title .pvq-card__desc .pvq-card__action

示例：

<div class="pvq-card">
  <div class="pvq-card__header">
    <span class="pvq-card__icon pvq-card__icon--primary"><i class="fas fa-cog"></i></span>
    <div>
      <h3 class="pvq-card__title">连接设置</h3>
      <p class="pvq-card__desc">配置账号信息</p>
    </div>
  </div>
  <div class="pvq-card__action">
    <button class="pvq-btn pvq-btn--primary">保存</button>
  </div>
</div>

表单 Field / Input · `stable`

类：.pvq-field .pvq-field__label .pvq-field__help .pvq-input .pvq-input__wrap .pvq-input__wrap--has-icon .pvq-input__icon .pvq-input__toggle

示例：

<div class="pvq-field">
  <label class="pvq-field__label">API Token</label>
  <div class="pvq-input__wrap pvq-input__wrap--has-icon">
    <i class="pvq-input__icon fas fa-key"></i>
    <input class="pvq-input" type="text" placeholder="请输入">
  </div>
  <p class="pvq-field__help">在设置页获取你的 Token。</p>
</div>

选择器 Select（自定义下拉，渐进增强原生 select）· `experimental`

类：.pvq-select（包裹原生 <select>，库自动初始化）.pvq-select__trigger .pvq-select__text .pvq-select__arrow .pvq-select__dropdown .pvq-select__option .pvq-select--open .pvq-select__option--selected .pvq-select__option--disabled
结构：.pvq-select 内放一个原生 <select>（保留其 name/value/disabled，表单照常提交）；库 JS 自动把它增强为自定义下拉，原生 select 仅视觉隐藏、DOM 仍存在，选中即同步原生 select 的 value 并派发 change。
交互（库 JS，原生事件委托、无 jQuery）：点击 trigger 开/关；打开时箭头翻转、空间不足自动向上弹（flip）、右边界贴合、滚动/缩放重定位；键盘 Enter/Space 切换、ArrowDown 打开、Esc 关闭；点击外部关闭；同时只开一个。
可访问性：首版 experimental 为简易键盘（trigger tabindex=0 + Enter/Space/Esc），role=listbox/option、aria-expanded、方向键在选项间移动留待 stable 时补齐。
下拉面板挂 <body>（position:fixed）：为绕过 WP metabox 的 overflow:hidden 裁剪，非 jQuery 特性，原生版同样如此。

示例：

<div class="pvq-select">
  <select name="threads_sync_settings[mode]">
    <option value="auto">自动同步</option>
    <option value="manual" selected>手动同步</option>
    <option value="off">关闭</option>
  </select>
</div>

开关 Switch（语义化，纯 CSS）· `stable`

结构：.pvq-switch 包 <input type="checkbox" class="pvq-switch__input"> + <span class="pvq-switch__slider">
行布局：.pvq-switch-row .pvq-switch-row__label .pvq-switch-row__desc
行为：纯 CSS，由 :checked 控制，零 JS；可访问性最好（真实 checkbox）。

示例：

<div class="pvq-switch-row">
  <div>
    <div class="pvq-switch-row__label">启用同步</div>
    <div class="pvq-switch-row__desc">开启后自动同步内容</div>
  </div>
  <label class="pvq-switch">
    <input type="checkbox" class="pvq-switch__input" checked>
    <span class="pvq-switch__slider"></span>
  </label>
</div>

状态指示 Status · `stable`

类：.pvq-status --{success,warning,error} .pvq-status__dot
示例：<span class="pvq-status pvq-status--success"><span class="pvq-status__dot"></span> 已连接</span>

徽标 Badge · `stable`【新增】

类：.pvq-badge；可选修饰符 --primary 等（默认主色浅底）
示例：<span class="pvq-badge">v1.3.18</span>

横幅 Banner（原 connection-status）· `stable`

类：.pvq-banner --{success,danger,warning,info} .pvq-banner__dot .pvq-banner__title .pvq-banner__text
映射：connected→--success、disconnected→--danger、unconfigured→--warning

示例：

<div class="pvq-banner pvq-banner--success">
  <span class="pvq-banner__dot"></span>
  <div><div class="pvq-banner__title">已连接</div><div class="pvq-banner__text">账号验证通过</div></div>
</div>

提示 Alert（原 test-result）· `stable`

类：.pvq-alert --{success,error,loading} + 显隐类 .pvq-alert--show
示例：<div class="pvq-alert pvq-alert--show pvq-alert--success"><i class="fas fa-check"></i> 测试通过</div>

统计 Stat（原 cache-stat）· `stable`

类：.pvq-stat-grid .pvq-stat .pvq-stat__value .pvq-stat__label

示例：

<div class="pvq-stat-grid">
  <div class="pvq-stat"><div class="pvq-stat__value">128</div><div class="pvq-stat__label">已同步</div></div>
  <div class="pvq-stat"><div class="pvq-stat__value">12</div><div class="pvq-stat__label">待处理</div></div>
</div>

帮助 Help（原 help-card）· `stable`

类：.pvq-help .pvq-help__icon .pvq-help__title .pvq-help__text

示例：

<div class="pvq-help">
  <i class="pvq-help__icon fas fa-lightbulb"></i>
  <div><div class="pvq-help__title">小贴士</div><div class="pvq-help__text">首次使用请先配置 Token。</div></div>
</div>

范围 Range · `stable`（场景层 admin 引用，见 §3.2）

类：.pvq-range .pvq-range__group .pvq-range__value .pvq-range__labels

示例：

<div class="pvq-range__group">
  <input type="range" class="pvq-range" min="1" max="100" value="50">
  <span class="pvq-range__value">50</span>
</div>
<div class="pvq-range__labels"><span>慢</span><span>快</span></div>

分隔 Divider · `stable`

类：.pvq-divider

转圈 Spinner · `stable`

类：.pvq-spinner；动画 @keyframes pvq-spin

元信息列表 Meta-list（原 system-info）· `stable`

类：.pvq-meta-list .pvq-meta-list__row .pvq-meta-list__key .pvq-meta-list__value .pvq-meta-list__value--{ok,bad}

示例：

<div class="pvq-meta-list">
  <div class="pvq-meta-list__row"><span class="pvq-meta-list__key">PHP</span><span class="pvq-meta-list__value pvq-meta-list__value--ok">8.1</span></div>
</div>

动画 Animations · `stable`

@keyframes pvq-spin（转圈）、pvq-pulse（状态点）、pvq-shimmer（光泽）、pvq-slideDown/Up、pvq-cardEnter、pvq-tabEnter、pvq-iconBounce、pvq-badgePulse、pvq-resultSlide、pvq-logoAppear、pvq-lightbulb、pvq-detectBarEnter
base 层另含 @media (prefers-reduced-motion: reduce) 全局降级。

3.2 Admin 层（`pvq-ui-admin.css`）

设置页骨架 Settings · `stable`

类：.pvq-settings .pvq-settings__header .pvq-settings__logo .pvq-settings__title-group .pvq-settings__title .pvq-settings__subtitle .pvq-settings__version-badge .pvq-settings__footer .pvq-settings__footer-info .pvq-settings__footer-links .pvq-settings__footer-link .pvq-settings__footer-link--disabled

选项卡 + 磁吸滑块 Tabs · `stable`

类：.pvq-tabs .pvq-tabs__slider .pvq-tab .pvq-tab--active .pvq-tab__icon .pvq-tab-content .pvq-tab-content--active
交互：库 JS 委托点击切换 + 移动滑块（见《调用手册》§5）。
形态：分段控件式胶囊（pill）。容器 .pvq-tabs、磁吸滑块 .pvq-tabs__slider、tab .pvq-tab 均为全圆角（--pvq-radius-pill: 999px）；容器 width: fit-content 紧凑跟随内容（不撑满整行）、1px --pvq-border-light 淡边框（与 pvq-wp 一致）；激活态靠滑块主色渐变垫底、文字白，未激活灰字、hover 浅主色底。JS 仅按 offsetLeft/offsetWidth 定位滑块，圆角变化不影响逻辑。参考 pvq-wp 选项卡实现（1.1.1 起由矩形圆角改为胶囊，1.1.2 起边框对齐 pvq-wp 淡边框）。

示例：

<div class="pvq-tabs">
  <span class="pvq-tabs__slider"></span>
  <button class="pvq-tab pvq-tab--active" data-pvq-tab="general"><i class="pvq-tab__icon fas fa-cog"></i> 常规</button>
  <button class="pvq-tab" data-pvq-tab="advanced"><i class="pvq-tab__icon fas fa-sliders-h"></i> 高级</button>
</div>
<div class="pvq-tab-content pvq-tab-content--active" data-pvq-tab-panel="general">…</div>
<div class="pvq-tab-content" data-pvq-tab-panel="advanced">…</div>

范围 Range · `stable`（见 §3.1，admin 设置页常用，随 admin 层提供）

3.3 Editor 层（`pvq-ui-editor.css`）

块骨架 Block · `stable`

类：.pvq-block-placeholder .pvq-block-loading .pvq-block-empty .pvq-block-preview .pvq-block-frame
说明：通用块编辑占位 / 加载 / 空态 / 预览 / 边框，供各插件块复用。

3.4 Frontend 层（`pvq-ui-frontend.css`）

内容组件 · `stable`

类：.pvq-callout .pvq-callout__icon .pvq-callout__content .pvq-quote .pvq-prose
说明：前端通用内容展示（提示框 / 引用 / 正文排版）。

4. 不在库内（留在插件自有）

以下强绑定各自数据模型 / 业务逻辑，不进库，但要求改用 --pvq-* 令牌保持一致风格：

wolai 专有：.pvq-wolai-*、.pvq-token-info、.pvq-detect-bar、.pvq-status-available/-unavailable、.pvq-wolai-callout 等。
各插件业务逻辑专有样式，留在插件，不回流库。

5. 新增组件流程（库增量贡献）

先查本表确认不存在。
在 doc/开发文档/ 或本表写组件条目（API / 类 / 令牌 / 示例），先标 experimental。
写 CSS/JS（BEM 双横线、统一令牌、pvq- 动画前缀）。
bump 版本（MINOR），同步 CHANGELOG.md 与 readme.md（版本三处同步）。
经 1~2 个插件验证后，本表稳定性改为 stable。

详见《PVQ-UI项目规则.md》§1、§5、§8 与《库演进治理方案.md》§4。

文档

PVQ-UI 设计令牌与组件清单（模块文档 / 组件 API 说明）

0. 文档地位

1. 当前库版本

2. 设计令牌（:root 全集，base 层 pvq-ui.css）

2.1 主色系（森林绿）

2.2 语义色

2.3 中性色

2.4 圆角

2.5 阴影

2.6 缓动与过渡

2.7 尺寸补充

3. 组件清单（按层）

3.1 Base 层（pvq-ui.css）

按钮 Button · stable

删除按钮二次确认（破坏性操作防护）· stable（1.2.0 新增行为）

卡片 Card · stable

表单 Field / Input · stable

选择器 Select（自定义下拉，渐进增强原生 select）· experimental

开关 Switch（语义化，纯 CSS）· stable

状态指示 Status · stable

徽标 Badge · stable【新增】

横幅 Banner（原 connection-status）· stable

提示 Alert（原 test-result）· stable

统计 Stat（原 cache-stat）· stable

帮助 Help（原 help-card）· stable

范围 Range · stable（场景层 admin 引用，见 §3.2）

分隔 Divider · stable

转圈 Spinner · stable

元信息列表 Meta-list（原 system-info）· stable

动画 Animations · stable

3.2 Admin 层（pvq-ui-admin.css）

设置页骨架 Settings · stable

选项卡 + 磁吸滑块 Tabs · stable

范围 Range · stable（见 §3.1，admin 设置页常用，随 admin 层提供）

3.3 Editor 层（pvq-ui-editor.css）

块骨架 Block · stable

3.4 Frontend 层（pvq-ui-frontend.css）

内容组件 · stable

4. 不在库内（留在插件自有）

5. 新增组件流程（库增量贡献）

2. 设计令牌（`:root` 全集，base 层 `pvq-ui.css`）

3.1 Base 层（`pvq-ui.css`）

按钮 Button · `stable`

删除按钮二次确认（破坏性操作防护）· `stable`（1.2.0 新增行为）

卡片 Card · `stable`

表单 Field / Input · `stable`

选择器 Select（自定义下拉，渐进增强原生 select）· `experimental`

开关 Switch（语义化，纯 CSS）· `stable`

状态指示 Status · `stable`

徽标 Badge · `stable`【新增】

横幅 Banner（原 connection-status）· `stable`

提示 Alert（原 test-result）· `stable`

统计 Stat（原 cache-stat）· `stable`

帮助 Help（原 help-card）· `stable`

范围 Range · `stable`（场景层 admin 引用，见 §3.2）

分隔 Divider · `stable`

转圈 Spinner · `stable`

元信息列表 Meta-list（原 system-info）· `stable`

动画 Animations · `stable`

3.2 Admin 层（`pvq-ui-admin.css`）

设置页骨架 Settings · `stable`

选项卡 + 磁吸滑块 Tabs · `stable`

范围 Range · `stable`（见 §3.1，admin 设置页常用，随 admin 层提供）

3.3 Editor 层（`pvq-ui-editor.css`）

块骨架 Block · `stable`

3.4 Frontend 层（`pvq-ui-frontend.css`）

内容组件 · `stable`