From f70a6eab2bdb5aafed293baa5a9c6215d5f61ec7 Mon Sep 17 00:00:00 2001
From: Marcella Maki <marcellamaki@gmail.com>
Date: Fri, 4 Sep 2026 15:00:55 -0400
Subject: [PATCH 1/2] Add a fieldset/visually hidden grouping to filter pills,
 and change them to be a semantic checkbox (that looks like a button) for a11y

---
 .../LibraryPage/HorizontalFilterPills.vue     |  87 +++++++++-----
 .../__tests__/HorizontalFilterPills.spec.js   | 111 +++++++++++++++---
 .../strings/searchAndFilterStrings.js         |   5 +
 3 files changed, 159 insertions(+), 44 deletions(-)

diff --git a/kolibri/plugins/learn/frontend/views/LibraryPage/HorizontalFilterPills.vue b/kolibri/plugins/learn/frontend/views/LibraryPage/HorizontalFilterPills.vue
index 44f528e4d16..83a49fc93e5 100644
--- a/kolibri/plugins/learn/frontend/views/LibraryPage/HorizontalFilterPills.vue
+++ b/kolibri/plugins/learn/frontend/views/LibraryPage/HorizontalFilterPills.vue
@@ -1,37 +1,37 @@
 <template>
 
   <div class="filter-pills">
-    <KButton
-      v-for="(entry, index) in entries"
-      :key="`${entry.type}-${index}`"
-      :data-testid="`${entry.type}-pill`"
-      :text="entry.label"
-      appearance="flat-button"
-      class="pill"
-      :appearanceOverrides="pillOverridesFor(entry)"
-      :disabled="loading"
-      @click="toggleFilter({ key: entry.termKey, value: entry.value })"
-    >
-      <template
-        v-if="entry.icon"
-        #icon
+    <fieldset class="filters-fieldset">
+      <legend class="visuallyhidden">{{ appliedFiltersGroupLabel$() }}</legend>
+      <label
+        v-for="entry in entries"
+        :key="`${entry.termKey}:${entry.value}`"
+        :data-testid="`${entry.type}-pill`"
+        class="pill"
+        :class="$computedClass(pillPseudoStylesFor())"
+        :style="pillColorStyleFor(entry)"
       >
+        <input
+          type="checkbox"
+          class="visuallyhidden"
+          :checked="isFilterActive(entry.termKey, entry.value)"
+          :aria-disabled="loading"
+          @click.prevent="handleToggle(entry)"
+        >
         <KIcon
+          v-if="entry.icon"
           :icon="entry.icon"
           :color="entry.type === 'activity' ? null : $themeTokens.primary"
           class="pill-icon"
         />
-      </template>
-      <template
-        v-if="iconAfterFor(entry)"
-        #iconAfter
-      >
+        <span class="link-text">{{ entry.label }}</span>
         <KIcon
+          v-if="iconAfterFor(entry)"
           :icon="iconAfterFor(entry)"
           class="pill-icon-after"
         />
-      </template>
-    </KButton>
+      </label>
+    </fieldset>
     <span
       v-if="hasAvailableLabels"
       class="all-filters-group"
@@ -45,7 +45,7 @@
         :text="allFilters$()"
         appearance="flat-button"
         class="pill"
-        :appearanceOverrides="pillOverridesFor({})"
+        :appearanceOverrides="pillColorStyleFor({})"
         :disabled="loading"
         @click="$emit('openFilters')"
       >
@@ -80,7 +80,7 @@
 
 <script>
 
-  import { computed } from 'vue';
+  import { computed, getCurrentInstance } from 'vue';
   import { get } from '@vueuse/core';
   import { themeTokens, themeBrand, themePalette } from 'kolibri-design-system/lib/styles/theme';
   import { CategoriesLookup } from 'kolibri/constants';
