Component Builder

Before Building (Design Intent)

Before writing code, answer these questions:

1. •

   What emotion should this evoke?

   • •Trust/stability → Blue palette, ample whitespace, professional typography
   • •Urgency/action → Red/orange accents, bold CTAs, high contrast
   • •Calm/wellness → Soft colors, rounded corners, generous spacing
   • •Innovation/tech → Geometric shapes, gradients, subtle animations
2. •

   What's the ONE thing users must notice first?

   • •If everything is important, nothing is. Pick ONE focal point.
   • •Nielsen Norman eye-tracking: Users follow F-pattern on text-heavy, Z-pattern on visual pages
   • •Place primary CTA at natural eye-flow endpoints
3. •

   What makes this NOT generic?

   • •shadcn/ui has 66k+ GitHub stars — everyone uses the defaults
   • •Customize: colors, spacing, typography, border-radius, shadows
   • •Add micro-interactions that match brand personality
4. •

   Mobile-first or desktop-first?

   • •82.9% of landing page visitors use mobile (Unbounce 2024)
   • •Mobile users have 8% lower conversion — design to close that gap

Reference Loading

Step 1: Design Direction (Smart Approach)

For full pages or when context is unclear:

1. •Read ../../references/design-direction/personality-framework.md (dynamic framework)
2. •Analyze user's request for context clues
3. •Ask 1-3 questions ONLY if critical info missing (see framework)
4. •Derive design tokens from answers

For single components: Skip questions, infer from context or use defaults.

If project has .claude/forgex.local.md: Use stored preferences, don't re-ask.

Step 2: Component References

../../references/components/cross-reference.md

Library Catalog (after selection)

Available catalog files in ../../references/components/catalogs/:

• •shadcn-ui.json - shadcn/ui components
• •radix-ui.json - Radix primitives
• •magic-ui.json - Magic UI animations
• •aceternity-ui.json - Aceternity effects
• •page-ui.json - Page UI blocks
• •flowbite.json - Flowbite components
• •mantine.json - Mantine library
• •heroui.json - HeroUI components
• •daisyui.json - DaisyUI themes

Library Selection

GitHub stars and NPM downloads from State of React 2024

Page Mode

For full page requests ("build a landing page"):

Section Flow by Site Type

SaaS median CVR from Unbounce 2024 benchmark report

Visual Hierarchy Principles

• •Z-Pattern: For visual-driven pages (hero, landing). Eye moves: top-left → top-right → diagonal → bottom-right
• •F-Pattern: For text-heavy pages (features, docs). Eye scans: top bar → second horizontal → left column down
• •Single CTA Rule: Pages with 1 CTA convert 13.5% vs 10.5% for 5+ CTAs (Unbounce, 18,639 pages analyzed)

Touch Target Requirements

Research-backed minimums for mobile:

Spacing: Minimum 8dp between targets (Material Design)

// ✅ Correct: Adequate touch target
<button className="min-h-[44px] min-w-[44px] p-3">

// ❌ Wrong: Too small
<button className="p-2">  // Only ~32px

Anti-patterns (Research-Backed)

Output Checklist

Before delivering, verify:

• • Touch targets ≥44px with 8px spacing
• • Single clear CTA per viewport
• • dark: variants for all colors
• • aria-label on interactive elements
• • Responsive breakpoints (sm:, md:, lg:)
• • Hover, focus, active, disabled states
• • Loading state for async operations
• • Real copy, not placeholders

Redesign Mode

When user asks to redesign/rebuild/revamp existing UI:

CRITICAL: RUN AUDIT FIRST!

DO NOT start redesigning without understanding the current state.

> "Before I redesign, let me audit your current site to understand
> what's working, what's broken, and what to preserve..."

Step 0: Comprehensive Audit (MANDATORY for Redesigns)

Run the design-audit skill mindset:

1. •

   Spawn ALL 5 validation agents on current design:

   • •design-validator
   • •accessibility-checker
   • •mobile-validator
   • •dark-mode-checker
   • •copy-analyzer
2. •

   Analyze what's WORKING (preserve these):

   • •Brand colors that work
   • •Content that converts
   • •Patterns users recognize
3. •

   Identify what's BROKEN (fix these):

   • •Accessibility issues
   • •Conversion blockers
   • •Mobile problems
   • •Dark mode issues
