Frontend Design

Frontend Design

Design Rules

• Less is more! Do not add buttons that don't have a purpose. Do not add text that is not strictly required.
• Hide implementation details. If the user asked you to add caching, retries, batching, normalization, fallbacks, or any other under-the-hood mechanic, do not surface that mechanic in the UI. Internal labels like "smart cache: months already pulled are skipped", "fetching last 60 days…", "months ok / months empty / sources", or tooltips that explain how the backend works belong in code comments, not in user-facing copy. The interface should describe what the user sees and can do — not how the system achieves it. Strip such phrasing on first pass; add neutral, outcome-focused copy instead (e.g. "loading data…", "available data: ").
• Never allow buttons to overlap or overflow.
• Never allow words to break in the middle or text to get cut off by a container edge. If content needs more room, resize, reflow, or restack the layout instead of letting typography fail.
• Keep related form controls visually flush. When neighboring controls have labels of the same role or expected text height, their input boxes/buttons should share the same top and bottom edges; reserve equal label height or restructure the row instead of letting one control stagger lower.
• Make attached UI fit its anchor. Date pickers, dropdowns, menus, and popovers should align flush to the control or panel they belong to, sharing a clean edge and width when that is the natural relationship. If an overlay covers a table, chart, or panel, its placement should look intentionally docked to that surface instead of arbitrarily floating over it.
• Keep related status/action controls on one horizontal line when there is room. Use flexible text and identical square icon buttons to preserve rhythm instead of adding vertical space just because the viewport changed.
• If there is space make sure it's tasteful and symmetrical. For example, don't allow one section in the page to feel dense and small while there is plenty of space in another. Spread things out intelligently.
• Preserve the last successful UI while data refreshes whenever it is technically possible. Do not replace populated charts, tables, or controls with an empty/loading placeholder during a routine refresh; keep the old data visible, mark the section as updating, then swap in new data when it arrives. Use empty states only before the first successful load or after a real failure with no usable prior state.
• Keep state changes self-contained and quiet. A button appearing, a picker opening, a zoom reset becoming available, or a data refresh should not casually re-scroll the page, move the viewport, add surprise height, or create visual noise. Use the smallest clean control that fits the existing composition unless there is a deliberate reason to move things.
• Use real, production-grade code. Do not produce mockup-only markup.
• Avoid generic AI aesthetics: default system fonts, Inter-heavy layouts, timid color palettes, purple-on-white gradients, boilerplate cards, and interchangeable hero sections.
• Do not add gradients unless the user explicitly asks for one. Prefer minimal, flat UI surfaces with deliberate contrast, spacing, borders, and typography.
• Default to a minimal, uncluttered aesthetic. Keep the composition calm and not busy — every element must earn its place, and when in doubt, remove.
• Emphasize with size, not volume. The most important message should be the largest thing on screen; lead with big, confident type and resist shrinking key points into small text. Build a bold, deliberate type scale so the hierarchy reads at a glance.
• Add motion where it matters: staged entrances, hover states, panel transitions, scroll reveals, or emphasis moments. Prefer a few strong gestures over constant micro-animation.
• Keep the result responsive, accessible, and legible on desktop and mobile.

Implementation

• Start by naming the visual concept in one sentence, then implement toward that concept.
• Define reusable tokens first: colors, spacing, radii, shadows, motion timing, and type scale.
• Make states feel finished: hover, focus, active, disabled, loading, empty, and error.
• Use meaningful content hierarchy and spacing. Tighten copy, labels, and density so the UI feels intentional.
• When the work involves writing or substantially revising user-facing copy — headlines, body, marketing, or informational text — consult the content-generator skill instead of improvising prose.
• For React projects, follow the repo's conventions and modern patterns already in use.
• When introducing third-party fonts or assets, do so only when the environment supports them cleanly.

Quality Bar

Before finishing, check the result against this bar:

• The interface has a clear point of view.
• The typography feels chosen, not defaulted.
• The layout has at least one memorable compositional decision.
• The color and background treatment create atmosphere.
• The interactions feel deliberate.
• Every element is deliberate — nothing is left at framework defaults, decorative by accident, or default by omission.
• It passes the eye test: a screenshot looks and feels genuinely good — striking, dynamic, and inviting — not merely structurally correct.
• The implementation is complete enough to run, not just look good in a screenshot.

Direction from Scratch

If creating a new design, decide the visual direction before coding.

• Define the product purpose, audience, and tone.
• Choose or note a memorable aesthetic axis and commit to it: editorial, brutalist, playful, industrial, luxe, retro-futurist, organic, toy-like, minimal, maximal, or another clear direction.
• Identify the one thing a user should remember after seeing the interface.
• Preserve an existing product language when the repo already has one. Do not force a new aesthetic onto an established system.
• Use distinctive typography. Pair a display face with a readable body face when the stack allows it.
• Use a deliberate palette with CSS variables.
• Use asymmetry, overlap, negative space, or density intentionally. Make the layout feel designed, not assembled.