---
name: frontend-design
effort: medium
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
license: Complete terms in LICENSE.txt
---

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

## Project Context

**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.ui_guidelines`, `identity.design_philosophy`, `stack.charting.canonical`, `stack.animation.canonical`.
**Gated by features:** `features.has_design_system` (when `true`, the BLOCKING reads in the next section are mandatory; when `false`, fall back to `paths.ui_guidelines` alone — the BOLD aesthetic direction is then driven by `identity.design_philosophy` only).
**Overlay:** loads `.baldart/overlays/frontend-design.md` if present — project-specific aesthetic mandates, forbidden patterns, illustration-motion contract.
**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?

**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail

## Frontend Aesthetics Guidelines

Focus on:
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

## MANDATORY Pre-Work Read (project design-system override)

The registry-first cascade below is the consumer view of the SSOT in
[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
When the cascade rules diverge between this file and the protocol module,
the protocol module wins.

When operating inside a repo that ships a design-system SSOT, the generic
creative guidance above is BLOCKED by the project design-system until the
reads below are complete. MANDATORY pre-work reads (skipping any of them is
a protocol violation when the docs exist):

1. **MANDATORY / BLOCKING** — `${paths.design_system}/INDEX.md`. Authoritative component index + Canonical Authority Matrix. Discover existing primitives there BEFORE inventing new ones.
2. **MANDATORY / BLOCKING** — `${paths.design_system}/tokens-reference.md`. Human-readable token contract (colors, spacing, radius, shadows, typography). Never hardcode hex colors, shadow pixel tuples, or border widths not defined in the design-system doc.
3. **MANDATORY** — `${paths.design_system}/components/<Name>.md` for every primitive in scope, and `${paths.design_system}/patterns/*.md` (overlays, theming, animations, platform quirks) for the pattern involved.
4. **MANDATORY / BLOCKING** — `${paths.ui_guidelines}`. Brand philosophy, aesthetic rules, SVG rules, accessibility constraints.
5. **MANDATORY for generated marketing illustrations/videos** — `the project's illustration-motion pattern doc (listed in `.baldart/overlays/frontend-design.md` if present)` (if your project has one). Canonical illustration language, product-variant vocabulary, and surgical element-by-element video prompt contract.

Non-negotiable constraints typical of mature design-system SSOTs (adapt to your project):

- Token consumption: only via the project's design-token mechanism (e.g. CSS custom properties, Tailwind theme, Stitches tokens). Never hardcode values outside this contract.
- **Themed-surface text/bg pairing rule (MANDATORY / BLOCKING)** when the design-system defines a primary theme color: any text rendered over the themed primary background MUST pair with the project's theme-primary-text token (e.g. `text-[var(--theme-primary-text,#000)]` on `bg-[var(--theme-primary)]`).
- Do NOT create new overlay systems if the project already catalogs an overlay decision tree — pick from the existing options.
- **Chart library (MANDATORY / BLOCKING)** when the project standardizes a chart stack: use only the approved library and the project's wrappers, never call the underlying chart library from feature code. Banned libraries (typical): `chart.js`, `echarts`, `victory`, `visx`, `d3` standalone, `observable-plot`, `tremor`. Exceptions require an ADR.

Within those bounds, creative choices (typography nuance, composition, motion intensity) are welcome — but the design-system token contract and themed-surface pairing are non-negotiable.

---

## Performance Gates (Core Web Vitals 2026)

Production-grade frontend is not just "looks good" — it ships within the CWV
thresholds. Every page / component / route MUST be designed against these
budgets, not retrofitted after Lighthouse complains.

### Thresholds (p75, CrUX dataset)

| Metric | Good | Poor | What it measures |
|---|---|---|---|
| **LCP** | ≤ 2.5s | > 4.0s | Largest Contentful Paint — usually the hero image or H1 |
| **INP** | ≤ 200ms | > 500ms | Interaction to Next Paint — replaced FID in Mar 2024 |
| **CLS** | ≤ 0.1 | > 0.25 | Cumulative Layout Shift |
| TTFB | ≤ 0.8s | > 1.8s | Subset of LCP (~40% of budget) |
| FCP | ≤ 1.8s | > 3.0s | Diagnostic only |

A page passes CWV when all three (LCP/INP/CLS) are *good* at p75. INP is the
hardest of the three on JS-heavy apps and the most commonly failed (~43% of
sites globally).

### LCP image: the only correct pattern

```html
<!-- in <head> — preload + fetchpriority for the hero -->
<link rel="preload" as="image"
      href="/hero.avif"
      imagesrcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
      imagesizes="100vw"
      fetchpriority="high">

<!-- in body — picture with AVIF/WebP/fallback + explicit dimensions -->
<picture>
  <source srcset="/hero.avif" type="image/avif">
  <source srcset="/hero.webp" type="image/webp">
  <img src="/hero.jpg" alt="..."
       fetchpriority="high"
       width="1600" height="900">
</picture>
```

**Never** apply `loading="lazy"` to the LCP image. **Never** render the LCP
image via client-side JS after hydration — server-render it or preload it.

### INP fixes

- Break any task > 50ms into `await scheduler.yield()` chunks (Chrome 129+;
  fallback `await new Promise(r => setTimeout(r, 0))`).
- Debounce input handlers to one frame (~16ms) when they trigger expensive
  recomputes. Throttle scroll/resize to `requestAnimationFrame`.
- Move CPU-bound work (parsing, transforming, encoding) off the main thread
  with Web Workers when latency matters.
- Avoid `setInterval` polling for data — use SWR / React Query / TanStack
  Query with stale-while-revalidate.

### CLS budget — zero unexpected shift

- Every `<img>`, `<iframe>`, `<video>` declares `width` + `height` or
  `aspect-ratio` CSS.
- Web fonts: `font-display: optional` (no FOIT/FOUT shift, accept fallback
  on first load) OR `size-adjust` + matching `ascent-override` /
  `descent-override` / `line-gap-override` to produce a metric-compatible
  fallback font.
- Skeleton screens mirror the real layout dimensions exactly — a skeleton
  that's the wrong height *causes* CLS instead of preventing it.
- Inserted UI (banners, cookie notices, ads) must reserve space upfront via
  `min-height` — never push existing content down post-paint.

## Modern CSS (2025–2026)

Default to platform features instead of JS shims:

- **Container queries** (`@container` + `container-type: inline-size`) —
  default for any component that lives in variable-width contexts (sidebar,
  grid cell, modal). Component decides its own breakpoint, independent of
  viewport. Use viewport-based `@media` only for app-shell-level layout.
- **`:has()`** — collapse `useState` that exists *only for styling*
  (e.g. label color reacting to input invalid state). Never put business
  logic into `:has()` — only visual reactions to DOM state.
- **View Transitions API** — `document.startViewTransition()` for SPA
  navigation and `view-transition-name` for shared-element morphs. See
  `motion-design/reference/accessibility-and-modern-apis.md` for the full
  pattern.
- **Subgrid** — children align to the parent grid without re-declaring
  tracks. Fixes the long-standing "card content alignment across rows"
  problem.
- **Logical properties** — `margin-inline-start` / `padding-block` instead
  of `margin-left` / `padding-top` whenever the project might add RTL or
  vertical-writing-mode locales. Free i18n with zero overhead.
- **`color-mix()`** — derive hover / focus / disabled states from semantic
  tokens without inventing new tokens
  (`color-mix(in oklch, var(--color-action-primary) 90%, black)`).
- **`@scope`** — scope CSS to a subtree without selector specificity wars or
  CSS-in-JS. Useful when migrating off CSS Modules / styled-components.

## Form quality (always-on requirements)

These apply to every form, every project — they are not "nice to have":

- `<label>` associated to input via `htmlFor` / `id` (never wrap-only — fails
  some screen readers).
- `autocomplete=` filled for every personal-data field
  (`email | tel | given-name | family-name | street-address | postal-code |
  cc-number | one-time-code` …). Required by WCAG 2.1 SC 1.3.5.
- Validation **on blur**, not on every keystroke. Re-validate on submit.
- Error messages are **actionable** ("Email manca @ — esempio:
  nome@dominio.it"), never generic ("Invalid input").
- `aria-invalid` + `aria-describedby` linking the input to its error
  element. Error element has `role="alert"` only when it appears
  dynamically.
- `inputMode=` set when it differs from `type` (e.g. `type="text"
  inputMode="numeric"` for SMS codes — keeps the field text-shaped but
  triggers the numeric keypad).
- Paste handling normalizes whitespace and format BEFORE validating
  (cc-number without spaces, tel without separators).
- Submit button disabled only **after** a failed attempt — never blocked
  pre-emptively; users should be allowed to try and receive feedback.

---

## Standalone Prototypes and Demos

When the task calls for an interactive HTML prototype, animated demo, slide deck, iOS/app mockup, or design exploration **not tied to the project codebase**, the `huashu-design` skill can supplement or replace this skill. It provides:
- App Prototype shell (AppPhone state manager, tappable, iPhone frame)
- Tweaks panel for in-page variants
- Animation export → MP4/GIF (25fps base, 60fps interpolated)
- 5 flows × 20 design philosophies for design exploration
- Playwright click-test validation before delivery

**`huashu-design` is OPTIONAL** — it is a user-installed skill, not shipped with the framework. If it is not present, proceed with this skill alone and notify the user: "huashu-design not found; continuing with frontend-design only. Install huashu-design for advanced prototype tooling."

**Filesystem Rule (ABSOLUTE):** every HTML output/prototype must be written to disk with the `Write` tool BEFORE opening it in a browser or sharing it with the user. Outputting inline code blocks is not sufficient.
