ui-design

# UI Design

A design-quality reference for any visual output you produce. It exists to make that output look like it came from a research desk, not a marketing landing page or a generic AI template.

Read this **before** producing any styled output — it covers design taste: typography, color, composition, and restraint. The examples below are HTML/CSS (the most common surface), but the principles apply to any visual you render — charts and images, PDFs, on-screen layouts — not just HTML.

> **This skill exists to help you match the user's personal frontend style and UI preferences — those always win over the defaults below.** If the user has stated a taste — in this conversation, in your long-term memory, or in their saved preferences — it outranks every rule here. They want a specific brand color, a chosen font, a different accent, dark-only, no serif? Do that. The directions below are strong defaults for when the user hasn't expressed a preference; they are never a license to overrule the user's explicit style.

> **These are reference defaults, not a cage.** They anchor quality and steer you off generic, lazy output — they don't replace your own judgment. When you have a clearly better, coherent choice for the specific content, take it. The only non-negotiables are the hard constraints: WCAG AA contrast, green/red reserved for profit/loss, and the theme-variable + print mechanics. The specific palette, font pairings, and exact scale below are strong starting points you are free to improve on.

## The Tone: Research Desk, Not Marketing Page

The audience is a portfolio manager, analyst, or sophisticated investor reading a research note. They want **dense, scannable, credible** information design — the visual language of a sell-side note, a Bloomberg terminal, or a quality print newspaper's business section. Not a SaaS hero page.

This means:
- Information density over whitespace theatre. A research reader expects a high signal-per-screen ratio.
- Restraint over decoration. No hero gradients, no oversized rounded cards floating on pastel backgrounds, no "Get Started" energy.
- Numbers are the protagonist. Tables, figures, and charts carry the page; prose supports them.
- Credibility cues: sources cited, dates stamped, units labelled, precision consistent.

## Avoid AI Slop

These are the tells of generic AI-generated UI. Each one has a concrete replacement — use the "instead" column.

| Anti-pattern | Why it reads as slop | Instead |
|---|---|---|
| **Inter everywhere** (or system-font-only) for headings and body | The default AI font; signals zero typographic intent | Commit to a real pairing (see Typography). A serif or a distinctive grotesque for headings; a clean readable face for body. |
| **Purple/violet gradients** on white, or any gradient hero | The single most overused AI aesthetic | One flat accent color used sparingly. Backgrounds are paper (light) or ink (dark), not gradients. |
| **Uniform rounded card grids** — everything is a `border-radius: 16px` card with a drop shadow | Marketing-template look; wastes vertical space; flattens hierarchy | Use tables for tabular data, rules (hairline borders) to separate sections, and reserve cards for genuine KPI callouts. Small radius (4–8px) or none. |
| **Emoji as icons** (📈 💰 🚀 in headings/labels) | Looks unserious; breaks in print; inconsistent rendering | Use a real icon set sparingly (inline SVG, e.g. lucide), or just clean typographic labels. Most research UIs need no icons at all. |
| **Rainbow categorical charts** — 8 saturated hues with no logic | Looks like a default Chart.js palette; hard to read; no semantic meaning | A restrained sequential or single-hue-with-tints palette; reserve green/red strictly for profit/loss. Max 3-4 categorical colors, muted. |
| **Centered everything** with huge top margins | Landing-page composition; poor for scanning data | Left-aligned reading column, tables flush, consistent baseline grid. |
| **Generic stock-photo-style placeholder vibes** — giant empty cards, "Lorem"-feeling filler | Signals the content wasn't really designed | Fill with real numbers and real findings; size containers to the actual content. |

## Typography

**Commit to an intentional pairing** — a real headline voice plus a clean body face, loaded from the Google Fonts CDN (allowlisted). The three below are proven starting points: pick one, use the user's brand font, or choose your own with the same level of intent. What matters is the commitment — don't fall back to Inter-everywhere or the bare system stack.

### Pairings that work (starting points)

1. **Editorial / authoritative** — headings `"Source Serif 4", Georgia, serif`; body `"Inter", -apple-system, sans-serif`. Serif headings give a print-research feel; body stays clean and readable. (The only acceptable use of Inter: as the *body* of a serif-headed document — never as the headline voice.)
2. **Modern terminal** — headings & body `"IBM Plex Sans", system-ui, sans-serif`; figures/tables `"IBM Plex Mono", monospace`. Plex reads as engineered and precise; the mono companion makes numeric tables align beautifully.
3. **Refined grotesque** — headings `"Newsreader", Georgia, serif` (a true reading serif) or `"Libre Franklin", sans-serif`; body `"Libre Franklin", sans-serif`. Franklin is a workhorse news face with more character than Inter.

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Source+Serif+4:opsz,wght@8..60,400;8..60,600&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
```

### Type scale

A real, restrained scale (ratio ~1.25) keeps sizing coherent. The values below are a sensible default — whatever scale you use, keep it consistent rather than sizing ad-hoc.

```css
--text-xs: 0.75rem;   /* 12px — captions, source lines, table headers */
--text-sm: 0.875rem;  /* 14px — secondary text, dense table