When AI Generates Frontend Pages Like a Blind Box, I Built a Project Design Language Skill

Problem

AI‑generated front‑end pages in legacy projects become visually inconsistent: primary colors shift, button, spacing, and footer styles differ, and prototype colors are copied directly into production. Prototypes define layout, but there is no stable visual contract.

Design Intent

1. Project‑level “skin specification”

Store a fixed file docs/design.md in the repository that answers questions such as primary color, spacing, button, footer, modal styles, and legacy patterns to avoid.

2. Prototypes supply layout only

During development, interaction HTML and screenshots guide structure, while color, font size, corner radius, and component appearance must follow docs/design.md, not the prototype’s demo skin.

3. Borrow Bootstrap’s role‑based classification

Adopt Bootstrap’s method of categorizing colors (primary, neutral, exceptions) but do not impose Bootstrap’s default blue unless the scan confirms its use.

Pitfalls and Solutions

Pitfall 1: Scan returns many colors without guidance. Solution: Record an evidence ledger (source, frequency, confidence) and select the primary color by hierarchy: brand variable > component‑library theme > high‑frequency raw colors.

Pitfall 2: Scanning mixes multiple products. Solution: Restrict scanning to a single product directory; shared style packages participate only when actually referenced.

Pitfall 3: Refresh deletes old rules silently. Solution: Perform a diff before updating; keep unseen old rules as pending review.

Pitfall 4: Vague directives (“keep it simple”) are misinterpreted. Solution: Write specifications with explicit objects, rules, and scopes.

Pitfall 5: Applying design.md flattened a reusable bottom‑menu component. Solution: Require that listed reusable components be used unchanged; host pages cannot arbitrarily modify their box model or size.

Pitfall 6: Too many optional capabilities complicated the main flow. Solution: Export machine‑readable functions as optional; default path remains scan → converge → write docs/design.md.

Core Capabilities

Extract : Scan the codebase and generate or complete docs/design.md.

Reuse : If a design.md already exists, reuse it without rescanning.

Refresh : Rescan when the theme changes, preserving previous decisions.

Apply : When building a new page from a prototype, skin follows design.md only.

Audit : Check whether a page deviates from project standards.

Optional export : Export machine‑readable .jsonl files when needed.

Optional verification : Sample running pages to confirm style enforcement.

Integration Flow

When integrated into an AI‑assisted front‑end workflow, the skill can automatically trigger extraction or reuse and block page generation if no design.md is present, without slowing requirement documentation.

Target Audience

Legacy projects with many pages and scattered styles where developers need a stable visual contract.

AI‑assisted development teams that receive fast prototypes/HTML but want consistent skins across requests.

Parallel demand scenarios where layout is handled by prototypes and skin by a shared design.md.

Conclusion

The skill does not replace a design system or UI designers; it provides a searchable, refreshable, and auditable design specification that keeps AI‑generated pages aligned with project expectations, reducing manual adjustments and developer fatigue.