@@ -93,6 +93,7 @@
   export default {
     name: 'HorizontalFilterPills',
     setup() {
+      const instance = getCurrentInstance().proxy;
       const {
         availableLearningActivities,
         availableLibraryCategories,
@@ -197,8 +198,16 @@
         return isFilterActive(entry.termKey, entry.value) ? 'close' : null;
       }
 
-      // Only theme-dependent styling lives here; layout is in the style block
-      function pillOverridesFor(entry) {
+      // Guarding here, rather than disabling the checkbox while loading, keeps
+      // it focusable so a keyboard toggle doesn't lose focus mid-search.
+      function handleToggle(entry) {
+        if (get(searchLoading)) {
+          return;
+        }
+        toggleFilter({ key: entry.termKey, value: entry.value });
+      }
+
+      function pillColorStyleFor(entry) {
         if (isFilterActive(entry.termKey, entry.value)) {
           return {
             backgroundColor: themeBrand().primary.v_100,
@@ -216,19 +225,34 @@
         };
       }
 
-      const { allFilters$ } = searchAndFilterStrings;
+      // for a11y, the pill is a semantic checkbox and label
+      // but visually styled to match KButton for sighted users
+      function pillPseudoStylesFor() {
+        return {
+          ':hover': get(searchLoading) ? {} : { backgroundColor: 'rgba(0,0,0,.1)' },
+          ':focus-within': { ...instance.$coreOutline, outlineOffset: 0 },
+          ...(get(searchLoading)
+            ? { pointerEvents: 'none', cursor: 'default', opacity: 0.5 }
+            : { cursor: 'pointer' }),
+        };
+      }
+
+      const { allFilters$, appliedFiltersGroupLabel$ } = searchAndFilterStrings;
       const { clearAllAction$ } = coreStrings;
 
       return {
         entries,
         hasActiveFilters,
         hasAvailableLabels,
+        isFilterActive,
         iconAfterFor,
-        pillOverridesFor,
-        toggleFilter,
+        pillColorStyleFor,
+        pillPseudoStylesFor,
+        handleToggle,
         clearSearch,
         loading: searchLoading,
         allFilters$,
+        appliedFiltersGroupLabel$,
         clearAllAction$,
       };
     },
@@ -246,6 +270,13 @@
     align-items: center;
   }
 
+  // Strip the fieldset's default border/padding/min-width and let its pills
+  // lay out as direct flex children of .filter-pills, same as before grouping.
+  .filters-fieldset {
+    all: unset;
+    display: contents;
+  }
+
   .filter-pills .pill {
     display: inline-flex;
     align-items: center;
diff --git a/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/HorizontalFilterPills.spec.js b/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/HorizontalFilterPills.spec.js
index b046fad6d7c..7946719b3e2 100644
--- a/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/HorizontalFilterPills.spec.js
+++ b/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/HorizontalFilterPills.spec.js
@@ -1,5 +1,5 @@
 import { ref } from 'vue';
-import { render, screen, fireEvent } from '@testing-library/vue';
+import { render, screen, fireEvent, within } from '@testing-library/vue';
 import { Categories } from 'kolibri/constants';
 import { coreStrings } from 'kolibri/uiText/commonCoreStrings';
 import { searchAndFilterStrings } from 'kolibri-common/strings/searchAndFilterStrings';
@@ -15,7 +15,7 @@ const {
   mathematics$,
   clearAllAction$,
 } = coreStrings;
-const { allFilters$ } = searchAndFilterStrings;
+const { allFilters$, appliedFiltersGroupLabel$ } = searchAndFilterStrings;
 
 const KEYWORD_FILTER = 'hummingbirds';
 
@@ -67,35 +67,113 @@ function renderComponent(provides = {}, props = {}) {
 }
 
 describe('HorizontalFilterPills', () => {
+  describe('grouping', () => {
+    it('groups the filter checkboxes under a named group', () => {
+      renderComponent();
+      const group = screen.getByRole('group', { name: appliedFiltersGroupLabel$() });
+      expect(within(group).getByRole('checkbox', { name: create$() })).toBeInTheDocument();
+      expect(within(group).getByRole('checkbox', { name: school$() })).toBeInTheDocument();
+    });
+
+    it('does not include the all-filters or clear-all actions in the group', () => {
+      renderComponent({
+        appliedFilters: () => [{ key: 'learning_activities', value: 'UXADWcXZ' }],
+      });
+      const group = screen.getByRole('group', { name: appliedFiltersGroupLabel$() });
+      expect(within(group).queryByRole('button', { name: allFilters$() })).not.toBeInTheDocument();
+      expect(
+        within(group).queryByRole('button', { name: clearAllAction$() }),
+      ).not.toBeInTheDocument();
+    });
+  });
+
   describe('activity pills', () => {
-    it('renders a pill for each available activity', () => {
+    it('renders a checkbox for each available activity', () => {
       renderComponent();
       expect(screen.getAllByTestId('activity-pill')).toHaveLength(3);
-      expect(screen.getByRole('button', { name: create$() })).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: explore$() })).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: listen$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: create$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: explore$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: listen$() })).toBeInTheDocument();
     });
 
     it('calls toggleFilter when an activity pill is clicked', async () => {
       const { toggleFilter } = renderComponent();
-      await fireEvent.click(screen.getByRole('button', { name: create$() }));
+      await fireEvent.click(screen.getByRole('checkbox', { name: create$() }));
       expect(toggleFilter).toHaveBeenCalledWith(
         expect.objectContaining({ key: 'learning_activities', value: 'UXADWcXZ' }),
       );
     });
+
+    it('reflects the applied state as checked', () => {
+      renderComponent({
+        appliedFilters: () => [{ key: 'learning_activities', value: 'UXADWcXZ' }],
+        isFilterActive: (key, value) => key === 'learning_activities' && value === 'UXADWcXZ',
+      });
+      expect(screen.getByRole('checkbox', { name: create$() })).toBeChecked();
+      expect(screen.getByRole('checkbox', { name: explore$() })).not.toBeChecked();
+    });
+
+    it('keeps checked in sync after unapplying the first of two applied activities', async () => {
+      const applied = ref([]);
+      renderComponent({
+        appliedFilters: () => applied.value,
+        isFilterActive: (key, value) => applied.value.some(f => f.key === key && f.value === value),
+        toggleFilter: ({ key, value }) => {
+          const idx = applied.value.findIndex(f => f.key === key && f.value === value);
+          applied.value =
+            idx === -1
+              ? [...applied.value, { key, value }]
+              : applied.value.filter((_, i) => i !== idx);
+        },
+      });
+
+      await fireEvent.click(screen.getByRole('checkbox', { name: explore$() }));
+      await fireEvent.click(screen.getByRole('checkbox', { name: listen$() }));
+      await fireEvent.click(screen.getByRole('checkbox', { name: explore$() }));
+
+      expect(screen.getByRole('checkbox', { name: listen$() })).toBeChecked();
+      expect(screen.getByRole('checkbox', { name: explore$() })).not.toBeChecked();
+    });
+  });
+
+  describe('while loading', () => {
+    it('keeps the checkbox enabled so a keyboard toggle does not lose focus', () => {
+      renderComponent({ searchLoading: ref(true) });
+      expect(screen.getByRole('checkbox', { name: create$() })).toBeEnabled();
+    });
+
+    it('ignores a toggle started while a previous one is still loading', async () => {
+      const { toggleFilter } = renderComponent({ searchLoading: ref(true) });
+      await fireEvent.click(screen.getByRole('checkbox', { name: create$() }));
+      expect(toggleFilter).not.toHaveBeenCalled();
+    });
+
+    it('does not let an ignored click flip the checkbox out of sync with the applied filters', async () => {
+      renderComponent({ searchLoading: ref(true) });
+      await fireEvent.click(screen.getByRole('checkbox', { name: create$() }));
+      expect(screen.getByRole('checkbox', { name: create$() })).not.toBeChecked();
+    });
+
+    it('marks the checkbox aria-disabled for assistive tech', () => {
+      renderComponent({ searchLoading: ref(true) });
+      expect(screen.getByRole('checkbox', { name: create$() })).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
+    });
   });
 
   describe('category pills', () => {
-    it('renders a pill for each available category', () => {
+    it('renders a checkbox for each available category', () => {
       renderComponent();
       expect(screen.getAllByTestId('category-pill')).toHaveLength(2);
-      expect(screen.getByRole('button', { name: school$() })).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: dailyLife$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: school$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: dailyLife$() })).toBeInTheDocument();
     });
 
     it('calls toggleFilter when a category pill is clicked', async () => {
       const { toggleFilter } = renderComponent();
-      await fireEvent.click(screen.getByRole('button', { name: school$() }));
+      await fireEvent.click(screen.getByRole('checkbox', { name: school$() }));
       expect(toggleFilter).toHaveBeenCalledWith(
         expect.objectContaining({ key: 'categories', value: Categories.SCHOOL }),
       );
@@ -112,6 +190,7 @@ describe('HorizontalFilterPills', () => {
       });
       const pill = screen.getByTestId('category-pill');
       expect(pill).toHaveTextContent(mathematics$());
+      expect(screen.getByRole('checkbox', { name: mathematics$() })).toBeChecked();
       expect(screen.queryByText(SUBCATEGORY_VALUE)).not.toBeInTheDocument();
     });
   });
