Restraint, then one bright move.

Inline label element with variant and size options. Enhanced with prefers-contrast support for users who request higher contrast.

a11y prefers-contrast: more — heavier borders and font weight

<Badge variant="primary" size="sm">Primary</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="neutral">Neutral</Badge>

Polymorphic button/link component. Renders as <a> when href is provided, <button> otherwise. Supports disabled state with proper aria.

a11y Disabled state uses aria-disabled and removes from tab order

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost" size="sm">Ghost</Button>

Hover/focus tooltip upgraded with the Popover API. Browsers that support popover='hint' get auto-dismiss and Escape-to-close. Others fall back to CSS hover/focus.

a11y Visible on focus + hover; Escape-to-close (Popover API)

<Tooltip text="Helpful information" position="top">
  Hover me
</Tooltip>

Scroll-driven reveal animations. Replaces AOS, ScrollMagic, and GSAP ScrollTrigger with zero JavaScript. Uses animation-timeline: view() — content animates in as it enters the viewport.

a11y prefers-reduced-motion: respected — content visible immediately

<ScrollReveal animation="fade-up">
  <Card>Content reveals on scroll</Card>
</ScrollReveal>

Animated counter using CSS @property with <integer> type and counter(). Numbers count up from 0 when scrolled into view — entirely in CSS.

a11y role=img + aria-label exposes counter values to assistive tech

<CounterBadge value={42} suffix="+" label="Components" />

Inline SVG from a Lucide-aligned path registry (ADR-055). currentColor means each icon takes its colour from the surrounding text token; size with utility classes.

a11y Decorative icons get aria-hidden; meaningful ones take an ariaLabel

<Icon name="zap" class="size-6 text-primary-600" ariaLabel="Performance" />

Wrapper over astro:assets <Image> with project defaults: lazy loading, async decoding, and AVIF/WebP output for raster sources. Width/height are required so layout never shifts.

a11y alt is required by the Props type — no silent missing alt

import hero from "@/assets/hero.png";
<Image src={hero} alt="Hero" width={1200} height={630} />

Accessible social link pairing a registry-mapped Icon with an accessible label. purpose='share' vs 'profile' tunes the rel/aria semantics.

<SocialLink platform="github" href="https://github.com/you" />

Dark/light switch backed by a tiny inline script — no framework. It flips the .dark class and persists the choice; the whole page re-themes through the tokens. Progressive enhancement: a real button that works the instant JS runs.

a11y Real <button> with aria-label — keyboard and screen-reader operable

<ThemeToggle />

Base container with optional @starting-style entry animation. When animated=true, the card fades and slides in on first render — visible during View Transitions navigation.

a11y prefers-reduced-motion: respected — no entry animation

<Card animated>
  <div class="p-4">Content with entry animation</div>
</Card>

Native <dialog> element with ::backdrop, focus trapping, and Escape-to-close — all browser-provided. Replaces Radix Dialog, HeadlessUI, or any modal library. Entry animation via @starting-style.

a11y Focus trap + Escape-to-close: native to <dialog>

<Dialog id="my-dialog" title="Dialog Title" size="md">
  <p>Dialog content here</p>
</Dialog>

<button onclick="document.getElementById('my-dialog').showModal()">
  Open Dialog
</button>

CSS-only tab switching using hidden radio buttons — the same pattern as the Header's mobile menu checkbox. Arrow key navigation via ~15 lines of inline script (WCAG requirement).

a11y Keyboard: arrow keys, Home, End — full WCAG tablist pattern

<Tabs tabs={[{ id: "one", label: "Tab One" }, ...]}>
  <div data-tab-panel="one" role="tabpanel">First panel</div>
  <div data-tab-panel="two" role="tabpanel">Second panel</div>
</Tabs>

Feature card with a headline metric and an expandable detail list, built on native <details>/<summary> — no JS for the disclosure. Icon from the registry (ADR-055).

a11y Native <details> disclosure — keyboard operable, announced as expandable

<ExpandableFeatureCard
  icon="gauge"
  title="Performance"
  description="Fast by default"
  metric="99 Lighthouse"
  expandedDetails={["Zero-JS baseline", "AVIF images"]}
/>

Blog index card — cover, reading time, relative date, tags — driven by a content-collection entry plus computed metadata. Renders a real published post.

Architecture Performance Astro

Building This Template: A Ghost's Tour

Seven decisions that hold the Astro Performance Starter together — zero-JS by default, semantic tokens, contract tests, halt-on-violation gates.

3 weeks ago 4 min read

const posts = await getPublishedPosts();
const post = { ...posts[0], metadata: formatPostMetadata(posts[0].data.date, posts[0].body) };
<PostCard post={post} />

Portfolio card — cover, title, description, and a tech-stack row — rendered from a real entry in the projects collection (ADR-056).

Northwind Docs — Documentation Portal

A fictional product's docs, built to show the starter handling dense, navigable, search-friendly content.

Technologies used:

• Astro
• MDX
• Expressive Code
• Pagefind

<ProjectCard
  title={p.data.title}
  description={p.data.description}
  image={p.data.cover}
  techStack={p.data.technologies}
/>

Responsive grid that uses @container queries instead of media queries. The grid responds to its parent container's width, not the viewport — making it truly reusable in any layout context.

<Grid cols={3} gap={4}>
  <Card>Item 1</Card>
  <Card>Item 2</Card>
  <Card>Item 3</Card>
</Grid>

CSS scroll-driven parallax. Decorative background shapes move at different rates than content using animation-timeline: scroll(). Replaces Rellax, Locomotive Scroll, or GSAP ScrollTrigger.

a11y prefers-reduced-motion: respected — shapes stay static; aria-hidden on decorations

<ParallaxSection intensity="subtle">
  <h2>Content moves at normal speed</h2>
  <p>Background shapes drift with parallax</p>
</ParallaxSection>

MDX admonition — note / info / success / warning / danger. Status colours come from the role tokens; the icon is optional.

<Callout type="warning" title="Heads up">
  Body content here.
</Callout>

Pull quote with optional attribution — semantic <blockquote> + <cite>, styled from the border and muted-foreground tokens.

<Blockquote author="Pulci Nella" source="Resident Ghost Dev">
  Ship the artifact, not the apology.
</Blockquote>

Content image with a semantic <figcaption>. Pairs src/alt with an optional caption.

<Figure src="/og-default.png" alt="…" caption="The default OG card" />

The anchor MDX maps to. Internal links stay plain; external links get target=_blank + rel=noopener and a screen-reader 'opens in new tab' note.

[Astro](https://astro.build)  {/* in MDX, rendered by Link */}

Renders a real source file as a syntax-highlighted block at build time (Expressive Code). The snippet can't drift from the file — it IS the file. src resolves against parentUrl; anchor it to the project root so the path is stable through the bundle.

/**
 * Demo source file rendered by the `CodeFromFile` showcase example.
 * It is read from disk at build time and syntax-highlighted by Expressive Code,
 * so the snippet on /showcase can never drift from this file — it IS this file.
 */
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

<CodeFromFile
  src="./src/components/mdx/examples/greet.ts"
  lang="ts"
  title="greet.ts"
  parentUrl={`file://${process.cwd()}/`}
/>