Designer Skill

Designer Skill

A cross-cutting skill on the staff-software-engineer agent, applied when building something new with a UI: a new app, page, feature, or landing. It encodes the visual and UX defaults so a green-field interface ships looking deliberate and modern, not like a default template. It layers on top of the area skill (web/mobile); per-repo conventions in .claude/conventions/web.md still win, and if the repo already has a design system the agent uses that instead.

Skill file: skills/designer/SKILL.md. Read by /sse:plan and /sse:dev when the work includes a new UI.

Why a design skill

Most AI-built UIs converge on the same generic look: centered everything, default framework blue, gradients on every surface, emoji as icons, lorem ipsum, one theme, English-only. The designer skill is a feedforward guide (Guides) that pushes the agent toward a higher bar before it writes a single component, the same way the coding-style guide shapes code. It is opinionated on purpose.

Material Design 3 as the system

Use M3 as the token system, not as a literal Google look. The point is structure: design with roles and scales, never hardcoded values.

• Color roles. Define primary, on-primary, primary-container, secondary, tertiary, surface, surface-container (lowest to highest), on-surface, on-surface-variant, outline, error. Derive them from a single seed color (M3 dynamic color), and pick the seed from the product's context, not the default purple.
• Type scale. display / headline / title / body / label, each L/M/S, mapped to CSS classes.
• Shape scale. none 0, xs 4, s 8, m 12, l 16, xl 28, full. Cards l, buttons full or m.
• Tonal elevation. Six levels via layered surface-container tints plus a subtle shadow. Prefer the container tint over heavy drop shadows.
• State layers. hover 8%, focus 10%, pressed 10% of the on-* color over the component.
• Motion. M3 emphasized easing cubic-bezier(.2,0,0,1), standard 200-300ms, small 100ms.

Dark and light, both mandatory

Never ship a single theme.

• System preference first (prefers-color-scheme), user toggle second, choice persisted to localStorage and reflected on :root[data-theme].
• Two token sets, light and dark. Dark is tonal, not pure black: a #1A1C1E-ish surface, elevated with lighter container tints rather than shadows.
• Verify contrast in both themes (see Accessibility).

:root { color-scheme: light dark; }
:root[data-theme="light"] { --surface:#FDFCFF; --on-surface:#1A1C1E; --primary:#0B57D0; }
:root[data-theme="dark"]  { --surface:#1A1C1E; --on-surface:#E3E2E6; --primary:#A8C7FA; }

Modern type

• Default Inter (variable) for UI and body; M3-native alternative Roboto Flex. Self-host or load with font-display: swap.
• Optional one display face for hero/headline only (Space Grotesk, Sora, Plus Jakarta Sans).
• Tabular numbers for data (font-variant-numeric: tabular-nums).
• Stack: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif.

Behance-grade polish

The bar for "new and good" is top Behance UI work. Concretely:

• 8pt spacing grid (4/8/12/16/24/32/48/64). Generous whitespace; let layouts breathe.
• Strong hierarchy. One clear focal point per view. Confident headline, calm body. Size, weight, and space carry hierarchy before color does.
• Restrained palette. One brand seed, neutrals, one accent. Color earns attention.
• Crisp components. Consistent radius, aligned grids, optical alignment, no orphaned elements.
• Real content. Realistic copy and data, never lorem. Empty, loading, and error states are designed, not afterthoughts.
• Micro-interactions. Hover, focus, press feedback on every interactive element. Subtle and fast.
• One icon family (Material Symbols or Lucide), never emoji as icons.

Internationalization (en, pt-BR, es)

Every user-facing string is translatable. Three locales ship: English (default), Brazilian Portuguese, Spanish.

• No hardcoded strings; a t('key') lookup with semantic keys (cart.empty.title).
• locales/{en,pt-BR,es}.json, identical key sets across all three.
• Detect navigator.language, fall back to en; user can switch, persist the choice.
• Set <html lang> dynamically; format dates, numbers, and currency with Intl per locale; plurals via the i18n library's plural rules.

Context-aware favicon

Generate a favicon that reflects the product's context, not a placeholder.

• Author as SVG (crisp, themeable), using the brand seed, light/dark aware.
• Derive the mark from context: the product's initial/monogram, or a glyph matching the domain (a cart for commerce, a chart for analytics). Legible at 16px.
• Ship favicon.svg (primary), favicon.ico 32, apple-touch-icon.png 180, and a site.webmanifest with 192 and 512 maskable PNGs, plus theme-color meta per scheme.
• State which symbol and seed were chosen and why (the context link).

Accessibility (non-negotiable)

• Contrast: body text >= 4.5:1, large text and UI >= 3:1 (WCAG 2.2 AA), in both themes.
• Visible :focus-visible ring on every interactive element. Hit target >= 44x44px.
• Respect prefers-reduced-motion. Semantic HTML, labeled inputs, keyboard reachable.

What the agent delivers with a new UI

1. Token file (color roles, type, shape) for light and dark.
2. Theme toggle wired to system preference and persistence.
3. Modern font loaded with font-display: swap.
4. locales/{en,pt-BR,es}.json plus t() wiring and a language switch.
5. Context-aware favicon set, manifest, and link tags.
6. Designed empty, loading, and error states.

Forbidden

Hardcoded colors instead of tokens; a single theme; hardcoded user-facing strings; a placeholder favicon; lorem ipsum in shipped UI; contrast below AA in either theme.

See also

• Agents and Guides
• Pipeline and Stages, where /sse:plan and /sse:dev read this skill

References

• Material Design 3 specification, m3.material.io (color roles, type scale, elevation, motion).
• WCAG 2.2, Web Content Accessibility Guidelines (contrast, focus, targets).
• Inter typeface, rsms.me/inter; Roboto Flex (Google Fonts).
• Intl (ECMAScript Internationalization API) for locale-aware formatting.
• Web App Manifest and favicon best practices (MDN).