frontend-design

name	frontend-design
description	Build polished, specific, non-generic frontend web experiences. Use when designing or implementing UI, landing pages, marketing sites, product UI, dashboards, editorial layouts, or conversion flows. Produces and maintains a project DESIGN.md token system so visual decisions persist across sessions and models.
license	MIT
metadata	{"author":"sixtyoneeighty","version":"2.0.0"}

Frontend Design

Description

Build frontend web experiences that feel specific, deliberate, usable, and difficult to confuse with generic templates. Start from subject matter, audience, content, and user behavior before choosing components. Prefer one clear visual thesis, one decisive anchor, disciplined typography, responsive layout logic, accessible interaction, and memorable but restrained motion.

The goal is to prevent generic frontend output while preserving usability, clarity, performance, and implementation quality.

Requirements

Use the project's existing stack when possible.

# Optional checks if available in the project
npm run lint
npm run typecheck
npm run build
npm run test

DESIGN.md Integration

This skill treats visual identity as a persistent project artifact, not a per-session decision. After the creative pass selects a route, capture the resulting system in a DESIGN.md file at the project root using the @google/design.md format. Later sessions and other models read that file for exact token values instead of re-inventing them, which keeps brand execution consistent over time.

When to create or update DESIGN.md

• Create DESIGN.md the first time you commit to a visual direction for a project.
• Update it whenever you change palette, typography, spacing, radii, or component tokens.
• Treat the YAML tokens as the normative values and the prose sections as rationale for how to apply them.

Format

A DESIGN.md file has YAML front matter (machine-readable design tokens) followed by markdown sections (human-readable rationale). Sections, when present, must appear in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.

---
version: alpha
name: <System Name>
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.neutral}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

One or two sentences describing the visual thesis in concrete, evocative terms.

## Colors

