docs: add .impeccable.md design context file

Co-Authored-By: Claude <noreply@anthropic.com>

Author: vinta

.impeccable.md

@@ -0,0 +1,97 @@
+# 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.