nathankoerschner/my-frontend-design

My Frontend Design

A comprehensive frontend skill that combines accessibility review, opinionated UI constraints, and Vercel Web Interface Guidelines compliance.

Mode

• Build mode (no arguments): Apply all constraints when building new UI
• Review mode ($ARGUMENTS provided): Review specified files against all guidelines

---

1. Rams Accessibility Review (WCAG 2.1)

Critical (Must Fix)

| Check | WCAG | What to look for | |-------|------|------------------| | Images without alt | 1.1.1 | <img> without alt attribute | | Icon-only buttons | 4.1.2 | <button> with only SVG/icon, no aria-label | | Form inputs without labels | 1.3.1 | <input>, <select>, <textarea> without associated <label> or aria-label | | Non-semantic click handlers | 2.1.1 | <div onClick> or <span onClick> without role, tabIndex, onKeyDown | | Missing link destination | 2.1.1 | <a> without href using only onClick |

Serious (Should Fix)

| Check | WCAG | What to look for | |-------|------|------------------| | Focus outline removed | 2.4.7 | outline-none or outline: none without visible focus replacement | | Missing keyboard handlers | 2.1.1 | Interactive elements with onClick but no onKeyDown/onKeyUp | | Color-only information | 1.4.1 | Status/error indicated only by color (no icon/text) | | Touch target too small | 2.5.5 | Clickable elements smaller than 44x44px |

Moderate (Consider Fixing)

| Check | WCAG | What to look for | |-------|------|------------------| | Heading hierarchy | 1.3.1 | Skipped heading levels (h1 -> h3) | | Positive tabIndex | 2.4.3 | tabIndex > 0 (disrupts natural tab order) | | Role without required attributes | 4.1.2 | role="button" without tabIndex="0" |

---

2. UI Skills Constraints

Stack

• MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested
• MUST use motion/react (formerly framer-motion) when JavaScript animation is required
• SHOULD use tw-animate-css for entrance and micro-animations in Tailwind CSS
• MUST use cn utility (clsx + tailwind-merge) for class logic

Components

• MUST use accessible component primitives for anything with keyboard or focus behavior (Base UI, React Aria, Radix)
• MUST use the project's existing component primitives first
• NEVER mix primitive systems within the same interaction surface
• SHOULD prefer Base UI for new primitives if compatible with the stack
• MUST add an aria-label to icon-only buttons
• NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

Interaction

• MUST use an AlertDialog for destructive or irreversible actions
• SHOULD use structural skeletons for loading states
• NEVER use h-screen, use h-dvh
• MUST respect safe-area-inset for fixed elements
• MUST show errors next to where the action happens
• NEVER block paste in input or textarea elements

Animation

• NEVER add animation unless it is explicitly requested
• MUST animate only compositor props (transform, opacity)
• NEVER animate layout properties (width, height, top, left, margin, padding)
• SHOULD avoid animating paint properties (background, color) except for small, local UI (text, icons)
• SHOULD use ease-out on entrance
• NEVER exceed 200ms for interaction feedback
• MUST pause looping animations when off-screen
• SHOULD respect prefers-reduced-motion
• NEVER introduce custom easing curves unless explicitly requested
• SHOULD avoid animating large images or full-screen surfaces

Typography

• MUST use text-balance for headings and text-pretty for body/paragraphs
• MUST use tabular-nums for data
• SHOULD use truncate or line-clamp for dense UI
• NEVER modify letter-spacing (tracking-*) unless explicitly requested

Layout

• MUST use a fixed z-index scale (no arbitrary z-*)
• SHOULD use size-* for square elements instead of w-* + h-*

Performance

• NEVER animate large blur() or backdrop-filter surfaces
• NEVER apply will-change outside an active animation
• NEVER use useEffect for anything that can be expressed as render logic

Design

• NEVER use gradients unless explicitly requested
• NEVER use purple or multicolor gradients
• NEVER use glow effects as primary affordances
• SHOULD use Tailwind CSS default shadow scale unless explicitly requested
• MUST give empty states one clear next action
• SHOULD limit accent color usage to one per view
• SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones

---

3. Web Interface Guidelines

Accessibility

• Icon-only buttons need aria-label
• Form controls need <label> or aria-label
• Interactive elements need keyboard handlers (onKeyDown/onKeyUp)
• <button> for actions, <a>/<Link> for navigation (not <div onClick>)
• Images need alt (or alt="" if decorative)
• Decorative icons need aria-hidden="true"
• Async updates (toasts, validation) need aria-live="polite"
• Use semantic HTML (<button>, <a>, <label>, <table>) before ARIA
• Headings hierarchical <h1>-<h6>; include skip link for main content
• scroll-margin-top on heading anchors

Focus States

• Interactive elements need visible focus: focus-visible:ring-* or equivalent
• Never outline-none / outline: none without focus replacement
• Use :focus-visible over :focus (avoid focus ring on click)
• Group focus with :focus-within for compound controls

Forms

