An open source design system that's fully customizable and agent ready
TypeScript
feat(templates): category system, standardized names, localized assets (#2442)
Ernest811c6b5f57e6
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex a5260e99e6..23432a1015 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -790,6 +790,8 @@ async function generateTemplateRegistry() {name: doc.name || dir.name,description: doc.description || '',isReady: doc.isReady ?? true,+ category: doc.category || '',+ isHiddenFromOverview: doc.isHiddenFromOverview ?? false,source,});}@@ -803,6 +805,11 @@ export interface TemplateEntry {name: string;description: string;isReady: boolean;+ /** Functional category, e.g. 'Dashboard - Analytics'. Empty when untagged.+ * The overview groups by the part before ' - '. */+ category: string;+ /** When true, hide from the Templates overview gallery (still CLI-available). */+ isHiddenFromOverview: boolean;source: string;}diff --git a/apps/docsite/src/app/(site)/templates/page.tsx b/apps/docsite/src/app/(site)/templates/page.tsxindex 6201f6094d..b3f646d872 100644--- a/apps/docsite/src/app/(site)/templates/page.tsx+++ b/apps/docsite/src/app/(site)/templates/page.tsx@@ -8,10 +8,9 @@import {useMemo} from 'react';import * as stylex from '@stylexjs/stylex';-import {XDSText} from '@xds/core/Text';+import {XDSText, XDSHeading} from '@xds/core/Text';import {XDSVStack, XDSHStack} from '@xds/core/Layout';import {XDSSection} from '@xds/core/Section';-import {XDSGrid} from '@xds/core/Grid';import {XDSCard} from '@xds/core/Card';import {XDSButton} from '@xds/core/Button';import {XDSOverlay} from '@xds/core/Overlay';@@ -21,9 +20,32 @@ import {TemplateThumbnail} from '../../../components/TemplateThumbnail';import {buildPlaygroundHref} from '../../../components/playgroundLink';const styles = stylex.create({+ section: {+ marginInline: 'auto',+ },heroTitle: {textAlign: 'center' as const,},+ // Establishes a query container so the grid responds to its own available+ // width (the content area), not the viewport.+ gridContainer: {+ containerType: 'inline-size',+ },+ // Mobile-first: 1 column by default, 2 columns at >=800px, 3 at >=1200px of+ // container width. min-width queries are used because StyleX reorders+ // overlapping max-width queries (the wider one wins), which would prevent+ // the 1-column case from ever triggering. Uses 1fr tracks so cards always+ // fill the row width at every column count.+ grid: {+ display: 'grid',+ columnGap: 'var(--spacing-4)',+ rowGap: 'var(--spacing-6)',+ gridTemplateColumns: {+ default: 'minmax(0, 1fr)',+ '@container (min-width: 800px)': 'repeat(2, minmax(0, 1fr))',+ '@container (min-width: 1200px)': 'repeat(3, minmax(0, 1fr))',+ },+ },cardImage: {display: 'block',width: '100%',@@ -48,91 +70,185 @@ const styles = stylex.create({},});+/** Display order for the top-level category groups. Groups not listed here+ * are appended alphabetically; untagged templates fall under 'Other'. */+const GROUP_ORDER = [+ 'Dashboard',+ 'Table',+ 'Form',+ 'Settings',+ 'Login',+ 'Tools',+ 'Content',+ 'AI Chat',+ 'Gallery',+ 'Shell',+];++const OTHER_GROUP = 'Other';++/** Plural display labels for the group headings. The underlying category data+ * stays singular (e.g. 'Dashboard - Analytics'); only the heading is pluralized.+ * Handles irregulars (Gallery → Galleries) and uncountable nouns (Content). */+const GROUP_LABELS: Record<string, string> = {+ Dashboard: 'Dashboards',+ Table: 'Tables',+ Form: 'Forms',+ Settings: 'Settings',+ Login: 'Logins',+ Tools: 'Tools',+ Content: 'Content',+ 'AI Chat': 'AI Chats',+ Gallery: 'Galleries',+ Shell: 'Shells',+};++/** Derive the group heading from a category string. The group is the text+ * before the first ' - ' separator (e.g. 'Dashboard - Analytics' → 'Dashboard').+ * Standalone categories without a separator (e.g. 'Settings') are their own+ * group. Untagged templates fall under 'Other'. */+function groupOf(category: string): string {+ if (!category) {return OTHER_GROUP;}+ const idx = category.indexOf(' - ');+ return idx === -1 ? category : category.slice(0, idx);+}++interface TemplateItem {+ name: string;+ description: string;+ slug: string;+ href: string;+ isReady: boolean;+ category: string;+ source: string;+}+export default function TemplatesPage() {- const items = useMemo(- () =>- templates.map(t => ({+ const groups = useMemo(() => {+ const visible = templates.filter(t => !t.isHiddenFromOverview);++ const byGroup = new Map<string, TemplateItem[]>();+ for (const t of visible) {+ const group = groupOf(t.category);+ const item: TemplateItem = {name: t.name,description: t.description,slug: t.slug,href: `/templates/${t.slug}`,isReady: t.isReady,+ category: t.category,source: t.source,- })),- [],- );+ };+ const list = byGroup.get(group);+ if (list) {list.push(item);}+ else {byGroup.set(group, [item]);}+ }++ const rank = (g: string) => {+ const i = GROUP_ORDER.indexOf(g);+ if (i !== -1) {return i;}+ return g === OTHER_GROUP ? Number.MAX_SAFE_INTEGER : GROUP_ORDER.length;+ };++ return [...byGroup.entries()]+ .map(([group, list]) => ({+ group,+ items: list.sort((a, b) => a.name.localeCompare(b.name)),+ }))+ .sort(+ (a, b) =>+ rank(a.group) - rank(b.group) || a.group.localeCompare(b.group),+ );+ }, []);return (- <XDSSection maxWidth="xl" padding={6}>- <XDSVStack gap={6}>+ <XDSSection maxWidth={2000} padding={6} xstyle={styles.section}>+ <XDSVStack gap={8}><XDSVStack gap={2} style={{alignItems: 'center'}}>- <XDSText type="display-2" xstyle={styles.heroTitle}>+ <XDSHeading level={1} type="display-2" xstyle={styles.heroTitle}>Templates- </XDSText>+ </XDSHeading><XDSText type="body" color="secondary" xstyle={styles.heroTitle}>Ready-to-use page templates to kickstart your project.</XDSText></XDSVStack>- <XDSGrid columns={{minWidth: 300, repeat: 'fill'}} gap={4} rowGap={6}>- {items.map(item => (- <XDSCard key={item.slug} padding={0}>- <XDSOverlay- showOn="hover"- scrim="dark"- content={- <div {...stylex.props(styles.overlayInner)}>- <XDSVStack gap={2}>- <XDSVStack gap={0.5}>- <XDSText- type="body"- weight="bold"- style={{color: '#fff'}}>- {item.name}- </XDSText>- <XDSText- type="supporting"- style={{color: 'rgba(255,255,255,0.7)'}}>- {item.description.slice(0, 80)}- {item.description.length > 80 ? '\u2026' : ''}- </XDSText>- </XDSVStack>- <XDSHStack gap={2}>- <XDSButton- label="Preview"- variant="secondary"- size="sm"- href={item.href}- />- {item.source && (- <XDSButton- label="Open in Playground"- variant="secondary"- size="sm"- onClick={() => {- window.location.href = buildPlaygroundHref(- item.source,- );- }}- />+ {groups.map(({group, items}) => (+ <XDSVStack key={group} gap={4}>+ <XDSHeading level={2}>{GROUP_LABELS[group] ?? group}</XDSHeading>+ <div {...stylex.props(styles.gridContainer)}>+ <div {...stylex.props(styles.grid)}>+ {items.map(item => (+ <XDSCard key={item.slug} padding={0}>+ {/* Inline style overrides --color-overlay for a stronger scrim.+ CSS variable overrides in stylex.create hit a type mismatch+ with StyleXStyles in TS 6+ / StyleX 0.18+ strict mode. */}+ <div+ style={+ {+ '--color-overlay':+ 'color-mix(in srgb, var(--color-on-light) 78%, transparent)',+ } as React.CSSProperties+ }>+ <XDSOverlay+ showOn="hover"+ scrim="dark"+ content={+ <div {...stylex.props(styles.overlayInner)}>+ <XDSVStack gap={2}>+ <XDSVStack gap={0.5}>+ <XDSText+ type="body"+ weight="bold"+ style={{color: '#fff'}}>+ {item.name}+ </XDSText>+ <XDSText+ type="supporting"+ style={{color: 'rgba(255,255,255,0.7)'}}>+ {item.description.slice(0, 80)}+ {item.description.length > 80 ? '\u2026' : ''}+ </XDSText>+ </XDSVStack>+ <XDSHStack gap={2}>+ <XDSButton+ label="Preview"+ variant="secondary"+ size="sm"+ href={item.href}+ />+ {item.source && (+ <XDSButton+ label="Open in Playground"+ variant="secondary"+ size="sm"+ onClick={() => {+ window.location.href =+ buildPlaygroundHref(item.source);+ }}+ />+ )}+ </XDSHStack>+ </XDSVStack>+ </div>+ }>+ {item.isReady ? (+ <TemplateThumbnail slug={item.slug} />+ ) : (+ <div {...stylex.props(styles.cardImage)}>+ <div {...stylex.props(styles.comingSoon)}>+ <XDSBadge label="Coming Soon" variant="info" />+ </div>+ </div>)}- </XDSHStack>- </XDSVStack>- </div>- }>- {item.isReady ? (- <TemplateThumbnail slug={item.slug} />- ) : (- <div {...stylex.props(styles.cardImage)}>- <div {...stylex.props(styles.comingSoon)}>- <XDSBadge label="Coming Soon" variant="info" />+ </XDSOverlay></div>- </div>- )}- </XDSOverlay>- </XDSCard>- ))}- </XDSGrid>+ </XDSCard>+ ))}+ </div>+ </div>+ </XDSVStack>+ ))}</XDSVStack></XDSSection>);diff --git a/apps/docsite/src/components/TemplateThumbnail.tsx b/apps/docsite/src/components/TemplateThumbnail.tsxindex f4a8122a8f..eba65263a4 100644--- a/apps/docsite/src/components/TemplateThumbnail.tsx+++ b/apps/docsite/src/components/TemplateThumbnail.tsx@@ -63,6 +63,10 @@ const TEMPLATE_COMPONENTS: Record<'ai-chat': lazy(() => import('../../../../packages/cli/templates/pages/ai-chat/page'),),+ 'ai-chat-artifact': lazy(+ () =>+ import('../../../../packages/cli/templates/pages/ai-chat-artifact/page'),+ ),'ai-chat-landing': lazy(() =>import('../../../../packages/cli/templates/pages/ai-chat-landing/page'),@@ -167,6 +171,22 @@ const TEMPLATE_COMPONENTS: Record<'table-page': lazy(() => import('../../../../packages/cli/templates/pages/table-page/page'),),+ 'table-page-chart': lazy(+ () =>+ import('../../../../packages/cli/templates/pages/table-page-chart/page'),+ ),+ 'table-page-heatmap-status': lazy(+ () =>+ import(+ '../../../../packages/cli/templates/pages/table-page-heatmap-status/page'+ ),+ ),+ 'table-page-shoe-store-heatmap': lazy(+ () =>+ import(+ '../../../../packages/cli/templates/pages/table-page-shoe-store-heatmap/page'+ ),+ ),};export function TemplateThumbnail({slug}: {slug: string}) {diff --git a/packages/cli/templates/pages/ai-chat-artifact/template.doc.mjs b/packages/cli/templates/pages/ai-chat-artifact/template.doc.mjsindex 4bc4b93282..94d28bef92 100644--- a/packages/cli/templates/pages/ai-chat-artifact/template.doc.mjs+++ b/packages/cli/templates/pages/ai-chat-artifact/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'AI Chat (Artifact)',- displayName: 'AI Chat (Artifact)',+ name: 'Artifact Page',+ displayName: 'Artifact Page',description: 'AI chat interface with a resizable chat panel on the left and an artifact preview area on the right for content being created via the conversation',isReady: true,+ category: 'AI Chat - Artifact Page',};diff --git a/packages/cli/templates/pages/ai-chat-landing/template.doc.mjs b/packages/cli/templates/pages/ai-chat-landing/template.doc.mjsindex eaebf7eb81..f01ec053ef 100644--- a/packages/cli/templates/pages/ai-chat-landing/template.doc.mjs+++ b/packages/cli/templates/pages/ai-chat-landing/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'AI Chat (Landing Page)',- displayName: 'AI Chat (Landing Page)',+ name: 'Landing',+ displayName: 'Landing',description: 'AI assistant landing page with chat composer, greeting, and category toggles',isReady: true,+ category: 'AI Chat - Landing',};diff --git a/packages/cli/templates/pages/ai-chat/template.doc.mjs b/packages/cli/templates/pages/ai-chat/template.doc.mjsindex 9521c9aad2..b13fe8d4bf 100644--- a/packages/cli/templates/pages/ai-chat/template.doc.mjs+++ b/packages/cli/templates/pages/ai-chat/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'AI Chat',- displayName: 'AI Chat',+ name: 'Conversation',+ displayName: 'Conversation',description: 'AI assistant conversation view with tool calls, system messages, markdown, code blocks, and multi-bubble grouping',isReady: true,+ category: 'AI Chat - Conversation',};diff --git a/packages/cli/templates/pages/blank/template.doc.mjs b/packages/cli/templates/pages/blank/template.doc.mjsindex d0d83dcae5..c7b8836d09 100644--- a/packages/cli/templates/pages/blank/template.doc.mjs+++ b/packages/cli/templates/pages/blank/template.doc.mjs@@ -3,9 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Blank Page',- displayName: 'Blank Page',+ name: 'Blank',+ displayName: 'Blank',description: 'Minimal page scaffold',isReady: true,scaffold: true,+ category: 'Shell - Blank',};diff --git a/packages/cli/templates/pages/centered-hero/template.doc.mjs b/packages/cli/templates/pages/centered-hero/template.doc.mjsindex a631f14e12..ade01143e4 100644--- a/packages/cli/templates/pages/centered-hero/template.doc.mjs+++ b/packages/cli/templates/pages/centered-hero/template.doc.mjs@@ -3,9 +3,11 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Centered Hero',- displayName: 'Centered Hero',+ name: 'Basic',+ displayName: 'Basic',description:'Centered headline, description, and CTA buttons above a full-width image.',isReady: false,+ category: 'Gallery - Basic',+ isHiddenFromOverview: true,};diff --git a/packages/cli/templates/pages/classic-gallery/template.doc.mjs b/packages/cli/templates/pages/classic-gallery/template.doc.mjsindex 3fcb89e04f..1afde28154 100644--- a/packages/cli/templates/pages/classic-gallery/template.doc.mjs+++ b/packages/cli/templates/pages/classic-gallery/template.doc.mjs@@ -2,9 +2,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {- name: 'Classic Gallery',- displayName: 'Classic Gallery',+ name: 'Basic',+ displayName: 'Basic',description: 'Clean 2×2 image grid with uniform sizing',type: 'page',isReady: true,+ category: 'Gallery - Basic',};diff --git a/packages/cli/templates/pages/contact-form/template.doc.mjs b/packages/cli/templates/pages/contact-form/template.doc.mjsindex b42092978c..6a3953033e 100644--- a/packages/cli/templates/pages/contact-form/template.doc.mjs+++ b/packages/cli/templates/pages/contact-form/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Contact Form',- displayName: 'Contact Form',+ name: 'Basic',+ displayName: 'Basic',description: 'Marketing lead-capture form with pill toggles, dropdowns, and full-width CTA.',isReady: true,+ category: 'Form - Basic',};diff --git a/packages/cli/templates/pages/dashboard-portfolio/template.doc.mjs b/packages/cli/templates/pages/dashboard-portfolio/template.doc.mjsindex ef2be8e748..92110f7f56 100644--- a/packages/cli/templates/pages/dashboard-portfolio/template.doc.mjs+++ b/packages/cli/templates/pages/dashboard-portfolio/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Dashboard (Portfolio)',- displayName: 'Dashboard (Portfolio)',+ name: 'Portfolio',+ displayName: 'Portfolio',description: 'Investment portfolio dashboard with KPI metrics, area chart, and top asset holdings',isReady: true,+ category: 'Dashboard - Portfolio',};diff --git a/packages/cli/templates/pages/dashboard/template.doc.mjs b/packages/cli/templates/pages/dashboard/template.doc.mjsindex a8d9879b1e..64cc40f5e6 100644--- a/packages/cli/templates/pages/dashboard/template.doc.mjs+++ b/packages/cli/templates/pages/dashboard/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Dashboard',- displayName: 'Dashboard',+ name: 'Analytics',+ displayName: 'Analytics',description: 'Analytics dashboard with KPI cards, charts, and data tables',isReady: true,+ category: 'Dashboard - Analytics',};diff --git a/packages/cli/templates/pages/detail-page/template.doc.mjs b/packages/cli/templates/pages/detail-page/template.doc.mjsindex 3ffd494201..fec49449ae 100644--- a/packages/cli/templates/pages/detail-page/template.doc.mjs+++ b/packages/cli/templates/pages/detail-page/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Detail Page',- displayName: 'Detail Page',+ name: 'Order Detail',+ displayName: 'Order Detail',description: 'Order detail page with timeline and line items',isReady: true,+ category: 'Content - Order Detail',};diff --git a/packages/cli/templates/pages/documentation-design/template.doc.mjs b/packages/cli/templates/pages/documentation-design/template.doc.mjsindex f76852f57e..46d39b3759 100644--- a/packages/cli/templates/pages/documentation-design/template.doc.mjs+++ b/packages/cli/templates/pages/documentation-design/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Component Reference',- displayName: 'Component Reference',+ name: 'Documentation Design',+ displayName: 'Documentation Design',description: 'Component documentation page with live preview, usage guide, best practices table, and code examples.',isReady: true,+ category: 'Content - Documentation Design',};diff --git a/packages/cli/templates/pages/documentation-technical/template.doc.mjs b/packages/cli/templates/pages/documentation-technical/template.doc.mjsindex b65b287c66..309d47f843 100644--- a/packages/cli/templates/pages/documentation-technical/template.doc.mjs+++ b/packages/cli/templates/pages/documentation-technical/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Setup Guide',- displayName: 'Setup Guide',+ name: 'Documentation Technical',+ displayName: 'Documentation Technical',description: 'Getting started guide with install steps, AI assistance prompt card, theming setup, and next steps.',isReady: true,+ category: 'Content - Documentation Technical',};diff --git a/packages/cli/templates/pages/documentation/template.doc.mjs b/packages/cli/templates/pages/documentation/template.doc.mjsindex 52dff41194..1b5a28071a 100644--- a/packages/cli/templates/pages/documentation/template.doc.mjs+++ b/packages/cli/templates/pages/documentation/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Documentation Home',- displayName: 'Documentation Home',+ name: 'Documentation Catalog',+ displayName: 'Documentation Catalog',description: 'Documentation landing page with hero banner and component category grid organized by Core, Layout, Navigation, and Form.',isReady: true,+ category: 'Content - Documentation Catalog',};diff --git a/packages/cli/templates/pages/editor/template.doc.mjs b/packages/cli/templates/pages/editor/template.doc.mjsindex 722258a23f..d1b909cd85 100644--- a/packages/cli/templates/pages/editor/template.doc.mjs+++ b/packages/cli/templates/pages/editor/template.doc.mjs@@ -7,4 +7,5 @@ export const doc = {displayName: 'Page Editor',description: 'Block-based page builder with sidebar config and live preview',isReady: true,+ category: 'Tools - Page Editor',};diff --git a/packages/cli/templates/pages/file-explorer/template.doc.mjs b/packages/cli/templates/pages/file-explorer/template.doc.mjsindex c98730aa22..ec7bee292d 100644--- a/packages/cli/templates/pages/file-explorer/template.doc.mjs+++ b/packages/cli/templates/pages/file-explorer/template.doc.mjs@@ -7,4 +7,5 @@ export const doc = {displayName: 'File Explorer',description: 'Column-based file browser inspired by macOS Finder',isReady: true,+ category: 'Tools - File Explorer',};diff --git a/packages/cli/templates/pages/form-two-column/template.doc.mjs b/packages/cli/templates/pages/form-two-column/template.doc.mjsindex 7406ea811f..52ede984c2 100644--- a/packages/cli/templates/pages/form-two-column/template.doc.mjs+++ b/packages/cli/templates/pages/form-two-column/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Form (Two-Column)',- displayName: 'Form (Two-Column)',+ name: 'Two-column',+ displayName: 'Two-column',description: 'Hero header with form card layout for data collection',isReady: true,+ category: 'Form - Two-column',};diff --git a/packages/cli/templates/pages/gallery-hero/template.doc.mjs b/packages/cli/templates/pages/gallery-hero/template.doc.mjsindex 20afcee15d..01d72a2175 100644--- a/packages/cli/templates/pages/gallery-hero/template.doc.mjs+++ b/packages/cli/templates/pages/gallery-hero/template.doc.mjs@@ -3,9 +3,11 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Gallery Hero',- displayName: 'Gallery Hero',+ name: 'Hero',+ displayName: 'Hero',description:'Centered headline, description, and CTA buttons above a three-image gallery grid.',isReady: false,+ category: 'Gallery - Hero',+ isHiddenFromOverview: true,};diff --git a/packages/cli/templates/pages/ide/template.doc.mjs b/packages/cli/templates/pages/ide/template.doc.mjsindex 92e9f90ef8..1f40829f6f 100644--- a/packages/cli/templates/pages/ide/template.doc.mjs+++ b/packages/cli/templates/pages/ide/template.doc.mjs@@ -8,4 +8,5 @@ export const doc = {description:'Code editor workspace with file explorer, tabbed editor, terminal panel, and properties sidebar — all resizable and collapsible.',isReady: true,+ category: 'Tools - IDE',};diff --git a/packages/cli/templates/pages/library/template.doc.mjs b/packages/cli/templates/pages/library/template.doc.mjsindex de177b521b..e7d733db23 100644--- a/packages/cli/templates/pages/library/template.doc.mjs+++ b/packages/cli/templates/pages/library/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Library',- displayName: 'Library',+ name: 'Card Grid',+ displayName: 'Card Grid',description: 'Browsable grid of XDS components organized by category with tabs and filters',isReady: true,+ category: 'Content - Card Grid',};diff --git a/packages/cli/templates/pages/login-card/template.doc.mjs b/packages/cli/templates/pages/login-card/template.doc.mjsindex 1fc89187d4..96221fa8d9 100644--- a/packages/cli/templates/pages/login-card/template.doc.mjs+++ b/packages/cli/templates/pages/login-card/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Login (Card)',- displayName: 'Login (Card)',+ name: 'Card',+ displayName: 'Card',description: 'Centered login card with social sign-in and email form',isReady: true,+ category: 'Login - Card',};diff --git a/packages/cli/templates/pages/login-split/template.doc.mjs b/packages/cli/templates/pages/login-split/template.doc.mjsindex fc1e00bacd..51f3e4ede4 100644--- a/packages/cli/templates/pages/login-split/template.doc.mjs+++ b/packages/cli/templates/pages/login-split/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Login (Split)',- displayName: 'Login (Split)',+ name: 'Split',+ displayName: 'Split',description: 'Split-screen login with form and cover image',isReady: true,+ category: 'Login - Split',};diff --git a/packages/cli/templates/pages/login-sso/template.doc.mjs b/packages/cli/templates/pages/login-sso/template.doc.mjsindex 36935be7d0..fb608f06db 100644--- a/packages/cli/templates/pages/login-sso/template.doc.mjs+++ b/packages/cli/templates/pages/login-sso/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Login (SSO)',- displayName: 'Login (SSO)',+ name: 'SSO',+ displayName: 'SSO',description: 'SSO login with email-based provider detection',isReady: true,+ category: 'Login - SSO',};diff --git a/packages/cli/templates/pages/login/template.doc.mjs b/packages/cli/templates/pages/login/template.doc.mjsindex 7a3a6214a1..e34fd00870 100644--- a/packages/cli/templates/pages/login/template.doc.mjs+++ b/packages/cli/templates/pages/login/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Login',- displayName: 'Login',+ name: 'Basic',+ displayName: 'Basic',description: 'Auth form with email and password inputs',isReady: true,+ category: 'Login - Basic',};diff --git a/packages/cli/templates/pages/mixed-gallery/template.doc.mjs b/packages/cli/templates/pages/mixed-gallery/template.doc.mjsindex 971ad7cfe7..c027215c48 100644--- a/packages/cli/templates/pages/mixed-gallery/template.doc.mjs+++ b/packages/cli/templates/pages/mixed-gallery/template.doc.mjs@@ -2,9 +2,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {- name: 'Mixed Gallery',- displayName: 'Mixed Gallery',+ name: 'Mixed',+ displayName: 'Mixed',description: 'Masonry-style image gallery with varying image sizes',type: 'page',isReady: true,+ category: 'Gallery - Mixed',};diff --git a/packages/cli/templates/pages/payment-form/template.doc.mjs b/packages/cli/templates/pages/payment-form/template.doc.mjsindex f5b7cbf1be..73d9371882 100644--- a/packages/cli/templates/pages/payment-form/template.doc.mjs+++ b/packages/cli/templates/pages/payment-form/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Payment Form',- displayName: 'Payment Form',+ name: 'Checkout',+ displayName: 'Checkout',description: 'Secure checkout page with billing info, card details, and order summary.',isReady: true,+ category: 'Form - Checkout',};diff --git a/packages/cli/templates/pages/product-detail/template.doc.mjs b/packages/cli/templates/pages/product-detail/template.doc.mjsindex 85fd204538..fb6e35fd87 100644--- a/packages/cli/templates/pages/product-detail/template.doc.mjs+++ b/packages/cli/templates/pages/product-detail/template.doc.mjs@@ -7,4 +7,5 @@ export const doc = {displayName: 'Product Detail',description: 'Product page with image gallery and collapsible sections',isReady: true,+ category: 'Content - Product Detail',};diff --git a/packages/cli/templates/pages/product-gallery/template.doc.mjs b/packages/cli/templates/pages/product-gallery/template.doc.mjsindex f95f6b3de5..4bab28b8ec 100644--- a/packages/cli/templates/pages/product-gallery/template.doc.mjs+++ b/packages/cli/templates/pages/product-gallery/template.doc.mjs@@ -2,9 +2,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {- name: 'Product Gallery',- displayName: 'Product Gallery',+ name: 'Product',+ displayName: 'Product',description: 'Card grid of products with images, titles, descriptions, and prices',type: 'page',isReady: true,+ category: 'Gallery - Product',};diff --git a/packages/cli/templates/pages/settings-dialog/template.doc.mjs b/packages/cli/templates/pages/settings-dialog/template.doc.mjsindex 4aa0cafe52..88a8f4ad11 100644--- a/packages/cli/templates/pages/settings-dialog/template.doc.mjs+++ b/packages/cli/templates/pages/settings-dialog/template.doc.mjs@@ -3,9 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Settings (Dialog)',- displayName: 'Settings (Dialog)',+ name: 'Dialog',+ displayName: 'Dialog',description:'Account settings in a modal dialog with sidebar navigation and multi-section content',isReady: true,+ category: 'Settings - Dialog',};diff --git a/packages/cli/templates/pages/settings-sidebar/template.doc.mjs b/packages/cli/templates/pages/settings-sidebar/template.doc.mjsindex 0b90676c62..de8ece429a 100644--- a/packages/cli/templates/pages/settings-sidebar/template.doc.mjs+++ b/packages/cli/templates/pages/settings-sidebar/template.doc.mjs@@ -3,9 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Settings (Sidebar)',- displayName: 'Settings (Sidebar)',+ name: 'Sidebar',+ displayName: 'Sidebar',description:'Account settings with sidebar navigation, inline editing, and multi-section privacy controls',isReady: true,+ category: 'Settings - Sidebar',};diff --git a/packages/cli/templates/pages/settings/template.doc.mjs b/packages/cli/templates/pages/settings/template.doc.mjsindex 9c2a7912bb..d7969a18e0 100644--- a/packages/cli/templates/pages/settings/template.doc.mjs+++ b/packages/cli/templates/pages/settings/template.doc.mjs@@ -7,4 +7,5 @@ export const doc = {displayName: 'Settings',description: 'Account settings page with profile, password, and advanced configuration sections',isReady: true,+ category: 'Settings',};diff --git a/packages/cli/templates/pages/side-gallery/template.doc.mjs b/packages/cli/templates/pages/side-gallery/template.doc.mjsindex c1d3ad2d24..2019f47be4 100644--- a/packages/cli/templates/pages/side-gallery/template.doc.mjs+++ b/packages/cli/templates/pages/side-gallery/template.doc.mjs@@ -2,9 +2,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {- name: 'Side Gallery',- displayName: 'Side Gallery',+ name: 'Side',+ displayName: 'Side',description: 'Text and CTA on the left with an image collage on the right',type: 'page',isReady: true,+ category: 'Gallery - Side',};diff --git a/packages/cli/templates/pages/table-grouped/template.doc.mjs b/packages/cli/templates/pages/table-grouped/template.doc.mjsindex 154f0e305b..c92b50b065 100644--- a/packages/cli/templates/pages/table-grouped/template.doc.mjs+++ b/packages/cli/templates/pages/table-grouped/template.doc.mjs@@ -3,8 +3,9 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table (Grouped)',- displayName: 'Table (Grouped)',+ name: 'Grouped',+ displayName: 'Grouped',description: 'Grouped data table with collapsible status sections, PowerSearch, and detail panel',isReady: true,+ category: 'Table - Grouped',};diff --git a/packages/cli/templates/pages/table-page-chart/template.doc.mjs b/packages/cli/templates/pages/table-page-chart/template.doc.mjsindex dd058d65af..bd9e94f760 100644--- a/packages/cli/templates/pages/table-page-chart/template.doc.mjs+++ b/packages/cli/templates/pages/table-page-chart/template.doc.mjs@@ -3,9 +3,11 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table Page (Matcha Store)',- displayName: 'Table Page (Matcha Store)',+ name: 'Chart',+ displayName: 'Chart',description:'Matcha store sales data table with a revenue area chart and product thumbnails.',isReady: true,+ category: 'Table - Chart',+ isHiddenFromOverview: true,};diff --git a/packages/cli/templates/pages/table-page-heatmap-status/template.doc.mjs b/packages/cli/templates/pages/table-page-heatmap-status/template.doc.mjsindex f767ce4b74..d120acd0f9 100644--- a/packages/cli/templates/pages/table-page-heatmap-status/template.doc.mjs+++ b/packages/cli/templates/pages/table-page-heatmap-status/template.doc.mjs@@ -3,9 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table Page (Heatmap Status)',- displayName: 'Table Page (Heatmap Status)',+ name: 'Heatmap',+ displayName: 'Heatmap',description:'Product status page with an outage heatmap and incident log table.',isReady: true,+ category: 'Table - Heatmap',};diff --git a/packages/cli/templates/pages/table-page-shoe-store-heatmap/template.doc.mjs b/packages/cli/templates/pages/table-page-shoe-store-heatmap/template.doc.mjsindex 81cd2535ac..72f2125a75 100644--- a/packages/cli/templates/pages/table-page-shoe-store-heatmap/template.doc.mjs+++ b/packages/cli/templates/pages/table-page-shoe-store-heatmap/template.doc.mjs@@ -3,9 +3,11 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table Page (Chart Shoe Store)',- displayName: 'Table Page (Chart Shoe Store)',+ name: 'Chart',+ displayName: 'Chart',description:'Shoe store sales data table with a revenue area chart and product thumbnails.',isReady: true,+ category: 'Table - Chart',+ isHiddenFromOverview: true,};diff --git a/packages/cli/templates/pages/table-page/template.doc.mjs b/packages/cli/templates/pages/table-page/template.doc.mjsindex fb473ede8a..152d11ef06 100644--- a/packages/cli/templates/pages/table-page/template.doc.mjs+++ b/packages/cli/templates/pages/table-page/template.doc.mjs@@ -3,9 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table Page',- displayName: 'Table Page',+ name: 'Basic',+ displayName: 'Basic',description:'Data table page with power search filtering and action toolbar.',isReady: true,+ category: 'Table - Basic',};diff --git a/packages/cli/templates/pages/table/template.doc.mjs b/packages/cli/templates/pages/table/template.doc.mjsindex 6db617ab89..07752b7778 100644--- a/packages/cli/templates/pages/table/template.doc.mjs+++ b/packages/cli/templates/pages/table/template.doc.mjs@@ -3,8 +3,10 @@/** @type {import('../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'page',- name: 'Table',- displayName: 'Table',+ name: 'Basic',+ displayName: 'Basic',description: 'Data table with actions',isReady: false,+ category: 'Table - Basic',+ isHiddenFromOverview: true,};diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex e380e0108a..48bd2c5502 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -706,6 +706,95 @@ export interface ReferenceTranslationDoc {** The CLI and sandbox import these for discovery and display.*/++/**+ * Functional category for a page template, used to group templates on the+ * docsite Templates overview gallery. Independent of any sidebar/nav grouping.+ *+ * Values follow a `"Group - Variant"` convention (e.g. `"Dashboard - Analytics"`).+ * The overview page derives the group heading from the text before the `" - "`.+ * Standalone values without a hyphen (e.g. `"Settings"`) are their own group.+ *+ * Not every value maps to an existing template — unused values are reserved+ * for future templates so authors get autocomplete for the full taxonomy.+ */+export type TemplateCategory =+ // Dashboard+ | 'Dashboard - Analytics'+ | 'Dashboard - KPI Summary'+ | 'Dashboard - Monitoring'+ | 'Dashboard - Executive Summary'+ | 'Dashboard - Widget Grid'+ | 'Dashboard - Split'+ | 'Dashboard - Tabbed'+ | 'Dashboard - Filterable'+ | 'Dashboard - Portfolio'+ // Table+ | 'Table - Basic'+ | 'Table - Grouped'+ | 'Table - Index/Detail'+ | 'Table - Split Pane'+ | 'Table - Bulk Actions'+ | 'Table - Filtering'+ | 'Table - Tree/Hierarchical List'+ | 'Table - Frozen Column'+ | 'Table - Chart'+ | 'Table - Heatmap'+ // Form+ | 'Form - Basic'+ | 'Form - Page'+ | 'Form - Checkout'+ | 'Form - Two-column'+ | 'Form - Wizard'+ | 'Form - Modal Overlay'+ | 'Form - Side Sheet'+ | 'Form - Inline Edits'+ | 'Form - Settings'+ // Settings+ | 'Settings'+ | 'Settings - Dialog'+ | 'Settings - Sidebar'+ // Login+ | 'Login - Basic'+ | 'Login - Card'+ | 'Login - SSO'+ | 'Login - Split'+ // Tools+ | 'Tools - File Explorer'+ | 'Tools - Page Editor'+ | 'Tools - IDE'+ | 'Tools - Kanban Board'+ | 'Tools - Notebook/Report Page'+ | 'Tools - Diff Compare Viewer'+ | 'Tools - Search Results Page'+ // Content+ | 'Content - Card Grid'+ | 'Content - Order Detail'+ | 'Content - Product Detail'+ | 'Content - Product List'+ | 'Content - Documentation Catalog'+ | 'Content - Documentation Design'+ | 'Content - Documentation Technical'+ | 'Content - Infinite Scroll Page'+ | 'Content - Timeline'+ | 'Content - Profile Page'+ // AI Chat+ | 'AI Chat - Conversation'+ | 'AI Chat - Landing'+ | 'AI Chat - Artifact Page'+ // Gallery+ | 'Gallery - Hero'+ | 'Gallery - Basic'+ | 'Gallery - Mixed'+ | 'Gallery - Side'+ | 'Gallery - Product'+ // Shell+ | 'Shell - Left Sidebar'+ | 'Shell - Top Nav'+ | 'Shell - Top Nav + Left Sidebar'+ | 'Shell - Breadcrumb Driven Layout'+ | 'Shell - Blank';+interface BaseTemplateDoc {/** Identifier name for the template. For block templates this matches* the React component import name (e.g. `"ChatMessageMetadata"`); for@@ -731,6 +820,18 @@ interface BaseTemplateDoc {* Scaffold templates are available via the CLI but hidden from* browsable template galleries like the craft browser. */scaffold?: boolean;++ /** Functional category for the docsite Templates overview gallery.+ * Templates are grouped by the part before `" - "` (e.g. `"Dashboard"`).+ * Independent of CLI discovery, which uses `name`/`description`. */+ category?: TemplateCategory;++ /** Boolean opt-out for templates that shouldn't appear on the Templates+ * overview gallery. The template stays available via the CLI and+ * `xds template <name>` — it's only hidden from the browsable gallery.+ * Use for duplicate/experimental variants. Scaffold templates are+ * hidden automatically and don't need this flag. */+ isHiddenFromOverview?: boolean;}export interface PageTemplateDoc extends BaseTemplateDoc {