ui-ux-design-system

name	ui-ux-design-system
description	UI/UX 设计系统与开放式设计探索 Skill。用于视觉方向、设计系统、交互规则、色板、字体、无障碍、设计评审、原型方向、HTML review 优先的设计交付建议；也用于读取 Sketch 源文件 / SketchMCP / 蓝湖标注并整理可追溯 Design-to-Code source packet，iOS 高保真链路随后交给 design-context-compiler 生成 Canonical UI IR / Agent Packet；若需要正式 HTML 文档交给 html-docs。不要用于 SwiftUI/UIKit API 级实现、设计上下文编译、构建配置或性能取证。

UI/UX Design System

Purpose

Guide UI/UX direction, design systems, design exploration, accessibility, prototype planning, and design-review decisions before implementation or artifact generation.

中文说明

该 Skill 是 UI/UX 设计系统与开放式设计探索专项 Skill。

负责：

• 视觉方向。
• 设计系统。
• 色板、字体、间距、圆角、阴影、图标规则。
• 交互规则。
• 无障碍和可读性建议。
• 原型方向选择。
• Sketch 源文件 / SketchMCP / 蓝湖标注到可追溯 Design Evidence / Design-to-Code source packet 的拆解。
• HTML review / 设计文档优先的交付建议。
• 设计评审与风险提示。

不负责：

• SwiftUI / UIKit API 级代码实现。
• Liquid Glass API 级实现；交给 ios-feature-implementation 的 liquid-glass 模式。
• 构建配置、签名、Archive、CI。
• 性能 profiling / benchmark。
• 外部 Open Design 工具安装和运行维护。

When to Use

Use this Skill when the user asks for:

• Visual direction.
• Design system.
• Color palette.
• Typography.
• Spacing and layout rhythm.
• Interaction rules.
• Accessibility guidance.
• Design critique or review.
• Prototype planning before implementation.
• Product UI direction for iOS, web, dashboard, landing page, or docs.
• Sketch source file, SketchMCP, Lanhu/Figma inspect, or exported design asset analysis before coding.
• Design Evidence / Design-to-Code source packet generation for high-fidelity compilation handoff.
• HTML review first, then optional PDF/PPTX/export discussion.

When Not to Use

Do not use this Skill when:

• The user needs SwiftUI page code, NavigationStack, state ownership, or modifiers; use ios-feature-implementation with swiftui mode.
• The user needs UIKit ViewController/View/layout implementation; use ios-feature-implementation with uikit mode.
• The task is Liquid Glass API implementation; use ios-feature-implementation with liquid-glass mode.
• The task is build/signing/archive/CI; use xcode-build.
• The task is device automation or screenshot capture; use ios-automation.
• The task is runtime debugging or performance profiling.
• The user only asks for App Store release notes; use app-store-changelog.

Agent Rules

Design Mode Rules

Choose the smallest design mode that fits the request:

Mode	Use When
design-exploration	Visual direction, product style, mood, design references, or broad concept.
design-system	Tokens, components, typography, colors, spacing, accessibility, consistency.
design-review	Existing UI or mock needs critique and improvement suggestions.
prototype-planning	User wants a prototype direction before SwiftUI/UIKit implementation.
sketch-to-code-spec	User provides Sketch source, SketchMCP, Lanhu/Figma inspect, PNG, or design assets and wants high-fidelity implementation guidance.
artifact-guidance	User wants HTML review, design doc, PDF/PPTX/export direction.

Discovery Rules

Before giving a full design direction, capture the smallest useful packet:

• Product type.
• Target users.
• Platform: iOS / iPadOS / macOS / web / mixed.
• Visual keywords: minimal, bold, playful, enterprise, dark, Apple-like, editorial, data-heavy.
• Primary screens or flows.
• Brand constraints.
• Accessibility constraints.
• Design source: Sketch file path, SketchMCP endpoint, inspect link, PNG screenshots, asset zip, or selected frame / artboard name.
• Output format: discussion, HTML review, PRD, prototype plan, or implementation handoff.

If the user already provided enough context, do not ask again.

Design System Rules

• Prefer one coherent design system per artifact.
• Avoid mixing multiple unrelated visual languages.
• Define tokens before component details when designing from scratch.
• For iOS, respect HIG-style clarity, depth, hierarchy, and platform conventions.
• For data-heavy apps, define chart, table, empty state, and error state rules.
• For subscription/paywall screens, keep comparison clarity and restore-purchase affordance visible.
• For accessibility, consider contrast, Dynamic Type, hit targets, VoiceOver labels, and motion sensitivity.

Prototype / Artifact Rules

• Prefer HTML review before final export when design direction is still uncertain.
• Use a prototype plan before generating many screens.
• Keep prototype scope small for first iteration.
• Do not over-specify implementation APIs unless handing off to SwiftUI/UIKit Skills.
• If the output becomes a formal HTML design spec, PRD, review document, or shareable / archived HTML artifact, hand off source decisions and evidence to html-docs; do not craft the final HTML in this Skill.

Sketch / Design Source Rules

• When the input is a Sketch file, SketchMCP endpoint, Lanhu/Figma inspect link, or exported PNG, select sketch-to-code-spec mode before implementation.
• First produce a traceable Design-to-Code source packet; for iOS, route it through design-context-compiler before SwiftUI/UIKit implementation.
• Read references/sketch-to-code-spec.md before using SketchMCP or converting a design source into implementation guidance.
• Prefer source-of-truth data over visual guessing: document info, artboard size, layer tree, text styles, layer styles, swatches, symbols, exported assets, and screenshots.
• If using SketchMCP, call its get_guide(topic: "mcp") first, then inspect the document with get_document_info, target frame with get_layer_tree_summary, and visual state with get_screenshot.
• Require the user to identify the target frame / artboard when multiple frames match; do not pick by name guess if ambiguous.
• Record unknown design facts explicitly in unknowns instead of inventing measurements, colors, fonts, or states.
• The implementation handoff must include tokens, component tree, state matrix, asset list, responsive rules, accessibility notes, and visual acceptance criteria.
• If the next step is code, hand off to ios-feature-implementation(swiftui|uikit|mixed-ui) or an appropriate web implementation flow with the Spec as source of truth.

