[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6PMJAV7856XN2RAZTS6AR6M":3,"skill-same:01M6PMJAV7856XN2RAZTS6AR6M":95},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":60,"commitSha":61,"skillDirectory":62,"forksCount":14,"repositoryHtmlUrl":63,"repositoryHomepageUrl":6,"ownerHtmlUrl":64,"ownerBlogUrl":65,"ownerDescription":6,"updatedAt":66,"install":67,"resources":80},"01M6PMJAV7856XN2RAZTS6AR6M","web-design-guidelines",null,"Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.","headmktlucca-ui\u002Fneuroads-lp","headmktlucca-ui","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F247379838?v=4","01M6PDVAV6M1W96D1SR1PDF8CS","NeuroAds","01M6PDVAZ4P281GNDKD45CYTF5",0,"MIT","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.agent\u002Fskills\u002Fweb\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"web","guidelines","web design","design","web design guidelines","ui","implementing","triggers","platform","responsive","responsive design","html","platform design","web performance","code","tasks","web components","components","performance","css","2026-11-10 10:12:30",false,"---\nname: web-design-guidelines\ndescription: Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.\nlicense: MIT\nmetadata:\n  author: platform-design-skills\n  version: \"1.0.0\"\n---\n\n# Web Platform Design Guidelines\n\nFramework-agnostic rules for accessible, performant, responsive web interfaces. Based on WCAG 2.2, MDN Web Docs, and modern web platform APIs.\n\n---\n\n## 1. Accessibility \u002F WCAG [CRITICAL]\n\nAccessibility is not optional. Most rules in this section map to WCAG 2.2 success criteria at Level A or AA. A small number of best-practice rules (noted inline) target Level AAA or go beyond WCAG.\n\n### 1.1 Use Semantic HTML Elements\n\nUse elements for their intended purpose. Semantic structure provides free accessibility, SEO, and reader-mode support.\n\n| Element | Purpose |\n|---------|---------|\n| `\u003Cmain>` | Primary page content (one per page) |\n| `\u003Cnav>` | Navigation blocks |\n| `\u003Cheader>` | Introductory content or navigational aids |\n| `\u003Cfooter>` | Footer for nearest sectioning content |\n| `\u003Carticle>` | Self-contained, independently distributable content |\n| `\u003Csection>` | Thematic grouping with a heading |\n| `\u003Caside>` | Tangentially related content (sidebars, callouts) |\n| `\u003Cfigure>` \u002F `\u003Cfigcaption>` | Illustrations, diagrams, code listings |\n| `\u003Cdetails>` \u002F `\u003Csummary>` | Expandable\u002Fcollapsible disclosure widget |\n| `\u003Cdialog>` | Modal or non-modal dialog boxes |\n| `\u003Ctime>` | Machine-readable dates\u002Ftimes |\n| `\u003Cmark>` | Highlighted\u002Freferenced text |\n| `\u003Caddress>` | Contact information for nearest article\u002Fbody |\n\n```html\n\u003C!-- Good -->\n\u003Cmain>\n  \u003Carticle>\n    \u003Ch1>Article Title\u003C\u002Fh1>\n    \u003Cp>Content...\u003C\u002Fp>\n  \u003C\u002Farticle>\n  \u003Caside>Related links\u003C\u002Faside>\n\u003C\u002Fmain>\n\n\u003C!-- Bad: div soup -->\n\u003Cdiv class=\"main\">\n  \u003Cdiv class=\"article\">\n    \u003Cdiv class=\"title\">Article Title\u003C\u002Fdiv>\n    \u003Cdiv class=\"content\">Content...\u003C\u002Fdiv>\n  \u003C\u002Fdiv>\n\u003C\u002Fdiv>\n```\n\n**Anti-pattern**: Using `\u003Cdiv>` or `\u003Cspan>` for interactive elements. Never write `\u003Cdiv onclick>` when `\u003Cbutton>` exists.\n\n### 1.2 ARIA Labels on Interactive Elements\n\nEvery interactive element must have an accessible name. Prefer visible text; use `aria-label` or `aria-labelledby` only when visible text is insufficient (SC 4.1.2).\n\n```html\n\u003C!-- Icon-only button: needs aria-label -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n\n\u003C!-- Linked by labelledby -->\n\u003Ch2 id=\"section-title\">Notifications\u003C\u002Fh2>\n\u003Cul aria-labelledby=\"section-title\">...\u003C\u002Ful>\n\n\u003C!-- Redundant: visible text is enough -->\n\u003Cbutton>Save Changes\u003C\u002Fbutton> \u003C!-- No aria-label needed -->\n```\n\n### 1.3 Keyboard Navigation\n\nAll interactive elements must be reachable and operable via keyboard (SC 2.1.1).\n\n- Use native interactive elements (`\u003Cbutton>`, `\u003Ca href>`, `\u003Cinput>`, `\u003Cselect>`) which are keyboard-accessible by default.\n- Custom widgets need `tabindex=\"0\"` to enter tab order and keydown handlers for activation.\n- Never use `tabindex` values greater than 0.\n- Trap focus inside modals; return focus on close.\n\n```js\n\u002F\u002F Focus trap for modal\ndialog.addEventListener('keydown', (e) => {\n  if (e.key === 'Tab') {\n    const focusable = dialog.querySelectorAll(\n      'button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])'\n    );\n    const first = focusable[0];\n    const last = focusable[focusable.length - 1];\n    if (e.shiftKey && document.activeElement === first) {\n      e.preventDefault();\n      last.focus();\n    } else if (!e.shiftKey && document.activeElement === last) {\n      e.preventDefault();\n      first.focus();\n    }\n  }\n});\n```\n\n### 1.4 Visible Focus Indicators\n\nNever remove focus outlines without providing a visible replacement (SC 2.4.7, enhanced SC 2.4.11 (AA) and SC 2.4.12 (AAA) in WCAG 2.2).\n\n```css\n\u002F* Good: custom focus indicator *\u002F\n:focus-visible {\n  outline: 3px solid var(--focus-color, #4A90D9);\n  outline-offset: 2px;\n}\n\n\u002F* Remove default only when :focus-visible is supported *\u002F\n:focus:not(:focus-visible) {\n  outline: none;\n}\n\n\u002F* Bad: removing all focus styles *\u002F\n\u002F* *:focus { outline: none; } *\u002F\n```\n\nWCAG 2.2 requires focus indicators to have a minimum area of the perimeter of the component times 2px, with 3:1 contrast against adjacent colors.\n\n### 1.5 Skip Navigation Links\n\nProvide a mechanism to skip repeated blocks of content (SC 2.4.1).\n\n```html\n\u003Cbody>\n  \u003Ca href=\"#main-content\" class=\"skip-link\">Skip to main content\u003C\u002Fa>\n  \u003Cnav>...\u003C\u002Fnav>\n  \u003Cmain id=\"main-content\">...\u003C\u002Fmain>\n\u003C\u002Fbody>\n```\n\n```css\n.skip-link {\n  position: absolute;\n  top: -100%;\n  left: 0;\n  z-index: 1000;\n  padding: 0.75rem 1.5rem;\n  background: var(--color-primary);\n  color: var(--color-on-primary);\n}\n.skip-link:focus {\n  top: 0;\n}\n```\n\n### 1.6 Alt Text for Images\n\nEvery `\u003Cimg>` must have an `alt` attribute (SC 1.1.1).\n\n- **Informative images**: describe the content and function. `alt=\"Bar chart showing sales doubled in Q4\"`.\n- **Decorative images**: use `alt=\"\"` (empty string) so screen readers skip them.\n- **Functional images** (inside links\u002Fbuttons): describe the action. `alt=\"Search\"`.\n- **Complex images**: use `alt` for short description, link to long description or use `\u003Cfigcaption>`.\n\n```html\n\u003Cimg src=\"chart.png\" alt=\"Revenue chart: Q1 $2M, Q2 $2.4M, Q3 $3.1M, Q4 $4.5M\">\n\u003Cimg src=\"decorative-wave.svg\" alt=\"\">\n```\n\n### 1.7 Color Contrast\n\nMaintain minimum contrast ratios (SC 1.4.3, 1.4.6, 1.4.11).\n\n| Content | Minimum Ratio |\n|---------|--------------|\n| Normal text (\u003C24px \u002F \u003C18.66px bold) | 4.5:1 |\n| Large text (>=24px \u002F >=18.66px bold) | 3:1 |\n| UI components and graphical objects | 3:1 |\n\nDo not rely on color alone to convey information (SC 1.4.1). Pair color with icons, text, or patterns.\n\n```css\n\u002F* Check contrast of these tokens *\u002F\n:root {\n  --text-primary: #1a1a2e;    \u002F* on white: ~16:1 *\u002F\n  --text-secondary: #555770;  \u002F* on white: ~6.5:1 *\u002F\n  --text-disabled: #767693;   \u002F* on white: ~4.5:1, borderline *\u002F\n}\n```\n\n### 1.8 Form Labels\n\nEvery form input must have a programmatically associated label (SC 1.3.1, 3.3.2).\n\n```html\n\u003C!-- Explicit label (preferred) -->\n\u003Clabel for=\"email\">Email address\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" autocomplete=\"email\">\n\n\u003C!-- Implicit label (acceptable) -->\n\u003Clabel>\n  Email address\n  \u003Cinput type=\"email\" autocomplete=\"email\">\n\u003C\u002Flabel>\n\n\u003C!-- Never: placeholder as sole label -->\n\u003C!-- \u003Cinput placeholder=\"Email\"> -->\n```\n\n### 1.9 Error Identification\n\nIdentify and describe errors in text (SC 3.3.1). Link error messages to inputs with `aria-describedby` or `aria-errormessage`.\n\n```html\n\u003Clabel for=\"email\">Email\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" aria-describedby=\"email-error\" aria-invalid=\"true\">\n\u003Cp id=\"email-error\" role=\"alert\">Enter a valid email address, e.g. name@example.com\u003C\u002Fp>\n```\n\n### 1.10 ARIA Live Regions\n\nAnnounce dynamic content changes to screen readers (SC 4.1.3).\n\n```html\n\u003C!-- Polite: announced when user is idle -->\n\u003Cdiv aria-live=\"polite\" aria-atomic=\"true\">\n  3 results found\n\u003C\u002Fdiv>\n\n\u003C!-- Assertive: interrupts current speech -->\n\u003Cdiv role=\"alert\">\n  Your session will expire in 2 minutes.\n\u003C\u002Fdiv>\n\n\u003C!-- Status messages -->\n\u003Cdiv role=\"status\">\n  File uploaded successfully.\n\u003C\u002Fdiv>\n```\n\nUse `aria-live=\"polite\"` by default. Reserve `role=\"alert\"` \u002F `aria-live=\"assertive\"` for time-sensitive warnings.\n\n### 1.11 ARIA Role Quick Reference\n\n| Role | Purpose | Native Equivalent |\n|------|---------|-------------------|\n| `button` | Clickable action | `\u003Cbutton>` |\n| `link` | Navigation | `\u003Ca href>` |\n| `tab` \u002F `tablist` \u002F `tabpanel` | Tab interface | None |\n| `dialog` | Modal | `\u003Cdialog>` |\n| `alert` | Assertive live region | None |\n| `status` | Polite live region | `\u003Coutput>` |\n| `navigation` | Nav landmark | `\u003Cnav>` |\n| `main` | Main landmark | `\u003Cmain>` |\n| `complementary` | Aside landmark | `\u003Caside>` |\n| `search` | Search landmark | `\u003Csearch>` (HTML5) |\n| `img` | Image | `\u003Cimg>` |\n| `list` \u002F `listitem` | List | `\u003Cul>\u002F\u003Cli>` |\n| `heading` | Heading (with `aria-level`) | `\u003Ch1>`-`\u003Ch6>` |\n| `menu` \u002F `menuitem` | Menu widget | None |\n| `tree` \u002F `treeitem` | Tree view | None |\n| `grid` \u002F `row` \u002F `gridcell` | Data grid | `\u003Ctable>` |\n| `progressbar` | Progress | `\u003Cprogress>` |\n| `slider` | Range input | `\u003Cinput type=\"range\">` |\n| `switch` | Toggle | `\u003Cinput type=\"checkbox\">` |\n\n**Rule**: Prefer native HTML over ARIA. Use ARIA only when no native element exists for the pattern.\n\n### 1.12 Label in Name (WCAG 2.5.3 Level A)\n\nWhen an interactive element has visible text, its accessible name must contain that visible text as a substring (SC 2.5.3). Voice control users (Dragon NaturallySpeaking, macOS Voice Control) speak the visible label to activate controls. If `aria-label` replaces or contradicts the visible text, voice commands fail.\n\n```html\n\u003C!-- Correct: aria-label contains visible text as substring -->\n\u003Cbutton aria-label=\"Delete item from cart\">Delete\u003C\u002Fbutton>\n\n\u003C!-- Correct: no aria-label needed — visible text is the accessible name -->\n\u003Cbutton>Save Changes\u003C\u002Fbutton>\n\n\u003C!-- Correct: icon button — no visible text, aria-label is fine -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n```\n\n```html\n\u003C!-- Incorrect: aria-label overrides visible text with different text -->\n\u003Cbutton aria-label=\"Remove\">Delete\u003C\u002Fbutton>\n\n\u003C!-- Incorrect: aria-label does not contain visible \"Submit\" -->\n\u003Cbutton aria-label=\"Proceed to next step\">Submit\u003C\u002Fbutton>\n```\n\n**Rule**: When visible text is present, `aria-label` must include that visible text (verbatim, case-insensitively). Prefer no `aria-label` at all when visible text is sufficient.\n\n---\n\n## 2. Responsive Design [CRITICAL]\n\n### 2.1 Mobile-First Approach\n\nWrite base styles for the smallest viewport. Layer complexity with `min-width` media queries.\n\n```css\n\u002F* Base: mobile *\u002F\n.grid {\n  display: grid;\n  grid-template-columns: 1fr;\n  gap: 1rem;\n}\n\n\u002F* Tablet *\u002F\n@media (min-width: 48rem) {\n  .grid {\n    grid-template-columns: repeat(2, 1fr);\n  }\n}\n\n\u002F* Desktop *\u002F\n@media (min-width: 64rem) {\n  .grid {\n    grid-template-columns: repeat(3, 1fr);\n  }\n}\n```\n\n### 2.2 Fluid Layouts with Modern CSS Functions\n\nUse `clamp()`, `min()`, and `max()` for fluid sizing without breakpoints.\n\n```css\n\u002F* Fluid typography *\u002F\nh1 {\n  font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem);\n}\n\n\u002F* Fluid spacing *\u002F\n.section {\n  padding: clamp(1.5rem, 4vw, 4rem);\n}\n\n\u002F* Fluid container *\u002F\n.container {\n  width: min(90%, 72rem);\n  margin-inline: auto;\n}\n```\n\n### 2.3 Container Queries\n\nSize components based on their container, not the viewport.\n\n```css\n.card-container {\n  container-type: inline-size;\n  container-name: card;\n}\n\n@container card (min-width: 400px) {\n  .card {\n    display: grid;\n    grid-template-columns: 200px 1fr;\n  }\n}\n\n@container card (min-width: 700px) {\n  .card {\n    grid-template-columns: 300px 1fr;\n    gap: 2rem;\n  }\n}\n```\n\n### 2.4 Content-Based Breakpoints\n\nSet breakpoints where your content breaks, not at device widths. Common starting points:\n\n```css\n\u002F* Content-based, not \"iPhone\" or \"iPad\" *\u002F\n@media (min-width: 30rem)  { \u002F* ~480px: single column gets cramped *\u002F }\n@media (min-width: 48rem)  { \u002F* ~768px: room for 2 columns *\u002F }\n@media (min-width: 64rem)  { \u002F* ~1024px: room for sidebar + content *\u002F }\n@media (min-width: 80rem)  { \u002F* ~1280px: wide multi-column *\u002F }\n```\n\n### 2.5 Touch Targets\n\nMinimum 44x44 CSS pixels for touch targets (WCAG SC 2.5.5 AAA; SC 2.5.8 requires only 24x24px at AA). Provide at least 24px spacing between adjacent targets.\n\n```css\nbutton, a, input, select, textarea {\n  min-height: 44px;\n  min-width: 44px;\n}\n\n\u002F* Enlarge tap area without changing visual size *\u002F\n.icon-button {\n  position: relative;\n  width: 24px;\n  height: 24px;\n}\n.icon-button::after {\n  content: \"\";\n  position: absolute;\n  inset: -10px; \u002F* expands clickable area *\u002F\n}\n```\n\n### 2.6 Viewport Meta Tag\n\nAlways include in the document `\u003Chead>`:\n\n```html\n\u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n```\n\nNever use `maximum-scale=1` or `user-scalable=no` -- these break pinch-to-zoom accessibility (SC 1.4.4).\n\n### 2.7 No Horizontal Scrolling\n\nContent must reflow at 320px width without horizontal scrolling (SC 1.4.10).\n\n```css\n\u002F* Prevent overflow *\u002F\nimg, video, iframe, svg {\n  max-width: 100%;\n  height: auto;\n}\n\n\u002F* Contain long words\u002FURLs *\u002F\n.prose {\n  overflow-wrap: break-word;\n}\n\n\u002F* Tables: scroll container, not page *\u002F\n.table-wrapper {\n  overflow-x: auto;\n  -webkit-overflow-scrolling: touch;\n}\n```\n\n---\n\n## 3. Forms [HIGH]\n\n### 3.1 Label Every Input\n\nEvery input needs a visible, programmatically associated label. See section 1.8.\n\n### 3.2 Autocomplete Attributes\n\nUse `autocomplete` for common fields to enable browser autofill (SC 1.3.5).\n\n```html\n\u003Cinput type=\"text\" autocomplete=\"name\" name=\"full-name\">\n\u003Cinput type=\"email\" autocomplete=\"email\" name=\"email\">\n\u003Cinput type=\"tel\" autocomplete=\"tel\" name=\"phone\">\n\u003Cinput type=\"text\" autocomplete=\"street-address\" name=\"address\">\n\u003Cinput type=\"text\" autocomplete=\"postal-code\" name=\"zip\">\n\u003Cinput type=\"text\" autocomplete=\"cc-name\" name=\"card-name\">\n\u003Cinput type=\"text\" autocomplete=\"cc-number\" name=\"card-number\">\n\u003Cinput type=\"password\" autocomplete=\"new-password\" name=\"password\">\n\u003Cinput type=\"password\" autocomplete=\"current-password\" name=\"current-pw\">\n```\n\n### 3.3 Correct Input Types\n\nUse the right `type` to trigger appropriate mobile keyboards and native validation.\n\n| Type | Use For |\n|------|---------|\n| `email` | Email addresses |\n| `tel` | Phone numbers |\n| `url` | URLs |\n| `number` | Numeric values with spinners (not for phone, zip, card numbers) |\n| `search` | Search fields (shows clear button) |\n| `date` \u002F `time` \u002F `datetime-local` | Temporal values |\n| `password` | Passwords (triggers password manager) |\n| `text` with `inputmode=\"numeric\"` | Numeric data without spinners (PINs, zip codes) |\n\n```html\n\u003Cinput type=\"tel\" inputmode=\"numeric\" pattern=\"[0-9]*\" autocomplete=\"one-time-code\">\n```\n\n### 3.4 Inline Validation\n\nValidate on `blur` (not on every keystroke). Show success and error states.\n\n```html\n\u003Cdiv class=\"field\" data-state=\"error\">\n  \u003Clabel for=\"username\">Username\u003C\u002Flabel>\n  \u003Cinput id=\"username\" type=\"text\" aria-describedby=\"username-hint username-error\" aria-invalid=\"true\">\n  \u003Cp id=\"username-hint\" class=\"hint\">3-20 characters, letters and numbers only\u003C\u002Fp>\n  \u003Cp id=\"username-error\" class=\"error\" role=\"alert\">Username must be at least 3 characters\u003C\u002Fp>\n\u003C\u002Fdiv>\n```\n\n```css\n.field[data-state=\"error\"] input {\n  border-color: var(--color-error);\n  box-shadow: 0 0 0 1px var(--color-error);\n}\n.field[data-state=\"error\"] .error { display: block; }\n.field:not([data-state=\"error\"]) .error { display: none; }\n```\n\n### 3.5 Fieldset and Legend for Groups\n\nGroup related inputs with `\u003Cfieldset>` and label the group with `\u003Clegend>`.\n\n```html\n\u003Cfieldset>\n  \u003Clegend>Shipping Address\u003C\u002Flegend>\n  \u003Clabel for=\"street\">Street\u003C\u002Flabel>\n  \u003Cinput id=\"street\" type=\"text\" autocomplete=\"street-address\">\n  \u003C!-- ... -->\n\u003C\u002Ffieldset>\n\n\u003Cfieldset>\n  \u003Clegend>Preferred contact method\u003C\u002Flegend>\n  \u003Clabel>\u003Cinput type=\"radio\" name=\"contact\" value=\"email\"> Email\u003C\u002Flabel>\n  \u003Clabel>\u003Cinput type=\"radio\" name=\"contact\" value=\"phone\"> Phone\u003C\u002Flabel>\n\u003C\u002Ffieldset>\n```\n\n### 3.6 Required Field Indication\n\nIndicate required fields visually and programmatically. Use `required` attribute and visible markers.\n\n```html\n\u003Clabel for=\"name\">\n  Full name \u003Cspan aria-hidden=\"true\">*\u003C\u002Fspan>\n  \u003Cspan class=\"sr-only\">(required)\u003C\u002Fspan>\n\u003C\u002Flabel>\n\u003Cinput id=\"name\" type=\"text\" required autocomplete=\"name\">\n```\n\nIf most fields are required, indicate which are optional instead.\n\n### 3.7 Submit Button State\n\nDo not disable the submit button. Instead, validate on submit and show errors.\n\n```html\n\u003C!-- Good: always enabled, validate on submit -->\n\u003Cbutton type=\"submit\">Create Account\u003C\u002Fbutton>\n\n\u003C!-- Bad: disabled button with no explanation -->\n\u003C!-- \u003Cbutton type=\"submit\" disabled>Create Account\u003C\u002Fbutton> -->\n```\n\nDisabled buttons fail to communicate why the user cannot proceed. If you must disable, provide a visible explanation.\n\n### 3.8 Keep Instructions Near the Field\n\nPlace format examples, constraints, and recovery text next to the relevant field via hint and error text. Never explain requirements only once in introductory copy and expect users to remember them later.\n\n---\n\n## 4. Typography [HIGH]\n\n### 4.1 Font Stacks\n\nUse system font stacks for performance, or web fonts with proper fallbacks.\n\n```css\n\u002F* System font stack *\u002F\nbody {\n  font-family: system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif;\n}\n\n\u002F* Monospace stack *\u002F\ncode, pre, kbd {\n  font-family: ui-monospace, \"Cascadia Code\", \"Source Code Pro\", Menlo, Consolas, monospace;\n}\n\n\u002F* Web font with fallbacks and size-adjust *\u002F\n@font-face {\n  font-family: \"CustomFont\";\n  src: url(\"\u002Ffonts\u002Fcustom.woff2\") format(\"woff2\");\n  font-display: swap;\n  font-weight: 100 900;\n}\nbody {\n  font-family: \"CustomFont\", system-ui, sans-serif;\n}\n```\n\n### 4.2 Relative Units\n\nUse `rem` for font sizes and spacing. Use `em` for component-relative sizing.\n\n```css\nhtml {\n  font-size: 100%; \u002F* = 16px default, respects user preference *\u002F\n}\n\nbody {\n  font-size: 1rem;       \u002F* 16px *\u002F\n}\n\nh1 { font-size: 2.5rem; }  \u002F* 40px *\u002F\nh2 { font-size: 2rem; }    \u002F* 32px *\u002F\nh3 { font-size: 1.5rem; }  \u002F* 24px *\u002F\nsmall { font-size: 0.875rem; } \u002F* 14px *\u002F\n\n\u002F* Never: font-size: 16px; (ignores user zoom settings) *\u002F\n```\n\n### 4.3 Line Height and Spacing\n\nBody text line height of at least 1.5 (SC 1.4.12). Paragraph spacing at least 2x font size.\n\n```css\nbody {\n  line-height: 1.6;\n}\n\nh1, h2, h3 {\n  line-height: 1.2;\n}\n\np + p {\n  margin-top: 1em;\n}\n```\n\n### 4.4 Maximum Line Length\n\nLimit line length to approximately 75 characters for readability.\n\n```css\n.prose {\n  max-width: 75ch;\n}\n\n\u002F* Or for a content column *\u002F\n.content {\n  max-width: 40rem; \u002F* roughly 65-75ch depending on font *\u002F\n  margin-inline: auto;\n}\n```\n\n### 4.5 Typographic Details\n\nUse real quotes, proper dashes, and tabular numbers for data.\n\n```css\n\u002F* Smart quotes *\u002F\nq { quotes: \"\\201C\" \"\\201D\" \"\\2018\" \"\\2019\"; } \u002F* curly double then single *\u002F\n\n\u002F* Tabular numbers for aligned data *\u002F\n.data-table td {\n  font-variant-numeric: tabular-nums;\n}\n\n\u002F* Oldstyle numbers for running prose (optional) *\u002F\n.prose {\n  font-variant-numeric: oldstyle-nums;\n}\n\n\u002F* Proper list markers *\u002F\nul { list-style-type: disc; }\nol { list-style-type: decimal; }\n```\n\n### 4.6 Heading Hierarchy\n\nUse `h1` through `h6` in order. Never skip levels. One `h1` per page.\n\n```html\n\u003C!-- Good -->\n\u003Ch1>Page Title\u003C\u002Fh1>\n  \u003Ch2>Section\u003C\u002Fh2>\n    \u003Ch3>Subsection\u003C\u002Fh3>\n  \u003Ch2>Another Section\u003C\u002Fh2>\n\n\u003C!-- Bad: skipping h2 -->\n\u003Ch1>Page Title\u003C\u002Fh1>\n  \u003Ch3>Subsection\u003C\u002Fh3> \u003C!-- Where is h2? -->\n```\n\nIf you need visual styling that differs from the hierarchy, use CSS classes:\n\n```html\n\u003Ch2 class=\"text-lg\">Visually smaller but semantically h2\u003C\u002Fh2>\n```\n\n---\n\n## 5. Performance [HIGH]\n\n### 5.1 Lazy Load Below-Fold Images\n\nUse native lazy loading for images not visible on initial load.\n\n```html\n\u003C!-- Above fold: load eagerly, add fetchpriority -->\n\u003Cimg src=\"hero.webp\" alt=\"Hero image\" fetchpriority=\"high\" width=\"1200\" height=\"600\">\n\n\u003C!-- Below fold: lazy load -->\n\u003Cimg src=\"feature.webp\" alt=\"Feature image\" loading=\"lazy\" width=\"600\" height=\"400\">\n```\n\n### 5.2 Explicit Image Dimensions\n\nAlways specify `width` and `height` to prevent layout shift (CLS).\n\n```html\n\u003Cimg src=\"photo.webp\" alt=\"Description\" width=\"800\" height=\"600\">\n```\n\n```css\n\u002F* Responsive images with aspect ratio preservation *\u002F\nimg {\n  max-width: 100%;\n  height: auto;\n}\n```\n\n### 5.3 Resource Hints\n\nUse `preconnect` for third-party origins and `preload` for critical resources.\n\n```html\n\u003Chead>\n  \u003C!-- Preconnect to critical third-party origins -->\n  \u003Clink rel=\"preconnect\" href=\"https:\u002F\u002Ffonts.googleapis.com\">\n  \u003Clink rel=\"preconnect\" href=\"https:\u002F\u002Fcdn.example.com\" crossorigin>\n\n  \u003C!-- Preload critical resources -->\n  \u003Clink rel=\"preload\" href=\"\u002Ffonts\u002Fmain.woff2\" as=\"font\" type=\"font\u002Fwoff2\" crossorigin>\n  \u003Clink rel=\"preload\" href=\"\u002Fcss\u002Fcritical.css\" as=\"style\">\n\n  \u003C!-- DNS prefetch for non-critical origins -->\n  \u003Clink rel=\"dns-prefetch\" href=\"https:\u002F\u002Fanalytics.example.com\">\n\u003C\u002Fhead>\n```\n\n### 5.4 Code Splitting\n\nLoad JavaScript only when needed. Use dynamic `import()` for route-based and component-based splitting.\n\n```js\n\u002F\u002F Route-based splitting\nconst routes = {\n  '\u002Fdashboard': () => import('.\u002Fpages\u002Fdashboard.js'),\n  '\u002Fsettings':  () => import('.\u002Fpages\u002Fsettings.js'),\n};\n\n\u002F\u002F Interaction-based splitting\nbutton.addEventListener('click', async () => {\n  const { openEditor } = await import('.\u002Feditor.js');\n  openEditor();\n});\n```\n\n### 5.5 Virtualize Long Lists\n\nFor lists exceeding a few hundred items, render only visible rows.\n\n```js\n\u002F\u002F Concept: virtual scrolling\n\u002F\u002F Render only items in viewport + buffer\nconst visibleStart = Math.floor(scrollTop \u002F itemHeight);\nconst visibleEnd = visibleStart + Math.ceil(containerHeight \u002F itemHeight);\nconst buffer = 5;\nconst renderStart = Math.max(0, visibleStart - buffer);\nconst renderEnd = Math.min(totalItems, visibleEnd + buffer);\n```\n\n### 5.6 Avoid Layout Thrashing\n\nBatch DOM reads and writes. Never interleave them.\n\n```js\n\u002F\u002F Bad: read-write-read-write (forces synchronous layout)\nelements.forEach(el => {\n  const height = el.offsetHeight;     \u002F\u002F read\n  el.style.height = height + 10 + 'px'; \u002F\u002F write\n});\n\n\u002F\u002F Good: batch reads, then batch writes\nconst heights = elements.map(el => el.offsetHeight); \u002F\u002F all reads\nelements.forEach((el, i) => {\n  el.style.height = heights[i] + 10 + 'px'; \u002F\u002F all writes\n});\n```\n\n### 5.7 Use `will-change` Sparingly\n\nOnly apply `will-change` to elements that will animate, and remove it after animation completes.\n\n```css\n\u002F* Good: scoped and temporary *\u002F\n.card:hover {\n  will-change: transform;\n}\n.card.animating {\n  will-change: transform, opacity;\n}\n\n\u002F* Bad: blanket will-change *\u002F\n\u002F* * { will-change: transform; } *\u002F\n```\n\n### 5.8 Expose Waiting States Promptly\n\nAfter a user action, acknowledge the new state immediately. If work cannot finish within a brief moment, show progress, skeletons, optimistic UI, or `aria-busy` feedback instead of leaving the interface unchanged.\n\n---\n\n## 6. Animation and Motion [MEDIUM]\n\n### 6.1 Respect prefers-reduced-motion\n\nAlways provide a reduced-motion alternative (SC 2.3.3, Level AAA).\n\n```css\n\u002F* Define animations normally *\u002F\n.fade-in {\n  animation: fadeIn 300ms ease-out;\n}\n\n@keyframes fadeIn {\n  from { opacity: 0; transform: translateY(8px); }\n  to   { opacity: 1; transform: translateY(0); }\n}\n\n\u002F* Remove or reduce for users who prefer it *\u002F\n@media (prefers-reduced-motion: reduce) {\n  *, *::before, *::after {\n    animation-duration: 0.01ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.01ms !important;\n    scroll-behavior: auto !important;\n  }\n}\n```\n\n```js\n\u002F\u002F Check in JavaScript\nconst prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;\n```\n\n### 6.2 Compositor-Friendly Animations\n\nAnimate only `transform` and `opacity` for smooth 60fps animation. These run on the GPU compositor thread.\n\n```css\n\u002F* Good: compositor-only properties *\u002F\n.slide-in {\n  transition: transform 200ms ease-out, opacity 200ms ease-out;\n}\n\n\u002F* Bad: triggers layout\u002Fpaint *\u002F\n.slide-in-bad {\n  transition: left 200ms, width 200ms, height 200ms;\n}\n```\n\n### 6.3 No Flashing Content\n\nNever flash content more than 3 times per second (SC 2.3.1). This can trigger seizures.\n\n### 6.4 Transitions for State Changes\n\nUse transitions for hover, focus, open\u002Fclose, and other state changes to provide continuity.\n\n```css\n.dropdown {\n  opacity: 0;\n  transform: translateY(-4px);\n  transition: opacity 150ms ease-out, transform 150ms ease-out;\n  pointer-events: none;\n}\n.dropdown.open {\n  opacity: 1;\n  transform: translateY(0);\n  pointer-events: auto;\n}\n```\n\n### 6.5 Meaningful Motion Only\n\nAnimation should communicate state, guide attention, or show spatial relationships. Never animate for decoration alone.\n\n---\n\n## 7. Dark Mode and Theming [MEDIUM]\n\n### 7.1 System Preference Detection\n\n```css\n@media (prefers-color-scheme: dark) {\n  :root {\n    --bg: #0f0f17;\n    --text: #e4e4ef;\n    --surface: #1c1c2e;\n    --border: #2e2e44;\n  }\n}\n```\n\n### 7.2 CSS Custom Properties for Theming\n\nDefine all theme values as custom properties. Toggle themes by changing property values.\n\n```css\n:root {\n  color-scheme: light dark;\n\n  \u002F* Light theme (default) *\u002F\n  --color-bg: #ffffff;\n  --color-surface: #f5f5f7;\n  --color-text-primary: #1a1a2e;\n  --color-text-secondary: #555770;\n  --color-border: #d1d1e0;\n  --color-primary: #2563eb;\n  --color-primary-text: #ffffff;\n  --color-error: #dc2626;\n  --color-success: #16a34a;\n}\n\n@media (prefers-color-scheme: dark) {\n  :root {\n    --color-bg: #0f0f17;\n    --color-surface: #1c1c2e;\n    --color-text-primary: #e4e4ef;\n    --color-text-secondary: #a0a0b8;\n    --color-border: #2e2e44;\n    --color-primary: #60a5fa;\n    --color-primary-text: #0f0f17;\n    --color-error: #f87171;\n    --color-success: #4ade80;\n  }\n}\n```\n\n### 7.3 Color-Scheme Meta Tag\n\nTell the browser about supported color schemes for native UI elements (scrollbars, form controls).\n\n```html\n\u003Cmeta name=\"color-scheme\" content=\"light dark\">\n```\n\n### 7.4 Maintain Contrast in Both Modes\n\nVerify contrast ratios in both light and dark modes. Dark mode often suffers from low-contrast text on dark surfaces.\n\n### 7.5 Adaptive Images\n\nProvide appropriate images for light and dark contexts.\n\n```html\n\u003Cpicture>\n  \u003Csource srcset=\"logo-dark.svg\" media=\"(prefers-color-scheme: dark)\">\n  \u003Cimg src=\"logo-light.svg\" alt=\"Company logo\">\n\u003C\u002Fpicture>\n```\n\n```css\n\u002F* Or use CSS filter for simple cases *\u002F\n@media (prefers-color-scheme: dark) {\n  .decorative-img {\n    filter: brightness(0.9) contrast(1.1);\n  }\n}\n```\n\n### 7.6 Respect prefers-contrast\n\nHonor the user's contrast preference using `@media (prefers-contrast: more)` and `@media (prefers-contrast: forced)`. `prefers-contrast: more` responds to macOS\u002FiOS \"Increase Contrast\" in System Settings; `prefers-contrast: forced` responds to Windows High Contrast Mode — a distinct OS feature that overrides colors entirely.\n\n```css\n\u002F* Default theme *\u002F\n:root {\n  --color-text: #555770;\n  --color-border: #d1d1e0;\n  --color-bg: #ffffff;\n}\n\n\u002F* High contrast mode: stronger text and border colors *\u002F\n@media (prefers-contrast: more) {\n  :root {\n    --color-text: #1a1a2e;       \u002F* Darker text for higher ratio *\u002F\n    --color-border: #1a1a2e;     \u002F* Stronger borders *\u002F\n    --color-bg: #ffffff;\n  }\n\n  \u002F* Ensure interactive elements are clearly delineated *\u002F\n  button, input, select, textarea {\n    border: 2px solid currentColor;\n  }\n}\n\n\u002F* Forced colors (Windows High Contrast mode) *\u002F\n@media (prefers-contrast: forced) {\n  \u002F* Use system color keywords to respect OS color palette *\u002F\n  :root {\n    --color-text: ButtonText;\n    --color-bg: ButtonFace;\n    --color-border: ButtonBorder;\n  }\n}\n```\n\n---\n\n## 8. Navigation and State [MEDIUM]\n\n### 8.1 URL Reflects State\n\nEvery meaningful view should have a unique URL. Users should be able to bookmark, share, and reload any state.\n\n```js\n\u002F\u002F Update URL without full page reload\nfunction updateFilters(filters) {\n  const params = new URLSearchParams(filters);\n  history.pushState(null, '', `?${params}`);\n  renderResults(filters);\n}\n\n\u002F\u002F Restore state from URL on load\nconst params = new URLSearchParams(location.search);\nconst initialFilters = Object.fromEntries(params);\n```\n\n### 8.2 Browser Back\u002FForward\n\nHandle `popstate` to support browser navigation.\n\n```js\nwindow.addEventListener('popstate', () => {\n  const params = new URLSearchParams(location.search);\n  renderResults(Object.fromEntries(params));\n});\n```\n\n### 8.3 Active Navigation States\n\nIndicate the current page or section in navigation. Use `aria-current=\"page\"` for the active link.\n\n```html\n\u003Cnav aria-label=\"Main\">\n  \u003Ca href=\"\u002F\" aria-current=\"page\">Home\u003C\u002Fa>\n  \u003Ca href=\"\u002Fproducts\">Products\u003C\u002Fa>\n  \u003Ca href=\"\u002Fabout\">About\u003C\u002Fa>\n\u003C\u002Fnav>\n```\n\n```css\n[aria-current=\"page\"] {\n  font-weight: 700;\n  border-bottom: 2px solid var(--color-primary);\n}\n```\n\n### 8.4 Breadcrumbs\n\nProvide breadcrumbs for sites with deep hierarchies.\n\n```html\n\u003Cnav aria-label=\"Breadcrumb\">\n  \u003Col>\n    \u003Cli>\u003Ca href=\"\u002F\">Home\u003C\u002Fa>\u003C\u002Fli>\n    \u003Cli>\u003Ca href=\"\u002Fproducts\">Products\u003C\u002Fa>\u003C\u002Fli>\n    \u003Cli>\u003Ca href=\"\u002Fproducts\u002Fwidgets\" aria-current=\"page\">Widgets\u003C\u002Fa>\u003C\u002Fli>\n  \u003C\u002Fol>\n\u003C\u002Fnav>\n```\n\n### 8.5 Scroll Restoration\n\nManage scroll position for SPA navigation.\n\n```js\n\u002F\u002F Disable browser auto-restoration for manual control\nif ('scrollRestoration' in history) {\n  history.scrollRestoration = 'manual';\n}\n\n\u002F\u002F Save scroll position before navigation\nfunction saveScrollPosition() {\n  sessionStorage.setItem(`scroll-${location.pathname}`, window.scrollY);\n}\n\n\u002F\u002F Restore on back\u002Fforward\nwindow.addEventListener('popstate', () => {\n  const saved = sessionStorage.getItem(`scroll-${location.pathname}`);\n  if (saved) {\n    requestAnimationFrame(() => window.scrollTo(0, parseInt(saved)));\n  }\n});\n```\n\n---\n\n## 9. Touch and Interaction [MEDIUM]\n\n### 9.1 Touch-Action for Scroll Control\n\nUse `touch-action` to control gesture behavior on interactive elements.\n\n```css\n\u002F* Allow only vertical scrolling (disable horizontal pan and pinch-zoom) *\u002F\n.vertical-scroll {\n  touch-action: pan-y;\n}\n\n\u002F* Carousel: horizontal scroll only *\u002F\n.carousel {\n  touch-action: pan-x;\n}\n\n\u002F* Canvas\u002Fmap: disable all browser gestures *\u002F\n.canvas {\n  touch-action: none;\n}\n```\n\n### 9.2 Tap Highlight\n\nControl the tap highlight on mobile WebKit browsers.\n\n```css\nbutton, a {\n  -webkit-tap-highlight-color: transparent;\n}\n```\n\n### 9.3 Hover and Focus Parity\n\nEvery hover interaction must also work with keyboard focus.\n\n```css\n\u002F* Always pair :hover with :focus-visible *\u002F\n.card:hover,\n.card:focus-visible {\n  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);\n  transform: translateY(-2px);\n}\n```\n\n### 9.4 No Hover-Only Interactions\n\nNever hide essential functionality behind hover. Touch devices have no hover state.\n\n```css\n\u002F* Bad: content only accessible on hover *\u002F\n\u002F* .tooltip { display: none; }\n   .trigger:hover .tooltip { display: block; } *\u002F\n\n\u002F* Good: works with focus and click too *\u002F\n.trigger:hover .tooltip,\n.trigger:focus-within .tooltip,\n.tooltip:focus-within {\n  display: block;\n}\n```\n\n### 9.5 Scroll Snap for Carousels\n\nUse CSS scroll snap for card carousels and horizontal lists.\n\n```css\n.carousel {\n  display: flex;\n  overflow-x: auto;\n  scroll-snap-type: x mandatory;\n  gap: 1rem;\n  scroll-padding: 1rem;\n}\n\n.carousel > .slide {\n  scroll-snap-align: start;\n  flex: 0 0 min(85%, 400px);\n}\n```\n\n---\n\n## 10. Internationalization [MEDIUM]\n\n### 10.1 dir and lang Attributes\n\nSet `lang` on the `\u003Chtml>` element. Use `dir=\"auto\"` for user-generated content.\n\n```html\n\u003Chtml lang=\"en\" dir=\"ltr\">\n\n\u003C!-- User-generated content: let browser detect direction -->\n\u003Cp dir=\"auto\">User-submitted text here\u003C\u002Fp>\n\n\u003C!-- Explicit override for known RTL content -->\n\u003Cblockquote lang=\"ar\" dir=\"rtl\">...\u003C\u002Fblockquote>\n```\n\n### 10.2 Intl APIs for Formatting\n\nUse the `Intl` API for locale-aware formatting. Never hard-code date or number formats.\n\n```js\n\u002F\u002F Dates\nnew Intl.DateTimeFormat('en-US', { dateStyle: 'long' }).format(date);\n\u002F\u002F \"January 15, 2026\"\n\n\u002F\u002F Numbers\nnew Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234.56);\n\u002F\u002F \"1.234,56 EUR\"\n\n\u002F\u002F Relative time\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(-1, 'day');\n\u002F\u002F \"yesterday\"\n\n\u002F\u002F Lists\nnew Intl.ListFormat('en', { style: 'long', type: 'conjunction' }).format(['a', 'b', 'c']);\n\u002F\u002F \"a, b, and c\"\n\n\u002F\u002F Plurals\nconst pr = new Intl.PluralRules('en');\nconst suffixes = { one: 'st', two: 'nd', few: 'rd', other: 'th' };\nfunction ordinal(n) { return `${n}${suffixes[pr.select(n)]}`; }\n```\n\n### 10.3 Avoid Text in Images\n\nText in images cannot be translated, resized, or read by screen readers. Use HTML\u002FCSS text with background images when a styled text overlay is needed.\n\n### 10.4 CSS Logical Properties\n\nUse logical properties instead of physical ones to support both LTR and RTL layouts.\n\n```css\n\u002F* Physical (breaks in RTL) *\u002F\n\u002F* margin-left: 1rem; padding-right: 2rem; border-left: 1px solid; *\u002F\n\n\u002F* Logical (works in LTR and RTL) *\u002F\n.sidebar {\n  margin-inline-start: 1rem;\n  padding-inline-end: 2rem;\n  border-inline-start: 1px solid var(--color-border);\n}\n\n.stack > * + * {\n  margin-block-start: 1rem;\n}\n\n\u002F* Logical shorthands *\u002F\n.box {\n  margin-inline: auto;     \u002F* left + right *\u002F\n  padding-block: 2rem;     \u002F* top + bottom *\u002F\n  inset-inline-start: 0;   \u002F* left in LTR, right in RTL *\u002F\n  border-start-start-radius: 8px; \u002F* top-left in LTR, top-right in RTL *\u002F\n}\n```\n\n| Physical | Logical |\n|----------|---------|\n| `left` \u002F `right` | `inline-start` \u002F `inline-end` |\n| `top` \u002F `bottom` | `block-start` \u002F `block-end` |\n| `margin-left` | `margin-inline-start` |\n| `padding-right` | `padding-inline-end` |\n| `border-top-left-radius` | `border-start-start-radius` |\n| `width` | `inline-size` |\n| `height` | `block-size` |\n| `text-align: left` | `text-align: start` |\n\n### 10.5 RTL Layout Support\n\nTest layouts in RTL mode. Flexbox and Grid handle RTL automatically with logical properties.\n\n```css\n\u002F* This layout works in both LTR and RTL without changes *\u002F\n.layout {\n  display: flex;\n  gap: 1rem;\n}\n\n\u002F* Icons that indicate direction need flipping *\u002F\n[dir=\"rtl\"] .arrow-icon {\n  transform: scaleX(-1);\n}\n```\n\n---\n\n## 11. Progressive Web Apps [MEDIUM]\n\nPWAs allow web apps to be installed and run offline. When building an installable web app, the following rules ensure the experience is consistent and reliable.\n\n### 11.1 Provide a Complete Web App Manifest\n\nInclude a `manifest.json` linked from `\u003Chead>` with all required fields for installability. Missing fields silently prevent install prompts.\n\n```html\n\u003Clink rel=\"manifest\" href=\"\u002Fmanifest.json\">\n```\n\n```json\n{\n  \"name\": \"My App\",\n  \"short_name\": \"App\",\n  \"start_url\": \"\u002F\",\n  \"display\": \"standalone\",\n  \"icons\": [\n    { \"src\": \"\u002Ficons\u002Ficon-192.png\", \"sizes\": \"192x192\", \"type\": \"image\u002Fpng\" },\n    { \"src\": \"\u002Ficons\u002Ficon-512.png\", \"sizes\": \"512x512\", \"type\": \"image\u002Fpng\" }\n  ]\n}\n```\n\n**Incorrect:**\n```json\n{\n  \"name\": \"My App\"\n  \u002F\u002F Missing start_url, display, and icons — app is not installable\n}\n```\n\n### 11.2 Set theme_color and background_color\n\n`theme_color` tints the browser chrome and the OS task switcher. `background_color` fills the splash screen before the app loads. Both must match your brand colors.\n\n```json\n{\n  \"theme_color\": \"#1a73e8\",\n  \"background_color\": \"#ffffff\"\n}\n```\n\n### 11.3 Register a Service Worker for Offline Support\n\nA service worker is required for installability and offline capability. Cache critical assets on install; respond from cache when offline.\n\n```js\n\u002F\u002F In your main entry point\nif ('serviceWorker' in navigator) {\n  navigator.serviceWorker.register('\u002Fsw.js');\n}\n```\n\n```js\n\u002F\u002F sw.js — cache on install, serve from cache when offline\nconst CACHE = 'v1';\nconst PRECACHE = ['\u002F', '\u002Findex.html', '\u002Fapp.js', '\u002Fapp.css'];\n\nself.addEventListener('install', e =>\n  e.waitUntil(caches.open(CACHE).then(c => c.addAll(PRECACHE)))\n);\n\nself.addEventListener('fetch', e =>\n  e.respondWith(\n    caches.match(e.request).then(hit => hit ?? fetch(e.request))\n  )\n);\n```\n\n### 11.4 Meet Installability Criteria\n\nFor the browser install prompt to appear: the app must be served over HTTPS, have a registered service worker with a `fetch` handler, and include a manifest with `name`, `icons`, `start_url`, and `display: standalone` (or `fullscreen`\u002F`minimal-ui`).\n\n### 11.5 Use display Mode Appropriately\n\n| Value | Use When |\n|-------|----------|\n| `standalone` | App replaces browser UI; most common choice |\n| `fullscreen` | Games or media apps needing the entire screen |\n| `minimal-ui` | Retain minimal browser controls (back, reload) |\n| `browser` | No installation behavior; opens in browser tab |\n\n---\n\n## Evaluation Checklist\n\nUse this checklist when building or reviewing web interfaces.\n\n### Accessibility\n- [ ] All images have appropriate `alt` text\n- [ ] Color contrast meets 4.5:1 (text) and 3:1 (UI components)\n- [ ] All interactive elements are keyboard accessible\n- [ ] Focus indicators are visible (3:1 contrast, 2px minimum perimeter)\n- [ ] Skip navigation link is present\n- [ ] Form inputs have associated labels\n- [ ] Error messages are linked to their inputs\n- [ ] Dynamic content updates use ARIA live regions\n- [ ] No content flashes more than 3 times per second\n- [ ] Page has proper heading hierarchy (h1-h6, no skips)\n- [ ] Landmarks are used correctly (main, nav, header, footer)\n\n### Responsive\n- [ ] No horizontal scrolling at 320px width\n- [ ] Touch targets are at least 44x44px\n- [ ] Viewport meta tag is present (no user-scalable=no)\n- [ ] Layout works on mobile, tablet, and desktop\n- [ ] Text is readable without zooming on mobile\n\n### Forms\n- [ ] All inputs have visible labels\n- [ ] Autocomplete attributes are set for common fields\n- [ ] Correct input types trigger correct mobile keyboards\n- [ ] Error messages are clear and specific\n- [ ] Required fields are indicated\n- [ ] Submit button is not disabled\n\n### Performance\n- [ ] Below-fold images use `loading=\"lazy\"`\n- [ ] Images have explicit `width` and `height`\n- [ ] Critical fonts are preloaded\n- [ ] Third-party origins use `preconnect`\n- [ ] Large JS bundles are code-split\n\n### Motion and Theming\n- [ ] `prefers-reduced-motion` is respected\n- [ ] Animations use only `transform` and `opacity`\n- [ ] Dark mode maintains contrast ratios\n- [ ] `color-scheme` meta tag is present\n- [ ] Theme uses CSS custom properties\n- [ ] `prefers-contrast: more` increases text and border contrast\n- [ ] `prefers-contrast: forced` uses system color keywords\n\n### Internationalization\n- [ ] `lang` attribute on `\u003Chtml>`\n- [ ] CSS logical properties used (not physical)\n- [ ] Dates\u002Fnumbers formatted with Intl APIs\n- [ ] No text embedded in images\n- [ ] Layout tested in RTL mode\n\n### Progressive Web App\n- [ ] Web App Manifest linked from `\u003Chead>` with `name`, `icons`, `start_url`, and `display`\n- [ ] `theme_color` and `background_color` match brand palette\n- [ ] Service worker registered with a `fetch` handler for offline support\n- [ ] App served over HTTPS\n\n---\n\n## Common Anti-Patterns\n\n| Anti-Pattern | Fix |\n|--------------|-----|\n| `\u003Cdiv onclick=\"...\">` | Use `\u003Cbutton>` |\n| `outline: none` without replacement | Use `:focus-visible` with custom outline |\n| `placeholder` as label | Add a `\u003Clabel>` element |\n| `tabindex=\"5\"` | Use `tabindex=\"0\"` or natural order |\n| `user-scalable=no` | Remove it |\n| `font-size: 12px` | Use `font-size: 0.75rem` |\n| Animating `width`\u002F`height`\u002F`top`\u002F`left` | Animate `transform` and `opacity` |\n| Disabling submit button | Validate on submit, show errors |\n| Color alone for status | Add icon, text, or pattern |\n| `margin-left` \u002F `padding-right` | Use `margin-inline-start` \u002F `padding-inline-end` |\n| `\u003Cimg>` without dimensions | Add `width` and `height` attributes |\n| Hover-only disclosure | Add `:focus-within` and click handler |\n","# Web Platform Design Guidelines\n\nFramework-agnostic rules for accessible, performant, responsive web interfaces. Based on WCAG 2.2, MDN Web Docs, and modern web platform APIs.\n\n---\n\n## 1. Accessibility \u002F WCAG [CRITICAL]\n\nAccessibility is not optional. Most rules in this section map to WCAG 2.2 success criteria at Level A or AA. A small number of best-practice rules (noted inline) target Level AAA or go beyond WCAG.\n\n### 1.1 Use Semantic HTML Elements\n\nUse elements for their intended purpose. Semantic structure provides free accessibility, SEO, and reader-mode support.\n\n| Element | Purpose |\n|---------|---------|\n| `\u003Cmain>` | Primary page content (one per page) |\n| `\u003Cnav>` | Navigation blocks |\n| `\u003Cheader>` | Introductory content or navigational aids |\n| `\u003Cfooter>` | Footer for nearest sectioning content |\n| `\u003Carticle>` | Self-contained, independently distributable content |\n| `\u003Csection>` | Thematic grouping with a heading |\n| `\u003Caside>` | Tangentially related content (sidebars, callouts) |\n| `\u003Cfigure>` \u002F `\u003Cfigcaption>` | Illustrations, diagrams, code listings |\n| `\u003Cdetails>` \u002F `\u003Csummary>` | Expandable\u002Fcollapsible disclosure widget |\n| `\u003Cdialog>` | Modal or non-modal dialog boxes |\n| `\u003Ctime>` | Machine-readable dates\u002Ftimes |\n| `\u003Cmark>` | Highlighted\u002Freferenced text |\n| `\u003Caddress>` | Contact information for nearest article\u002Fbody |\n\n```html\n\u003C!-- Good -->\n\u003Cmain>\n  \u003Carticle>\n    \u003Ch1>Article Title\u003C\u002Fh1>\n    \u003Cp>Content...\u003C\u002Fp>\n  \u003C\u002Farticle>\n  \u003Caside>Related links\u003C\u002Faside>\n\u003C\u002Fmain>\n\n\u003C!-- Bad: div soup -->\n\u003Cdiv class=\"main\">\n  \u003Cdiv class=\"article\">\n    \u003Cdiv class=\"title\">Article Title\u003C\u002Fdiv>\n    \u003Cdiv class=\"content\">Content...\u003C\u002Fdiv>\n  \u003C\u002Fdiv>\n\u003C\u002Fdiv>\n```\n\n**Anti-pattern**: Using `\u003Cdiv>` or `\u003Cspan>` for interactive elements. Never write `\u003Cdiv onclick>` when `\u003Cbutton>` exists.\n\n### 1.2 ARIA Labels on Interactive Elements\n\nEvery interactive element must have an accessible name. Prefer visible text; use `aria-label` or `aria-labelledby` only when visible text is insufficient (SC 4.1.2).\n\n```html\n\u003C!-- Icon-only button: needs aria-label -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n\n\u003C!-- Linked by labelledby -->\n\u003Ch2 id=\"section-title\">Notifications\u003C\u002Fh2>\n\u003Cul aria-labelledby=\"section-title\">...\u003C\u002Ful>\n\n\u003C!-- Redundant: visible text is enough -->\n\u003Cbutton>Save Changes\u003C\u002Fbutton> \u003C!-- No aria-label needed -->\n```\n\n### 1.3 Keyboard Navigation\n\nAll interactive elements must be reachable and operable via keyboard (SC 2.1.1).\n\n- Use native interactive elements (`\u003Cbutton>`, `\u003Ca href>`, `\u003Cinput>`, `\u003Cselect>`) which are keyboard-accessible by default.\n- Custom widgets need `tabindex=\"0\"` to enter tab order and keydown handlers for activation.\n- Never use `tabindex` values greater than 0.\n- Trap focus inside modals; return focus on close.\n\n```js\n\u002F\u002F Focus trap for modal\ndialog.addEventListener('keydown', (e) => {\n  if (e.key === 'Tab') {\n    const focusable = dialog.querySelectorAll(\n      'button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])'\n    );\n    const first = focusable[0];\n    const last = focusable[focusable.length - 1];\n    if (e.shiftKey && document.activeElement === first) {\n      e.preventDefault();\n      last.focus();\n    } else if (!e.shiftKey && document.activeElement === last) {\n      e.preventDefault();\n      first.focus();\n    }\n  }\n});\n```\n\n### 1.4 Visible Focus Indicators\n\nNever remove focus outlines without providing a visible replacement (SC 2.4.7, enhanced SC 2.4.11 (AA) and SC 2.4.12 (AAA) in WCAG 2.2).\n\n```css\n\u002F* Good: custom focus indicator *\u002F\n:focus-visible {\n  outline: 3px solid var(--focus-color, #4A90D9);\n  outline-offset: 2px;\n}\n\n\u002F* Remove default only when :focus-visible is supported *\u002F\n:focus:not(:focus-visible) {\n  outline: none;\n}\n\n\u002F* Bad: removing all focus styles *\u002F\n\u002F* *:focus { outline: none; } *\u002F\n```\n\nWCAG 2.2 requires focus indicators to have a minimum area of the perimeter of the component times 2px, with 3:1 contrast against adjacent colors.\n\n### 1.5 Skip Navigation Links\n\nProvide a mechanism to skip repeated blocks of content (SC 2.4.1).\n\n```html\n\u003Cbody>\n  \u003Ca href=\"#main-content\" class=\"skip-link\">Skip to main content\u003C\u002Fa>\n  \u003Cnav>...\u003C\u002Fnav>\n  \u003Cmain id=\"main-content\">...\u003C\u002Fmain>\n\u003C\u002Fbody>\n```\n\n```css\n.skip-link {\n  position: absolute;\n  top: -100%;\n  left: 0;\n  z-index: 1000;\n  padding: 0.75rem 1.5rem;\n  background: var(--color-primary);\n  color: var(--color-on-primary);\n}\n.skip-link:focus {\n  top: 0;\n}\n```\n\n### 1.6 Alt Text for Images\n\nEvery `\u003Cimg>` must have an `alt` attribute (SC 1.1.1).\n\n- **Informative images**: describe the content and function. `alt=\"Bar chart showing sales doubled in Q4\"`.\n- **Decorative images**: use `alt=\"\"` (empty string) so screen readers skip them.\n- **Functional images** (inside links\u002Fbuttons): describe the action. `alt=\"Search\"`.\n- **Complex images**: use `alt` for short description, link to long description or use `\u003Cfigcaption>`.\n\n```html\n\u003Cimg src=\"chart.png\" alt=\"Revenue chart: Q1 $2M, Q2 $2.4M, Q3 $3.1M, Q4 $4.5M\">\n\u003Cimg src=\"decorative-wave.svg\" alt=\"\">\n```\n\n### 1.7 Color Contrast\n\nMaintain minimum contrast ratios (SC 1.4.3, 1.4.6, 1.4.11).\n\n| Content | Minimum Ratio |\n|---------|--------------|\n| Normal text (\u003C24px \u002F \u003C18.66px bold) | 4.5:1 |\n| Large text (>=24px \u002F >=18.66px bold) | 3:1 |\n| UI components and graphical objects | 3:1 |\n\nDo not rely on color alone to convey information (SC 1.4.1). Pair color with icons, text, or patterns.\n\n```css\n\u002F* Check contrast of these tokens *\u002F\n:root {\n  --text-primary: #1a1a2e;    \u002F* on white: ~16:1 *\u002F\n  --text-secondary: #555770;  \u002F* on white: ~6.5:1 *\u002F\n  --text-disabled: #767693;   \u002F* on white: ~4.5:1, borderline *\u002F\n}\n```\n\n### 1.8 Form Labels\n\nEvery form input must have a programmatically associated label (SC 1.3.1, 3.3.2).\n\n```html\n\u003C!-- Explicit label (preferred) -->\n\u003Clabel for=\"email\">Email address\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" autocomplete=\"email\">\n\n\u003C!-- Implicit label (acceptable) -->\n\u003Clabel>\n  Email address\n  \u003Cinput type=\"email\" autocomplete=\"email\">\n\u003C\u002Flabel>\n\n\u003C!-- Never: placeholder as sole label -->\n\u003C!-- \u003Cinput placeholder=\"Email\"> -->\n```\n\n### 1.9 Error Identification\n\nIdentify and describe errors in text (SC 3.3.1). Link error messages to inputs with `aria-describedby` or `aria-errormessage`.\n\n```html\n\u003Clabel for=\"email\">Email\u003C\u002Flabel>\n\u003Cinput id=\"email\" type=\"email\" aria-describedby=\"email-error\" aria-invalid=\"true\">\n\u003Cp id=\"email-error\" role=\"alert\">Enter a valid email address, e.g. name@example.com\u003C\u002Fp>\n```\n\n### 1.10 ARIA Live Regions\n\nAnnounce dynamic content changes to screen readers (SC 4.1.3).\n\n```html\n\u003C!-- Polite: announced when user is idle -->\n\u003Cdiv aria-live=\"polite\" aria-atomic=\"true\">\n  3 results found\n\u003C\u002Fdiv>\n\n\u003C!-- Assertive: interrupts current speech -->\n\u003Cdiv role=\"alert\">\n  Your session will expire in 2 minutes.\n\u003C\u002Fdiv>\n\n\u003C!-- Status messages -->\n\u003Cdiv role=\"status\">\n  File uploaded successfully.\n\u003C\u002Fdiv>\n```\n\nUse `aria-live=\"polite\"` by default. Reserve `role=\"alert\"` \u002F `aria-live=\"assertive\"` for time-sensitive warnings.\n\n### 1.11 ARIA Role Quick Reference\n\n| Role | Purpose | Native Equivalent |\n|------|---------|-------------------|\n| `button` | Clickable action | `\u003Cbutton>` |\n| `link` | Navigation | `\u003Ca href>` |\n| `tab` \u002F `tablist` \u002F `tabpanel` | Tab interface | None |\n| `dialog` | Modal | `\u003Cdialog>` |\n| `alert` | Assertive live region | None |\n| `status` | Polite live region | `\u003Coutput>` |\n| `navigation` | Nav landmark | `\u003Cnav>` |\n| `main` | Main landmark | `\u003Cmain>` |\n| `complementary` | Aside landmark | `\u003Caside>` |\n| `search` | Search landmark | `\u003Csearch>` (HTML5) |\n| `img` | Image | `\u003Cimg>` |\n| `list` \u002F `listitem` | List | `\u003Cul>\u002F\u003Cli>` |\n| `heading` | Heading (with `aria-level`) | `\u003Ch1>`-`\u003Ch6>` |\n| `menu` \u002F `menuitem` | Menu widget | None |\n| `tree` \u002F `treeitem` | Tree view | None |\n| `grid` \u002F `row` \u002F `gridcell` | Data grid | `\u003Ctable>` |\n| `progressbar` | Progress | `\u003Cprogress>` |\n| `slider` | Range input | `\u003Cinput type=\"range\">` |\n| `switch` | Toggle | `\u003Cinput type=\"checkbox\">` |\n\n**Rule**: Prefer native HTML over ARIA. Use ARIA only when no native element exists for the pattern.\n\n### 1.12 Label in Name (WCAG 2.5.3 Level A)\n\nWhen an interactive element has visible text, its accessible name must contain that visible text as a substring (SC 2.5.3). Voice control users (Dragon NaturallySpeaking, macOS Voice Control) speak the visible label to activate controls. If `aria-label` replaces or contradicts the visible text, voice commands fail.\n\n```html\n\u003C!-- Correct: aria-label contains visible text as substring -->\n\u003Cbutton aria-label=\"Delete item from cart\">Delete\u003C\u002Fbutton>\n\n\u003C!-- Correct: no aria-label needed — visible text is the accessible name -->\n\u003Cbutton>Save Changes\u003C\u002Fbutton>\n\n\u003C!-- Correct: icon button — no visible text, aria-label is fine -->\n\u003Cbutton aria-label=\"Close dialog\">\n  \u003Csvg aria-hidden=\"true\">...\u003C\u002Fsvg>\n\u003C\u002Fbutton>\n```\n\n```html\n\u003C!-- Incorrect: aria-label overrides visible text with different text -->\n\u003Cbutton aria-label=\"Remove\">Delete\u003C\u002Fbutton>\n\n\u003C!-- Incorrect: aria-label does not contain visible \"Submit\" -->\n\u003Cbutton aria-label=\"Proceed to next step\">Submit\u003C\u002Fbutton>\n```\n\n**Rule**: When visible text is present, `aria-label` must include that visible text (verbatim, case-insensitively). Prefer no `aria-label` at all when visible text is sufficient.\n\n---\n\n## 2. Responsive Design [CRITICAL]\n\n### 2.1 Mobile-First Approach\n\nWrite base styles for the smallest viewport. Layer complexity with `min-width` media queries.\n\n```css\n\u002F* Base: mobile *\u002F\n.grid {\n  display: grid;\n  grid-template-columns: 1fr;\n  gap: 1rem;\n}\n\n\u002F* Tablet *\u002F\n@media (min-width: 48rem) {\n  .grid {\n    grid-template-columns: repeat(2, 1fr);\n  }\n}\n\n\u002F* Desktop *\u002F\n@media (min-width: 64rem) {\n  .grid {\n    grid-template-columns: repeat(3, 1fr);\n  }\n}\n```\n\n### 2.2 Fluid Layouts with Modern CSS Functions\n\nUse `clamp()`, `min()`, and `max()` for fluid sizing without breakpoints.\n\n```css\n\u002F* Fluid typography *\u002F\nh1 {\n  font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem);\n}\n\n\u002F* Fluid spacing *\u002F\n.section {\n  padding: clamp(1.5rem, 4vw, 4rem);\n}\n\n\u002F* Fluid container *\u002F\n.container {\n  width: min(90%, 72rem);\n  margin-inline: auto;\n}\n```\n\n### 2.3 Container Queries\n\nSize components based on their container, not the viewport.\n\n```css\n.card-container {\n  container-type: inline-size;\n  container-name: card;\n}\n\n@container card (min-width: 400px) {\n  .card {\n    display: grid;\n    grid-template-columns: 200px 1fr;\n  }\n}\n\n@container card (min-width: 700px) {\n  .card {\n    grid-template-columns: 300px 1fr;\n    gap: 2rem;\n  }\n}\n```\n\n### 2.4 Content-Based Breakpoints\n\nSet breakpoints where your content breaks, not at device widths. Common starting points:\n\n```css\n\u002F* Content-based, not \"iPhone\" or \"iPad\" *\u002F\n@media (min-width: 30rem)  { \u002F* ~480px: single column gets cramped *\u002F }\n@media (min-width: 48rem)  { \u002F* ~768px: room for 2 columns *\u002F }\n@media (min-width: 64rem)  { \u002F* ~1024px: room for sidebar + content *\u002F }\n@media (min-width: 80rem)  { \u002F* ~1280px: wide multi-column *\u002F }\n```\n\n### 2.5 Touch Targets\n\nMinimum 44x44 CSS pixels for touch targets (WCAG SC 2.5.5 AAA; SC 2.5.8 requires only 24x24px at AA). Provide at least 24px spacing between adjacent targets.\n\n```css\nbutton, a, input, select, textarea {\n  min-height: 44px;\n  min-width: 44px;\n}\n\n\u002F* Enlarge tap area without changing visual size *\u002F\n.icon-button {\n  position: relative;\n  width: 24px;\n  height: 24px;\n}\n.icon-button::after {\n  content: \"\";\n  position: absolute;\n  inset: -10px; \u002F* expands clickable area *\u002F\n}\n```\n\n### 2.6 Viewport Meta Tag\n\nAlways include in the document `\u003Chead>`:\n\n```html\n\u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n```\n\nNever use `maximum-scale=1` or `user-scalable=no` -- these break pinch-to-zoom accessibility (SC 1.4.4).\n\n### 2.7 No Horizontal Scrolling\n\nContent must reflow at 320px width without horizontal scrolling (SC 1.4.10).\n\n```css\n\u002F* Prevent overflow *\u002F\nimg, video, iframe, svg {\n  max-width: 100%;\n  height: auto;\n}\n\n\u002F* Contain long words\u002FURLs *\u002F\n.prose {\n  overflow-wrap: break-word;\n}\n\n\u002F* Tables: scroll container, not page *\u002F\n.table-wrapper {\n  overflow-x: auto;\n  -webkit-overflow-scrolling: touch;\n}\n```\n\n---\n\n## 3. Forms [HIGH]\n\n### 3.1 Label Every Input\n\nEvery input needs a visible, programmatically associated label. See section 1.8.\n\n### 3.2 Autocomplete Attributes\n\nUse `autocomplete` for common fields to enable browser autofill (SC 1.3.5).\n\n```html\n\u003Cinput type=\"text\" autocomplete=\"name\" name=\"full-name\">\n\u003Cinput type=\"email\" autocomplete=\"email\" name=\"email\">\n\u003Cinput type=\"tel\" autocomplete=\"tel\" name=\"phone\">\n\u003Cinput type=\"text\" autocomplete=\"street-address\" name=\"address\">\n\u003Cinput type=\"text\" autocomplete=\"postal-code\" name=\"zip\">\n\u003Cinput type=\"text\" autocomplete=\"cc-name\" name=\"card-name\">\n\u003Cinput type=\"text\" autocomplete=\"cc-number\" name=\"card-number\">\n\u003Cinput type=\"password\" autocomplete=\"new-password\" name=\"password\">\n\u003Cinput type=\"password\" autocomplete=\"current-password\" name=\"current-pw\">\n```\n\n### 3.3 Correct Input Types\n\nUse the right `type` to trigger appropriate mobile keyboards and native validation.\n\n| Type | Use For |\n|------|---------|\n| `email` | Email addresses |\n| `tel` | Phone numbers |\n| `url` | URLs |\n| `number` | Numeric values with spinners (not for phone, zip, card numbers) |\n| `search` | Search fields (shows clear button) |\n| `date` \u002F `time` \u002F `datetime-local` | Temporal values |\n| `password` | Passwords (triggers password manager) |\n| `text` with `inputmode=\"numeric\"` | Numeric data without spinners (PINs, zip codes) |\n\n```html\n\u003Cinput type=\"tel\" inputmode=\"numeric\" pattern=\"[0-9]*\" autocomplete=\"one-time-code\">\n```\n\n### 3.4 Inline Validation\n\nValidate on `blur` (not on every keystroke). Show success and error states.\n\n```html\n\u003Cdiv class=\"field\" data-state=\"error\">\n  \u003Clabel for=\"username\">Username\u003C\u002Flabel>\n  \u003Cinput id=\"username\" type=\"text\" aria-describedby=\"username-hint username-error\" aria-invalid=\"true\">\n  \u003Cp id=\"username-hint\" class=\"hint\">3-20 characters, letters and numbers only\u003C\u002Fp>\n  \u003Cp id=\"username-error\" class=\"error\" role=\"alert\">Username must be at least 3 characters\u003C\u002Fp>\n\u003C\u002Fdiv>\n```\n\n```css\n.field[data-state=\"error\"] input {\n  border-color: var(--color-error);\n  box-shadow: 0 0 0 1px var(--color-error);\n}\n.field[data-state=\"error\"] .error { display: block; }\n.field:not([data-state=\"error\"]) .error { display: none; }\n```\n\n### 3.5 Fieldset and Legend for Groups\n\nGroup related inputs with `\u003Cfieldset>` and label the group with `\u003Clegend>`.\n\n```html\n\u003Cfieldset>\n  \u003Clegend>Shipping Address\u003C\u002Flegend>\n  \u003Clabel for=\"street\">Street\u003C\u002Flabel>\n  \u003Cinput id=\"street\" type=\"text\" autocomplete=\"street-address\">\n  \u003C!-- ... -->\n\u003C\u002Ffieldset>\n\n\u003Cfieldset>\n  \u003Clegend>Preferred contact method\u003C\u002Flegend>\n  \u003Clabel>\u003Cinput type=\"radio\" name=\"contact\" value=\"email\"> Email\u003C\u002Flabel>\n  \u003Clabel>\u003Cinput type=\"radio\" name=\"contact\" value=\"phone\"> Phone\u003C\u002Flabel>\n\u003C\u002Ffieldset>\n```\n\n### 3.6 Required Field Indication\n\nIndicate required fields visually and programmatically. Use `required` attribute and visible markers.\n\n```html\n\u003Clabel for=\"name\">\n  Full name \u003Cspan aria-hidden=\"true\">*\u003C\u002Fspan>\n  \u003Cspan class=\"sr-only\">(required)\u003C\u002Fspan>\n\u003C\u002Flabel>\n\u003Cinput id=\"name\" type=\"text\" required autocomplete=\"name\">\n```\n\nIf most fields are required, indicate which are optional instead.\n\n### 3.7 Submit Button State\n\nDo not disable the submit button. Instead, validate on submit and show errors.\n\n```html\n\u003C!-- Good: always enabled, validate on submit -->\n\u003Cbutton type=\"submit\">Create Account\u003C\u002Fbutton>\n\n\u003C!-- Bad: disabled button with no explanation -->\n\u003C!-- \u003Cbutton type=\"submit\" disabled>Create Account\u003C\u002Fbutton> -->\n```\n\nDisabled buttons fail to communicate why the user cannot proceed. If you must disable, provide a visible explanation.\n\n### 3.8 Keep Instructions Near the Field\n\nPlace format examples, constraints, and recovery text next to the relevant field via hint and error text. Never explain requirements only once in introductory copy and expect users to remember them later.\n\n---\n\n## 4. Typography [HIGH]\n\n### 4.1 Font Stacks\n\nUse system font stacks for performance, or web fonts with proper fallbacks.\n\n```css\n\u002F* System font stack *\u002F\nbody {\n  font-family: system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif;\n}\n\n\u002F* Monospace stack *\u002F\ncode, pre, kbd {\n  font-family: ui-monospace, \"Cascadia Code\", \"Source Code Pro\", Menlo, Consolas, monospace;\n}\n\n\u002F* Web font with fallbacks and size-adjust *\u002F\n@font-face {\n  font-family: \"CustomFont\";\n  src: url(\"\u002Ffonts\u002Fcustom.woff2\") format(\"woff2\");\n  font-display: swap;\n  font-weight: 100 900;\n}\nbody {\n  font-family: \"CustomFont\", system-ui, sans-serif;\n}\n```\n\n### 4.2 Relative Units\n\nUse `rem` for font sizes and spacing. Use `em` for component-relative sizing.\n\n```css\nhtml {\n  font-size: 100%; \u002F* = 16px default, respects user preference *\u002F\n}\n\nbody {\n  font-size: 1rem;       \u002F* 16px *\u002F\n}\n\nh1 { font-size: 2.5rem; }  \u002F* 40px *\u002F\nh2 { font-size: 2rem; }    \u002F* 32px *\u002F\nh3 { font-size: 1.5rem; }  \u002F* 24px *\u002F\nsmall { font-size: 0.875rem; } \u002F* 14px *\u002F\n\n\u002F* Never: font-size: 16px; (ignores user zoom settings) *\u002F\n```\n\n### 4.3 Line Height and Spacing\n\nBody text line height of at least 1.5 (SC 1.4.12). Paragraph spacing at least 2x font size.\n\n```css\nbody {\n  line-height: 1.6;\n}\n\nh1, h2, h3 {\n  line-height: 1.2;\n}\n\np + p {\n  margin-top: 1em;\n}\n```\n\n### 4.4 Maximum Line Length\n\nLimit line length to approximately 75 characters for readability.\n\n```css\n.prose {\n  max-width: 75ch;\n}\n\n\u002F* Or for a content column *\u002F\n.content {\n  max-width: 40rem; \u002F* roughly 65-75ch depending on font *\u002F\n  margin-inline: auto;\n}\n```\n\n### 4.5 Typographic Details\n\nUse real quotes, proper dashes, and tabular numbers for data.\n\n```css\n\u002F* Smart quotes *\u002F\nq { quotes: \"\\201C\" \"\\201D\" \"\\2018\" \"\\2019\"; } \u002F* curly double then single *\u002F\n\n\u002F* Tabular numbers for aligned data *\u002F\n.data-table td {\n  font-variant-numeric: tabular-nums;\n}\n\n\u002F* Oldstyle numbers for running prose (optional) *\u002F\n.prose {\n  font-variant-numeric: oldstyle-nums;\n}\n\n\u002F* Proper list markers *\u002F\nul { list-style-type: disc; }\nol { list-style-type: decimal; }\n```\n\n### 4.6 Heading Hierarchy\n\nUse `h1` through `h6` in order. Never skip levels. One `h1` per page.\n\n```html\n\u003C!-- Good -->\n\u003Ch1>Page Title\u003C\u002Fh1>\n  \u003Ch2>Section\u003C\u002Fh2>\n    \u003Ch3>Subsection\u003C\u002Fh3>\n  \u003Ch2>Another Section\u003C\u002Fh2>\n\n\u003C!-- Bad: skipping h2 -->\n\u003Ch1>Page Title\u003C\u002Fh1>\n  \u003Ch3>Subsection\u003C\u002Fh3> \u003C!-- Where is h2? -->\n```\n\nIf you need visual styling that differs from the hierarchy, use CSS classes:\n\n```html\n\u003Ch2 class=\"text-lg\">Visually smaller but semantically h2\u003C\u002Fh2>\n```\n\n---\n\n## 5. Performance [HIGH]\n\n### 5.1 Lazy Load Below-Fold Images\n\nUse native lazy loading for images not visible on initial load.\n\n```html\n\u003C!-- Above fold: load eagerly, add fetchpriority -->\n\u003Cimg src=\"hero.webp\" alt=\"Hero image\" fetchpriority=\"high\" width=\"1200\" height=\"600\">\n\n\u003C!-- Below fold: lazy load -->\n\u003Cimg src=\"feature.webp\" alt=\"Feature image\" loading=\"lazy\" width=\"600\" height=\"400\">\n```\n\n### 5.2 Explicit Image Dimensions\n\nAlways specify `width` and `height` to prevent layout shift (CLS).\n\n```html\n\u003Cimg src=\"photo.webp\" alt=\"Description\" width=\"800\" height=\"600\">\n```\n\n```css\n\u002F* Responsive images with aspect ratio preservation *\u002F\nimg {\n  max-width: 100%;\n  height: auto;\n}\n```\n\n### 5.3 Resource Hints\n\nUse `preconnect` for third-party origins and `preload` for critical resources.\n\n```html\n\u003Chead>\n  \u003C!-- Preconnect to critical third-party origins -->\n  \u003Clink rel=\"preconnect\" href=\"https:\u002F\u002Ffonts.googleapis.com\">\n  \u003Clink rel=\"preconnect\" href=\"https:\u002F\u002Fcdn.example.com\" crossorigin>\n\n  \u003C!-- Preload critical resources -->\n  \u003Clink rel=\"preload\" href=\"\u002Ffonts\u002Fmain.woff2\" as=\"font\" type=\"font\u002Fwoff2\" crossorigin>\n  \u003Clink rel=\"preload\" href=\"\u002Fcss\u002Fcritical.css\" as=\"style\">\n\n  \u003C!-- DNS prefetch for non-critical origins -->\n  \u003Clink rel=\"dns-prefetch\" href=\"https:\u002F\u002Fanalytics.example.com\">\n\u003C\u002Fhead>\n```\n\n### 5.4 Code Splitting\n\nLoad JavaScript only when needed. Use dynamic `import()` for route-based and component-based splitting.\n\n```js\n\u002F\u002F Route-based splitting\nconst routes = {\n  '\u002Fdashboard': () => import('.\u002Fpages\u002Fdashboard.js'),\n  '\u002Fsettings':  () => import('.\u002Fpages\u002Fsettings.js'),\n};\n\n\u002F\u002F Interaction-based splitting\nbutton.addEventListener('click', async () => {\n  const { openEditor } = await import('.\u002Feditor.js');\n  openEditor();\n});\n```\n\n### 5.5 Virtualize Long Lists\n\nFor lists exceeding a few hundred items, render only visible rows.\n\n```js\n\u002F\u002F Concept: virtual scrolling\n\u002F\u002F Render only items in viewport + buffer\nconst visibleStart = Math.floor(scrollTop \u002F itemHeight);\nconst visibleEnd = visibleStart + Math.ceil(containerHeight \u002F itemHeight);\nconst buffer = 5;\nconst renderStart = Math.max(0, visibleStart - buffer);\nconst renderEnd = Math.min(totalItems, visibleEnd + buffer);\n```\n\n### 5.6 Avoid Layout Thrashing\n\nBatch DOM reads and writes. Never interleave them.\n\n```js\n\u002F\u002F Bad: read-write-read-write (forces synchronous layout)\nelements.forEach(el => {\n  const height = el.offsetHeight;     \u002F\u002F read\n  el.style.height = height + 10 + 'px'; \u002F\u002F write\n});\n\n\u002F\u002F Good: batch reads, then batch writes\nconst heights = elements.map(el => el.offsetHeight); \u002F\u002F all reads\nelements.forEach((el, i) => {\n  el.style.height = heights[i] + 10 + 'px'; \u002F\u002F all writes\n});\n```\n\n### 5.7 Use `will-change` Sparingly\n\nOnly apply `will-change` to elements that will animate, and remove it after animation completes.\n\n```css\n\u002F* Good: scoped and temporary *\u002F\n.card:hover {\n  will-change: transform;\n}\n.card.animating {\n  will-change: transform, opacity;\n}\n\n\u002F* Bad: blanket will-change *\u002F\n\u002F* * { will-change: transform; } *\u002F\n```\n\n### 5.8 Expose Waiting States Promptly\n\nAfter a user action, acknowledge the new state immediately. If work cannot finish within a brief moment, show progress, skeletons, optimistic UI, or `aria-busy` feedback instead of leaving the interface unchanged.\n\n---\n\n## 6. Animation and Motion [MEDIUM]\n\n### 6.1 Respect prefers-reduced-motion\n\nAlways provide a reduced-motion alternative (SC 2.3.3, Level AAA).\n\n```css\n\u002F* Define animations normally *\u002F\n.fade-in {\n  animation: fadeIn 300ms ease-out;\n}\n\n@keyframes fadeIn {\n  from { opacity: 0; transform: translateY(8px); }\n  to   { opacity: 1; transform: translateY(0); }\n}\n\n\u002F* Remove or reduce for users who prefer it *\u002F\n@media (prefers-reduced-motion: reduce) {\n  *, *::before, *::after {\n    animation-duration: 0.01ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.01ms !important;\n    scroll-behavior: auto !important;\n  }\n}\n```\n\n```js\n\u002F\u002F Check in JavaScript\nconst prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;\n```\n\n### 6.2 Compositor-Friendly Animations\n\nAnimate only `transform` and `opacity` for smooth 60fps animation. These run on the GPU compositor thread.\n\n```css\n\u002F* Good: compositor-only properties *\u002F\n.slide-in {\n  transition: transform 200ms ease-out, opacity 200ms ease-out;\n}\n\n\u002F* Bad: triggers layout\u002Fpaint *\u002F\n.slide-in-bad {\n  transition: left 200ms, width 200ms, height 200ms;\n}\n```\n\n### 6.3 No Flashing Content\n\nNever flash content more than 3 times per second (SC 2.3.1). This can trigger seizures.\n\n### 6.4 Transitions for State Changes\n\nUse transitions for hover, focus, open\u002Fclose, and other state changes to provide continuity.\n\n```css\n.dropdown {\n  opacity: 0;\n  transform: translateY(-4px);\n  transition: opacity 150ms ease-out, transform 150ms ease-out;\n  pointer-events: none;\n}\n.dropdown.open {\n  opacity: 1;\n  transform: translateY(0);\n  pointer-events: auto;\n}\n```\n\n### 6.5 Meaningful Motion Only\n\nAnimation should communicate state, guide attention, or show spatial relationships. Never animate for decoration alone.\n\n---\n\n## 7. Dark Mode and Theming [MEDIUM]\n\n### 7.1 System Preference Detection\n\n```css\n@media (prefers-color-scheme: dark) {\n  :root {\n    --bg: #0f0f17;\n    --text: #e4e4ef;\n    --surface: #1c1c2e;\n    --border: #2e2e44;\n  }\n}\n```\n\n### 7.2 CSS Custom Properties for Theming\n\nDefine all theme values as custom properties. Toggle themes by changing property values.\n\n```css\n:root {\n  color-scheme: light dark;\n\n  \u002F* Light theme (default) *\u002F\n  --color-bg: #ffffff;\n  --color-surface: #f5f5f7;\n  --color-text-primary: #1a1a2e;\n  --color-text-secondary: #555770;\n  --color-border: #d1d1e0;\n  --color-primary: #2563eb;\n  --color-primary-text: #ffffff;\n  --color-error: #dc2626;\n  --color-success: #16a34a;\n}\n\n@media (prefers-color-scheme: dark) {\n  :root {\n    --color-bg: #0f0f17;\n    --color-surface: #1c1c2e;\n    --color-text-primary: #e4e4ef;\n    --color-text-secondary: #a0a0b8;\n    --color-border: #2e2e44;\n    --color-primary: #60a5fa;\n    --color-primary-text: #0f0f17;\n    --color-error: #f87171;\n    --color-success: #4ade80;\n  }\n}\n```\n\n### 7.3 Color-Scheme Meta Tag\n\nTell the browser about supported color schemes for native UI elements (scrollbars, form controls).\n\n```html\n\u003Cmeta name=\"color-scheme\" content=\"light dark\">\n```\n\n### 7.4 Maintain Contrast in Both Modes\n\nVerify contrast ratios in both light and dark modes. Dark mode often suffers from low-contrast text on dark surfaces.\n\n### 7.5 Adaptive Images\n\nProvide appropriate images for light and dark contexts.\n\n```html\n\u003Cpicture>\n  \u003Csource srcset=\"logo-dark.svg\" media=\"(prefers-color-scheme: dark)\">\n  \u003Cimg src=\"logo-light.svg\" alt=\"Company logo\">\n\u003C\u002Fpicture>\n```\n\n```css\n\u002F* Or use CSS filter for simple cases *\u002F\n@media (prefers-color-scheme: dark) {\n  .decorative-img {\n    filter: brightness(0.9) contrast(1.1);\n  }\n}\n```\n\n### 7.6 Respect prefers-contrast\n\nHonor the user's contrast preference using `@media (prefers-contrast: more)` and `@media (prefers-contrast: forced)`. `prefers-contrast: more` responds to macOS\u002FiOS \"Increase Contrast\" in System Settings; `prefers-contrast: forced` responds to Windows High Contrast Mode — a distinct OS feature that overrides colors entirely.\n\n```css\n\u002F* Default theme *\u002F\n:root {\n  --color-text: #555770;\n  --color-border: #d1d1e0;\n  --color-bg: #ffffff;\n}\n\n\u002F* High contrast mode: stronger text and border colors *\u002F\n@media (prefers-contrast: more) {\n  :root {\n    --color-text: #1a1a2e;       \u002F* Darker text for higher ratio *\u002F\n    --color-border: #1a1a2e;     \u002F* Stronger borders *\u002F\n    --color-bg: #ffffff;\n  }\n\n  \u002F* Ensure interactive elements are clearly delineated *\u002F\n  button, input, select, textarea {\n    border: 2px solid currentColor;\n  }\n}\n\n\u002F* Forced colors (Windows High Contrast mode) *\u002F\n@media (prefers-contrast: forced) {\n  \u002F* Use system color keywords to respect OS color palette *\u002F\n  :root {\n    --color-text: ButtonText;\n    --color-bg: ButtonFace;\n    --color-border: ButtonBorder;\n  }\n}\n```\n\n---\n\n## 8. Navigation and State [MEDIUM]\n\n### 8.1 URL Reflects State\n\nEvery meaningful view should have a unique URL. Users should be able to bookmark, share, and reload any state.\n\n```js\n\u002F\u002F Update URL without full page reload\nfunction updateFilters(filters) {\n  const params = new URLSearchParams(filters);\n  history.pushState(null, '', `?${params}`);\n  renderResults(filters);\n}\n\n\u002F\u002F Restore state from URL on load\nconst params = new URLSearchParams(location.search);\nconst initialFilters = Object.fromEntries(params);\n```\n\n### 8.2 Browser Back\u002FForward\n\nHandle `popstate` to support browser navigation.\n\n```js\nwindow.addEventListener('popstate', () => {\n  const params = new URLSearchParams(location.search);\n  renderResults(Object.fromEntries(params));\n});\n```\n\n### 8.3 Active Navigation States\n\nIndicate the current page or section in navigation. Use `aria-current=\"page\"` for the active link.\n\n```html\n\u003Cnav aria-label=\"Main\">\n  \u003Ca href=\"\u002F\" aria-current=\"page\">Home\u003C\u002Fa>\n  \u003Ca href=\"\u002Fproducts\">Products\u003C\u002Fa>\n  \u003Ca href=\"\u002Fabout\">About\u003C\u002Fa>\n\u003C\u002Fnav>\n```\n\n```css\n[aria-current=\"page\"] {\n  font-weight: 700;\n  border-bottom: 2px solid var(--color-primary);\n}\n```\n\n### 8.4 Breadcrumbs\n\nProvide breadcrumbs for sites with deep hierarchies.\n\n```html\n\u003Cnav aria-label=\"Breadcrumb\">\n  \u003Col>\n    \u003Cli>\u003Ca href=\"\u002F\">Home\u003C\u002Fa>\u003C\u002Fli>\n    \u003Cli>\u003Ca href=\"\u002Fproducts\">Products\u003C\u002Fa>\u003C\u002Fli>\n    \u003Cli>\u003Ca href=\"\u002Fproducts\u002Fwidgets\" aria-current=\"page\">Widgets\u003C\u002Fa>\u003C\u002Fli>\n  \u003C\u002Fol>\n\u003C\u002Fnav>\n```\n\n### 8.5 Scroll Restoration\n\nManage scroll position for SPA navigation.\n\n```js\n\u002F\u002F Disable browser auto-restoration for manual control\nif ('scrollRestoration' in history) {\n  history.scrollRestoration = 'manual';\n}\n\n\u002F\u002F Save scroll position before navigation\nfunction saveScrollPosition() {\n  sessionStorage.setItem(`scroll-${location.pathname}`, window.scrollY);\n}\n\n\u002F\u002F Restore on back\u002Fforward\nwindow.addEventListener('popstate', () => {\n  const saved = sessionStorage.getItem(`scroll-${location.pathname}`);\n  if (saved) {\n    requestAnimationFrame(() => window.scrollTo(0, parseInt(saved)));\n  }\n});\n```\n\n---\n\n## 9. Touch and Interaction [MEDIUM]\n\n### 9.1 Touch-Action for Scroll Control\n\nUse `touch-action` to control gesture behavior on interactive elements.\n\n```css\n\u002F* Allow only vertical scrolling (disable horizontal pan and pinch-zoom) *\u002F\n.vertical-scroll {\n  touch-action: pan-y;\n}\n\n\u002F* Carousel: horizontal scroll only *\u002F\n.carousel {\n  touch-action: pan-x;\n}\n\n\u002F* Canvas\u002Fmap: disable all browser gestures *\u002F\n.canvas {\n  touch-action: none;\n}\n```\n\n### 9.2 Tap Highlight\n\nControl the tap highlight on mobile WebKit browsers.\n\n```css\nbutton, a {\n  -webkit-tap-highlight-color: transparent;\n}\n```\n\n### 9.3 Hover and Focus Parity\n\nEvery hover interaction must also work with keyboard focus.\n\n```css\n\u002F* Always pair :hover with :focus-visible *\u002F\n.card:hover,\n.card:focus-visible {\n  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);\n  transform: translateY(-2px);\n}\n```\n\n### 9.4 No Hover-Only Interactions\n\nNever hide essential functionality behind hover. Touch devices have no hover state.\n\n```css\n\u002F* Bad: content only accessible on hover *\u002F\n\u002F* .tooltip { display: none; }\n   .trigger:hover .tooltip { display: block; } *\u002F\n\n\u002F* Good: works with focus and click too *\u002F\n.trigger:hover .tooltip,\n.trigger:focus-within .tooltip,\n.tooltip:focus-within {\n  display: block;\n}\n```\n\n### 9.5 Scroll Snap for Carousels\n\nUse CSS scroll snap for card carousels and horizontal lists.\n\n```css\n.carousel {\n  display: flex;\n  overflow-x: auto;\n  scroll-snap-type: x mandatory;\n  gap: 1rem;\n  scroll-padding: 1rem;\n}\n\n.carousel > .slide {\n  scroll-snap-align: start;\n  flex: 0 0 min(85%, 400px);\n}\n```\n\n---\n\n## 10. Internationalization [MEDIUM]\n\n### 10.1 dir and lang Attributes\n\nSet `lang` on the `\u003Chtml>` element. Use `dir=\"auto\"` for user-generated content.\n\n```html\n\u003Chtml lang=\"en\" dir=\"ltr\">\n\n\u003C!-- User-generated content: let browser detect direction -->\n\u003Cp dir=\"auto\">User-submitted text here\u003C\u002Fp>\n\n\u003C!-- Explicit override for known RTL content -->\n\u003Cblockquote lang=\"ar\" dir=\"rtl\">...\u003C\u002Fblockquote>\n```\n\n### 10.2 Intl APIs for Formatting\n\nUse the `Intl` API for locale-aware formatting. Never hard-code date or number formats.\n\n```js\n\u002F\u002F Dates\nnew Intl.DateTimeFormat('en-US', { dateStyle: 'long' }).format(date);\n\u002F\u002F \"January 15, 2026\"\n\n\u002F\u002F Numbers\nnew Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234.56);\n\u002F\u002F \"1.234,56 EUR\"\n\n\u002F\u002F Relative time\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(-1, 'day');\n\u002F\u002F \"yesterday\"\n\n\u002F\u002F Lists\nnew Intl.ListFormat('en', { style: 'long', type: 'conjunction' }).format(['a', 'b', 'c']);\n\u002F\u002F \"a, b, and c\"\n\n\u002F\u002F Plurals\nconst pr = new Intl.PluralRules('en');\nconst suffixes = { one: 'st', two: 'nd', few: 'rd', other: 'th' };\nfunction ordinal(n) { return `${n}${suffixes[pr.select(n)]}`; }\n```\n\n### 10.3 Avoid Text in Images\n\nText in images cannot be translated, resized, or read by screen readers. Use HTML\u002FCSS text with background images when a styled text overlay is needed.\n\n### 10.4 CSS Logical Properties\n\nUse logical properties instead of physical ones to support both LTR and RTL layouts.\n\n```css\n\u002F* Physical (breaks in RTL) *\u002F\n\u002F* margin-left: 1rem; padding-right: 2rem; border-left: 1px solid; *\u002F\n\n\u002F* Logical (works in LTR and RTL) *\u002F\n.sidebar {\n  margin-inline-start: 1rem;\n  padding-inline-end: 2rem;\n  border-inline-start: 1px solid var(--color-border);\n}\n\n.stack > * + * {\n  margin-block-start: 1rem;\n}\n\n\u002F* Logical shorthands *\u002F\n.box {\n  margin-inline: auto;     \u002F* left + right *\u002F\n  padding-block: 2rem;     \u002F* top + bottom *\u002F\n  inset-inline-start: 0;   \u002F* left in LTR, right in RTL *\u002F\n  border-start-start-radius: 8px; \u002F* top-left in LTR, top-right in RTL *\u002F\n}\n```\n\n| Physical | Logical |\n|----------|---------|\n| `left` \u002F `right` | `inline-start` \u002F `inline-end` |\n| `top` \u002F `bottom` | `block-start` \u002F `block-end` |\n| `margin-left` | `margin-inline-start` |\n| `padding-right` | `padding-inline-end` |\n| `border-top-left-radius` | `border-start-start-radius` |\n| `width` | `inline-size` |\n| `height` | `block-size` |\n| `text-align: left` | `text-align: start` |\n\n### 10.5 RTL Layout Support\n\nTest layouts in RTL mode. Flexbox and Grid handle RTL automatically with logical properties.\n\n```css\n\u002F* This layout works in both LTR and RTL without changes *\u002F\n.layout {\n  display: flex;\n  gap: 1rem;\n}\n\n\u002F* Icons that indicate direction need flipping *\u002F\n[dir=\"rtl\"] .arrow-icon {\n  transform: scaleX(-1);\n}\n```\n\n---\n\n## 11. Progressive Web Apps [MEDIUM]\n\nPWAs allow web apps to be installed and run offline. When building an installable web app, the following rules ensure the experience is consistent and reliable.\n\n### 11.1 Provide a Complete Web App Manifest\n\nInclude a `manifest.json` linked from `\u003Chead>` with all required fields for installability. Missing fields silently prevent install prompts.\n\n```html\n\u003Clink rel=\"manifest\" href=\"\u002Fmanifest.json\">\n```\n\n```json\n{\n  \"name\": \"My App\",\n  \"short_name\": \"App\",\n  \"start_url\": \"\u002F\",\n  \"display\": \"standalone\",\n  \"icons\": [\n    { \"src\": \"\u002Ficons\u002Ficon-192.png\", \"sizes\": \"192x192\", \"type\": \"image\u002Fpng\" },\n    { \"src\": \"\u002Ficons\u002Ficon-512.png\", \"sizes\": \"512x512\", \"type\": \"image\u002Fpng\" }\n  ]\n}\n```\n\n**Incorrect:**\n```json\n{\n  \"name\": \"My App\"\n  \u002F\u002F Missing start_url, display, and icons — app is not installable\n}\n```\n\n### 11.2 Set theme_color and background_color\n\n`theme_color` tints the browser chrome and the OS task switcher. `background_color` fills the splash screen before the app loads. Both must match your brand colors.\n\n```json\n{\n  \"theme_color\": \"#1a73e8\",\n  \"background_color\": \"#ffffff\"\n}\n```\n\n### 11.3 Register a Service Worker for Offline Support\n\nA service worker is required for installability and offline capability. Cache critical assets on install; respond from cache when offline.\n\n```js\n\u002F\u002F In your main entry point\nif ('serviceWorker' in navigator) {\n  navigator.serviceWorker.register('\u002Fsw.js');\n}\n```\n\n```js\n\u002F\u002F sw.js — cache on install, serve from cache when offline\nconst CACHE = 'v1';\nconst PRECACHE = ['\u002F', '\u002Findex.html', '\u002Fapp.js', '\u002Fapp.css'];\n\nself.addEventListener('install', e =>\n  e.waitUntil(caches.open(CACHE).then(c => c.addAll(PRECACHE)))\n);\n\nself.addEventListener('fetch', e =>\n  e.respondWith(\n    caches.match(e.request).then(hit => hit ?? fetch(e.request))\n  )\n);\n```\n\n### 11.4 Meet Installability Criteria\n\nFor the browser install prompt to appear: the app must be served over HTTPS, have a registered service worker with a `fetch` handler, and include a manifest with `name`, `icons`, `start_url`, and `display: standalone` (or `fullscreen`\u002F`minimal-ui`).\n\n### 11.5 Use display Mode Appropriately\n\n| Value | Use When |\n|-------|----------|\n| `standalone` | App replaces browser UI; most common choice |\n| `fullscreen` | Games or media apps needing the entire screen |\n| `minimal-ui` | Retain minimal browser controls (back, reload) |\n| `browser` | No installation behavior; opens in browser tab |\n\n---\n\n## Evaluation Checklist\n\nUse this checklist when building or reviewing web interfaces.\n\n### Accessibility\n- [ ] All images have appropriate `alt` text\n- [ ] Color contrast meets 4.5:1 (text) and 3:1 (UI components)\n- [ ] All interactive elements are keyboard accessible\n- [ ] Focus indicators are visible (3:1 contrast, 2px minimum perimeter)\n- [ ] Skip navigation link is present\n- [ ] Form inputs have associated labels\n- [ ] Error messages are linked to their inputs\n- [ ] Dynamic content updates use ARIA live regions\n- [ ] No content flashes more than 3 times per second\n- [ ] Page has proper heading hierarchy (h1-h6, no skips)\n- [ ] Landmarks are used correctly (main, nav, header, footer)\n\n### Responsive\n- [ ] No horizontal scrolling at 320px width\n- [ ] Touch targets are at least 44x44px\n- [ ] Viewport meta tag is present (no user-scalable=no)\n- [ ] Layout works on mobile, tablet, and desktop\n- [ ] Text is readable without zooming on mobile\n\n### Forms\n- [ ] All inputs have visible labels\n- [ ] Autocomplete attributes are set for common fields\n- [ ] Correct input types trigger correct mobile keyboards\n- [ ] Error messages are clear and specific\n- [ ] Required fields are indicated\n- [ ] Submit button is not disabled\n\n### Performance\n- [ ] Below-fold images use `loading=\"lazy\"`\n- [ ] Images have explicit `width` and `height`\n- [ ] Critical fonts are preloaded\n- [ ] Third-party origins use `preconnect`\n- [ ] Large JS bundles are code-split\n\n### Motion and Theming\n- [ ] `prefers-reduced-motion` is respected\n- [ ] Animations use only `transform` and `opacity`\n- [ ] Dark mode maintains contrast ratios\n- [ ] `color-scheme` meta tag is present\n- [ ] Theme uses CSS custom properties\n- [ ] `prefers-contrast: more` increases text and border contrast\n- [ ] `prefers-contrast: forced` uses system color keywords\n\n### Internationalization\n- [ ] `lang` attribute on `\u003Chtml>`\n- [ ] CSS logical properties used (not physical)\n- [ ] Dates\u002Fnumbers formatted with Intl APIs\n- [ ] No text embedded in images\n- [ ] Layout tested in RTL mode\n\n### Progressive Web App\n- [ ] Web App Manifest linked from `\u003Chead>` with `name`, `icons`, `start_url`, and `display`\n- [ ] `theme_color` and `background_color` match brand palette\n- [ ] Service worker registered with a `fetch` handler for offline support\n- [ ] App served over HTTPS\n\n---\n\n## Common Anti-Patterns\n\n| Anti-Pattern | Fix |\n|--------------|-----|\n| `\u003Cdiv onclick=\"...\">` | Use `\u003Cbutton>` |\n| `outline: none` without replacement | Use `:focus-visible` with custom outline |\n| `placeholder` as label | Add a `\u003Clabel>` element |\n| `tabindex=\"5\"` | Use `tabindex=\"0\"` or natural order |\n| `user-scalable=no` | Remove it |\n| `font-size: 12px` | Use `font-size: 0.75rem` |\n| Animating `width`\u002F`height`\u002F`top`\u002F`left` | Animate `transform` and `opacity` |\n| Disabling submit button | Validate on submit, show errors |\n| Color alone for status | Add icon, text, or pattern |\n| `margin-left` \u002F `padding-right` | Use `margin-inline-start` \u002F `padding-inline-end` |\n| `\u003Cimg>` without dimensions | Add `width` and `height` attributes |\n| Hover-only disclosure | Add `:focus-within` and click handler |\n",{"name":5,"license":15,"metadata":57,"description":7},{"author":58,"version":59},"platform-design-skills","1.0.0","main","7a940b8e5af16c95e5c190a524421d32fc7445a9",".agent\u002Fskills\u002Fweb","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui","https:\u002F\u002Fneuroads.com.br","2026-08-12 00:42:44",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":79},[69,72,75],{"tool":70,"command":71},"npx","npx skills add headmktlucca-ui\u002Fneuroads-lp --skill web-design-guidelines",{"tool":73,"command":74},"bunx","bunx skills add headmktlucca-ui\u002Fneuroads-lp --skill web-design-guidelines",{"tool":76,"command":77},"pnpm","pnpm dlx skills add headmktlucca-ui\u002Fneuroads-lp --skill web-design-guidelines","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.agent\u002Fskills\u002Fweb\u002FSKILL.md",true,[81,87,91],{"path":82,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":85,"sourceHtmlUrl":86},"AGENTS.md","REFERENCE","参考文档",2179,"https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.agent\u002Fskills\u002Fweb\u002FAGENTS.md",{"path":88,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":89,"sourceHtmlUrl":90},"metadata.json",589,"https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.agent\u002Fskills\u002Fweb\u002Fmetadata.json",{"path":92,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":93,"sourceHtmlUrl":94},"rules\u002F_sections.md",15081,"https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.agent\u002Fskills\u002Fweb\u002Frules\u002F_sections.md",[96,119,144,168,186,194],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":108,"publishedAt":52},"01M6PTDCZTXTGSTX4RFK901YSZ","xunit-skill","Generates xUnit.net tests in C#. Covers Fact\u002FTheory, constructor injection, IClassFixture, and FluentAssertions. Use when user mentions \"xUnit\", \"[Fact]\", \"[Theory]\", \"Assert.Equal\", \"C# xUnit\". Triggers on: \"xUnit\", \"[Fact]\", \"[Theory]\", \"Assert.Equal C#\", \"xUnit.net\".","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fxunit-skill\u002FSKILL.md",[102,105],{"categoryNo":103,"categoryName":104,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":106,"categoryName":107,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[109,110,111,112,113,114,115,39,116,117,118],"xunit","xunit skill","testing","injection","user","use","tests","unit","unit-testing","C#",{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":127,"publishedAt":52},"01M6PTCB59ZTG5FTMWGPYEMMBP","xcuitest-skill","Generates XCUITest UI tests for iOS\u002FiPadOS apps in Swift. Apple's native testing framework for reliable, fast UI automation. Supports local simulators and TestMu AI cloud real devices. Use when user mentions \"XCUITest\", \"XCTest\", \"iOS UI test\", \"Swift test\", \"XCUIApplication\". Triggers on: \"XCUITest\", \"XCTest UI\", \"iOS UI test\", \"Swift UI test\", \"XCUIApplication\", \"TestMu\".","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fxcuitest-skill\u002FSKILL.md",[125,126],{"categoryNo":103,"categoryName":104,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":106,"categoryName":107,"taxonomyType":21,"taxonomyTypeDesc":22},[128,129,111,130,131,132,133,134,114,135,136,137,138,139,115,39,140,141,142,143],"xcuitest","xcuitest skill","automation","test","testing framework","ios","devices","mobile","mobile-testing","ui test","local","apple","apps","native","for","objective",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":152,"publishedAt":52},"01M6PTATMNTY9NF4J7KSR76YK6","world-builder","Create and manage generative game zones for Dorothy's Pokemon-style world. Use this skill when creating, updating, or designing game worlds via MCP tools.","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fworld-builder\u002FSKILL.md",[150,151],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":106,"categoryName":107,"taxonomyType":21,"taxonomyTypeDesc":22},[153,154,155,156,157,158,159,160,114,161,162,163,164,165,166,142,167],"builder","world","world builder","MCP","create","mcp tools","Tools","game","pokemon","manage","style","via","theme","zone","generative",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":176,"publishedAt":52},"01M6PT9Z92JTSQEHE1QR0NNW5F","webdriverio-skill","Generates WebdriverIO (WDIO) automation tests in JavaScript or TypeScript. Supports local and TestMu AI cloud. Use when user mentions \"WebdriverIO\", \"WDIO\", \"wdio.conf\", \"browser.url\", \"$\", \"$$\". Triggers on: \"WebdriverIO\", \"WDIO\", \"wdio\", \"browser.$\".","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwebdriverio-skill\u002FSKILL.md",[174,175],{"categoryNo":103,"categoryName":104,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":106,"categoryName":107,"taxonomyType":21,"taxonomyTypeDesc":22},[177,111,178,130,179,180,181,182,113,114,183,138,115,39,184,185],"webdriverio skill","typescript","javascript","browser","cloud","e2e","e2e-testing","URL","conf",{"skillNo":187,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":188,"categories":189,"keywords":193,"publishedAt":52},"01M6PT9NVK36ZWCQ69YXK3FR4K","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fweb\u002FSKILL.md",[190,191,192],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},[35,32,33,36,34,51,50,49,48,47,46,45,37,44,43,42,41,40,39,38],{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":202,"publishedAt":52},"01M6PT9A3JKRE3X34276F2FW5R","watchos-design-guidelines","Apple Human Interface Guidelines for Apple Watch. Use when building watchOS apps, complications, or workout features. Triggers on tasks involving Watch UI, Digital Crown, glanceable interfaces, or wrist-based interactions.","https:\u002F\u002Fgithub.com\u002Fheadmktlucca-ui\u002Fneuroads-lp\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwatchos\u002FSKILL.md",[200,201],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},[35,33,203,47,37,114,204,205,139,40,206,39,140,207,142,208,209],"watchos design guidelines","workout","human","watch","interface","platform-design","features"]