taste-code-craft

A designed page is a designed codebase. The DOM is the first layout you write — structure it like one.

1. SEMANTIC HTML (The DOM Is Design)

• One <h1> per page; heading levels descend without skipping (h1 → h2 → h3, never h2 after a bare h4).
• Use the element that means the thing: <nav>, <main>, <section aria-labelledby>, <figure>, <time>, <button> (not a <div> with a click handler), <a href> for navigation.
• Lists are <ul>/<ol> — a row of features is a list, not five <div>s.
• Every <img> has alt (empty alt="" only when decorative) and explicit width/height to prevent layout shift.
• Labels: every <input> has a visible <label> (or aria-labelledby); never placeholder as the only label.
• If the page has no <main>, one <section> without a heading, or a clickable <div>, it fails.

2. TOKENS OVER LITERALS (The Design System in Code)

• Every color, spacing value, radius, shadow, and font size comes from a variable — zero hardcoded hex values in component rules. Literal #000 or padding: 13px appearing three times is a token missing.
• The palette in code matches the design read exactly: no invented extra grays (#F7F8FA for a page that says #F4F1EA), no brand-name hexes that weren't chosen.
• Type uses the declared scale (rem/fluid clamp), not ad-hoc pixel sizes per component.
• Breakpoints come from a single media-query convention (one set of widths, documented once), not per-component magic numbers.
• When a design system exists (taste-design-system), components consume semantic tokens — never reach past them to primitives.

3. SPECIFICITY & CSS ARCHITECTURE

• No !important — if one is needed, the selector model is wrong.
• No styling by ID, no bare element selectors with side effects (section { }), no * { } resets past a single box-sizing reset.
• Max nesting depth 2 (or the framework's own convention); selectors that need 4+ levels describe a component boundary that should exist.
• Utility/inline systems (Tailwind) are fine if the config is tokenized and class counts stay readable; 30-class soup on one element is not.
• Dead rules: any CSS rule that matches nothing in the markup gets deleted before delivery — pages ship with zero unused selectors.
• Components are single-responsibility: one file/block per UI component, no component doing hero + footer + modal work.

4. ZERO INLINE STYLES (Except The Three Exceptions)

• Inline style="..." is banned for layout, color, and type — that's what classes exist for.
• Allowed exceptions (use sparingly, comment why): dynamic values (CSS variable injection from JS state, e.g. progress), one-off alignment of a single static element that would need a new class, SVG presentation attributes.
• An audit counts inline styles; more than ~5 on a page = architecture drift.

5. HYGIENE & DELIVERY

• No dead markup: unused wrapper divs, empty elements, comments of old code, console.log, TODO-left-in-production.
• No placeholder assets: no lorem text, no https://placehold.co, no unsplash URLs without intent, no image that 404s.
• Files that ship: every font is loaded once (see taste-web-performance), every stylesheet is used, no duplicate font links from copy-paste.
• Formatting is consistent (one quote style, one trailing-comma policy) — run the formatter; an agent that skips formatting signals it skipped other things.
• No accessibility regressions introduced in markup: focusable elements reachable, aria-hidden not applied to focusable content, buttons not nested in buttons.

6. CHECKLIST (Fail the Code If…)

• Any element that should be a <button>/<a>/<ul> is a <div>.
• Any hardcoded color, spacing, radius, or type size outside the token set.
• Any !important, ID-styling, or 4+ level nesting.
• Any inline style outside the three exceptions.
• Any unused CSS rule, dead markup, or console.log shipped.
• Heading levels skipped or duplicated h1.
• An image without alt and explicit dimensions.
• The code looks like it was generated by an agent that didn't read the design system.