# Frontend Design

> Implement distinctive, production-grade frontend UI code with strong visual direction, motion systems, local media asset generation, conversion-aware copy, and polished frontend execution. Use when building landing pages, marketing sites, product pages, dashboards, motion-heavy interfaces, or frontend experiences that need real assets and compelling copy.

- Skill: `jochenyang/frontend-design` (Agent Skill, multi-file: 71 files)
- Install (CLI): `npx skillmds@latest add jochenyang/frontend-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jochenyang/frontend-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: JochenYang (https://skillmd.com/u/jochenyang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jochenyang/frontend-design

---


# Frontend Design

Build distinctive, production-grade frontend interfaces that feel intentional,
polished, and ready to ship. This skill exists to prevent generic AI UI: weak
typography, timid color, repetitive layouts, placeholder copy, and ornamental
motion.

## Use This Skill When

- the output is implemented frontend code, not just critique
- the task is a landing page, product page, marketing site, dashboard, app
  shell, docs surface, or interactive prototype
- the UI needs strong visual direction, premium polish, motion, assets, or
  conversion-aware copy
- an existing frontend needs targeted redesign without a full rewrite

## Do Not Use This Skill When

- the task is backend, API, database, or infrastructure work
- the user wants UX critique before implementation -> use `ui-ux-pro-max`
- the user wants broader full-stack delivery -> use `developer`

## Non-Negotiables

- Do not ship generic AI aesthetics.
- Do not guess critical design direction when it would materially change the
  implementation.
- Do not design from scratch when local code, screenshots, or a design system
  already exist and can be mined first.
- Do not use placeholder copy, placeholder media URLs, or half-finished code.
- Do not break an existing design system unless the user explicitly asks.
- Do not add heavy motion or media without clear payoff.
- If a required asset is missing, prefer an explicit local placeholder or
  simple custom illustration over irrelevant stock UI or fake product chrome.

## Execution Model

Before implementation, lock these four inputs:

- **Purpose**: what the interface does and who it serves
- **Anchor**: brand, product, or mood reference
- **Constraints**: framework, design system, accessibility, performance,
  device priority
- **Difference-maker**: the one memorable visual or interaction idea

Then write three anchors:

- **Visual thesis**: one sentence for mood, material, and energy
- **Content plan**: hero, support, detail, final CTA
- **Interaction thesis**: two or three motion ideas that change the feel of
  the page

Each section gets one job, one dominant idea, and one primary takeaway or
action.

## Design Controls

Use these internal dials to avoid generic output:

- **DESIGN_VARIANCE**
  - `1-3`: restrained, symmetrical, predictable
  - `4-7`: offset, structured, moderately experimental
  - `8-10`: asymmetric, broken-grid, high-contrast composition
- **MOTION_INTENSITY**
  - `1-3`: hover, focus, pressed states only
  - `4-7`: reveals, stagger, restrained choreography
  - `8-10`: scroll-linked sequencing, magnetic motion, cinematic behavior
- **VISUAL_DENSITY**
  - `1-3`: airy, luxurious, gallery-like
  - `4-7`: balanced product UI
  - `8-10`: dense operational or telemetry surfaces

Default baseline:

- `DESIGN_VARIANCE = 6`
- `MOTION_INTENSITY = 4`
- `VISUAL_DENSITY = 4`

Adapt the dials to the product type, user request, and existing brand language.

## Clarification Rule

If missing information would materially change the implementation, ask exactly
one focused clarification question before proceeding.

Clarification triggers:

- no clear reference anchor
- no clear interface type
- unclear motion intensity
- unclear device priority
- unclear requirement to preserve an existing brand or design system
- no usable design context for a net-new design task

Use `AskUserQuestion` if available. If not, ask the same question in plain
text. Prefer multiple-choice framing. Ask one thing at a time.

When no brand or style is specified, proactively recommend 2-3 anchors from
`design-md/` based on page type and product tone. Example question patterns:

- "Which direction should we anchor to: a specific brand in `design-md/`, a
  URL reference, or a mood description?"
- "Is there an existing brand or design system I must preserve?"
- "What is the best starting context: existing repo UI, screenshots, a design
  system, or should I choose an anchor and proceed?"

Skip clarification only when:

- the repo already has a strong design system
- the user explicitly says to choose the direction
- the missing detail would not meaningfully change the implementation

If you proceed without asking, state the assumption first.

## Workflow

### 1. Align

1. Identify page type, audience, and technical constraints.
2. Confirm framework and styling stack before importing dependencies.
3. If direction is ambiguous enough to change the build, ask one question.
4. Inspect the most relevant existing UI context first: local components,
   screenshots, route shells, design-system docs, or brand references.
5. If the user names a brand or style, immediately load
   `design-md/<brand>/DESIGN.md` and treat it as authoritative.
6. If no brand is named, recommend 2-3 anchors from `design-md/` based on page
   type and product tone, then load the chosen anchor.
7. If no anchor fits, summarize the intended style as a visual thesis before
   building.
8. When offering options, recommend 2-3 concrete directions max.

### 2. Plan

1. Break the UI into sections and reusable components.
2. Decide which sections need motion, which need static polish, and which need
   supporting media.
3. Set the three design controls.
4. Prefer the smallest toolset that can still deliver the effect.
5. Decide whether the task is best handled as direct implementation, a focused
   design study, or a clickable prototype.

### 3. Read References

Load only what the task needs:

- layout, hero composition, hierarchy, section rhythm ->
  `references/composition-playbook.md`
- motion, reveal choreography, stagger, scroll behavior ->
  `references/motion-recipes.md`
- redesigning an existing page or app -> `references/redesign-audit.md`
- media generation -> `references/asset-prompt-guide.md` first, then the
  currently supported toolchain docs; prefer the installed toolchain (e.g. `mmx-cli`)
- tooling trouble -> `references/troubleshooting.md`,
  `references/env-setup.md`

### 3.5. Acquire Context Before Freehanding

- Prefer code and design context over screenshots alone when both exist.
- When editing an existing product, inspect the visual vocabulary before making
  changes: hierarchy, spacing, color roles, radius, borders, shadows, motion,
  copy tone, and density.
- When the repo lacks enough context, explicitly anchor to one of:
  `design-md/`, a provided reference, or a written visual thesis.
- Treat full freehand invention as the last resort, not the default.

### 4. Build

- write responsive, accessible, production-ready UI
- integrate real copy, local assets, and intentional motion
- preserve the existing system when working inside a product
- redesign in place unless the user explicitly asks for a rebuild
- when the task is exploratory, keep variants easy to compare inside the same
  implementation path unless separation is clearly cleaner
- check `package.json` before introducing any new dependency
- do not mix Tailwind v3 and v4 syntax
- keep interactive or animation-heavy behavior inside the correct client
  boundary when using React or Next.js

### 5. Verify

- run quality gates before delivery

## DESIGN.md Consumption

Treat `design-md/` as the authoritative style library.

Each `DESIGN.md` may contain two layers:

1. YAML front matter for machine-readable tokens
2. Markdown body for rationale and application guidance

Each `DESIGN.md` typically covers these areas:

1. Visual Theme and Atmosphere
2. Color Palette and Roles (hex values with semantic names)
3. Typography Rules (families, sizes, weights, line-heights)
4. Component Stylings (buttons, cards, inputs with exact specs)
5. Layout Principles (spacing scale, grid, container)
6. Depth and Elevation (shadow system)
7. Do's and Don'ts (explicit design constraints)
8. Responsive Behavior (breakpoints and collapsing)
9. Agent Prompt Guide (reusable component prompts)

Extract and apply all relevant sections systematically, not just color and
typography.

When YAML exists:

- read tokens first for exact colors, typography, spacing, radius, and
  component defaults
- treat tokens as normative values
- use prose for tone, hierarchy, composition philosophy, and edge cases
- if prose and tokens conflict, follow tokens for exact values and prose for
  intent, then note the ambiguity

When the user does not specify a brand or style:

1. ask for direction if needed
2. recommend 2-3 anchors max
3. load the chosen `DESIGN.md`
4. extract the core token set if YAML exists
5. build against that anchor instead of freehanding the aesthetic

## Exploration Modes And Variations

Choose the working mode by the actual problem:

- purely visual direction work -> produce tightly scoped visual comparisons
  rather than a bloated full app shell
- interaction, flow, or concept exploration -> prefer a realistic clickable
  prototype or end-to-end implemented slice
- direct product implementation -> ship the chosen direction cleanly instead of
  over-optimizing for breadth

When the user wants options:

- vary 2-4 meaningful dimensions max: layout, typography, color treatment,
  motion language, or interaction model
- start with one direction that stays close to the existing product language,
  then expand into bolder alternatives
- make variants comparable; avoid creating unrelated designs with no shared
  evaluation frame
- if a single code path can support comparison cleanly, prefer toggles, props,
  or structured variants over fragmented duplicate files
- if a design needs multiple files, name them clearly and preserve the prior
  revision when making a major directional change

## Design Rules

### Typography

- Use distinctive display and body pairings.
- Avoid Inter, Arial, Roboto, and generic defaults unless the existing product
  already uses them.
- Match font personality to product tone.
- For dashboards and operational UI, avoid serif unless already established.
- Use monospace or tabular numerals for dense numbers and technical labels.

### Color And Surface

- Commit to one coherent palette with one accent color. See `craft/color.md` for palette structure, contrast min, and dark theme rules.
- Avoid pure `#000000`, purple-on-white AI gradients, and generic black shadows.
- Use CSS variables for token-driven consistency.

