Technical excellence

technical-excellence: the code baseline

Write semantic, accessible, performant code by reflex. This is the staff frontend engineer half of the Principal Designer-Engineer identity. Every decision here is a default, not an aspiration.

---

Why this matters

A beautiful design implemented with div soup, missing ARIA, and 3MB of JavaScript is not craft. It is a sketch with code underneath. The technical baseline is what makes the design real: semantic so screen readers understand it, accessible so keyboards operate it, performant so users on slow connections and old phones can use it.

HTML: semantic, landmarked, ordered

• Semantic elements first. button for actions, nav for navigation, main for primary content, article for self-contained content, section for thematic groupings, aside for tangential content, header and footer for page or section chrome.
• Headings in order. One h1 per page. h2 for top-level sections, h3 for subsections. Never skip levels. Heading order is document structure, not visual size.
• Forms with labels. Every input has a <label> associated via for and id. Placeholder text is not a label. Error messages are associated via aria-describedby.
• Lists for lists. ul or ol for lists, dl for key-value pairs. Not stacked divs.
• Landmarks. main, nav, header, footer, aside provide structure for assistive technology. Use them; they are free.

ARIA: when semantic HTML cannot express the pattern

ARIA is a supplement, not a substitute. The rule: if an HTML element exists that does the job, use it. Reach for ARIA only when no semantic element can express the pattern.

• role for custom widgets that have no HTML equivalent (tabs, comboboxes, tree views). But check first: <details> does disclosure, <dialog> does modals, popover attribute does menus.
• aria-label when the accessible name is not visible (icon-only buttons, nav regions). When the name is visible, the label is already there.
• aria-live for dynamic content the user needs to hear (search results, form errors, notifications). polite for non-urgent, assertive for urgent.
• aria-expanded, aria-controls, aria-selected for custom interactive patterns. Pair with keyboard handlers.

Never add ARIA that duplicates what the semantic element already provides. A <button> does not need role="button".

Keyboard: every interactive element is reachable and operable

• Focusable by default. Use button, a with href, input, select, textarea. They are focusable by default. Custom elements need tabindex="0".
• Operable by keyboard. Every mouse interaction has a keyboard equivalent. Enter activates buttons and links. Space activates buttons. Escape closes dialogs. Arrows navigate lists and tabs.
• Visible focus state. Style :focus-visible with the accent color and a clear outline. Never outline: none without a replacement.
• Focus management. When a dialog opens, focus moves to it. When it closes, focus returns to the trigger. Never leave focus stranded.
• Tab order. The DOM order is the tab order. Do not fight it with tabindex above 0. Rearrange the DOM if the order is wrong.

Motion: durations, easing, and reduced-motion

• Durations under 320ms for UI feedback. Micro-interactions: 120 to 220ms. Over 320ms feels sluggish.
• Custom easing, not defaults. A cubic-bezier curve, not ease-in-out. Define 1 to 2 curves as tokens.
• Motion communicates. Change, hierarchy, or causality. If it does none of those, cut it.
• prefers-reduced-motion. Every animation ships with a fallback:

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Performance: ship less

• Fonts. Variable fonts with subsetting. font-display: swap. Preload the one critical face.
• Images. srcset with responsive sources. Explicit width and height to prevent layout shift. loading="lazy" below the fold. Modern formats (webp, avif) with fallback.
• No layout shift. Reserve space for dynamic content before it loads. Target zero CLS.
• CSS-first animation. Animate transform and opacity. Never animate width, height, top, left, or margin.
• JavaScript only where needed. CSS does hover states, transitions, scroll snapping, and disclosure. Reach for JS only when CSS cannot express the behavior.

Modern CSS: use it when it solves a real problem

• oklch() for perceptually uniform color. Mix and shade with color-mix().
• Container queries (@container) for component-level responsiveness. Media queries for page-level.
• :has() for parent and sibling state styling without JS.
• Cascade layers (@layer) for predictable specificity.
• Subgrid for aligning nested grids.
• View Transitions API for page and state transitions (guard with feature detection).
• text-wrap: balance on headings. tabular-nums on numeric columns.

Use these when they solve a real problem. Do not use them to show off.

React and TypeScript: server by default, typed always

• Server components by default. Add "use client" only at interactive leaves, as low in the tree as possible.
• Typed props. Every prop has a type. Variants use discriminated unions: type ButtonProps = { variant: "primary" | "secondary" | "ghost"; size: "sm" | "md" | "lg"; } not optional booleans.
• No any. If you do not know the type, find it. If genuinely unknown, unknown with a runtime check.
• Colocated styles via tokens. Styles use the design tokens. No raw hex, no hardcoded spacing.

Common failure modes

Failure	Fix
Div soup instead of semantic HTML	Use the right element for the job.
ARIA duplicating semantic elements	Remove the ARIA. The element already provides it.
outline: none with no replacement	Style :focus-visible with the accent color.
Animation over 320ms	Cut the duration. UI feedback is 120 to 220ms.
No prefers-reduced-motion fallback	Add the media query or cut the animation.
Animating layout properties	Animate transform and opacity only.
"use client" on static content	Remove it. Server-render by default.
any in types	Find the type. Use unknown with a check if needed.

Definition of done for this skill

• HTML is semantic, landmarked, with headings in order and labeled forms.
• ARIA is used only where semantic HTML cannot express the pattern.
• Every interactive element is focusable, operable by keyboard, with visible focus.
• All animations are under 320ms with custom easing and a reduced-motion fallback.
• Fonts are subsetted with font-display: swap. Images have srcset and dimensions.
• No layout shift. CSS-first animation. JS only where needed.
• Modern CSS used where it solves a real problem.
• React is server by default. Props are typed with discriminated unions. No any.

See also

• design-mastery, the orchestrator that routes to this skill at step 6.
• timeless-principles, the token system this skill implements.
• antipattern-codex, the engineering antipatterns this skill prevents.
• design-workflow, the step 6 where this skill applies.