FRD: Search and Filter Page Recipe

Document Summary

Field	Details
Feature Name	Search / Filter Page Recipe
Status	Draft
Owner	David Holmes
Contributors	Engineering, Design
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #77, ADR-027 (Default Tech Stack)
Last Updated	2026-05-26

---

Introduction

Overview

The Search / Filter Page recipe is an MDX documentation page with copy-pasteable code examples demonstrating how to compose existing design system components into a complete search-and-filter experience. It combines global-search-bar.tsx, filter-bar.tsx, badge components, empty states, and result layout variants into a cohesive pattern. The recipe shows URL-backed filter state, saved views, and responsive behavior.

Goals

• Provide a complete, copy-pasteable recipe for building a search/filter page using existing components.
• Demonstrate URL-backed filter state using useUrlState helpers.
• Show multiple result layout variants (list, grid, table).
• Include empty state, loading state, and error state patterns.
• Document saved views (persisted filter configurations).

Non-Goals

• Building new primitive components (the recipe uses existing ones).
• Implementing server-side search or filtering logic.
• Providing a generic “search page” component that handles all use cases.
• Building a saved-views backend or persistence layer.

---

Scope

In Scope

Area	Description
MDX recipe page	Storybook documentation page with code examples
Search input integration	Using global-search-bar.tsx with debounced input
Filter bar integration	Using filter-bar.tsx with typed filter definitions
Badge display	Active filter badges with remove action
URL-backed state	Filters, search term, sort, and pagination in URL params
Saved views	Pattern for saving and restoring filter configurations
Result layouts	List, grid, and table variants with a layout toggle
Empty states	”No results” with clear-filters action; “No data” initial state
Loading state	Skeleton-matched loading for each layout variant
Error state	Error display with retry action
Responsive behavior	Filter collapse on mobile; layout adaptation
Stories	Storybook stories demonstrating the composed recipe

Out of Scope

Area	Reason
New primitive components	Recipe uses existing components
Server-side search API	Consumer responsibility
Full-text search implementation	Consumer responsibility
Saved-views persistence backend	Consumer responsibility
Pagination component (new)	Uses existing pagination if available; otherwise shows pattern

---

Users and Pain Points

User Groups

User	Description	Needs
Application developers	Engineers building search/filter pages	A reference implementation showing how to compose existing components
Designers	Team members reviewing search/filter UX	A documented pattern they can reference for consistency
New team members	Engineers onboarding to the design system	A working example showing best practices

Pain Points

User	Pain Point	Impact
Application developers	No reference for combining search bar, filters, and results with URL state	Each developer invents their own composition; inconsistent UX
Application developers	Unclear how to handle empty, loading, and error states in a search context	States are missing or implemented inconsistently
Application developers	Filter state is often kept in component state, not the URL	Users cannot share or bookmark filtered views

---

Definitions

Term	Definition
Recipe	An MDX documentation page with complete, copy-pasteable code examples showing how to compose components
URL-backed state	Application state stored in URL search parameters so it survives page reloads and is shareable
Saved view	A named, persisted filter configuration that users can recall
Filter badge	A pill-shaped UI element showing an active filter with a remove action
Result layout	The visual arrangement of search results: list (vertical), grid (cards), or table (rows)

---

Current State

Existing Behavior

global-search-bar.tsx provides a search input with keyboard shortcut support. filter-bar.tsx provides a horizontal filter bar with typed filter definitions. Both exist as standalone components without a documented composition pattern.

Current Limitations

• No recipe showing how to combine search bar and filter bar.
• No documented pattern for URL-backed filter state.
• No example of empty, loading, and error states in a search context.
• No saved-views pattern.
• No guidance on result layout variants.

Existing Workarounds

• Developers study other applications’ source code or build from scratch.
• Search/filter pages across products have inconsistent behavior and appearance.

---

Proposed Solution

Summary

Create an MDX recipe page in Storybook documenting a complete search/filter page pattern. Include code examples for composing global-search-bar, filter-bar, badges, result layouts, and state management. Ship companion stories demonstrating the composed recipe.

Key Capabilities

• Complete code example showing GlobalSearchBar + FilterBar + results composition.
• URL-backed state management using useUrlState for search term, filters, sort, and pagination.
• Filter badges rendered from active filter state with individual removal.
• Three result layout variants (list, grid, table) with a toggle control.
• Empty state gated on isSuccess && data.length === 0 with a clear-filters action.
• Loading state using shape-matched skeletons per layout variant.
• Error state with retry action.
• Saved views: save current filters to a named view, select from saved views dropdown.

