docs: design template catalog

[soma-enyi]

docs: design template catalog browsing experience

Summary

Adds a comprehensive design specification for the template catalog browsing
experience at /app/templates. The document captures the full discovery flow
so that contributors, reviewers, and designers share a single source of truth
for how users browse, filter, and select templates.

Changes

Added docs/template-catalog.md

Layout

• Annotated ASCII wireframe of the full catalog page structure.

Filter controls

• Search input: placement (top-left, max-w-md), type="search", 300 ms
  debounce, matches name and description.
• Category chips: All · DEX · Lending · Payment · Asset Issuance; always
  visible (no hidden dropdowns); clicking an active chip deselects it.
• URL persistence: active filters serialised to ?category=&search= so state
  survives reload and is shareable.
• Sort: documented as server-defined order; sort control deferred to a future
  iteration with rationale.

Card anatomy

• Full breakdown of every card element: preview image / emoji fallback,
  category badge, name, description (line-clamp-2), enabled-feature count
  (pluralised), and "Use Template" CTA button.
• Hover and transition behaviour noted.

States

• Loading: 6-card pulse skeleton, role="status", visually-hidden SR text.
• Error: <ErrorState> with retry; special-cased 429 message.
• No results (filtered): <EmptyState> with "Clear Filters" action.
• No results (unfiltered): <EmptyState> without action button.
• Results count: aria-live="polite" region above the grid.

Mobile behavior

• Breakpoint table: 1-column grid and stacked filter bar below 640 px;
  2-column grid at sm–md; 3-column grid at ≥ lg.
• Filter bar reflow and chip wrapping behaviour documented.

Category discovery

• All four categories always visible as chips.
• Category value → label → emoji → use-case table.

Accessibility

• role="group" aria-label="Filter by category" on chip group.
• aria-pressed on each chip.
• aria-live="polite" results count.
• Unique aria-label="Use {name} template" on every card CTA.
• alt text on preview images; aria-hidden on emoji fallbacks.

Implementation reference

• Maps each concern (page, filters, grid, card, hook, types) to its source
  file for quick navigation.

Edge cases & assumptions

• Abort controller on rapid filter changes, missing preview images, long
  names, singular/plural result count, pagination and sort deferred.

Testing

No runtime code was changed. Existing component and hook tests
(TemplateCard.test.tsx, TemplateCatalogFilters.test.tsx,
TemplateGrid.test.tsx, useTemplates.test.ts) continue to cover the
implementation this document describes.

Closes

Closes #12

[drips-wave]

@soma-enyi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits