Skip to content

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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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 {