awesome-python/.impeccable.md

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) applied via .section-shell. This is the ONLY width cap in the project. Widescreen monitors are the default viewing context.
• Do NOT add max-width to sections, cards, table cells, table rows, expanded rows, CTA backgrounds, sponsor descriptions, hero subcopy, paragraphs, or list items. The user has removed narrow inner caps repeatedly (56ch, 65-75ch, etc.). Default is no inner cap.
• The impeccable skill reference rule "cap line length at ~65-75ch" does NOT apply here. Ignore it. Readability at wide widths is carried by vertical rhythm, leading, and the modular type scale instead.
• If you believe a width cap is actually necessary for some specific element, ask first with a concrete reason before adding it.
• 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.