Back to Details

design-systems-frontend-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Systems Frontend Architecture

设计系统前端架构

Purpose

目标

Help an agent convert UI, UX, product, and brand decisions into a durable frontend system: reusable components, tokens, layout rules, state behavior, documentation, governance, and implementation guidance that can scale across screens, teams, devices, and time.
Optimize for actual product work. Do not merely describe design systems. Produce decisions, defaults, component contracts, implementation guidance, critiques, and next steps the user can act on.
帮助Agent将UI、UX、产品及品牌决策转化为可长期使用的前端系统：包含可复用组件、tokens、布局规则、状态行为、文档、治理机制，以及可跨屏幕、团队、设备和时间扩展的实施指南。
以实际产品工作为优化核心，不要仅停留在描述设计系统层面。要产出用户可落地执行的决策、默认规则、组件契约、实施指南、评审意见及下一步行动。

When to use this skill

适用场景

Use this skill when the user asks for any of the following:
  • Design-system strategy, component libraries, pattern libraries, style guides, design tokens, UI kits, component audits, interface inventories, or governance.
  • UI critique, redesign, frontend implementation plans, component decomposition, responsive layout guidance, CSS architecture, or frontend maintainability.
  • Turning mockups, screenshots, UX flows, or product requirements into scalable frontend components.
  • Documentation for components, tokens, accessibility states, usage guidance, or design-to-code handoff.
  • Resolving inconsistency across UI surfaces, duplicated patterns, ad hoc styling, or component drift.
当用户提出以下需求时，可使用本技能：
  • 设计系统策略、组件库、模式库、样式指南、design tokens、UI套件、组件审计、界面清单或治理机制相关需求。
  • UI评审、重设计、前端实施计划、组件拆解、响应式布局指导、CSS架构或前端可维护性相关需求。
  • 将原型图、截图、UX流程或产品需求转化为可扩展前端组件的需求。
  • 组件、tokens、无障碍状态、使用指南或设计转开发交接文档的编写需求。
  • 解决UI界面不一致、重复模式、临时样式或组件漂移问题的需求。

When not to use this skill

不适用场景

Do not use this skill as the primary lens when the task is mainly:
  • Broad UX research planning, ethnography, discovery interviews, market research, or product strategy not yet connected to UI/system decisions.
  • Visual art direction, illustration style, campaign creative, or brand identity creation unless the user is converting it into system rules.
  • Pure backend architecture, API design, data modeling, or infrastructure.
  • One-off static graphic design where reuse, accessibility, and frontend implementation do not matter.
当任务主要为以下内容时，请勿将本技能作为核心工具：
  • 尚未与UI/系统决策关联的广泛UX研究规划、人种学研究、发现访谈、市场调研或产品策略。
  • 视觉艺术指导、插画风格、营销创意或品牌标识创建（除非用户要将其转化为系统规则）。
  • 纯后端架构、API设计、数据建模或基础设施相关工作。
  • 无需复用、无障碍支持和前端实现的一次性静态平面设计。

Core principles

核心原则

  1. Design systems, not pages. Scope effort by components, templates, content types, states, integrations, and behaviors rather than by page count.
  2. Think simultaneously in parts and wholes. Evaluate tokens, atoms, components, sections, templates, and real pages together. Do not design a component without checking how it works in realistic compositions and content.
  3. Separate function from perception. Treat functional patterns as behavioral/interface modules and perceptual patterns as the style, tone, motion, spacing, color, and type treatments that create product character.
  4. Start with purpose before abstraction. A component exists to solve a user or product problem. Do not create abstractions from visual similarity alone.
  5. Use shared language as infrastructure. Names, definitions, usage rules, and examples are part of the system, not decoration around it.
  6. Prefer reusable primitives, but preserve product distinctiveness. Consistency should reduce user effort and team waste; it should not erase useful brand expression or signature moments.
  7. Make the system the source of truth. Changes to shipped UI should update the component, token, or guideline where appropriate; avoid isolated hotfixes.
  8. Treat accessibility as a component contract. Semantics, keyboard behavior, focus, contrast, hit areas, error handling, and reduced-motion behavior must be specified with the pattern.
  9. Choose frontend architecture early enough to prevent debt, but keep it adaptable. Establish conventions before implementation spreads, then revise them intentionally as the product evolves.
  10. Document for use, not archival. Documentation must answer when to use a pattern, when not to use it, how it behaves, how it is implemented, and who owns it.
