Merge pull request #22 from hauntedfail/refine/ui-routing-refresh

docs: define task 18-alpha UI refresh workflow

Author: nonnil

docs/architecture/ui-and-routing.md

@@ -60,10 +60,11 @@ used by right-panel flashback shortcuts.
 
 Each flashback row shows the source memory title, muted prefix context,
 flashbacked text, and muted suffix context. The visual treatment should feel
-close to a GitHub pull request file-review view: dense rows, quote-focused
-content, clear source labels, and no full article rendering.
+close to a GitHub pull request file-review view: dense rows, selected text as
+the focal content, muted surrounding context, subordinate source metadata, and
+no full article rendering.
 
-Clicking the source title or quote opens `/memories/:id` at the corresponding
+Clicking the row content or source title opens `/memories/:id` at the corresponding
 flashback anchor.
 
 ## Responsive Behavior

docs/references/design-system/components-and-surfaces.md

@@ -49,10 +49,13 @@ Button shape follows the job:
 Use icons inside buttons when an icon exists. Do not replace familiar icon
 actions with verbose text-only controls.
 
+Read-status controls on memory cards and reader pages are icon-only action
+buttons. They keep accessible labels on the button. Open eye means unread
+(`read: false`), and closed eye means read (`read: true`).
+
 Paper themes add one deliberate material exception for archive actions:
 
-- Add-memory commands and List/Grid view toggles use the
-  `trauma-paper-wax-seal` treatment.
+- Add-memory commands use the `trauma-paper-wax-seal` treatment.
 - Do not replace theme colours inside this treatment. The button's existing
   semantic background, text, border, hover, and `aria-pressed` classes stay in
   charge of colour.
@@ -74,22 +77,31 @@ Paper themes add one deliberate material exception for archive actions:
 
 ## Browse Header
 
-The Memories browse header owns the list/grid view toggle. Keep the title block
-and view toggle in one two-column grid row at every route width:
-
-- Title/eyebrow column: `minmax(0, 1fr)` so it can shrink.
-- View mode column: `auto`, aligned to the inline end.
-- Do not let phone layout push List/Grid below the `Memories` title.
-- The shared narrow-route header container query can stack other route headers,
-  but `MemoryBrowse` uses its own header marker to remain a single row.
+The Memories browse header owns the read-state tabs, not a large route title
+or list/grid toggle.
+
+- Render exactly three equal-width tabs: `All`, `Unread`, and `Read`.
+- `All` is the default state and removes read-state tokens from the search
+  query.
+- `Unread` appends the standalone `unread` search token.
+- `Read` appends the standalone `read` search token.
+- The search bar and URL remain the source of truth for the filter state.
+- The active tab uses bold primary text plus a short rounded accent underline
+  anchored to the tab bottom. Inactive tabs use muted text.
+- The tab strip stays in one sticky row at every route width.
+- These tabs are not wax controls. Paper/Hermès wax treatment remains reserved
+  for archive commands such as Add memory.
 
 ## Shell Popovers
 
 Left-rail transient controls open as anchored popovers rather than global
 drawers:
 
-- Theme settings and Add memory composer use the same `role="dialog"` popup
-  pattern, `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls`.
+- Theme settings and Add memory composer use the shared `Popup` shell with
+  `role="dialog"`, `aria-haspopup`, `aria-expanded`, and `aria-controls`.
+- General action menus use the same `Popup` shell with `role="menu"`. Memory,
+  Moment, and Flashback delete actions use one danger menu-item treatment and
+  the shared trash icon.
 - Popovers close on Escape, outside pointer interaction, or successful
   completion of the contained workflow.
 - Add memory keeps the shell-level command globally reachable, but the composer
@@ -110,8 +122,25 @@ Inputs use semantic surfaces:
 Search inputs:
 
 - The browse route owns the memory search field.
+- The focus indicator belongs to the rounded search surface itself, using an
+  inset ring so focus corners follow the search bar shape.
 - The right rail does not contain a search field.
 
+## Taxonomy Rendering
+
+Use `TaxonomyList` for category/tag chips and right-rail taxonomy filters.
+
+- `mode="chips"` renders attached categories/tags on memory rows and reader
+  intros, and the same chip styling is also used for right-rail category/tag
+  filters.
+- Use `density="compact"` for right-rail chip lists when the section needs
+  tighter item spacing than memory-row metadata.
+- Selectable chips use `aria-pressed` for active right-rail filters.
+- `mode="filters"` remains available for full-width taxonomy controls, but the
+  current shell does not use it for the right rail.
+- Parents own route/query state; taxonomy rendering components do not know
+  browse query keys.
+
 ## Memory Browse Rows
 
 Memory rows are the primary archive scanning surface.
@@ -136,19 +165,24 @@ Grid mode reuses the same content and adds:
 
 ## Flashback Excerpts
 
