Semantic markup & modern CSS

Load first on marketing UI, layout refactors, or any task touching TSX + styles. Pair with react-client-expert for client state; this skill owns HTML, ARIA, tokens, and CSS architecture.

Optional project overlay: see examples/overlays/ (e.g. Next.js portfolio marketing CSS).

Decision order (always)

1. Native element — can <button>, <a>, <dialog>, <details>, <address>, <figure>, <ul>/<ol> do the job?
2. Semantics + one heading level — correct landmark/section/article; single h1, section h2, card h3
3. WAI-ARIA only to fill gaps — prefer native semantics; don't duplicate what HTML already exposes
4. data-* state in DOM — style with CSS; avoid parallel isOpen && "block" class soup
5. Token/contrast fix — adjust CSS variables before per-component color hacks
6. Tailwind for layout/type — spacing, grid, responsive; CSS for scroll-margin, :has(), @container, color-mix, reduced motion

Semantic HTML

Buttons vs links: navigation → <a href>; in-page actions → <button type="button">. Never <div role="button">.

WAI-ARIA (minimal)

• Landmarks: aria-label on <nav> when multiple (Primary, Footer, Social)
• Disclosures: aria-expanded, aria-controls on menu triggers; panel id matches
• Current page/section: aria-current="page" or "location" where accurate
• Live feedback: role="status" aria-live="polite" for form/async messages; aria-busy="true" on loading regions
• Decorative: aria-hidden="true" on icons; meaningful controls keep visible text or aria-label
• Invalid fields: native aria-invalid + visible error text linked via aria-describedby
• Dialogs: aria-labelledby → dialog title; prefer native <dialog> focus behavior

Do not add redundant roles (role="navigation" on <nav>) or label with ARIA what visible text already provides.

Color contrast (WCAG 2.2 AA)

Fix at token layer (theme.css / design tokens), not one-off utilities.

Verify both theme variants (e.g. light + dim). Document adjusted token values in a short comment.

data-* state conventions

Expose UI state in HTML; style in CSS @layer components:

React: set attributes from reducer/status enum; don't mirror the same state in redundant class toggles.

Example CSS (few lines, high leverage):

@layer components {
  [data-section] { scroll-margin-top: var(--header-offset, 5rem); }
  [data-state="closed"] { display: none; }
  [data-status="loading"] { pointer-events: none; opacity: 0.7; }
  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }
}

Tailwind vs modern CSS

Goal: many fixes = token tweak + 3–5 lines CSS, not 20 new classes per component.

Workflow (before editing TSX)

- [ ] Read target component + parent layout (landmarks, heading order)
- [ ] Grep for nested <main>, div-onClick, role="button", orphan tokens
- [ ] List states → map to data-* + native elements
- [ ] Contrast-check affected text/surface pairs in all themes
- [ ] Implement: semantics first, then CSS layer, then Tailwind layout
- [ ] Verify: keyboard tab order, Esc on dialog, lint/type-check

Anti-patterns (reject)

// ❌ Div button
<div role="button" tabIndex={0} onClick={…}>

// ✅
<button type="button" onClick={…}>

// ❌ State in classes only
<div className={isOpen ? "block" : "hidden"}>

// ✅
<nav data-state={isOpen ? "open" : "closed"} aria-expanded={isOpen}>

// ❌ Muted token for body copy (contrast fail)
<p className="text-text2">{longParagraph}</p>

// ✅ Body on text1; text2 for meta only

Done when

• One <main>; sections use aria-labelledby
• Interactive controls are native <button> / <a> / <dialog>
• Stateful UI exposes data-* (or native open on <details>/<dialog>)
• Contrast-sensitive pairs pass AA in all active themes
• :has() / scroll-margin / reduced-motion handled in CSS where applicable
• No new div-only patterns where semantic elements suffice

Related

• Client state/fetch: react-client-expert
• Optional overlay: examples/overlays/nextjs-portfolio-marketing-css.md