See references/principle-cards.md for each principle as a reusable card.
  1. 设计系统而非页面：以组件、模板、内容类型、状态、集成和行为为范围规划工作，而非按页面数量划分。
  2. 同时兼顾局部与整体：协同评估tokens、原子、组件、区块、模板及真实页面。设计组件时，必须检查其在真实组合场景和内容中的表现。
  3. 分离功能与感知：将功能模式视为行为/界面模块，将感知模式视为构建产品特质的样式、色调、动效、间距、色彩和字体处理规则。
  4. 先明确目标再抽象：组件的存在是为了解决用户或产品问题，不要仅因视觉相似性就创建抽象组件。
  5. 将共享语言作为基础设施：命名、定义、使用规则及示例是系统的一部分，而非附加装饰。
  6. 优先复用基础元素，但保留产品独特性：一致性应减少用户操作成本和团队冗余工作，而非消除有用的品牌表达或标志性场景。
  7. 让系统成为唯一可信源：已上线UI的变更应同步更新对应的组件、token或指南；避免孤立的临时修复。
  8. 将无障碍作为组件契约的一部分：语义、键盘行为、焦点、对比度、点击区域、错误处理和低动效行为必须与模式一同明确规定。
  9. 尽早确定前端架构以避免技术债务，但保持适应性：在实施范围扩大前建立规范，随后随着产品演进有意地修订规范。
  10. 为使用而非归档而文档：文档必须回答何时使用某模式、何时不使用、其行为方式、实现方式及负责人。
查看references/principle-cards.md获取每个原则的可复用卡片版本。

Default recommendations

默认推荐方案

Use these defaults unless the user provides context that clearly calls for a different choice.
除非用户提供明确要求不同方案的上下文，否则默认使用以下规则。

Product and scope defaults

产品与范围默认规则

  • Default scope: define the smallest useful system slice: tokens + 3-5 core components + 1-2 representative templates + documentation. This avoids a bloated “big bang” system.
  • Default prioritization: prioritize high-frequency, high-risk patterns first: buttons, links, forms, alerts, navigation, cards/lists, layout primitives, type scale, spacing, color semantics, loading/empty/error states.
  • Default migration: improve incrementally. Prefer component-by-component replacement and deprecation over a full redesign unless the product is early-stage or a major platform migration is already happening.
  • 默认范围：定义最小可用系统切片：tokens + 3-5个核心组件 + 1-2个代表性模板 + 文档。避免构建臃肿的“大爆炸”式系统。
  • 默认优先级：优先处理高频、高风险模式：按钮、链接、表单、提示框、导航、卡片/列表、布局基础元素、字体层级、间距、色彩语义、加载/空/错误状态。
  • 默认迁移方式：渐进式改进。除非产品处于早期阶段或正在进行重大平台迁移，否则优先采用逐个组件替换和弃用的方式，而非全面重设计。

Design-system structure defaults

设计系统结构默认规则

  • Default model: use a layered system: foundations/tokens → primitives → components → compositions/templates → product examples/pages.
  • Default naming: name patterns by purpose, not appearance. Prefer 
    Primary action
    , 
    Course card
    , 
    Filter panel
    , 
    Inline validation
    , or 
    Promotion banner
    over 
    blue button
    , 
    big box
    , or 
    right rail thing
    .
  • Default documentation: every reusable pattern gets purpose, anatomy, variants, states, accessibility contract, content guidance, responsive behavior, implementation notes, examples, and anti-examples.
  • Default governance: use light curation. Allow contribution, but require review for new tokens/components and require evidence before adding variants.
  • 默认模型：采用分层系统：基础层/tokens → 基础组件 → 业务组件 → 组合/模板 → 产品示例/页面。
  • 默认命名规则：按用途而非外观命名模式。优先使用
    Primary action
    、
    Course card
    、
    Filter panel
    、
    Inline validation
    或
    Promotion banner
    ，而非“蓝色按钮”“大盒子”或“右侧栏模块”。
  • 默认文档规则：每个可复用模式都需包含用途、结构、变体、状态、无障碍契约、内容指导、响应式行为、实现说明、示例及反例。
  • 默认治理规则：采用轻量化管理。允许贡献，但新增tokens/组件需经过评审，且添加变体需提供依据。

Token defaults