• Inputs need autocomplete and meaningful name
• Use correct type (email, tel, url, number) and inputmode
• Never block paste (onPaste + preventDefault)
• Labels clickable (htmlFor or wrapping control)
• Disable spellcheck on emails, codes, usernames (spellCheck={false})
• Checkboxes/radios: label + control share single hit target (no dead zones)
• Submit button stays enabled until request starts; spinner during request
• Errors inline next to fields; focus first error on submit
• Placeholders end with ... and show example pattern
• autocomplete="off" on non-auth fields to avoid password manager triggers
• Warn before navigation with unsaved changes (beforeunload or router guard)

Animation

• Honor prefers-reduced-motion (provide reduced variant or disable)
• Animate transform/opacity only (compositor-friendly)
• Never transition: all-list properties explicitly
• Set correct transform-origin
• SVG: transforms on <g> wrapper with transform-box: fill-box; transform-origin: center
• Animations interruptible-respond to user input mid-animation

Typography

• ... not ...
• Curly quotes " " not straight "
• Non-breaking spaces: 10 MB, Cmd K, brand names
• Loading states end with ...: "Loading...", "Saving..."
• font-variant-numeric: tabular-nums for number columns/comparisons
• Use text-wrap: balance or text-pretty on headings (prevents widows)

Content Handling

• Text containers handle long content: truncate, line-clamp-*, or break-words
• Flex children need min-w-0 to allow text truncation
• Handle empty states-don't render broken UI for empty strings/arrays
• User-generated content: anticipate short, average, and very long inputs

Images

• <img> needs explicit width and height (prevents CLS)
• Below-fold images: loading="lazy"
• Above-fold critical images: priority or fetchpriority="high"

Performance

• Large lists (>50 items): virtualize (virtua, content-visibility: auto)
• No layout reads in render (getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
• Batch DOM reads/writes; avoid interleaving
• Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
• Add <link rel="preconnect"> for CDN/asset domains
• Critical fonts: <link rel="preload" as="font"> with font-display: swap

Navigation & State

• URL reflects state-filters, tabs, pagination, expanded panels in query params
• Links use <a>/<Link> (Cmd/Ctrl+click, middle-click support)
• Deep-link all stateful UI (if uses useState, consider URL sync via nuqs or similar)
• Destructive actions need confirmation modal or undo window-never immediate

Touch & Interaction

• touch-action: manipulation (prevents double-tap zoom delay)
• -webkit-tap-highlight-color set intentionally
• overscroll-behavior: contain in modals/drawers/sheets
• During drag: disable text selection, inert on dragged elements
• autoFocus sparingly-desktop only, single primary input; avoid on mobile

Safe Areas & Layout

• Full-bleed layouts need env(safe-area-inset-*) for notches
• Avoid unwanted scrollbars: overflow-x-hidden on containers, fix content overflow
• Flex/grid over JS measurement for layout

Dark Mode & Theming

• color-scheme: dark on <html> for dark themes (fixes scrollbar, inputs)
• <meta name="theme-color"> matches page background
• Native <select>: explicit background-color and color (Windows dark mode)

Locale & i18n

• Dates/times: use Intl.DateTimeFormat not hardcoded formats
• Numbers/currency: use Intl.NumberFormat not hardcoded formats
• Detect language via Accept-Language / navigator.languages, not IP

Hydration Safety

• Inputs with value need onChange (or use defaultValue for uncontrolled)
• Date/time rendering: guard against hydration mismatch (server vs client)
• suppressHydrationWarning only where truly needed

Hover & Interactive States

• Buttons/links need hover: state (visual feedback)
• Interactive states increase contrast: hover/active/focus more prominent than rest

Content & Copy

• Active voice: "Install the CLI" not "The CLI will be installed"
• Title Case for headings/buttons (Chicago style)
• Numerals for counts: "8 deployments" not "eight"
• Specific button labels: "Save API Key" not "Continue"
• Error messages include fix/next step, not just problem
• Second person; avoid first person
• & over "and" where space-constrained

---

Anti-patterns (Flag These)

• user-scalable=no or maximum-scale=1 disabling zoom
• onPaste with preventDefault
• transition: all
• outline-none without focus-visible replacement
• Inline onClick navigation without <a>
• <div> or <span> with click handlers (should be <button>)
• Images without dimensions
• Large arrays .map() without virtualization
• Form inputs without labels
• Icon buttons without aria-label
• Hardcoded date/number formats (use Intl.*)
• autoFocus without clear justification

---

Output Format

When reviewing files, output:

=====================================
MY FRONTEND DESIGN REVIEW: [filename]
=====================================

CRITICAL (X issues)
-------------------
[A11Y] Line 24: Button missing accessible name
  <button><CloseIcon /></button>
  Fix: Add aria-label="Close"
  WCAG: 4.1.2

[UI-SKILL] Line 42: Using h-screen
  Fix: Replace with h-dvh

SERIOUS (X issues)
------------------
[WIG] Line 55: transition: all
  Fix: List properties explicitly

=====================================
SUMMARY: X critical, X serious, X moderate
Score: XX/100
=====================================

---

Guidelines

1. Read the file(s) first before making assessments
2. Be specific with line numbers and code snippets
3. Provide fixes, not just problems
4. Prioritize critical accessibility issues first
5. When building, apply all constraints proactively
6. If asked, offer to fix the issues directly