// 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 setMode(m => (m === 'light' ? 'dark' : 'light'))}\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