User Experience

Developers read the recipe in Storybook, copy code examples into their application, and customize the data fetching and filter definitions for their domain. The recipe shows all states and interactions so developers know what to implement.

Developer Experience

The recipe is self-contained MDX with inline code blocks. Developers can copy individual sections (just the filter bar, just the URL state, just the saved views) or the entire composition. Stories provide a visual reference for each state and layout.

---

Requirements

ID	Requirement	Priority	Notes
FR-001	The recipe must show integration of GlobalSearchBar and FilterBar	Must	Core composition
FR-002	The recipe must demonstrate URL-backed filter state	Must	Per P3 design principles
FR-003	The recipe must show filter badges with removal	Must	Active filter visibility
FR-004	The recipe must include list, grid, and table result layouts	Must	Common variants
FR-005	The recipe must show empty, loading, and error states	Must	Per P3 design principles
FR-006	The recipe should show a saved views pattern	Should	Advanced feature
FR-007	The recipe must be accompanied by Storybook stories	Must	Visual reference

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	Search input debounces queries by 300ms before updating URL state	Prevents excessive re-renders and API calls	Must
FUNC-002	Filters update URL search parameters on change	Shareable, bookmarkable filter state	Must
FUNC-003	Active filters render as badges below the filter bar	Users see what is active and can remove individual filters	Must
FUNC-004	”Clear all filters” action resets all filters and search term	Quick reset path	Must
FUNC-005	Layout toggle switches between list, grid, and table views	Users choose their preferred layout	Must
FUNC-006	Empty state shows when isSuccess && data.length === 0	Correct state gating per P3 principles	Must
FUNC-007	Loading state uses shape-matched skeletons for each layout variant	Visual consistency during loading	Must
FUNC-008	Error state shows an error message with a retry button	Recoverable error experience	Must
FUNC-009	Saved views: user can name and save current filter state	Recall frequently used filter sets	Should
FUNC-010	Saved views: user can select a saved view to apply its filters	Quick navigation to common filter sets	Should
FUNC-011	On mobile, filter bar collapses into a “Filters” button that opens a sheet or drawer	Responsive design	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Recipe code examples must be copy-pasteable without modification beyond data fetching	Maintainability	Must
NFR-002	Recipe must use only existing design system components (no new primitives)	Maintainability	Must
NFR-003	All recipe examples must pass TypeScript strict mode	Correctness	Must
NFR-004	Storybook stories must render without errors in both light and dark themes	Compatibility	Must
NFR-005	Filter state changes must update the URL without a full page reload	Performance	Must

---

API / Interface Requirements

Public API

This is a recipe (documentation), not a shipped component. No new public API is exported. The recipe demonstrates composition of existing APIs.

Name	Type	Description	Required
Recipe MDX page	documentation	Storybook MDX page with code examples	Yes
Recipe stories	stories	Storybook stories showing the composed pattern	Yes

Example Usage

// From the recipe: composing search + filter + results
function SearchPage() {
  const [search, setSearch] = useUrlState("q", "");
  const [filters, setFilters] = useUrlState("filters", {});
  const [layout, setLayout] = useUrlState("layout", "list");

  const { data, isLoading, isSuccess, isError, refetch } = useQuery({
    queryKey: ["search", search, filters],
    queryFn: () => fetchResults(search, filters),
  });

  return (
    <div>
      <GlobalSearchBar value={search} onChange={setSearch} />
      <FilterBar filters={filterDefinitions} value={filters} onChange={setFilters} />
      <ActiveFilterBadges filters={filters} onRemove={(key) => removeFilter(key)} />
      <LayoutToggle value={layout} onChange={setLayout} />

      {isLoading && <ResultsSkeleton layout={layout} />}
      {isError && <ErrorState onRetry={refetch} />}
      {isSuccess && data.length === 0 && <EmptyState onClearFilters={clearAll} />}
      {isSuccess && data.length > 0 && <ResultsList data={data} layout={layout} />}
    </div>
  );
}

API Notes

• The recipe uses useUrlState for URL-backed state; document the expected helper shape.
• GlobalSearchBar and FilterBar are imported from the design system.
• Result layouts and skeletons are shown as inline code for consumers to customize.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Search input must have an accessible label	aria-label or associated <label>
A11Y-002	Filter badges must be keyboard-removable (Enter/Space on the remove button)	Standard button behavior
A11Y-003	Layout toggle must use role="radiogroup" with role="radio" buttons	Correct ARIA for toggle group
A11Y-004	Empty state must be announced to screen readers when it appears	role="status" or aria-live="polite"
A11Y-005	Loading state must have aria-busy="true" on the results container	Screen readers know content is loading
A11Y-006	Error state must be announced to screen readers	role="alert"