Token默认规则

  • Default token categories: color, typography, spacing, radius, border, elevation/shadow, motion, opacity, z-index/layer, size, breakpoint/container, and semantic state tokens.
  • Default token shape: separate primitive values from semantic tokens. Example: primitive 
    color.blue.600
    ; semantic 
    color.action.primary.bg
    ; component token 
    button.primary.bg
    only when component-specific mapping is necessary.
  • Default naming: use role and state rather than raw appearance. Prefer 
    text.muted
    , 
    surface.raised
    , 
    border.focus
    , 
    status.error.fg
    over 
    gray-500-for-labels
    .
  • Default override rule: do not introduce a new token for a single exception. First test whether an existing semantic token, component variant, or local product need already covers the case.
  • 默认Token分类：色彩、排版、间距、圆角、边框、阴影/层级、动效、透明度、z-index/层级、尺寸、断点/容器及语义状态tokens。
  • 默认Token结构：将原始值与语义token分离。示例：原始值
    color.blue.600
    ；语义token
    color.action.primary.bg
    ；仅当需要组件特定映射时才使用组件token
    button.primary.bg
    。
  • 默认命名规则：按角色和状态而非原始外观命名。优先使用
    text.muted
    、
    surface.raised
    、
    border.focus
    、
    status.error.fg
    ，而非“标签用灰色-500”。
  • 默认覆盖规则：不要为单个例外新增token。首先测试现有语义token、组件变体或本地产品需求是否已覆盖该场景。

Layout and responsive defaults

布局与响应式默认规则

  • Default layout strategy: design content-first, intrinsically responsive layouts using flexible containers, grid/flex primitives, fluid spacing, and container-aware rules. Avoid designing separate desktop/tablet/mobile screens as unrelated artifacts.
  • Default breakpoints: use only enough breakpoints to protect readability, navigation, and task completion. Prefer component/container behavior over global viewport choreography.
  • Default density: start with moderate density and generous scanability. Increase density only when expert workflows, data-heavy tasks, or screen real estate constraints justify it.
  • Default content testing: test with real or realistic content, including long labels, missing images, empty data, error states, loading states, dense data, and translated strings when relevant.
  • 默认布局策略：采用内容优先的内在响应式布局，使用灵活容器、网格/弹性布局基础元素、流式间距及容器感知规则。避免将桌面/平板/移动端屏幕作为无关工件单独设计。
  • 默认断点：仅使用足够的断点来保障可读性、导航和任务完成。优先采用组件/容器行为而非全局视口编排。
  • 默认密度：从中等密度和高可读性开始。仅当专家工作流、数据密集型任务或屏幕空间限制需要时，才增加密度。
  • 默认内容测试：使用真实或模拟内容测试，包括长标签、缺失图片、空数据、错误状态、加载状态、密集数据及相关翻译文本。

CSS and frontend defaults

CSS与前端默认规则

  • Default markup: semantic HTML first. Add ARIA only to fill semantic gaps, not to replace native semantics.
  • Default CSS: component-scoped, low-specificity, token-driven CSS. Avoid styling through deep page location selectors.
  • Default methodology: pick or adapt a clear naming and layering convention. BEM-like naming, utility layers, CSS modules, or framework-scoped styles can all work if the rules are explicit and consistent.
  • Default JS: do not use JavaScript for effects CSS handles reliably. Use JS when behavior, state, data, or accessibility requires it.
  • Default custom controls: start with native controls. If custom styling is needed, preserve native semantics, labels, keyboard behavior, focus visibility, and form behavior.
  • Default build/process: automate linting, formatting, type checks where applicable, accessibility checks, visual regression for important components, and preview/documentation builds.
  • 默认标记：优先使用语义化HTML。仅在语义存在缺口时添加ARIA，而非替代原生语义。
  • 默认CSS：组件作用域、低优先级、token驱动的CSS。避免通过深层页面位置选择器进行样式设置。
  • 默认方法论：选择或调整清晰的命名和分层约定。如果规则明确且一致，类BEM命名、工具层、CSS modules或框架作用域样式均可使用。
  • 默认JS规则：CSS可可靠处理的效果，不要使用JavaScript实现。仅当行为、状态、数据或无障碍需求需要时才使用JS。
  • 默认自定义控件：从原生控件开始。如果需要自定义样式，需保留原生语义、标签、键盘行为、焦点可见性和表单行为。
  • 默认构建流程：自动化 linting、格式化、类型检查（如适用）、无障碍检查、重要组件的视觉回归测试，以及预览/文档构建。

Accessibility defaults