@@ -139,7 +218,7 @@ describe('HorizontalFilterPills', () => {
           key === 'learning_activities' ? value === '#j8L0eq3' : false,
       });
       expect(screen.getAllByTestId('activity-pill')).toHaveLength(1);
-      expect(screen.getByRole('button', { name: explore$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: explore$() })).toBeInTheDocument();
       expect(screen.queryAllByTestId('category-pill')).toHaveLength(0);
     });
 
@@ -150,7 +229,7 @@ describe('HorizontalFilterPills', () => {
         isFilterActive: (key, value) => key === 'learning_activities' && value === 'UXADWcXZ',
       });
       expect(screen.getAllByTestId('activity-pill')).toHaveLength(1);
-      expect(screen.getByRole('button', { name: create$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: create$() })).toBeInTheDocument();
     });
   });
 
@@ -161,7 +240,7 @@ describe('HorizontalFilterPills', () => {
         isFilterActive: (key, value) => key === 'keywords' && value === KEYWORD_FILTER,
       });
       expect(screen.getByTestId('keyword-pill')).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: KEYWORD_FILTER })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: KEYWORD_FILTER })).toBeChecked();
     });
 
     it('renders an active filter from a non-catalog dimension', () => {
@@ -170,7 +249,7 @@ describe('HorizontalFilterPills', () => {
         isFilterActive: (key, value) => key === 'grade_levels' && value === 'basic_skills',
       });
       expect(screen.getByTestId('grade_levels-pill')).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: basicSkills$() })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: basicSkills$() })).toBeChecked();
     });
 
     it('labels an applied language with its name, not the raw code', () => {
@@ -183,7 +262,7 @@ describe('HorizontalFilterPills', () => {
         isFilterActive: (key, value) => key === 'languages' && value === language.id,
       });
       expect(screen.getByTestId('language-pill')).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: language.lang_name })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: language.lang_name })).toBeChecked();
       expect(screen.queryByText(language.id)).not.toBeInTheDocument();
     });
   });