-`FlashbackExcerpt` is the shared excerpt component for browse cards and the
-canonical `/flashbacks` view.
+`FlashbackInlineText` is the shared text primitive for right-rail Flashback
+shortcuts and the canonical `/flashbacks` view. `FlashbackExcerpt` is only a
+thin browse-card wrapper around the same primitive.
 
 Contract:
 
-- Rounded quote block.
-- Left border uses `border-trauma-quote-bar`.
-- Background uses `bg-trauma-quote-bg`.
-- Text uses `text-trauma-quote-ink`.
-- Flashback text uses `mark` with `bg-trauma-flashback-bg`.
+- Prefix and suffix context render around the selected Flashback text.
+- Context uses theme secondary/tertiary foreground tokens plus the shared
+  Flashback context blur/mask treatment, so it stays visibly lower contrast
+  than the selected text. The blur belongs to the prefix/suffix text spans, not
+  to the whole Flashback card, list, or right-rail island.
+- The selected Flashback string uses normal primary readable contrast and a
+  semantic `mark` element without becoming a separate highlighter badge.
 - Optional link wraps the whole excerpt.
 
-Do not hand-roll separate flashback quote treatments for each route.
+Do not hand-roll separate Flashback text treatments for each route. `/flashbacks`
+uses dense route rows: shared inline Flashback text first, then the source
+memory title as small supplemental metadata at the bottom.
 
 ## Right Rail Sections
 
@@ -167,17 +201,21 @@ route content containers. Contextual route content must stay small enough to
 act as a right rail aid rather than a second main pane.
 
 When an island contains an unbounded list, the list body must be a bounded
-scroll region. This is required for Flashback shortcut lists and reader TOC. Do not
-let those islands grow vertically for every item.
-
-Reader TOC should make overflow discoverable. When its bounded list can still
-scroll in a direction, show a low-contrast blur fade on that edge only. The
-fade should make the edge entries look slightly hazy, not like a heavy shadow
-or spotlight. Use neutral black in the fade recipe, not the primary/accent
-colour. The top fade must start at the scroll body edge so text cannot appear
-unblurred between the TOC heading and the fade. Use CSS gradients and masks to
-soften the fade boundary; do not use JavaScript to paint the effect. Do not
-render a fade for a direction that is not currently scrollable.
+scroll region. This is required for Flashback shortcut lists and reader TOC. Do
+not let those islands grow vertically for every item.
+
+Reader TOC should make overflow discoverable. When the bounded TOC can still
+scroll in a direction, show a low-contrast blur fade on that edge only. The fade
+should make the edge entries look slightly hazy, not like a heavy shadow or
+spotlight. Use neutral black in the fade recipe, not the primary/accent colour.
+The top fade must start at the scroll body edge so text cannot appear unblurred
+between the heading and the fade. Use CSS gradients and masks to soften the fade
+boundary. Do not render a fade for a direction that is not currently scrollable.
+
+Flashback shortcut lists do not use TOC scroll-edge overlays. Their focal
+treatment is per Flashback item: selected text remains normal and readable,
+while the stored prefix/suffix context uses the shared Flashback context
+blur/mask classes.
 
 ## Add Memory Composer
 

docs/references/design-system/interaction-and-accessibility.md

@@ -6,12 +6,14 @@ Canonical UI routes:
 
 - `/memories`
 - `/flashbacks`
+- `/moments`
 - `/memories/:id`
+- `/settings`
 
 The root route redirects to `/memories`.
 
-Do not add live navigation links to missing `/category`, `/tags`, `/backup`,
-or `/settings` routes. Future items may be rendered as disabled controls only.
+Do not add live navigation links to missing `/category`, `/tags`, or `/backup`
+routes. Future items may be rendered as disabled controls only.
 
 ## Query State
 
@@ -28,14 +30,29 @@ Supported browse concerns:
 Filter buttons should toggle their own query key without clearing unrelated
 query state.
 
+The `q` search value is preserved as raw input in the URL and may contain
+fielded filters:
+
+- `title:{some title}`
+- `url:{example.com}`
+- `tag:{sqlite}`
+- `category:{research}`
+- `flashback:{selected text}`
+- standalone `read` or `unread`
+
+Field filters, free-text terms, read-state filters, and explicit right-rail
+filters combine with AND semantics. `read unread` intentionally matches no
+rows.
+
 ## Row Navigation
 
 Memory browse rows are full-row links.
 
 Rules:
 
 - The entire row/card opens the memory.
-- Nested controls should be avoided inside the row.
+- Nested controls must stop propagation so action buttons do not trigger row
+  navigation.
 - There is no separate trailing `Open` button.
 - Keyboard focus must reach the row link.
 
@@ -86,8 +103,9 @@ Route surfaces should use `aria-labelledby` and stable headings:
 - `memories-title`.
 - `flashbacks-title`.
 - Reader fallback states use `reader-state-title`; ready reader content uses
