Rails Application UI Blocks
Use this skill to choose, adapt, and integrate premium UI blocks from templates/application-ui into Rails views.
Workflow
- Determine mode:
- new-page for brand new features/pages
- refactor-page for existing views/partials
- Identify constraints first:
- Required interactions (Turbo Frames/Streams, Stimulus targets/actions, form semantics)
- Accessibility constraints (labels, keyboard flow, ARIA)
- Existing component boundaries (partials, helpers, shared layouts)
- Pick candidate blocks from catalog:
- Read
references/selection-playbook.md - Query
references/template-catalog.json
- Integrate minimally:
- Keep existing routes/controllers/domain logic unchanged
- Replace markup in thin steps (shell first, then sections, then micro-components)
- Verify:
- Ensure no loss of behavior, accessibility, or test coverage
- Keep existing design tokens and class conventions where required by project standards
Selection Order
For new-page:
- Start with
ui.page-examples.*to anchor page structure. - Choose shell from
ui.application-shells.*. - Add page/section headings from
ui.headings.*. - Add core body blocks (
ui.forms.*,ui.lists.*,ui.data-display.*,ui.feedback.*). - Finish with navigation and overlay details (
ui.navigation.*,ui.overlays.*).
For refactor-page:
- Preserve current information architecture and interaction contracts.
- Map each existing UI region to one candidate catalog block.
- Replace one region at a time and run relevant tests.
- Extract repeated markup into partials only after reuse is proven.
Guardrails
- Do not change controllers/models/policies unless explicitly requested.
- Do not remove
data-controller,data-action,data-turbo-*,aria-*, or form field names without replacement. - Prefer adapting blocks to project styles over introducing conflicting visual systems.
- Avoid block insertion that duplicates existing design-system components when native components already solve the same need.
Output Expectations
When completing a task with this skill, include:
- Selected catalog IDs (for traceability)
- Source template paths used
- Any behavior/accessibility deltas introduced
- What was intentionally not replaced and why
Resources
references/selection-playbook.md
- Decision rules for what template families to check first, and when not to use them.
references/template-catalog.json
- Canonical block IDs with aliases and source paths.
scripts/build_template_catalog.py
- Regenerates the catalog after template updates.
Maintenance
Regenerate the catalog when files under templates/application-ui change:
python3 .agents/skills/rails-application-ui-blocks/scripts/build_template_catalog.py \
--root .