name: hyperblue description: Build premium, brand-aware React/Next.js frontends that feel designed by a senior UI engineer, not generated by AI. Use this skill whenever the user wants to create websites, landing pages, dashboards, web apps, React components, or any frontend UI — especially when they provide brand assets (logos, screenshots, colors), mention a specific business or industry, want to match an existing design system, or ask for "non-generic" or "premium" output. Also trigger when the user shares competitor sites for inspiration, asks for design tokens, wants animation direction, or needs responsive brand consistency. This skill replaces generic AI aesthetics with market-aware, brand-calibrated design engineering. Created by Incredible Visibility.

Hyperblue

Build premium React/Next.js interfaces calibrated to a specific brand identity, informed by competitive landscape research, and engineered to override default LLM design biases.

This skill operates in six phases. Each phase feeds the next. Brand tokens generated in Phase 2 are the connective tissue — every rule in Phases 3-5 references them instead of hardcoded values. Use AskUserQuestion throughout to gather input interactively via selectable options rather than open-ended prose questions.

PHASE GATE SYSTEM — MANDATORY WORKFLOW

CRITICAL: Do NOT skip phases. Do NOT write component code before Phase 2 is complete.

Every full build follows this sequence. Each phase has a gate — a deliverable that must be presented to the user and confirmed before proceeding. Refinement modes (Phase 6) are the only exception: they operate independently on existing code.

Build Strategy — how the sitemap becomes a real multi-page site:

The build phase is NOT "write one long landing page." It follows a strict foundation-first, pages-second order:

Step 1: Design System Foundation (always built first)

• Token file: Create a CSS/Tailwind token file that codifies all Phase 2 tokens (globals.css with --brand-* custom properties, or tailwind.config theme extensions). This is the single source of truth for the entire site.
• Next.js routing scaffold: Create the app/ directory structure matching the confirmed sitemap. Every route gets at minimum a page.tsx with a placeholder that imports the shared layout. Dynamic routes get their [slug] folders.
• Root layout: app/layout.tsx with font loading, metadata, theme provider, and the token file imported.
• Shared components: Build these before any page content:
  • Navigation — responsive nav derived from the sitemap (all routes become nav links or grouped under dropdowns). Hamburger/sheet on mobile.
  • Footer — sitemap-derived link groups, brand info, legal links.
  • Section — reusable section wrapper with consistent spacing rhythm (py-16 md:py-24), max-width container, and optional background variants.
  • Button — primary, secondary, ghost variants using brand tokens.
  • Card — if the design uses cards, a branded card with consistent radii, shadow, and padding.
  • Typography — heading and body text components with the brand's type scale baked in (optional but recommended for large sites).
• Dark mode toggle — if dark mode was defined in tokens, wire it up in the layout.

Step 2: Page-by-Page Build

• After the foundation is confirmed, ask the user: "Which page should I build first?" Default suggestion: homepage.
• Each page imports and composes the shared components. Page-specific sections are built as local components within that route.
• Every page uses the design tokens — no hardcoded colors, fonts, or spacing.
• Internal links between pages use the sitemap routes (<Link href="/about">), not anchor links to sections on the same page.
• After each page is complete, ask: "Page done. Which page next?" Continue until the user stops or all sitemap pages are built.

Step 3: What if the user only wants one page right now?

• Build the full foundation (Step 1) regardless — it's the design system investment.
• Build the requested page (Step 2).
• The remaining sitemap routes keep their placeholder page.tsx files with a consistent "Coming Soon" or skeleton state using the brand's design tokens.
• The user can return in a future session and say "build the /about page" — the foundation, tokens, nav, and footer are already in place.

CRITICAL: Never flatten the sitemap into a single scrolling page. If the sitemap has /about, /services, /contact as separate routes, they must be separate Next.js routes with their own page.tsx files — not sections within a single-page layout. The only exception is if the user explicitly asks for a single-page/one-pager.

How to enforce this in practice:

• After completing each gate, explicitly tell the user which phase you just finished and which phase comes next: "Phase 1A complete — competitive anchors locked. Moving to Phase 1B: Brand Intake."
• If the user says "just build it" or pushes to skip ahead, you may compress phases (combine questions, make reasonable defaults) but you must still pass through each gate. At minimum, summarize what you're assuming for each skipped gate so the user can course-correct.
• If the user asks for a single component (not a full site), you may fast-track: run 1B (brand intake) and 2 (tokens) only, then build. Skip 1A, 1C, 1D, 1E.
• For refinement modes (Phase 6), no gates are needed — read the existing code and apply targeted fixes.

PHASE 1: DISCOVERY

Before writing any code, establish the design context. This phase has four tracks.

Interactive Discovery: Throughout this phase, use the AskUserQuestion tool to gather user input interactively — present selectable options instead of asking open-ended questions in prose. This gives the user a faster, click-to-choose experience. Use preview fields when comparing visual directions (e.g., layout mockups, color palettes). Use multiSelect: true when choices aren't mutually exclusive. Always keep options to 2-4 per question, with clear labels and descriptions. The user can always pick "Other" for custom input.

1A. Competitive Landscape Research

When the user provides a business description (even a one-liner like "luxury perfume e-commerce in the Gulf" or "B2B SaaS for construction teams"), research the competitive landscape before designing anything.

Workflow:

1. Use web search to find 5-8 notable players in the user's industry/niche.
2. For each player, extract their visual signature:
   • Color family (warm/cool/neutral, primary accent)
   • Layout approach (editorial, grid-heavy, card-based, full-bleed imagery)
   • Typography choices (serif/sans, display vs system, hierarchy depth)
   • Animation style (minimal, functional, cinematic, playful)
   • Content tone (formal, conversational, technical, aspirational)
   • Navigation patterns (sticky, minimal, mega-menu, sidebar)
