/frontend-design

name: frontend-design
description: "Build production-grade frontend interfaces with distinctive aesthetics and working code. Use for UI components, pages, or frontend features. Don't use for backend/API work or usability-only audits."
license: MIT
effort: high
metadata:
  version: 1.4.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Frontend Design

Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with deliberate aesthetic choices.

When to Use

Trigger this skill when the user asks to:

• Build a UI component, page, or full frontend application
• Design or implement a frontend feature (navigation, forms, data tables, dashboards)
• Redesign an existing interface for better aesthetics or usability
• Convert a mockup, wireframe, or spec into working code

Instructions

1. Record the **explicit brief**: any style preference, color palette, brand kit, or style direction the user gives. If there is none, the Default Style Guide applies. 2. If the request does not state the purpose and the target audience, ask for them before writing code. 3. If the work extends an existing codebase, read its framework, CSS variables, and component patterns before proposing anything. 4. Propose an aesthetic direction (*Design Thinking*). In an existing codebase, also list the files you will create or modify. Emit the Design Thinking step report. 5. Wait for the user to approve the direction before writing code. If the user asks for changes, propose again. If the user says "just build it", state the direction in one line and continue. If the user ends the run without approving, end with a `BLOCKED` Final Report. 6. Read `references/aesthetics-guide.md` and the Quick rules in `references/usability-guide.md`. Run *Repo Sync Before Edits*. Then implement the code. Add a short comment at each non-obvious design decision (font pairing, palette mapping, motion timing). 7. Run the verification checks:

• **Responsive:** if a browser tool is available, render at 375, 768, and 1280 px and check for horizontal overflow. Otherwise, inspect the breakpoints in the CSS and record responsive rendering as untested.
• **Contrast:** compute the contrast ratio of each text and background color pair. Each must be at least 4.5:1, or 3:1 for text at 24 px or larger (18.66 px or larger when bold).
• **Quality and usability:** walk the Default Quality Bar checklist and the six usability Quick rules.
• **Build:** if the project has a build, lint, or test command, run it and record the exit result. Otherwise record `build: not run (no command)`.

8. If a check fails, fix it and re-run that check. After the second fix cycle, stop fixing and list each remaining failure in the Final Report. 9. Emit the Implementation step report, then the Final Report.

Repo Sync Before Edits (mandatory)

Run this once, before the first file write in step 6. The sync target is the directory the code is written to.

1. Run `repo="$(git -C "<target dir>" rev-parse --show-toplevel)"`. If it fails, skip the sync and record `sync: skipped (not a git repo)`. 2. Run `git -C "$repo" remote get-url origin`. If it fails, skip steps 3–7 and record `sync: skipped (no origin)`. 3. Run `branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)"`. If it prints `HEAD`, skip steps 4–7 and record `sync: skipped (detached HEAD)`. 4. Run `git -C "$repo" status --porcelain`. If the output is empty, run `git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch"`. 5. If the output is not empty, run `git -C "$repo" stash push -u -m "frontend-design pre-sync"`, then the same fetch and pull, then `git -C "$repo" stash pop`. 6. If `fetch` or `pull` fails before a rebase starts (network, authentication, or a missing remote branch), do not retry. Run `git -C "$repo" stash pop` when step 5 stashed, record `sync: failed (<first error line>)`, and continue. 7. If the rebase conflicts, run `git -C "$repo" rebase --abort`, then `git -C "$repo" stash pop` when step 5 stashed. If the stash pop conflicts, leave the stash in place. In both cases write no file; stop and ask the user how to continue. With no answer, the status is `BLOCKED`.

This skill commits nothing.

Design Thinking

Before coding, identify the active style source and commit to a clear aesthetic direction:

• **Brief precedence**: With an explicit brief, follow it. Without one, the Default Style Guide below is binding: keep its four core colors (with the text-only status-color exception) and its elegant, clear, clean, professional language; make the result distinctive through composition, typography, spacing, depth, and motion rather than extra core colors.
• **Purpose**: What problem does this interface solve? Who uses it?
• **Tone**: With an explicit brief, honor its direction. Without one, choose from directions such as brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, or industrial/utilitarian, and only when the direction stays compatible with the Default Style Guide.
• **Constraints**: Technical requirements (framework, performance, accessibility).
• **Differentiation**: Name the one thing someone will remember about this interface.

Bold maximalism and refined minimalism both work when they fit the active style source; the key is intentionality, not intensity.

Default Style Guide

When the user gives no explicit brief, apply this style guide:

1. **Color Palette (Strictly Limited):** Use only four core colors — Black (`#000000`), White (`#FFFFFF`), Gray (`#6B7280`), and Bright Green (`#22C55E`). 2. **Aesthetic:** Maintain an elegant, clear, clean, and professional design language. 3. **Visual Depth:** Incorporate visual depth using elements like cards, lines, borders, and subtle shadows. 4. **Bright Green Usage Constraint:** The Bright Green color is strictly reserved for highlights (text,