klod68/frontend-visual-design

---

name: frontend-visual-design description: "Use when a Blazor or web application needs intentional visual design beyond default Bootstrap styling, when scaffolding a greenfield app that should look polished rather than generic, or when the design brief requires aesthetic direction (typography, color, motion, spatial composition). Covers the design thinking process, aesthetic vocabulary, font pairing, color palette composition, animation patterns for Blazor, and anti-generic design principles. Domain: UI, Visual Design, Blazor. Level: Intermediate. Tags: design, typography, color, animation, aesthetics, layout, blazor, visual-quality."

Frontend Visual Design

Problem

Technical CSS framework setup (Bootstrap wired, variables defined, isolation configured) is necessary but not sufficient for a polished product. Without intentional visual design, every Blazor app converges on the same generic appearance: system fonts, default Bootstrap gray, uniform card grids, and zero personality. Users perceive these as "AI-generated" or "developer-designed" — functional but forgettable.

The gap is not technical — it is intentional. No one in the pipeline asks "what should this look like?" before scaffolding begins. The Solution Designer defines component hierarchy and data flow; the Scaffolder creates files; the Implementer fills logic. Visual design falls through the cracks because no artifact captures aesthetic intent.

When to Use

• Scaffolding a greenfield Blazor application where visual polish matters
• The frontend-orchestrator's design brief requires aesthetic direction (feature, module, or greenfield scope)
• A project looks "generic" or "default Bootstrap" and needs visual elevation
• Choosing typography, color palette, or animation approach for a new application
• Reviewing a UI implementation for visual design quality (beyond functional correctness)

Do NOT use for:

• CSS framework selection (see web-ui-styling — that skill decides Bootstrap vs MudBlazor vs Tailwind)
• Component architecture, state management, or DI wiring (see blazor.md rules)
• API-only projects, class libraries, or console applications with no UI

---

Design Thinking Process

Before any markup is written, the design brief must answer four questions. This process applies at Stage 1 (Solution Designer) of the frontend pipeline.

1. Purpose

What problem does this interface solve? Who uses it? Context drives every visual decision.

| Application Type | Visual Priority | Tone | |---|---|---| | Internal admin dashboard | Clarity, density, scanability | Professional, utilitarian | | Public documentation site | Readability, navigation, trust | Clean, authoritative | | Customer-facing portal | Brand alignment, delight, trust | Polished, branded | | Demo / showcase site | Impact, memorability, exploration | Bold, distinctive | | Data analytics dashboard | Information density, comparison | Precise, technical |

2. Aesthetic Direction

Commit to a visual direction. Declare it in the design brief as a one-phrase descriptor. These are reference points — combine or adapt, but never ship "no direction."

| Direction | Character | When It Works | |---|---|---| | Clean professional | Generous whitespace, muted palette, clear hierarchy | Business apps, SaaS dashboards, enterprise tools | | Bold editorial | Strong typography, asymmetric layout, dramatic contrast | Marketing sites, portfolios, documentation with personality | | Soft modern | Rounded corners, pastel accents, light shadows, warm tones | Consumer apps, onboarding flows, friendly tools | | Dark technical | Dark surfaces, monospace accents, subtle glow effects, high contrast text | Developer tools, CLI companions, monitoring dashboards | | Minimal refined | Maximum whitespace, restrained palette, precise alignment, no decoration | Luxury, premium, or design-conscious brands | | Data-dense utilitarian | Compact spacing, small type, borders over shadows, maximum information | Trading platforms, operations dashboards, admin panels |

3. Constraints

Technical and brand constraints that bound the visual design:

• Framework: Bootstrap (default), MudBlazor, or other (declared in web-ui-styling decision)
• Brand colors: if the organization has a brand guide, honor it
• Accessibility: WCAG AA contrast ratios are mandatory (not optional)
• Performance: heavy animations may conflict with Blazor Server's SignalR latency

4. Signature Element

What is the one visual detail someone will remember? Every polished app has one:

• A distinctive header treatment (gradient, texture, or typography)
• An animated page transition or loading state
• A unique color accent that runs through the entire interface
• A card or layout pattern that breaks the grid

If the brief cannot name a signature element, the design is generic.

---

Typography

Typography is the highest-leverage visual improvement. Upgrading from Bootstrap's default system font stack to a considered font pairing transforms the entire feel of an application.

Font Pairing Principles

Pair a display font (headings, hero text) with a body font (paragraphs, UI labels). Contrast in style, harmonize in proportion.

| Pairing Strategy | Display Font | Body Font | Character | |---|---|---|---| | Geometric + Humanist | Poppins, Outfit, Plus Jakarta Sans | Source Sans 3, Nunito Sans | Modern, friendly | | Serif + Sans | Playfair Display, Lora, Merriweather | Inter, Open Sans | Editorial, authoritative | | Mono + Sans | JetBrains Mono, Fira Code | IBM Plex Sans, Rubik | Technical, developer-oriented | | Rounded + Clean | Nunito, Quicksand | Lato, Noto Sans | Approachable, soft | | Sharp + Neutral | Manrope, Sora, General Sans | DM Sans, Work Sans | Contemporary, clean |

