web-design

Files (2)

• SKILL.md
• audit_html.py · scripts/

SKILL.md (first lines)

Design decisions here are constraints, not taste. Each one below has a reason;
follow it unless the user's brief overrides it.

## Before writing markup

If a design already exists in the project, match it — read an existing
component and reuse its spacing, radii, colours and type sizes. A page that
looks "well designed" but unlike the rest of the app is a worse result than a
plain page that fits.

If nothing exists, decide these five things first, in writing, in one or two
lines: the type scale, the spacing unit, the palette, the corner radius, the
shadow depth. Everything downstream follows from them.

## Layout

Pick one spacing unit (4px or 8px) and use only multiples of it. Mixed
arbitrary values are the single most common reason a layout looks amateur.

Constrain reading width: 60–75 characters per line for prose (`max-width:
65ch`). Full-width paragraphs are unreadable on a wide monitor.

Use CSS Grid for the page skeleton and Flexbox inside components. Reach for
absolute positioning only when an element genuinely leaves the flow.

Space belongs to the thing it separates. Prefer `gap` on the container over
margins on children — margins collapse, gaps do not, and one rule beats N.

## Type

Two type families at most, often one. Weight and size carry hierarchy better
than a second family.

Use a modular scale rather than picking sizes ad hoc: 12, 14, 16, 20, 24, 32,
48 covers almost everything. Body text is 16px minimum — smaller is a
readability bug on phones, not a style.

Line height scales inversely with size: ~1.5 for body, ~1.2 for headings.

Never set a heading in pure black on white. `#111`–`#1a1a1a` reads as sharper
because it lowers the contrast collision with the background.

## Colour

Build from one accent plus a neutral ramp. A palette of many hues is far harder
to keep coherent than one hue at many lightnesses.

Verify contrast, do not eyeball it: 4.5:1 for body text, 3:1 for large text and
for UI boundaries that carry meaning. Compute it — see the check below.

Never encode meaning in hue alone. An error state needs an icon or wording, not
just red, or it disappears for a colour-blind user.

Support both schemes from the start. Retrofitting dark mode means revisiting
every colour decision; use variables from the first line of CSS.

## States and motion

Every interactive element needs hover, focus-visible, active and disabled.
Missing `:focus-visible` is an accessibility failure — keyboard users lose the
cursor entirely. Never `outline: none` without an equal replacement.

An element that can be clicked must look clickable, and one that cannot must
not. Cursor, contrast and elevation all carry that signal.

Animate only `transform` and `opacity` — they are compositor-only. Animating
`width`, `top` or `box-shadow` forces layout on every frame and janks on weak
hardware. Keep durations at 150–250ms; longer feels sluggish rather than smooth.

Respect `prefers-reduced-motion` — for some users motion causes nausea, not
delight.

## Responsive

Start at the narrow width and add breakpoints where the content breaks, not at
device sizes. Devices change; the point at which a column becomes unreadable
does not.

Touch targets are 44×44px minimum. A 24px icon button is a miss on a phone.

Test at 320px wide. If nothing overflows there, wider screens are easy.

## Checking the work

Start with the markup audit — it finds in a second what takes minutes by eye:

```
python scripts/audit_html.py page.html
```

Flags images without alt, inputs without a label, clickable `div`s (unreachable
by keyboard), `outline:none` with no `:focus-visible` replacement, skipped
heading levels, missing `lang`/viewport, and colour pairs below 4.5:1.

It reads markup only — it cannot see layout, overflow or the rendered result.

Do not claim a design is correct from the markup. Verify it:

- **Browser Use** (Code space, enable in Settings → Automation): open the page,
  screenshot it, read the accessibility tree to confirm structure and labels,
  resize to 320px and to desktop, and check both colour schemes.
- **RunPython** (Home): compute contrast ratios rather than judging by eye.

```python
def contrast(hex1, hex2):
    def lum(h):
        c = [int(h.lstrip('#')[i:i+2], 16) / 255 for i in (0, 2, 4)]
        c = [x / 12.92 if x <= 0.04045 else ((x + 0.055) / 1.055) ** 2.4 for x in c]
        return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]
    a, b = sorted((lum(hex1), lum(hex2)), reverse=True)
    return round((a + 0.05) / (b + 0.05), 2)

print(contrast('#1a1a1a', '#ffffff'))  # 17.4 — passes
print(contrast('#8a8a8a', '#ffffff'))  # 3.1  — fails body text
```

State what you actually checked and what you did not.

## Reviewing someone else's page

From iaa2005/monet-directory, MIT.

More from iaa2005/monet-directory