| name | frontend-design-aesthetics |
| description | Optional frontend aesthetics, DESIGN.md, design-system, visual redesign, brand identity, accessibility, responsive UI, and anti-slop guidance. Use only for assigned UI aesthetics/design-system/visual redesign work or when the plan explicitly requests it. |
Frontend Design Aesthetics
Use this optional skill for UI-significant work where visual direction, design-system decisions, or aesthetic quality are in scope. It is project-specific guidance, not a global mandate for bold, extreme, or highly stylized interfaces.
Prefer the project's existing design language. If the project has a DESIGN.md, treat it as the source of truth.
DESIGN.md workflow
Before changing UI aesthetics or reusable design-system behavior:
- Look for
DESIGN.md at the workspace or project root.
- If it exists, follow it and note any conflicts with the assignment.
- If it is missing and the task is UI-significant, propose or create one only when assigned to do so.
- Update
DESIGN.md only when introducing a reusable token, component rule, brand rule, accessibility policy, or repeated anti-pattern.
- Do not update
DESIGN.md for pure copy edits, one-off experiments, or mechanical refactors with no reusable design impact.
Design reasoning workflow
Before implementation, form a compact design intent:
- Product category, audience, and primary user job.
- Interface pattern: marketing page, dashboard, form flow, editor, data-dense admin view, etc.
- Existing visual language and design-system constraints.
- Palette, typography, spacing, and motion choices that fit the product.
- Accessibility and responsive constraints.
- Anti-patterns to avoid for this product.
- One optional aesthetic risk, only if it serves the product and does not harm usability.
Practical guidance
- Reuse existing components before creating one-off markup.
- Use semantic tokens/classes when available.
- Keep visual complexity proportional to the product and assignment.
- Make typography, color, spacing, hierarchy, and motion support the user's task.
- Ensure contrast, keyboard focus, responsive layout, empty/loading/error states, and reduced-motion behavior are considered.
- Avoid generic choices that are not grounded in the product, such as unexplained gradients, meaningless badges/avatars, repeated metadata, or nested containers without semantic purpose.
UI construction anti-slop rules
- Translate references into concrete component anatomy and behavior before styling.
- Avoid
card > panel > card nesting unless each wrapper has a distinct semantic, layout, or accessibility job.
- Give cards/lists explicit sizing, overflow, clamping, and inter-item spacing behavior.
- Do not duplicate metadata already implied by layout, such as a status chip inside its own status column.
- For dialogs, verify opened-state layering against sticky headers, sidebars, and floating bars.
- Render rich text/Markdown in read mode unless the product is explicitly a source editor.
- Verify visual changes incrementally when practical, especially layout, modal, card, form, and responsive changes.
Pre-delivery checklist
DESIGN.md checked, updated, proposed, or intentionally skipped.- Existing components reused or extension/new component justified.
- Contrast is acceptable for text, buttons, links, and disabled states.
- Responsive behavior covers key widths when practical.
- Keyboard focus is visible and semantics are appropriate.
- Non-trivial motion respects
prefers-reduced-motion.
- Empty, error, and loading states have clear user-facing copy when affected.
- Visual choices are grounded in the project/product rather than generic defaults.
Output template
## DESIGN.md status
- Found/created/updated/proposed/skipped: <status and path/reason>
## Design intent
- Product/audience/job: <summary>
- Pattern/style: <chosen pattern and why>
- Visual identity: <palette, typography, spacing, motion, aesthetic risk if any>
## Component/token choices
- Components reused: `<path>` / none
- Tokens/classes used: <summary>
- DESIGN.md updates: <summary or `None`>
## Quality checks
- Contrast: pass/fail/not checked + notes
- Alignment/hierarchy: pass/fail/not checked + notes
- Responsiveness: pass/fail/not checked + notes
- Accessibility/focus: pass/fail/not checked + notes
- Motion/reduced-motion: pass/fail/not checked + notes
## Fixes applied or required
- `<path>` — <fix>
