Rails Application UI Blocks

templates/application-ui

Workflow

1. Determine mode:

• new-page for brand new features/pages
• refactor-page for existing views/partials

1. 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)

1. Pick candidate blocks from catalog:

• Read

  references/selection-playbook.md

• Query

  references/template-catalog.json

1. Integrate minimally:

• Keep existing routes/controllers/domain logic unchanged
• Replace markup in thin steps (shell first, then sections, then micro-components)

1. Verify:

• Ensure no loss of behavior, accessibility, or test coverage
• Keep existing design tokens and class conventions where required by project standards

Selection Order

new-page

1. Start with

   ui.page-examples.*

   to anchor page structure.
2. Choose shell from

   ui.application-shells.*

   .
3. Add page/section headings from

   ui.headings.*

   .
4. Add core body blocks (

   ui.forms.*

   ,

   ui.lists.*

   ,

   ui.data-display.*

   ,

   ui.feedback.*

   ).
5. Finish with navigation and overlay details (

   ui.navigation.*

   ,

   ui.overlays.*

   ).

refactor-page

1. Preserve current information architecture and interaction contracts.
2. Map each existing UI region to one candidate catalog block.
3. Replace one region at a time and run relevant tests.
4. 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

• 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

templates/application-ui

python3 .agents/skills/rails-application-ui-blocks/scripts/build_template_catalog.py \
  --root .