4. •

   Check SEO (don't break in redesign!):

   • •Current heading hierarchy
   • •Meta tags
   • •URL structure

Step 1: Present Audit Findings

> "I've analyzed your current site. Here's what I found:
>
> ✓ WORKING (will preserve):
> - [List items]
>
> ✗ ISSUES (will fix):
> - [List issues with severity]
>
> Based on this, would you like me to:
> 1. **Quick Fixes** - Fix issues, keep design (fastest)
> 2. **Refresh** - Modernize while keeping brand (recommended)
> 3. **Full Redesign** - New direction entirely"

Step 2: Execute Based on Choice

If Quick Fixes:

• •Fix critical issues only
• •Keep existing design
• •Fast turnaround

If Refresh:

• •Maintain brand personality
• •Apply 2026 trends where appropriate
• •Fix all identified issues
• •Improve without changing direction

If Full Redesign:

• •Load personality-framework.md
• •Ask differentiation questions
• •Generate new design direction
• •Apply full pipeline

Step 3: After Redesign

Always check:

• • SEO not broken (headings, meta preserved)
• • All previous functionality works
• • Accessibility improved from original
• • Copy improved (run copy-optimizer)
• • Mobile experience better
• • Dark mode works properly

Redesign Checklist

Before delivering redesign:

• • Ran audit FIRST
• • Preserved content/copy unless asked to change
• • Maintained brand colors unless new direction
• • Improved accessibility from original
• • Added/fixed dark mode support
• • Better mobile experience than original
• • Kept working functionality intact
• • SEO structure preserved or improved

MANDATORY PIPELINE (DO NOT SKIP)

This skill is part of a multi-step pipeline. You MUST follow these steps:

PHASE 1: Pre-Build (MANDATORY)

Before writing ANY code, you MUST load ALL relevant references:

1. •

   Design Direction & Personality:

   code

   READ: ../../references/design-direction/personality-framework.md
   READ: ../../references/psychology/visual-hierarchy.md
   READ: ../../references/psychology/trust-signals.md
   READ: ../../references/psychology/cognitive-biases.md
   

2. •

   2026 TRENDS (MANDATORY for modern design):

   code

   READ: ../../references/trends/index.md
   READ: ../../references/trends/colors-gradients.md
   READ: ../../references/trends/layouts.md
   READ: ../../references/trends/glassmorphism.md
   

   Apply trends like: Dopamine palettes, Bento grids, Glassmorphism, Kinetic typography

3. •

   Copy & Psychology (for ANY text content):

   code

   READ: ../../references/copywriting/headline-formulas.md
   READ: ../../references/copywriting/cta-patterns.md
   READ: ../../references/copywriting/value-propositions.md
   READ: ../../references/psychology/aida-framework.md
   READ: ../../references/psychology/pas-framework.md
   

4. •

   Animation & Motion (for ANY interactive elements):

   code

   READ: ../../references/animation/motion-principles.md
   READ: ../../references/animation/micro-interactions.md
   

   Apply micro-interactions: button feedback (100-200ms), page transitions, hover states

5. •

   Accessibility & Mobile:

   code

   READ: ../../references/accessibility/wcag-checklist.md
   READ: ../../references/mobile/touch-targets.md
   READ: ../../references/mobile/thumb-zone.md
   

6. •

   DESIGN SYSTEM FOUNDATIONS (NEW):

   code

   READ: ../../references/design-system/icons.md
   READ: ../../references/design-system/shadows-elevation.md
   READ: ../../references/design-system/spacing-scale.md
   READ: ../../references/design-system/border-radius.md
   READ: ../../references/design-system/buttons.md
   READ: ../../references/design-system/component-states.md
   

   Apply:

   • •Consistent shadow scale (xs → 2xl)
   • •4px spacing grid
   • •Radius by personality (corporate=4-8px, friendly=12-24px)
   • •All 8 component states (default, hover, focus, active, disabled, loading, error, success)
   • •Proper icon sizing and accessibility
7. •

   Color Palette GENERATION (NOT stereotypes):

   code

   READ: ../../references/theming/palette-generation.md
   READ: ../../references/theming/color-psychology.md
   

   DO NOT just pick "blue for SaaS". Generate a UNIQUE palette based on:

   • •Brand values and differentiation
   • •Target emotional response
   • •Competitor analysis (be different)
   • •2026 color trends (Dopamine vs Nature Distilled)
8. •

   Check for project preferences:

   • •If .claude/forgex.local.md exists, read it
   • •Use stored personality/brand settings
   • •If no preferences, ASK differentiation questions

CONTEXT GATHERING: AI-Driven Approach

Read ../../references/shared/ai-orchestration.md for full guidelines.

Principle: INFER before asking. Ask only what's critical.

TRY TO INFER FROM:

• •User's request ("AI startup" → tech, innovation, likely B2B or developer-focused)
• •Existing code (read files first → understand current style, colors, patterns)
• •Conversation context (what have they already told you?)
• •Project preferences (check .claude/forgex.local.md)

ONLY ASK WHEN:

• •Critical information is genuinely missing
• •The answer significantly changes your approach
• •You can't reasonably infer it

USEFUL QUESTIONS (use judgment on which to ask):

DON'T ASK:

• •"What industry?" (if they said it)
• •"What colors?" (unless they want specific)
• •Generic questions you can infer

PHASE 2: Build

• •Build components following loaded references
• •Apply psychology principles to visual hierarchy
• •Use conversion-optimized copy patterns
• •Ensure touch targets ≥44px
• •Include dark: variants for all colors

PHASE 3: Post-Build (MANDATORY)

After building, you MUST:

1. •

   Self-check the output checklist (from Output Checklist section above)

2. •

   Invoke copy-optimizer skill for headline/CTA review:

   "Let me optimize the copy using the copy-optimizer skill..."

   • •Apply AIDA/PAS framework to headlines
   • •Check CTAs against friction word list
   • •Verify benefit-focused language
3. •

   Run FULL validation before completing:

   "Let me validate this using all Forgex validation systems..."

   A. Launch 5 agents in parallel using Task tool:

   • •design-validator - Visual hierarchy, consistency, polish
   • •accessibility-checker - WCAG 2.1 AA compliance
   • •mobile-validator - Touch targets, thumb zones, readability
   • •dark-mode-checker - Anti-pattern detection
   • •copy-analyzer - Headlines, CTAs, psychology triggers

   B. Check React/Next.js performance (if applicable):

   • •Invoke react-best-practices skill
   • •Check for waterfalls, bundle issues, server-side optimization
   • •Apply 57 performance rules

   C. Check against Web Design Guidelines:

   • •Invoke web-design-guidelines skill
   • •Validate against 100+ UI compliance rules
   • •Check semantic HTML, keyboard navigation, screen reader compatibility
4. •

   Fix ALL issues before marking complete:

   • •All 5 agents must score ≥80
   • •React performance issues fixed
   • •Web design guideline violations resolved
   • •Re-run validation after fixes

PHASE 4: Completion

Only complete when ALL of these are true:

References & Context:

• • All 20+ Phase 1 references were loaded
• • 2026 trends were considered and applied where appropriate
• • Differentiation questions answered (or context inferred)
• • UNIQUE color palette generated (not stereotype)

Psychology & Copy:

• • Copy optimized with AIDA/PAS/JTBD framework
• • Headlines are benefit-focused with specifics
• • CTAs have no friction words, use first-person
• • Psychology triggers applied (social proof, urgency, authority)

Design Quality:

• • All 5 validation agents pass (≥80 score)
• • React best practices checked (if applicable)
• • Web design guidelines validated
• • Animation/motion principles applied to interactions
• • Micro-interactions have 100-200ms feedback

Accessibility & Mobile:

• • Touch targets verified ≥44px
• • Thumb zone placement for mobile CTAs
• • WCAG 2.1 AA compliance verified
• • prefers-reduced-motion respected for animations

Theming:

• • Dark mode support with proper anti-patterns avoided
• • 3-tier token architecture (if applicable)
• • No pure black (#000) backgrounds
• • Saturated colors desaturated for dark mode

Design System Foundations:

• • Icons from consistent library (Lucide/Phosphor/Heroicons)
• • Icon buttons have aria-label
• • Icons sized correctly (16-24px for UI)
• • Shadows use scale (shadow-xs → shadow-2xl)
• • Spacing uses 4px grid consistently
• • Border radius matches brand personality
• • All 8 states for interactive elements:
  • • Default, Hover, Focus, Active
  • • Disabled, Loading, Error, Success
• • Buttons follow size scale (height 32-56px)
• • Loading states with spinners for async
• • Error states with clear messages
• • Empty states with helpful CTAs

PIPELINE ENFORCEMENT

DO NOT:

• •Skip reference loading ("I'll just build quickly...")
• •Skip copy optimization ("The text looks fine...")
• •Skip validation ("It should be good...")
• •Complete with validation failures

ALWAYS:

• •Load ALL mandatory references before building
• •Apply psychology frameworks to copy
• •Run full validation pipeline
• •Fix issues before completion