- **Primary (#1A1C1E):** where and why it is used.
- **Tertiary (#B8422E):** the single interaction-driver accent.

Colors must be # + sRGB hex. Dimensions use px, em, or rem. Token references use {path.to.token} and must resolve to a defined token.

Validate before finishing

Run the linter and resolve errors before reporting completion. It checks structure, broken token references, and WCAG AA contrast on component color pairs.

npx @google/design.md lint DESIGN.md

Optionally export tokens for the project's stack instead of hand-copying values:

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css   # Tailwind v4 @theme block
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json   # Tailwind v3 theme.extend
npx @google/design.md export --format dtcg DESIGN.md > tokens.json   # W3C Design Tokens

If @google/design.md cannot be installed in the environment, still write DESIGN.md in this format and note that linting was skipped.

DESIGN.md captures what was decided. The rest of this skill governs how the decision is made. A correct token file does not replace the creative process below.

Safety Policy

Execute without confirmation

• Inspect project structure and design files.
• Run local lint, typecheck, build, or test commands.
• Edit frontend source, styles, components, routes, and documentation inside the project.
• Create or update the project DESIGN.md and run npx @google/design.md lint.
• Add small helper scripts, CSS utilities, or component variants when needed.

Ask before proceeding

• Installing new dependencies.
• Changing global config, deployment settings, auth, billing, analytics, or database behavior.
• Large rewrites that affect app architecture.
• Destructive commands such as deleting directories, resetting branches, or overwriting generated assets.

Instructions

1. Classify the web mode

   • Choose one primary mode: landing, marketing_site, product_ui, editorial, portfolio, dashboard, or conversion_flow.
   • Do not start from component libraries or generic SaaS patterns.

2. Extract brand and content grammar

   • Identify nouns, verbs, emotional register, audience expectation, web constraints, content density, accessibility needs, and conversion goals.
   • Translate these into grid, typography, palette, imagery, interaction, surface treatment, and responsive behavior.

3. Write working notes before building

   • mode
   • visual_thesis
   • tension_pair
   • audience
   • content_plan
   • interaction_thesis
   • responsive_thesis
   • accessibility_risks
   • data_driver
   • conversion_goal
   • reference_trap
   • borrowed_logic
   • creative_constraint

4. Generate three distinct routes

   • Route A: familiar but elevated.
   • Route B: directional and branded.
   • Route C: structural inversion or category break.
   • Routes must differ in composition, type attitude, image treatment, motion, density, pacing, and responsive behavior.

5. Choose one route

   • State why it best fits the brief, user intent, implementation constraints, and conversion goal.
   • Select one hard creative constraint before building.

6. Capture the system in DESIGN.md

   • Translate the chosen route's palette, typography, spacing, radii, and key components into DESIGN.md tokens.
   • Write the Overview and Colors prose so the rationale survives a model or session change.
   • Run npx @google/design.md lint DESIGN.md and fix findings.

7. Map the web experience

   • Landing or marketing: poster-like hero, proof, detail, credibility, conversion.
   • Product UI: workspace model, state clarity, density, hierarchy, task completion.
   • Editorial: sequence, pacing, captions, media treatment, narrative flow.
   • Dashboard: scanability, data hierarchy, empty/loading/error states.
   • Conversion flow: trust, friction reduction, form clarity, progress, recovery.

8. Define systems

   • Spatial system: grid, rhythm, depth, breakpoints, container strategy.
   • Type system: scale, hierarchy, line length, weight, reading rhythm.
   • Motion system: entrance, continuity, feedback, reduced-motion fallback.
   • Data behavior: how live, variable, or user-generated content changes layout.
   • Accessibility: contrast, focus, keyboard, semantic HTML, screen-reader behavior.

9. Build with restraint

   • Use existing project conventions and the tokens defined in DESIGN.md.
   • Add only necessary abstractions.
   • Prefer semantic HTML, responsive CSS, accessible components, and clear state handling.
   • Avoid decorative complexity that weakens performance or clarity.

10. Run checks

• Anti-derivative check.
• Clarity scan.
• Responsive check.
• Accessibility check.
• npx @google/design.md lint DESIGN.md.
• Build or lint check when available.

11. Output final recommendation or implementation

• Include route rationale, changed files, design decisions, risks, and next steps.

Working Notes Template

mode:
visual_thesis:
tension_pair:
audience:
content_plan:
interaction_thesis:
responsive_thesis:
accessibility_risks:
data_driver:
conversion_goal:
reference_trap:
borrowed_logic:
creative_constraint:

If any field is vague, refine the concept before implementation.

Quality Standard for Visual Thesis

Weak:

warm, modern, and confident

Strong:

a museum conservation lab: gray linen, specimen labels, controlled light, and institutional patience

A strong thesis should imply typography, palette, spacing, texture, hierarchy, and motion without naming every design choice directly.

Web Mode Routing

Landing

Use poster logic, one decisive promise, proof, social credibility, and conversion rhythm.

Marketing Site

Use brand storytelling, clear navigation, modular page rhythm, proof sections, use cases, and trust-building.

Product UI

Use workspace-first logic, utility copy, state clarity, calm density, responsive behavior, and operational readability.

Editorial

Use narrative pacing, captions, media crops, typographic voice, negative space, and sequence.

Portfolio

Use identity, work evidence, project navigation, case-study structure, and strong first impression.

Dashboard

Use scan-first hierarchy, persistent context, clear numbers, filters, states, and progressive detail.

Conversion Flow

Use trust, reduced friction, form clarity, explicit progress, recovery paths, and persuasive but honest copy.

Do not let landing-page theatrics weaken product UI. Do not let dashboard card logic flatten brand pages. Do not let editorial mood harm accessibility or conversion clarity.

Brand Grammar Extraction

Capture:

• nouns: objects, materials, places, symbols, environments
• verbs: browse, compare, queue, compose, track, explore, trade, publish, schedule, analyze
• emotional register: clinical, rebellious, ceremonial, playful, warm, technical, luxurious, calm, urgent
• era or geography signal: the production culture that fits the product personality
• audience expectation: mass market, enthusiast, operator, buyer, traveler, founder, creator, analyst
• practical constraints: performance, accessibility, trust, device patterns, asset quality, copy density

Translate those signals into:

• geometry and grid
• typography attitude
• palette and tonal range
• imagery or illustration direction
• motion behavior
• surface treatment
• responsive layout behavior
• component density

Choose style because it fits the subject matter, not because it is fashionable.

Conceptual Leap

Before route generation, choose one external artifact, system, or discipline to borrow from.

Examples:

• shipping manifests
• estate maps
• cockpit controls
• field notebooks
• NOAA charts
• record-store taxonomy
• museum labels
• architectural signage
• restaurant menus
• airline wayfinding
• financial ledgers
• print magazines

Borrow logic, not visual cosplay.

Answer:

• what is being borrowed
• why it fits the product
• what organizational principle transfers to screen
• how it improves web hierarchy, navigation, or conversion

Also define the depth strategy. Treat the browser as layered space, not a flat sheet. State what sits in front, behind, overlaps, pins, scrolls, fades, or becomes legible through interaction.

Route Generation

Generate three routes that are actually different.

Route A

Familiar but elevated. Safest viable interpretation.

Route B

Directional and branded. Default preference for most creative briefs.

Route C

Structural inversion or category break. Should feel surprising even to a designer.

At least one route must be data-subordinate: the design system visibly bends to real content, product data, user state, or responsive constraints instead of forcing everything into fixed cards.

Routes must differ in:

• composition
• typography attitude
• image treatment
• motion language
• density and pacing
• responsive behavior
• depth strategy
• relationship to live or structural data

If the three routes look like the same layout with garnish, fail and redo.

Route C Generators

Use one of these:

• inversion
• reduction
• scale extremity
• cultural code-switch
• material literalism
• temporal displacement
• navigation reversal
• content-first collapse
• single-object interface
• typographic dominance

If Route C does not create a genuine category break, it is not Route C.

Surprise Budget

Allow at most:

• one structural surprise
• one material surprise
• one interaction surprise

Do not spend all surprises in the first viewport unless the brief explicitly calls for intensity.

Creative Constraint

Choose one real restriction before building.

Examples:

• no photography or illustration
• no symmetry anywhere
• no more than three words in any headline
• no cards, borders, or dividers
• monochrome only
• the page must work as a printed poster before interaction
• every section must use the same grid differently
• no decorative gradients
• no fixed hero screenshot
• all CTAs must appear only after proof
• mobile layout must be designed first

A good constraint should make obvious solutions impossible.

If the constraint is abandoned later, explain why.

Composition Defaults

• Start with composition, not components.
• Choose one decisive visual anchor.
• Make brand or product name strongly present on branded pages.
• Treat the first viewport as a poster, not a document.
• Use whitespace, scale, cropping, alignment, contrast, and type before adding chrome.
• Default to two typefaces maximum and one accent color maximum.
• Cards are guilty until proven necessary.
• Prefer sections, planes, lists, dividers, media blocks, columns, timelines, captions, and tables before card stacks.
• Give each section one job.
• Design mobile, tablet, and desktop behavior intentionally.

If decorative shadows are doing the premium work, the composition is weak.

Page Rhythm

Select a rhythm that matches the brief:

• poster -> proof -> detail -> convert
• atmosphere -> offer -> logistics -> convert
• product -> workflow -> edge cases -> convert
• story -> mechanism -> credibility -> convert
• problem -> proof -> demo -> convert
• trust -> form -> confirmation -> recovery
• overview -> filter -> inspect -> act

Vary pace deliberately:

• dense -> sparse
• static -> kinetic
• proof -> atmosphere
• compression -> release
• explanation -> evidence
• scan -> detail

Do not open strong and then collapse into generic feature bands.

Landing and Marketing Rules

• Choose one dominant hero composition.
• Use full bleed only when it strengthens the story.
• Place brand first, headline second, body third, action fourth.
• Keep text columns narrow and anchored to calm areas.
• Avoid hero cards, stat strips, logo clouds, pill soup, and floating dashboard clichés by default.
• Count fixed headers against the hero viewport budget.
• Show proof close to the claim.
• Make the primary CTA visually stable across breakpoints.

Hero strength test:

If the anchor is removed and the first screen feels unchanged, the anchor is too weak.

Product UI Rules

Choose a workspace model first:

• canvas + inspector
• list + detail
• board + filters
• timeline + detail
• map + console
• stream + command bar
• table + preview
• inbox + triage
• editor + side context
• search + results + refinement

Then optimize for state clarity, density, hierarchy, and calm operation.

Product UI copy must be utility-first. Headings should orient, not advertise. If the same UI could belong to five unrelated SaaS products after a logo swap, the visual system is too generic.

Dashboard Rules

• Put the most decision-relevant data first.
• Separate monitoring, diagnosis, and action.
• Design empty, loading, error, stale, and overflow states.
• Use color for meaning before decoration.
• Let filters and time ranges remain visible when they affect interpretation.
• Avoid arbitrary chart grids without a reading order.
• Prefer progressive detail over overwhelming first view.

Editorial Web Rules

• Let image, caption, quote, schedule, or artifact carry meaning.
• Use negative space for pacing.
• Let typography act as voice.
• Separate mood sections from logistics sections.
• Prefer sequence over collage unless fragmentation is the concept.
• Maintain readable line lengths and accessible contrast.

Conversion Flow Rules

• State the user's current step clearly.
• Remove unnecessary choices near high-intent actions.
• Make form errors specific and recoverable.
• Preserve entered data when errors occur.
• Use trust signals close to risk points.
• Do not hide pricing, requirements, or commitments.
• Make success, failure, and next action obvious.

Copy Rules

Write in product language, user language, or brand language. Never write design commentary into the UI.

• Headline carries the meaning.
• Supporting copy scans in seconds.
• Every section must explain, prove, deepen, orient, or convert.
• Delete anything that could be pasted onto a competitor page unchanged.
• Delete lines that only restate mood.
• Prefer specific nouns and verbs over abstract claims.

If deleting 30 percent improves the page, keep deleting.

Motion Rules

Use motion for presence, continuity, affordance, atmosphere, or timing.

Default to 2 or 3 meaningful motions:

• one entrance sequence
• one scroll-linked, sticky, or depth effect
• one hover, reveal, or layout transition

Motion must be:

• noticeable in a short recording
• smooth on mobile
• consistent with the visual thesis
• safe under reduced-motion preferences
• useful for hierarchy, continuity, feedback, or atmosphere

Remove ornamental motion.

Motion-First Option

Use motion-first logic when transformation, flow, rhythm, or time is the product's main feeling.

In motion-first work:

• define motion before layout
• every static frame should feel like a paused moment from a larger sequence
• the page should feel incomplete without motion
• provide a reduced-motion fallback

Time as Material

Consider what changes simply because time passes.

Options:

• slow reveal
• drift
• idle mutation
• environmental cycling
• content freshness
• live activity
• deadline pressure
• recent-user behavior

Time behavior must deepen the concept, not act like a screensaver.

Realism and Anti-Polish

Do not optimize for pleasantness by default. Some brands should feel raw, dense, overdriven, institutional, technical, handmade, or intentionally awkward.

Possible levers:

• off-grid alignment
• hyper-dense information zones
• aggressive contrast
• dominant industrial typography
• awkward pacing or dead stops
• one overloaded zone balanced by radical emptiness elsewhere
• visible system artifacts
• utilitarian tables or labels

But preserve clarity. Aggression must be intentional.

Responsive Design Rules

• Define mobile behavior before implementation when the content is complex.
• Do not simply stack desktop sections.
• Preserve the visual thesis at every breakpoint.
• Reconsider navigation, media crops, sticky elements, and CTA placement on mobile.
• Test long headings, missing images, large numbers, and variable content.
• Avoid horizontal overflow unless deliberately designed and accessible.
• Ensure tap targets are usable.

Accessibility Rules

• Use semantic HTML before ARIA.
• Preserve keyboard navigation and visible focus.
• Maintain contrast for text and essential UI.
• Do not encode meaning with color alone.
• Respect reduced-motion preferences.
• Label forms, controls, icons, and interactive regions.
• Keep reading order logical after responsive changes.
• Make error states programmatically and visually clear.

Performance Rules

• Avoid unnecessary animation libraries.
• Optimize images and media.
• Prefer CSS layout and transitions where practical.
• Do not block content with decorative effects.
• Keep first viewport meaningful before heavy assets load.
• Avoid large dependencies for small visual effects.
• Use lazy loading only where it does not harm comprehension.

Anti-Derivative Check

Before finalizing:

1. identify the nearest obvious reference
2. remove the logo and copy mentally
3. ask whether the silhouette still reads as that reference
4. if yes, change at least two of:
   • grid logic
   • typography attitude
   • hero or workspace model
   • texture or material system
   • motion language
   • image treatment
   • responsive behavior
   • navigation model

Common Reference Traps

Watch for silhouettes that echo:

• Linear
• Stripe
• Apple
• Notion
• Framer
• Vercel
• Webflow templates
• generic Awwwards editorial templates
• generic AI startup gradients
• generic SaaS dashboard cards

Borrow quality cues, not spatial fingerprints.

Hard Failures

Reject output that includes:

• generic SaaS card grid as the first impression
• strong headline with weak brand presence
• beautiful image with no structural idea
• busy imagery behind text
• template feature bands after a promising hero
• product UI built from stacked cards instead of layout
• three concept routes that are really the same layout
• a visual thesis that names only mood
• Route C that is just Route B with garnish
• decorative motion that harms usability
• inaccessible contrast, focus, or form behavior
• mobile layout that merely stacks desktop content
• conversion pages that hide cost, risk, or next step

Final Litmus Checks

The work is ready only if most answers are yes:

• Is the product unmistakable in the first screen?
• Is there one decisive visual anchor?
• Does the design survive a logo swap test?
• Can the surface be understood by scanning major labels, headings, and numbers only?
• Does each section have one job?
• Does the core motif survive past the first viewport?
• Are cards actually necessary?
• Does motion improve hierarchy, continuity, feedback, or atmosphere?
• Is there a deliberate depth strategy?
• Did the design borrow logic from outside UI?
• Does the tension pair truly hold?
• Would the design still feel strong if decorative shadows were removed?
• Does it work across mobile, tablet, and desktop?
• Are keyboard, focus, contrast, and reduced-motion states handled?
• Does the page guide the user toward a clear next action?
• Does DESIGN.md exist, lint clean, and match the implemented UI?

Output Format

STATUS: SUCCESS | FAILED | BLOCKED

Mode:
Working Notes:
Routes:
Chosen Route:
Creative Constraint:
Experience Model:
Spatial / Motion / Data Behavior:
Accessibility / Responsive Notes:
DESIGN.md: created | updated | unchanged (lint: pass | fail | skipped)
Anti-Derivative Risk:
Implementation Summary:
Changed Files:
Validation:
Risks / Follow-ups:

Error Handling

Common automatic handling:

• Missing scripts -> inspect package.json and run available checks only.
• Build failure -> report exact command and first actionable error.
• Styling conflict -> preserve existing design tokens where possible.
• Accessibility issue -> fix semantic, focus, contrast, or label problem before decoration.
• Responsive issue -> adjust layout strategy, not just spacing.
• @google/design.md unavailable -> still author DESIGN.md in-format and note that linting was skipped.