@zmzai/theme 0.5.8 → 0.6.1

package/README.md

@@ -9,7 +9,7 @@ zmzai 全品牌设计系统 — Radix UI + framer-motion + Tailwind v4。v0.2.0
 ```bash
 pnpm add @zmzai/theme
 # or via git:
-pnpm add @zmzai/theme@github:Ulanxx/zmzai-theme
+pnpm add @zmzai/theme@github:zmzai-cloud/zmzai-theme
 ```
 
 ### Import tokens + fonts

package/docs/design-conventions.md

@@ -0,0 +1,50 @@
+# 设计约定（Design Conventions）
+
+> 2026-08-27 起。整合：交互取择表（源自 hallmark microinteractions 纪律）、反 AI 味检查清单、hallmark skill 的使用边界。
+> 与 `prefer-theme-components` 原则（UI 一律 @zmzai/theme 组件）配套执行。
+
+## 一、交互取择表（Tool-UI 场景）
+
+写交互时的默认选择——左边被否决时才允许用右边：
+
+| 默认采用 ✅ | 而不是 ❌ | 适用 |
+| --- | --- | --- |
+| 静默成功（状态自然变化） | 庆祝型 toast / 弹窗 | 所有操作反馈 |
+| 乐观更新 + Undo | 事前确认对话框 | 可逆操作（删除入回收站、重命名） |
+| 事前确认 | 乐观更新 | **不可逆**操作（真删数据、对外发布）——Undo 救不了的必须问 |
+| 就近内联错误（字段旁/卡片内） | 顶部全局 toast 报错 | 表单与工具卡 |
+| hover 提示延迟 800ms / focus 0ms | 两者都 0ms | Tooltip（防扫过闪烁） |
+| `prefers-reduced-motion: reduce` 全局降级 | 只做动画不管偏好 | 所有动效 |
+| 只动 `transform` / `opacity` | 动 layout 属性（width/top/margin） | 所有动效 |
+| `--ease-out`（入场）/ `--ease-in`（退场） | 浏览器默认 `ease`、bounce/overshoot | 所有过渡 |
+| 动效时长 ≤200ms（状态） / ≤400ms（进出场） | 更长 | 工具 UI 节奏 |
+| 裁剪：删掉不损失信息的动画就删 | 多多益善 | Review 时逐个问「删了会丢信息吗」 |
+
+**harness/工作台类界面专项**：消息流自动跟随滚动但不锁底（用户上翻即停，近底再恢复）；长任务用 terminal_read 式游标增量而非整段重渲染。
+
+## 二、反 AI 味检查清单（并入 design-review）
+
+每次 UI 批次过 review 时逐项检查，任一命中即退回：
+
+1. **斜体标题**——headings 一律 roman（`font-style: normal`）；强调用字重/accent 色/下划线，不用 `<em>`。
+2. **编造数据**——页面上的任何数字（用户数、百分比、"10×"）必须有真实来源；没有就放 `—` 占位并标注"数据待确认"，或者干脆换结构。
+3. **手绘假 chrome**——不画假浏览器栏（URL pill + 红绿灯）、假手机框、假 IDE 窗口包 `<pre>`；要么用真实截图（hairline 边框的 `<figure>`），要么裸内容。
+4. **模板节奏**——同仓两页不许共享 hero→3 特性→CTA→footer 的同一韵律；工具型界面豁免（一致性优先）。
+5. **未经 token 的即兴取值**——CSS 里出现内联 hex/oklch/rgb 或绕过 token 块的 `font-family: "某字体"`，一律改为引用命名 token。
+6. **假占位图冒充成品**——stock 图必须标 placeholder，不得当作最终交付。
+
+## 三、hallmark skill 使用边界（拍板 2026-08-27）
+
+| 场景 | 用法 | 约束 |
+| --- | --- | --- |
+| **叙事型新页面**（落地页、官网、产品介绍） | `hallmark redesign` / default Design flow 可用 | **token 只准指向 @zmzai/theme**；禁走 catalog 主题自选（会引入第二套 OKLCH + 字体配对，与 theme 冲突）；macrostructure 轮换照常 |
+| **工具型界面**（工作台、后台、harness） | 只用 audit / 反 AI 味清单 | 不进 Design flow（工具 UI 要一致性不要多样性） |
+| **任何 UI 的质检** | `hallmark audit` | 输出进 design-review 流程，与可用性审查并列 |
+| **参考站拆解** | `hallmark study` | 产出的 DNA 回写 theme 时走正常 token 变更（主应用 v0.6.0 荧光绿即 study 产物） |
+
+**权威序**：`@zmzai/theme` tokens > 各产品 globals.css 内联 token > 页面级样式。hallmark 在任何环节都不得越过第一级。
+
+## 四、违反后果
+
+- push main 前的约定检查（见 `prefer-theme-components` 记忆）把本文件第一、二节纳入检查范围；
+- 新组件 PR 缺 8 态矩阵行（states-discipline.md）不予合并。

