前台设计规范与验证清单
适用范围：当前适配 Halo 2.26.0 及以上版本的言答Issue。旧版插件的界面与构建方式可能不同。
本项目将 shadcn/ui 的视觉规范应用于 Thymeleaf + Alpine 前台页面，继续使用现有的 Vite / Tailwind 3 构建。前台不依赖 React，也不执行上游文档中的新建 React 工程或安装全部组件步骤。
下载的官方参考
2026-10-25 从 shadcn-ui/ui 官方仓库下载：
- 设计系统规则原文：变量、尺寸、组件变体和检查方法。
- 主题与语义变量原文：背景/前景配对、明暗模式和圆角规范。
docs/design/reference/sources.json中记录的来源与 Git blob 标识。- 上游 MIT 许可证。
reference/ 保留下载原文；本文件记录适用于当前插件的实施约定。上游文件可能讨论其他框架和脚手架，不作为本仓库的迁移或依赖安装指令。
本项目采用的规则
| 项目 | 规则 |
|---|---|
| 视觉方向 | Neutral / Zinc 中性灰；黑白主操作；状态保留语义色 |
| 背景层级 | 页面、卡片、菜单使用配对的背景/前景变量；弱信息使用 muted |
| 按钮 | primary、outline、ghost 三种变体；桌面高度 36px，手机至少 40px |
| 输入框 | 40px 高度、1px 边框、6px 圆角；手机字体 16px，避免输入时自动放大 |
| 卡片 | 10px 圆角、1px 边框、极轻阴影；内容内边距 20px |
| 版式 | 页面内边距 16–32px；区块间距 24–28px；最大内容宽度 1200px |
| 字号 | 页面标题 24–28px；正文/操作 14px；辅助信息 12px |
| 图标 | 新增界面优先 Lucide；图标使用 16–20px；不依赖装饰插画表达空状态 |
| 统计 | 清晰的标签与数字；等宽数字；无花环、渐变或排名装饰 |
| 焦点 | 保留可见 focus ring；按钮和链接支持键盘访问 |
| 弹窗 | 原生 dialog：焦点限制、Esc 关闭、关闭后焦点返回；避免依赖悬停 |
| 动效 | 150ms 颜色变化；尊重 prefers-reduced-motion；无布局位移动效 |
实现入口
packages/issue-static/src/styles/tokens.css：明暗模式默认值。packages/issue-static/src/styles/layout.css：页面容器、标题、栅格和响应式结构。packages/issue-static/src/styles/components.css：按钮、卡片、Tabs、表单、菜单和 dialog。src/main/resources/templates/fragments/pages/：四个公共页面正文。
所有颜色变量与样式均使用 piw 命名或 .piw-app 作用域。不要将 shadcn 的全局 :root、--background 等直接粘贴到主题，否则可能影响站点的其他组件。
新增组件应使用 .piw-button / .piw-card / .piw-caption 等现有语义类，避免再次堆叠独立的背景、圆角和阴影值。静态模板中的任意 Tailwind 工具类必须保留 piw- 前缀。
主题覆盖颜色及复用页面的方法见 主题开发文档。
提交前检查
- 构建日志包含
:issue-static:pnpmBuild；JAR 内存在static/webAssets/style.css、main.iife.js。 - 主题支持布局时只出现一组主题页头/页脚和一个页面标题；没有布局时 fallback 可渲染。
- 检查主体、列表、详情、创建四页；包括匿名登录跳转、空列表、搜索、模板弹窗、评论编辑。
- 检查 375px 手机宽度、桌面、暗色模式，主题页面自身的按钮和字体不应被插件 preflight 改写。
- 浏览器控制台没有
piw* is not defined或 Alpine 重复启动错误。