Frontend Design System

Premise: Nothing on the page is accidental. Space is a feature. Decisions trace back to the person using the product. Working rule: Reason it out, don't recite it. When in doubt, ask.

Read Files Deliberately

One file is mandatory; the rest are a reference shelf, pulled in only when the work calls for them.

Audit Helpers

Run these against a project; they are tools, not reading material.

Resist the Reflex to Default

When a brief is loose, the easy move is to fall back on the same handful of "tasteful" choices. Don't.

If the brief leaves it open, ask: a color direction (cool / warm / neutral / bolder?), a style cue (pared-back / loud / retro / futuristic / organic?), a layout hint (single column / grid / asymmetric / edge-to-edge?).

Each "safe" pick nudges the result closer to a template. Choose the braver option more often than feels comfortable.

1. Pin Down the Constraints First

No visual decisions until these are answered (or asked):

Audience cues: Gen Z → loud, quick, mobile-native; Millennials → tidy, values-forward; Gen X → familiar, legible; Boomers → large type, strong contrast; B2B → credible, data-forward; Luxury → quiet confidence, lots of air.

2. Behavioral Foundations

The full treatment lives in ux-psychology.md; the shortlist:

Emotion runs on three layers — visceral (the gut reaction: color, imagery, vibe), behavioral (the using: speed, feedback, smoothness), reflective (the afterthought: "this says something about me"). Earn trust with security cues where stakes are high, real proof from others, easy access to help, consistency, and honest policies.

3. Layout, Color, Type, Effects, Motion — the Essentials

Each has a dedicated reference file; the load-bearing rules to keep in mind:

• Layout — Lean on the golden ratio (~62/38 splits) for balance and an 8px spacing rhythm. Keep text columns to 45–75 characters; size tap targets to be hit without precision.
• Color — Split roughly 60 / 30 / 10 (base / support / accent). Pick by industry then emotion, decide a light or dark base, and ask if it's unspecified. → color-system.md
• Type — Choose a modular scale (1.25 is the safe general pick; 1.5–1.618 for display). Pair faces that are distinct enough for hierarchy yet related enough to cohere. Body ≥ 16px, line height 1.4–1.6, contrast meets WCAG. → typography-system.md
• Effects — Use frosted glass, gradients, and shadows only with intent: shadows imply elevation (vertical offset, layered), gradients stay coherent (analogous or one hue), and the stock looks are clichés. → visual-effects.md
• Motion — Time it to distance, size, stakes, and mood. Ease-out to enter, ease-in to leave, ease-in-out for emphasis. Animate transform and opacity only, honor reduced-motion, test on weak hardware. → animation-guide.md, motion-graphics.md

4. Signals of a Standout Result

• Premium: real breathing room, quiet depth, smooth purposeful motion, tight alignment, a coherent rhythm, bespoke (not all-stock) touches.
• Trustworthy: security cues where they matter, genuine proof, one clear value proposition, quality imagery, a single consistent design language.
• Emotional: a hero that hits the intended note, a human presence, visible progress, small deliberate delights.

5. What to Avoid

• Phoned-in: default system fonts, mismatched stock photos, wandering spacing, clashing colors, undifferentiated walls of text, failing contrast.
• The generated look: the same palette every time, dark-plus-neon by reflex, purple as the automatic accent, bento grids on simple pages, mesh-gradient-plus-glow pileups, recycled layouts, never asking the user.
• Dishonest (never): hidden costs, fabricated urgency, inescapable actions, deceptive interfaces, guilt-tripping the exit.

6. The Loop, Condensed

On every design task:

1. CONSTRAINTS — time, brand, stack, audience? Unclear → ask.
2. CONTENT     — what exists, and what ranks highest?
3. DIRECTION   — what suits this context? Unclear → ask, don't default.
4. BUILD       — apply the principles; check against the anti-patterns.
5. REVIEW      — Does it serve the user? Is it different from my usual?
                 Would I put my name on it?

Where This Fits

After it's coded, run the web-design-guidelines skill to check accessibility, focus states, motion, and performance.

The throughline: design is reasoning, not duplication. Every project earns a fresh look at its own context and people. Steer wide of the default SaaS template.