agentcss 0.0.0-stage → 0.11.2

package/02-primitives/card/README.md

@@ -0,0 +1,145 @@
+# card
+
+| 字段 | 内容 |
+|---|---|
+| **来源** | 原创。2px 抬起一条来自对 `animal-island-ui` 的观察（那套设计里最认同的一条） |
+| **实测** | `states.py` 零缺失（card 形态：focus HIGH / hover LOW） |
+| **适用** | 精简档 / B / C，纯 CSS |
+| **依赖** | `01-tokens/tokens.css`  + `01-tokens/typography.css`（`.note` 提示框） + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`） |
+
+---
+
+## 用法
+
+```html
+<div class="card">
+  <div class="card__body">
+    <h3>标题</h3>
+    <p class="small">说明文字</p>
+  </div>
+</div>
+```
+
+**`.card__body` 不是可选的。** `.card` 自身 `padding: 0`，内边距全在
+`.card__body` 上（`padding: var(--sp-5)`）。直接往 `.card` 里放内容，文字会**贴边**。
+
+**`.card` 是 `display: flex; flex-direction: column`**，子元素默认被拉伸到整宽。
+所以**行内小元素会被拉成一条整宽的色带**（实测：一个本该 54px 宽的状态标签
+被拉到 355px）。这不是 bug，是 flex 的默认 `align-items: stretch`。
+
+两种解法：
+
+```html
+<!-- ① 包一层（推荐，语义更清楚） -->
+<div class="card"><div class="card__body">
+  <h3>标题</h3>
+  <div><span>状态</span></div>
+</div></div>
+
+<!-- ② 直接给那个元素 align-self: flex-start -->
+<div class="card"><div class="card__body">
+  <h3>标题</h3>
+  <span style="align-self:flex-start">状态</span>
+</div></div>
+```
+
+> 若要在卡片里放**状态标签**，请同时引入 `02-primitives/badge/badge.css` ——
+> 它不在 card 的依赖里，本目录的 `demo.html` 也没有演示它。
+
+| 变体 | 用途 |
+|---|---|
+| `.card--interactive` | 可点击（hover 抬起 2px + 阴影） |
+| `.card--linked` | 整卡可点，语义由 `<a>` 承担 |
+| `.card--flat` | 无边框，靠背景区分 |
+| `.card--elevated` | 常驻阴影 |
+| `.card--compact` | 紧凑内边距 |
+| `.card--row` | 横向排列（图左文右） |
+| `.card--selected` | 选中态 |
+
+依赖：`01-tokens/tokens.css` + `01-tokens/typography.css`（正文）+
+`01-tokens/page.css`（`.wrap` / `.small` 等页面骨架）。
+
+---
+
+## 唯一的核心判据：hover 不能有布局跳动
+
+hover 只改 **`transform`** 和 **`box-shadow`**，这两个属性不触发回流。
+改 `border-width` / `margin` / `padding` / `height` 任何一项都会引起重排，相邻卡片跟着抖。
+
+那个抖动很轻——1px 左右，轻到说不清哪里不对——**但整页会显得廉价**。
+`demo.html` 把它放大到 4px，鼠标移上去一次就能记住。
+
+**要"加粗"边框怎么办**：用 `box-shadow: inset 0 0 0 2px`，不要改 `border-width`。
+`--selected` 变体就是这么做的。
+
+---
+
+## 变体
+
+| 变体 | 用途 | 注意 |
+|---|---|---|
+| `.card` | 默认，1px 边框 | 一排卡片时边框会显得重 |
+| `.card--flat` | 无边框，靠明度差分层 | **列表首选**，比全都有边框干净 |
+| `.card--elevated` | 默认带阴影 | 只给浮层/弹窗；列表全用它阴影会打架 |
+| `.card--interactive` | 可点，hover 抬 2px | 需要整卡可点时配 `--linked` |
+| `.card--linked` | 整卡可点 | 内部必须有真实 `<a>`/`<button>` |
+| `.card--selected` | 选中态 | inset shadow，不是改 border |
+| `.card--compact` | 紧凑 | 两档够了，第三档说明密度没规划 | —— demo 未演示，是留给复用者的钩子
+| `.card--row` | 横向 | 560px 以下自动回退纵向 |
+
+---
+
+## 🔴 整卡可点：正确做法 vs 错误做法
+
+**错误**：给 `<div>` 加 `onclick`。
+键盘 Tab 不到、屏幕阅读器不认、不能中键新开、不能复制链接。
+
+**正确**：卡片内放一个真实的 `<a>`，用它的 `::after` 铺满整卡。
+
+```html
+<div class="card card--linked card--interactive">
+  <div class="card__body">
+    <h3 class="card__title"><a class="card__link" href="/x">标题</a></h3>
+    <p class="card__desc">摘要</p>
+  </div>
+</div>
+```
+
+焦点用 `:focus-within`——内部链接获焦时**整张卡**显示 ring，而不是只有标题那一小块。
+链接本身的 `:focus-visible` 要关掉，否则会出现两个框。
+
+卡片里如果有其他可点元素（按钮、标签），要 `z-index: 1` 盖在热区之上。
+
+---
+
+## 抬起 2px，不是 8px
+
+卡片是"被拿起"，不是"被弹起"。8px 以上会有游戏感——
+**长文和数据类界面不能要那种感觉**。
+
+这条来自对 `animal-island-ui` 的观察：卡片 20px 圆角、无投影、hover 只抬 2px。
+那套库整体画风跟严肃内容不搭，但这一条是对的。
+
+---
+
+## 反例 —— 什么时候不该用
+
+- ❌ **一排卡片全用 `--elevated`** —— 阴影互相打架，整页发灰。列表用 `--flat`
+- ❌ **hover 抬起 8px 以上** —— 游戏感
+- ❌ **整卡套 `div onclick`** —— 键盘不可达，见上
+- ❌ **给链接本身再画焦点环** —— 会变成两个框
+- ❌ **用 JS 截断描述文字** —— 会留下半个词或半个字，用 `-webkit-line-clamp`
+- ❌ **手动覆盖 `--row` 在窄屏的回退** —— 那个回退是必要的
+
+---
+
+## 门禁
+
+```bash
+python 05-audit/states.py 02-primitives/card/card.css
+```
+
+card 形态查两项：`focus`（HIGH，整卡可点时键盘不可达）、`hover`（LOW）。
+不查 `disabled` / `active`——卡片没有禁用态，也不响应按压。
+
+跑在 某项目 上立刻抓出 `.card` / `.card-grid` / `.side-card` 三个类全缺 focus。

package/02-primitives/card/card.css

@@ -0,0 +1,246 @@
+/* ============================================================================
+   frontend-lib / 02-primitives / card / card.css
+   卡片
+
+   依赖：01-tokens/tokens.css
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴 本组件的核心判据：hover 时不能有布局跳动。
+      达成方式：hover 只改 transform 和 box-shadow，
+      **绝不改 border-width / margin / padding / height**。
+      改任何影响盒模型的属性都会引起回流，相邻元素会跟着抖一下 ——
+      这个抖动很轻，轻到说不清哪里不对，但整页会显得廉价。
+
+      card 是容器，承载的内容态（empty/loading/error/success）在 03-patterns。
+   ========================================================================= */
+
+.card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+
+  background: var(--surface);
+  /* 🔴 边框恒为 1px。hover 时想"加粗"边框？用 box-shadow 模拟，不要改 border-width。 */
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-md);
+
+  /* 只需动画 transform 和 box-shadow —— 这两个不触发回流 */
+  transition: transform var(--dur-base) var(--ease-out),
+              box-shadow  var(--dur-base) var(--ease-out);
+}
+
+/* ---------------------------------------------------------------- 结构 */
+.card__media {
+  /* 用 aspect-ratio 而不是 padding-top hack —— 后者要多一层包装 div */
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border-radius: calc(var(--r-md) - 1px) calc(var(--r-md) - 1px) 0 0;
+  background: var(--surface-sunken);
+}
+.card__media img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+/* 没有 media 时，body 要补上顶部圆角 */
+.card__media + .card__body { border-radius: 0; }
+
+.card__body {
+  padding: var(--sp-5);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+}
+
+.card__title {
+  margin: 0;
+  font-size: var(--fs-md);
+  font-weight: 500;
+  line-height: var(--lh-tight);
+  color: var(--text-primary);
+}
+
+/* 副标题/摘要。行数限制用 -webkit-line-clamp，
+   别用 JS 截字符串 —— 截出来会留下半个词或半个字。 */
+.card__desc {
+  margin: 0;
+  font-size: var(--fs-sm);
+  color: var(--text-secondary);
+  line-height: var(--lh-base);
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.card__footer {
+  padding: var(--sp-3) var(--sp-5);
+  border-top: 1px solid var(--border-decor);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--sp-3);
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);
+}
+
+/* ---------------------------------------------------------------- 变体 */
+
+/* 无边框：靠背景色和纸底的明度差分层，界面更轻。
+   一排卡片时用它，比全都有边框干净。 */
+.card--flat {
+  border-color: transparent;
+  background: var(--surface);
+}
+
+/* 浮起：默认就有阴影。用在浮层、弹窗类场景。
+   🔴 常规列表里不要用 —— 满屏阴影会互相打架。 */
+.card--elevated {
+  border-color: transparent;
+  box-shadow: var(--shadow-1);
+}
+
+/* ---------------------------------------------------------------- 可交互卡片
+   🔴 hover 抬起的正确写法：
+      transform 抬 2px（--lift-md），阴影从 1 级升到 2 级。
+      两个属性都不触发回流，所以旁边的卡片不会抖。
+
+   为什么是 2px 不是 8px：卡片是"被拿起"不是"被弹起"。
+   8px 会有游戏感，长文/数据类界面不能要那种感觉。
+   ---------------------------------------------------------------- */
+.card--interactive {
+  cursor: pointer;
+}
+@media (hover: hover) and (pointer: fine) {
+.card--interactive:hover {
+  transform: translateY(calc(-1 * var(--lift-md)));
+  box-shadow: var(--shadow-2);
+}
+}
+/* 按下时落回原位 —— 和 button 的 active 是同一套语言 */
+.card--interactive:active {
+  transform: translateY(0);
+  box-shadow: var(--shadow-1);
+}
+
+/* ---------------------------------------------------------------- 整卡可点
+   🔴 正确做法：卡片里放一个真实的 <a> 或 <button>，
+      用它的 ::after 铺满整张卡。
+
+   错误做法：给 <div> 加 onclick。
+      那样键盘 Tab 不到、屏幕阅读器不认、不能中键新开、不能复制链接。
+
+   焦点样式用 :focus-within —— 内部的链接获得焦点时，整卡显示 ring。
+   ---------------------------------------------------------------- */
+.card--linked { position: relative; }
+
+.card__link {
+  /* 让链接文字本身还是普通样式，只把它当作"热区提供者" */
+  color: inherit;
+  text-decoration: none;
+}
+.card__link::after {
+  content: "";
+  position: absolute;
+  inset: 0;                 /* 铺满整张卡 */
+  border-radius: var(--r-md);
+  z-index: var(--z-base);
+}
+/* 卡片里如果有其他**可点元素**（按钮、链接、标签），要盖在热区之上。
+
+   🔴 **修正一个真 bug**（契约实测抓到：卡片内采样 5 点，0 点命中链接）：
+   原来写的是 `.card__body > *:not(.card__link)`
+   ⇒ **把标题、段落、说明文字全都抬到热区之上**
+   ⇒ 结果**点卡片正文不跳转**，"整卡可点"名存实亡。
+   （实测：卡片中心点命中的是 `P.card__desc`，不是那条链接。）
+
+   ⚠️ 这类 bug 在视觉上**完全看不出来** —— 卡片照常显示、
+      标题里那条链接也照常能点，只有"点卡片空白/正文"才发现失效。
+
+   ⇒ 现在只抬**真正可交互**的元素，纯内容不抬。
+   ⚠️ 顺带修掉硬编码的 `z-index: 1` → 走 `--z-raised` 令牌。 */
+.card__body :is(button, a, input, select, textarea, [role="button"],
+                [role="checkbox"], [role="switch"], [tabindex]):not(.card__link) {
+  position: relative;
+  z-index: var(--z-raised);
+}
+
+.card--linked:focus-within {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+/* 别给链接本身再画一次 ring，会变成两个框 */
+.card__link:focus-visible { outline: none; }
+
+/* ---------------------------------------------------------------- 选中态
+   多选场景（如筛选后的项目列表）。
+   🔴 用 inset box-shadow 加"内描边"，而不是 border-width 变化 —— 同样的理由：不跳动。
+   ---------------------------------------------------------------- */
+.card--selected {
+  box-shadow: inset 0 0 0 2px var(--accent);
+}
+
+/* ---------------------------------------------------------------- 尺寸
+   两档够了。出现第三档说明信息密度没规划好。
+   ---------------------------------------------------------------- */
+.card--compact .card__body { padding: var(--sp-4); gap: var(--sp-1); }
+.card--compact .card__title { font-size: var(--fs-base); }
+
+/* ---------------------------------------------------------------- 横向卡片
+   窄屏回退为纵向。
+   ---------------------------------------------------------------- */
+.card--row {
+  flex-direction: row;
+  align-items: stretch;
+}
+.card--row .card__media {
+  flex: none;
+  width: 160px;
+  aspect-ratio: auto;
+  border-radius: calc(var(--r-md) - 1px) 0 0 calc(var(--r-md) - 1px);
+}
+@media (max-width: 560px) {
+  .card--row { flex-direction: column; }
+  .card--row .card__media {
+    width: 100%;
+    aspect-ratio: 16 / 9;
+    border-radius: calc(var(--r-md) - 1px) calc(var(--r-md) - 1px) 0 0;
+  }
+}
+
+/* ---------------------------------------------------------------- 无障碍兜底
+   card 的 hover 位移属于"小幅位移"，reduced-motion 下应当去掉抬起，
+   只保留阴影变化 —— 阴影不属于前庭敏感类动效。
+   ---------------------------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+@media (hover: hover) and (pointer: fine) {
+  .card--interactive:hover,
+  .card--interactive:active {
+    transform: none;
+  }
+}
+}
+
+/* ============================================================================
+   反模式 —— 库内一律退回
+   =========================================================================
+   1. hover 时改 border-width（如 1px -> 2px）
+      内容整体位移 1px，相邻卡片跟着抖。这是卡片最经典的 bug。
+      要"加粗"边框用 box-shadow: inset 0 0 0 2px。
+
+   2. hover 时改 margin / padding / height
+      同上，且会引起整页重排。
+
+   3. 整卡套 <div onclick>
+      键盘不可达、屏幕阅读器不认、不能新标签打开。用 .card__link::after。
+
+   4. 一排卡片全用 --elevated
+      阴影会互相打架，整页发灰。列表用 --flat，浮层才用 --elevated。
+
+   5. hover 抬起 8px 以上
+      游戏感。卡片是"被拿起"不是"被弹起"。
+
+   6. 用 JS 截断描述文字
+      会留下半个词或半个字。用 -webkit-line-clamp。
+   ========================================================================= */

package/02-primitives/card/demo.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="data:,">
+<title>card · hover 无跳动</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="card.css">
+<style>
+p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6; }
+.grid3 { display: grid; gap: var(--sp-4); grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
+.cmp { display: grid; gap: var(--sp-5); grid-template-columns: 1.55fr 1fr; }
+@media (max-width: 700px) {.cmp { grid-template-columns: 1fr; }
+
+ }
+.cmp>div { padding: var(--sp-5); border-radius: var(--r-md); border: 1px solid var(--border-decor); }
+.bad { background: var(--surface-sunken); }
+.good { background: var(--surface-sunken); }
+.cmp h3 { margin: 0 0 var(--sp-2); font-size: var(--fs-sm); font-weight: 500; }
+.bad h3 { color: var(--danger); }
+.good h3 { color: var(--success); }
+.cmp .stack { display: flex; flex-direction: column; gap: var(--sp-3); }
+/* ---- 反例卡片：hover 时改 border-width，引起回流 ---- */
+.card-bad { position: relative; background: var(--surface);
+              border: 1px solid var(--border-decor); border-radius: var(--r-md);
+              padding: var(--sp-4); font-size: var(--fs-sm); cursor: pointer;
+              transition: border-color 180ms, box-shadow 180ms; }
+.card-bad:hover { border-width: 4px; border-color: var(--accent); box-shadow: var(--shadow-2); }
+.card-bad .ruler { height: 12px; background: repeating-linear-gradient(90deg,
+              var(--text-tertiary) 0 1px, transparent 1px 8px); opacity: .5; margin-bottom: var(--sp-2); }
+/* ---- 正确卡片：用库里的 .card--interactive ---- */
+.card-ok .ruler { height: 12px; background: repeating-linear-gradient(90deg,
+              var(--text-tertiary) 0 1px, transparent 1px 8px); opacity: .5; margin-bottom: var(--sp-2); }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+  <h1>card · hover 无布局跳动</h1>
+  <p class="lede">
+    卡片的核心判据：hover 时只改 <code>transform</code> 和 <code>box-shadow</code>，
+    <strong>绝不改 border-width / margin / padding / height</strong>。
+  </p>
+
+  <h2 class="rule-bottom">把 1px 的跳动放大给你看</h2>
+  <div class="note">
+    真实项目里这个 bug 通常是 <code>border: 1px → 2px</code>，只跳 1px ——
+    轻到说不清哪里不对，但整页会显得廉价。<br>
+    下面<strong>故意放大到 4px</strong>，好让你一次看清楚。请分别把鼠标移到两张卡上。
+  </div>
+
+  <div class="cmp">
+    <div class="box bad">
+      <h3>反例：hover 改 border-width</h3>
+      <p class="small" style="margin:0 0 var(--sp-3)">
+        移上来 —— 里面那把尺子和文字整体往下挪了，卡片也变高了。
+        一排卡片时，邻居会跟着抖。
+      </p>
+      <div class="stack">
+        <div class="card-bad">
+          <div class="ruler"></div>
+          <strong>2026-09-24</strong><br>动物森友会 UI 库实拍
+        </div>
+        <div class="card-bad">
+          <div class="ruler"></div>
+          <strong>2026-09-27</strong><br>MICRO 微交互组件实拍
+        </div>
+      </div>
+    </div>
+
+    <div class="good">
+      <h3>本库：transform + box-shadow</h3>
+      <p class="small" style="margin:0 0 var(--sp-3)">
+        移上来 —— 卡片整体抬起 2px，<strong>里面的内容一个像素都不动</strong>，
+        邻居也不会被推挤。
+      </p>
+      <div class="stack">
+        <div class="card card--interactive card-ok">
+          <div class="card__body">
+            <div class="ruler"></div>
+            <span class="card__title">动物森友会 UI 库实拍</span>
+            <span class="card__desc" style="-webkit-line-clamp:1">2026-09-24</span>
+          </div>
+        </div>
+        <div class="card card--interactive card-ok">
+          <div class="card__body">
+            <div class="ruler"></div>
+            <span class="card__title">MICRO 微交互组件实拍</span>
+            <span class="card__desc" style="-webkit-line-clamp:1">2026-09-27</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <h2 class="rule-bottom">抬起 2px，不是 8px</h2>
+  <p class="small">
+    卡片是"被拿起"，不是"被弹起"。8px 以上会有游戏感 ——
+    长文和数据类界面不能要那种感觉。这也是森友会那套设计里我最认同的一条：
+    卡片 20px 圆角、无投影、hover 只抬 2px。
+  </p>
+
+  <h2 class="rule-bottom">变体</h2>
+  <div class="grid3">
+    <div class="card card--flat">
+      <div class="card__body">
+        <h3 class="card__title">flat</h3>
+        <p class="card__desc">无边框，靠背景色和纸底的明度差分层。一排卡片时用它最干净。</p>
+      </div>
+    </div>
+    <div class="card card--elevated">
+      <div class="card__body">
+        <h3 class="card__title">elevated</h3>
+        <p class="card__desc">默认带阴影。只用在浮层、弹窗。列表里全用它，阴影会互相打架。</p>
+      </div>
+    </div>
+    <div class="card card--selected">
+      <div class="card__body">
+        <h3 class="card__title">selected</h3>
+        <p class="card__desc">用 inset box-shadow 做内描边，不是改 border-width —— 同样为了不跳动。</p>
+      </div>
+    </div>
+  </div>
+
+  <h2 class="rule-bottom">整卡可点：Tab 一下试试</h2>
+  <div class="grid3">
+    <div class="card card--linked card--interactive">
+      <div class="card__body">
+        <h3 class="card__title"><a class="card__link" href="#x">点标题，整卡可点</a></h3>
+        <p class="card__desc">用键盘 Tab 到这里 —— 整张卡会出现焦点环，而不是只有标题那一小块。</p>
+      </div>
+    </div>
+    <div class="card">
+      <div class="card__body">
+        <h3 class="card__title">对照：普通 div onclick</h3>
+        <p class="card__desc" style="-webkit-line-clamp:2">
+          （这张是正确实现的对照说明）给 div 加 onclick：键盘 Tab 不到、
+          屏幕阅读器不认、不能中键新开、不能复制链接。
+        </p>
+      </div>
+    </div>
+  </div>
+  <p class="small">
+    实现：卡内放一个真实的 <code>&lt;a&gt;</code>，用它的 <code>::after</code> 铺满整卡。
+    焦点样式用 <code>:focus-within</code>，内部链接获焦时整卡显示 ring。
+  </p>
+
+  <h2 class="rule-bottom">横向卡片（窄屏自动回退）</h2>
+  <div class="card card--row">
+    <div class="card__media"></div>
+    <div class="card__body">
+      <h3 class="card__title">横向布局</h3>
+      <p class="card__desc">560px 以下自动变回纵向。别手动覆盖这个回退。</p>
+    </div>
+  </div>
+
+  <h2 class="rule-bottom">门禁抓到的真问题</h2>
+  <div class="note">
+    给 <code>states.py</code> 加了 card 形态后，跑 某项目 立刻多报 4 项 HIGH：
+    <code>.card</code> / <code>.card-grid</code> / <code>.side-card</code> <strong>全都缺 focus</strong> ——
+    那几张卡鼠标能 hover，但键盘 Tab 不到。<br><br>
+    这就是"按形态分开检查"的价值：统一清单时这些根本不会被发现。
+  </div>
+
+</main>
+</body>
+</html>