Write a Tabler demo page

Demo pages live in preview/pages/*.astro and are served at /<name> in dev, /<name>.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

---
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'
---

<DefaultLayout title="Badges" pageMenu="base.badges" description="Badges highlight a count, status, or short label attached to text, buttons, or menu items.">
  <DocsLink slot="page-header-actions" path="/ui/components/badge" />

  <div class="row row-cards">
    <div class="col-md-6 col-lg-4">
      <Card>
        <CardBody>
          <CardTitle>Basic</CardTitle>
          <CardSubtitle>One sentence on what this variant is for.</CardSubtitle>
          …
        </CardBody>
      </Card>
    </div>
  </div>
</DefaultLayout>

• 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 <meta name="description">. 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 <DefaultLayout>:

<DocsLink slot="page-header-actions" path="/ui/components/badge" />

• 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 <DocsLink path="…"> 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: <HeaderActionsButtons slot="page-header-actions" />. There is no actions="buttons" prop any more.

3. Card grid

• One card per variant, in <div class="row row-cards"> 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 <code> inside the subtitle. Readers scan for the token.
• Never write <h3 class="card-title"> or <div class="card-subtitle"> 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 <h3>/<h4> 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:

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. No page-level styles

Never add a <style> block to a preview page or a shared component, and never import CSS from the frontmatter. The built HTML is the product: a plain <style> makes Astro stamp data-astro-cid-* on every element of the page, so a copied page carries dozens of attributes nobody wants. The block also bypasses build-css.ts, so a custom property written bare (var(--table-color)) stays unprefixed and never matches Tabler's --tblr-* names. is:global or is:inline avoids the stamping but not the prefix problem, and still hides styling where nobody looks for it.

If a demo needs a look the framework does not have, either use existing utilities in the markup or add the class to core/scss/ (core-scss skill). If neither fits, keep the plain markup; a demo page never justifies a one-off rule.

7. Accessible demo markup

Demo markup is copied as-is, so a shortcut here becomes a shortcut in every user's app. The four that keep coming back:

• An action with no destination is <button type="button" class="btn">, never <a class="btn"> without href. An anchor without href is not focusable, so keyboard users cannot reach it. An anchor that really links keeps href, and href="#" is fine for a demo link.
• Every control has a name. A search box, a table-row <select>, a switch in a card footer: give it a <label for> or an aria-label. placeholder is not a name.
• A <label> wraps exactly one control or points at one with for. A label wrapping a radio and an unrelated dropdown toggle selects the radio when the toggle is clicked.
• A link or button whose only content is an icon or a logo gets aria-label. <Icon> renders aria-hidden, so without the label the control has no name at all.

Dropdown toggles are <button type="button" data-bs-toggle="dropdown">, or <a href="#" role="button" …> inside a nav; never a <label>. One .dropdown-menu per toggle — Bootstrap shows only the first sibling.

8. 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.

9. 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.

10. 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 /<page-name>.
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:

curl -s http://localhost:3000/badges | grep -o '<h[1-6]' | sort | uniq -c

A demo page should show exactly one h1 and then h2s — no h3 in the card grid.

11. Quality checklist

• title and description set; no pageHeader repeating the title
• DocsLink present when a docs page exists; pnpm run check:docs-links passes
• One card per variant; CardTitle + CardSubtitle on each
• No raw card-title / card-subtitle / page-title markup
• List wrappers instead of per-item margins
• No <style> block and no CSS import; new looks go to core/scss/
• Actions are <button type="button">, controls and icon-only links have a name, every <label> matches one control
• Every <Icon name> exists in shared/data/icons.json (play does not; player-play does)
• pnpm run format:prettier and pnpm run type-check clean (repo root, not a tail-filtered subset)
• Page opened in the browser, console clean, heading order checked
• Changeset written with the generate-changeset skill