Interaction guide

Use native controls for their built-in behaviour, Alpine.js for local state, and HTMX when the server owns data.

Advanced integration: calendars, custom Select, Flow, maps, LayerDialog and chart legends

Choose the owner of each action

Owner	Use for
HTML + wdj.js	Forms, sliders, accordions, dialogs, popovers, menus, copy and reveal.
Alpine.js	Local tab panels, calendars, custom Select, counters, sidebar state and chart lifecycle.
Django + HTMX	Search, filtering, sort, pagination, validation and persistence.

A styled Button does not invent a business action. Set a URL, a form type, HTMX attributes or an Alpine handler. Presentation commands in this demo only show a notification.

Live playground

Try the buttons, local tabs, both slider handles and exclusive accordion. Reload replaces this fragment; the controls initialize again and local state resets.

Project configuration, rendered locally.

Preferences change without a server request.

Disabled panel.

First accordion section

Native details work with Enter and Space.

Second accordion section

A shared name allows only one expanded section.

Integration steps

Add wdj to Django, serve its static files and load HTMX, wdj.js, then Alpine.js.
Use explicit, unique IDs and labels. Use the block tag for HTML slots; use only for nested includes.
Return only fragment markup for HTMX. Set Vary: HX-Request and Cache-Control: no-store for dynamic fragments.
Keep Alpine state on a stable parent if it must survive swaps. Never conditionally remove dialog markup.
Validate POST data and permissions in Django. Include a CSRF token; button state is browser feedback.
Rebuild CSS when template classes change, then test the changed interaction and keyboard path.

Check an integration

Verify mouse and keyboard use, disabled/loading states, native validation, focus return, repeated HTMX swaps, form reset, both themes and a narrow viewport. Test the actual endpoint for persisted actions.

Component examples Installation Accessibility contract

Repository references: docs/GUIDE.md (complete workflow), docs/SKILL.md (component API), docs/INTERACTIONS.md (behaviour and verification), docs/DECISIONS.md (adaptations).