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.
• Original, modern icons (see below), never emoji.

Iconography: original, modern, never emoji

• Never use emojis. Not as icons, not in buttons, labels, headings, empty states, or copy. Emojis render differently per platform, break visual consistency, and read as unfinished. Hard rule.
• Create original icons. Design a custom SVG set for the product's key actions and brand marks on a consistent grid (e.g. 24px, 2px stroke, rounded joins) with one visual language. The logo/brand glyph and primary actions should be original, not stock.
• Modern style. Clean line or duotone, optically balanced, legible at 16-20px, pixel-snapped, with stroke weight matched to the type weight.
• If a full custom set is out of scope, use one modern open set as the base (Lucide, Material Symbols, Phosphor) and still draw the brand and hero marks original. Never mix icon families.
• Ship as inline SVG or a sprite, currentColor-driven so icons theme with light/dark; give each an accessible label (aria-label or <title>).

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. Original, modern SVG icon set (currentColor, accessible labels), no emoji.
6. Context-aware favicon set, manifest, and link tags.
7. Designed empty, loading, and error states.

Forbidden

Emojis anywhere (UI, icons, buttons, copy); stock/generic icons for brand or primary marks; mixing icon families; 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).

This page mirrors Designer Skill in the wiki. Edit it there.