🎨 Palette: Standardize pagination icon-only buttons for accessibility

.jules/palette.md

@@ -1,16 +1,3 @@
-# Pallete Log
-
-## 2024-05-18 - Component icon-only `aria-label` conventions
-
-**Learning:** Found multiple icon-only components across the Ruby UI layout using `span.sr-only`, but icon-only buttons implemented using `Button` or `Link` components should simply accept the `aria_label:` prop. Ensure it exists.
-**Action:** When working with `<Button>` or `<Link>`, default to setting `aria_label` directly on the component rather than nesting an `sr-only` span.
-
-## 2026-03-05 - Swatch pickers need announced selection state
-
-**Learning:** Visual-only selection rings on theme swatches are not enough; button groups that behave like toggles need `aria-pressed` and a keyboard-visible focus treatment so the current choice is discoverable without sight or a mouse.
-**Action:** Treat palette, theme, and icon swatches as toggle buttons by default: set `type="button"`, expose pressed state, and keep a visible `focus-visible` ring on the interactive element itself.
-
-## 2024-03-05 - Add Descriptive Placeholders for Better Guidance
-
-**Learning:** Form fields lacking `placeholder` attributes (such as the Medication form inputs) can cause user friction since it’s not immediately clear what expected format or type of data to provide, especially on larger, empty textareas like `warnings` or `description`. Adding placeholder text does not break existing test locators compared to changing ARIA labels.
-**Action:** When working with forms or input fields via `RubyUI::Input` or `RubyUI::Textarea`, add a corresponding translated placeholder where appropriate to guide users effectively without cluttering the UI with additional helper text.
+## 2024-03-24 - Phlex Pagination Accessibility Refactoring
+**Learning:** When refactoring icon-only buttons for accessibility in Phlex components, be cautious of Phlex's block rendering semantics. Returning a string literal inside a Phlex block (e.g., `span { '‹' }`) does not output the text; you must explicitly use the `plain` helper (e.g., `span { plain '‹' }`). Also, when applying `aria-label` to disabled placeholder elements (like a generic non-interactive `span`), remember to include `role="button"` and `aria-disabled="true"` so screen readers correctly identify the element as a disabled interactive control instead of ignoring the `aria-label`.
+**Action:** Always use `plain` for text nodes in Phlex blocks and pair `aria-label` with an appropriate interactive role (`role="button"`) and state (`aria-disabled="true"`) when mocking disabled buttons with plain `span` elements.

app/components/admin/users/pagination.rb

@@ -92,15 +92,19 @@
               href: page_url(pagy_obj.previous),
               variant: :link,
               class: nav_button_class('rounded-l-md'),
-              data: { turbo_frame: 'admin-users-frame' }
+              data: { turbo_frame: 'admin-users-frame' },
+              "aria-label": t('admin.users.pagination.previous')
             ) do
-              span(class: 'sr-only') { t('admin.users.pagination.previous') }
-              plain '‹'
+              span(aria_hidden: 'true') { plain '‹' }
             end
           else
-            span(class: "#{nav_button_class('rounded-l-md')} opacity-50 cursor-not-allowed") do
-              span(class: 'sr-only') { t('admin.users.pagination.previous') }
-              plain '‹'
+            span(
+              class: "#{nav_button_class('rounded-l-md')} opacity-50 cursor-not-allowed",
+              role: 'button',
+              "aria-disabled": 'true',
+              "aria-label": t('admin.users.pagination.previous')
+            ) do
+              span(aria_hidden: 'true') { plain '‹' }
             end
           end
         end
@@ -111,15 +115,19 @@
               href: page_url(pagy_obj.next),
               variant: :link,
               class: nav_button_class('rounded-r-md'),
-              data: { turbo_frame: 'admin-users-frame' }
+              data: { turbo_frame: 'admin-users-frame' },
+              "aria-label": t('admin.users.pagination.next')
             ) do
-              span(class: 'sr-only') { t('admin.users.pagination.next') }
-              plain '›'
+              span(aria_hidden: 'true') { plain '›' }
             end
           else
-            span(class: "#{nav_button_class('rounded-r-md')} opacity-50 cursor-not-allowed") do
-              span(class: 'sr-only') { t('admin.users.pagination.next') }
-              plain '›'
+            span(
+              class: "#{nav_button_class('rounded-r-md')} opacity-50 cursor-not-allowed",
+              role: 'button',
+              "aria-disabled": 'true',
+              "aria-label": t('admin.users.pagination.next')
+            ) do
+              span(aria_hidden: 'true') { plain '›' }
             end
           end
         end