Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(cli): enforce two-file template model (page.tsx + template.doc.mjs) (#1268)

Joeyf20e4c281109
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 3594c6ae3e..ee7573c1ee 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -100,6 +100,8 @@ Every response has a `type` string that uniquely identifies it:
| `xds --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |
| `xds --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |
| `xds --json template [--list]` | `template.list` | `TemplateListResponse` |
+| `xds --json template <name>` | `template.show` | `TemplateShowResponse` |
+| `xds --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |
| `xds --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |
| `xds --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |
| `xds --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |
@@ -261,10 +263,23 @@ If the component has no `.doc.mjs`, `xds component {Name}` returns a clean error
### Adding a new template
-1. Add a directory in `packages/cli/templates/{name}/` with a `page.tsx`
-2. Optionally add `template.doc.mjs` for metadata (name, description, isReady)
+Every template is exactly **two files** — no exceptions:
+
+```
+packages/cli/templates/{name}/
+├── page.tsx ← the template code (single self-contained file)
+└── template.doc.mjs ← metadata (name, description, isReady)
+```
+
+1. Create `packages/cli/templates/{name}/page.tsx` with a default-exported React component
+2. Create `packages/cli/templates/{name}/template.doc.mjs` with a `doc` export (`TemplateDoc`)
3. Done — auto-discovered by `xds template --list` and the `template()` API function
+**Rules:**
+- No extra files — no CSS, no images, no other assets. Everything lives in `page.tsx`.
+- Images must use external URLs (e.g. Unsplash), not local imports.
+- All styles must use stylex or inline styles, not separate CSS files.
+
### Adding a new option to an existing API function
1. Add the option to the API function in `src/api/{command}.mjs`
@@ -371,7 +386,7 @@ src/
component.d.ts # ComponentListResponse, ComponentDetailResponse, ...
discover.d.ts # DiscoverListResponse, ...
docs.d.ts # DocsListResponse, ...
- template.d.ts # TemplateListResponse, TemplateCopyResponse
+ template.d.ts # TemplateListResponse, TemplateShowResponse, TemplateSkeletonResponse, TemplateCopyResponse
swizzle.d.ts # SwizzleListResponse, SwizzleCopyResponse
theme.d.ts # ThemeBuildResponse
upgrade.d.ts # UpgradeListResponse, UpgradeRunResponse
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index 7c8e1029bd..724d2aa2cb 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -226,47 +226,34 @@ export async function template(name, options = {}) {
}
const templateDir = path.join(TEMPLATES_DIR, name);
+ const pagePath = path.join(templateDir, 'page.tsx');
const doc = await loadTemplateDoc(templateDir);
- // Show mode: return file contents without writing to disk
+ if (!fs.existsSync(pagePath)) {
+ throw new XDSError(`No page.tsx found for template "${name}"`);
+ }
+
+ // Show mode: return page.tsx content without writing to disk
if (show || !targetPath) {
- const files = fs.readdirSync(templateDir);
- const fileContents = {};
- for (const file of files) {
- if (file === 'template.doc.mjs') continue;
- const srcPath = path.join(templateDir, file);
- if (!fs.statSync(srcPath).isFile()) continue;
- fileContents[file] = fs.readFileSync(srcPath, 'utf-8');
- }
return {
type: 'template.show',
data: {
template: name,
description: doc?.description || '',
- components: extractComponents(path.join(templateDir, 'page.tsx')),
- files: fileContents,
+ components: extractComponents(pagePath),
+ source: fs.readFileSync(pagePath, 'utf-8'),
},
};
}
- // Copy mode: write files to disk
+ // Copy mode: write page.tsx to disk
const outputDir = path.resolve(cwd, targetPath);
fs.mkdirSync(outputDir, {recursive: true});
-
- const files = fs.readdirSync(templateDir);
- let copied = 0;
-
- for (const file of files) {
- if (file === 'template.doc.mjs') continue;
- const srcPath = path.join(templateDir, file);
- if (!fs.statSync(srcPath).isFile()) continue;
- fs.copyFileSync(srcPath, path.join(outputDir, file));
- copied++;
- }
+ fs.copyFileSync(pagePath, path.join(outputDir, 'page.tsx'));
const relOutput = path.relative(cwd, outputDir);
return {
type: 'template.copy',
- data: {template: name, outputDir: relOutput, filesCopied: copied},
+ data: {template: name, outputDir: relOutput, filesCopied: 1},
};
}
diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjs
index 2ab19e450e..49f1b40676 100644
--- a/packages/cli/src/commands/init.mjs
+++ b/packages/cli/src/commands/init.mjs
@@ -90,17 +90,10 @@ async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
}
const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
- const templateDir = path.join(CLI_ROOT, 'templates', templateName);
+ const srcPath = path.join(CLI_ROOT, 'templates', templateName, 'page.tsx');
fs.mkdirSync(outputDir, {recursive: true});
-
- const files = fs.readdirSync(templateDir);
- for (const file of files) {
- const srcPath = path.join(templateDir, file);
- if (fs.statSync(srcPath).isFile()) {
- fs.copyFileSync(srcPath, path.join(outputDir, file));
- }
- }
- console.log(`✓ Template created at ${path.relative(targetDir, outputDir)}/`);
+ fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
+ console.log(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
return;
}
@@ -129,19 +122,12 @@ async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
);
const outputDir = path.resolve(targetDir, targetPath);
- const templateDir = path.join(CLI_ROOT, 'templates', templateChoice);
+ const srcPath = path.join(CLI_ROOT, 'templates', templateChoice, 'page.tsx');
fs.mkdirSync(outputDir, {recursive: true});
+ fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
- const files = fs.readdirSync(templateDir);
- for (const file of files) {
- const srcPath = path.join(templateDir, file);
- if (fs.statSync(srcPath).isFile()) {
- fs.copyFileSync(srcPath, path.join(outputDir, file));
- }
- }
-
- p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/`);
+ p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
}
// ─── Command ─────────────────────────────────────────────────────────────────
diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjs
index 57a109689f..7448c47f52 100644
--- a/packages/cli/src/commands/template.mjs
+++ b/packages/cli/src/commands/template.mjs
@@ -61,15 +61,12 @@ export function registerTemplate(program) {
}
case 'template.show': {
- for (const [filename, content] of Object.entries(result.data.files)) {
- console.log(`// ${filename}`);
- console.log(content);
- }
+ console.log(result.data.source);
break;
}
case 'template.copy': {
- console.log(`\n✓ Copied ${result.data.filesCopied} template files to ${result.data.outputDir}/\n`);
+ console.log(`\n✓ Copied template to ${result.data.outputDir}/page.tsx\n`);
break;
}
}
diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.ts
index b3eb4afff0..4a96a7e407 100644
--- a/packages/cli/src/types/api.d.ts
+++ b/packages/cli/src/types/api.d.ts
@@ -23,7 +23,12 @@ import type {
DiscoverDetailDocResponse,
DiscoverSearchResponse,
} from './discover';
-import type {TemplateListResponse, TemplateCopyResponse} from './template';
+import type {
+ TemplateListResponse,
+ TemplateShowResponse,
+ TemplateSkeletonResponse,
+ TemplateCopyResponse,
+} from './template';
/** Structured API error with optional suggestions. */
export declare class XDSError extends Error {
@@ -102,11 +107,17 @@ export declare function discover(
export interface TemplateOptions {
list?: boolean;
+ skeleton?: boolean;
+ show?: boolean;
targetPath?: string;
cwd?: string;
}
-type TemplateResult = TemplateListResponse | TemplateCopyResponse;
+type TemplateResult =
+ | TemplateListResponse
+ | TemplateShowResponse
+ | TemplateSkeletonResponse
+ | TemplateCopyResponse;
export declare function template(
name?: string,
diff --git a/packages/cli/src/types/template.d.ts b/packages/cli/src/types/template.d.ts
index 30155cab06..75070e3925 100644
--- a/packages/cli/src/types/template.d.ts
+++ b/packages/cli/src/types/template.d.ts
@@ -1,10 +1,14 @@
/**
* Template command JSON responses.
*
+ * Each template is exactly two files: page.tsx (code) + template.doc.mjs (metadata).
+ *
* Invocation -> type discriminator
* ------------------------------------------------------------------
* xds --json template [--list] -> template.list
- * xds --json template <name> [path] -> template.copy
+ * xds --json template <name> -> template.show
+ * xds --json template <name> --skeleton -> template.skeleton
+ * xds --json template <name> [path] -> template.copy
* (unknown template) -> CLIError
*/
@@ -20,6 +24,28 @@ export interface TemplateListEntry {
isReady: boolean;
}
+/** xds --json template <name> */
+export interface TemplateShowResponse {
+ type: 'template.show';
+ data: {
+ template: string;
+ description: string;
+ components: string[];
+ source: string;
+ };
+}
+
+/** xds --json template <name> --skeleton */
+export interface TemplateSkeletonResponse {
+ type: 'template.skeleton';
+ data: {
+ template: string;
+ description: string;
+ components: string[];
+ skeleton: string;
+ };
+}
+
/** xds --json template <name> [path] */
export interface TemplateCopyResponse {
type: 'template.copy';
diff --git a/packages/cli/templates/contact-form/banner.png b/packages/cli/templates/contact-form/banner.png
deleted file mode 100644
index 1593bec780..0000000000
Binary files a/packages/cli/templates/contact-form/banner.png and /dev/null differ
diff --git a/packages/cli/templates/contact-form/page.tsx b/packages/cli/templates/contact-form/page.tsx
index c8f115fabe..6326deb3db 100644
--- a/packages/cli/templates/contact-form/page.tsx
+++ b/packages/cli/templates/contact-form/page.tsx
@@ -12,14 +12,17 @@ import {XDSLink} from '@xds/core/Link';
import {XDSToken} from '@xds/core/Token';
import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';
import {XDSTextArea} from '@xds/core/TextArea';
-import Image from 'next/image';
import {XDSDivider} from '@xds/core/Divider';
-import bannerImg from './banner.png';
-import whyUs1 from './why-us-1.png';
-import whyUs2 from './why-us-2.png';
-import whyUs3 from './why-us-3.png';
import {colorVars, typeScaleVars, fontWeightVars} from '@xds/core/theme/tokens.stylex';
+const BANNER_URL =
+ 'https://images.unsplash.com/photo-1557683316-973673baf926?w=1600&q=80';
+const WHY_US_IMAGES = [
+ 'https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=600&q=80',
+ 'https://images.unsplash.com/photo-1600880292203-757bb62b4baf?w=600&q=80',
+ 'https://images.unsplash.com/photo-1552664730-d307ca884978?w=600&q=80',
+];
+
const CAMPAIGN_GOALS = [
'Brand Awareness',
'Product Sampling',
@@ -51,17 +54,17 @@ const BUDGET_OPTIONS = [
const WHY_US = [
{
- image: whyUs1,
+ image: WHY_US_IMAGES[0],
title: 'We move fast for you',
description: 'We cut through the noise and get straight to the work.',
},
{
- image: whyUs2,
+ image: WHY_US_IMAGES[1],
title: 'We build around you',
description: "We tailor everything to what you're trying to achieve.",
},
{
- image: whyUs3,
+ image: WHY_US_IMAGES[2],
title: 'We show up for you',
description: 'A dedicated team that knows your brand and wants to win.',
},
@@ -140,8 +143,8 @@ export default function FormSimplePage() {
style={{minHeight: '100svh', display: 'flex', flexDirection: 'column'}}>
{/* Full-bleed banner */}
<div style={{width: '100%', maxHeight: '15vh', overflow: 'hidden'}}>
- <Image
- src={bannerImg}
+ <img
+ src={BANNER_URL}
alt="Decorative banner"
style={{width: '100%', height: '100%', objectFit: 'cover', objectPosition: 'center'}}
/>
@@ -173,7 +176,7 @@ export default function FormSimplePage() {
<div style={{display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 16}}>
{WHY_US.map(item => (
<XDSVStack key={item.title} gap={3}>
- <Image
+ <img
src={item.image}
alt={item.title}
style={{width: '100%', height: 'auto', objectFit: 'cover', borderRadius: 8}}
diff --git a/packages/cli/templates/contact-form/why-us-1.png b/packages/cli/templates/contact-form/why-us-1.png
deleted file mode 100644
index bece78478a..0000000000
Binary files a/packages/cli/templates/contact-form/why-us-1.png and /dev/null differ
diff --git a/packages/cli/templates/contact-form/why-us-2.png b/packages/cli/templates/contact-form/why-us-2.png
deleted file mode 100644
index acb6588bc5..0000000000
Binary files a/packages/cli/templates/contact-form/why-us-2.png and /dev/null differ
diff --git a/packages/cli/templates/contact-form/why-us-3.png b/packages/cli/templates/contact-form/why-us-3.png
deleted file mode 100644
index 9a945c751d..0000000000
Binary files a/packages/cli/templates/contact-form/why-us-3.png and /dev/null differ
diff --git a/packages/cli/templates/form-two-column/form-two-column.css b/packages/cli/templates/form-two-column/form-two-column.css
deleted file mode 100644
index ae3e33843f..0000000000
--- a/packages/cli/templates/form-two-column/form-two-column.css
+++ /dev/null
@@ -1,73 +0,0 @@
-.ftc-page {
- background-color: var(--color-background-surface);
- display: flex;
- align-items: center;
- justify-content: center;
- min-height: 100svh;
- padding: 48px;
-}
-.ftc-inner {
- max-width: 1100px;
- width: 100%;
- display: flex;
- flex-direction: column;
- gap: 56px;
-}
-.ftc-top-grid {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 80px;
- align-items: center;
-}
-.ftc-headline {
- font-size: 48px;
- font-weight: 700;
- line-height: 1.05;
- letter-spacing: -0.03em;
- margin: 0;
-}
-.ftc-image {
- width: 85%;
- aspect-ratio: 4 / 3;
- display: flex;
- align-items: center;
- justify-content: center;
- border-radius: 12px;
- overflow: hidden;
-}
-.ftc-inline-grid {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 12px;
-}
-.ftc-footer-grid {
- display: grid;
- grid-template-columns: 1fr 1fr 1fr;
- gap: 32px;
- padding-top: 32px;
- text-align: center;
-}
-.ftc-footer-label {
- text-transform: uppercase;
- letter-spacing: 0.08em;
-}
-@media (max-width: 767px) {
- .ftc-page {
- padding: 20px;
- align-items: flex-start;
- }
- .ftc-top-grid {
- grid-template-columns: 1fr;
- gap: 32px;
- }
- .ftc-image {
- width: 100%;
- }
- .ftc-footer-grid {
- grid-template-columns: 1fr;
- text-align: left;
- }
- .ftc-inline-grid {
- grid-template-columns: 1fr;
- }
-}
diff --git a/packages/cli/templates/form-two-column/illustration.png b/packages/cli/templates/form-two-column/illustration.png
deleted file mode 100644
index 9f26238f3b..0000000000
Binary files a/packages/cli/templates/form-two-column/illustration.png and /dev/null differ
diff --git a/packages/cli/templates/form-two-column/page.tsx b/packages/cli/templates/form-two-column/page.tsx
index b6d50dd3b2..981aa5b824 100644
--- a/packages/cli/templates/form-two-column/page.tsx
+++ b/packages/cli/templates/form-two-column/page.tsx
@@ -12,10 +12,10 @@ import {XDSLink} from '@xds/core/Link';
import {XDSDivider} from '@xds/core/Divider';
import {XDSCard} from '@xds/core/Card';
import {XDSSelector} from '@xds/core/Selector';
-import Image from 'next/image';
-import illustrationSrc from './illustration.png';
import {colorVars, spacingVars, radiusVars} from '@xds/core/theme/tokens.stylex';
-import './form-two-column.css';
+
+const ILLUSTRATION_URL =
+ 'https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800&q=80';
// ─────────────────────────────────────────────────────────────
// Constants
@@ -47,16 +47,64 @@ const CONTACT_COLUMNS = [
];
// ─────────────────────────────────────────────────────────────
-// Styles — tokens for colors, radius, spacing only
-// Grid layout lives in form-two-column.css
+// Styles
// ─────────────────────────────────────────────────────────────
const styles = stylex.create({
+ page: {
+ backgroundColor: colorVars['--color-background-surface'],
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ minHeight: '100svh',
+ padding: 48,
+ },
+ inner: {
+ maxWidth: 1100,
+ width: '100%',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 56,
+ },
+ topGrid: {
+ display: 'grid',
+ gridTemplateColumns: '1fr 1fr',
+ gap: 80,
+ alignItems: 'center',
+ },
+ headline: {
+ fontSize: 48,
+ fontWeight: 700,
+ lineHeight: 1.05,
+ letterSpacing: '-0.03em',
+ margin: 0,
+ },
imagePlaceholder: {
backgroundColor: colorVars['--color-background-surface'],
borderRadius: radiusVars['--radius-container'],
overflow: 'hidden',
alignSelf: 'flex-start',
+ width: '85%',
+ aspectRatio: '4 / 3',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+ inlineGrid: {
+ display: 'grid',
+ gridTemplateColumns: '1fr 1fr',
+ gap: 12,
+ },
+ footerGrid: {
+ display: 'grid',
+ gridTemplateColumns: '1fr 1fr 1fr',
+ gap: 32,
+ paddingTop: 32,
+ textAlign: 'center',
+ },
+ footerLabel: {
+ textTransform: 'uppercase',
+ letterSpacing: '0.08em',
},
tokenWrap: {
display: 'flex',
@@ -68,6 +116,29 @@ const styles = stylex.create({
},
});
+const mobileStyles = stylex.create({
+ page: {
+ padding: 20,
+ alignItems: 'flex-start',
+ },
+ topGrid: {
+ gridTemplateColumns: '1fr',
+ gap: 32,
+ },
+ image: {
+ width: '100%',
+ },
+ footerGrid: {
+ gridTemplateColumns: '1fr',
+ textAlign: 'left',
+ },
+ inlineGrid: {
+ gridTemplateColumns: '1fr',
+ },
+});
+
+const MOBILE = '@media (max-width: 767px)' as const;
+
// ─────────────────────────────────────────────────────────────
// Page
// ─────────────────────────────────────────────────────────────
@@ -103,16 +174,16 @@ export default function FormTwoColumnPage() {
const handleSubmit = () => setSubmitted(true);
return (
- <div className="ftc-page">
- <div className="ftc-inner">
+ <div {...stylex.props(styles.page)}>
+ <div {...stylex.props(styles.inner)}>
{/* ── Top: two-column ── */}
- <div className="ftc-top-grid">
+ <div {...stylex.props(styles.topGrid)}>
{/* Left: headline + description + illustration */}
<XDSVStack gap={6}>
<XDSVStack gap={3}>
- <div className="ftc-headline">
+ <div {...stylex.props(styles.headline)}>
Let&apos;s work together
</div>
<XDSText type="body" color="secondary">
@@ -120,9 +191,9 @@ export default function FormTwoColumnPage() {
figure out the best path forward.
</XDSText>
</XDSVStack>
- <div className="ftc-image" {...stylex.props(styles.imagePlaceholder)}>
- <Image
- src={illustrationSrc}
+ <div {...stylex.props(styles.imagePlaceholder)}>
+ <img
+ src={ILLUSTRATION_URL}
alt="Illustration"
style={{width: '100%', height: '100%', objectFit: 'contain'}}
/>
@@ -141,7 +212,7 @@ export default function FormTwoColumnPage() {
onChange={setFullName}
status={errors.fullName ? {type: 'error', message: errors.fullName} : undefined}
/>
- <div className="ftc-inline-grid">
+ <div {...stylex.props(styles.inlineGrid)}>
<XDSTextInput
label="Email"
isLabelHidden
@@ -158,7 +229,7 @@ export default function FormTwoColumnPage() {
onChange={setCompany}
/>
</div>
- <div className="ftc-inline-grid">
+ <div {...stylex.props(styles.inlineGrid)}>
<XDSTextInput
label="Job title"
isLabelHidden
@@ -220,11 +291,11 @@ export default function FormTwoColumnPage() {
{/* ── Bottom: contact strip ── */}
<div>
<XDSDivider />
- <div className="ftc-footer-grid">
+ <div {...stylex.props(styles.footerGrid)}>
{CONTACT_COLUMNS.map(col => (
<XDSVStack key={col.label} gap={1} hAlign="center">
<XDSText type="supporting" color="secondary">
- <span className="ftc-footer-label">{col.label}</span>
+ <span {...stylex.props(styles.footerLabel)}>{col.label}</span>
</XDSText>
<XDSLink
label={col.email}