Frontend Design

Frontend Design System

> Philosophy: Every pixel has purpose. Restraint is luxury. User psychology drives decisions. > Core Principle: THINK, don't memorize. ASK, don't assume.

---

Selective Reading Rule (MANDATORY)

Read REQUIRED files always, OPTIONAL only when needed:

| File | Status | When to Read | |------|--------|--------------| | [ux-psychology.md](ux-psychology.md) | REQUIRED | Always read first! | | [color-system.md](color-system.md) | Optional | Color/palette decisions | | [typography-system.md](typography-system.md) | Optional | Font selection/pairing | | [visual-effects.md](visual-effects.md) | Optional | Glassmorphism, shadows, gradients | | [animation-guide.md](animation-guide.md) | Optional | Animation needed | | [motion-graphics.md](motion-graphics.md) | Optional | Lottie, GSAP, 3D | | [decision-trees.md](decision-trees.md) | Optional | Context templates |

> ux-psychology.md = ALWAYS READ. Others = only if relevant.

---

Question Tool Usage (MANDATORY)

When this skill requires user input or choices:

• Use question tool for all multi-option scenarios
• Present design options with clear descriptions
• Structure preference questions properly

Example usage:

question({
  questions: [{
      question: "Which design style?",
      header: "Style",
      options: [
        { label: "Minimal", description: "Clean, simple" },
        { label: "Glassmorphism", description: "Modern, depth" },
        { label: "Neon", description: "Bold, vibrant" }
      ]
    }]
})

See .opencode/rules/MASTER.md for complete Question Tool Protocol.

---

Runtime Scripts