package/docs/states-discipline.md

@@ -0,0 +1,36 @@
+# 组件状态纪律（States Discipline）
+
+> 来源：hallmark skill 的 8-state discipline，经 2026-08-27 评审吸收进 @zmzai/theme。
+> 自 v0.6.1 起执行。适用范围：**所有交互组件**（theme 仓内 + 各产品仓自建控件）。
+
+## 验收标准（8 态清单）
+
+每个交互组件必须对以下状态有**明确的设计决定**——要么有样式，要么有书面豁免理由（如纯装饰元素）。缺态 = 验收不通过。
+
+| 状态 | 载体 | 硬性要求 |
+| --- | --- | --- |
+| default | — | 基线样式 |
+| hover | `:hover` | 必须有可感知反馈（边框/背景/阴影任一），纯 `cursor` 不算 |
+| focus-visible | `:focus-visible` | **≥3:1 对比度的 ring，立即可见、禁止动画**。用 `ring-2 ring-ink ring-offset-2 ring-offset-bg`；绝不能用 `:focus` 代替（避免鼠标点击也出 ring） |
+| active | `:active` | 按压反馈统一 `active:scale-[0.98]`（按钮族）；不可缩的用背景加深 |
+| disabled | `disabled:` | `pointer-events-none opacity-40`（按钮）/ `cursor-not-allowed bg-surface text-ink-3`（输入族） |
+| loading | `data-state` / 组件内状态 | 由 `StatefulButton` 承担（spinner + 防重复点击） |
+| error | `aria-invalid` | 输入族：边框转 `border-danger`；按钮族：错误不落在按钮上，落在就近的错误文案区 |
+| success | `data-state` | 静默优先——成功不必庆祝，需要确认感的操作用 `StatefulButton` 的 checkmark 过渡（1.5s 自复位） |
+
+## 现状矩阵（v0.6.1 基线）
+
+| 组件 | default | hover | focus-visible | active | disabled | loading | error | success |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Button | ✅ | ✅ | ✅ 0.6.1 补 | ✅ 0.6.1 补齐 secondary/ghost | ✅ | via StatefulButton | 豁免（就近文案） | via StatefulButton |
+| Input / Textarea | ✅ | ✅ 0.6.1 补 | ✅ 0.6.1 补 | 豁免（输入不按压） | ✅ 0.6.1 补 | 豁免 | ✅ 0.6.1 补（aria-invalid） | 豁免 |
+| SelectTrigger | ✅ | ✅ | ✅ 0.6.1 补 | 豁免 | ✅ 0.6.1 补 | 豁免 | ✅ 0.6.1 补（aria-invalid） | 豁免 |
+| StatefulButton | ✅ | ✅ | ✅（继承 Button） | ✅ | ✅ | ✅ | ⚠️ **待补**：当前 catch 静默回 idle | ✅ |
+
+**待办**：StatefulButton 的 error 呈现（失败态停留 + 重试入口，不自动复位）——下个版本。
+
+## 新组件自查流程
+
+1. 写完组件后对照矩阵逐格打勾，打不了勾的写豁免理由进组件头注释；
+2. playground 里过一遍键盘 Tab 流（只看 focus-visible 是否全程可见）；
+3. `aria-invalid` / `data-state` 用真实表单校验驱动，不要手动塞 class。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmzai/theme",
-  "version": "0.5.8",
+  "version": "0.6.1",
   "private": false,
   "type": "module",
   "description": "zmzai 全品牌设计系统 — Radix UI + framer-motion + Tailwind v4 + MiSans",
@@ -56,6 +56,7 @@
   },
   "files": [
     "src",
+    "docs",
     "README.md",
     "LICENSE"
   ],

package/src/components/button/button.styles.ts

