| 1 | # Web Development |
| 2 | |
| 3 | ## Scope |
| 4 | |
| 5 | - Use for HTML, CSS, HTMX, vanilla JS, and server-rendered templates. |
| 6 | - Do not use for React, Vue, Angular, TypeScript, Node.js backends, or app architecture. |
| 7 | - Follow existing template language, asset pipeline, framework, accessibility, and security conventions. |
| 8 | - Do not add a dependency, build step, or framework unless the project already uses it or the user approves. |
| 9 | |
| 10 | ## Reference Reads |
| 11 | |
| 12 | - Read `references/patterns.md` before layout, behavior, accessibility, or security changes; skip for copy-only edits. |
| 13 | |
| 14 | ## Defaults |
| 15 | |
| 16 | - Prefer semantic HTML and CSS; add HTMX or JS only when native browser behavior is insufficient. |
| 17 | - Use mobile-first, fluid CSS. Put repeated design tokens in custom properties; keep one-off values local. |
| 18 | - Preserve usable links and forms when practical. |
| 19 | - Treat accessibility, responsive behavior, and safe rendering as required behavior. |
| 20 | - Escape untrusted output; avoid `innerHTML` unless project sanitizer marks content trusted. |
| 21 | |
| 22 | ## Comments |
| 23 | |
| 24 | - Use HTML comments only for template boundaries, generated blocks, or security assumptions that are not obvious from markup. |
| 25 | - Use CSS comments for non-obvious hacks, browser constraints, or integration boundaries. |
| 26 | - Use JS comments only for non-obvious constraints, invariants, side effects, tradeoffs, or browser quirks. |
| 27 | - Keep comments short. Move longer rationale to docs, issue links, or design notes. |
| 28 | - Do not comment obvious markup, selectors, declarations, or event handlers. |
| 29 | - Keep UI tests readable without comments; add one only for unobvious fixtures, browser setup, timing, or regression context. |
| 30 | |
| 31 | ## Verification |
| 32 | |
| 33 | - Run project-configured format, lint, validation, tests, and browser checks for the changed files. |
| 34 | - For UI changes, check mobile and desktop widths plus keyboard navigation. |
| 35 | - For changed interactive behavior, run a browser test or state why it was skipped. |
| 36 | - If a check is unavailable, state the gap and run the closest configured gate. |
| 37 | - For rendered-browser verification (screenshots, live interaction, cross-viewport checks), use `browser-automation`. |
| 38 | |
| 39 | ## Failure Handling |
| 40 | |
| 41 | - HTML or accessibility validation fails: fix the markup; do not suppress configured checks. |
| 42 | - HTMX request does not fire: check trigger, target, swap, response status, and CSRF/auth headers before adding JS fallback. |
| 43 | - Project conventions or checks are unclear: inspect config first; if still unclear, state the assumption and smallest safe gate. |
| 44 | - Broad, risky, or destructive change: state the risk and ask before acting. Do not run destructive commands. |
| 45 | |
| 46 | ## Final Response |
| 47 | |
| 48 | - Files changed: |
| 49 | - Checks: |
| 50 | - Skipped checks: |
| 51 | - Risks/follow-ups: |