无障碍默认规则

  • Default target: meet WCAG 2.2 AA expectations unless the user has a stricter internal standard.
  • Default contrast: text and meaningful UI indicators must meet contrast requirements; do not rely on color alone for state.
  • Default focus: all interactive controls need visible focus and keyboard operation.
  • Default targets: small controls need usable hit areas, especially for touch and motor accessibility.
  • Default motion: motion should be purposeful, brief, interruptible when possible, and honor reduced-motion preferences.
  • 默认目标：满足WCAG 2.2 AA要求，除非用户有更严格的内部标准。
  • 默认对比度：文本和有意义的UI指示器必须符合对比度要求；不要仅依赖颜色区分状态。
  • 默认焦点：所有交互控件需要可见焦点和键盘操作支持。
  • 默认目标区域：小控件需要可用的点击区域，尤其针对触摸和运动无障碍需求。
  • 默认动效：动效应有明确目的、时长简短、尽可能可中断，并尊重低动效偏好设置。

Required user questions

必问用户问题

Ask only when the answer materially changes the system. Do not ask users to decide routine best practices.
Ask a focused question when any of these are unknown and relevant:
  • The product goal, user task, or target audience is unclear.
  • The user asks for a new system, but the brand/product personality or existing system maturity is unknown.
  • The work must integrate with an existing frontend stack, CMS, component framework, or token format.
  • The product has unusual accessibility, regulatory, performance, device, localization, or data-density constraints.
  • The user wants a recommendation that depends on governance, team size, release process, or contribution model.
  • The user asks to override a default that would affect accessibility, implementation cost, brand consistency, or maintainability.
When asking, include a recommended default and options. Use a 
question
tool or equivalent pattern when available.
Use the question-tool-ready prompts in references/decision-prompts.md.
仅当答案会实质性改变系统时才提问。不要让用户决定常规最佳实践。
当以下信息未知且相关时，提出针对性问题：
  • 产品目标、用户任务或目标受众不明确。
  • 用户要求构建新系统，但品牌/产品个性或现有系统成熟度未知。
  • 工作需要与现有前端栈、CMS、组件框架或token格式集成。
  • 产品存在特殊的无障碍、合规、性能、设备、本地化或数据密度约束。
  • 用户需要依赖治理机制、团队规模、发布流程或贡献模型的推荐方案。
  • 用户要求覆盖影响无障碍、实施成本、品牌一致性或可维护性的默认规则。
提问时需包含推荐的默认选项。如有可用工具，请使用
question
工具或类似模式。
使用references/decision-prompts.md中的就绪型提问模板。

Workflow: critique existing work

工作流：评审现有工作

When reviewing an existing UI, design system, component library, or frontend implementation, inspect in this order:
  1. Task fit and product purpose — What user goal is the UI solving? Are the main actions and outcomes clear?
  2. System coverage — What tokens, components, templates, and states already exist? What is duplicated or missing?
  3. Information hierarchy — Are primary, secondary, and tertiary elements distinguishable without decorative overuse?
  4. Functional patterns — Are modules named, purposeful, reusable, and behaviorally clear?
  5. Perceptual patterns — Are color, type, spacing, motion, imagery, and tone consistent with the intended personality?
  6. Layout and responsiveness — Does the layout adapt from content and container needs rather than arbitrary breakpoints?
  7. Interaction clarity — Are affordances, states, validation, loading, errors, empty states, and edge cases specified?
  8. Accessibility — Check semantics, keyboard flow, focus, contrast, labels, target size, reading order, motion, and assistive text.
  9. Frontend feasibility — Inspect markup complexity, CSS specificity, token mapping, dependencies, performance risk, and testability.
  10. Documentation and governance — Is there a source of truth, ownership, contribution path, and deprecation process?
Output critiques as: highest-risk issue → why it matters → recommended fix → system implication → implementation note. Avoid long unordered lists of visual opinions.
评审现有UI、设计系统、组件库或前端实现时，按以下顺序检查：
  1. 任务适配与产品目标：该UI解决了什么用户目标？主要操作和结果是否清晰？
  2. 系统覆盖范围：已存在哪些tokens、组件、模板和状态？哪些内容重复或缺失？
  3. 信息层级：主次三级元素是否无需过度装饰即可区分？
  4. 功能模式：模块是否命名清晰、有明确用途、可复用且行为明确？
  5. 感知模式：颜色、字体、间距、动效、图像和色调是否与预期个性一致？
  6. 布局与响应式：布局是否根据内容和容器需求自适应，而非依赖任意断点？
  7. 交互清晰度：是否明确规定了交互提示、状态、验证、加载、错误、空状态和边缘情况？
  8. 无障碍：检查语义、键盘流程、焦点、对比度、标签、目标尺寸、阅读顺序、动效和辅助文本。
  9. 前端可行性：检查标记复杂度、CSS优先级、token映射、依赖项、性能风险和可测试性。
  10. 文档与治理：是否存在可信源、负责人、贡献路径和弃用流程？
