{
  "brand": "AI UP LAB",
  "version": "1.2.1",
  "format": "ai-up-lab-design-knowledge/v1",
  "delivery": "Static JSON and Markdown; no MCP endpoint",
  "reference": "https://tmall-design.com/",
  "groups": [
    {
      "id": "foundation",
      "title": {
        "zh": "基础与素材",
        "en": "Foundations & assets"
      }
    },
    {
      "id": "component",
      "title": {
        "zh": "组件规范",
        "en": "Components"
      }
    },
    {
      "id": "pattern",
      "title": {
        "zh": "页面模式",
        "en": "Page patterns"
      }
    },
    {
      "id": "workflow",
      "title": {
        "zh": "AI 协作与验收",
        "en": "AI & review"
      }
    }
  ],
  "specs": [
    {
      "id": "foundations",
      "group": "foundation",
      "title": {
        "zh": "品牌、色彩与字体",
        "en": "Brand, color & typography"
      },
      "definition": {
        "zh": "用稳定的身份标志和语义变量统一界面；颜色说明作用，字号说明信息层级。",
        "en": "Use a stable identity and semantic tokens. Color expresses purpose; typography establishes hierarchy."
      },
      "anatomy": [
        {
          "zh": "身份：六边形轮廓、向上留白、45% 中心三角形。",
          "en": "Identity: hexagonal outline, upward cutout, 45% central triangle."
        },
        {
          "zh": "颜色：品牌强调、内容表面、文字、边界与反馈。",
          "en": "Color: brand, surfaces, text, borders, and feedback."
        },
        {
          "zh": "字体：Geist 与中文系统字体，代码使用 IBM Plex Mono。",
          "en": "Type: Geist and system CJK fonts; IBM Plex Mono for code."
        }
      ],
      "parameters": [
        {
          "name": "color.brand",
          "value": "#6741c2 / #b79af5",
          "usage": {
            "zh": "浅 / 深主题中的主动作与选中状态。",
            "en": "Primary actions and selection in light / dark themes."
          }
        },
        {
          "name": "color.text",
          "value": "#17151b / #f5f2fa",
          "usage": {
            "zh": "标题与正文；不要以品牌色替代整页正文。",
            "en": "Headings and body; do not color all prose with the brand accent."
          }
        },
        {
          "name": "type.body",
          "value": "15px / 1.7",
          "usage": {
            "zh": "常规说明正文；卡片短简介可使用专用密度。",
            "en": "Regular prose; compact card descriptions use their own density."
          }
        },
        {
          "name": "logo.centerScale",
          "value": "45%",
          "usage": {
            "zh": "围绕空心三角形重心等比缩小，保持方向。",
            "en": "Scale around the triangle centroid without changing direction."
          }
        },
        {
          "name": "logo.lockup",
          "value": "Geist 500 · gap 0.5 cap",
          "usage": {
            "zh": "标志 + AI UP LAB：桌面 32px 标志配 18px 字，手机 24px 配 14px；标志与首字母的可见间距 = 字母大写高度的一半；字距 -0.02em；标志按可见图形对齐网格并与大写高度居中。",
            "en": "Mark + AI UP LAB: 32px mark with 18px type on desktop, 24px with 14px on mobile. Visible gap to the first letter = half the cap height; tracking -0.02em; align the visible glyph to the grid and centre it on the cap height."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/foundations.md",
      "states": [
        {
          "name": {
            "zh": "浅色",
            "en": "Light"
          },
          "behavior": {
            "zh": "白色背景、近黑正文、深紫动作。",
            "en": "White surfaces, near-black text, deep-violet actions."
          }
        },
        {
          "name": {
            "zh": "深色",
            "en": "Dark"
          },
          "behavior": {
            "zh": "深灰紫背景、浅色正文、浅紫动作；保留用户选择。",
            "en": "Dark neutral surfaces, light text, lighter-violet actions; preserve user preference."
          }
        }
      ],
      "good": {
        "zh": "同一按钮引用品牌色和对应前景色；深浅主题一起验证。",
        "en": "Pair the brand token with its on-brand token and verify both themes."
      },
      "bad": {
        "zh": "深色主题继续使用白字配浅紫底，或把分隔线颜色用来显示正文。",
        "en": "Use white text on pale violet in dark mode, or use a border color for body text."
      },
      "checks": [
        {
          "zh": "深浅主题均可读，导出色值与实际界面一致。",
          "en": "Both themes are readable and exported values match the interface."
        },
        {
          "zh": "16 / 24 / 32 px 下 Logo 的中心三角形都能辨认。",
          "en": "The central triangle remains recognizable at 16/24/32px."
        },
        {
          "zh": "页头组合的可见间距约等于大写高度的一半，图形左缘与正文对齐。",
          "en": "The header lockup gap is about half the cap height and the glyph edge aligns with the content edge."
        },
        {
          "zh": "中英标题没有溢出或切断关键短语。",
          "en": "Chinese and English titles fit without breaking key phrases."
        }
      ],
      "tokens": [
        "--lab-color-brand",
        "--lab-color-onBrand",
        "--lab-color-text",
        "--lab-font-sans"
      ],
      "code": [
        {
          "path": "src/lib/design-system.ts",
          "purpose": {
            "zh": "主题与字体参数",
            "en": "Theme and type tokens"
          }
        },
        {
          "path": "src/components/BrandMark.astro",
          "purpose": {
            "zh": "品牌标志组件",
            "en": "Shared brand mark"
          }
        }
      ],
      "dependencies": [],
      "reference": "https://tmall-design.com/#style/element/color",
      "snippet": ".primary {\n  color: var(--lab-color-onBrand);\n  background: var(--lab-color-brand);\n  font-family: var(--lab-font-sans);\n}",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/foundations/"
    },
    {
      "id": "layout",
      "group": "foundation",
      "title": {
        "zh": "栅格、间距与容器",
        "en": "Grid, spacing & containers"
      },
      "definition": {
        "zh": "用容器与间距组织阅读顺序，让同一套内容在手机和桌面自然重排。",
        "en": "Use containers and spacing to preserve reading order as the same content reflows between mobile and desktop."
      },
      "anatomy": [
        {
          "zh": "外层容器控制页面宽度与安全边距。",
          "en": "The outer container sets content width and safe gutters."
        },
        {
          "zh": "内层栅格按内容类型决定列数，卡片内部保持自己的结构。",
          "en": "The inner grid chooses columns by content type; cards preserve their internal anatomy."
        },
        {
          "zh": "相近内容使用小间距，不同主题使用较大区块间距。",
          "en": "Use tighter spacing for related content and larger gaps between topics."
        }
      ],
      "parameters": [
        {
          "name": "layout.maxWidth",
          "value": "1344px",
          "usage": {
            "zh": "本站宽内容容器上限。",
            "en": "Maximum width for the site's wide content container."
          }
        },
        {
          "name": "layout.gutter",
          "value": "≥ 14px",
          "usage": {
            "zh": "窄屏左右最小边距；宽屏由居中容器增加留白。",
            "en": "Minimum narrow-screen gutters; centered wide containers add outer space."
          }
        },
        {
          "name": "layout.breakpoints",
          "value": "700 / 1050px",
          "usage": {
            "zh": "主要重排点；组件也应检查 320px 的长文案。",
            "en": "Primary reflow boundaries; also test long copy at 320px."
          }
        },
        {
          "name": "spacing",
          "value": "4 · 8 · 12 · 16 · 20 · 24 · 32 · 48 · 64",
          "usage": {
            "zh": "先按语义分组，再从间距阶梯中选择。",
            "en": "Group by meaning, then select a spacing step."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/layout.md",
      "states": [
        {
          "name": {
            "zh": "手机",
            "en": "Mobile"
          },
          "behavior": {
            "zh": "单列内容；图片与文本可横向组成紧凑卡片，保持 DOM 阅读顺序。",
            "en": "Single-column content; compact cards may align image and copy horizontally while preserving DOM order."
          }
        },
        {
          "name": {
            "zh": "桌面",
            "en": "Desktop"
          },
          "behavior": {
            "zh": "资源网格使用多列；首页主推与补充推荐按重要性分配宽度。",
            "en": "Use multi-column resource grids; give the homepage lead more space than supporting picks."
          }
        }
      ],
      "good": {
        "zh": "同一容器中的标题、资源网格和底部操作对齐。",
        "en": "Align headings, resource grids, and bottom actions to one container."
      },
      "bad": {
        "zh": "为了凑满首屏把标题区拉高，或让卡片宽度由最长英文决定。",
        "en": "Inflate the heading area to fill the viewport, or let the longest English word set card width."
      },
      "checks": [
        {
          "zh": "320 / 390 / 768 / 1440 px 均无页面横向溢出。",
          "en": "No page overflow at 320/390/768/1440px."
        },
        {
          "zh": "改变列数不会改变阅读顺序或隐藏重要操作。",
          "en": "Changing columns does not reorder reading or hide important actions."
        },
        {
          "zh": "分类页第一张内容卡片在手机首屏可见。",
          "en": "The first category card is visible in the mobile viewport."
        }
      ],
      "tokens": [
        "--lab-width-content",
        "--lab-space-16",
        "--lab-space-24"
      ],
      "code": [
        {
          "path": "src/styles/global.css",
          "purpose": {
            "zh": "容器与目录栅格",
            "en": "Containers and directory grid"
          }
        },
        {
          "path": "src/styles/editorial.css",
          "purpose": {
            "zh": "响应式首页布局",
            "en": "Responsive editorial layout"
          }
        }
      ],
      "dependencies": [
        "foundations"
      ],
      "reference": "https://tmall-design.com/#style/layout/grid",
      "snippet": ".resource-grid {\n  display: grid;\n  grid-template-columns: repeat(3, minmax(0, 1fr));\n  gap: 20px;\n}\n@media (max-width: 700px) {\n  .resource-grid { grid-template-columns: minmax(0, 1fr); }\n}",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/layout/"
    },
    {
      "id": "assets-motion",
      "group": "foundation",
      "title": {
        "zh": "图像、图标与动效",
        "en": "Images, icons & motion"
      },
      "definition": {
        "zh": "素材帮助识别内容，动效说明状态变化；它们都应服务于用户当前的动作。",
        "en": "Assets help identify content; motion explains state changes. Both should support the user's current action."
      },
      "anatomy": [
        {
          "zh": "真实预览：对应原资源，支持读者判断内容。",
          "en": "Real preview: identifies the original resource and helps readers assess it."
        },
        {
          "zh": "概念插图：说明主题，不作为功能实测证据。",
          "en": "Concept illustration: expresses a theme without implying hands-on validation."
        },
        {
          "zh": "图标与过渡：提供辅助识别和及时反馈。",
          "en": "Icons and transitions: aid recognition and timely feedback."
        }
      ],
      "parameters": [
        {
          "name": "icon.size",
          "value": "18 / 20 / 24px",
          "usage": {
            "zh": "按钮、导航和独立功能图标；使用 Phosphor regular。",
            "en": "Button, navigation, and standalone icons; use Phosphor regular."
          }
        },
        {
          "name": "image.ratio",
          "value": "16:10 / 2:1",
          "usage": {
            "zh": "目录封面 / 首页补充预览；手机紧凑卡片另用固定缩略图。",
            "en": "Directory covers / supporting homepage previews; compact mobile cards use a fixed thumbnail."
          }
        },
        {
          "name": "motion.feedback",
          "value": "160ms ease-out",
          "usage": {
            "zh": "按钮反馈、轻量展开；不延迟真实动作。",
            "en": "Button feedback and lightweight reveals without delaying the actual action."
          }
        },
        {
          "name": "motion.reduced",
          "value": "0ms / no transform",
          "usage": {
            "zh": "尊重减少动态效果设置，保留文字反馈。",
            "en": "Respect reduced motion and retain textual feedback."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/assets-motion.md",
      "states": [
        {
          "name": {
            "zh": "正常加载",
            "en": "Loaded"
          },
          "behavior": {
            "zh": "呈现完整预览，装饰性图片使用空替代文本。",
            "en": "Display the preview; use empty alt text for decorative images."
          }
        },
        {
          "name": {
            "zh": "缺失图片",
            "en": "Missing image"
          },
          "behavior": {
            "zh": "保留正文与链接，不用随机生成图冒充产品界面。",
            "en": "Keep text and links; never substitute a fabricated product screenshot."
          }
        },
        {
          "name": {
            "zh": "减少动态效果",
            "en": "Reduced motion"
          },
          "behavior": {
            "zh": "状态即时切换，完成结果仍用文字提示。",
            "en": "Switch states instantly and announce completion in text."
          }
        }
      ],
      "good": {
        "zh": "点击后立即响应，160ms 的轻量反馈只解释变化。",
        "en": "Respond immediately and use a short 160ms transition only to explain the change."
      },
      "bad": {
        "zh": "先播一段装饰动画再执行操作，或自动循环移动正文。",
        "en": "Play decorative animation before acting, or continuously animate reading content."
      },
      "checks": [
        {
          "zh": "图片缺失时内容仍可理解和操作。",
          "en": "Content remains understandable and actionable without images."
        },
        {
          "zh": "减少动态效果模式下没有位移或循环装饰动画。",
          "en": "Reduced-motion mode removes movement and decorative loops."
        },
        {
          "zh": "图标按钮具有可读名称，真实截图与概念插图含义清楚。",
          "en": "Icon buttons have names; real previews and conceptual art are distinguishable."
        }
      ],
      "tokens": [
        "--lab-space-16",
        "--lab-radius-card"
      ],
      "code": [
        {
          "path": "src/components/Icon.astro",
          "purpose": {
            "zh": "图标库入口",
            "en": "Shared icon library"
          }
        },
        {
          "path": "src/components/EditorialPreview.astro",
          "purpose": {
            "zh": "真实预览与无图内容",
            "en": "Real previews and text-only content"
          }
        }
      ],
      "dependencies": [
        "foundations"
      ],
      "reference": "https://tmall-design.com/#style/element/motion",
      "snippet": "@media (prefers-reduced-motion: reduce) {\n  .feedback { animation: none; transition: none; transform: none; }\n}",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/assets-motion/"
    },
    {
      "id": "buttons",
      "group": "component",
      "title": {
        "zh": "按钮与行动层级",
        "en": "Buttons & action hierarchy"
      },
      "definition": {
        "zh": "按钮执行动作，链接进入目标。视觉层级应帮助读者找到当前最重要的下一步。",
        "en": "Buttons perform actions and links navigate. Visual hierarchy should reveal the most useful next step."
      },
      "anatomy": [
        {
          "zh": "文字标签：动词加对象，例如“浏览工具”“复制规则”。",
          "en": "Label: a verb plus an object, such as Explore tools or Copy rules."
        },
        {
          "zh": "可选图标：补充方向或状态，不能替代必要文字。",
          "en": "Optional icon: clarifies direction or state without replacing necessary words."
        },
        {
          "zh": "交互区域：包含内边距、焦点轮廓和禁用语义。",
          "en": "Hit area: includes padding, a focus outline, and disabled semantics."
        }
      ],
      "parameters": [
        {
          "name": "size.regular",
          "value": "44px / 14px",
          "usage": {
            "zh": "常规局部动作的最小高度与文字字号。",
            "en": "Minimum height and label size for regular local actions."
          }
        },
        {
          "name": "size.large",
          "value": "48px / 16px",
          "usage": {
            "zh": "手机主动作；桌面首页主推可用现有 56px 规格。",
            "en": "Primary mobile actions; the desktop editorial lead may use the existing 56px variant."
          }
        },
        {
          "name": "radius.control",
          "value": "7px",
          "usage": {
            "zh": "统一控件圆角；不要把所有按钮改成胶囊。",
            "en": "Consistent control corners; avoid turning every control into a pill."
          }
        },
        {
          "name": "emphasis",
          "value": "primary / secondary / text",
          "usage": {
            "zh": "主动作、补充动作、轻量导航，按任务重要性选择。",
            "en": "Primary action, supporting action, and quiet navigation, chosen by task importance."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/buttons.md",
      "states": [
        {
          "name": {
            "zh": "默认 / 悬停",
            "en": "Default / hover"
          },
          "behavior": {
            "zh": "标签清楚可读；悬停轻微改变表面，不移动布局。",
            "en": "Keep labels readable; hover subtly changes the surface without moving layout."
          }
        },
        {
          "name": {
            "zh": "键盘焦点",
            "en": "Keyboard focus"
          },
          "behavior": {
            "zh": "2px 可见描边与内容分离，Tab 可到达。",
            "en": "Use a separate visible 2px outline and preserve Tab navigation."
          }
        },
        {
          "name": {
            "zh": "加载",
            "en": "Loading"
          },
          "behavior": {
            "zh": "保留动作位置，禁止重复点击，完成后恢复可用并提示结果。",
            "en": "Preserve position, prevent repeats, then restore the control and announce the result."
          }
        },
        {
          "name": {
            "zh": "禁用",
            "en": "Disabled"
          },
          "behavior": {
            "zh": "原生 disabled，不响应鼠标和键盘；必要时说明前置条件。",
            "en": "Native disabled semantics; no mouse or keyboard activation. Explain prerequisites when needed."
          }
        }
      ],
      "good": {
        "zh": "“复制规则”执行本地复制，并给出完成或失败反馈。",
        "en": "Copy rules performs a real clipboard action and reports success or failure."
      },
      "bad": {
        "zh": "按钮写“了解更多”却没有目标，或用低透明度假装禁用。",
        "en": "A Learn more button has no target, or opacity alone pretends to disable a control."
      },
      "checks": [
        {
          "zh": "主次层级、加载和禁用状态都能区分。",
          "en": "Primary, secondary, loading, and disabled states remain distinct."
        },
        {
          "zh": "加载期间重复激活不会再次执行。",
          "en": "Repeated activation during loading cannot repeat the action."
        },
        {
          "zh": "焦点、键盘和两种语言都可用。",
          "en": "Focus, keyboard use, and both languages work."
        }
      ],
      "tokens": [
        "--lab-color-brand",
        "--lab-color-onBrand",
        "--lab-radius-control"
      ],
      "code": [
        {
          "path": "src/components/ActionButton.astro",
          "purpose": {
            "zh": "规范按钮与加载语义",
            "en": "Guideline action button and loading semantics"
          }
        },
        {
          "path": "src/components/FavButton.astro",
          "purpose": {
            "zh": "站内收藏切换",
            "en": "Site favorite toggle"
          }
        }
      ],
      "dependencies": [
        "foundations",
        "assets-motion"
      ],
      "reference": "https://tmall-design.com/#style/component/button",
      "snippet": "import ActionButton from \"../components/ActionButton.astro\";\n\n<ActionButton variant=\"primary\" size=\"regular\">\n  <Loc zh=\"复制规则\" en=\"Copy rules\" />\n</ActionButton>",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/buttons/"
    },
    {
      "id": "resource-cards",
      "group": "component",
      "title": {
        "zh": "资源卡片与收藏",
        "en": "Resource cards & favorites"
      },
      "definition": {
        "zh": "把预览、用途、来源与下一步放在一个可扫描的单元里，帮助读者从发现进入详情。",
        "en": "Combine preview, purpose, source, and next action in a scannable unit that leads readers into a resource."
      },
      "anatomy": [
        {
          "zh": "可选预览 → 目录标签 → 标题 → 短简介 → 来源域名。",
          "en": "Optional preview → section → title → short description → source host."
        },
        {
          "zh": "主链接包裹内容区域，收藏按钮作为相邻独立控件。",
          "en": "The primary link wraps the content; the favorite button is a separate sibling."
        },
        {
          "zh": "稳定键由来源库与原始 id 组成，不能用当前列表位置替代。",
          "en": "Stable keys combine source library and original ID, never list position."
        }
      ],
      "parameters": [
        {
          "name": "card.radius",
          "value": "8px",
          "usage": {
            "zh": "统一卡片边界，悬停仅强调边线。",
            "en": "Consistent card edge; hover emphasizes the border only."
          }
        },
        {
          "name": "card.title",
          "value": "17px / mobile 15px",
          "usage": {
            "zh": "桌面纵向卡片 / 手机紧凑卡片。",
            "en": "Desktop vertical / compact mobile card."
          }
        },
        {
          "name": "card.thumbnail",
          "value": "16:10 / mobile 100×90px",
          "usage": {
            "zh": "桌面封面比例与当前手机缩略图规格。",
            "en": "Desktop cover ratio and current mobile thumbnail size."
          }
        },
        {
          "name": "favorite.key",
          "value": "library:id",
          "usage": {
            "zh": "与详情页和收藏页共用同一个稳定键。",
            "en": "Share the stable key with detail and saved pages."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/resource-cards.md",
      "states": [
        {
          "name": {
            "zh": "有图 / 无图",
            "en": "With / without image"
          },
          "behavior": {
            "zh": "两者都能独立传达用途与来源，图像不决定是否可阅读。",
            "en": "Both communicate purpose and source independently of imagery."
          }
        },
        {
          "name": {
            "zh": "未收藏 / 已收藏",
            "en": "Unsaved / saved"
          },
          "behavior": {
            "zh": "图标、可读标签与 aria-pressed 同步；重复点击可以撤销。",
            "en": "Synchronize icon, label, and aria-pressed; clicking again reverses it."
          }
        },
        {
          "name": {
            "zh": "数据陈旧",
            "en": "Stale data"
          },
          "behavior": {
            "zh": "以真实核验日期和说明表达状态，不自动伪装成“已验证”。",
            "en": "Use real review dates and explanations; never invent a verified badge."
          }
        }
      ],
      "good": {
        "zh": "“CSS Bed：切换 HTML 的 CSS 主题”，附 cssbed.com 来源。",
        "en": "CSS Bed: switch CSS themes for HTML, with the cssbed.com source."
      },
      "bad": {
        "zh": "“最强神器，效率暴涨 100 倍”，没有来源或使用条件。",
        "en": "The ultimate tool: 100× faster, with no source or requirements."
      },
      "checks": [
        {
          "zh": "无图、长中文标题和长英文域名均不溢出。",
          "en": "Missing images, long Chinese titles, and long hosts do not overflow."
        },
        {
          "zh": "收藏与详情跳转可以分别用键盘触发。",
          "en": "Keyboard users can save and navigate independently."
        },
        {
          "zh": "来源库 id 与旧收藏键保持兼容。",
          "en": "Source IDs remain compatible with existing saved keys."
        }
      ],
      "tokens": [
        "--lab-radius-card",
        "--lab-color-surface",
        "--lab-color-border"
      ],
      "code": [
        {
          "path": "src/components/DirectoryCard.astro",
          "purpose": {
            "zh": "卡片结构与链接",
            "en": "Card anatomy and links"
          }
        },
        {
          "path": "src/components/FavButton.astro",
          "purpose": {
            "zh": "收藏按钮",
            "en": "Favorite control"
          }
        },
        {
          "path": "src/lib/directory.ts",
          "purpose": {
            "zh": "统一内容对象",
            "en": "Unified resource objects"
          }
        }
      ],
      "dependencies": [
        "foundations",
        "layout",
        "buttons"
      ],
      "reference": "https://tmall-design.com/#style/component/product-card",
      "snippet": "import DirectoryCard from \"../components/DirectoryCard.astro\";\nimport { entries } from \"../lib/directory\";\nconst entry = entries.find(item => item.key === \"html:css-bed\");\n\n{entry && <DirectoryCard entry={entry} />}",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/resource-cards/"
    },
    {
      "id": "navigation",
      "group": "component",
      "title": {
        "zh": "导航与渐进展开",
        "en": "Navigation & progressive disclosure"
      },
      "definition": {
        "zh": "主导航对应稳定任务目录，把搜索、收藏和站点说明安排在合适层级。",
        "en": "Map primary navigation to stable task sections, with search, saved items, and site information at appropriate levels."
      },
      "anatomy": [
        {
          "zh": "品牌入口与五个任务目录构成全站主导航。",
          "en": "The brand entry and five task sections form the global navigation."
        },
        {
          "zh": "更多菜单承载搜索、更新记录、关于和设计规范。",
          "en": "More contains search, update notes, about, and design guidelines."
        },
        {
          "zh": "独立规范目录仅在规范库出现，不占用资源分类页。",
          "en": "The documentation index appears only in the handbook, not resource sections."
        }
      ],
      "parameters": [
        {
          "name": "nav.active",
          "value": "aria-current=page",
          "usage": {
            "zh": "当前位置不是 hover，离开鼠标后仍保留标记。",
            "en": "The current page is not a hover state and remains marked after pointer exit."
          }
        },
        {
          "name": "menu.primitive",
          "value": "details / summary",
          "usage": {
            "zh": "菜单在无 JavaScript 时仍可展开。",
            "en": "Menus remain operable without JavaScript."
          }
        },
        {
          "name": "list.initial",
          "value": "24",
          "usage": {
            "zh": "目录初始展示 24 条，再按需展开。",
            "en": "Show 24 entries first, then reveal more on request."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/navigation.md",
      "states": [
        {
          "name": {
            "zh": "当前位置",
            "en": "Current page"
          },
          "behavior": {
            "zh": "保留强调与 aria-current，帮助用户定位。",
            "en": "Keep emphasis and aria-current to indicate location."
          }
        },
        {
          "name": {
            "zh": "菜单打开",
            "en": "Menu open"
          },
          "behavior": {
            "zh": "目标全部可读，内容不超出手机视口。",
            "en": "Show readable destinations within the mobile viewport."
          }
        },
        {
          "name": {
            "zh": "加载更多",
            "en": "Reveal more"
          },
          "behavior": {
            "zh": "按序增加内容，不跳回页首；全部显示后隐藏按钮。",
            "en": "Append in order without returning to the top; hide the control once complete."
          }
        }
      ],
      "good": {
        "zh": "进入“学习与工作流”后立即浏览条目，需要查找时再打开搜索。",
        "en": "Browse Learning & workflows immediately and open search when a specific goal emerges."
      },
      "bad": {
        "zh": "每个分类都重复展示搜索、排序、难度和格式控件。",
        "en": "Repeat search, sort, level, and format controls on every category page."
      },
      "checks": [
        {
          "zh": "主导航、菜单和规范目录都能识别当前位置。",
          "en": "Global, menu, and handbook navigation indicate location where relevant."
        },
        {
          "zh": "手机菜单不溢出，Escape 后焦点位置正确。",
          "en": "Mobile menus fit and Escape restores focus."
        },
        {
          "zh": "旧筛选链接仍能进入对应搜索范围。",
          "en": "Legacy filtered links retain their search scope."
        }
      ],
      "tokens": [
        "--lab-color-brand",
        "--lab-logo-mobile"
      ],
      "code": [
        {
          "path": "src/components/Header.astro",
          "purpose": {
            "zh": "全站导航与菜单",
            "en": "Global navigation and menu"
          }
        },
        {
          "path": "src/components/DirectoryListing.astro",
          "purpose": {
            "zh": "渐进展开与旧链接兼容",
            "en": "Progressive reveal and legacy links"
          }
        }
      ],
      "dependencies": [
        "buttons",
        "layout"
      ],
      "reference": "https://tmall-design.com/#style/component/top-bar",
      "snippet": "<a href={withBase(\"learn/\")} aria-current={active ? \"page\" : undefined}>\n  <Loc zh=\"学习与工作流\" en=\"Learning & workflows\" />\n</a>",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/navigation/"
    },
    {
      "id": "feedback",
      "group": "component",
      "title": {
        "zh": "加载、空白与错误反馈",
        "en": "Loading, empty & error feedback"
      },
      "definition": {
        "zh": "让用户理解发生了什么、哪些内容仍可用，以及下一步能做什么。",
        "en": "Explain what happened, what remains usable, and what the user can do next."
      },
      "anatomy": [
        {
          "zh": "状态标题说明当前情况。",
          "en": "A state heading explains the current situation."
        },
        {
          "zh": "短说明给出原因或限制，只写已知事实。",
          "en": "A short explanation gives a known cause or constraint."
        },
        {
          "zh": "恢复动作具体可执行，例如重试或查看全部。",
          "en": "A concrete recovery action offers retry or a broader view."
        }
      ],
      "parameters": [
        {
          "name": "loading",
          "value": "aria-busy=true",
          "usage": {
            "zh": "仅标记正在更新的区域，不封锁无关内容。",
            "en": "Mark the updating region without blocking unrelated content."
          }
        },
        {
          "name": "status",
          "value": "role=status / polite",
          "usage": {
            "zh": "复制完成、收藏变更等非阻断结果。",
            "en": "Non-blocking results such as copied text or saved state."
          }
        },
        {
          "name": "feedback.duration",
          "value": "4.5s",
          "usage": {
            "zh": "短暂操作提示可自动消失；错误原因留在原区域。",
            "en": "Transient confirmations may clear automatically; persistent errors remain in context."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/feedback.md",
      "states": [
        {
          "name": {
            "zh": "加载中",
            "en": "Loading"
          },
          "behavior": {
            "zh": "展示稳定占位；完成后替换为内容并结束 busy 状态。",
            "en": "Show a stable placeholder, then replace it with content and clear busy state."
          }
        },
        {
          "name": {
            "zh": "无匹配",
            "en": "No matches"
          },
          "behavior": {
            "zh": "说明当前没有匹配项，提供清除条件或浏览入口。",
            "en": "Explain the lack of matches and offer reset or browsing."
          }
        },
        {
          "name": {
            "zh": "失败",
            "en": "Failure"
          },
          "behavior": {
            "zh": "保留上下文，重试只作用于失败模块。",
            "en": "Keep context and retry the affected module only."
          }
        },
        {
          "name": {
            "zh": "完成",
            "en": "Complete"
          },
          "behavior": {
            "zh": "即时反馈并保留可继续操作的状态。",
            "en": "Announce completion while keeping the interface usable."
          }
        }
      ],
      "good": {
        "zh": "“未能复制，可选中文字或下载文件”，仍保留文档。",
        "en": "Copy failed; select the text or download the file, while keeping the document accessible."
      },
      "bad": {
        "zh": "仅弹出“错误”，或因一张预览失败让整页不可点击。",
        "en": "Show only Error, or block the whole page because one preview failed."
      },
      "checks": [
        {
          "zh": "加载、无匹配和失败状态可以分别触发与恢复。",
          "en": "Loading, no-match, and failure states can each be triggered and recovered."
        },
        {
          "zh": "反馈通过可读文本表达，读屏能收到结果。",
          "en": "Readable text and live status expose the result."
        },
        {
          "zh": "恢复后焦点仍在有意义的位置。",
          "en": "Recovery leaves focus in a meaningful place."
        }
      ],
      "tokens": [
        "--lab-color-success",
        "--lab-color-warning",
        "--lab-color-error",
        "--lab-color-soft"
      ],
      "code": [
        {
          "path": "src/components/DirectoryExplorer.astro",
          "purpose": {
            "zh": "真实搜索空状态",
            "en": "Real search empty state"
          }
        },
        {
          "path": "src/components/BrandSpecDemo.astro",
          "purpose": {
            "zh": "状态转换与恢复演示",
            "en": "State transitions and recovery examples"
          }
        }
      ],
      "dependencies": [
        "buttons",
        "assets-motion"
      ],
      "reference": "https://tmall-design.com/#case/feed",
      "snippet": "<section aria-busy=\"true\" aria-label=\"资源列表\">\n  <!-- Keep the layout stable while loading. -->\n</section>\n<p role=\"status\" aria-live=\"polite\"></p>",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/feedback/"
    },
    {
      "id": "page-patterns",
      "group": "pattern",
      "title": {
        "zh": "首页、分类与详情模板",
        "en": "Home, section & detail patterns"
      },
      "definition": {
        "zh": "按用户意图选择最小必要结构：发现内容、直接浏览、定向查找或理解用法。",
        "en": "Choose the smallest useful structure for discovery, browsing, targeted search, or understanding a resource."
      },
      "anatomy": [
        {
          "zh": "首页：主推与补充 → 最近更新 → 目录 → 入门入口。",
          "en": "Home: lead and supporting picks → recent updates → sections → starter guides."
        },
        {
          "zh": "分类：标题与简介 → 数量 → 最新列表 → 继续展开。",
          "en": "Category: title and description → count → newest entries → progressive reveal."
        },
        {
          "zh": "详情：用途 → 来源与日期 → 用法与限制 → 相关资源。",
          "en": "Detail: purpose → source and dates → usage and limits → related resources."
        },
        {
          "zh": "搜索：查询与筛选 → 结果数量 → 结果 / 空状态。",
          "en": "Search: query and filters → count → results or empty state."
        }
      ],
      "parameters": [
        {
          "name": "home.featured",
          "value": "1 lead + creative rail",
          "usage": {
            "zh": "仅为首页主推与创意轨分配强层级。",
            "en": "Reserve strong editorial hierarchy for the homepage lead and creative rail."
          }
        },
        {
          "name": "category.order",
          "value": "updatedAt desc / key asc",
          "usage": {
            "zh": "按已有更新日期排序，相同日期保持稳定顺序。",
            "en": "Sort by existing update date, then stable key for ties."
          }
        },
        {
          "name": "detail.evidence",
          "value": "source + context",
          "usage": {
            "zh": "区分来源核对、作者声称与操作实测。",
            "en": "Distinguish source checks, author claims, and hands-on testing."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/page-patterns.md",
      "states": [
        {
          "name": {
            "zh": "内容充足",
            "en": "Enough content"
          },
          "behavior": {
            "zh": "保持精选与最新条目的角色区分，渐进展示长列表。",
            "en": "Separate editorial and recent roles; progressively reveal long lists."
          }
        },
        {
          "name": {
            "zh": "内容稀少",
            "en": "Sparse content"
          },
          "behavior": {
            "zh": "使用直接列表，不填充无内容的大模块。",
            "en": "Use a direct list without large empty modules."
          }
        },
        {
          "name": {
            "zh": "定向查找",
            "en": "Targeted search"
          },
          "behavior": {
            "zh": "进入独立搜索页，URL 保留条件便于分享。",
            "en": "Use the dedicated search page with shareable URL state."
          }
        }
      ],
      "good": {
        "zh": "三个真正值得看的推荐，比十个没有理由的占位模块更有用。",
        "en": "Three justified picks are more useful than ten unexplained placeholder modules."
      },
      "bad": {
        "zh": "照搬电商价格、优惠券和促销倒计时到 AI 资源目录。",
        "en": "Copy prices, coupons, or promotional countdowns into an AI resource directory."
      },
      "checks": [
        {
          "zh": "首屏直接回答“这里有什么、下一步做什么”。",
          "en": "The viewport answers what is here and what to do next."
        },
        {
          "zh": "每个模块都有真实内容来源与明确目的。",
          "en": "Each module has a real content source and purpose."
        },
        {
          "zh": "页面稀疏、空结果和长列表都有合理结构。",
          "en": "Sparse, empty-result, and long-list pages have appropriate structures."
        }
      ],
      "tokens": [
        "--lab-width-content",
        "--lab-space-24",
        "--lab-space-48"
      ],
      "code": [
        {
          "path": "src/components/HomeShell.astro",
          "purpose": {
            "zh": "编辑精选首页",
            "en": "Editorial homepage"
          }
        },
        {
          "path": "src/pages/[section].astro",
          "purpose": {
            "zh": "分类页",
            "en": "Category page"
          }
        },
        {
          "path": "src/pages/search.astro",
          "purpose": {
            "zh": "独立搜索页",
            "en": "Dedicated search page"
          }
        }
      ],
      "dependencies": [
        "resource-cards",
        "navigation",
        "feedback",
        "layout"
      ],
      "reference": "https://tmall-design.com/#case/feed",
      "snippet": "import DirectoryListing from \"../components/DirectoryListing.astro\";\n\n<h1><Loc zh=\"学习与工作流\" en=\"Learning & workflows\" /></h1>\n<p><Loc zh=\"从教程开始实践。\" en=\"Start with a practical guide.\" /></p>\n<DirectoryListing section=\"learn\" />",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/page-patterns/"
    },
    {
      "id": "ai-workflow",
      "group": "workflow",
      "title": {
        "zh": "AI 工作说明与代码映射",
        "en": "AI briefs & code mapping"
      },
      "definition": {
        "zh": "让 AI 先理解任务，再查需要的规则，最后按现有组件实现并验证。",
        "en": "Have AI understand the task, retrieve relevant rules, implement with existing components, and verify the result."
      },
      "anatomy": [
        {
          "zh": "任务：页面类型、读者、目标与真实内容来源。",
          "en": "Task: page type, audience, outcome, and real content source."
        },
        {
          "zh": "规则：相关对象的定义、参数、使用边界与状态。",
          "en": "Rules: definitions, parameters, constraints, and states for relevant objects."
        },
        {
          "zh": "映射：稳定对象 id、依赖、变量名和实际代码文件。",
          "en": "Mapping: stable IDs, dependencies, tokens, and actual source files."
        },
        {
          "zh": "验收：截图、交互和构建结果与规则对照。",
          "en": "Review: compare screenshots, interactions, and build results against the rules."
        }
      ],
      "parameters": [
        {
          "name": "knowledge.json",
          "value": "structured registry",
          "usage": {
            "zh": "检索对象、依赖与代码位置；不是自动生成服务。",
            "en": "Retrieve objects, dependencies, and code locations; it is not a generation service."
          }
        },
        {
          "name": "rules/*.md",
          "value": "one object / file",
          "usage": {
            "zh": "按需给 AI 对应规范，减少无关上下文。",
            "en": "Give AI the relevant object guide without unrelated context."
          }
        },
        {
          "name": "task",
          "value": "create / modify / review",
          "usage": {
            "zh": "区分新建、改动和检查，明确交付内容。",
            "en": "Differentiate creation, modification, and review outputs."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/ai-workflow.md",
      "states": [
        {
          "name": {
            "zh": "新建",
            "en": "Create"
          },
          "behavior": {
            "zh": "给出页面结构、组件选择和响应式方案，再实现。",
            "en": "Specify structure, components, and responsive behavior before implementing."
          }
        },
        {
          "name": {
            "zh": "修改",
            "en": "Modify"
          },
          "behavior": {
            "zh": "说明目标区域、需要保留的内容与改动依据。",
            "en": "Identify the target area, retained context, and rationale."
          }
        },
        {
          "name": {
            "zh": "检查",
            "en": "Review"
          },
          "behavior": {
            "zh": "输出问题、对应规则、证据与修改建议，不把建议写成已完成。",
            "en": "Report findings, rule IDs, evidence, and recommendations without claiming implementation."
          }
        }
      ],
      "good": {
        "zh": "读取 resource-cards 规则和实际组件，再改卡片简介与状态。",
        "en": "Read resource-cards and its actual implementation before changing copy and states."
      },
      "bad": {
        "zh": "只输入“高级、科技、简洁”，让 AI 自行猜测品牌、内容和操作。",
        "en": "Ask only for premium, futuristic, minimal and let AI guess brand, content, and behavior."
      },
      "checks": [
        {
          "zh": "工作说明包含任务、目标页面、相关规则和验收方式。",
          "en": "The brief includes task, target page, relevant rules, and validation."
        },
        {
          "zh": "映射中的组件路径确实存在。",
          "en": "Every mapped source path exists."
        },
        {
          "zh": "没有把示例服务或 MCP 配置描述为已部署能力。",
          "en": "Examples and MCP configurations are not presented as deployed capabilities."
        }
      ],
      "tokens": [],
      "code": [
        {
          "path": "src/lib/design-knowledge.ts",
          "purpose": {
            "zh": "规则与映射注册表",
            "en": "Rules and mapping registry"
          }
        },
        {
          "path": "src/components/BrandBriefBuilder.astro",
          "purpose": {
            "zh": "任务工作说明生成器",
            "en": "Task brief builder"
          }
        }
      ],
      "dependencies": [
        "page-patterns"
      ],
      "reference": "https://tmall-design.com/#blog/building-design-wiki-for-aigui",
      "snippet": "// Read the public knowledge registry, then the referenced source files.\nconst knowledge = await fetch(\"/ai-up-lab/brand/knowledge.json\")\n  .then(response => response.json());\nconst cardSpec = knowledge.objects.find(item => item.id === \"resource-cards\");",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/ai-workflow/"
    },
    {
      "id": "review",
      "group": "workflow",
      "title": {
        "zh": "设计验收与维护",
        "en": "Design review & maintenance"
      },
      "definition": {
        "zh": "把品牌一致性、交互完整性和内容可靠性变成可复核的验收项。",
        "en": "Make brand consistency, interaction completeness, and content reliability reviewable."
      },
      "anatomy": [
        {
          "zh": "基础：Logo、语义色彩、字号与间距。",
          "en": "Foundations: logo, semantic color, type, and spacing."
        },
        {
          "zh": "交互：焦点、状态、键盘、恢复路径与收藏。",
          "en": "Interaction: focus, states, keyboard, recovery, and saved items."
        },
        {
          "zh": "内容：来源、日期、双语与真实用途。",
          "en": "Content: sources, dates, both languages, and real purpose."
        },
        {
          "zh": "维护：版本、共用参数、代码映射与静态导出同步。",
          "en": "Maintenance: synchronize versions, shared tokens, code mappings, and exports."
        }
      ],
      "parameters": [
        {
          "name": "severity.blocking",
          "value": "broken / misleading",
          "usage": {
            "zh": "无法完成任务、内容错误、链接失效或关键操作不可达。",
            "en": "Broken tasks, incorrect content, dead links, or inaccessible core actions."
          }
        },
        {
          "name": "severity.major",
          "value": "hierarchy / states",
          "usage": {
            "zh": "首屏内容被挤走、关键状态缺失、手机严重溢出。",
            "en": "Buried content, missing key states, or major mobile overflow."
          }
        },
        {
          "name": "severity.polish",
          "value": "consistency",
          "usage": {
            "zh": "局部间距、非关键文案和轻微视觉差异。",
            "en": "Local spacing, non-critical wording, and minor visual inconsistencies."
          }
        }
      ],
      "rules": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/rules/review.md",
      "states": [
        {
          "name": {
            "zh": "待检查",
            "en": "Not checked"
          },
          "behavior": {
            "zh": "没有运行就保留待检查，不预先勾选。",
            "en": "Keep items unchecked until verified."
          }
        },
        {
          "name": {
            "zh": "发现问题",
            "en": "Issue found"
          },
          "behavior": {
            "zh": "记录证据、严重度和修复动作。",
            "en": "Record evidence, severity, and the fix."
          }
        },
        {
          "name": {
            "zh": "已验证",
            "en": "Verified"
          },
          "behavior": {
            "zh": "记录实际验证范围，改动后复查相关项。",
            "en": "Record the verified scope and recheck affected items after changes."
          }
        }
      ],
      "good": {
        "zh": "“390px 下分类首卡可见，按钮可键盘触发”，附截图或检查结果。",
        "en": "At 390px, the first card is visible and actions are keyboard-operable, with evidence."
      },
      "bad": {
        "zh": "只写“看起来不错”或把所有检查默认标记为通过。",
        "en": "Write only looks good or mark all checks as passed by default."
      },
      "checks": [
        {
          "zh": "检查记录能对应具体页面与规则。",
          "en": "Review records identify the page and rule."
        },
        {
          "zh": "重要问题已关闭，剩余问题明确说明。",
          "en": "Important findings are resolved and remaining ones are explicit."
        },
        {
          "zh": "构建通过，相关交互已实际操作。",
          "en": "The build passes and affected interactions were exercised."
        }
      ],
      "tokens": [],
      "code": [
        {
          "path": "scripts/verify-build.mjs",
          "purpose": {
            "zh": "构建与规范数据检查",
            "en": "Build and design-data verification"
          }
        }
      ],
      "dependencies": [
        "foundations",
        "layout",
        "buttons",
        "resource-cards",
        "feedback"
      ],
      "reference": "https://tmall-design.com/#blog/building-design-wiki-for-aigui",
      "snippet": "npm run build\n# Then exercise affected pages in both themes and languages.\n# Capture evidence at 320, 390, 768, and 1440 CSS px.",
      "url": "https://mostdesign01-sudo.github.io/ai-up-lab/brand/guides/review/"
    }
  ]
}