Integration in Blazor (Google Fonts)

Add to App.razor <head>, before Bootstrap CSS:

<!-- Google Fonts — load before Bootstrap so font-family overrides apply -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&family=Source+Sans+3:wght@400;600&display=swap"
      rel="stylesheet" />

Apply in wwwroot/css/app.css:

:root {
    --app-font-display: 'Plus Jakarta Sans', sans-serif;
    --app-font-body: 'Source Sans 3', sans-serif;
    --app-font-mono: 'JetBrains Mono', monospace;
}

body {
    font-family: var(--app-font-body);
}

h1, h2, h3, h4, h5, h6 {
    font-family: var(--app-font-display);
    font-weight: 600;
}

code, pre, .font-mono {
    font-family: var(--app-font-mono);
}

Rules

• Always define fonts as CSS custom properties (--app-font-*) — never hardcode font-family per component
• Load only the weights you use — each weight adds ~20KB latency
• Use display=swap on Google Fonts to prevent invisible text during load
• System font stack is acceptable for internal-only tools — but declare it as an intentional choice, not a default
• Never use more than 3 font families in one project

---

Color Composition

A cohesive palette is more than Bootstrap's $primary blue. Design the full color system in the design brief.

Palette Structure

| Role | Purpose | Example | |---|---|---| | Primary | Brand action color — buttons, links, active states | #2563eb (blue) | | Accent | Secondary emphasis — badges, highlights, decorative elements | #f59e0b (amber) | | Surface | Background layers — cards, modals, sidebar | #ffffff, #f8f9fa, #1e1e2e | | Text | Content hierarchy — headings, body, muted | #111827, #6b7280, #9ca3af | | Semantic | Status signals — success, warning, error, info | Standard green/yellow/red/blue |

Principles

• One dominant color with one sharp accent outperforms an evenly-distributed 5-color palette
• Semantic colors (success/warning/error) should be universally recognizable — not branded
• Dark mode is not "invert everything" — it is a separate surface/text palette that preserves the same primary and accent
• Test contrast ratios: WCAG AA requires 4.5:1 for body text, 3:1 for large text

Implementation

:root {
    --app-primary: #2563eb;
    --app-primary-hover: #1d4ed8;
    --app-accent: #f59e0b;
    --app-surface-0: #ffffff;
    --app-surface-1: #f8f9fa;
    --app-surface-2: #e9ecef;
    --app-text-primary: #111827;
    --app-text-secondary: #6b7280;
    --app-text-muted: #9ca3af;
}

[data-bs-theme="dark"] {
    --app-surface-0: #0f172a;
    --app-surface-1: #1e293b;
    --app-surface-2: #334155;
    --app-text-primary: #f1f5f9;
    --app-text-secondary: #94a3b8;
    --app-text-muted: #64748b;
}

---

Motion & Animation

Animation adds perceived quality. In Blazor, CSS-only animations are preferred over JS because they avoid SignalR round-trips and work in both SSR and interactive modes.

High-Impact Patterns (CSS-Only)

| Pattern | Where | CSS Technique | |---|---|---| | Page load reveal | Page content on first render | @keyframes fadeInUp with staggered animation-delay | | Card hover lift | Interactive cards | transform: translateY(-4px) + box-shadow transition | | Sidebar collapse | Navigation | transition: width 0.3s ease with overflow: hidden | | Loading skeleton | Data-loading states | @keyframes shimmer with gradient background-position animation | | Button press | Action buttons | transform: scale(0.97) on :active | | Toast slide-in | Notifications | @keyframes slideInRight with transform: translateX() |

Staggered Page Load Example

/* In app.css or component .razor.css */
.stagger-in {
    opacity: 0;
    transform: translateY(12px);
    animation: fadeInUp 0.4s ease forwards;
}

.stagger-in:nth-child(1) { animation-delay: 0.05s; }
.stagger-in:nth-child(2) { animation-delay: 0.10s; }
.stagger-in:nth-child(3) { animation-delay: 0.15s; }
.stagger-in:nth-child(4) { animation-delay: 0.20s; }

@keyframes fadeInUp {
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

Loading Skeleton Example

.skeleton {
    background: linear-gradient(90deg,
        var(--app-surface-1) 25%,
        var(--app-surface-2) 50%,
        var(--app-surface-1) 75%);
    background-size: 200% 100%;
    animation: shimmer 1.5s infinite;
    border-radius: 4px;
}

@keyframes shimmer {
    0%   { background-position: 200% 0; }
    100% { background-position: -200% 0; }
}

Rules

• Prefer CSS animations over JS — they work in SSR mode and avoid Blazor interop overhead
• Keep animation duration under 400ms for UI transitions — longer feels sluggish
• Use ease or ease-out timing — never linear for UI motion (feels mechanical)
• Loading skeletons are mandatory for any data fetch over 200ms — never show a blank void
• Disable animations when prefers-reduced-motion: reduce is set (accessibility)

@media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
        animation-duration: 0.01ms !important; /* effectively instant */
        transition-duration: 0.01ms !important;
    }
}