Checklist

• Keyboard support is defined.
• Focus behavior is defined.
• Screen reader behavior is defined.
• Color contrast requirements are met.
• Reduced motion behavior is considered.
• Semantic HTML expectations are documented.
• ARIA usage is defined only where needed.

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Complete recipe MDX page with all code examples	Storybook MDX	Must
DOC-002	”When to use this recipe” and “When not to use” guidance	Storybook MDX	Must
DOC-003	Section on URL-backed state management	Storybook MDX	Must
DOC-004	Section on state management (empty, loading, error)	Storybook MDX	Must
DOC-005	Section on saved views pattern	Storybook MDX	Should
DOC-006	Responsive behavior notes	Storybook MDX	Must

Documentation Should Include

• Overview of the pattern
• When to use / when not to use
• Prerequisites (which components to install)
• Complete composition example
• URL state management
• Filter badges
• Result layout variants
• Empty, loading, error states
• Saved views
• Responsive behavior
• Accessibility notes
• Common mistakes

---

Dependencies

Dependency	Type	Owner	Status	Notes
global-search-bar.tsx	Design System	David Holmes	Ready	Existing component
filter-bar.tsx	Design System	David Holmes	Ready	Existing component
Badge component	Design System	David Holmes	Ready	For filter badges
Skeleton components	Design System	David Holmes	Ready	For loading states
TanStack Query	Engineering	David Holmes	Ready	Data fetching in examples

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Recipe may not cover all search/filter use cases	Developers may need to adapt significantly for complex filters	Document the recipe as a starting point; link to component docs for advanced usage
URL-backed state adds complexity compared to local state	More code to set up initially	Provide a useUrlState helper or reference; explain the benefits
Saved views pattern requires consumer persistence	Recipe shows the UI pattern but not the backend	Clearly document that persistence is the consumer’s responsibility
Recipe code may drift from component updates	Code examples may become outdated	Stories validate that the composition works; update recipe when components change

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the recipe include a sort control, or is that a separate pattern?	David Holmes	Open	—
Q-002	Should the recipe show pagination, infinite scroll, or both?	David Holmes	Open	—
Q-003	Should we ship a SearchFilterPage compound component in addition to the recipe?	David Holmes	Open	—
Q-004	Should the saved views UI use a dropdown, a sidebar section, or both?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Recipe MDX page renders in Storybook without errors	DOC-001
AC-002	Recipe shows GlobalSearchBar and FilterBar composed together	FR-001
AC-003	Recipe demonstrates URL-backed filter state with useUrlState	FR-002
AC-004	Recipe shows active filter badges with remove action	FR-003
AC-005	Recipe includes list, grid, and table result layout examples	FR-004
AC-006	Recipe shows empty state gated on isSuccess && data.length === 0	FUNC-006
AC-007	Recipe shows shape-matched loading skeletons for each layout	FUNC-007
AC-008	Recipe shows error state with retry action	FUNC-008
AC-009	Companion stories demonstrate each layout and state	FR-007
AC-010	All recipe code passes TypeScript strict mode	NFR-003

---

LLM Handoff Instructions

Expected LLM Behavior

• Follow the requirements and acceptance criteria in this document.
• Do not expand scope beyond the In Scope section.
• Respect the Out of Scope section.
• Use existing design system components; do not create new primitives.
• Gate empty state on isSuccess && data.length === 0 per P3 design principles.
• Use shape-matched skeletons for loading states per P3 design principles.
• Use useUrlState helpers for URL-backed state, not hand-rolled split/join per P3 design principles.
• Stories should cover all three layouts and all three states (loading, empty, error).

LLM Should Not

• Invent undocumented product behavior.
• Create new primitive components.
• Implement server-side search or filtering.
• Add new dependencies beyond what the design system already uses.
• Use inline styles instead of design system tokens.
• Gate empty state incorrectly (e.g., data.length === 0 without checking isSuccess).

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Recipe (MDX + stories), not a shipped compound component	Recipes give developers more flexibility and understanding than opaque components	David Holmes
2026-05-26	URL-backed state is mandatory in the recipe	Per P3 design principles: filters, tabs, sort use URL state	David Holmes
2026-05-26	Three layout variants (list, grid, table)	Covers the most common search result presentations	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft