Skip to content

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

TypeScript

docs(cli): the custom themes guide names a local theme's files (#10347)

Joey44a0c628bd28
diff --git a/.changeset/local-theme-descriptor.md b/.changeset/local-theme-descriptor.md
new file mode 100644
index 0000000000..f298407601
--- /dev/null
+++ b/.changeset/local-theme-descriptor.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] The custom theme guide names the files of a local theme, including the same-stem descriptor `theme add` reads.
+
+@josephfarina
diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjs
index 6c084752ed..1db1646591 100644
--- a/packages/cli/assets/docs/author-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs
@@ -15,6 +15,8 @@ export const docs = {
title: 'Custom themes',
content: [
{type: 'prose', text: "Use an installed built theme as the base for ordinary customization. Import it into your source and pass it as `extends` to `defineTheme({extends: importedTheme, ...})`. Build the result, then add the local slug. Only eject when you need to own and maintain a full source fork."},
+ {type: 'prose', text: "A local theme is a folder in `src/themes/<slug>/` holding a `<name>Theme.ts` source that exports `<name>Theme`, and a same-stem `<name>Theme.doc.mjs` descriptor that `theme add` reads. The stem must be a valid export name, so a hyphenated slug drops the hyphen: `brand-dark` lives in `src/themes/brand-dark/brandDarkTheme.ts` exporting `brandDarkTheme`, beside `brandDarkTheme.doc.mjs`. The descriptor's `name` is the folder's slug, and it must declare its type or `theme add` and `theme list` refuse it. {@command docs authoring theme-doc} lists every field."},
+ {type: 'code', lang: 'js', label: 'src/themes/brand-dark/brandDarkTheme.doc.mjs', code: "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n type: 'theme',\n name: 'brand-dark',\n displayName: 'Brand Dark',\n description: 'The brand accent, tuned for dark mode.',\n maintained: false,\n};"},
{type: 'code', lang: 'bash', label: 'Add to use, eject to fork', code: '{@command theme list}\n{@command theme add stone}\n{@command theme eject stone}\n{@command theme build src/themes/stone/stoneTheme.ts}\n{@command theme add stone}'},
{type: 'prose', text: "For an annotated map of the whole surface (every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference), run `{@command theme template}`. It writes `theme.template.ts` into your project to read and copy from (`{@command init --features theme}` writes it as part of project setup)."},
{type: 'prose', text: 'To apply a theme you created, see {@link generic:use-a-theme}. To generate colors from seed values, see the Palette section below. Before you eject a package theme instead, see when that fits in {@link generic:use-a-theme}.'},
diff --git a/packages/cli/test/__golden__/no-icon-set/docs-topics.json b/packages/cli/test/__golden__/no-icon-set/docs-topics.json
index e5953890a6..205d92ef48 100644
--- a/packages/cli/test/__golden__/no-icon-set/docs-topics.json
+++ b/packages/cli/test/__golden__/no-icon-set/docs-topics.json
@@ -103,7 +103,7 @@
"token-utilities",
"usetheme-hook"
],
- "skeleton": "9d5b6d6c228d6f569726bc06c61eaac8fbe073ff28d1d8b2d33ad4c5644188b8",
+ "skeleton": "11dd50b9d1b4ab0d08622c70d90634a9848d91fea3ed0eb3aad5845d120a1042",
"mentions": []
},
"browser-support": {