# Getting started

> Accessible, native-first Astro components you copy into your project and own.

URL: https://apogee.avaui.dev/docs
Last updated: 2026-10-21

Accessible, native-first Astro components you copy into your project and own.

Last updated October 21, 2026

**Apogee** is the AVA design system for Astro: accessible, responsive components with **zero external JavaScript**, copied into your project so you own the code.

```astro
<Button>Get started</Button>
<Button variant="outline" color="neutral">Docs</Button>
```

## New project

One command makes a new Astro site with Apogee set up:

```sh
npx @ava-ui/apogee create my-site
cd my-site && npm run dev
```

It runs `create-astro` for the latest Astro and Tailwind, installs Lucide, adds the Apogee tokens to `src/styles/global.css` and writes a starter page with a Button. You need a Node version the latest Astro supports; if Tailwind can’t be added, `create` stops and says what to run.

## Existing project

Add Tailwind v4 first (`npx astro add tailwind`), then:

```sh
npx @ava-ui/apogee init                 # tokens + config, added to your Tailwind stylesheet
npx @ava-ui/apogee add button dialog    # copies components (+ their deps)
npx @ava-ui/apogee list                 # all available components
npx @ava-ui/apogee diff                 # your copies vs the package, line by line
npx @ava-ui/apogee update               # take package changes for files you haven't edited
```

`add` resolves dependencies for you and prints any npm packages to install. Files land in `src/components/apogee/`, yours to edit. Sections, blocks and whole pages are added the same way; see the **Sections** groups in the sidebar.

## Use

```astro
---
import Button from '../components/apogee/Button/Button.astro'
---
<Button>Get started</Button>
```

## Principles

-   **Accessible** — keyboard, ARIA, visible focus, `prefers-reduced-motion`.
-   **Native-first** — `<details>`, `<dialog>`, popover, real form controls. JS only when the platform can’t do it, then as a progressive-enhancement island.
-   **Token-driven** — every value reads a semantic token; theming and dark mode are a token override. Contrast is an enforced AA gate.
-   **RTL-ready** — logical properties throughout.