评审意见按以下结构输出：最高风险问题 → 影响原因 → 推荐修复方案 → 系统影响 → 实施说明。避免冗长的无序列表式视觉意见。

Workflow: create or improve a system

工作流：创建或优化系统

When creating a new recommendation, proceed in this order:
  1. Clarify the feature or user problem. Identify the main task, audience, platform, existing constraints, and success criteria.
  2. Choose the smallest useful system slice. Do not start with an exhaustive component catalog.
  3. Inventory existing patterns. Look for repeated functions, repeated styles, duplicated code, inconsistent names, and recurring states.
  4. Define functional patterns. Group UI by purpose and behavior, then name components by what they do.
  5. Define perceptual patterns. Extract the product’s signature treatments: type, color, spacing, shape, motion, imagery, tone, and state expression.
  6. Establish tokens. Convert recurring perceptual decisions into primitive, semantic, and component-level tokens where useful.
  7. Specify component contracts. For each component, document anatomy, variants, states, content rules, accessibility behavior, responsive behavior, and implementation guidance.
  8. Compose templates with real content. Validate components in actual flows and page-level compositions.
  9. Plan implementation architecture. Choose semantic markup, CSS strategy, component boundaries, build/test pipeline, distribution, and migration path.
  10. Document and govern. Define ownership, contribution, review, release, deprecation, and adoption workflow.
  11. Validate. Run quality, accessibility, responsive, performance, and maintainability checks before finalizing.
  12. Explain decisions. Tie recommendations to user goals, system consistency, accessibility, maintainability, and implementation cost.
制定新推荐方案时，按以下步骤进行：
  1. 明确功能或用户问题：确定主要任务、受众、平台、现有约束和成功标准。
  2. 选择最小可用系统切片：不要从详尽的组件目录开始。
  3. 盘点现有模式：查找重复的功能、样式、代码、不一致的命名和重复出现的状态。
  4. 定义功能模式：按用途和行为对UI进行分组，然后按组件功能命名。
  5. 定义感知模式：提取产品的标志性处理规则：字体、颜色、间距、形状、动效、图像、色调和状态表达。
  6. 建立tokens：将重复出现的感知决策转化为有用的原始、语义和组件级tokens。
  7. 明确组件契约：为每个组件文档化结构、变体、状态、内容规则、无障碍行为、响应式行为和实施指南。
  8. 用真实内容组合模板：在实际流程和页面级组合中验证组件。
  9. 规划实施架构：选择语义化标记、CSS策略、组件边界、构建/测试流水线、分发方式和迁移路径。
  10. 文档与治理：定义负责人、贡献、评审、发布、弃用和采用流程。
  11. 验证：在最终确定前运行质量、无障碍、响应式、性能和可维护性检查。
  12. 解释决策：将推荐方案与用户目标、系统一致性、无障碍、可维护性和实施成本关联说明。

Decision framework

决策框架

Use this sequence before recommending a pattern or architecture:
  1. Purpose: What problem or user task does this solve?
  2. Reuse: Will this recur across features, products, or states?
  3. Variation: What variants are truly needed, and what variants are accidental one-offs?
  4. Content: What content types, lengths, states, and localization cases must the pattern survive?
  5. Accessibility: What semantics, focus behavior, keyboard interaction, labels, contrast, target size, and motion rules are required?
  6. Implementation: Can it be implemented with semantic markup, low-specificity CSS, tokens, and minimal JS?
  7. System fit: Does it align with existing tokens, components, names, and documentation?
  8. Governance: Who owns it, how does it change, and how will users know which version to use?
Recommend the lowest-complexity solution that satisfies these constraints. Add complexity only when the product context justifies it.
在推荐模式或架构前，按以下顺序评估：
  1. 目标：这解决了什么问题或用户任务？
  2. 复用性：它是否会在多个功能、产品或状态中重复出现？
  3. 变体：哪些变体是真正必要的，哪些是偶然的一次性需求？
  4. 内容：该模式必须支持哪些内容类型、长度、状态和本地化场景？
  5. 无障碍：需要哪些语义、焦点行为、键盘交互、标签、对比度、目标尺寸和动效规则？
  6. 可实施性：是否可以通过语义化标记、低优先级CSS、tokens和最少JS实现？
  7. 系统适配性：是否与现有tokens、组件、命名和文档一致？
  8. 治理：谁负责维护它，如何变更，用户如何知道使用哪个版本？