@@ -4,22 +4,33 @@ import { cva } from "class-variance-authority";
  * Button variant styles.
  *
  * Design:
- * - 锐角 2px（v0.2 暖纸风），hover 轻微缩放
+ * - 锐角 2px（v0.2 暖纸风沿用的锐利语言），hover 阴影 / active 微缩
  * - primary: black fill, white text, hover scale + shadow
  * - secondary: transparent, border, hover fill
  * - ghost: no border, subtle hover bg
+ * - danger: red fill
+ *
+ * States discipline (v0.6.1 起，见 docs/states-discipline.md):
+ * - focus-visible: 2px ink ring + offset，立即可见不做动画（键盘可达性硬性要求）
+ * - active: 所有可按压 variant 统一 scale 反馈（此前仅 primary/danger 有）
+ * - disabled: opacity-40 + pointer-events-none
+ * - loading/error/success 语义态由 StatefulButton 承担（error 呈现待补）
  */
 export const buttonVariants = cva(
-  "inline-flex cursor-pointer items-center justify-center gap-2 rounded-sm font-semibold transition-colors transition-transform disabled:pointer-events-none disabled:opacity-40 select-none",
+  [
+    "inline-flex cursor-pointer items-center justify-center gap-2 rounded-sm font-semibold transition-colors transition-transform select-none",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ink focus-visible:ring-offset-2 focus-visible:ring-offset-bg",
+    "disabled:pointer-events-none disabled:opacity-40",
+  ].join(" "),
   {
     variants: {
       variant: {
         primary:
           "bg-ink text-white hover:shadow-md active:scale-[0.98]",
         secondary:
-          "border border-line text-ink hover:border-ink hover:bg-surface-2",
+          "border border-line text-ink hover:border-ink hover:bg-surface-2 active:scale-[0.98]",
         ghost:
-          "text-ink-2 hover:bg-surface-2 hover:text-ink",
+          "text-ink-2 hover:bg-surface-2 hover:text-ink active:scale-[0.98]",
         danger:
           "bg-danger text-white hover:shadow-md active:scale-[0.98]",
       },

package/src/components/input/input.styles.ts

@@ -4,23 +4,31 @@ import { cva } from "class-variance-authority";
  * Input variant styles.
  *
  * Design:
- * - default: light border, focus turns border to ink
- * - brutal: 2px ink border + hard offset shadow (neobrutalism), focus shifts
+ * - default: light border, hover 提示可交互，focus turns border to ink
+ * - brutal: 2px ink border + hard offset shadow (neobrutalism)
+ *
+ * States discipline (v0.6.1 起，见 docs/states-discipline.md):
+ * - disabled: 灰化 + not-allowed 光标
+ * - aria-invalid: 边框转 danger（与 Radix/shadcn 惯例一致，业务层无需传额外 prop）
  */
 export const inputVariants = cva(
-  "w-full bg-bg font-sans text-ink placeholder:text-ink-3 outline-none transition-all",
+  [
+    "w-full bg-bg font-sans text-ink placeholder:text-ink-3 outline-none transition-all",
+    "focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-offset-bg disabled:cursor-not-allowed disabled:bg-surface disabled:text-ink-3",
+    "aria-invalid:border-danger aria-invalid:focus:border-danger",
+  ].join(" "),
   {
     variants: {
       variant: {
         default:
-          "border border-line rounded-sm px-4 py-2.5 text-sm focus:border-ink",
+          "h-10 border border-line rounded-sm px-4 text-sm hover:border-ink/40 focus:border-ink focus-visible:ring-ink",
         brutal:
-          "border-2 border-ink rounded-sm px-4 py-3 text-sm",
+          "h-10 border-2 border-ink rounded-sm px-4 text-sm focus-visible:ring-line-strong",
       },
       size: {
-        sm: "text-xs py-2 px-3",
-        md: "text-sm py-2.5 px-4",
-        lg: "text-base py-3 px-5",
+        sm: "h-8 text-xs px-3",
+        md: "h-10 text-sm px-4",
+        lg: "h-12 text-base px-5",
       },
     },
     defaultVariants: {

package/src/components/select/Select.tsx

@@ -18,8 +18,10 @@ export function SelectTrigger({
   return (
     <SelectPrimitive.Trigger
       className={cn(
-        "inline-flex h-9 items-center justify-between gap-2 rounded-sm border border-line bg-bg px-3 py-2 text-sm font-medium text-ink outline-none transition-colors",
+        "inline-flex h-10 items-center justify-between gap-2 rounded-sm border border-line bg-bg px-4 text-sm font-medium text-ink outline-none transition-colors",
         "hover:border-ink/40 focus:border-ink data-[placeholder]:text-ink-3",
+        "disabled:cursor-not-allowed disabled:bg-surface disabled:text-ink-3",
+        "aria-invalid:border-danger focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-offset-bg focus-visible:ring-ink",
         className
       )}
     >

package/src/tokens/theme.css

@@ -6,32 +6,33 @@
  *   @import "@zmzai/theme/tokens";
  *   @import "@zmzai/theme/fonts";
  *
- * v0.2.0 起为暖色杂志风（Warm paper, warm ink, seal-red accent），
- * 与 zmzai.cloud 主应用（Hallmark Study）同源。v0.1.x 是黑白
- * Monochrome 风，已废弃。
+ * v0.6.0 起为纯白 + 荧光绿（Pure white + fluorescent green），
+ * 与 zmzai.cloud 主应用（Hallmark Study）同源。
+ * v0.2.0~0.5.x 为暖色杂志风（Warm paper + seal-red，已弃用）。
+ * v0.1.x 黑白 Monochrome 风，更早废弃。
  */
 
 @theme {
   /* ===== Color =====
-     暖纸张底 + 暖墨字 + 印章红 accent（Hallmark Study 锁定）。
-     accent 用于强调/链接/审批等，red 系有印章感。 */
-  --color-bg:            oklch(0.95 0.012 85);
-  --color-surface:       oklch(0.97 0.008 85);
-  --color-surface-2:     oklch(0.92 0.014 80);
-  --color-ink:           oklch(0.18 0.011 40);
-  --color-ink-2:         oklch(0.47 0.013 55);
+     纯白底 + 荧光绿 accent（与 zmzai.cloud 主应用同源，Hallmark Study 锁定）。
+     accent 为荧光绿（oklch 0.78 0.220 142）；accent-ink 为深色（用于绿底上的字）。 */
+  --color-bg:            oklch(0.995 0.002 90);
+  --color-surface:       oklch(0.98 0.004 90);
+  --color-surface-2:     oklch(0.95 0.006 88);
+  --color-ink:           oklch(0.15 0.010 30);
+  --color-ink-2:         oklch(0.50 0.012 55);
   --color-ink-3:         oklch(0.55 0.012 55);
-  --color-line:          oklch(0.86 0.012 80);
-  --color-line-strong:   oklch(0.18 0.011 40);
-  --color-accent:        oklch(0.46 0.150 27);
-  --color-accent-ink:    oklch(0.97 0.008 85);
-  --color-success:       oklch(0.52 0.090 160);
-  --color-danger:        oklch(0.42 0.155 27);
-  --color-warning:       oklch(0.65 0.10 80);
+  --color-line:          oklch(0.90 0.005 88);
+  --color-line-strong:   oklch(0.15 0.010 30);
+  --color-accent:        oklch(0.78 0.220 142);
+  --color-accent-ink:    oklch(0.15 0.010 30);
+  --color-success:       oklch(0.72 0.180 145);
+  --color-danger:        oklch(0.55 0.200 25);
+  --color-warning:       oklch(0.80 0.150 90);
 
   /* Dark surface — 仅用于代码块/preview，不是全局 dark mode */
   --color-dark-bg:       #0A0A0A;
-  --color-dark-surface:  #171717;
+  --color-dark-surface:  #141414;
   --color-dark-ink:      #FAFAFA;
   --color-dark-line:     #27272A;
 
@@ -62,7 +63,7 @@
   --color-muted:         var(--color-ink-2);
   --color-rule:          var(--color-ink);
   --color-surface-strong: var(--color-surface-2);
-  --color-accent-strong: oklch(0.39 0.150 27);
+  --color-accent-strong: oklch(0.68 0.220 142);
   --animate-dur-fast:    150ms;
   --animate-dur-base:    250ms;
   --animate-dur-slow:    500ms;
@@ -100,8 +101,8 @@
   }
 
   ::selection {
-    background: var(--color-ink);
-    color: #fff;
+    background: var(--color-accent);
+    color: var(--color-accent-ink);
   }
 
   :focus-visible {