# 前端模式库 · 给 AI 的取料入口

本库完全不预设视觉风格。先理解本次页面的内容、受众和关键任务，再决定布局与表现；没有必须照搬的配色、字体、圆角、材质、曲线或装饰。
本库提供可复用资产与质量要求；示例页面的外观只是示例，不是消费方的默认风格。

## 从需求到取料
1. 先理解本次用户、内容与目标操作，再决定需要什么结构和行为；不要从整页例子开始换字。
2. 读 agent/guides/index.json，按问题选取相关方法，不要求每次通读全部材料或输出固定思考格式。
3. 确认行为后读 agent/index.json 的 items，按 id / cat / t / en / d / motion / tags 检索；可以改造、组合或不用现成资产。
4. 按 files 取原文：blocks/<id>.html 是 body，.css 是样式；hasInit 为 true 时才有 .js。打开 preview/<id>.html 检查交互，不凭记忆补写依赖。
5. agent/typography.md 提供排版判断方法；agent/layouts/ 只记录可选的局部结构关系，不是整页模板、固定页面顺序或必须选择的有限名单。ai-tells.html 按任务检查模板化问题。
6. 本库是取材源。消费方在自己的工程里改代码；维护本库时才修改 data/ 并重跑生成器，不手改 agent/** 或 llms.txt。

## 按需读取的方法材料
- agent/guides/decisions.md：理解任务、内容和约束，再决定结构与表现，不选风格菜单。
- agent/guides/composition.md：按信息关系组合零件，检查共享状态、作用域与依赖，不设组件或区块配额。
- agent/guides/interaction.md：补全当前操作的真实结果、等待、失败、取消和返回等必要分支，不强加统一流程。
- agent/guides/adaptation.md：用内容、数据、语言、设备和输入方式的变化检查适配，不只等比例缩小页面。
- agent/guides/review.md：分别检查操作、视觉完成度与机械套版，记录实际验证证据，不以测试数量代替视觉判断。

## 现在有什么
- 资产 374 条，分类 26 个，令牌表 v1.0.0。数量以 agent/index.json 为准。
- 分类：入场 → 加载 → 微交互 → 光标 → 滚动 → 过渡 → 拖拽 → 布局 → 数据 → 图表 → 反馈 → 排印 → 无障碍 → 表单 → 导航 → 浮层 → 列表 → 手势 → 内容 → 长文 → 表格 → 状态页 → 媒体 → SVG 与路径 → 3D 与透视 → 滚动驱动。
- motion 是检索标签，不是风格限制；可以按实际交互修改曲线、时长，或完全不用动画。

## 冲突时如何判断
1. 本次用户需求、品牌规范与业务内容决定设计方向。
2. 可读性、可访问性、功能正确性、性能和代码隔离必须满足；视觉偏好不能代替这些检查。
3. 资产里的具体参数只是实现示例；与当前任务不符时可以修改，不要求与预览数字一致。
4. data/tokens.json 是本库预览变量的唯一数值来源；正式项目可重新定义变量，不能依赖未定义的变量。

## 避免 AI 模板感（按问题判断，不按元素封禁）
- 内容先于容器：不要把每段文字都套成同尺寸卡片；只有需要分组、比较或操作的内容才使用相应容器。
- 不默认套用“大标题＋说明＋三张卡＋口号”的区块顺序；每个区块应回答当前页面的实际问题。
- 不为凑数生成相同长度的卖点、无来源的指标、虚构评价或没有信息的标签。
- 装饰要有作用：渐变、玻璃、阴影、发光、紫色、胶囊等均可使用；不能无视品牌和内容、整页机械重复或妨碍阅读与操作。
- 信息层级靠主次、分组、对齐与密度体现；不要所有标题同重量、所有区块同留白、所有元素同强调。
- 动效应说明状态、关系或操作结果；不叠加抢注意力的动画，不用动画掩盖内容不足。
- 文案写具体对象、动作和结果；说明字段要给理由，避免以 赋能 / 一键 / 无缝 / 极致 / 沉浸 / 丝滑 / 焕新 等空话代替信息。
- 不强迫刻意破格，也不要求与上一页人为不同；差异来自内容和任务，系列页面需要一致时可以复用结构。

## 通用质量要求
- 交互可执行，必要的加载、空结果、失败、成功、禁用和焦点状态有对应处理。
- 字体大小、行宽、行距与对比度支持实际内容阅读；在目标屏宽和内容长度下检查溢出。
- 键盘可操作、焦点可见；有动画时尊重 prefers-reduced-motion，不能只靠颜色传递关键信息。
- 颜色、间距、圆角、字阶和动效参数在当前项目内有一致的语义；不规定固定档数、固定数值或唯一材质。
- transition 只列需要变化的属性，避免 transition:all 带来无关属性动画。
- 复用 CSS 时加外层作用域；keyframes 带资产 id 前缀，避免多个资产同屏时互相覆盖。
- 引用的变量必须有定义或有效 fallback；不要把预览的占位值误当用户品牌规范。
- 保留资产的 HTML / CSS / init 依赖关系，使用真实内容检查按钮、长文案与边界状态。

## 变量与代码接口
资产通过变量兼容预览，变量名不代表视觉风格。按当前项目需要覆盖 agent/tokens.css 中的值即可。
预览里使用的变量：`--bg · --paper · --ink · --muted · --faint · --line · --ink-vermilion · --ink-indigo · --ink-yellow · --marker-hi · --ok · --warn · --fs-9 · --fs-11 · --fs-13 · --fs-15 · --fs-21 · --fs-34 · --fs-56 · --fs-96 · --lh-body · --lh-note · --lh-display · --tracking-display · --tracking-body · --tracking-mono-label · --font-sans · --font-serif · --font-mono · --sp-4 · --sp-8 · --sp-12 · --sp-16 · --sp-24 · --sp-40 · --sp-64 · --sp-96 · --radius-table · --radius-tag · --radius-control · --radius-card · --radius-pill · --dur-feedback · --dur-move · --dur-reveal · --dur-ambient · --ease-mechanical · --ease-physical · --ease-print · --shadow-divider · --shadow-press · --shadow-overlay · --border-default · --border-strong · --sans · --serif · --mono · --lime · --coral · --blue · --mint · --lime-soft · --lav · --ease · --ease-out · --ease-spring · --r · --sp`。
颜色、字体、材质、圆角、阴影、时长和曲线都可重定；固定值并非天然错误，但应与当前项目体系自洽。

## 直接取料
- jsDelivr 基址：https://cdn.jsdelivr.net/gh/suxingchen37-cloud/frontend-pattern-library@main/
- raw 基址：https://raw.githubusercontent.com/suxingchen37-cloud/frontend-pattern-library/main/
- 拼接 llms.txt、agent/index.json、agent/tokens.css、agent/blocks/<id>.html|.css|.js、agent/preview/<id>.html。
- 数值源为 data/tokens.json；可发布站点同时提供此文件，但不发布完整 data/ 与 tools/。
- CDN 可能缓存分支内容。需要可复现版本时，把 @main 替换成明确的提交 SHA。
- files 的路径相对 agent/；使用 GitHub Pages 时保留基址里的仓库目录，不能只取域名。

## 组装与初始化
1. 按实际内容组织结构，再添加确有用途的交互；资产数量按任务决定，不设统一配额。
2. blocks/<id>.html 放进容器；blocks/<id>.css 不带 style 标签，添加作用域后再使用。
3. blocks/<id>.js 形如 window.INITS["<id>"] = root => {...}；加载后调用 window.INITS["<id>"](root)，root 是对应资产容器。
4. preview/<id>.html 已注入预览变量，可独立打开；?theme=night 可查看示例夜间状态。

## 交付前自检
- [ ] 区块、容器、装饰与动效都能说明用途，没有因模板习惯而添加的空内容。
- [ ] 真实文案、长内容与不同屏宽下层级清楚，操作路径可理解。
- [ ] 必要状态、键盘焦点和 reduced-motion 已检查；未验证项明确说明。
- [ ] 作用域、keyframes、变量和初始化依赖完整，没有运行错误。
- [ ] 已列明使用的资产 id、关键设计理由和未通过的检查；无需强制破格或套固定交付话术。