From 6c0b0e375a1dceb974a951812bc3f58a47b09337 Mon Sep 17 00:00:00 2001 From: Vinta Chen Date: Mon, 20 Apr 2026 00:46:14 +0800 Subject: [PATCH] docs: add .impeccable.md design context file Co-Authored-By: Claude --- .impeccable.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 .impeccable.md diff --git a/.impeccable.md b/.impeccable.md new file mode 100644 index 00000000..2fd685ea --- /dev/null +++ b/.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.