Frontend Design Guide

Purpose

Use this skill before frontend implementation. Generate or adapt a project-level DESIGN.md and a concise UX artifact so later frontend code must follow explicit design rules instead of generic AI defaults.

Operating Rules

• Do not copy brand-specific identity, logos, slogans, or distinctive visual assets from external references.
• Use external design references only as inspiration for layout, density, hierarchy, component behavior, and interaction principles.
• Prefer a business-fit design style over a fashionable style.
• For operational systems, prioritize clarity, scan speed, predictable navigation, form efficiency, table usability, and error recovery.
• Frontend code generation must read DESIGN.md before creating pages or components.
• If an existing DESIGN.md exists, adapt it to the current project instead of replacing it blindly.
• Native choice widgets are client-dependent. If no choice widget is available, show the built-in templates as a numbered list and ask the user to reply with the number or template name.

Style Selection Workflow

1. Identify product type: admin system, data dashboard, government/professional system, SaaS product, mobile/H5, public portal, or custom.
2. Identify users: high-frequency operators, managers, analysts, external visitors, mobile users, or mixed roles.
3. Identify workflow density: dense operations, dashboard scanning, step-by-step process, content reading, or marketing conversion.
4. Ask whether brand assets, color constraints, component library, or existing DESIGN.md exists.
5. Choose one built-in template or adapt the user's external reference.
6. Generate DESIGN.md and docs/03-frontend-design/frontend-ux-design.md.
7. Record design constraints in .project-guide/state.yaml when project state is used.

Built-in Templates

Use these neutral templates as defaults:

1. enterprise-admin: internal admin systems, CRM, WMS, ticketing, workflow systems.
2. data-dashboard: BI, monitoring, command center, operational metrics.
3. gov-professional: government, public security, compliance, regulated professional systems.
4. modern-saas: team tools, productivity SaaS, collaboration products.
5. mobile-h5: mobile web, WeChat/H5 flows, lightweight client-side workflows.

Read the matching file under references/templates/ before generating DESIGN.md.

When asking the user to choose, use this fallback format:

Choose a frontend design template:
1. enterprise-admin - internal admin, CRM, WMS, workflow, ticketing
2. data-dashboard - BI, monitoring, metrics, command center
3. gov-professional - government, public security, compliance, audit-heavy systems
4. modern-saas - SaaS, collaboration, productivity tools
5. mobile-h5 - mobile web, WeChat/H5, lightweight client workflows

Reply with a number or template name.

External Reference Policy

When the user provides an external DESIGN.md or mentions awesome-design-md:

• Read the user-provided design file if available.
• Extract transferable principles: spacing, density, typography, component behavior, interaction tone.
• Remove brand names, brand colors, proprietary imagery, and unique copywriting.
• Adapt the style to the project's business type and component library.
• Keep a short "Reference Adaptation Notes" section in docs/03-frontend-design/frontend-ux-design.md.

Output Requirements

Generate:

• DESIGN.md: project-level rules that frontend generation must follow.
• docs/03-frontend-design/frontend-ux-design.md: short explanation of selected style, target users, page patterns, and tradeoffs.

After producing DESIGN.md, stop and request explicit user review. Do not proceed to frontend UX notes or implementation until the user approves the design guidelines.

After producing docs/03-frontend-design/frontend-ux-design.md, stop and request explicit user review. Do not proceed to frontend implementation until the user approves the UX artifact.

DESIGN.md should include:

• Product type and design intent.
• Visual tone.
• Color system.
• Typography.
• Layout and spacing.
• Navigation.
• Components.
• Tables/forms/modals.
• State design: loading, empty, error, success, disabled.
• Responsive behavior.
• Accessibility.
• Prohibited patterns.
• Frontend implementation notes.

Anti-Generic Rules

Avoid:

• Decorative gradient backgrounds for operational tools.
• Oversized hero sections in admin/productivity systems.
• Card-inside-card layouts.
• Random bokeh/orb decorations.
• Excessive rounded corners.
• Fake charts with no data semantics.
• Low-density dashboards where users need scanning efficiency.
• Placeholder-heavy pages that look polished but do not support real workflows.