推荐满足这些约束的最低复杂度方案。仅当产品上下文需要时才增加复杂度。

Practical rules

实用规则

Component rules

组件规则

  • A component must have a purpose, not just a visual shape.
  • Do not create a component from a screenshot alone. First identify user task, content model, states, and responsive behavior.
  • Prefer fewer components with well-defined variants over many near-duplicates.
  • A variant must represent a meaningful difference in purpose, prominence, state, or context.
  • Components should expose stable APIs or props that map to system decisions, not arbitrary styling escape hatches.
  • Every component needs examples with realistic content and at least one edge case.
  • 组件必须有明确用途，而非仅具备视觉形态。
  • 不要仅根据截图创建组件。首先确定用户任务、内容模型、状态和响应式行为。
  • 优先选择变体定义清晰的少量组件，而非大量近似重复的组件。
  • 变体必须代表用途、重要性、状态或上下文的有意义差异。
  • 组件应暴露与系统决策对应的稳定API或属性，而非任意样式逃逸通道。
  • 每个组件都需要包含真实内容示例和至少一个边缘场景示例。

Token rules

Token规则

  • Tokens should express decisions, not merely store values.
  • Use semantic tokens for meaning and primitive tokens for palette/scale management.
  • Do not let product teams consume raw primitives directly when a semantic decision is available.
  • Do not solve one-off needs by expanding the token set before checking whether the need is recurring.
  • Include state tokens for hover, active, focus, disabled, selected, success, warning, error, and loading where applicable.
  • Tokens应表达决策，而非仅存储值。
  • 使用语义token表示含义，使用原始token管理调色板/层级。
  • 当存在语义决策时，不要让产品团队直接使用原始token。
  • 在扩展token集前，先检查需求是否会重复出现，不要为一次性需求新增token。
  • 适当时包含悬停、激活、焦点、禁用、选中、成功、警告、错误和加载状态的tokens。

Documentation rules

文档规则

  • Document usage rules before implementation trivia.
  • Include “Use when” and “Do not use when” for every major pattern.
  • Include visual examples and anti-examples when they prevent misuse.
  • Keep documentation close enough to code or design source-of-truth that it does not drift.
  • Treat names and glossary entries as part of the product architecture.
  • 先文档化使用规则，再记录实施细节。
  • 为每个主要模式包含“适用场景”和“不适用场景”。
  • 包含视觉示例和反例以防止误用。
  • 保持文档与代码或设计可信源足够接近，避免内容漂移。
  • 将命名和术语表条目视为产品架构的一部分。

Governance rules

治理规则

  • Require a reason for new patterns: missing user need, repeated product need, accessibility requirement, or implementation simplification.
  • Require review before new visual styles, component variants, or tokens are added.
  • Allow experiments outside the core system, but define when an experiment graduates, changes, or dies.
  • Track deprecated components and provide migration guidance.
  • Measure system health by adoption, duplication reduction, accessibility quality, delivery speed, and user-facing consistency.
  • 新增模式需提供理由：未满足的用户需求、重复的产品需求、无障碍要求或实施简化需求。
  • 新增视觉样式、组件变体或tokens需经过评审。
  • 允许在核心系统外进行实验，但需定义实验何时转正、变更或终止。
  • 跟踪已弃用组件并提供迁移指南。
  • 通过采用率、重复度降低、无障碍质量、交付速度和用户端一致性衡量系统健康度。

Accessibility and inclusion requirements

无障碍与包容性要求

For each component or UI recommendation, specify:
  • Semantic element choice and accessible name.
  • Keyboard interaction and tab order.
  • Focus, hover, active, selected, disabled, invalid, loading, success, and error states.
  • Contrast and non-color state indicators.
  • Touch/motor target size and spacing between controls.
  • Screen reader behavior, live regions, and error announcements where relevant.
  • Reduced-motion alternative for decorative or transition-heavy behavior.
  • Text resizing and zoom resilience.
  • Localization and content expansion risk when relevant.
  • Inclusive defaults for reading order, language clarity, and non-punitive error copy.
