ecelayes/roots-skills

Overview

This skill is the definitive guide for building Hypermedia-Driven Applications (HDA) with HTMX, prioritizing secure server-driven UI and reliable UX patterns. It codifies practical rules for responses, security, error handling, and progressive enhancement so teams can build consistent, maintainable interactions. Use it to standardize HTMX patterns across projects and reduce common pitfalls like CSRF and XSS.

How this skill works

The guide enforces server-rendered HTML fragments (partials) for all HTMX interactions instead of JSON, and prescribes how responses should drive DOM updates via hx-swap. It specifies security controls (CSRF header or hidden form token and strict server-side escaping), defines HTTP status semantics for UX flows, and documents client indicators and active-state patterns to make interactions predictable. Developers implement small server routes that return only the partial needed for the targeted DOM swap.

When to use it

• Building interactive UIs where server-side rendering is preferred over client-side state
• Implementing form submissions, inline editing, or incremental updates without a SPA
• Standardizing patterns across teams to ensure secure HTMX usage
• Adding progressive enhancement to existing server-rendered pages
• Handling validation and global alerts from the server in a consistent way

Best practices

• Always return HTML partials for HTMX endpoints; avoid JSON responses for DOM updates
• Protect non-idempotent HTMX requests with CSRF tokens via global hx-headers or hidden form fields
• Escape all user-provided content on the server to prevent XSS when injecting HTML
• Design one route per partial (the Partial Rule) so swaps are minimal and predictable
• Use HTTP semantics: GET read-only, POST/PUT/PATCH/DELETE for state changes
• Add hx-indicator to show request progress and use hx-vals or server-rendered classes for active states

Example use cases

• Inline edit workflow: click an Edit button that hx-get's a form partial, submit via hx-post and swap the row with updated HTML
• Create/update forms that return 422 with the form containing validation errors to be swapped into the current view
• Global alerts: return 200 with HX-Retarget header to update the top-level alert area from any partial
• Loading lists or pagination fragments via hx-get to replace only the list container without full page reload
• Secure action buttons: include hx-headers with X-CSRF-Token or embed hidden token inputs in forms