### Layout

- Prefer asymmetry, modular rhythm, or intentional negative space.
- If `DESIGN_VARIANCE > 4`, avoid centered hero compositions by default.
- Avoid the interchangeable centered hero plus three-card grid pattern.
- Treat the first viewport like a poster, not a document.
- Use sections, columns, dividers, lists, and media before defaulting to card
  grids.
- Use `min-h-[100dvh]` instead of `h-screen` for full-height hero sections.
- Collapse high-variance layouts aggressively to one column on mobile.

### Landing Pages

- Default flow: hero, support, detail, final CTA.
- Make the brand or product unmistakable in the first screen.
- Give the first viewport one dominant visual anchor.
- Avoid hero cards, logo clouds, stat strips, and floating fake dashboards by
  default.
- Keep the hero text column narrow and placed on a calm tonal area.

### Dashboards And Product UI

- Default to calm hierarchy, strong spacing, few colors, and minimal chrome.
- Organize around workspace, navigation, context, and one clear action accent.
- Prefer utility copy over marketing copy.
- If `VISUAL_DENSITY > 7`, prefer dividers, spacing, and alignment over
  generic cards.

### Copy And Imagery

- Write real copy. No lorem ipsum, fake brand names, generic people names, or
  empty hype language.
- Keep headlines concise and meaning-heavy.
- Make imagery do narrative work; decorative texture alone is not enough.
- Prefer real-looking, in-situ imagery over fake dashboards or abstract filler.
- Avoid emojis in UI copy, alt text, and interface chrome unless already part
  of the product language.
