Skip to content

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

TypeScript
10.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */

export const docs = {
  name: 'getting-started',
  title: 'Getting Started',
  category: 'guide',
  description: 'Add the design system to your project and start building.',
  keywords: ['quick start', 'setup', 'install'],

  sections: [
    {
      title: 'Quick Start with AI',
      content: [
        {
          type: 'prose',
          text: 'Paste this into your AI coding tool and let it handle the setup:',
        },
        {
          type: 'code',
          lang: 'text',
          label: 'Set up the design system',
          code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `{@command init}` to set up agent docs. Read the generated files to learn the conventions.',
        },
        {
          type: 'prose',
          text: 'Then give it a look. Every app gets a theme whether or not anyone picks one, so it is worth one question at setup rather than revisiting screens later that were built around the wrong look:',
        },
        {
          type: 'code',
          lang: 'text',
          label: 'Give it a look',
          code: 'Ask me what look and feel this app should have. Run `{@command theme list}`, install the closest theme package, and run `theme add <slug>`; use `--package` when owners share a slug. Import `themes` and `defaultThemeSlug` from the generated module once and pass `themes[defaultThemeSlug]` to `<Theme>`. Customize with `defineTheme({extends: importedTheme, ...})`. Use `theme eject` only when I ask for an independent source fork. Default to neutral if I have no preference, and show me the result before moving on.',
        },
      ],
    },
    {
      title: 'Install',
      content: [
        {
          type: 'prose',
          text: 'Astryx requires React 19 or later: `react` and `react-dom` >= 19.0.0 are peer dependencies of `@astryxdesign/core`.',
        },
        {
          type: 'prose',
          text: 'Add the core package and its `@stylexjs/stylex` peer dependency, plus a theme and the CLI.',
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Terminal',
          code: `{@pm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/cli}`,
        },
        {
          type: 'prose',
          text: "Then run `{@command init}` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive; no prompts; so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.",
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Terminal',
          code: `{@command init}`,
        },
      ],
    },
    {
      id: 'upgrade',
      title: 'Upgrade',
      content: [
        {
          type: 'prose',
          text: 'Upgrade every Astryx package your app lists in one command, to the same release. Each theme names the exact Core release it works with, so a theme left on an older release no longer matches the new Core.',
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Terminal',
          code: `{@pm install @astryxdesign/core@latest @astryxdesign/theme-neutral@latest @astryxdesign/cli@latest}\n{@command upgrade --from <old Core version> --apply}`,
        },
        {
          type: 'prose',
          text: "Add every other Astryx package your app lists to the same command, and pass the Core version you had before to `--from`. If your package manager holds new releases back, exempt the whole `@astryxdesign/*` scope; in pnpm, `minimumReleaseAgeExclude: ['@astryxdesign/*']`. Exempting only some of its packages installs packages from different releases side by side.",
        },
      ],
    },
    {
      id: 'install-once',
      title: 'Install once, use everywhere',
      content: [
        {
          type: 'prose',
          text: "Install the CLI once for your computer too, and the astryx command works in any folder, for you and for any coding agent, even before a project exists. Inside a project, the project's own version still answers, so a global install never changes what your team and CI get. Keep it in the project as well; that is the recommended setup.",
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Terminal',
          code: `{@pm install @astryxdesign/cli --global}`,
        },
        {
          type: 'prose',
          text: 'Project, global, or both: {@link generic:project-global-or-both}. Everything else about global mode: {@link namespace:global}.',
        },
      ],
    },
    {
      title: 'Add base CSS and a theme',
      content: [
        {
          type: 'prose',
          text: 'Import the reset and base styles in your global CSS. Then run `{@command theme add neutral}`; the generated app module imports the theme’s production CSS and font CSS.',
        },
        {
          type: 'code',
          lang: 'css',
          label: 'globals.css',
          code: `@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';`,
        },
        {
          type: 'prose',
          text: 'Run `{@command theme list}` to see every theme.',
        },
        {
          type: 'code',
          lang: 'tsx',
          label: 'App root',
          code: `import {Theme} from '@astryxdesign/core/theme';
import {themes, defaultThemeSlug} from './astryx-themes';

<Theme theme={themes[defaultThemeSlug]}><App /></Theme>`,
        },
        {
          type: 'list',
          style: 'unordered',
          items: [
            '`@astryxdesign/theme-neutral`: muted and minimal; a good starting point',
            '`@astryxdesign/theme-butter`: warm, golden tones with blue accents',
            '`@astryxdesign/theme-chocolate`: rich chocolate and caramel tones',
            '`@astryxdesign/theme-gothic`: dark-only theme with ink and noir influences',
            '`@astryxdesign/theme-matcha`: earthy greens and botanical tones',
            '`@astryxdesign/theme-stone`: warm neutrals inspired by sandstone',
            '`@astryxdesign/theme-y2k`: playful early-2000s pop aesthetic',
          ],
        },
        {
          type: 'prose',
          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of {@link generic:migration-setup}.',
        },
        {
          type: 'prose',
          text: 'Run {@link generic:use-a-theme} for the full theming guide.',
        },
      ],
    },
    {
      title: 'Add your first component',
      content: [
        {
          type: 'prose',
          text: 'Import each component from its own entry, the path `{@command component <Name>}` prints. This keeps bundles small and makes intent clear.',
        },
        {
          type: 'code',
          lang: 'tsx',
          label: 'app/page.tsx',
          code: `import {Button} from '@astryxdesign/core/Button';
import {VStack} from '@astryxdesign/core/VStack';

export default function Page() {
  return (
    <VStack gap={2}>
      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
    </VStack>
  );
}`,
        },
      ],
    },
    {
      title: 'Customize with StyleX',
      content: [
        {
          type: 'prose',
          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link namespace:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
        },
        {
          type: 'code',
          lang: 'tsx',
          label: 'Style overrides',
          code: `import * as stylex from '@stylexjs/stylex';

const overrides = stylex.create({
  save: { alignSelf: 'flex-end', marginTop: 16 },
});

<Button label="Save" xstyle={overrides.save} />`,
        },
      ],
    },
    {
      title: 'Example Apps',
      content: [
        {
          type: 'prose',
          text: 'For a full working project, clone one of the example apps from the repo. These are complete setups with routing, theming, and components wired together.',
        },
        {
          type: 'table',
          headers: ['Example', 'Stack', 'Path'],
          rows: [
            [
              'Next.js',
              'Next.js + theme CSS',
              '[apps/example-nextjs](https://github.com/meta/astryx/tree/main/apps/example-nextjs)',
            ],
            [
              'Next.js + StyleX',
              'Next.js + StyleX for custom styles',
              '[apps/example-nextjs-stylex](https://github.com/meta/astryx/tree/main/apps/example-nextjs-stylex)',
            ],
            [
              'Next.js + Tailwind',
              'Next.js + Tailwind bridge',
              '[apps/example-nextjs-tailwind](https://github.com/meta/astryx/tree/main/apps/example-nextjs-tailwind)',
            ],
            [
              'Vite + Tailwind',
              'Vite + Tailwind bridge',
              '[apps/example-vite-tailwind](https://github.com/meta/astryx/tree/main/apps/example-vite-tailwind)',
            ],
          ],
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Clone and run an example',
          code: `git clone https://github.com/meta/astryx.git
cd astryx/apps/example-nextjs
{@pm install}
{@pm run dev}`,
        },
      ],
    },
    {
      title: 'Explore the CLI',
      content: [
        {
          type: 'prose',
          text: 'The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:',
        },
        {
          type: 'code',
          lang: 'json',
          label: 'package.json',
          code: `"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}`,
        },
        {
          type: 'prose',
          text: "Then discover what's available:",
        },
        {
          type: 'code',
          lang: 'bash',
          label: 'Terminal',
          code: `{@command component}          # list all components
{@command component Button}   # props, usage, theming for Button
{@command docs}               # list all doc topics
{@command template --list}    # available page templates
{@command docs tokens}        # spacing, color, radius reference`,
        },
      ],
    },
  ],
};