@zmzai/theme 0.6.0 → 0.7.0

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.6.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "zmzai 全品牌设计系统 — Radix UI + framer-motion + Tailwind v4 + MiSans",
@@ -56,9 +56,16 @@
   },
   "files": [
     "src",
+    "docs",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc --noEmit",
+    "playground": "vite playground --port 5174",
+    "prepublishOnly": "pnpm typecheck"
+  },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -98,9 +105,5 @@
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^2.5.0"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit",
-    "typecheck": "tsc --noEmit",
-    "playground": "vite playground --port 5174"
-  }
-}
+  "packageManager": "pnpm@10.34.5+sha512.a4ee05f2f73658255bd6a89859c065a45c28a57daefae2c893a168ee2b73168c37b91e83e57ea67654ad03f03031746430e8bce38e362e042605fb8abc80192e"
+}

package/src/components/app-shell/AppShell.tsx

@@ -0,0 +1,211 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import type { ComponentType, ReactNode } from "react";
+
+import { Badge } from "../badge/Badge";
+import { Icon, type IconName } from "../icon/Icon";
+import { CommandPalette, type AppPaletteItem } from "./CommandPalette";
+
+export type AppNavItem = { label: string; href: string; icon: IconName; keywords?: string };
+export type AppNavSection = { label: string; items: AppNavItem[] };
+export type { AppPaletteItem } from "./CommandPalette";
+
+/** 消费端注入的链接组件（Next.js 传 next/link 以保持 SPA 导航；缺省用 <a>）。 */
+export type AppShellLink = ComponentType<{
+  href: string;
+  className?: string;
+  children?: ReactNode;
+  onClick?: () => void;
+  "aria-current"?: "page" | undefined;
+}>;
+
+export function appShellIsActive(pathname: string, href: string): boolean {
+  return pathname === href || pathname.startsWith(`${href}/`);
+}
+
+/** 无 SPA 需求时的缺省链接：普通 <a>。 */
+function DefaultAnchor({ href, className, children, onClick, "aria-current": ariaCurrent }: { href: string; className?: string; children?: ReactNode; onClick?: () => void; "aria-current"?: "page" }) {
+  return (
+    <a href={href} className={className} onClick={onClick} aria-current={ariaCurrent}>
+      {children}
+    </a>
+  );
+}
+
+function SidebarSections({
+  sections,
+  pathname,
+  link: Link,
+  onNavigate,
+}: {
+  sections: AppNavSection[];
+  pathname: string;
+  link: AppShellLink;
+  onNavigate?: () => void;
+}) {
+  return (
+    <>
+      {sections.map((section) => (
+        <div key={section.label} className="flex flex-col gap-0.5">
+          <p className="px-2 pb-1 font-mono text-[10px] uppercase tracking-wider text-ink-3">{section.label}</p>
+          {section.items.map((item) => {
+            const active = appShellIsActive(pathname, item.href);
+            return (
+              <Link
+                key={item.href}
+                href={item.href}
+                onClick={onNavigate}
+                aria-current={active ? "page" : undefined}
+                className={`flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px] transition-colors ${
+                  active ? "bg-surface font-medium text-accent-readable" : "text-muted hover:bg-surface hover:text-accent"
+                }`}
+              >
+                <Icon name={item.icon} size={13} />
+                {item.label}
+              </Link>
+            );
+          })}
+        </div>
+      ))}
+    </>
+  );
+}
+
+/**
+ * 全站统一应用外壳（OpenRouter 式交互内核）：
+ * 全高左侧 sidebar（分组导航）+ 轻顶栏（标题 + ⌘K）+ 侧栏底部账户块。
+ * 站点无关：导航分组、品牌区、账户块、链接组件均由调用方注入；
+ * relay 的 RelayShell / sandbox 的 SandboxShell 是它的薄封装。
+ */
+export function AppShell({
+  brand,
+  sections,
+  pathname,
+  link,
+  account = null,
+  headerExtras = null,
+  paletteItems,
+  children,
+}: {
+  /** 品牌区：侧栏顶部与顶栏兜底标题 */
+  brand: { label: string; suffix?: string; href?: string };
+  /** 侧栏分组导航 */
+  sections: AppNavSection[];
+  /** 当前路径（消费端传 usePathname() ?? "/"；theme 不依赖 next） */
+  pathname: string;
+  /** 链接组件（Next.js 站传 next/link） */
+  link?: AppShellLink;
+  /** 侧栏底部账户块（登录按钮 / 用户信息） */
+  account?: ReactNode;
+  /** 顶栏右侧扩展（余额、状态等） */
+  headerExtras?: ReactNode;
+  /** ⌘K 命令面板条目；为空时顶栏不显示搜索按钮 */
+  paletteItems?: AppPaletteItem[];
+  children: ReactNode;
+}) {
+  const Link = (link ?? DefaultAnchor) as AppShellLink;
+  const hasPalette = Boolean(paletteItems?.length);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const [paletteOpen, setPaletteOpen] = useState(false);
+
+  // 顶栏标题：当前激活项的 label（取最长匹配，/admin/models 优先于 /admin）
+  const currentLabel = useMemo(() => {
+    const matches = sections.flatMap((s) => s.items).filter((item) => appShellIsActive(pathname, item.href));
+    if (!matches.length) return brand.label;
+    return matches.sort((a, b) => b.href.length - a.href.length)[0].label;
+  }, [pathname, sections, brand.label]);
+
+  // ⌘K / Ctrl+K 全局快捷键
+  useEffect(() => {
+    if (!hasPalette) return;
+    const onKey = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        setPaletteOpen((open) => !open);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [hasPalette]);
+
+  const brandBlock = (
+    <Link href={brand.href ?? "/"} className="flex items-baseline gap-1.5 px-2">
+      <span className="text-sm font-semibold tracking-tight">{brand.label}</span>
+      {brand.suffix ? <span className="font-mono text-[11px] text-ink-3">{brand.suffix}</span> : null}
+    </Link>
+  );
+
+  return (
+    <div className="min-h-dvh bg-bg">
+      {hasPalette ? <CommandPalette open={paletteOpen} onClose={() => setPaletteOpen(false)} items={paletteItems!} /> : null}
+
+      {/* 移动端抽屉 */}
+      {drawerOpen ? (
+        <div className="fixed inset-0 z-40 lg:hidden" role="presentation">
+          <div className="absolute inset-0 bg-black/30" onClick={() => setDrawerOpen(false)} />
+          <nav className="absolute inset-y-0 left-0 flex w-64 flex-col gap-5 overflow-y-auto border-r border-line bg-bg px-3 py-4">
+            {brandBlock}
+            <SidebarSections sections={sections} pathname={pathname} link={Link} onNavigate={() => setDrawerOpen(false)} />
+            {account}
+          </nav>
+        </div>
+      ) : null}
+
+      <div className="lg:grid lg:grid-cols-[13.5rem_minmax(0,1fr)]">
+        {/* 桌面固定侧栏 */}
+        <aside className="sticky top-0 hidden h-dvh flex-col gap-5 overflow-y-auto border-r border-line px-3 py-4 lg:flex">
+          {brandBlock}
+          <SidebarSections sections={sections} pathname={pathname} link={Link} />
+          {account}
+        </aside>
+
+        <div className="flex min-h-dvh min-w-0 flex-col">
+          {/* 轻顶栏 */}
+          <header className="sticky top-0 z-30 flex items-center gap-3 border-b border-line bg-bg/95 px-4 py-2.5 backdrop-blur lg:px-8">
+            <button
+              type="button"
+              aria-label="打开导航"
+              onClick={() => setDrawerOpen(true)}
+              className="rounded-md p-1 text-muted hover:bg-surface hover:text-accent lg:hidden"
+            >
+              <Icon name="menu" size={16} />
+            </button>
+            <span className="text-sm font-medium text-ink-2">{currentLabel}</span>
+            <div className="ml-auto flex items-center gap-3">
+              {headerExtras}
+              {hasPalette ? (
+                <button
+                  type="button"
+                  onClick={() => setPaletteOpen(true)}
+                  className="flex items-center gap-2 rounded-md border border-line px-2.5 py-1 font-mono text-[11px] text-muted transition-colors hover:border-accent hover:text-accent"
+                  aria-label="打开命令面板"
+                >
+                  <Icon name="search" size={12} />
+                  <span className="hidden sm:inline">搜索</span>
+                  <kbd className="hidden sm:inline">⌘K</kbd>
+                </button>
+              ) : null}
+            </div>
+          </header>
+
+          {/* 内容区 */}
+          <main className="page-shell flex-1 py-8">{children}</main>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** 侧栏账户块通用样式辅助：登录后的用户信息行。 */
+export function AppShellAccountRow({ name, badge, children }: { name: string; badge?: string; children?: ReactNode }) {
+  return (
+    <div className="mt-auto flex flex-col gap-2 border-t border-line px-2 pt-3">
+      <div className="flex items-center justify-between gap-2">
+        <span className="truncate font-mono text-xs text-ink-2">{name}</span>
+        {badge ? <Badge variant="outline" size="sm">{badge}</Badge> : null}
+      </div>
+      {children ? <div className="flex items-center justify-between gap-2 font-mono text-[11px]">{children}</div> : null}
+    </div>
+  );
+}

package/src/components/app-shell/CommandPalette.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { Icon, type IconName } from "../icon/Icon";
+
+export type AppPaletteItem = {
+  label: string;
+  hint?: string;
+  group: string;
+  icon?: IconName;
+  keywords?: string;
+  run: () => void;
+};
+
+/**
+ * ⌘K / Ctrl+K 命令面板：纯手写 overlay（无新依赖）。
+ * 键盘：↑↓ 选择、Enter 确认、Esc 关闭；输入即时过滤（label/hint/keywords 子串匹配）。
+ */
+export function CommandPalette({ open, onClose, items, placeholder = "搜索页面或执行动作…" }: { open: boolean; onClose: () => void; items: AppPaletteItem[]; placeholder?: string }) {
+  const [query, setQuery] = useState("");
+  const [cursor, setCursor] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return items;
+    return items.filter((item) => `${item.label} ${item.hint ?? ""} ${item.keywords ?? ""}`.toLowerCase().includes(q));
+  }, [items, query]);
+
+  useEffect(() => {
+    if (open) {
+      setQuery("");
+      setCursor(0);
+      // 等一帧让 overlay 挂载后再聚焦，避免被浏览器焦点还原打断
+      requestAnimationFrame(() => inputRef.current?.focus());
+    }
+  }, [open]);
+
+  useEffect(() => setCursor(0), [query]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        onClose();
+      } else if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setCursor((c) => Math.min(c + 1, filtered.length - 1));
+      } else if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setCursor((c) => Math.max(c - 1, 0));
+      } else if (event.key === "Enter") {
+        event.preventDefault();
+        const item = filtered[cursor];
+        if (item) {
+          onClose();
+          item.run();
+        }
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, filtered, cursor, onClose]);
+
+  useEffect(() => {
+    listRef.current?.querySelector<HTMLElement>(`[data-index="${cursor}"]`)?.scrollIntoView({ block: "nearest" });
+  }, [cursor]);
+
+  if (!open) return null;
+
+  const execute = (index: number) => {
+    const item = filtered[index];
+    if (!item) return;
+    onClose();
+    item.run();
+  };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-start justify-center bg-black/30 px-4 pt-[12vh]" onClick={onClose} role="presentation">
+      <div
+        className="w-full max-w-xl overflow-hidden rounded-xl border border-line bg-bg shadow-lg"
+        onClick={(event) => event.stopPropagation()}
+        role="dialog"
+        aria-modal="true"
+        aria-label="命令面板"
+      >
+        <div className="flex items-center gap-2 border-b border-line px-4 py-3">
+          <Icon name="search" size={14} className="text-muted" />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder={placeholder}
+            className="w-full bg-transparent text-sm outline-none placeholder:text-ink-3"
+          />
+          <kbd className="rounded border border-line px-1.5 py-0.5 font-mono text-[10px] text-ink-3">esc</kbd>
+        </div>
+        <div ref={listRef} className="max-h-[50vh] overflow-y-auto py-1.5">
+          {filtered.length === 0 ? (
+            <p className="px-4 py-6 text-center font-mono text-xs text-ink-3">没有匹配结果</p>
+          ) : (
+            filtered.map((item, index) => (
+              <button
+                key={`${item.group}-${item.label}`}
+                type="button"
+                data-index={index}
+                onClick={() => execute(index)}
+                onMouseEnter={() => setCursor(index)}
+                className={`flex w-full items-center gap-2.5 px-4 py-2 text-left text-sm transition-colors ${
+                  index === cursor ? "bg-surface text-accent-readable" : "text-ink-2"
+                }`}
+              >
+                {item.icon ? <Icon name={item.icon} size={13} className="shrink-0 text-muted" /> : null}
+                <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                {item.hint ? <span className="shrink-0 font-mono text-[11px] text-ink-3">{item.hint}</span> : null}
+              </button>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/app-shell/index.ts

@@ -0,0 +1,4 @@
+export { AppShell, AppShellAccountRow, appShellIsActive } from "./AppShell";
+export type { AppNavItem, AppNavSection, AppShellLink } from "./AppShell";
+export { CommandPalette } from "./CommandPalette";
+export type { AppPaletteItem } from "./CommandPalette";

package/src/components/badge/Badge.tsx

@@ -9,7 +9,7 @@ export const badgeVariants = cva(
   {
     variants: {
       variant: {
-        solid: "bg-ink text-white",
+        solid: "bg-ink text-bg",
         outline: "border border-line text-ink-2",
         success: "border border-success/30 bg-success/10 text-success",
         warning: "border border-warning/30 bg-warning/10 text-warning",

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

@@ -4,22 +4,34 @@ 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]",
+          // 反色按钮：bg-ink 上用 bg 色作文字（浅色=白、深色=黑），硬编码 text-white 在深色主题下不可读
+          "bg-ink text-bg 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/index.ts

@@ -1,6 +1,7 @@
 // @zmzai/theme — Components barrel (54 components)
 
 // === Basic ===
+export * from "./app-shell";
 export * from "./button";
 export * from "./input";
 export * from "./textarea";

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

@@ -4,18 +4,26 @@ 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:
-          "h-10 border border-line rounded-sm px-4 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:
-          "h-10 border-2 border-ink rounded-sm px-4 text-sm",
+          "h-10 border-2 border-ink rounded-sm px-4 text-sm focus-visible:ring-line-strong",
       },
       size: {
         sm: "h-8 text-xs px-3",

package/src/components/navbar/Navbar.tsx

@@ -9,7 +9,7 @@ import { Icon } from "../icon/Icon";
 /**
  * navItemClass — 导航项统一样式（全域导航一致）。
  *
- * active 时深墨 pill 高亮（bg-ink text-white），其余 hover 浮现。
+ * active 时深墨 pill 高亮（bg-ink text-bg，深浅主题自适应），其余 hover 浮现。
  * 链接本身由调用方渲染（Next.js 用 next/link，保持 SPA 导航），
  * 只要都套这个 className，任何站点的导航观感就完全一致。
  */
@@ -17,7 +17,7 @@ export function navItemClass(active: boolean): string {
   return cn(
     "inline-flex items-center gap-1.5 rounded-full px-3 py-1.5 text-sm font-medium transition-colors",
     active
-      ? "bg-ink text-white"
+      ? "bg-ink text-bg"
       : "text-ink-2 hover:bg-surface-2 hover:text-ink"
   );
 }

package/src/components/select/Select.tsx

@@ -20,6 +20,8 @@ export function SelectTrigger({
       className={cn(
         "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/components/sticky-banner/StickyBanner.tsx

@@ -16,7 +16,7 @@ export interface StickyBannerProps extends HTMLAttributes<HTMLDivElement> {
 
 const variantStyles: Record<BannerVariant, string> = {
   info: "bg-surface text-ink border-line",
-  warning: "bg-ink text-white border-ink",
+  warning: "bg-ink text-bg border-ink",
   danger: "bg-bg text-ink border-ink border-2",
 };
 

package/src/components/vanish-input/VanishInput.tsx

@@ -145,7 +145,7 @@ export function VanishInput({
       <button
         type="submit"
         aria-label="提交"
-        className="ml-2 flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-ink text-white transition-transform hover:scale-105 active:scale-95"
+        className="ml-2 flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-ink text-bg transition-transform hover:scale-105 active:scale-95"
       >
         <svg
           className="h-3.5 w-3.5"