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 .