20 added, 89 removed. Audit A to A.
---
name: ui-blueprint
- description: Use when building or substantially redesigning frontend UI where visual quality matters, including websites, landing pages, web apps, dashboards, prototypes, and game UI. This skill requires Codex to generate a UI mockup image with image-creator first, inspect that image, and then implement the frontend against the generated visual blueprint instead of jumping directly into code.
+ description: Generate a visual blueprint before building new frontend UI or substantially redesigning a screen. Exclude small copy or styling changes, narrow bug fixes, and work that should preserve the existing design.
---
# UI Blueprint
- Build frontend UI from a generated visual blueprint, not from an unvisualized text-only plan.
-
- ## Happy Path
-
- User request:
-
- ```text
- Use $ui-blueprint to redesign the settings dashboard.
- ```
-
- Skill behavior:
-
- 1. Read the existing frontend structure, routes, components, and styling conventions.
- 2. Ask `$image-creator` for a project-specific UI mockup and save it under `ui-blueprints/`.
- 3. Inspect the saved mockup and extract concrete layout, hierarchy, color, spacing, state, and responsive notes.
- 4. Implement the UI in the existing stack, verify it in a browser or equivalent renderer, and report the blueprint path.
-
- ## Hard Rules
-
- - Use `gpt-5.4` as the reasoning model for this workflow whenever model selection is available.
- - Before writing UI code, generate a UI mockup image through the `$image-creator` workflow.
- - Save or copy the selected generated blueprint image under the project-root `ui-blueprints/` directory before implementation. Do not leave it only in the default image generation output location.
- - Inspect the generated image and extract concrete implementation notes before coding.
- - Do not silently skip the image step for new UI, major redesigns, visually led pages, app surfaces, prototypes, or game UI.
- - Do not implement from a generic placeholder mockup. The image prompt must reflect the user's actual product, audience, content, and constraints.
- - If image generation fails or is unavailable, stop and report the blocker. Continue without a generated blueprint only if the user explicitly accepts that fallback.
-
- ## When To Use
-
- Use this skill for:
-
- - new websites, landing pages, marketing pages, product pages, and portfolios
- - new app screens, dashboards, admin tools, inspectors, editors, and data surfaces
- - visual redesigns or "make it look better" requests
- - prototypes, demos, games, and interactive tools where the first screen must feel designed
- - UI work where layout, hierarchy, imagery, color, typography, or motion matters
-
- Do not use this skill for:
-
- - small text, copy, spacing, or color tweaks on an existing UI
- - narrow bug fixes where the intended UI is already clear
- - backend, API, data, CI, deployment, or test-only tasks
- - pure accessibility or performance fixes that should preserve the current visual design
+ Use the session's selected reasoning model. Build from a generated, saved, and inspected UI mockup.
## Workflow
- 1. Read the existing frontend structure, design system, routes, and styling conventions.
- 2. Distill the UI brief into a blueprint prompt:
- - product or surface type
- - target user and primary task
- - viewport or screen type
- - information hierarchy
- - required content and controls
- - visual tone, density, and constraints from the repo
- 3. Use `$image-creator` to generate one strong UI mockup image before implementation. Pass the distilled blueprint brief as the image request, let `$image-creator` convert it into a model-friendly prompt, and specify the project-root `ui-blueprints/` directory as the save destination.
- 4. Confirm the selected image was persisted under the project-root `ui-blueprints/` directory:
- - create `ui-blueprints/` if it does not exist
- - use a descriptive, non-overwriting filename
- - keep the blueprint image even if the final UI does not directly reference it
- 5. Inspect the saved mockup and write a short visual extraction:
- - layout grid and major regions
- - typography scale and hierarchy
- - color palette and contrast strategy
- - component states, controls, imagery, and iconography
- - spacing, density, and responsive behavior implied by the image
- 6. Implement the UI in the existing stack, using existing components and local patterns first.
- 7. Verify in the browser or an equivalent renderer. Compare the result against the blueprint for composition, hierarchy, spacing, color, and responsiveness.
- 8. If the implemented screen drifts from the blueprint, revise the UI rather than rationalizing the drift.
-
- ## Blueprint Prompt Rules
-
- - Ask for a complete screen, not a decorative fragment.
- - Make the prompt specific to the user's domain; avoid generic SaaS, generic dashboard, and generic portfolio language.
- - Include real UI elements that the final implementation must contain.
- - Request polished product-quality UI with clear hierarchy and usable controls.
- - Avoid asking the image model to render long paragraphs of exact text. Use realistic text blocks and reserve exact copy for implementation.
- - Avoid mockups that depend on impossible assets, overly dense effects, or decorative elements that would not survive real implementation.
+ 1. Read the existing frontend structure, design system, routes, and components relevant to the requested screen.
+ 2. Distill the product, audience, primary task, viewport, required content and controls, and visual constraints into a blueprint brief.
+ 3. Use `$image-creator` to generate one product-specific mockup. Give it the brief and the project-root `ui-blueprints/` directory as the destination.
+ 4. Inspect the saved image before writing UI code. Extract actionable notes on layout, hierarchy, typography, color, spacing, controls, and responsive behavior.
+ 5. Implement the screen in the existing stack using local components and patterns.
+ 6. Verify the implementation in a browser or equivalent renderer on desktop and mobile. Compare composition and hierarchy against the blueprint and repair meaningful drift.
- ## Implementation Rules
+ Keep the blueprint under `ui-blueprints/` with a descriptive, non-overwriting filename even if the app does not use it as an asset. If image generation fails or is unavailable, report the blocker; proceed without a blueprint only when the user has accepted that fallback.
- - The generated image is the visual source of truth, but the repo remains the engineering source of truth.
- - Preserve existing routing, state management, data contracts, component APIs, and design tokens unless the task explicitly requires changing them.
- - Use visual assets when the screen needs imagery. Do not replace the blueprint's visual anchor with gradients or empty placeholders.
- - Build responsive behavior deliberately; do not assume the desktop composition will collapse cleanly on mobile.
- - Keep UI text user-facing. Do not include prompt notes, implementation commentary, or design rationale in the product surface.
- - Validate that text fits, controls remain usable, and key content is visible on common desktop and mobile viewports.
+ ## Blueprint and Implementation
- ## Response
+ - Request a complete screen using the user's actual product and content. A generic placeholder mockup does not satisfy the workflow.
+ - Use short representative text in the image; implement exact copy from the user's requirements. Do not depend on long, precisely rendered image text.
+ - Choose visual elements that can be implemented with available assets and technology.
+ - Preserve existing routing, state management, component APIs, data contracts, and design tokens unless the task requires changing them.
+ - Use the image for visual direction and the repository for engineering constraints. Preserve required controls and behavior even where the static image is incomplete.
+ - Implement responsive behavior and component states deliberately; a desktop mockup does not specify them fully.
+ - Supply actual visual assets where the composition needs imagery. Keep implementation notes and prompt commentary out of product UI.
+ - Check text fit, usable controls, and visibility of key content as part of the visual verification.
- When finished, report:
+ ## Handoff
- - where the implementation changed
- - the project-local path of the saved blueprint image
- - that a generated UI blueprint was used
- - what verification was run
- - any meaningful deviations from the blueprint and why they were necessary
+ Report the implementation changes, saved blueprint link, verification performed, and any meaningful deviation with its reason.