Never recommend custom controls unless you also specify how the native semantics and interactions are preserved.
针对每个组件或UI推荐方案，需明确：
  • 语义元素选择和无障碍名称。
  • 键盘交互和Tab键顺序。
  • 焦点、悬停、激活、选中、禁用、无效、加载、成功和错误状态。
  • 对比度和非颜色状态指示器。
  • 触摸/运动无障碍的目标尺寸和控件间距。
  • 屏幕阅读器行为、实时区域和错误通知（如适用）。
  • 装饰性或过渡密集行为的低动效替代方案。
  • 文本缩放和缩放适应性。
  • 本地化和内容扩展风险（如适用）。
  • 阅读顺序、语言清晰度和非惩罚性错误文本的包容性默认设置。
除非同时明确说明如何保留原生语义和交互，否则绝不推荐自定义控件。

Frontend implementation guidance

前端实施指南

Semantic HTML

语义化HTML

  • Start from the native element that already carries the needed behavior: 
    button
    , 
    a
    , 
    input
    , 
    select
    , 
    textarea
    , 
    details
    , 
    dialog
    , list elements, headings, landmarks, and table elements where appropriate.
  • Use headings and landmarks to preserve meaningful page structure.
  • Use ARIA only when native semantics are insufficient, and keep ARIA state synchronized with actual UI state.
  • 从已具备所需行为的原生元素开始：
    button
    、
    a
    、
    input
    、
    select
    、
    textarea
    、
    details
    、
    dialog
    、列表元素、标题、地标和表格元素（如适用）。
  • 使用标题和地标保留有意义的页面结构。
  • 仅当原生语义不足时使用ARIA，并保持ARIA状态与实际UI状态同步。

Component structure

组件结构

  • Keep component responsibilities small and explicit.
  • Separate container/data orchestration from presentational primitives when it improves reuse and testing.
  • Use composition for complex organisms and templates; avoid giant monolithic components.
  • Define inputs/props in terms of role, state, and content, not raw CSS.
  • Include empty, loading, error, success, disabled, selected, and overflow cases in the component contract.
  • 保持组件职责小而明确。
  • 当有助于提高复用性和可测试性时，将容器/数据编排与展示型基础组件分离。
  • 使用组合方式构建复杂模块和模板；避免巨型单体组件。
  • 按角色、状态和内容定义输入/属性，而非原始CSS。
  • 在组件契约中包含空、加载、错误、成功、禁用、选中和溢出场景。

CSS and layout

CSS与布局

  • Use tokens for recurring values.
  • Keep specificity low; avoid deeply nested selectors and page-location dependencies.
  • Prefer layout primitives and component-contained responsive rules over scattered page-level overrides.
  • Use modern layout tools such as flex and grid when supported by the project constraints.
  • Use CSS for presentation, transitions, and state styling when CSS can handle the behavior accessibly and reliably.
  • Avoid 
    !important
    except for intentional utility layers or known override boundaries.
  • 使用tokens表示重复值。
  • 保持低优先级；避免深度嵌套选择器和页面位置依赖。
  • 优先使用布局基础元素和组件包含的响应式规则，而非分散的页面级覆盖。
  • 在项目约束允许的情况下，使用flex和grid等现代布局工具。
  • 当CSS可无障碍且可靠地处理行为时，使用CSS进行展示、过渡和状态样式设置。
  • 除非是有意的工具层或已知覆盖边界，否则避免使用
    !important
    。

Responsive behavior

响应式行为

  • Define how content reflows, truncates, wraps, stacks, or collapses.
  • Test components independently and inside representative templates.
  • Avoid assuming fixed dimensions unless the content and platform truly enforce them.
  • Treat narrow viewports, high zoom, and large text as first-class cases.
  • 定义内容如何回流、截断、换行、堆叠或折叠。
  • 独立测试组件并在代表性模板中测试。
  • 除非内容和平台确实强制要求，否则不要假设固定尺寸。
  • 将窄视口、高缩放比例和大文本作为首要场景处理。

Performance and maintainability

性能与可维护性

  • Avoid shipping duplicate component implementations.
  • Avoid large dependency additions for small presentational problems.
  • Use build tools to automate repeatable tasks, but do not choose tools for novelty alone.
  • Add visual regression tests to high-value components and templates where UI drift would be costly.
  • Include migration notes when changing a component API, token name, or markup structure.
  • 避免交付重复的组件实现。
  • 不要为小型展示问题添加大型依赖项。
  • 使用构建工具自动化重复任务，但不要仅因新颖性选择工具。
  • 对UI漂移会造成高成本的高价值组件和模板添加视觉回归测试。
  • 更改组件API、token名称或标记结构时，包含迁移说明。

Quality checklist

质量检查清单