- If real assets are unavailable, use deliberate placeholders that make the
  intended structure obvious instead of low-credibility filler.

### Components

- Customize primitives so they belong to the chosen direction.
- Add loading, empty, error, hover, focus, and pressed states.
- Prefer visible labels above inputs.
- Aim for at least `44px` touch targets.

## Motion Rules

### Tool Choice

- CSS for simple hover, focus, and lightweight entrances
- Framer Motion for UI choreography and layout transitions
- GSAP for precise scroll sequencing only
- Three.js / React Three Fiber only when 3D materially improves the experience

### Guardrails

- Do not mix GSAP and Framer Motion in the same component tree.
- Animate `transform`, `opacity`, `filter`, and carefully chosen `clip-path`,
  not layout properties.
- Respect `prefers-reduced-motion`.
- Do not use React `useState` for magnetic hover or continuous motion.
- Keep perpetual or CPU-heavy animation in small leaf components.
- Keep `staggerChildren` parents and animated children in the same client tree.
- Use `IntersectionObserver`, `whileInView`, or scroll libraries instead of raw
  `window.addEventListener("scroll")`.
- Apply grain or noise overlays only to fixed, pointer-events-none layers.
- Clean up timers, scroll triggers, and effects.
- Remove ornamental motion with no hierarchy, affordance, or atmosphere value.

