# Design Context

awesome-python.com is a searchable, filterable index of ~650 curated Python projects. It is a reference tool, not a landing page and not a GitHub README mirror.

## Users

Working Python developers (mid to senior). They already write Python daily and arrive with a specific question in mind: "what's a good HTTP client these days", "is there still a maintained ORM for X", "what are people using for task queues now". Secondary readers: polyglot developers evaluating Python's ecosystem, and curious browsers.

Jobs to be done:

1. Find a library for a specific need fast (search + tag filter).
2. Compare candidates at a glance (stars, last commit, tags, one-line description).
3. Confirm a project is alive before clicking through.

These users skim. They reward density and terse copy. They penalize marketing fluff.

## Brand Personality

Three words: **opinionated, confident, dense**.

Voice:

- Editorial. Every word earns its place.
- Confident, not combative. "This is the list" energy, not "check out these cool projects".
- No hype. The content is what's interesting.
- Calm authority. Closer to a well-edited technical reference (O'Reilly index, The Economist briefing, a good man page) than a blog or product site.

Emotional goals: trust, efficiency, craft. The reader should feel the list was edited by someone with taste, find what they need in seconds, and notice the typographic care as a signal that the curation is careful too.

## Aesthetic Direction

Stay close to the current direction. It works.

- Warm editorial palette in OKLCH. Cream/ivory page, dark earthy hero, warm brown-red accent near `oklch(58% 0.16 45)`.
- Type pairing: `Cormorant Garamond` (serif display, 600) with `Manrope` (sans body, 400/600/700/800). Do not swap.
- Magazine-cover scale for the main headline (`clamp(4.5rem, 11vw, 8.5rem)`), then a tight modular scale for the rest.
- Textured hero: subtle grid, slow sheen, warm radial gradients. Respect `prefers-reduced-motion`.
- Light theme only (`color-scheme: light`). No dark mode toggle, no alternate palettes.
- Table-driven index (sticky header, sortable columns, expandable rows). Not a card grid.
- Dark warm charcoal footer, part of the same system.

References (what to stay close to):

- Magazine reference pages (The Economist, FT Weekend, Monocle).
- Field-guide books. Curated, functional, hand-made.
- Library card catalogs. Dense tabular information, excellent typography, no decoration for decoration's sake.

Anti-references (avoid strictly):

- Generic dark developer-tool look. No cyan on near-black, neon gradients, VSCode-palette dashboards, terminal-green monospace branding.
- Other awesome-* sites. No plain README dumps, bare lists of links, no voice.
- SaaS marketing pages. No big metric counters, testimonial cards, feature grids, pricing tiers, or "join 10,000+ developers" social proof bands.

## Design Principles

1. **The list is the hero.** Hero, sponsor band, and CTA exist, but they must not compete with the table for attention.
2. **Density is a feature.** Prefer tables and tight rhythm over giant cards with one fact each. Mid-senior developers want to see more at once.
3. **Editorial typography over decoration.** Visual interest comes from the serif/sans pairing, type hierarchy, and whitespace. Not from gradients, shadows, badges, or icon boxes above headings.
4. **Warm, not cool.** Neutrals tint toward warm hues (roughly 55 to 80 in OKLCH). Pure grays and cool blues do not belong.
5. **One point of view.** No dark mode, no theme picker, no alternate palettes. Consistency signals curation.

## Implementation Rules

The project already follows these. Future work must keep them.

Layout and sizing:

- Keep existing `--shell-max: 84rem` (~1344px). Do not drop below 1280px for the main column.
- Body type floor is 16px (`--text-base: 1rem`). Content-heavy passages may go to 1.125rem.
- Adjacent heading levels differ by at least 0.25rem of rendered size.

Color:

- Use OKLCH for any new color. Not HSL, not hex.
- Accent colors (`--accent`, `--accent-deep`) only on interactive elements.
- Tags, badges, pills, inline code, source badges use `--ink-muted`, `--ink-soft`, or `--bg-paper-strong`. Never the accent.

CSS hygiene:

- CSS custom properties for all colors and repeated values.
- `rem` for spacing and type. `px` only for borders and shadows.
- `gap` over child margins in flex and grid.
- Logical properties (`margin-inline`, `padding-block`) over physical (`margin-left`, `padding-top`).
- Never `!important`. Fix specificity instead.
- Never `text-transform`. Write the casing in the markup.
- Sibling components (card lists, grid items) share identical spacing.

Absolute bans (from the impeccable skill):

- No `border-left` or `border-right` greater than 1px as a colored accent stripe on cards, list items, callouts, or alerts. Use a different structure.
- No gradient text (`background-clip: text` on gradients). Solid color only.
- No glassmorphism as default decoration.
- No bounce or elastic easing. Real objects decelerate smoothly.

## Verification

After any frontend change, use the `playwright-cli` skill to visually verify in a real browser. Check layout, responsiveness, and interactive behavior. Do not claim a UI change works based on code alone.