--- name: demo-pages description: >- Build or update a Tabler demo page under `preview/pages/*.astro` — the pages that show a component's variants side by side. Use whenever the user asks to add, extend, or clean up a preview/demo page, and on your own after adding a new `shared/ui` component that has no page showing it. Covers the page skeleton, the header (title, description, docs link, actions), the card grid, heading levels, and how to verify the result in the browser. --- # Write a Tabler demo page Demo pages live in `preview/pages/*.astro` and are served at `/` in dev, `/.html` in the build. Each one shows the variants of a single component so a reader can compare them at a glance. They are not documentation — the prose is one line per card; the depth lives in `docs/content/**` (see the `write-docs` skill). ## 1. Page skeleton ```astro --- import DefaultLayout from '@shared/layouts/DefaultLayout.astro' import Card from '@ui/Card.astro' import CardBody from '@ui/CardBody.astro' import CardTitle from '@ui/CardTitle.astro' import CardSubtitle from '@ui/CardSubtitle.astro' import DocsLink from '@ui/DocsLink.astro' ---

Basic One sentence on what this variant is for. …

``` - `title` — browser title. It also becomes the page header, so **do not repeat it in a `pageHeader` prop**; `pageHeader` exists only for a header that differs from the browser title (`title="Dashboard" pageHeader="Boxed layout"`), or as `pageHeader={false}` for a page with no header at all. - `description` — renders under the page title *and* fills ``. One sentence, present tense, says what the component is for. - `pageMenu` — the menu entry to highlight, e.g. `base.badges`. Match an existing key in `shared/data/menu.json`. - Never hand-roll a title block inside the page body. The page header is the layout's job. ## 2. Page header extras Anything to the right of the title goes in the `page-header-actions` slot, as a direct child of ``: ```astro ``` - **Docs link:** `path` is the page's path under `docs/content/**` without the extension — `docs/content/ui/components/badge.mdx` → `/ui/components/badge`. Add one whenever a matching docs page exists. - **Check the path with `pnpm run check-docs-links`.** It resolves every `` against `docs/content/**` and fails on a typo, so you do not need a browser for this. - If you do open the link, use `docs-dev.tabler.io`, which serves `dev`. `docs.tabler.io` serves the last release and still has the pre-content-collection urls, so a valid page can 404 there. A 404 on production alone is never a reason to change a path. - **Prebuilt action groups** (`HeaderActionsButtons`, `HeaderActionsPrint`, `HeaderActionsPhotos`, …) live in `shared/components/layout/` and go in the same slot: ``. There is no `actions="buttons"` prop any more. ## 3. Card grid - One card per variant, in `

` with `col-*` wrappers. Keep column widths consistent down the page. - `CardTitle` names the variant in 1-3 words. `CardSubtitle` explains it in one sentence, naming the prop or class it demonstrates: "Add `showClose` to let users close the alert." - Put the class or prop in `

` inside the subtitle. Readers scan for the token.
- Never write `` or `` by hand — use the components, which also keep the heading level right.

## 4. Heading levels

`CardTitle` and `CardHeader` render `h2`, directly under the page `h1`. Pass `as="h3"` only for a card nested under its own `h2` section heading. Do not introduce raw ``/`
` headings for card titles; that is what made pages mix levels before.

## 5. Spacing between inline elements

Use the list wrappers instead of margin utilities on each child:

| Wrapper | For |
| --- | --- |
| `` | rows of buttons |
| `` | rows of badges |
| `` | rows of tags |
| `` | rows or stacks of avatars |

The pluralised class names (`.badges-list`, `.tags-list`) are deprecated aliases of `.badge-list` / `.tag-list`. Do not add `me-2`/`mb-2` to individual items.

Icon action buttons: `btn-action` is always combined with `btn` (`btn btn-action`, plus `btn-sm` when small) — never use `btn-action` on its own.

## 6. Data and repetition

- Loop over `shared/data/*.json` (`site.json` colors, `people.json`, `flags.json`) instead of pasting 20 near-identical blocks.
- Cast JSON entries to a named type in the frontmatter when you index into them; `astro check` is part of the quality gates.

## 7. Registering the page

- Add the page to `shared/data/menu.json` so it is reachable, and use the same key in `pageMenu`.
- A new `shared/ui` component usually needs both a demo page and a docs page. After finishing here, check `docs/content/**` and consult the `write-docs` skill if it is missing.

## 8. Verify in the browser

Never hand the page to the user unchecked.

1. `preview_start` with the `preview` config from `.claude/launch.json`, then open `/`.
2. Screenshot it, and read the console for errors.
3. For a page built by looping over data, assert the rendered structure instead of eyeballing it:

```shell
curl -s http://localhost:3000/badges | grep -o '