## Assets

Only generate media when it directly improves the frontend outcome.

Preferred execution path:

- use the currently installed, workspace-approved media generation toolchain
  first; `mmx-cli` is the preferred MiniMax path when available
- use the installed toolchain (e.g. `mmx-cli`); avoid script-based
  workflows that require separate environment setup

Asset rules:

- never ship placeholder media URLs
- save generated assets locally
- prefer WebP for images, compressed MP4 for video, normalized audio where
  relevant
- show prompts to the user before generation when the visual direction is
  sensitive
- keep commands reproducible and non-interactive when running generation in an
  agent workflow

## Output Integrity

- No placeholder comments such as `TODO`, `...`, or "same pattern".
- No skeleton output when full implementation is required.
- If the task asks for a full file or full component set, deliver the whole
  thing.
- If output must pause, stop at a clean breakpoint instead of compressing the
  rest into summaries.

## Prototype And Artifact Rules

Apply these when the deliverable is an HTML prototype, design study, or
standalone frontend artifact:

- choose a descriptive filename that reflects the screen or concept
- avoid giant monolithic files; split large artifacts into smaller components
  or support files when the structure starts hiding intent
- for major revisions, preserve the old version or make the variant boundary
  explicit so comparison is easy
- avoid fake title screens unless the user explicitly wants a presentation-like
  artifact
- keep the design centered on the interface itself, not decorative framing

## Escalation Rules

Pause and ask before:

- changing an established brand or design system in a major way
- adding motion or media that materially increases delivery risk
- shipping without responsive and accessibility validation

## Quality Gates

Before delivery, verify:

- responsive on mobile and desktop
- reduced-motion path handled
- loading, empty, and error states present when applicable
- no placeholder media URLs remain
- generated media saved locally
- heavy libraries justified and isolated
- code matches the intended aesthetic instead of a generic template
- first screen has one unmistakable visual anchor
- brand or product is unmistakable in the first screen
- each section has one job
- cards are used only when they earn their place
- no obvious filler, unfinished implementation, or generic slop remains
- when the UI is runnable, preview the implemented result rather than trusting
  static code inspection alone

### Anti-AI-Slop Checks

Run `craft/anti-ai-slop.md` as the quality gate before shipping. Covers:
indigo accent, trust gradients, emoji icons, wrong display fonts, AI
dashboard tiles, invented metrics, filler copy, and external placeholder CDNs.

## Final Output Contract

Every use of this skill should end with:

1. `Skill Fit`
2. `Primary Deliverable`
3. `Execution Evidence`
4. `Design System Alignment`
5. `Reference Evidence` - selected `design-md` anchor and any references loaded
6. `Risks / Open Questions`
7. `Next Action`

## References

Read only as needed:

- `references/composition-playbook.md`
- `references/motion-recipes.md`
- `references/redesign-audit.md`
- `references/troubleshooting.md`
- `references/asset-prompt-guide.md`
- `references/env-setup.md`

### Craft Rules

Brand-agnostic design craftsmanship. Read as needed during review:

- `craft/anti-ai-slop.md` — anti-AI-tell rules and quality gates
- `craft/color.md` — accent discipline, contrast, dark-theme rules
- `craft/typography-hierarchy.md` — hierarchy vectors, rhythm, controlled
  violations
- `craft/state-coverage.md` — loading, empty, error, edge, and form states
- `craft/accessibility-baseline.md` — WCAG 2.2 AA, ARIA, focus, labels
- `craft/laws-of-ux.md` — cognitive heuristics, decision-making, memory laws