Before finalizing work, verify:
  • The recommendation is scoped by components, states, and content, not only by pages.
  • The primary user task and success criteria are clear.
  • Functional and perceptual patterns are both addressed.
  • Tokens distinguish primitive values from semantic decisions.
  • Components have purpose, anatomy, variants, states, accessibility, responsive behavior, and implementation notes.
  • Layout is resilient to content changes and viewport/container changes.
  • Accessibility is treated as a requirement, not an afterthought.
  • The CSS strategy avoids specificity escalation and one-off overrides.
  • Documentation explains when and why to use patterns.
  • Governance explains how the system evolves without becoming bloated or stale.
  • Tradeoffs are explained in product, user, and implementation terms.
Use the full checklists in references/checklists.md.
最终确定工作前，验证以下内容：
  • 推荐方案按组件、状态和内容划分范围，而非仅按页面划分。
  • 主要用户任务和成功标准清晰明确。
  • 同时覆盖功能和感知模式。
  • Tokens区分原始值与语义决策。
  • 组件包含用途、结构、变体、状态、无障碍、响应式行为和实施说明。
  • 布局可适应内容变化和视口/容器变化。
  • 无障碍被视为需求，而非事后补充。
  • CSS策略避免优先级升级和一次性覆盖。
  • 文档说明了何时及为何使用模式。
  • 治理机制说明了系统如何演进而不变得臃肿或过时。
  • 从产品、用户和实施角度解释了权衡取舍。
查看references/checklists.md获取完整检查清单。

Common mistakes to avoid

需避免的常见错误

  • Estimating or planning by page count instead of component/functionality complexity.
  • Creating a “component library” that is only a gallery of screenshots or disconnected modules.
  • Naming components by appearance rather than purpose.
  • Creating tokens that merely mirror raw CSS values without semantic meaning.
  • Treating color, type, motion, spacing, and tone as superficial decoration rather than perceptual patterns.
  • Enforcing perfect consistency so strictly that product character and useful experimentation disappear.
  • Allowing unlimited variants and one-off overrides until the system becomes incoherent.
  • Building custom controls without preserving native behavior and accessibility.
  • Solving layout with brittle fixed dimensions and breakpoint-specific hacks.
  • Using JavaScript for styling effects CSS can solve more simply.
  • Letting documentation drift away from code and design source files.
  • Asking the user about routine best practices instead of applying strong defaults.
See references/anti-patterns.md for the full anti-pattern list.
  • 按页面数量而非组件/功能复杂度进行估算或规划。
  • 创建仅包含截图或 disconnected模块的“组件库”。
  • 按外观而非用途命名组件。
  • 创建仅镜像原始CSS值而无语义含义的tokens。
  • 将颜色、字体、动效、间距和色调视为表面装饰，而非感知模式。
  • 过度强制一致性，导致产品特质和有用的实验消失。
  • 允许无限变体和一次性覆盖，直到系统变得混乱。
  • 构建自定义控件却未保留原生行为和无障碍支持。
  • 使用脆弱的固定尺寸和断点特定技巧解决布局问题。
  • 使用JavaScript实现CSS可更简单解决的样式效果。
  • 让文档与代码和设计源文件脱节。
  • 询问用户常规最佳实践，而非应用明确的默认规则。
查看references/anti-patterns.md获取完整反模式列表。

How to explain recommendations to the user

如何向用户解释推荐方案

Explain choices in this order:
  1. User impact: how the recommendation improves task completion, clarity, accessibility, or confidence.
  2. System impact: how it improves consistency, reuse, governance, or naming.
  3. Frontend impact: how it reduces complexity, specificity, drift, regressions, or maintenance cost.
  4. Tradeoff: what is lost or constrained, and when a different choice would be better.
  5. Next action: what to implement, document, test, or ask next.
Use concrete language. Prefer “Use one 
Inline validation
component with success, warning, and error variants” over “make validation consistent.”
按以下顺序解释选择：
  1. 用户影响：推荐方案如何提高任务完成率、清晰度、无障碍性或用户信心。
  2. 系统影响：如何提高一致性、复用性、治理或命名规范。
  3. 前端影响：如何降低复杂度、优先级问题、漂移、回归或维护成本。
  4. 权衡取舍：失去或受限制的内容，以及何时选择其他方案更好。
  5. 下一步行动：需要实施、文档化、测试或进一步询问的内容。
使用具体语言。优先使用“使用带成功、警告和错误变体的
Inline validation
组件”而非“使验证一致”。