// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export const docs = {
name: 'use-a-theme',
title: 'Use a theme',
category: 'guide',
keywords: ['theme', 'Theme', 'dark mode', 'light', 'nested', 'provider', 'SSR', 'built', 'runtime', 'neutralTheme', 'available themes', 'theme add', 'import', 'astryx-themes', 'eject'],
description:
'Apply a theme to your app: install, import with the CLI, wire the generated module, switch dark mode, nest themes, and choose runtime or built for production.',
sections: [
{
id: 'quick-start',
title: 'Wrap your app in a theme',
content: [
{
type: 'code',
lang: 'bash',
label: 'Install and add a theme',
code: '{@pm install @astryxdesign/theme-neutral}\n{@command theme add neutral}',
},
{
type: 'code',
lang: 'tsx',
label: 'Wire the generated module once',
code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n \n \n \n );\n}",
},
{
type: 'code',
lang: 'tsx',
label: 'Switch among added themes',
code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState('neutral');\nconst app = ;",
},
{
type: 'prose',
text: '`theme add` records an installed package theme and regenerates `src/astryx-themes.ts` or `.js` with its built module, production CSS, and optional font CSS. In a project without `src`, the module is at the project root. The first imported theme becomes the default. `theme use ` changes that default, and `theme remove ` removes a non-default theme.',
},
{
type: 'prose',
text: 'Customize a package theme with `defineTheme({extends: importedTheme, ...})`, then build and add that local theme. Use `theme eject` only when you want an independent source fork that no longer receives the package owner\'s updates. For the full authoring guide, see {@link generic:author-a-theme}.',
},
],
},
{
title: 'Migrating Earlier Theme Copies',
content: [
{
type: 'prose',
text: 'A theme copied by the released `theme add` stays app source. The upgrade does not move, delete, or rewrite it. It only writes the missing same-stem descriptor with `maintained: false`, so the copy becomes a local theme.',
},
{
type: 'code',
lang: 'bash',
label: 'Add descriptors to earlier copies',
code: '{@command upgrade --from 0.6.4 --path . --apply}',
},
{
type: 'prose',
text: 'Before the upgrade runs, theme commands skip a descriptor-less copy in `src/themes`. `theme list` and doctor name it as unmigrated and show the upgrade command. A script that meant to copy source now runs `theme eject` with the same arguments. A script that meant to make the app use a theme runs `theme add`.',
},
{
type: 'prose',
text: '`ASTRYX_THEME` is no longer read. Run `theme add ` and `theme use ` to choose the default in a generated app theme module. When that module exists, component metadata reads its recorded default theme. Without the module, the released `package.json#astryx.theme` lookup keeps its meaning.',
},
],
},
{
title: 'Available Themes',
content: [
{
type: 'prose',
text: 'Install the theme package you want with `{@pm install @astryxdesign/theme-}`, then import its slug with `theme add `. The CLI imports the package\'s built outputs for you.',
},
{
type: 'table',
headers: ['Theme', 'Add command', 'Description'],
rows: [
['Neutral', '{@command theme add neutral}', 'Muted, minimal aesthetic with Figtree typography. A good starting point.'],
['Butter', 'astryx theme add butter', 'Golden, buttery surfaces with blue accents; Sarina + Outfit type.'],
['Chocolate', 'astryx theme add chocolate', 'Warm brown tones and cozy beige; Fraunces + Albert Sans type.'],
['Gothic', 'astryx theme add gothic', 'Dark-only atmospheric theme; deep blue-gray surfaces, distressed display type.'],
['Matcha', 'astryx theme add matcha', 'Earthy greens; DM Sans + Playwrite US Trad type.'],
['Stone', 'astryx theme add stone', 'Warm stone and slate tones; Montserrat + Figtree type.'],
['Y2K', 'astryx theme add y2k', 'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.'],
],
},
{
type: 'prose',
text: 'Every first-party package exports its built theme at `@astryxdesign/theme-{name}/built`, production CSS at `/theme.css`, and font loading CSS at `/fonts.css`. `theme add` writes those imports into the generated app module.',
},
],
},
{
title: 'Theme Props',
content: [
{
type: 'prose',
text: "`` takes `theme` (required), `mode` (`'system'` by default, or `'light'`/`'dark'`), and `children`. For every prop, run `{@command component Theme}`.",
},
],
},
{
id: 'integration-themes',
title: 'Using a Theme from an Integration',
content: [
{
type: 'prose',
text: 'Install the integration as a direct dependency. Astryx discovers its themes and guides without an `astryx.config` entry. A theme can be added only when the installed package exports its built module and production stylesheet.',
},
{
type: 'code',
lang: 'bash',
label: 'Install, inspect, and add',
code: '{@pm install @astryxdesign/core @acme/brand-integration}\n{@command theme list --package @acme/brand-integration}\n{@command docs brand-theme}\n{@command theme add ocean --package @acme/brand-integration}',
},
{
type: 'prose',
text: '`theme add` keeps the owner package in the app record and imports its built module, stylesheet, and optional font stylesheet. Package updates continue to reach the app. Run `theme eject ocean --package @acme/brand-integration` only to copy the source and descriptor into `src/themes/ocean` as an independent local fork.',
},
],
},
{
id: 'light-dark-mode',
title: 'Dark mode',
content: [
{
type: 'prose',
text: "Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference.",
},
{
type: 'code',
lang: 'tsx',
label: 'Light/dark tuple',
code: "'--color-accent': ['#0064E0', '#2694FE'],\n// ^light ^dark",
},
{
type: 'code',
lang: 'tsx',
label: 'Toggle with a button',
code: "const [mode, setMode] = useState<'light' | 'dark'>('light');\n\n\n ;",
},
{
type: 'prose',
text: 'To create a theme with custom dark mode colors, see {@link generic:author-a-theme}.',
},
],
},
{
id: 'nesting-themes',
title: 'Nested themes',
content: [
{
type: 'prose',
text: 'Wrap different sections in separate `` providers.',
},
{
type: 'code',
lang: 'tsx',
label: 'Dark sidebar with light content',
code: "\n ...}\n start={\n \n {/* Dark sidebar */}\n \n }\n content={{/* Light content */}}\n />\n",
},
],
},
{
title: 'Runtime vs Built Themes',
content: [
{
type: 'prose',
text: 'Themes work in two modes:',
},
{
type: 'table',
headers: ['', 'Runtime (source)', 'Built'],
rows: [
['Import (published theme)', '@astryxdesign/theme-{name}', '@astryxdesign/theme-{name}/built + theme.css'],
['Import (custom theme)', 'defineTheme() directly', 'Built .js + .css from `{@command theme build}`'],
['How it works', 'useInsertionEffect injects