agents/openai.yaml
interface:
display_name: "Creative Frontend Design"
short_description: "Prototype distinctive frontend directions"
default_prompt: "Use $creative-frontend-design to create three distinct isolated prototypes for this substantial frontend design, compare them, and wait for my selection before integration."
examples/creative-agency.md
# Creative agency direction brief
**Scenario:** A motion and identity studio focused on cultural institutions.
- Visual concept: A living production contact sheet with curatorial annotations.
- Typography: Warm grotesk in extreme scale contrast, with a monospaced caption layer.
- Composition: Project media changes size and cadence; annotations align across otherwise broken grids.
- Palette: Paper white, dense black, a rotating project-derived accent.
- Imagery: Work first—frames, process fragments, installed outcomes—with accurate credits.
- Motion: Hover scrubbing where useful, hard editorial cuts, restrained page transitions.
- Responsive transformation: Replace hover previews with inline project stills and preserve the project index as the navigation spine.
Let differences in the work shape each entry. Avoid a symmetrical portfolio card grid and inflated agency claims.
examples/gaming.md
# Gaming direction brief
**Scenario:** A competitive fantasy game about rival celestial houses.
- Visual concept: Astronomical tournament broadcast from a decaying observatory.
- Typography: Monumental chiseled display paired with compact broadcast utility type.
- Composition: One house dominates each chapter; orbital diagrams connect roster, abilities, and match structure.
- Palette: Carbon sky, bone, eclipse red, house-specific signal colors.
- Imagery: Isolated character silhouettes, engraved star maps, controlled volumetric depth.
- Motion: Orbital transitions and decisive masked character reveals; short responsive controls.
- Responsive transformation: Convert wide orbital relationships into a vertical constellation path with swipe-free roster controls.
Invent all heraldry and terminology. Avoid copying established faction screens, game UI chrome, or character compositions.
examples/luxury-minimal.md
# Luxury minimal direction brief
**Scenario:** A small-batch fragrance house launching a mineral collection.
- Visual concept: Geological still life presented with gallery restraint.
- Typography: High-contrast serif display with a narrow, precise sans for formulae and commerce.
- Composition: Wide quiet fields interrupted by extreme macro crops and fine offset captions.
- Palette: Chalk, graphite, oxidized green, and one warm metal accent.
- Imagery: Side-lit glass, stone, vapor, and tactile packaging details.
- Motion: Slow mask openings for campaign media; immediate, crisp product controls.
- Responsive transformation: Replace horizontal image tension with alternating full-bleed and inset mobile crops; retain generous pauses without hiding purchase information.
Reject generic luxury signals such as gratuitous gold gradients, scripted logos, and slow interactions everywhere. Specific materials and disciplined spacing carry the value.
examples/sports-editorial.md
# Sports editorial direction brief
**Scenario:** A city night-running league opening registrations.
- Visual concept: Race-day newspaper colliding with nocturnal street telemetry.
- Typography: Condensed uppercase display, pragmatic grotesk, tabular numerals.
- Composition: Cropped runners cross grid lines; results and dates anchor sharp side columns.
- Palette: Newsprint gray, asphalt black, sodium orange, reflective silver.
- Imagery: Flash photography, motion blur, wet pavement, close physical effort.
- Motion: Quick lateral wipes and count changes, balanced by still full-bleed portraits.
- Responsive transformation: Turn side data into compact route markers; preserve one dominant runner crop and short registration path.
The identity comes from event-specific evidence and pace, not generic neon fitness cards.
references/accessible-performance.md
# Accessible performance
Treat accessibility and speed as art-direction inputs. Preserve the intended hierarchy and atmosphere under keyboard input, reduced motion, zoom, slow networks, and small devices.
## Structure before styling
- Keep DOM order aligned with reading and focus order even when the layout is visually broken or overlapping.
- Use native landmarks, headings, links, buttons, labels, and disclosure controls before recreating behavior with generic elements.
- Give every interaction a visible keyboard focus state that belongs to the visual language.
- Keep tap targets operable without relying on hover or cursor-following behavior.
- Make image and video alternatives match purpose: informative alt text, empty alt for decoration, captions/transcripts where content requires them.
- Verify zoom, text resizing, long translations, and forced/high-contrast modes when the target platform supports them.
## Budget the spectacle
Identify the likely largest-content element, critical fonts, hero media, and above-fold JavaScript before implementation. Prioritize only what the first composition needs. Defer below-fold media and nonessential animation code.
- Reserve media dimensions to prevent layout shift.
- Use responsive image sources sized to the rendered slot.
- Subset and self-host fonts when licensing permits; limit families, weights, and blocking requests.
- Prefer CSS and platform behavior for simple interactions.
- Lazy-load 3D, video, and heavy motion modules behind capability and visibility checks.
- Do not ship desktop-scale media to narrow screens when an art-directed source is available.
## Design failure states
The page must retain content, hierarchy, and actions when custom fonts are late, images fail, JavaScript is unavailable, animation is reduced, or a low-power device drops effects. Progressive enhancement is part of the visual system.
Measure the built page rather than declaring it fast from implementation choices. Inspect loading, layout stability, responsiveness, and animation smoothness on representative mobile hardware and a throttled connection. Remove or simplify the least valuable effect first.
references/anti-ai-slop.md
# Remove the default-agent look
Generic output is usually not a lack of decoration. It is a lack of consequences: any font, crop, section order, or color could be swapped without changing the idea.
## Require an identity signature
Before styling, name three signatures that the page will own:
1. **Type signature:** a repeatable relationship between display and utility text.
2. **Composition signature:** a recognizable alignment, crop, overlap, or density behavior.
3. **Interaction signature:** one response or transition derived from the concept.
Tie each signature to the product's content or behavior. "Large serif," "asymmetric," and "smooth" are attributes, not signatures. "Headlines behave like auction-lot labels while object photography breaks their rule lines" is a signature because it predicts concrete decisions.
## Detect it
Flag the page when it relies on several of these shortcuts without a content-specific reason:
- centered headline, explanatory subtitle, and two equal CTAs;
- three interchangeable feature cards repeated section after section;
- rounded containers, pills, glass, shadows, and glows used as universal grammar;
- purple/blue gradient blobs, generic Web3 darkness, or gradient text standing in for identity;
- default Tailwind spacing, default shadcn composition, or Inter selected without a typographic reason;
- every section inside the same centered `max-w-*` wrapper;
- icon/title/paragraph grids with no content-specific hierarchy;
- stock photos dropped into predictable left-copy/right-image bands;
- every element entering through opacity plus `translateY`;
- decoration and animation without a concept or narrative job;
- placeholder claims, invented metrics, or synthetic testimonials used to fill a familiar landing-page skeleton;
- icons chosen before the information form is understood;
- visual novelty concentrated in the hero while the rest returns to stock sections.
These are diagnostic signals, not blanket bans. A centered hero or three-item grid can be correct; make its typography, proportions, content order, media relationship, and interaction inevitable for this brief.
## Perform replacement operations
Return to content and apply the smallest relevant operation:
| Generic symptom | Replacement operation |
| --- | --- |
| Equal hero elements | Name one dominant message or image; subordinate everything else through scale, contrast, and position |
| Three equal cards | Reclassify the content as sequence, comparison, evidence, index, roster, or annotated media |
| Container around everything | Keep containers only for semantic grouping, clipping, or interaction; release the rest into the page field |
| Repeated split sections | Change the relationship according to content: full bleed, inset caption, sticky context, dense index, or quiet text field |
| Trend palette/effects | Derive color and material from place, product, process, era, or source imagery |
| Uniform fade-ups | Assign motion by role and reading order; leave low-priority content still |
| Desktop stacked on mobile | Rechoose the focal point, crop, order, density, and interaction for narrow screens |
Choose one dominant message, one distinctive type relationship, one image behavior, one grid tension, and one motion principle. Vary section density and transitions. Remove every decorative treatment that does not strengthen one of the three signatures.
Restraint is not blandness. A near-empty composition with a decisive crop and exceptional type can be more specific than a busy effects stack.
## Reject counterfeit distinctiveness
Random diagonals, extreme type, noise textures, custom cursors, WebGL, and broken grids can make a page unusual without making it appropriate. Test novelty by removing the explanatory concept statement: can a reviewer infer the intended personality and content relationship from the page itself? If not, the effect is costume.
Do not solve generic copy with visual effects. Use real product language, credible evidence, meaningful labels, and content-shaped sections. When content is missing, expose the gap or use clearly marked provisional copy rather than fabricating proof.
## Self-review
Answer these after viewing the rendered page:
- Could this page belong to 500 unrelated SaaS startups?
- If the logo disappears, does the page retain a recognizable visual identity?
- Can each identity signature be pointed to in at least two separate sections?
- Is every section another rounded rectangle?
- Are hierarchy and order obvious within three seconds?
- Do type scale and line breaks create a composition, or merely format text?
- Does each image have an art-directed crop and role?
- Does section density change with the story?
- Are all animations simply opacity plus `translateY`?
- Can every glow, gradient, shadow, pill, and decorative mark justify its presence?
- Does mobile preserve the concept or only stack desktop?
- Is the page still specific after removing gradients, shadows, glow, and animation?
- Does any section exist only because landing pages usually contain one?
Revise when the page could serve an unrelated brand, when a signature does not recur, when effects carry more identity than content, or when sections follow a default skeleton instead of the brief.
references/color.md
# Color direction
Use color to establish hierarchy, atmosphere, and state. A palette is a set of relationships, not a row of swatches.
## Assign roles
Define field, ink, muted ink, surface, line, signal, and semantic state colors. Add a second accent only when it has a different job. Test each role against every background it actually touches, including image overlays, hover, disabled, and focus states.
Start with value structure in grayscale. If hierarchy collapses without hue, color is compensating for weak composition. Then introduce temperature and saturation deliberately:
- Use a broad field color to set atmosphere.
- Use one high-chroma signal sparingly enough to retain authority.
- Let imagery contribute color instead of competing with a large UI palette.
- Use off-black and off-white only when their temperature is intentional, not as automatic premium styling.
## Avoid trend palettes
Purple-blue gradients, neon-on-black, beige quiet luxury, or red sports accents are not concepts by themselves. Tie palette logic to material, place, era, product behavior, or source imagery. Change at least two of hue family, value structure, saturation behavior, and application pattern when a reference palette is recognizable.
Dark themes need more than inverted colors. Reduce high-contrast surface edges, control bloom around bright type, and keep large text crisp. Light themes need sufficient separation without outlining every region.
## Use gradients, texture, and transparency with a job
Use a gradient to describe light, depth, transition, or image legibility. Use transparency to reveal actual layering. Use texture to imply a named material. Remove any effect that only makes an empty area busier.
Validate contrast with an automated checker and with the final font weight, image crop, opacity, and state. Never encode status or interaction through color alone.
references/design-systems.md
# Design systems without template gravity
Build a small visual grammar that preserves the concept. Do not turn every design into the same component library.
## Separate invariants from expressions
Define invariants for accessibility and consistency: focus treatment, control sizing, type roles, spacing rhythm, color roles, grid anchors, media behavior, and motion tokens. Let expressive sections vary in composition, crop, scale, and density while using those invariants.
Create semantic tokens before component aliases:
```css
:root {
--color-field: #f2efe7;
--color-ink: #151515;
--color-signal: #d83a2e;
--space-edge: clamp(1rem, 3vw, 3rem);
--space-section: clamp(5rem, 12vw, 11rem);
--radius-control: 0.25rem;
--ease-enter: cubic-bezier(.16, 1, .3, 1);
}
```
Name roles by intent, not their current value. `--color-signal` survives a palette change; `--red-500` describes an implementation.
## Centralize tunable values
Treat visual values as design decisions, not markup trivia. In production and shared styles, use an existing semantic token or define one before introducing a tunable font size, line-height, spacing, width, radius, color, shadow, z-index, duration, or easing value.
Avoid hard-coded arbitrary Tailwind utilities such as `text-[12px]`, `mt-[37px]`, `rounded-[18px]`, or `shadow-[...]` when the value represents a design-system decision. Register the value in the project's Tailwind theme/configuration or expose it as a CSS custom property, then consume the named role:
```css
:root {
--text-meta: 0.75rem;
--leading-meta: 1.25;
--space-section-intro: clamp(3rem, 7vw, 7rem);
}
.metadata {
font-size: var(--text-meta);
line-height: var(--leading-meta);
margin-block-start: var(--space-section-intro);
}
```
```html
<!-- Prefer a project-defined semantic utility. -->
<p class="text-meta">Updated 3 hours ago</p>
<!-- Avoid embedding a design decision at the call site. -->
<p class="text-[12px]">Updated 3 hours ago</p>
```
Name the role, not the number: use `--text-meta`, `--space-hero-copy`, or `--radius-control`, not `--size-12`, `--gap-37`, or `--radius-18`. Keep component-specific variables near the component; promote values to global tokens only when multiple regions share the same contract.
A literal may remain local when it is a genuine implementation constant rather than a tunable design choice—for example, a `1px` hairline or a one-off calculation bound to an asset. Document unusual exceptions. During rapid prototype exploration, temporary literals are acceptable, but promote repeated values and every selected direction's tunable values to semantic tokens before production integration.
## Control component sameness
Create a component when behavior, semantics, or a repeated visual contract is genuinely shared. Do not abstract two superficially similar editorial arrangements into a universal card. Support controlled variants with a small explicit API; avoid dozens of booleans that hide unrelated compositions behind one component.
Use primitives for container edges, typography roles, buttons, links, media frames, focus, and recurring metadata. Let feature sections compose those primitives differently. A system is successful when pages feel related without appearing cloned.
## Audit the token signature
Before finalizing, inspect radius, shadow, border, blur, gradient, type, spacing, and container usage. Replace unexplained raw values and repeated arbitrary utilities with semantic tokens. If the same tokens appear on nearly every element, the system is flattening hierarchy; reserve strong treatments for named roles and allow `none` to be the default for decoration.
Document only decisions that future sections must preserve. The rendered interface—not token count—is the completion test.
references/game-sites.md
# Game and fantasy brand sites
Build a world-facing interface, not a generic product page wearing fantasy textures.
## Establish the fantasy
Choose a player promise: mastery, belonging, discovery, power, collection, competition, or spectacle. Derive the visual language from the world's rules, era, materials, factions, and combat rhythm. Keep navigation and calls to action legible beneath atmosphere.
## Hero key art
- Compose around a focal character, vehicle, landscape, or conflict—not several equal subjects.
- Reserve negative space for title and action during asset selection, not after.
- Separate foreground subject, atmospheric midground, and background when layers enable useful depth.
- Provide a dedicated mobile crop or asset; keep faces, weapons, silhouettes, and title readable.
- Treat logos and rating/platform marks with correct clear space.
## World presentation
Present factions, bloodlines, classes, or regions through a shared system with meaningful variation: emblem, color role, material, vocabulary, and motion character. Avoid recolored identical cards. Use maps, dossiers, banners, specimens, or match graphics when those forms fit the fiction.
Interactive rosters need keyboard navigation, visible selection, concise summaries, and a stable fallback. Large character transitions should not delay comparison or hide content from touch users.
## Cinematic storytelling
Use scroll sequences for transformations that benefit from continuity: entering a world, revealing a power system, moving through a tournament, or shifting factions. Keep each sequence bounded, avoid excessive pinning, and provide static reduced-motion states.
## Trust and action
Surface platforms, release state, modes, age rating, system requirements, community links, and purchase/wishlist actions without breaking immersion. Optimize key art and video aggressively; an atmospheric first screen that arrives late fails its purpose.
Never imitate a proprietary game's characters, heraldry, terminology, maps, UI, or signature presentation. Invent a visual system from the new world's own logic.
references/imagery.md
# Imagery direction
Choose imagery for a defined role: hero, evidence, atmosphere, narrative sequence, texture, or subject portrait. A coherent crop and treatment can carry more identity than extra UI.
## Direct the frame
- Identify the subject, gaze, motion vector, and negative space. Place copy in naturally quiet areas instead of covering detail.
- Set focal-point-aware `object-position` values per breakpoint. A centered crop is rarely neutral.
- Use full bleed for immersion; use contained media when its objecthood, caption, or border matters.
- Use masks and clipping shapes that repeat the concept's shape language. One distinctive mask is stronger than many unrelated shapes.
- Layer transparent PNG/WebP/AVIF subjects over type or fields when silhouette and depth matter. Maintain clean edges and believable overlap.
- Build editorial collage from deliberate scale, crop, z-order, and shared alignment. Random rotation is not art direction.
## Responsive crops
Provide different aspect ratios or sources with `<picture>` when desktop and mobile need different frames. Never preserve a panoramic desktop crop if the mobile subject disappears. Reserve space with `width`/`height` or `aspect-ratio` to prevent layout shift.
## Video and depth
Use video when movement communicates material, place, performance, or atmosphere. Supply poster imagery, muted inline behavior where appropriate, playback controls for meaningful content, and a reduced-data/static alternative. Avoid autoplaying large media that delays the page's central message.
Create depth through occlusion, scale, focus, and motion hierarchy. Keep text readable and interactive layers unambiguous.
## Delivery
- Choose modern formats with sensible fallbacks and source dimensions.
- Generate responsive `srcset` sizes matching rendered slots.
- Load the likely LCP hero eagerly and with appropriate priority; lazy-load below-fold media.
- Compress to the perceptual needs of the crop and display density.
- Write useful alt text for informative images and empty alt text for decoration.
- Measure LCP, decode cost, and layout shift on representative mobile hardware.
references/landing-pages.md
# Landing-page direction by category
Choose patterns from the product's buying logic and emotional promise. Do not combine every pattern below.
## Premium products
Lead with material, silhouette, or a single differentiating detail. Use controlled scarcity, precise specifications, macro imagery, and quiet transitions. Make price, configuration, delivery, and action clear without turning the page into a dashboard.
## Hospitality
Sell a sense of place before amenities. Sequence arrival, atmosphere, rooms, food, surroundings, and booking confidence. Use cinematic crops, local texture, editorial captions, and persistent but calm booking access. Keep essential accessibility and location information easy to find.
## Sports
Build around energy, stakes, people, numbers, and schedule. Combine decisive condensed type with sharp photography and data-like utility text. Use directional composition and fast accents; leave recovery space between dense moments.
## Creative agencies
Let work dominate claims. Establish a point of view quickly, then use varied case-study entries whose layouts respond to each project. Make services and contact discoverable without reducing the page to a capabilities grid.
## Fashion
Treat image sequencing, casting, crop, and pace as the primary interface. Use typography with editorial discipline. Balance campaign atmosphere with product or collection navigation. Avoid fashion pastiche when the available imagery cannot sustain it.
## Portfolios
Express the maker's selection logic. Lead with the strongest proof, give projects distinct rhythms, and expose role and contribution clearly. An index can coexist with immersive features. Avoid equal cards that imply every project is interchangeable.
## Launch sites
Concentrate attention around one reveal, promise, or date. Sequence intrigue, proof, mechanics, and action. Use one memorable interaction rather than a collection of effects. Ensure the core message and signup/purchase path work before animation loads.
For every category, derive an original concept from the actual brand. These patterns describe information and pacing, not a visual template.
references/layout.md
# Layout and page rhythm
Treat the grid as a system for creating relationships, not a cage.
## Establish a base
Start with a 12-column desktop grid when the page needs flexible editorial alignment. Define gutters, outer margins, and recurring anchors. Tablet may collapse to 8 columns and mobile to 4, but preserve meaningful alignment rather than the column count itself.
Use offset columns to create hierarchy: a title can occupy columns 1–7 while its deck begins at 8; media can align to one edge and let metadata hold the opposite margin. Break the grid only after establishing it, so the break reads as tension rather than error.
## Compose with tension
- Use asymmetry when unequal weights create a clear focal point.
- Overlap elements when their layering expresses depth or connection; protect readability and hit areas.
- Let full-bleed media release the page from contained sections.
- Use whitespace as an active field around important material, not leftover space.
- Crop oversized text or imagery intentionally at edges while retaining comprehension.
- Keep decorative geometry tied to alignment, content, or motion paths.
## Vary density
Sequence dense and sparse sections. A compressed roster may follow a spacious manifesto; a full-viewport image may reset the eye before detailed content. Avoid repeating identical vertical padding, heading placement, and card counts.
Plan transitions between sections: hard color cut, media bleed, typographic bridge, overlap, sticky handoff, or quiet whitespace. Each transition should advance pace. Full-viewport sections earn their height through a complete visual beat, not a blanket `min-height: 100vh`.
## Advanced structures
- Use sticky compositions when one context must remain while related content changes.
- Use horizontal sequences only when order, comparison, or panorama benefits; retain keyboard access and a simple narrow-screen alternative.
- Use broken grids for one or two focal moments rather than every section.
- Keep DOM reading order meaningful even when CSS repositions content.
Test extremely short and long content, browser zoom, and narrow widths. A composition is robust when its relationships survive content—not when one screenshot is perfect.
references/prototype-handoff.md
# Production adoption and exploration record
Complete the approved production design before retiring the design lab. Apply this handoff only after the user separately approves production integration.
## Adopt the approved direction
1. Summarize the selected direction or hybrid and the design problem it resolves as a compact production brief.
2. Inventory the behavior and production boundaries that must survive the redesign. Implement the brief through the existing application architecture while the lab remains available for visual comparison. Replace mocks with established data flows and preserve authentication, authorization, validation, analytics, transactions, business rules, background jobs, and stable behavior.
3. Compare the production result with the approved direction and exercise the preserved behavior. Continue until every approved surface is present and every risk-proportionate check passes. A commit, clean checkpoint, passing subset, or long turn marks progress only.
Report completion only after the whole approved production surface works. When a genuine blocker prevents that outcome, name the unmet criterion and report the integration as blocked.
## Preserve the design exploration
After production passes validation, record the starting production branch and worktree state, then:
1. Inventory every prototype or variant, switcher, mock, scoped style, asset, and experimental dependency created by the exploration.
2. Create a collision-free archive branch such as `design/<scope>-prototypes` or, for lightweight variants, `design/<scope>-variants`. Commit the complete exploration there, including approved, rejected, and hybrid directions. Exclude unrelated user changes, secrets, caches, and generated output.
3. Record the archive branch and commit ID. Verify that the commit restores every direction before removing exploration artifacts from the production line.
4. Record the archive location, production brief, and selection rationale in the final handoff or an implementation record already in scope.
5. Return to the production line and remove prototype routes and components, variant gates, comparison controls, mocks, scoped styles, experimental assets, and lab-only dependencies. Keep the shipped implementation free of design-lab machinery.
## Remove redesign-created orphans
Audit files and dependencies touched or superseded by the redesign. Check static and dynamic imports, routes, assets, styles, tests, stories, localization, build entries, and package usage before deletion. Remove each item proven unused because of this integration. Keep unrelated pre-existing dead code outside scope and retain uncertain dynamic consumers until their use is resolved.
Re-run reference searches and relevant build or type checks after cleanup. Commit locally; push only when the user explicitly requests it.
When Git is unavailable, keep the isolated lab, report that no archive branch was created, and remove it only with user approval.
## Completion criteria
- The approved direction is fully implemented and validated before archival begins.
- The recorded archive commit restores every explored direction when Git is available; otherwise the retained lab is reported.
- The production brief, selection rationale, and archive location are recorded durably.
- The production line contains the shipped design with no exploration machinery or redesign-created orphan.
references/prototype-workflow.md
# Prototype-first workflow
Use this workflow to separate visual exploration from production integration. Optimize for directional learning first and production confidence only after approval.
## Contents
- [Choose the branch](#choose-the-branch)
- [Set up the lab](#set-up-the-lab)
- [Add a comparison dock](#add-a-comparison-dock)
- [Create three real alternatives](#create-three-real-alternatives)
- [Use realistic mock data](#use-realistic-mock-data)
- [Protect production](#protect-production)
- [Apply the smallest useful validation](#apply-the-smallest-useful-validation)
- [Compare and select](#compare-and-select)
- [Refine and visually verify](#refine-and-visually-verify)
- [Integrate the approved specification](#integrate-the-approved-specification)
- [Validate production](#validate-production)
## Choose the branch
Enter prototype mode immediately for explicit requests containing prototype, mock it first, design only, exploration, concepts, directions, isolated version, do not touch backend, or do not change working code.
Use three prototypes by default for:
- a new homepage or landing page;
- a major visual redesign;
- a substantial section whose hierarchy or art direction is unresolved;
- a new brand, campaign, portfolio, game, hospitality, sports, fashion, or editorial direction;
- an experiment where typography, composition, imagery, interaction, or motion could change materially.
Stay on one direction when the user requests one concept or another explicit count, changes a local detail, asks to iterate a named prototype, refines an approved direction, or begins integration. Treat three as the default exploration count, not a quota.
## Set up the lab
Choose the lightest isolated environment the framework supports. Prefer routes or entry points such as:
```text
/design-lab/homepage
/design-lab/homepage/a
/design-lab/homepage/b
/design-lab/homepage/c
```
Equivalent component stories, static entries, or `/prototypes/homepage-01` routes are valid. Keep URLs stable enough for screenshot comparison. An index may provide direction summaries and thumbnails, but it is not the primary navigation between prototypes.
Keep prototype styles scoped so they cannot leak into production routes. Reuse safe project primitives—reset, font loading, icon access, media utilities—only when they accelerate work without constraining divergence.
## Add a comparison dock
For two or more directions, render one lightweight shared switcher on every prototype route. Make it a fixed floating dock—typically bottom-center or in a safe corner—that lets the user open A, B, C, and the optional overview directly. Use the framework router and prefetch when available so switching feels immediate; avoid a transition that obscures visual comparison.
Keep the dock visually neutral and independent from every prototype's art direction. Scope its styles, place it above prototype content, respect safe-area insets, and prevent it from changing page layout. Make it compact or horizontally scrollable on narrow screens rather than covering the design.
Meet this interaction contract:
- identify the control with an accessible label such as `Prototype switcher`;
- expose every direction by a short name or letter and mark the current route with `aria-current="page"` plus a non-color visual state;
- use real links when each direction has a URL, preserving open-in-new-tab and browser history behavior;
- provide visible focus and touch-friendly targets;
- support optional shortcuts such as `Alt+1`, `Alt+2`, and `Alt+3` only when they do not intercept typing in inputs or editable content;
- keep the current mock-data scenario or shared query state when switching where practical;
- provide collapse or hide behavior for unobstructed inspection and screenshots, with a discoverable way to restore the dock;
- keep the dock and its dependencies out of production routes and bundles.
Do not blindly preserve raw scroll pixels between directions with different content lengths. Preserve a shared section anchor or named comparison state when the prototypes have equivalent landmarks; otherwise start at a predictable position.
The dock is the one intentional shared UI primitive across prototypes. Do not use it as a reason to force the prototypes themselves through common layout or component abstractions.
## Create three real alternatives
Write a one-paragraph thesis for A, B, and C before implementation. Derive them from the brief rather than default labels. Make at least three high-leverage systems differ across every pair:
- dominant focal point and hero logic;
- typography voice and scale behavior;
- grid, alignment, overlap, and negative space;
- section order, density, and transition rhythm;
- imagery crop, layering, and media role;
- palette structure and material treatment;
- navigation and content presentation;
- interaction and motion character;
- mobile transformation.
Do not count token swaps as separate directions. If A and B share the same DOM composition, hierarchy, crop, and interaction and differ mostly in color or font, replace one.
Use the same core content and comparable scope. Bring each prototype far enough to judge the full design language—usually hero, navigation, two or more representative section types, a primary action, and a credible mobile transformation. Keep fidelity balanced; a polished A cannot be compared fairly with skeletal B and C.
## Use realistic mock data
Create one small shared mock-data layer when practical, while allowing each prototype to select and order it differently. Mock users, products, characters, articles, prices, statistics, leaderboards, navigation, API responses, media, and application states without connecting production services.
Include content stressors:
- very short and very long titles;
- missing descriptions, images, or optional metadata;
- long names and large numbers;
- multiple status or selection states;
- portrait, landscape, square, and unusual image ratios;
- realistic list sizes rather than three perfect items.
Label invented proof, metrics, quotes, and testimonials as mock content. Do not let synthetic marketing claims survive integration unnoticed.
## Protect production
During exploration, leave backend logic, controllers, APIs, database models, authentication, authorization, payments, jobs, server workflows, and stable production components unchanged. Do not add migrations, production endpoints, or state management merely to make a prototype look live.
Read from safe existing assets or types when useful, but copy or adapt presentation-facing shapes into mock data. Do not write to production stores. Keep experimental dependencies local and avoid adding a heavy package to the production bundle before the selected direction proves it necessary.
## Apply the smallest useful validation
Validate the question being answered, not the whole repository:
| Change | Prototype-mode validation |
| --- | --- |
| Color, spacing, type size, crop, or layout | Render the affected route; inspect the relevant viewport and obvious overflow |
| Prototype component behavior | Exercise that component and check relevant console/runtime errors |
| Comparison dock | Switch from every direction, confirm active/focus states, test narrow screens, and verify hide/restore behavior |
| Responsive composition | Inspect the affected breakpoints plus one width on each side of the transition |
| Animation or interaction | Observe trigger, interruption, final state, touch behavior, and reduced-motion alternative |
| Shared mock-data shape | Render all prototypes that consume it and include one edge case |
| New experimental dependency | Confirm the prototype loads and the dependency is scoped away from production entry points |
During active iteration, skip full backend/frontend suites, repository-wide lint and type checking, full E2E, and production builds unless the prototype cannot function without them. Record deferred checks when the experiment exposes a real production risk.
Avoid premature abstractions, production APIs, authentication wiring, business-logic refactors, elaborate state management, migrations, and extensive tests. Optimize in order for art direction, identity, composition, typography, imagery, responsive behavior, interaction, motion, and internal consistency.
## Compare and select
Capture all directions with the same viewport set, core content, and relevant state. Provide a compact comparison:
```text
Direction A — thesis
Strongest at: ...
Tradeoff: ...
Direction B — thesis
Strongest at: ...
Tradeoff: ...
Direction C — thesis
Strongest at: ...
Tradeoff: ...
```
Compare concept, hero, type, composition, imagery, navigation, section rhythm, interaction, motion, and mobile potential. Do not announce a winner unless requested. Ask the user to select A, B, C, or a named hybrid before integration.
## Refine and visually verify
Keep rejected prototypes available for reference and stop polishing them. Consolidate selected ideas into one refined prototype when the user requests a hybrid. Small revisions stay within that prototype; create another direction only when the user asks or the selected thesis fails fundamentally.
Use `motion-art-direction` for the refined prototype's substantial choreography, allowing exploratory implementation to remain local until the language is approved. Use `frontend-visual-qa` against the isolated refined prototype. Inspect desktop, tablet, mobile, hierarchy, typography, crops, spacing, rhythm, motion, interaction, accessibility basics, and mock-data stressors before integration.
After integration approval, execute [production adoption and exploration record](prototype-handoff.md): implement and validate the approved direction first, then preserve the design lab on an archive branch outside the production line. When Git is unavailable, retain every direction in the isolated lab, report that no archive branch can be created, and obtain direction before removing it.
## Integrate the approved specification
Treat the approved prototype as the presentation source of truth and the existing application as the behavior source of truth:
```text
APPROVED PROTOTYPE + EXISTING BUSINESS LOGIC -> FINAL IMPLEMENTATION
```
Port the visual hierarchy, tokens, layouts, media behavior, interactions, and approved motion into production architecture. Replace mock data with existing APIs and application state. Reconcile loading, empty, error, permission, authenticated, and transactional states. Preserve contracts, authorization, validation, analytics, and business rules.
Refactor only what integration requires. Do not use a redesign to rewrite unrelated application code or replace proven logic with prototype shortcuts.
## Validate production
After integration, identify every production boundary changed and choose checks that cover it. Run relevant type checking, linting, builds, unit tests, component tests, integration tests, backend tests, E2E flows, visual regression, accessibility checks, and performance measurement.
Broaden validation when shared components, routing, data contracts, authentication, transactions, or build behavior changed. Keep it targeted when the approved presentation is isolated and the evidence covers the affected surface. Finish only when the production page matches the approved prototype and existing behavior still works.
references/responsive-design.md
# Responsive composition
Treat each breakpoint as a new arrangement of the same narrative. Preserve priority and character, not desktop coordinates.
## Transformation pass
For every major composition, record:
| Decision | Desktop | Tablet | Mobile |
| --- | --- | --- | --- |
| Structure | columns, overlaps, sticky regions | simplified relationships | focused linear or intentionally layered sequence |
| Type | scale and line breaks | intermediate wrap | rewritten wrap, retained hierarchy |
| Media | ratio and focal point | revised crop | dedicated crop/source and position |
| Order | visual and DOM order | handoff | reading and action order |
| Space | margins and rhythm | compressed selectively | touch-safe, not uniformly cramped |
| Motion | full choreography | shorter/lower distance | essential feedback and simplified reveals |
## Recompose deliberately
- Collapse secondary navigation before it crowds the brand and primary action.
- Move metadata, captions, and controls near the content they describe.
- Replace fragile overlap with a purposeful crop, inset, or reordered stack.
- Keep one strong mobile focal point; do not preserve every desktop competitor.
- Use container queries when a component's available space, rather than viewport width, determines its layout.
- Let breakpoint changes occur where content breaks. Framework defaults are starting points.
## Validate real constraints
Test at widths between named breakpoints, not only presets. Check landscape phones, browser zoom, long words, localization, large text, safe areas, touch targets, sticky headers, virtual keyboards, and reduced motion. Ensure DOM order remains logical for keyboard and screen-reader use.
A mobile page that is merely desktop stacked vertically often becomes long, repetitive, and weak. Reframe the crop, reduce competing layers, alter section density, and protect the most important interaction.
references/typography.md
# Typography as composition
Use type to establish identity and spatial order before adding decoration.
## Assign roles
- Choose a display face for personality and a utility face for sustained reading. One variable family can perform both roles if its axes create real contrast.
- Pair by productive tension: condensed display with neutral grotesk, expressive serif with disciplined sans, or wide geometric display with compact utility text. Avoid two faces with nearly identical character.
- Do not default to Inter or the framework starter font. Inspect brand, language coverage, licensing, loading cost, numerals, punctuation, and available weights first.
- Limit the active palette of faces and weights. Distinction should come from scale, width, case, rhythm, and placement—not a font sampler.
## Build contrast
Define a small hierarchy with visibly different jobs: display, section title, deck, body, label, metadata. Adjacent levels must differ enough to scan at a glance. A timid ratio produces a uniformly gray page.
Use fluid sizes when the composition benefits:
```css
--step-display: clamp(3.5rem, 2rem + 7vw, 10rem);
--step-title: clamp(2rem, 1.3rem + 3vw, 5rem);
--step-body: clamp(1rem, 0.96rem + 0.2vw, 1.125rem);
```
Tune each clamp from a chosen minimum and maximum viewport; do not scatter arbitrary formulas. Test zoom and long translations.
## Shape the text block
- Tighten display line-height until lines lock together without collisions; body text generally needs more air.
- Control measure: roughly 45–75 characters is a useful body-text starting range, not a universal law.
- Use deliberate line breaks when they strengthen a headline composition. Remove them or provide breakpoint-specific breaks before they create stranded words.
- Balance letter-spacing with face and size. Uppercase utility labels often need tracking; large display type often needs less.
- Align cap heights, baselines, and text edges with media or grid lines—not just bounding boxes.
## Make type structural
Let headlines span columns, crop at viewport edges, wrap around media, become masks, or establish the page's dominant axis. Kinetic type should reveal reading order or physical character; splitting every heading into animated words is not a concept.
On mobile, recompose rather than proportionally reduce. Change line breaks, width, alignment, and relationship to imagery. Protect readable body sizes and touch labels while allowing display type to remain bold.
references/visual-direction.md
# Derive a visual direction
Translate the product's truth into a compact set of visual decisions before opening the component tree.
## Build the thesis
1. Extract nouns and verbs from the brief: audience, category, place, material, behavior, stakes, and desired feeling.
2. Choose two or three productive tensions, such as archival/future, elite/raw, intimate/monumental, or precise/feral.
3. Write one visual-concept sentence that could not plausibly describe hundreds of unrelated products.
4. Turn that sentence into systems, then test every system against it.
## Translate concept into systems
- **Personality:** choose three behavioral adjectives and one explicit boundary. “Severe, fast, ceremonial; never playful” is more useful than “premium.”
- **Motifs:** derive recurring forms from subject matter—score lines, crop marks, apertures, topographic paths, fabric folds—not trend catalogs.
- **Texture:** decide whether surfaces feel printed, polished, mineral, analog, digital, atmospheric, or uncoated. Apply sparingly enough to retain contrast.
- **Shape language:** specify corners, curves, angles, frames, and line weights. Keep them related.
- **Typography language:** define voice, width, contrast, case, rhythm, and the relationship between display and utility type.
- **Color language:** assign colors roles: field, ink, signal, accent, state. Check contrast in actual overlays and states.
- **Imagery language:** specify subject, lighting, lens feeling, crop, treatment, and sequencing.
- **Motion language:** specify pace, easing character, direction, depth, and where stillness belongs.
## Pressure-test originality
Remove the logo and brand name. If the direction becomes category-generic, strengthen the concept or content relationships. Compare choices against supplied references and deliberately change the composition, assets, palette logic, and choreography while preserving only abstract lessons.
Record the final thesis in five or six lines. Implementation is consistent when a new section can be judged against that statement without inventing a new aesthetic.
SKILL.md
---
name: creative-frontend-design
description: Develop and implement deep, original art direction for public-facing websites. Use for visual concepts, isolated directions, identity-defining typography, composition, imagery, responsive transformation, reference-led design, or replacement of generic styling when the task needs design intelligence without the full end-to-end orchestration. Use rapid-ui-redesign for fast experiments that retain an existing working UI's identity and architecture.
---
# Creative frontend design
Act as both a senior digital art director and a senior frontend engineer. **Do not start with components. Start with art direction.** Make the page recognizable before decorating it.
## Prototype-first default
For substantial visual design, redesign, art direction, layout, typography, or frontend experimentation, prototype in isolation and create **3 distinct directions by default** unless the user specifies another number. Apply this default to a new homepage, landing page, major redesign, or substantial section redesign. Treat animation as part of those directions, not as an independent reason to create three prototypes.
```text
UNDERSTAND -> CREATE 3 -> COMPARE -> ITERATE -> USER SELECTS -> REFINE -> VISUAL QA -> INTEGRATE -> PRODUCTION VALIDATION
```
Make the prototypes meaningfully different in concept, typography, composition, imagery, density, interaction, and motion—not cosmetic variations of one layout. Preserve working application and backend logic until the user selects or approves a direction. During exploration, use the **smallest useful validation**.
Keep a small change on an already selected direction as one change. Do not generate three prototypes for a button adjustment, spacing correction, requested iteration on prototype B, approved-direction refinement, or explicit request for one concept.
Read [prototype workflow](references/prototype-workflow.md) before coding whenever the task is substantial or the user says prototype, mock it first, design only, exploration, concepts, directions, isolated version, do not touch backend, or do not change working code.
## Workflow
### 1. Understand the scope
Inspect the repository, current design system, content, assets, routes, constraints, and stable application behavior. When references or screenshots are supplied, analyze hierarchy, typography, spacing, composition, color relationships, media treatment, navigation, section transitions, scroll behavior, interaction language, density, and motion.
Extract principles only. Create original branding, composition, copy treatment, crops, and choreography. Do not reproduce logos, proprietary text, distinctive illustrations, exact layouts, signature animation sequences, or unique assets.
Choose the prototype-first branch unless the user explicitly changes the count, asks for a small or single-direction change, names an existing prototype to iterate, or has already approved the direction and requested integration.
### 2. Frame the directions
Derive the chosen number of directions from the project's brand, audience, content, assets, product, desired emotion, references, and technical constraints. Do not reuse a fixed editorial/immersive/minimal trio across projects.
Write a compact brief for each direction covering:
1. Visual concept and brand personality
2. Typography language
3. Composition and grid
4. Color and imagery
5. Navigation and content order
6. Interaction and motion
7. Section rhythm and density
8. Responsive transformation
Give every direction a defensible thesis. When comparing multiple directions, give each a different dominant gesture and use shared content to make comparison honest.
### 3. Build isolated prototypes
Create framework-appropriate routes or components such as `/design-lab/homepage/a`, `/b`, and `/c`. When more than one direction exists, add one shared lab-only floating switcher to every prototype route so the user can move directly among A, B, and C without returning to an index. Keep an optional overview index for summaries or thumbnails. Share realistic mock data, not a rigid presentation architecture; the switcher may be shared even when prototype presentation code diverges.
Protect production behavior. Do not connect prototypes to real APIs, databases, authentication, payments, jobs, controllers, or stable business logic merely to preview design. Include mock-content extremes that expose visual fragility.
Bring every created prototype to comparable directional fidelity before polishing one. For each visual edit, render the affected prototype, inspect the relevant viewport or interaction, and check obvious runtime errors. Defer repository-wide tests, builds, and unrelated refactoring.
### 4. Compare and obtain selection
Show A, B, and C with the same core content and comparable viewport evidence. Explain each philosophy and its tradeoffs across hero, type, composition, imagery, navigation, rhythm, interaction, motion, and mobile potential.
Do not choose a winner unless asked. Apply comparison feedback to the relevant prototypes and repeat until the user can select confidently. Stop before production integration and obtain the user's selection or approval. Accept hybrids such as the hero from A, typography from B, and navigation from C; consolidate them into one refined direction.
### 5. Refine and visually verify
Stop investing heavily in rejected directions, but retain them unless removal is requested. Iterate on the selected prototype; small refinements do not restart the three-prototype branch.
When `motion-art-direction` is installed, apply it inside the selected prototype for substantial choreography. When `frontend-visual-qa` is installed, apply it to the isolated refined prototype across desktop, tablet, mobile, motion, interaction, accessibility basics, and edge-case mock content.
When `frontend-visual-qa` is unavailable, render the refined prototype at representative wide, intermediate, and narrow widths; inspect hierarchy, typography, composition, crops, overflow, interaction, and reduced motion; fix material failures and re-render them. Label states that cannot be rendered as unverified.
### 6. Integrate after approval
For substantial prototype-first work, execute [production adoption and exploration record](references/prototype-handoff.md). Treat the approved prototype as a visual specification expressed in working code. Port its presentation into the application, replace mocks with real data, reuse existing APIs, preserve business rules, and adapt components to production architecture. Validate the production implementation before archiving the lab and removing exploration from the production line. Do not replace proven application logic with prototype logic or use redesign as permission for unrelated cleanup.
### 7. Validate production
After integration, run validation proportional to the affected production surface: type checks, linting, builds, unit, component, integration, backend, E2E, and regression tests as scope and risk require. Use targeted validation when it establishes confidence; run broad suites when integration crosses broad boundaries.
## Reference routing
- Read [visual direction](references/visual-direction.md) when the brief lacks a clear concept, and [anti-AI slop](references/anti-ai-slop.md) before evaluating any direction.
- Read [design systems](references/design-systems.md) before creating or changing shared CSS, Tailwind utilities, tokens, or primitives; centralize tunable values instead of scattering raw arbitrary values. Read [typography](references/typography.md), [layout](references/layout.md), [color](references/color.md), and [imagery](references/imagery.md) when changing those systems.
- Read [responsive design](references/responsive-design.md) before mobile refinement and [accessible performance](references/accessible-performance.md) before media-, interaction-, or motion-heavy implementation.
- Read [landing pages](references/landing-pages.md) or [game sites](references/game-sites.md) only for the relevant category.
- Use a relevant example as a brief format, never a template: [luxury minimal](examples/luxury-minimal.md), [sports editorial](examples/sports-editorial.md), [gaming](examples/gaming.md), or [creative agency](examples/creative-agency.md).
## Completion criteria
- A substantial exploration produces three isolated, comparable directions unless the user overrides the count.
- Each prototype has a distinct thesis and dominant gesture, not merely different colors or minor layout changes.
- The user selects or approves a direction before production integration begins.
- Existing application and backend behavior remain untouched during exploration.
- The production-adoption and exploration-record criteria pass: the approved design ships and, when Git is available, the archive branch preserves the exploration.
- Every multi-direction lab supports direct, accessible switching from each prototype route without an index-page round trip.
- Prototype iteration uses the smallest useful validation; post-integration validation matches scope and risk.
- Production and shared styles express tunable values through semantic tokens rather than scattered hard-coded values.
- The approved result is original, accessible, performant, responsive, and verified in the browser.