Token Budget

• Do not include huge visual inventories.
• Use concise tables for tokens and component states.
• Prefer design decisions and rationale over long generic design theory.
• For review, list the top blocking UI/UX issues first.

Inputs

Expected input contract:

{
  "goal": "Design direction | design system | design review | prototype planning",
  "product_type": "optional",
  "platform": "iOS | iPadOS | macOS | web | mixed | unknown",
  "design_source": "Sketch file | SketchMCP endpoint | Lanhu/Figma link | PNG | asset zip | none",
  "target_frame": "optional artboard/frame name or id",
  "target_users": [],
  "visual_keywords": [],
  "screens_or_flows": [],
  "brand_constraints": [],
  "accessibility_requirements": [],
  "output_format": "discussion | html-review | prototype-plan | implementation-handoff | document"
}

Outputs

Return compact structured output:

{
  "status": "completed | partial | blocked",
  "mode": "design-exploration | design-system | design-review | prototype-planning | sketch-to-code-spec | artifact-guidance",
  "design_direction": [],
  "design_source_evidence": [],
  "design_to_code_spec": {},
  "tokens": {
    "color": [],
    "typography": [],
    "spacing": [],
    "radius": [],
    "elevation": []
  },
  "component_guidelines": [],
  "interaction_guidelines": [],
  "accessibility_notes": [],
  "visual_acceptance": [],
  "unknowns": [],
  "prototype_scope": [],
  "implementation_handoff": "design-context-compiler | ios-feature-implementation(swiftui|uikit|mixed-ui) | html-docs | none",
  "known_risks": [],
  "next_action": "prototype | implement | document | review | blocked"
}

Exit Conditions

Return completed when:

• Design mode is selected.
• Visual direction or design-system guidance is clear.
• For sketch-to-code-spec, target frame, extracted design facts, unknowns, and implementation handoff are explicit.
• Accessibility and implementation handoff are addressed when relevant.
• Next action is clear.

Return partial when:

• A useful direction is provided but brand, audience, assets, or screen list is incomplete.

Return blocked when:

• Required product, platform, audience, or output constraints are missing and cannot be reasonably inferred.

Escalation Rules

Escalate to ios-feature-implementation with swiftui mode when:

• Design direction is ready and SwiftUI implementation is next.

Escalate to ios-feature-implementation with uikit mode when:

• Design direction is ready and UIKit implementation is next.

Escalate to ios-feature-implementation with liquid-glass mode when:

• The task specifically needs Liquid Glass design and implementation details.

Escalate to html-docs when:

• The output should become a formal HTML design spec, PRD, or review document.
• The user asks to generate, save, publish, or archive the design output as HTML.

Escalate to design-context-compiler after sketch-to-code-spec when:

• The Design-to-Code source packet has a traceable file/page/frame/node and design evidence.
• UIKit / SwiftUI implementation needs Canonical UI IR, component bindings or a task-scoped Agent Packet.

Escalate to ios-feature-implementation only after design-context-compiler returns a validated Agent Packet, or when the task does not originate from an external design source.

Escalate to ios-automation when:

• The task needs screenshot capture, accessibility tree evidence, or device/simulator UI smoke.

Escalate to ios-performance when:

• The issue is rendering, scrolling, animation performance, or Instruments-based evidence.

Reporting Format

UI/UX status: completed | partial | blocked
Mode: design-exploration | design-system | design-review | prototype-planning | sketch-to-code-spec | artifact-guidance
Design direction:
- ...
Design source evidence:
- ...
Tokens:
- color: ...
- typography: ...
- spacing: ...
Component guidelines:
- ...
Interaction guidelines:
- ...
Accessibility notes:
- ...
Visual acceptance:
- ...
Unknowns:
- ...
Implementation handoff: ios-feature-implementation(swiftui|uikit|mixed-ui) | html-docs | none
Next action: prototype | implement | document | review | blocked

Reference Resources

• scripts/search.py
• scripts/design_system.py
• data/products.csv
• data/styles.csv
• data/colors.csv
• data/typography.csv
• data/charts.csv
• data/ux-guidelines.csv
• data/ui-reasoning.csv
• references/sketch-to-code-spec.md: Sketch / SketchMCP / inspect-link to Design Evidence / source packet extraction workflow, required data fields, output contract, and visual acceptance loop.

Relationship to Other Skills

• Visual direction, design exploration, design review, tokens, typography, color, accessibility: use this Skill.
• Sketch source file / SketchMCP / Lanhu/Figma inspect extraction and Design-to-Code source packet generation: use this Skill, then hand off to design-context-compiler for iOS.
• Canonical UI IR, iOS component bindings, context budget and Agent Packet: design-context-compiler.
• SwiftUI implementation: ios-feature-implementation with swiftui mode.
• UIKit implementation: ios-feature-implementation with uikit mode.
• Liquid Glass API implementation: ios-feature-implementation with liquid-glass mode.
• Formal HTML design docs: html-docs.
• This Skill owns design direction and tokens; html-docs owns final HTML document structure, templates, and dark-mode adaptation.
• Screenshots / device UI evidence: ios-automation.
• Rendering and animation performance: ios-performance.