78 lines
7.7 KiB
Markdown
78 lines
7.7 KiB
Markdown
# Design Guidance
|
|
|
|
Ported from forks/impeccable/skill/SKILL.src.md. Substantive design rules preserved verbatim; provider-specific tags and placeholder syntax removed.
|
|
|
|
## General rules
|
|
|
|
### Color
|
|
|
|
- **Verify contrast.** Body text must hit >=4.5:1 against its background; large text (>=18px or bold >=14px) needs >=3:1. Placeholder text needs the same 4.5:1, not the muted-gray default. The most common failure: muted gray body text on a tinted near-white. If the contrast is even close, bump the body color toward the ink end of the ramp; light gray "for elegance" is the single biggest reason AI designs feel hard to read.
|
|
- Gray text on a colored background looks washed out. Use a darker shade of the background's own hue, or a transparency of the text color.
|
|
|
|
### Typography
|
|
|
|
- Cap body line length at 65-75ch.
|
|
- Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights.
|
|
- Hero / display heading ceiling: clamp() max <= 6rem (~96px). Above that the page is shouting, not designing.
|
|
- Display heading letter-spacing floor: >= -0.04em. Anything tighter and letters touch; cramped, not "designed".
|
|
- Use `text-wrap: balance` on h1-h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans.
|
|
|
|
### Layout
|
|
|
|
- Vary spacing for rhythm.
|
|
- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
|
|
- Flexbox for 1D, Grid for 2D. Don't default to Grid when `flex-wrap` would be simpler.
|
|
- For responsive grids without breakpoints: `repeat(auto-fit, minmax(280px, 1fr))`.
|
|
- Build a semantic z-index scale (dropdown, sticky, modal-backdrop, modal, toast, tooltip). Never arbitrary values like 999 or 9999.
|
|
|
|
### Motion
|
|
|
|
- Motion should be intentional, and not be an afterthought. Consider it as part of the build.
|
|
- Don't animate CSS layout properties unless truly needed.
|
|
- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
|
|
- Use libraries for more advanced motion needs (e.g. motion, GSAP, anime.js, Lenis etc).
|
|
- Reduced motion is not optional. Every animation needs a `@media (prefers-reduced-motion: reduce)` alternative: typically a crossfade or instant transition.
|
|
- Staggering the items within one list is legitimate. The tell is the uniform reflex (one identical entrance applied to every section), not motion itself; each reveal should fit what it reveals. Suppressing the reflex is never a reason to ship a page with no motion at all.
|
|
- Reveal animations must enhance an already-visible default. Don't gate content visibility on a class-triggered transition; transitions pause on hidden tabs and headless renderers, so the reveal never fires and the section ships blank.
|
|
- Premium motion materials are not just transform/opacity. Blur, backdrop-filter, clip-path, mask, and shadow/glow are part of the palette when they materially improve the effect and stay smooth.
|
|
|
|
### Interaction
|
|
|
|
- Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context.
|
|
|
|
## New projects only (when no prior work exists)
|
|
|
|
### Color & Theme
|
|
|
|
- Use OKLCH.
|
|
- **The cream / sand / beige body bg is the saturated AI default of 2026.** The whole warm-neutral band (OKLCH L 0.84-0.97, C < 0.06, hue 40-100) reads as cream/sand/paper/parchment regardless of what you call it. Token names like `--paper`, `--cream`, `--sand`, `--bone`, `--flour`, `--linen`, `--parchment`, `--wheat`, `--biscuit`, `--ivory` are tells in themselves. If the brief is "warm, traditional, family-coastal-Italian" or "magazine-warm" or "editorial-restraint", DO NOT translate that into a near-white warm-tinted bg; that's the AI move. Pick: (a) a saturated brand color as the body (terracotta, oxblood, deep ochre, near-black), (b) a true off-white at chroma 0 (or chroma toward the brand's own hue, not toward warmth-by-default), or (c) a darker mid-tone tinted neutral that's clearly the brand's own. "Warmth" in the brand is carried by accent + typography + imagery, not by body bg.
|
|
- Tinted neutrals: add 0.005-0.015 chroma toward the brand's hue. Don't default-tint toward warm or cool "because the brand feels that way"; that's the cross-project monoculture move.
|
|
- When picking a theme: Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
|
|
- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
|
|
- **Restrained**: tinted neutrals + one accent <=10%. Product default; brand minimalism.
|
|
- **Committed**: one saturated color carries 30-60% of the surface. Brand default for identity-driven pages.
|
|
- **Full palette**: 3-4 named roles, each used deliberately. Brand campaigns; product data viz.
|
|
- **Drenched**: the surface IS the color. Brand heroes, campaign pages.
|
|
|
|
## Absolute bans
|
|
|
|
Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
|
|
|
|
- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
|
|
- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
|
|
- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
|
|
- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliche.
|
|
- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
|
|
- **Tiny uppercase tracked eyebrow above every section.** The 2023-era kicker (small all-caps text with wide tracking, "ABOUT" "PROCESS" "PRICING" above each heading) is now the saturated AI scaffold. One named kicker as a deliberate brand system is voice; an eyebrow on every section is AI grammar. Choose a different cadence.
|
|
- **Numbered section markers as default scaffolding (01 / 02 / 03).** Numbers earn their place when the section actually IS a sequence (a real 3-step process, an ordered flow, a typed timeline) and the order carries information the reader needs. One deliberate numbered sequence on one page is voice; numbered eyebrows on every section across the site is AI grammar.
|
|
- **Text that overflows its container.** Long heading words plus large clamp scales plus narrow grids cause headline overflow on tablet/mobile. Test the heading copy at every breakpoint; if it overflows, reduce the clamp max or rewrite the copy.
|
|
|
|
## The AI slop test
|
|
|
|
If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
|
|
|
|
**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
|
|
|
|
- **First-order:** if someone could guess the theme + palette from the category alone, it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
|
|
- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream, editorial-typographic", "fintech that's not navy-and-gold, terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious.
|