Execute these for audits (don't read, just run):

| Script | Purpose | Usage | |--------|---------|-------| | scripts/ux_audit.py | UX Psychology & Accessibility Audit | python scripts/ux_audit.py | | scripts/design_system.py | Design System Engine (Colors/Typo) | python scripts/design_system.py --help | | scripts/search.py | Semantic Design Search | python scripts/search.py "query" |

---

CRITICAL: ASK BEFORE ASSUMING (MANDATORY)

> STOP! If the user's request is open-ended, DO NOT default to your favorites.

When User Prompt is Vague, ASK:

Color not specified? Ask: > "What color palette do you prefer? (blue/green/orange/neutral/other?)"

Style not specified? Ask: > "What style are you going for? (minimal/bold/retro/futuristic/organic?)"

Layout not specified? Ask: > "Do you have a layout preference? (single column/grid/asymmetric/full-width?)"

DEFAULT TENDENCIES TO BE AWARE OF:

| AI Default Tendency | Why It's a Concern | Better Approach | |---------------------|--------------|---------------| | Bento Grids Everywhere | Used in every AI design | Why does this content NEED a grid? Use when appropriate | | Always Hero Split | Default to familiar pattern | Consider alternatives when they serve the content better | | Mesh/Aurora Gradients | The "new" lazy background | Use intentionally, not as default | | Glassmorphism | AI's idea of "premium" | Use when it enhances the design, not by default | | Generic Colors | Default blue/cyan/purple | Choose colors based on brand and emotion | | Generic Copy | AI-generated buzzwords | Write authentic copy that reflects the brand voice | | Dark background + neon glow | Overused "AI look" | Use when it matches the brand personality | | Rounded everything | Generic/Safe | Choose edge treatment based on brand personality |

> Default patterns aren't inherently bad - they become problems when used without thinking. Consider context and make intentional choices.

---

1. Constraint Analysis (ALWAYS FIRST)

Before any design work, ANSWER THESE or ASK USER:

| Constraint | Question | Why It Matters | |------------|----------|----------------| | Timeline | How much time? | Determines complexity | | Content | Ready or placeholder? | Affects layout flexibility | | Brand | Existing guidelines? | May dictate colors/fonts | | Tech | What stack? | Affects capabilities | | Audience | Who exactly? | Drives all visual decisions |

Audience → Design Approach

| Audience | Think About | |----------|-------------| | Gen Z | Bold, fast, mobile-first, authentic | | Millennials | Clean, minimal, value-driven | | Gen X | Familiar, trustworthy, clear | | Boomers | Readable, high contrast, simple | | B2B | Professional, data-focused, trust | | Luxury | Restrained elegance, whitespace |

---

2. UX Psychology Principles

Core Laws (Internalize These)

| Law | Principle | Application | |-----|-----------|-------------| | Hick's Law | More choices = slower decisions | Limit options, use progressive disclosure | | Fitts' Law | Bigger + closer = easier to click | Size CTAs appropriately | | Miller's Law | ~7 items in working memory | Chunk content into groups | | Von Restorff | Different = memorable | Make CTAs visually distinct | | Serial Position | First/last remembered most | Key info at start/end |

Emotional Design Levels

VISCERAL (instant)  → First impression: colors, imagery, overall feel
BEHAVIORAL (use)    → Using it: speed, feedback, efficiency
REFLECTIVE (memory) → After: "I like what this says about me"

Trust Building

• Security indicators on sensitive actions
• Social proof where relevant
• Clear contact/support access
• Consistent, professional design
• Transparent policies

---

3. Layout Principles

Golden Ratio (φ = 1.618)

Use for proportional harmony:
├── Content : Sidebar = roughly 62% : 38%
├── Each heading size = previous × 1.618 (for dramatic scale)
├── Spacing can follow: sm → md → lg (each × 1.618)

8-Point Grid Concept

All spacing and sizing in multiples of 8:
├── Tight: 4px (half-step for micro)
├── Small: 8px
├── Medium: 16px
├── Large: 24px, 32px
├── XL: 48px, 64px, 80px
└── Adjust based on content density

Key Sizing Principles

| Element | Consideration | |---------|---------------| | Touch targets | Minimum comfortable tap size | | Buttons | Height based on importance hierarchy | | Inputs | Match button height for alignment | | Cards | Consistent padding, breathable | | Reading width | 45-75 characters optimal |

---

4. Color Principles

60-30-10 Rule

60% → Primary/Background (calm, neutral base)
30% → Secondary (supporting areas)
10% → Accent (CTAs, highlights, attention)

Color Psychology (For Decision Making)

| If You Need... | Consider Hues | Avoid | |----------------|---------------|-------| | Trust, calm | Blue family | Aggressive reds | | Growth, nature | Green family | Industrial grays | | Energy, urgency | Orange, red | Passive blues | | Luxury, creativity | Deep Teal, Gold, Emerald | Cheap-feeling brights | | Clean, minimal | Neutrals | Overwhelming color |

Selection Process

1. What's the industry? (narrows options)
2. What's the emotion? (picks primary)
3. Light or dark mode? (sets foundation)
4. ASK USER if not specified

For detailed color theory: [color-system.md](color-system.md)

---

5. Typography Principles

Scale Selection

| Content Type | Scale Ratio | Feel | |--------------|-------------|------| | Dense UI | 1.125-1.2 | Compact, efficient | | General web | 1.25 | Balanced (most common) | | Editorial | 1.333 | Readable, spacious | | Hero/display | 1.5-1.618 | Dramatic impact |

Pairing Concept

Contrast + Harmony:
├── DIFFERENT enough for hierarchy
├── SIMILAR enough for cohesion
└── Usually: display + neutral, or serif + sans

Readability Rules

• Line length: 45-75 characters optimal
• Line height: 1.4-1.6 for body text
• Contrast: Check WCAG requirements
• Size: 16px+ for body on web

For detailed typography: [typography-system.md](typography-system.md)

---

6. Visual Effects Principles

Glassmorphism (When Appropriate)

Key properties:
├── Semi-transparent background
├── Backdrop blur
├── Subtle border for definition
└──  **WARNING:** Standard blue/white glassmorphism is a modern cliché. Use it radically or not at all.

Shadow Hierarchy

Elevation concept:
├── Higher elements = larger shadows
├── Y-offset > X-offset (light from above)
├── Multiple layers = more realistic
└── Dark mode: may need glow instead

Gradient Usage

Harmonious gradients:
├── Adjacent colors on wheel (analogous)
├── OR same hue, different lightness
├── Avoid harsh complementary pairs
├──  **NO Mesh/Aurora Gradients** (floating blobs)
└── VARY from project to project radically

For complete effects guide: [visual-effects.md](visual-effects.md)

---

7. Animation Principles

Timing Concept

Duration based on:
├── Distance (further = longer)
├── Size (larger = slower)
├── Importance (critical = clear)
└── Context (urgent = fast, luxury = slow)

Easing Selection

| Action | Easing | Why | |--------|--------|-----| | Entering | Ease-out | Decelerate, settle in | | Leaving | Ease-in | Accelerate, exit | | Emphasis | Ease-in-out | Smooth, deliberate | | Playful | Bounce | Fun, energetic |

Performance

• Animate only transform and opacity
• Respect reduced-motion preference
• Test on low-end devices

For animation patterns: [animation-guide.md](animation-guide.md), for advanced: [motion-graphics.md](motion-graphics.md)

---

8. "Wow Factor" Checklist

Premium Indicators

• [ ] Generous whitespace (luxury = breathing room)
• [ ] Subtle depth and dimension
• [ ] Smooth, purposeful animations
• [ ] Attention to detail (alignment, consistency)
• [ ] Cohesive visual rhythm
• [ ] Custom elements (not all defaults)

Trust Builders

• [ ] Security cues where appropriate
• [ ] Social proof / testimonials
• [ ] Clear value proposition
• [ ] Professional imagery
• [ ] Consistent design language

Emotional Triggers

• [ ] Hero that evokes intended emotion
• [ ] Human elements (faces, stories)
• [ ] Progress/achievement indicators
• [ ] Moments of delight

---

9. Anti-Patterns (What NOT to Do)

Lazy Design Indicators

• Default system fonts without consideration
• Stock imagery that doesn't match
• Inconsistent spacing
• Too many competing colors
• Walls of text without hierarchy
• Inaccessible contrast

AI Tendency Patterns (BE AWARE!)

• Same colors every project → Choose based on brand and context
• Dark + neon as default → Use when it fits the brand personality
• Generic color choices → Consider what works for the specific brand/industry
• Bento grids for simple landing pages → Use when they serve the content, not by default
• Mesh Gradients & Glow Effects → Apply intentionally, not as background default
• Same layout structure / Vercel clone → Consider alternatives, but use patterns that work
• Not asking user preferences → Always involve the user in design decisions

Dark Patterns (Unethical)

• Hidden costs
• Fake urgency
• Forced actions
• Deceptive UI
• Confirmshaming

---

10. Decision Process Summary

For EVERY design task:

1. CONSTRAINTS
   └── What's the timeline, brand, tech, audience?
   └── If unclear → ASK

2. CONTENT
   └── What content exists?
   └── What's the hierarchy?

3. STYLE DIRECTION
   └── What's appropriate for context?
   └── If unclear → ASK (don't default!)

4. EXECUTION
   └── Apply principles above
   └── Check against anti-patterns

5. REVIEW
   └── "Does this serve the user?"
   └── "Is this different from my defaults?"
   └── "Would I be proud of this?"

---

Reference Files

For deeper guidance on specific areas:

• [color-system.md](color-system.md) - Color theory and selection process
• [typography-system.md](typography-system.md) - Font pairing and scale decisions
• [visual-effects.md](visual-effects.md) - Effects principles and techniques
• [animation-guide.md](animation-guide.md) - Motion design principles
• [motion-graphics.md](motion-graphics.md) - Advanced: Lottie, GSAP, SVG, 3D, Particles
• [decision-trees.md](decision-trees.md) - Context-specific templates
• [ux-psychology.md](ux-psychology.md) - User psychology deep dive

---

Related Skills

| Skill | When to Use | |-------|-------------| | frontend-design (this) | Before coding - Learn design principles (color, typography, UX psychology) | | [web-design-guidelines](../web-design-guidelines/SKILL.md) | After coding - Audit for accessibility, performance, and best practices |

Post-Design Workflow

After implementing your design, run the audit:

1. DESIGN   → Read frontend-design principles ← YOU ARE HERE
2. CODE     → Implement the design
3. AUDIT    → Run web-design-guidelines review
4. FIX      → Address findings from audit

> Next Step: After coding, use web-design-guidelines skill to audit your implementation for accessibility, focus states, animations, and performance issues.

---

> Remember: Design is THINKING, not copying. Every project deserves fresh consideration based on its unique context and users. Make intentional choices based on goals, not arbitrary restrictions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: paulojalowyj
• Source: paulojalowyj/openkit
• License: MIT
• Homepage: https://linktr.ee/paulojalowyj

Install and usage instructions live in the source repository linked above.