diff --git a/packages/kolibri-common/strings/searchAndFilterStrings.js b/packages/kolibri-common/strings/searchAndFilterStrings.js
index c90904422c5..f51ac748b80 100644
--- a/packages/kolibri-common/strings/searchAndFilterStrings.js
+++ b/packages/kolibri-common/strings/searchAndFilterStrings.js
@@ -56,6 +56,11 @@ export const searchAndFilterStrings = createTranslator('SearchAndFilterStrings',
     message: 'All filters',
     context: 'Label for the button and side panel showing all available search filters',
   },
+  appliedFiltersGroupLabel: {
+    message: 'Filters',
+    context:
+      "Hidden label for the group of checkboxes shown as pills (e.g. 'School', 'Video') that a learner can check or uncheck to filter search results. Read by screen readers only, to identify the group; not shown visually because the pills are self-explanatory to sighted users.",
+  },
   searchHistory: {
     message: 'History',
     context: 'Header for recently viewed resources in the search autocomplete dropdown',

From 2ef07d6e55864ca05de92da8c8222e1ce2654e41 Mon Sep 17 00:00:00 2001
From: Marcella Maki <marcellamaki@gmail.com>
Date: Fri, 4 Sep 2026 15:31:09 -0400
Subject: [PATCH 2/2] creates an optional override for skip to main content
 logic, which allows the  itself to be the focus, but continues to default to
 the page H1. Adds this for the Learn > Library page since  is ahead of the h1
 in the DOM

---
 .../views/LibraryPage/LibrarySearchBar.vue    |  1 +
 .../__tests__/LibrarySearchBar.spec.js        |  5 ++++
 .../frontend/views/LibraryPage/index.vue      | 10 ++++++-
 .../views/__tests__/LibraryPage.spec.js       | 15 ++++++++++
 .../kolibri/components/SkipNavigationLink.vue | 30 ++++++++++++-------
 5 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/kolibri/plugins/learn/frontend/views/LibraryPage/LibrarySearchBar.vue b/kolibri/plugins/learn/frontend/views/LibraryPage/LibrarySearchBar.vue
index 1fef115744c..667ddd9001a 100644
--- a/kolibri/plugins/learn/frontend/views/LibraryPage/LibrarySearchBar.vue
+++ b/kolibri/plugins/learn/frontend/views/LibraryPage/LibrarySearchBar.vue
@@ -2,6 +2,7 @@
 
   <form
     class="library-search-bar"
+    role="search"
     @submit.prevent="handleSubmit"
   >
     <div
diff --git a/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/LibrarySearchBar.spec.js b/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/LibrarySearchBar.spec.js
index 92ae9fa9924..2d208bb92ab 100644
--- a/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/LibrarySearchBar.spec.js
+++ b/kolibri/plugins/learn/frontend/views/LibraryPage/__tests__/LibrarySearchBar.spec.js
@@ -88,6 +88,11 @@ describe('LibrarySearchBar', () => {
   });
 
   describe('rendering', () => {
+    it('exposes a search landmark so it can be reached independent of the skip link', () => {
+      renderComponent();
+      expect(screen.getByRole('search')).toBeInTheDocument();
+    });
+
     it('renders a search input', () => {
       renderComponent();
       expect(screen.getByRole('combobox', { name: searchLabel$() })).toBeInTheDocument();
diff --git a/kolibri/plugins/learn/frontend/views/LibraryPage/index.vue b/kolibri/plugins/learn/frontend/views/LibraryPage/index.vue
index a6d11e32137..ad86e7419bf 100644
--- a/kolibri/plugins/learn/frontend/views/LibraryPage/index.vue
+++ b/kolibri/plugins/learn/frontend/views/LibraryPage/index.vue
@@ -21,7 +21,15 @@
       :deviceId="deviceId"
       :route="back"
     >
-      <main class="main-grid">
+      <main
+        class="main-grid"
+        data-skip-nav-target
+        :aria-label="displayingSearchResults ? null : channelsLabel"
+      >
+        <!--
+          Overrides SkipNavigationLink's default of focusing the first h1: the
+          search bar precedes the h1 here, so focusing the h1 would skip over it.
+        -->
         <!-- Search header: search bar + filter pills grouped together -->
         <div
           class="search-header"
diff --git a/kolibri/plugins/learn/frontend/views/__tests__/LibraryPage.spec.js b/kolibri/plugins/learn/frontend/views/__tests__/LibraryPage.spec.js
index ea9f081f394..5a796e289cd 100644
--- a/kolibri/plugins/learn/frontend/views/__tests__/LibraryPage.spec.js
+++ b/kolibri/plugins/learn/frontend/views/__tests__/LibraryPage.spec.js
@@ -6,6 +6,7 @@ import KCircularLoader from 'kolibri-design-system/lib/loaders/KCircularLoader';
 import useKResponsiveWindow from 'kolibri-design-system/lib/composables/useKResponsiveWindow';
 import ContentNodeResource from 'kolibri-common/apiResources/ContentNodeResource';
 import useUser from 'kolibri/composables/useUser';
+import { coreString } from 'kolibri/uiText/commonCoreStrings';
 /* eslint-disable import-x/named */
 import useBaseSearch, { useBaseSearchMock } from 'kolibri-common/composables/useBaseSearch';
 import useChannels, { useChannelsMock } from 'kolibri-common/composables/useChannels';
@@ -94,6 +95,20 @@ describe('LibraryPage', () => {
       Promise.resolve([{ id: 'test', title: 'test', channel_id: CHANNEL_ID }]),
     );
   });
+  describe('skip navigation', () => {
+    it('marks the main landmark as the skip-link target, since the search bar precedes the h1', async () => {
+      const wrapper = await makeWrapper();
+      expect(wrapper.find('main.main-grid').attributes('data-skip-nav-target')).toBe('');
+    });
+
+    it("names the main landmark to match the page's own heading", async () => {
+      const wrapper = await makeWrapper();
+      expect(wrapper.find('main.main-grid').attributes('aria-label')).toBe(
+        coreString('yourLibrary'),
+      );
+    });
+  });
+
   describe('search bar', () => {
     it('is visible when channels are available', async () => {
       const wrapper = await makeWrapper();
diff --git a/packages/kolibri/components/SkipNavigationLink.vue b/packages/kolibri/components/SkipNavigationLink.vue
index 216debd6d27..43c933128e2 100644
--- a/packages/kolibri/components/SkipNavigationLink.vue
+++ b/packages/kolibri/components/SkipNavigationLink.vue
@@ -26,21 +26,29 @@
     },
     methods: {
       handleClickSkipLink() {
-        // Every page where this is supposed to work needs to have a top-level
-        // element with 'role' and 'id' attribute equal to 'main' and 'tabindex= -1'.
-        // If it doesn't have one, clicking this link is a noop, but will re-focus itself
-        // as a convenience (in case main div is still loading).
+        // Every page where this is supposed to work needs a top-level element
+        // with id="main" (typically an unlabelled wrapper div; a nested <main>
+        // or [role="main"] descendant, if present, is one of the focus targets
+        // below). If there's no #main at all, clicking this link is a noop, but
+        // will re-focus itself as a convenience (in case main div is still loading).
         const mainEl = document.getElementById('main');
         if (mainEl) {
-          // If it exists, actually target and focus on the main header
-          const header = mainEl.querySelector('h1');
+          // Default a11y behavior is "focus the first h1"
+          // Override this by marking the element where the focus should land instead (e.g.
+          // the `main` landmark itself, especially if DOM content preceeds the first H1).
+          const target =
+            mainEl.querySelector('[data-skip-nav-target]') ||
+            mainEl.querySelector('h1') ||
+            mainEl.querySelector('main, [role="main"]') ||
+            mainEl;
+          // Need to set the tabindex attribute on the fly to get tab behavior
+          target.setAttribute('tabindex', -1);
+          // The fixed app bar would otherwise cover the target when it scrolls into view
+          const header = document.querySelector('.scrolling-header');
           if (header) {
-            // HACK: Need to set its tabindex attribute on the fly to get tab behavior
-            header.setAttribute('tabindex', -1);
-            header.focus();
-          } else {
-            mainEl.focus();
+            target.style.scrollMarginTop = `${header.offsetHeight}px`;
           }
+          target.focus();
         } else {
           // NOTE: the button retains focus, but loses :focus styling after hitting "Enter"
           // TODO: look into theme input modality to see if we can get consistent