dev-design-context

Dev Design Context

Gather design context for this project, then persist it so future UI work starts with the same visual and product direction.

This skill is for one-time setup or major design-direction resets. It does not write application code, generate mockups, or review implementation diffs.

---

Trigger routing

Use this skill when the user wants Codex / Claude Code to learn a project's design direction before building UI.

Trigger phrases include:

• dev-design-context
• setup design context
• 设计上下文
• 设计规范
• 先建立设计方向
• gather design context
• persistent design guidelines

Output goes to .design-context.md in the project root.

Step 0 — Load baseline

执行前先加载 references/dev-baseline.md。以下行为准则在本 skill 全程生效:不假设、最小代码、外科手术式改动、可验证成功标准。

baseline 与本 skill 的关联点:

• 不假设 —— 先扫描真实代码和资产,再问问题;不要让用户重复回答代码里已经能看到的信息。
• 最小代码 —— 只写 .design-context.md 的设计上下文,不要顺手改组件、CSS 或产品文案。
• 外科手术式改动 —— 如果 .design-context.md 已存在,只更新 ## Design Context 相关内容。
• 可验证成功标准 —— 结束前明确写出设计原则已经落在哪个文件,并总结未来设计工作应遵守的 3-5 条原则。

Step 1 — Explore the codebase

Before asking questions, scan the project to discover what can be inferred:

• README and docs: project purpose, target audience, and stated goals
• Package / config files: tech stack, dependencies, and design libraries
• Existing components: layout patterns, spacing, typography, component conventions
• Brand assets: logos, favicons, image assets, and already-defined color values
• Design tokens / CSS variables: color palettes, font stacks, spacing scales, radii, motion values
• Style guides or brand docs: any explicit product, content, or visual direction

Summarize what you learned and what remains unclear before asking the user anything.

Step 2 — Ask UX-focused questions

Ask the user directly to clarify only what cannot be inferred from the codebase. Keep questions focused and avoid long questionnaires.

Users and purpose

• Who uses this? What is their context when using it?
• What job are they trying to get done?
• What emotions should the interface evoke, such as confidence, calm, delight, urgency, or precision?

Brand and personality

• How would you describe the brand personality in 3 words?
• Are there reference sites or apps that capture the right feel? What specifically works about them?
• What should this explicitly not look like? Are there anti-references?

Aesthetic preferences

• Are there strong preferences for visual direction, such as minimal, bold, editorial, technical, playful, or organic?
• Should it support light mode, dark mode, or both?
• Are there colors that must be used or avoided?

Accessibility and inclusion

• Are there specific accessibility requirements, such as a WCAG level or known user needs?
• Are there constraints around reduced motion, color blindness, contrast, or other accommodations?

Skip questions where the answer is already clear from the codebase exploration.

Step 3 — Write design context

Synthesize the codebase findings and the user's answers into this section:

## Design Context

### Users
[Who they are, their context, and the job to be done]

### Brand Personality
[Voice, tone, 3-word personality, and emotional goals]

### Aesthetic Direction
[Visual tone, references, anti-references, theme, color, and motion direction]

### Design Principles
[3-5 principles derived from the codebase and conversation that should guide all design decisions]

Write this section to .design-context.md in the project root. If the file already exists, update the ## Design Context section in place instead of duplicating it.

Then ask the user whether they also want the same Design Context appended to .github/copilot-instructions.md. If yes, append or update that section there as well.

Confirm completion and summarize the key design principles that will guide future UI work.

---

Multi-Agent Profile

Recommended agent_type: explorer

Use when:

• The main agent needs design-system or UI convention discovery before UI work.
• The project has existing components, styles, assets, or brand cues to inspect.
• The sub-agent can summarize findings without implementing UI changes.

Do:

• Explore README, assets, styles, components, tokens, and existing screens.
• Separate codebase facts from assumptions.
• Ask only UX questions that cannot be inferred.
• Follow the explorer boundaries in ../../docs/multi-agent-policy.md.

Do not:

• Implement UI.
• Rewrite product copy or CSS outside .design-context.md.
• Invent brand direction when the project already provides evidence.

Output:

• Codebase design facts
• Unknowns that require user input
• Proposed design principles
• Files inspected