docs: design compact programme switch

docs/superpowers/specs/2026-08-16-compact-programme-switch-and-sidebar-filtering-design.md

@@ -0,0 +1,93 @@
+# Compact Programme Switch and Sidebar Filtering Design
+
+## Goal
+
+Replace the current two-column bachelor programme selector with a compact segmented control. Selecting a programme must also focus the sidebar on that programme's curriculum and a small set of shared destinations.
+
+## Approved interaction
+
+The switch appears above the Starlight navigation tree and contains two short labels:
+
+- `DSAI` for Data Science & AI;
+- `CS` for Computer Science.
+
+Both options remain ordinary links. The current programme is shown with a filled accent state and `aria-current="page"`. Switching programmes navigates to the existing route-aware destination: a paired course where one exists, otherwise the other programme's overview.
+
+The control is navigation, not a client-side preference. Programme state continues to come from the current URL; it is not stored in cookies, local storage, or client JavaScript.
+
+## Visual design
+
+Use a small bordered container labelled `Bachelor programme`. Inside it, place `DSAI` and `CS` in an equal-width, two-segment row.
+
+The inactive segment uses the sidebar's subdued text and background colors. The active segment uses a filled blue accent with high-contrast text. Do not repeat the active programme's full name above the segments because the selected state and curriculum heading already communicate it.
+
+The control must fit the narrow mobile sidebar without either short label wrapping. It should use the existing Starlight and Incognito color variables so light and dark themes remain consistent.
+
+## Accessible naming and keyboard behavior
+
+Visible labels stay short, while each link exposes its full programme name to assistive technology. A tooltip may also expose the full name to pointer users, but it must not be the only source of the accessible name.
+
+The current link retains `aria-current="page"`. Both links remain reachable and operable by keyboard without JavaScript. Keyboard focus receives a visible outline that is distinguishable from the selected state.
+
+## Programme-specific sidebar contents
+
+On a Computer Science route, render:
+
+1. Home;
+2. Previous exams and documents;
+3. the complete Computer Science course tree;
+4. Useful Information and its existing child pages.
+
+On a Data Science & AI route, render:
+
+1. Home;
+2. Previous exams and documents;
+3. the complete Data Science & AI course tree;
+4. Useful Information and its existing child pages.
+
+Hide the inactive bachelor programme, About Incognito, Master AI, and Master DSDM in both programme-specific views.
+
+Global pages that are not associated with either bachelor programme retain the existing global sidebar. This keeps non-programme navigation usable and avoids arbitrarily choosing a programme when the URL supplies no programme context.
+
+## Implementation boundaries
+
+`ProgrammeSwitch.astro` owns only the accessible switch markup and presentation hooks. It consumes the current programme and switch destinations from the existing pure navigation helpers.
+
+The route-aware sidebar configuration remains responsible for selecting and ordering navigation entries. It must produce focused programme navigation without duplicating course definitions or switch-destination logic in the component.
+
+The Starlight `Sidebar` override continues to compose the programme switch with Starlight's default sidebar component. No client-side component or hydration directive is introduced.
+
+## Data flow
+
+1. The request pathname identifies the active programme.
+2. Existing navigation helpers calculate the two switch destinations.
+3. The switch renders ordinary links and marks the active programme.
+4. Middleware derives the resolved Starlight sidebar for the same pathname.
+5. Programme routes receive the selected curriculum plus the three approved shared destinations; global routes retain the global navigation.
+
+Unknown or malformed paths must fall back to global navigation rather than showing an incorrect programme as selected.
+
+## Verification
+
+Automated tests should verify:
+
+- the visible switch labels are `DSAI` and `CS`;
+- each link has a full accessible programme name;
+- the active link receives `aria-current="page"`;
+- the component contains no script or client hydration directive;
+- Computer Science routes include only the Computer Science course tree and the three shared destinations;
+- Data Science & AI routes include only the Data Science & AI course tree and the three shared destinations;
+- programme routes exclude About Incognito, Master AI, Master DSDM, and the inactive bachelor programme;
+- global routes retain the global navigation;
+- paired-course and fallback switch destinations continue to pass their existing route tests;
+- a production build renders the selector without horizontal overflow at narrow sidebar widths.
+
+Manual review should check both programme states in desktop and mobile navigation, in light and dark themes, with keyboard focus visible.
+
+## Out of scope
+
+- Changing course content or curriculum structure;
+- changing the paired-course mapping;
+- storing programme selection as a user preference;
+- adding JavaScript to animate or hydrate the switch;
+- redesigning the rest of Starlight's navigation tree.