[Templates] Fill systematic gaps in the official page-template roster (marketing, forms, palette, notifications, mobile)
- Dominant language
- TypeScript
- Stars
- 13.1k
- Forks
- 1.1k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 669
Description
## Summary
We ship ~45 page templates and 630+ component blocks, but there are systematic gaps in the page-template roster — whole classes of prompts that either retrieve nothing useful or retrieve a page that composes the *wrong* components. This issue proposes a prioritized set of official page templates to close those gaps, and grounds each recommendation in (a) an unrepresented slice of the component surface and (b) demand already proven by the community catalog.
This generalizes #4523 (scheduling/calendar). That issue found the calendar gap by the exact right method — a shipped component family with zero page-level usage. The same method surfaces several more gaps; this issue collects them so we can prioritize as a set.
## How `build` picks a template (why this defines "gap")
`build(query)` → `buildKit` → `search()`. The scoring ladder is exact-name 100 / exact-keyword 90 / name-Levenshtein 80 / keyword-substring 70 / name-substring 60 / description-mention 50.
The load-bearing detail: **for page templates, the searchable "keywords" are auto-extracted from the rendered component names plus the `category` split into words.** So a template's `category` + `description` + *the components it actually renders* dominate retrieval; the folder name is only a tiebreak (stopwords like `page`/`app`/`view`/`screen` are dropped).
Consequence: a "gap" is not "we lack a pretty page." A gap is **a prompt-class whose best answer would compose components that no page template currently renders** — so `search()` can only return a page built from other components, and the agent hand-rolls the rest.
## The frame: official = vocabulary, community = literature
- **Official core** teaches the *component surface* — the canonical, rubric-clean way to compose our primitives. Every template must pass the grading rubric (B+).
- **Community** (the catalog at https://thedjpetersen.github.io/astryx-templates/) is *domain literature* — ~540 hyper-specific applications. Its bar is safety, not curation.
So the right things to pull into **official** are patterns that **teach unrepresented vocabulary** and **answer an unserved prompt-class** — not domain-specific apps. The community catalog is the evidence layer: where it independently grew a pattern that core lacks, that's a validated gap.
## Primary signal: 61 components have a block but zero page-template usage
A page template is how `build` learns to *compose* components together. **61 shipped components never appear in any page template**, so a prompt whose ideal answer uses them can't retrieve a page that demonstrates them. Filtering out sub-parts (e.g. `CommandPaletteItem`), providers (`Theme`, `LinkProvider`), and a11y utilities leaves a clear set of page-worthy gaps, below.
---
## Recommended official page templates (ranked by prompt-frequency × vocabulary gap)
Each row lists the vocabulary it unlocks, the prompt-class it serves, and community templates that already validate the demand (links go to the live catalog).
### 1. Marketing set — biggest uncovered request domain (34 community templates, 0 official)
Landing / pricing / hero / features / footer / CTA are arguably the single most common request class for any design system, and official ships **nothing**. Proposed canonical pages: a full landing, pricing, feature-sections, and a footer collection.
- Unlocks: composition of `Section`, `Grid`, `Card`, `Heading`, `Button` at marketing scale (currently only app-shell composition is taught)
- Prompt-class: "landing page", "pricing page", "hero section", "feature grid", "footer" → currently no strong match
- Validated by:
- [saas-landing-page](https://thedjpetersen.github.io/astryx-templates/#saas-landing-page)
- [marketing-hero-showcase](https://thedjpetersen.github.io/astryx-templates/#marketing-hero-showcase)
- [pricing-plans](https://thedjpetersen.github.io/astryx-templates/#pricing-plans)
- [marketing-feature-sections](https://thedjpetersen.github.io/astryx-templates/#marketing-feature-sections)
- [marketing-footer-collection](https://thedjpetersen.github.io/astryx-templates/#marketing-footer-collection)
- [marketing-cta-banners](https://thedjpetersen.github.io/astryx-templates/#marketing-cta-banners)
- [marketing-faq-contact](https://thedjpetersen.github.io/astryx-templates/#marketing-faq-contact)
- [marketing-social-proof](https://thedjpetersen.github.io/astryx-templates/#marketing-social-proof)
### 2. Calendar / scheduler — see #4523
Unlocks `Calendar` + `DateInput` + `DateRangeInput` + `TimeInput` in one page (all four have zero page usage today). #4523 already scopes a single `scheduling` template; this is the highest-value single addition. Community validation:
- [calendar-month-grid](https://thedjpetersen.github.io/astryx-templates/#calendar-month-grid)
- [calendar-week-agenda](https://thedjpetersen.github.io/astryx-templates/#calendar-week-agenda)
- [booking-availability-picker](https://thedjpetersen.github.io/astryx-templates/#booking-availability-picker)
- [team-scheduler](https://thedjpetersen.github.io/astryx-templates/#team-scheduler)
- [time-off-planner](https://thedjpetersen.github.io/astryx-templates/#time-off-planner)
- [event-detail-rsvp](https://thedjpetersen.github.io/astryx-templates/#event-detail-rsvp)
### 3. Form wizard — unlocks `Stepper`
`Stepper` ships but appears in no page template. A multi-step wizard with a step indicator, per-step validation, and a review step is the canonical home for it.
- Prompt-class: "wizard", "multi-step form", "setup flow", "onboarding steps"
- Validated by: [form-wizard](https://thedjpetersen.github.io/astryx-templates/#form-wizard) (and the adjacent [form-page](https://thedjpetersen.github.io/astryx-templates/#form-page), [form-modal](https://thedjpetersen.github.io/astryx-templates/#form-modal), [form-side-sheet](https://thedjpetersen.github.io/astryx-templates/#form-side-sheet), [form-inline-edit](https://thedjpetersen.github.io/astryx-templates/#form-inline-edit) form-pattern set)
### 4. Command palette — unlocks the `CommandPalette` family
`CommandPalette` and its 7 sub-components have zero page usage. A cmd-K launcher over a dimmed workspace is the canonical demo.
- Prompt-class: "command palette", "cmd+k", "quick launcher", "fuzzy action search"
- Validated by: [command-palette-launcher](https://thedjpetersen.github.io/astryx-templates/#command-palette-launcher)
### 5. Notification center + confirm flow — unlocks `Toast` and `AlertDialog`
Both ship with zero page usage. A notification center (bell → popover → toast) plus a destructive-action confirm flow teach them together.
- Prompt-class: "notifications", "toast", "confirm dialog", "destructive action"
- Validated by: [notification-center](https://thedjpetersen.github.io/astryx-templates/#notification-center), [status-feedback-gallery](https://thedjpetersen.github.io/astryx-templates/#status-feedback-gallery)
### 6. One mobile shell — unlocks `BottomSheet` + `MobileNav` (distilled from 122)
The community's `Mobile` category is 122 templates — its crown jewel, but it is *literature*. We should NOT absorb it. Instead, distill **one** canonical mobile shell that teaches the 390px frame + `BottomSheet` + `MobileNav`.
- Prompt-class: "mobile app", "bottom sheet", "mobile nav", "snap points"
- Reference (for distillation, not absorption): [mobile-chrome-gallery](https://thedjpetersen.github.io/astryx-templates/#mobile-chrome-gallery), [bottom-sheet-snap-explorer](https://thedjpetersen.github.io/astryx-templates/#bottom-sheet-snap-explorer)
### Optional: UI-kit vocabulary showcases
If we want maximal surface coverage in one shot, the community's "gallery" pages each demonstrate a whole component family on one screen. Good raw material for showcase-style pages:
- [ui-elements-gallery](https://thedjpetersen.github.io/astryx-templates/#ui-elements-gallery)
- [form-controls-gallery](https://thedjpetersen.github.io/astryx-templates/#form-controls-gallery)
- [layout-primitives-gallery](https://thedjpetersen.github.io/astryx-templates/#layout-primitives-gallery)
- [headings-lists-gallery](https://thedjpetersen.github.io/astryx-templates/#headings-lists-gallery)
---
## What NOT to absorb
- **The 122 `Mobile` templates** — literature, not vocabulary. Distill into one shell (item 6).
- **Vertical Ops / Legal AI / Workforce / Healthcare / Logistics (~90 combined)** — pure domain literature. Leave in the community catalog; they double as an integration test suite for core.
The test for "official" is: *does it teach how to compose our components, or does it teach a domain?* Only the former belongs in core.
## Related retrieval-hygiene bug (worth fixing alongside)
Two existing pages are noise magnets that will outrank whatever we add: `dashboard-portfolio` (~30 auto-extracted keywords incl. Table/List) and `theme-showcase` (~51 keywords, empty `category`). On a query like "customer list", `dashboard-portfolio` can rank #1 over the correct table template. Suggested fixes: cap/curate auto-extracted page keywords, require a non-empty `category`, and down-weight kitchen-sink showcase pages in `search()`. Otherwise new templates get buried under the existing ones.
## Proposed sequencing
1. Marketing set (landing, pricing, feature-sections, footer)
2. Scheduling (#4523)
3. Form wizard
4. Command palette
5. Notification center + confirm flow
6. Mobile shell
Each is justified twice: it teaches vocabulary with zero current coverage, and it targets a prompt-class `search()` answers poorly today — with community demand already proven.
Contributor guide
Assessment
This issue has not been assessed yet.