3. Present findings as a curated reference set. Use AskUserQuestion to let the user interactively select which competitors feel closest to their desired positioning — present the top 3-4 competitors as selectable options (with descriptions summarizing each one's visual signature), with multiSelect: true so they can pick more than one.
4. Note industry conventions AND gaps — if every competitor uses dark backgrounds, that's both a convention worth knowing and a differentiation opportunity.

The user's selections become design anchors. They feed into token generation alongside the brand's own assets. If the user skips this step or provides no business context, proceed with brand assets alone.

1B. Brand Intake

Collect the user's brand materials. Accept any combination of:

• Screenshots of their existing site, Figma mockups, or design references
• Logo files or descriptions
• Color guidelines (hex values, palette names, brand book excerpts)
• Font preferences (specific typefaces or general direction)
• Brand personality brief (even informal: "clean and premium" or "bold and technical")

If the user hasn't provided explicit brand direction, use AskUserQuestion to ask about their brand personality (e.g., "Minimal & Clean", "Bold & Expressive", "Warm & Approachable", "Sharp & Technical") and their content density preference (e.g., "Airy/editorial", "Balanced", "Dense/data-heavy").

When the user shares screenshots, extract:

• Spacing rhythm (base unit, section gaps, component padding)
• Alignment tendencies (left-heavy, centered, asymmetric)
• Content density (airy/editorial vs packed/dashboard)
• Component patterns (card styles, button shapes, nav structure)
• Visual hierarchy cues (how they differentiate primary from secondary from tertiary)
• Color usage in context (where the accent appears, what's neutral)

When the user shares a logo, extract:

• Dominant and secondary colors
• Geometric vs organic character (informs border radii, icon style, layout decisions)
• Weight and proportion (heavy/bold logos need more breathing room)
• Whether it works on both light and dark backgrounds

1C. Content Strategy

Establish the verbal personality that drives all generated microcopy. If not already clear from the brand brief, use AskUserQuestion to let the user pick their brand voice:

• Formal → restrained, confident copy. "Begin your session" not "Let's go!"
• Technical → direct, precise copy. "Deploy to production" not "Launch your creation"
• Conversational → warm, friendly copy. "Find your next favorite" not "Browse catalog"
• Luxury → minimal, evocative copy. "Discover" not "Shop now"

Apply this voice to every generated text element: button labels, headings, empty states, error messages, loading text, tooltips, placeholder content. No more generic "Get Started" buttons or "Something went wrong" errors — every string should sound like it was written by the brand's copywriter.

Banned copy patterns (regardless of brand): "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize", "Cutting-edge", "Empower", "Supercharge", "Unlock the power of". Use concrete verbs tied to what the product actually does.

1D. Sitemap Architecture

After completing competitive research and brand intake, generate an ideal sitemap for the user's website. This happens before any code is written.

Workflow:

1. Based on the business description, industry research, and competitor analysis, determine the optimal page structure.
2. Present the sitemap using AskUserQuestion with preview to show the proposed structure visually (as an ASCII tree diagram) alongside alternatives. Offer 2-3 sitemap variations as options:
   • Minimal — lean site with only essential pages (ideal for launches/MVPs)
   • Standard — industry-appropriate page set covering expected user journeys
   • Comprehensive — full-featured site with content marketing, resources, and conversion funnels
3. Once the user selects a direction, output the finalized sitemap as a structured list:

/ (Homepage)
├── /about
├── /services
│   ├── /services/[service-1]
│   └── /services/[service-2]
├── /work or /portfolio
│   └── /work/[case-study]
├── /blog
│   └── /blog/[post]
├── /contact
└── /legal
    ├── /privacy
    └── /terms

Sitemap principles:

• Pages should map to real user intents, not vanity sections. Every page earns its place by serving a navigation goal or conversion step.
• URL slugs should be clean, lowercase, hyphenated, and SEO-friendly.
• Group related pages under logical parents (e.g., /services/branding, not /branding).
• For e-commerce: include category → subcategory → product hierarchy. For SaaS: include features, pricing, docs, and changelog.
• Flag pages that need dynamic routes (e.g., blog posts, case studies, product pages) vs. static pages.
• The sitemap informs the Next.js file-based routing structure (app/ directory layout) when code generation begins.

The finalized sitemap becomes the structural blueprint for Phase 3. All navigation components, internal linking, and routing are derived from it.

1E. Asset Sourcing

When the user has not supplied their own images or videos, source contextually relevant royalty-free assets instead of using random placeholders. This step runs after brand intake so you know the industry, brand personality, and visual direction.

Image sourcing workflow:

1. Based on the project description, brand personality, and sitemap, identify the specific image subjects needed. Be precise — not "business" but "construction team reviewing blueprints on-site" or "luxury perfume bottles on marble surface with warm lighting."
2. For each needed image, use WebSearch to search Unsplash (e.g., site:unsplash.com construction team blueprints). Search for 2-3 variations per slot to find the best match.
3. From the search results, navigate to the Unsplash photo pages and extract the direct image URL — the stable images.unsplash.com/photo-* format. These are permanent and will not break.
4. Append query parameters to control dimensions and cropping: ?w=800&h=600&fit=crop&auto=format&q=80. Adjust w and h to match the layout's aspect ratio needs (hero images, card thumbnails, avatars all have different ratios).
5. If Unsplash does not have a strong match, fall back to Pexels (site:pexels.com) using the same search strategy. Use the images.pexels.com/photos/* direct URLs with ?auto=compress&w=800&h=600.

Video sourcing workflow (when the project calls for video backgrounds or media sections):

1. Search Pexels Videos (site:pexels.com/video) with specific scene descriptions matching the brand context.
2. Use the direct video file URLs from Pexels (they provide free-to-use MP4 links).
3. Always include poster attributes on <video> elements using a sourced still image, so content is visible before the video loads.
4. Wrap video backgrounds in <video autoPlay muted loop playsInline> with prefers-reduced-motion media query to pause for accessibility.

Asset selection principles:

• Match the brand temperature. Warm brands get warm-toned photography (golden hour, warm interiors). Cool/technical brands get crisp, high-contrast, blue-toned images.
• Match the content density. Editorial layouts (VISUAL_DENSITY 1-3) need large, atmospheric hero images. Dashboard-style layouts (VISUAL_DENSITY 7-10) need small, functional thumbnails or icons instead of photos.
• Avoid stock clichés. No handshake photos, no woman-laughing-at-salad, no generic "diverse team in glass conference room." Search for specific, authentic scenes tied to the actual industry.
• People should match context. If the brand is a Dubai perfume house, source imagery that reflects that market. If it's a Portland coffee roaster, the imagery should feel Pacific Northwest.
• Consistent visual style across all sourced images. Don't mix moody dark photography with bright airy lifestyle shots on the same page. Pick a photographic direction and stick with it.
• Always include attribution. Add a comment in the code above each sourced image with the photographer name and Unsplash/Pexels link: {/* Photo by [Name] on Unsplash: [URL] */}.

The sourced asset set feeds into Phase 3. All image references in generated components use these curated URLs instead of random placeholders.

PHASE 2: BRAND TOKEN SYSTEM

Convert all discovery inputs into a structured set of design tokens. These tokens are the single source of truth for every subsequent phase.

Token Categories

Color Tokens:

• --brand-primary: Main brand color (from logo/guidelines)
• --brand-secondary: Supporting color
• --brand-accent: High-contrast action color (CTAs, active states)
• --brand-neutral-[50-950]: Neutral scale (warm or cool, matching brand temperature)
• --brand-surface: Card/container background
• --brand-surface-elevated: Modal/dropdown background
• --semantic-success, --semantic-warning, --semantic-error, --semantic-info: Status colors calibrated to not clash with brand palette

Typography Tokens:

• --font-display: Headlines and hero text
• --font-heading: Section headers
• --font-body: Paragraphs and UI text
• --font-mono: Code, data, technical content
• Type scale: --text-xs through --text-6xl with brand-appropriate ratios

Spacing Tokens:

• Base unit (4px or 8px, derived from screenshot analysis)
• Scale: --space-1 through --space-16
• Section gaps calibrated to brand density (luxury = generous, dashboard = tight)

Shape Tokens:

• --radius-sm, --radius-md, --radius-lg, --radius-xl
• Geometric brands → smaller radii (2-4px). Organic/friendly brands → larger radii (8-16px). Sharp/technical brands → 0-2px.

Shadow Tokens:

• Warm brands: shadows tinted toward brand primary
• Cool brands: shadows tinted toward neutral blue-gray
• Depth levels: --shadow-sm, --shadow-md, --shadow-lg

Dark Mode Mapping: Do not just invert. Define specifically for the brand:

• True dark (near-black bg) for tech/developer brands
• Warm dark (dark brown/charcoal) for lifestyle/luxury brands
• Navy dark for corporate/financial brands
• Surface, text, and border colors shift while brand accent stays recognizable

Brand Override Rule

If the brand's actual identity uses something that would normally be banned by the anti-slop rules in Phase 3 (their font IS Inter, their color IS purple, their layout IS centered), the brand tokens override the ban. Brand truth always beats generic anti-pattern rules.

PHASE 3: CORE ENGINE

3A. Active Configuration Dials

Four tunable variables drive all design decisions. Defaults are set below but adapt dynamically based on user prompts or brand personality.

Dial behavior:

• At BRAND_FIDELITY > 7, prioritize matching reference screenshots and brand guidelines exactly. Creative license decreases.
• At BRAND_FIDELITY < 4, treat the brand as a starting point. Colors and fonts stay, but layout and creative direction are open.
• DESIGN_VARIANCE and BRAND_FIDELITY are inversely coupled — high fidelity naturally constrains variance unless the brand itself is highly varied.

3B. Architecture & Conventions

Unless the user specifies a different stack:

Framework: React or Next.js. Default to Server Components (RSC).

• RSC SAFETY: Global state works only in Client Components. Wrap providers in a "use client" component.
• INTERACTIVITY ISOLATION: Interactive UI (animations, hover effects, state-driven components) must be extracted as isolated leaf components with 'use client' at the top. Server Components render static layouts only.

Styling: Tailwind CSS (v3/v4) for 90% of styling.

• TAILWIND VERSION LOCK: Check package.json first. Do not use v4 syntax in v3 projects.
• T4 CONFIG GUARD: For v4, do NOT use tailwindcss plugin in postcss.config.js. Use @tailwindcss/postcss or the Vite plugin.

Dependency Verification: Before importing ANY third-party library (framer-motion, lucide-react, zustand, etc.), check package.json. If missing, output the install command before providing code. Never assume a library exists.

• SINGLE-FILE MODE: When generating artifacts or prototypes without a project environment, keep everything in one .jsx or .html file. Import only from CDN-available sources.

Icons: Use @phosphor-icons/react or @radix-ui/react-icons. Standardize strokeWidth globally (1.5 or 2.0). No emojis in code, markup, text content, or alt text — ever.

State Management: Local useState/useReducer for isolated UI. Global state only to avoid deep prop-drilling.

Responsiveness & Spacing:

• Standardize breakpoints: sm (640), md (768), lg (1024), xl (1280)
• Contain layouts with max-w-[1400px] mx-auto or max-w-7xl
• NEVER use h-screen for full-height sections. ALWAYS use min-h-[100dvh] (prevents layout jumping on iOS Safari)
• NEVER use complex flexbox percentage math (w-[calc(33%-1rem)]). Use CSS Grid (grid grid-cols-1 md:grid-cols-3 gap-6)

3C. Design Engineering Directives (Bias Correction)

These rules counter known LLM design biases. Each rule is subject to the Brand Override Rule from Phase 2 — if the brand's actual identity conflicts, the brand wins.

Rule 1: Deterministic Typography

• Display/Headlines: text-4xl md:text-6xl tracking-tighter leading-none using the brand's --font-display
• ANTI-SLOP: Discourage Inter for premium or creative contexts. Prefer: Geist, Outfit, Cabinet Grotesk, Satoshi, General Sans, Switzer, Plus Jakarta Sans
• TECHNICAL UI: Serif fonts banned for dashboard/software UIs. Use sans-serif pairings (Geist + Geist Mono, Satoshi + JetBrains Mono)
• Body: text-base leading-relaxed max-w-[65ch] using --font-body, colored with --brand-neutral-600

Rule 2: Color Calibration

• Max 1 accent color. Saturation under 80%.
• THE LILA BAN: "AI Purple/Blue" gradient aesthetic is banned. No purple button glows, no neon gradients. Use brand tokens.
• COLOR CONSISTENCY: One palette for the entire output. Do not fluctuate between warm and cool grays.

Rule 3: Layout Diversification

• ANTI-CENTER BIAS: When DESIGN_VARIANCE > 4, centered Hero/H1 sections are banned. Use split-screen (50/50), left-aligned content with right asset, or asymmetric whitespace structures.

Rule 4: Materiality & Shadows

• DASHBOARD HARDENING: When VISUAL_DENSITY > 7, generic card containers are banned. Use border-t, divide-y, or negative space to group data.
• Use cards only when elevation communicates hierarchy. When using shadows, tint them to the brand's temperature.

Rule 5: Interactive UI States Generate complete interaction cycles, not just the "happy path":

• Loading: Skeleton loaders matching layout dimensions (not generic spinners). Brand the shimmer color.
• Empty states: Composed illustrations or branded messaging showing how to populate data.
• Error states: Inline, specific error reporting. Use brand voice.
• Tactile feedback: On :active, apply -translate-y-[1px] or scale-[0.98] for physical push feel.

Rule 6: Data & Form Patterns

• Label above input, always. Helper text optional but in markup. Error text below input.
• Use gap-2 for input blocks. Full-width inputs on mobile.

3D. AI Tells — Forbidden Patterns

Strictly avoid unless the brand's identity explicitly calls for them:

Visual:

• No neon/outer glows. Use inner borders or tinted shadows.
• No pure black (#000000). Use off-black, zinc-950, or the brand's darkest neutral.
• No oversaturated accents. Desaturate to blend with neutrals.
• No gradient text on large headers.

Layout:

• No generic 3-column card rows. Use 2-column zig-zag, asymmetric grid, or horizontal scroll.
• Pixel-perfect spacing. No floating elements with awkward gaps.

Content (the "Jane Doe" effect):

• No generic names: "John Doe", "Sarah Chen", "Jack Su" are banned. Invent realistic names.
• No generic avatars. Use creative photo placeholders or styled initials.
• No fake round numbers: 99.99%, 50%, 1234567. Use organic data: 47.2%, +1 (312) 847-1928.
• No startup slop names: "Acme", "Nexus", "SmartFlow". Invent contextual brand names.

Resources:

• No random placeholder images (picsum.photos, placeholder.com, via.placeholder). Use the curated assets from Phase 1E. If Phase 1E was skipped, use SVG placeholder illustrations styled with brand tokens — never random stock photos.
• Unsplash and Pexels direct image URLs (images.unsplash.com/photo-*, images.pexels.com/photos/*) are allowed and preferred. The old source.unsplash.com redirect URLs are banned (they break). Always use the stable direct format with dimension parameters.
• shadcn/ui allowed but NEVER in default state. Customize radii, colors, and shadows using brand tokens.

3E. Performance Guardrails

• Apply grain/noise filters only on fixed inset-0 z-50 pointer-events-none pseudo-elements, never on scrolling containers.
• Never animate top, left, width, or height. Animate exclusively via transform and opacity.
• Never use arbitrary z-50 or z-10. Z-indexes only for systemic layers (sticky nav, modals, overlays).
• Wrap CPU-heavy perpetual animations in their own Client Components. Memoize with React.memo.

PHASE 4: DESIGN LAYERS

4A. Animation Personality

Motion should feel like the brand, not like a generic animation library. Map the brand's personality to an animation archetype, then apply its characteristics to every moving element.

Archetypes:

Micro-interaction rules (apply based on MOTION_INTENSITY):

MOTION_INTENSITY 1-3 (Static):

• No automatic animations. CSS :hover and :active states only.
• Transitions limited to color and opacity changes.

MOTION_INTENSITY 4-6 (Fluid):

• Page load: staggered fade-in using the archetype's easing.
• Hover states: subtle scale/translate matching brand character.
• Page transitions: crossfade or slide using archetype timing.
• Use animation-delay cascades. Focus on transform and opacity only.

MOTION_INTENSITY 7-10 (Choreographed):

• Scroll-triggered reveals using Framer Motion or Intersection Observer.
• Magnetic buttons (pull toward cursor). Use useMotionValue and useTransform — NEVER useState for continuous animations.
• Perpetual micro-interactions: breathing status dots, floating elements, shimmer effects.
• Spring physics: type: "spring" with archetype-specific stiffness/damping.
• Staggered orchestration: staggerChildren or CSS animation-delay: calc(var(--index) * 80ms).
• Layout animations: Framer Motion layout and layoutId for smooth re-ordering.

Critical performance rules for animations:

• NEVER mix GSAP, Three.js/R3F, or Framer Motion in the same component tree. Each animation system gets its own isolated Client Component.
• staggerChildren parent and children must be in the same Client Component tree.
• Perpetual animations must be isolated in their own memoized Client Components.
• All useEffect animations must have cleanup functions.
• Respect prefers-reduced-motion: wrap all motion in @media (prefers-reduced-motion: no-preference) or Framer's useReducedMotion.

4B. Accessibility Layer

Non-negotiable baseline for all output. These are not optional enhancements.

Color & Contrast:

• All text must meet WCAG 2.1 AA contrast ratios (4.5:1 for body text, 3:1 for large text).
• Cross-reference brand tokens against contrast requirements during token generation. Flag conflicts early.
• Never rely on color alone to convey information. Pair with icons, text, or patterns.

Keyboard Navigation:

• All interactive elements must be keyboard accessible (Tab, Enter, Escape, Arrow keys where appropriate).
• Visible focus indicators on every focusable element. Style with brand accent color, not browser default.
• Logical tab order matching visual layout.

Semantic HTML & ARIA:

• Use semantic elements (nav, main, article, section, aside, header, footer) before reaching for ARIA.
• All images need meaningful alt text or aria-hidden="true" for decorative images.
• Form inputs linked to labels via htmlFor/id.
• Dynamic content changes announced via aria-live regions.

Motion Accessibility:

• All animations wrapped in prefers-reduced-motion checks.
• Provide static alternatives for motion-dependent interfaces.
• No auto-playing video or animation without user control.

4C. Responsive Brand Consistency

The brand must feel like itself at every viewport width. This goes beyond "stack on mobile."

Typography Scale Compression:

• Desktop text-6xl headlines don't just shrink — they rebalance. Use clamp() for fluid type: font-size: clamp(2rem, 5vw, 4.5rem).
• Maintain the same font pairing across breakpoints. Never swap display fonts for system fonts on mobile.

Logo Behavior:

• Define min-width for the logo (below which it switches to an icon mark if available).
• Maintain exclusion zone proportional to viewport.

Spacing Rhythm Contraction:

• Desktop section gaps compress by ~40% on mobile (not 50% — maintain hierarchy).
• Component internal padding reduces by one step on the spacing scale.
• Keep the base spacing unit consistent (if 8px on desktop, 8px on mobile — just fewer units).

Animation Degradation:

• At < 768px, reduce MOTION_INTENSITY by 2 levels automatically.
• Disable parallax, magnetic effects, and complex scroll animations.
• Keep simple transitions (fade, slide) for brand continuity.

Layout Transformation Rules:

• Multi-column layouts collapse to single column at < 768px with w-full px-4 py-8.
• Navigation transforms: horizontal nav → hamburger or bottom sheet. Branded transition.
• Asymmetric layouts (DESIGN_VARIANCE 4-10) must fall back to strict single-column on mobile. No horizontal scrolling.

4D. Component Theming

Systematic methodology for skinning component libraries to match brand tokens.

shadcn/ui Skinning: Map brand tokens to shadcn's CSS variables:

:root {
  --radius: var(--brand-radius-md);
  --primary: var(--brand-primary);
  --primary-foreground: /* contrast-safe text on brand-primary */;
  --secondary: var(--brand-secondary);
  --accent: var(--brand-accent);
  --background: var(--brand-surface);
  --foreground: var(--brand-neutral-900);
  --muted: var(--brand-neutral-100);
  --muted-foreground: var(--brand-neutral-500);
  --border: var(--brand-neutral-200);
}

• Override default shadows with brand shadow tokens.
• Adjust border-radius to match brand shape tokens.
• Customize focus rings to use brand accent.

Dark Mode Implementation:

• Use the brand-specific dark mode mapping from Phase 2 tokens.
• Brand accent color stays recognizable (may need slight luminance adjustment).
• Test every component state in both modes before shipping.

PHASE 5: OPTIONAL EXTENSIONS

These modules activate only when explicitly requested or when the project type naturally calls for them.

5A. Bento Paradigm (activate for SaaS feature sections)

Modern SaaS feature grid with perpetual micro-animations.

Aesthetic: High-end, minimal, functional. Background #f9fafb (or brand equivalent). Cards are white with 1px border at border-slate-200/50. Use rounded-[2.5rem] for major containers. Apply diffusion shadow: shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)].

Animation engine: All cards contain perpetual micro-interactions:

• Spring physics: type: "spring", stiffness: 100, damping: 20
• Layout transitions via layout and layoutId props
• Every card has an infinite loop state (pulse, typewriter, float, carousel)
• Wrap in <AnimatePresence>, memoize with React.memo

Five card archetypes:

1. Intelligent List — auto-sorting items using layoutId swaps
2. Command Input — typewriter cycling through prompts with blinking cursor
3. Live Status — breathing indicators with overshoot notification badges
4. Data Stream — seamless horizontal carousel (x: ["0%", "-100%"])
5. Contextual UI — staggered text highlight with floating action toolbar

Labels and descriptions sit outside and below cards. Use generous p-8 or p-10 inside.

5B. Creative Arsenal (reference library)

Pull from this library of advanced concepts when standard patterns feel insufficient. Each concept should be implemented using brand tokens and the selected animation archetype.

Hero Paradigms: Asymmetric splits, text left / asset right, subtle image fades into background. No centered text over dark image.

Navigation: Magnetic buttons, dynamic island morphing, mega menu staggered reveals, dock magnification, contextual radial menus.

Cards & Containers: Parallax tilt tracking mouse, spotlight border illumination, glassmorphism with inner refraction (border-white/10 + shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]), holographic foil, morphing modal (button expands into dialog).

Scroll Animations: Sticky scroll stacking, horizontal scroll hijack, zoom parallax, SVG path drawing on scroll, liquid swipe transitions. Use GSAP ScrollTrigger or Framer Motion — never window.addEventListener('scroll').

Typography Effects: Kinetic marquee, text mask reveal over video, text scramble decode, circular text path, gradient stroke animation.

Micro-Interactions: Particle explosion buttons, skeleton shimmer, directional hover-aware fills, ripple clicks, mesh gradient backgrounds, animated SVG line drawing.

5C. Scroll Animation Module (activate for editorial/storytelling sites)

For narrative-driven pages where scroll position controls the story.

Use GSAP with ScrollTrigger exclusively — never Framer Motion for scroll-driven sequences. Wrap in strict useEffect cleanup blocks. Never mix with Framer Motion in the same component tree.

Patterns: sticky scroll sequences, scroll-hijacked horizontal pans, parallax layering, scroll-progress SVG drawing, frame-by-frame animation tied to scrollbar position.

5D. 3D Animation Module (activate when explicitly requested or for product showcases, creative portfolios, immersive hero scenes)

Adds depth and dimensionality to the interface. Split into two tiers based on complexity.

Tier 1: CSS 3D (no dependencies)

Lightweight 3D effects using native CSS. These can be used at MOTION_INTENSITY 7+ without adding any bundle weight.

• Perspective card tilt — mouse-tracking rotateX/rotateY on hover using perspective and transform-style: preserve-3d. Track mouse position with useMotionValue (Framer Motion) or a lightweight mousemove handler. Apply will-change: transform on hover only.
• Depth layers — parallax-like stacking using translateZ() within a perspective container. Creates layered depth without scroll binding.
• Card flip — rotateY(180deg) with backface-visibility: hidden for reveal interactions (pricing toggles, feature comparisons, team bios).
• 3D button press — combine translateZ, rotateX, and brand-tinted box-shadow shifts to create physical push depth on :active.

CSS 3D implementation rules:

• Always set perspective on the parent container (800-1200px typical range). Never on the animated element itself.
• Use transform-style: preserve-3d only on direct parent of 3D-transformed children.
• Keep rotation angles subtle: ±5-15° for tilt effects, 180° only for full flips.
• Disable on mobile (< 768px) — fall back to flat 2D transitions.

Tier 2: React Three Fiber (opt-in, heavy)

For immersive 3D scenes. Only use when the project explicitly needs a 3D experience — product configurators, interactive globes, particle hero backgrounds, 3D model showcases.

Stack: @react-three/fiber + @react-three/drei. Check package.json before importing. If missing, output install commands:

npm install three @react-three/fiber @react-three/drei

Scene patterns:

Implementation rules:

• Every R3F <Canvas> must live in its own isolated Client Component. Never nest a Canvas inside a Framer Motion AnimatePresence tree.
• Set <Canvas frameloop="demand"> for static/interactive scenes (renders only on interaction). Use frameloop="always" only for continuous animation.
• Always provide a fallback for when WebGL is unavailable: wrap the Canvas in an error boundary that renders a static image or CSS alternative.
• Limit draw calls. One scene should have fewer than 50 meshes. Use <Instances> or <InstancedMesh> for repeated geometry.
• Compress 3D models: .glb format, Draco compression, textures under 1024x1024. Use <useGLTF.preload> for async loading with a branded skeleton loader.
• Lighting setup: one ambient (intensity: 0.4), one directional key light, optional <Environment preset="studio">. Tint lights toward brand temperature (warm or cool).
• Camera: fov: 45 for product shots (less distortion), fov: 75 for immersive scenes. Use <PresentationControls> over <OrbitControls> for guided user interaction.

Performance guardrails for 3D:

• Mobile (< 768px): disable R3F scenes entirely. Replace with a static image or CSS 3D fallback from Tier 1. Mobile GPUs cannot reliably handle WebGL + the rest of the page.
• Set dpr={[1, 1.5]} on the Canvas to cap pixel ratio. Never render at full retina (dpr={2}) for complex scenes.
• Lazy load the Canvas component: const Scene = dynamic(() => import('./Scene'), { ssr: false }). 3D scenes must never block initial page load or SSR.
• Dispose of geometries, materials, and textures in cleanup. Use drei's useGLTF (auto-disposes) over raw Three.js loaders.
• Never run useFrame callbacks that allocate objects. Pre-allocate vectors and quaternions outside the loop.
• prefers-reduced-motion: replace animated 3D scenes with a static camera angle. Keep the visual but stop the motion.

Brand integration:

• Materials should reference brand tokens. Map --brand-primary to meshStandardMaterial color. Use --brand-surface for environment background.
• Match the lighting mood to the animation archetype: warm and soft for Refined, high-contrast for Technical, colorful and dynamic for Energetic.
• 3D scenes must feel like a natural part of the page, not a tech demo. The surrounding 2D layout, typography, and spacing should flow seamlessly into and out of the 3D section.

PHASE 6: REFINEMENT MODES

These modes operate on existing code without re-running the full Phase 1-5 pipeline. Use them when the user has already-built frontend code and wants to improve a specific aspect. Each mode reads the current codebase, identifies issues within its domain, and applies targeted fixes using HyperBlue's design rules and any existing brand tokens.

How refinement modes activate: The user asks to fix, improve, audit, or refine a specific design dimension on code that already exists. They may reference the mode name directly (e.g., "run a typeset pass") or describe the intent (e.g., "the spacing feels off" → Arrange mode).

Brand token awareness: If brand tokens were established in a prior build (look for CSS custom properties like --brand-*, Tailwind theme extensions, or a design token file), refinement modes use them. If no tokens exist, the mode infers brand direction from the existing code's colors, fonts, and spacing patterns, and applies corrections consistent with what's already there — it does not invent a new brand.

6A. Review

Full design audit against HyperBlue's rules. Scans the codebase and produces a structured report — does not auto-fix unless asked.

What it checks:

• Anti-slop: Flags AI tells from Phase 3D — generic names ("John Doe"), fake round numbers ("99.99%"), AI purple gradients, placeholder images (picsum.photos), banned copy patterns ("Unleash", "Seamless"), Inter font in premium contexts, centered hero bias, generic 3-column card grids.
• Brand consistency: Hardcoded colors instead of tokens, mixed warm/cool neutrals, inconsistent font stacks, components that escaped the brand system.
• Accessibility: Contrast ratio failures, missing alt text, missing keyboard focus indicators, animations without prefers-reduced-motion checks, form inputs without labels.
• Performance: Animations on top/left/width/height instead of transform/opacity, h-screen instead of min-h-[100dvh], missing useEffect cleanup on animations, non-isolated Client Components.
• States: Missing loading skeletons, empty states, or error states on data-driven components.

Output format: A numbered list of findings grouped by severity (critical → warning → suggestion), each with the file path, line reference, the issue, and a concrete fix recommendation. The user can then ask to fix all, fix a category, or fix individually.

6B. Typeset

Targeted typography refinement. Fixes font selection, scale, hierarchy, measure, and rhythm without touching layout or color.

What it fixes:

• Font selection: Flags Inter/system fonts in premium or creative contexts. Suggests brand-appropriate alternatives (Geist, Satoshi, Cabinet Grotesk, Plus Jakarta Sans, etc.) based on the existing design's personality. Does not change fonts if the brand intentionally uses them (Brand Override Rule).
• Type scale: Ensures a consistent, intentional scale. For app UIs, applies a fixed scale (text-xs through text-6xl with defined steps). For marketing/content pages, applies fluid typography using clamp() (e.g., font-size: clamp(2rem, 5vw, 4.5rem)).
• Hierarchy depth: Checks that there are at least 3 distinct visual levels (display → heading → body) with clear size/weight differentiation. Flags headings that are too similar in size.
• Measure: Ensures body text has max-w-[65ch] or equivalent to prevent overly wide lines.
• Line height & tracking: Display text gets tracking-tighter leading-none. Body text gets leading-relaxed. Flags mismatches.
• Font loading: Checks that custom fonts are properly loaded (Next.js next/font, @font-face, or Google Fonts link) and that font-display: swap is set to prevent FOIT.

6C. Arrange

Layout and spacing refinement. Fixes alignment, whitespace rhythm, grid structure, and responsive behavior.

What it fixes:

• Spacing consistency: Identifies mixed spacing values (e.g., p-4 next to p-5 next to p-[18px]) and normalizes to a consistent scale. Ensures section gaps follow a rhythm (e.g., py-16 md:py-24 consistently, not random values per section).
• Grid structure: Replaces complex flexbox percentage math (w-[calc(33%-1rem)]) with clean CSS Grid. Ensures multi-column layouts use grid-cols-* with consistent gap-*.
• Container discipline: Checks that content is properly contained (max-w-7xl mx-auto or equivalent). Flags content that bleeds or floats without intent.
• Responsive collapse: Ensures all multi-column layouts collapse to w-full px-4 py-8 below 768px. Flags horizontal scrolling on mobile. Checks that asymmetric layouts fall back to single-column.
• Alignment audit: Detects mixed alignment within sections (left-aligned heading over centered content, or vice versa) and normalizes to a deliberate alignment strategy.
• Density calibration: If the user specifies a VISUAL_DENSITY target, adjusts padding, gaps, and whitespace to match that level. Low density (1-3) gets generous section gaps; high density (8-10) gets tight padding and border separators instead of cards.

6D. Palette

Color refinement. Fixes brand consistency, contrast, dark mode, and semantic color usage.

What it fixes:

• Token extraction: If the codebase uses hardcoded hex/rgb values, extracts them into a cohesive token system (--brand-primary, --brand-neutral-*, etc.) and replaces inline values with token references.
• Palette coherence: Detects mixed color temperatures (warm and cool grays in the same interface) and normalizes to one direction. Ensures accent colors are under 80% saturation.
• AI color purge: Flags AI purple/blue gradient aesthetics, neon outer glows, and oversaturated accents. Replaces with brand-appropriate alternatives.
• Contrast compliance: Tests all text/background combinations against WCAG 2.1 AA ratios (4.5:1 body, 3:1 large text). Flags failures with the exact contrast ratio and suggests the nearest compliant shade.
• Dark mode: If dark mode exists, checks that it's brand-specific (not simple inversion). Warm brands should use warm charcoal backgrounds, corporate brands navy, tech brands true dark. If dark mode doesn't exist and the user wants it, generates the full mapping.
• Semantic colors: Ensures success, warning, error, info colors exist and don't clash with the brand palette.

6E. Animate

Motion refinement. Adds, fixes, or calibrates animations to match a brand personality archetype.

What it fixes:

• Archetype alignment: Determines the appropriate animation archetype (Refined, Energetic, Technical, Editorial) from the existing brand direction, then checks that all motion uses consistent easing, duration, and character. Flags mismatches (e.g., bouncy spring animations on a luxury brand).
• Motion intensity calibration: If the user specifies a MOTION_INTENSITY target, adds or removes animations to match. Low intensity (1-3) strips all auto-animations, leaving only hover/active states. High intensity (7-10) adds scroll-triggered reveals, staggered orchestration, and micro-interactions.
• Performance fixes: Replaces animations on top/left/width/height with transform/opacity equivalents. Isolates perpetual animations into their own memoized Client Components. Adds useEffect cleanup to all animation hooks. Removes window.addEventListener('scroll') in favor of Intersection Observer or Framer Motion.
• Accessibility: Wraps all motion in prefers-reduced-motion checks. Adds static fallbacks for motion-dependent interactions.
• Mobile degradation: Ensures complex animations (parallax, magnetic effects, scroll hijacking) are disabled below 768px. Keeps simple transitions for brand continuity.
• Library isolation: Flags components that mix GSAP, Framer Motion, and/or React Three Fiber in the same component tree. Separates into isolated Client Components.

6F. Harden

State completeness refinement. Adds missing UI states and edge cases that make the interface feel production-ready.

What it fixes:

• Loading states: Adds skeleton loaders matching component dimensions (not generic spinners). Skeleton shimmer color matches brand tokens.
• Empty states: Adds branded messaging and illustration/icon for empty data views. Uses the established brand voice, not "No data found."
• Error states: Adds inline, specific error messages for form validation and data fetching failures. Uses brand voice and helpful recovery instructions, not "Something went wrong."
• Tactile feedback: Adds :active press effects (-translate-y-[1px] or scale-[0.98]) to interactive elements that lack them.
• Form completeness: Ensures labels above inputs, helper text in markup, error text below inputs, proper htmlFor/id linking, and full-width inputs on mobile.
• Placeholder data: Replaces generic names, round numbers, and stock placeholder content with realistic, organic alternatives. "John Doe" → "Marcus Reilly", "99.99%" → "47.2%", "$1,234" → "$1,847.30".

6G. Accessibility

Dedicated WCAG 2.1 AA compliance pass. Overlaps with the accessibility checks in Review mode but goes deeper and auto-fixes.

What it fixes:

• Contrast: Tests every text/background pair and adjusts colors to meet AA ratios while staying as close to the original brand color as possible.
• Keyboard navigation: Adds tabIndex, focus indicators styled with brand accent (not browser default), and logical tab order. Ensures all interactive elements respond to Enter, Escape, and Arrow keys where appropriate.
• Semantic HTML: Replaces generic <div> structures with semantic elements (nav, main, article, section, aside, header, footer). Adds role attributes only where semantic elements aren't sufficient.
• ARIA: Adds aria-label to icon-only buttons, aria-live regions to dynamic content, aria-expanded to toggles and accordions, and aria-describedby linking error messages to form inputs.
• Images: Adds meaningful alt text to content images. Adds aria-hidden="true" to decorative images. Flags missing alt attributes.
• Motion: Wraps every animation in prefers-reduced-motion media queries or Framer Motion's useReducedMotion. Ensures auto-playing video has user controls and pause capability.
• Color independence: Flags any UI that relies on color alone to convey information (status indicators, form validation, charts) and adds secondary indicators (icons, text, patterns).

PRE-FLIGHT CHECKLIST

Evaluate every output against this matrix before delivering:

Brand Alignment:

• Are brand tokens used for all colors, not hardcoded values?
• Does the typography use the brand's font stack?
• Does microcopy match the established brand voice?
• Would the brand team recognize this as theirs?

Technical Quality:

• Is global state used appropriately (not arbitrarily)?
• Do full-height sections use min-h-[100dvh] not h-screen?
• Do useEffect animations have cleanup functions?
• Are interactive components properly isolated as Client Components?
• Are dependencies verified against package.json?

Accessibility:

• Do all text elements meet WCAG AA contrast ratios?
• Are all interactive elements keyboard accessible?
• Do animations respect prefers-reduced-motion?
• Are images properly labeled with alt text?

Responsiveness:

• Does mobile layout collapse to single column with w-full px-4?
• Is typography fluid using clamp() or responsive classes?
• Are complex animations disabled below 768px?
• Does the logo behave correctly at small sizes?

Anti-Slop:

• Are loading, empty, and error states provided?
• Is placeholder data realistic and organic (not "John Doe" or "99.99%")?
• Are cards used only when elevation conveys hierarchy?
• Does the output look like it was designed for this specific brand?

Assets:

• Are all images contextually relevant to the brand and industry (not random stock)?
• Do image URLs use stable direct formats (images.unsplash.com/photo-* or images.pexels.com/photos/*)?
• Is photographic style consistent across the page (same tone, lighting, mood)?
• Do <video> elements have poster attributes and respect prefers-reduced-motion?
• Is attribution included as code comments for all sourced assets?

DIAL TECHNICAL REFERENCE

DESIGN_VARIANCE (1-10)

1-3 (Predictable): Flexbox justify-center, symmetrical 12-column grids, equal paddings. Safe, conventional layouts.

4-7 (Offset): Overlapping elements with margin-top: -2rem, varied image aspect ratios (4:3 next to 16:9), left-aligned headers over centered data. Interesting but controlled.

8-10 (Asymmetric): Masonry layouts, CSS Grid with fractional units (grid-template-columns: 2fr 1fr 1fr), bold empty zones (padding-left: 20vw). Striking and distinctive.

MOBILE OVERRIDE: For levels 4-10, any asymmetric layout above md: must collapse to strict single-column (w-full, px-4, py-8) below 768px.

MOTION_INTENSITY (1-10)

1-3 (Static): No automatic animations. :hover and :active only.

4-7 (Fluid CSS): transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1). Cascade delays for load-ins. transform and opacity only. will-change: transform sparingly.

8-10 (Choreographed): Scroll-triggered reveals, complex parallax, Framer Motion hooks, spring physics. Never window.addEventListener('scroll').

VISUAL_DENSITY (1-10)

1-3 (Gallery): Generous whitespace. Huge section gaps. Everything feels expensive and clean.

4-7 (App): Standard web app spacing. Balanced density.

8-10 (Cockpit): Tight padding. No card boxes — 1px lines only. Everything packed. Use monospace (font-mono) for all numbers.

BRAND_FIDELITY (1-10)

1-3 (Exploratory): Brand colors and fonts as starting point. Free creative interpretation.

4-7 (Guided): Brand system followed, creative latitude in layout and interaction design.

8-10 (Strict): Match reference screenshots and brand guidelines as closely as possible. Minimal creative deviation.