---

Spatial Composition

Layout is not "put things in a grid." Intentional spatial composition creates visual hierarchy and guides the eye.

Principles

• Generous whitespace between sections creates breathing room and hierarchy. Default Bootstrap spacing (mb-3, p-3) is too tight for page-level sections — use mb-5 or custom --app-section-gap values
• Asymmetric layouts are more visually interesting than perfectly centered everything. A 7/5 or 8/4 column split has more energy than 6/6
• Card hover elevation (shadow + lift) signals interactivity without a border
• Consistent alignment on a baseline grid — mixing left-aligned and center-aligned sections feels arbitrary. Pick one dominant alignment and use it everywhere
• Visual weight balance — a dark sidebar balances a light content area; a heavy header balances a spacious body

Responsive Breakpoints

Follow Bootstrap's breakpoints but design for the actual use case:

| Application Type | Primary Target | Design Priority | |---|---|---| | Admin dashboard | Desktop (1200px+) | Dense layout, sidebar nav | | Documentation site | Tablet+ (768px+) | Readable width (max 75ch), collapsible nav | | Public portal | Mobile-first (375px+) | Touch targets, stacked layout |

---

Visual Quality Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Default Bootstrap with no customization | Define custom palette, typography, and at least one signature element | | System font stack with no font declaration | Choose a font pairing and declare it in CSS custom properties | | Every section is a uniform card grid | Vary layout: hero sections, split layouts, full-width banners, list views | | No loading state — blank page then sudden content | Add loading skeletons or staggered fade-in reveals | | All colors from Bootstrap defaults (btn-primary, bg-light) | Define --app-* custom properties for project-specific palette | | Animations disabled for prefers-reduced-motion not handled | Always include the reduced-motion media query | | More than 3 font families loaded | Reduce to 2 (display + body) plus optional monospace | | linear timing on UI transitions | Use ease or ease-out for natural-feeling motion | | Everything center-aligned on the page | Choose a dominant alignment; use asymmetry intentionally | | No visual hierarchy — all text same size/weight | Use font size + weight + color to create 3+ hierarchy levels |

---

Design Brief Template

When the frontend-orchestrator requires a design brief (feature, module, or greenfield scope), populate this template in the design artifact:

## Visual Design Brief

**Aesthetic direction:** {one-phrase descriptor from the vocabulary table}
**Signature element:** {the one visual detail that makes this memorable}

### Typography
- Display font: {name} — {weights to load}
- Body font: {name} — {weights to load}
- Source: Google Fonts | system | self-hosted

### Color Palette
- Primary: {hex} — {where it appears}
- Accent: {hex} — {where it appears}
- Surface: {light hex} / {dark hex}
- Text: {primary hex} / {secondary hex} / {muted hex}

### Motion
- Page transitions: {yes/no — approach if yes}
- Loading states: {skeleton / spinner / fade-in}
- Hover effects: {lift / glow / underline / none}

### Layout
- Primary target viewport: {mobile / tablet / desktop}
- Navigation: {sidebar / topbar / combined}
- Content max-width: {e.g., 1200px / 75ch / full-width}

---

Examples

Example 1: Elevating a Generic Admin Dashboard

Before: Default Bootstrap, system fonts, btn-primary blue, uniform card grid, no loading states. Looks like every other Bootstrap admin template.

After: Plus Jakarta Sans headings + Source Sans 3 body, custom indigo primary (#4f46e5) with amber accent (#f59e0b), staggered card load animation, loading skeletons on data fetches, sidebar with subtle gradient background, one asymmetric hero stat bar at the top breaking the card grid pattern.

Design brief declared: "Clean professional with warm accent." Signature element: "Amber-highlighted stat bar with staggered number count-up."

Example 2: Documentation Site with Personality

Before: Default Bootstrap docs template, gray sidebar, Inter font, no visual identity.

After: Aesthetic direction "Bold editorial." Playfair Display headings, DM Sans body. Dark sidebar (#0f172a) contrasting with warm white content (#fffbf5). Code blocks with a subtle gradient border. Page sections fade in on scroll. Signature element: "Serif headings with a thin amber underline on hover."

Example 3: Knowing When NOT to Over-Design

Scenario: Internal operations dashboard used by 5 people in a warehouse. They need density, speed, and clarity — not personality.

Direction: "Data-dense utilitarian." System font stack (intentional choice, not default), compact spacing, borders instead of shadows, minimal color (monochrome with red for alerts), zero animation. This IS the design — restraint is intentional.

Design brief declared: "Utilitarian — maximum data density, zero decoration." Signature element: "None — density is the design."

---

Related Skills

• web-ui-styling — Technical framework selection (Bootstrap vs alternatives), CSS architecture, isolation, and variable conventions. Use that skill for which framework; use this skill for how it should look
• gen-blazor-demo-site — Scaffolds a complete Blazor demo site; this skill's design brief feeds the demo site's visual approach
• streaming-ai-responses — ChatGPT-style progressive display; complements motion guidance for AI-integrated UIs