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.mdindex 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 function1. 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, TemplateCopyResponseswizzle.d.ts # SwizzleListResponse, SwizzleCopyResponsetheme.d.ts # ThemeBuildResponseupgrade.d.ts # UpgradeListResponse, UpgradeRunResponsediff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjsindex 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 diskif (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 diskconst 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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.pngdeleted file mode 100644index 1593bec780..0000000000Binary files a/packages/cli/templates/contact-form/banner.png and /dev/null differdiff --git a/packages/cli/templates/contact-form/page.tsx b/packages/cli/templates/contact-form/page.tsxindex 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+ <imgsrc={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.pngdeleted file mode 100644index bece78478a..0000000000Binary files a/packages/cli/templates/contact-form/why-us-1.png and /dev/null differdiff --git a/packages/cli/templates/contact-form/why-us-2.png b/packages/cli/templates/contact-form/why-us-2.pngdeleted file mode 100644index acb6588bc5..0000000000Binary files a/packages/cli/templates/contact-form/why-us-2.png and /dev/null differdiff --git a/packages/cli/templates/contact-form/why-us-3.png b/packages/cli/templates/contact-form/why-us-3.pngdeleted file mode 100644index 9a945c751d..0000000000Binary files a/packages/cli/templates/contact-form/why-us-3.png and /dev/null differdiff --git a/packages/cli/templates/form-two-column/form-two-column.css b/packages/cli/templates/form-two-column/form-two-column.cssdeleted file mode 100644index 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.pngdeleted file mode 100644index 9f26238f3b..0000000000Binary files a/packages/cli/templates/form-two-column/illustration.png and /dev/null differdiff --git a/packages/cli/templates/form-two-column/page.tsx b/packages/cli/templates/form-two-column/page.tsxindex 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'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)}><XDSTextInputlabel="Email"isLabelHidden@@ -158,7 +229,7 @@ export default function FormTwoColumnPage() {onChange={setCompany}/></div>- <div className="ftc-inline-grid">+ <div {...stylex.props(styles.inlineGrid)}><XDSTextInputlabel="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><XDSLinklabel={col.email}