# Frontend Design Discipline

When building UI, follow these calibration prompts. They are **not absolute
rules** — the user's explicit instructions always override them. They exist
because UI failure modes are visible: a technically-correct page can still
look like a template, and a vision-enabled review will surface the drift to
the user before you do.

## When this discipline applies vs. when it does NOT

This applies when the agent is choosing visual decisions (typography,
palette, layout, copy register) for a UI build or significant redesign.

It does NOT override:
- The user's explicit style choices ("use Cormorant + Inter for this
  editorial book site" — follow the brief, don't fight it)
- An existing design system in the codebase (match the existing tokens,
  don't impose new palette/fonts on a half-styled app)
- Brand guidelines or Figma exports provided as source-of-truth
- One-line changes / tiny edits — the discipline content is overhead

When the user has named the genre and style, the agent's job is to execute
the brief cleanly, not to override taste.

## 1. Audience and genre first

A UI's job depends on its genre:

| Genre | What success looks like |
|---|---|
| Personal portfolio (artist, designer, photographer) | Work is the hero. Image-led, editorial, voice-driven |
| Personal portfolio (writer, academic) | Typography is the hero. Editorial, restrained, voice-driven |
| SaaS / product landing | Clear value prop, social proof, conversion path. Stat cards / metrics CAN be the right pattern here |
| B2B / enterprise marketing | Authoritative, dense, footnoted. Often dark or muted palettes |
| Admin / internal dashboard | Information density, data viz, fast scanning. Cards and tables are correct |
| Editorial / publication | Typography hierarchy, reading-flow optimized, white space generous |
| Local business (restaurant, shop) | Practical info first: hours, menu, location. Photos for atmosphere |
| Documentation | Search, scannable headings, code blocks, dark/light parity |

Match the register to the audience. A young person's site should not read
as a SaaS landing page; a dashboard should not read as an editorial
magazine.

## 2. Check against the AI-tells for your specific genre

The most-overused AI-generated **portfolio** template is the combination of
all of these together:

- Cormorant Garamond (or Playfair Display) + Inter typography
- Cream / off-white background (`#FAFAF8`-ish) + forest or sage green accent
- Stat cards in the hero ("4+ Awards / Founder / 1st Place")
- Vertical award timeline with dots and years
- Max-width 1200px contained grid as the only layout primitive
- `border-radius: 8px` on every surface
- 🏆 / ★ / 🦜 emoji sprinkles on achievements
- Subtle drop shadows + slight `translateY(-2px)` hover lift

If you're building a **portfolio** and reach for 3+ of these without
intentional reason, you've drifted to the template. Choose differently.

For **other genres**, this specific list does NOT apply. A SaaS landing
page legitimately uses stat cards in the hero. A B2B dashboard uses
border-radius and shadows as design-system tokens. An editorial blog can
use Playfair-style display serifs with Inter body without being template-y.

For your genre, ask: what are MY genre's overused defaults? Which patterns
do every cookie-cutter site in this space reach for? Check yourself against
THAT list, not against the portfolio list above.

## 3. Image-led for visual content

When the subject's work IS images (artists, photographers, designers,
illustrators):

- One large, generous image beats four small grid cards
- Break the grid for the strongest piece — let it bleed full-width if it earns it
- A 320px hero portrait above a 4-col artwork grid is wrong — the art should
  be bigger than the artist's face
- Negative space around the strongest piece is part of the design

For text-led content (essays, manifestos, docs), the inverse: typography is
the hero, images support.

## 4. Earn every UI component

Don't add stat cards, vertical timelines, pull-quotes, testimonial walls,
"by the numbers" sections, or feature grids by reflex.

Each should pass: would this section exist in a thoughtfully-designed
analog version of this site (printed monograph, gallery placard, zine,
brochure, internal dashboard, technical doc)? If not, cut it.

Borrowing resume sections for an artist portfolio is one specific failure
mode of this rule. Borrowing SaaS sections for an internal tool is
another. The rule is genre-agnostic: only build sections the content needs.

## 5. Reference before you type

For non-trivial UI, name 2-3 real-world sites whose register matches the
audience and explain what you're borrowing in one sentence each. "I'm
drawing on [X]'s editorial scale and [Y]'s color restraint." Then build.
This forces a point of view.

Good reference categories by genre:

- **Artist / photographer portfolio**: Are.na, Cargo, Tobias van Schneider, Index Magazine
- **Musician portfolio**: hillaryhahn.com, artist label sites
- **Family / personal site**: warm, illustrative, voice-driven personal sites
- **SaaS landing**: Linear, Stripe, Vercel
- **B2B / enterprise**: Salesforce, ServiceNow, modern enterprise marketing
- **Internal dashboard**: Linear app UI, Vercel dashboard, Notion
- **Editorial / writing**: The Pudding, Aeon, Craig Mod's site
- **Documentation**: Stripe docs, Tailwind docs, Vercel docs
- **Local business**: thoughtful single-page restaurant/cafe sites — not Square/Wix defaults

## 6. Look at what you built

Before claiming done, screenshot the page and self-critique. The
`browser_screenshot` tool is wired in:

```
browser_screenshot({ url: "file:///path/to/index.html", viewport: "desktop" })
browser_screenshot({ url: "file:///path/to/index.html", viewport: "mobile" })
```

(or `http://localhost:<port>` if you have a dev server.) Then READ the
PNGs the tool returns and check, calibrated to your audience:

- Audience fit: does the register match who this is for?
- Image-to-text ratio: appropriate for the content type?
- Visual rhythm: are sections varied, or rhythmically identical?
- Mobile: layout holds up at 390px wide — no clipping, no overflow?

If `browser_screenshot` returns `{ ok: false }` (e.g., no Chrome installed),
say so explicitly in the summary — don't pretend you verified. "Page
rendered correctly to my mental model but I had no browser to confirm" is
honest; silent assumption is not.

## 7. Voice in copy

If you write any copy (headings, taglines, bios), write it specifically for
this subject. "Award-winning artworks exploring nature, wildlife, and the
ocean" could describe anyone. Use the user's brief to anchor copy in
concrete details — name the actual subject of one piece, quote a real
moment, reference a place.

If you don't have voice material, leave clear placeholders like
"WRITE A REAL BIO HERE — needs the subject's own sentences" rather than
inventing plausible-sounding filler. Generic AI-generated copy is one of
the most visible drifts a vision-enabled review will catch.