-  the markdown heading from the stored content rather than a duplicate shell
-  header title.
+  a route-local sticky header with only the back control and `Memory` label.
+  The memory URL/action row, title, and taxonomy chips live in the main reader
+  intro.
 
 ## Selected And Disabled State
 

docs/references/design-system/layout-and-shell.md

@@ -171,7 +171,7 @@ Current islands:
 
 - Categories.
 - Tags.
-- Flashback.
+- Flashbacks.
 
 Route-specific content may be inserted above these browse filters when a route
 has a strong contextual aid. The current example is the reader table of
@@ -262,5 +262,5 @@ Reader image contract:
 Route frame classes belong to the route surface, not the shell. The shell owns
 columns, global navigation, bottom phone tabs, global composer popover state,
 and the right rail slot. Route files own
-headers, search controls, list/grid mode, empty states, reader content, and
+headers, search controls, read-state tabs, empty states, reader content, and
 route-specific loading states.

docs/references/design-system/reader-and-content.md

@@ -49,6 +49,9 @@ Contract:
 - Text is compact.
 - Links target generated markdown heading anchors and use the reader link
   token on hover.
+- Heading entries are left-aligned inside the island. Do not add global list
+  padding; reserve only the small Moment affordance slot and use heading-level
+  indentation for hierarchy.
 - Heading links live inside a bounded scroll body so many headings do not expand
   the right rail or the whole app layout.
 - When the bounded TOC body can scroll further, show a subtle blur fade only on
@@ -98,7 +101,8 @@ Visual contract:
   Keep this target treatment in the reader scope rather than as a generic mark
   rule.
 
-Flashback excerpts use `FlashbackExcerpt`, not the reader prose mark style.
+Flashback browse excerpts and right-rail shortcuts use the shared
+`FlashbackInlineText` primitive, not the reader prose mark style.
 
 ## Flashback Interaction
 

docs/references/design-system/tokens-and-themes.md

@@ -177,8 +177,12 @@ Reader links, flashbacks, and flashback excerpts use stable semantic tokens:
 
 - Inline flashbacks: `bg-trauma-flashback-bg`,
   `text-trauma-flashback-ink`.
-- Quote/excerpt cards: `bg-trauma-quote-bg`,
-  `border-trauma-quote-bar`, `text-trauma-quote-ink`.
+- Flashback browse context: shared context spans use secondary/tertiary
+  foreground mixing and the Flashback context blur/mask classes. Route and
+  right-rail Flashback rows should not use quote-card background or border
+  tokens.
+- Reader prose blockquotes still use the quote token family through the reader
+  prose styles.
 - Linked flashback hash targets:
   `.trauma-reader-content mark[data-flashback-id]:target` uses
   `anchor-flashback-bg`, `anchor-flashback-ink`, and

docs/references/design-system/verification.md

@@ -113,8 +113,8 @@ Check:
 - Phone `Primary tabs` render every rail item and use tab-bar-only horizontal
   scrolling when constrained.
 - Phone tab labels are visually hidden while role names remain available.
-- On phone, Memories List/Grid view controls stay on the right edge of the
-  `Memories` header row instead of wrapping below the title.
+- On phone, Memories read-state tabs stay as one sticky equal-width header row
+  and the obsolete List/Grid view controls are absent.
 - Tablet uses the compact icon rail and does not duplicate brand/filter header
   chrome.
 - Theme controls are hidden until the left-rail `Theme` tab opens their popover.

docs/workflows/README.md

@@ -23,6 +23,7 @@ architecture, reference, quality, or operations docs.
 | 14 | [Markdown reader refactor](task-14-markdown-reader-refactor.md) | Reader pipeline decomposition and behavior-preserving refactor | Ready after Task 13 |
 | 15 | [Refactor wave integration](task-15-refactor-wave-integration.md) | Cross-task verification and workflow/docs synchronization | Ready after Tasks 10-14 |
 | 18 | [Memory read status and memory actions](task-18-memory-read-status.md) | Persistent read/unread metadata, taxonomy creation/assignment, link-only status, reader action menu, memory deletion, settings page, Flashback marker selection, Moment section bookmarks, product-language migration, and imported media policy | Ready |
+| 18-alpha | [UI component and routing refresh](task-18-alpha-ui-routing-refresh.md) | Shared taxonomy rendering, popup shell consolidation, menu/composer/theme popup migration, and existing route-surface alignment | Ready on `workflow18-read-status` |
 | 19 | [Codex translation for memories](task-19-codex-translation.md) | ChatGPT sign-in through Codex, translation target settings, Codex-backed memory translation, and translated CONTENT.md variants | Ready |
 
 ## Archived Workflows
@@ -98,4 +99,5 @@ Use concise branch names that match the workflow:
 - `refactor/markdown-reader`
 - `chore/refactor-wave-integration`
 - `feat/memory-actions`
+- `refine/ui-routing-refresh`
 - `feat/codex-translation`