---
name: astro-component
description:
  Build one Astro component for the ai-for-dummies site from the project
  templates. Use when creating a primitive, block, or island, or when splitting
  existing markup into a component.
---

# Building an Astro component

## Decide it should exist

Three occurrences, or a name a person says out loud. Two is not enough — see
[`../../rules/componentization.md`](../../rules/componentization.md).

Then place it:

- `primitives/` — no domain knowledge (Eyebrow, Rule, Callout, CodeBlock)
- `blocks/` — composed, page-agnostic, takes props (RouteCard, PhasePanel)
- `islands/` — interactive, justified, a leaf

## Start from a template

```bash
cp .agents/templates/components/static-block.astro src/components/blocks/RouteCard.astro
# interactive? use island.astro instead
```

Templates exist so ten parallel agents produce one house style. Do not start
from a blank file.

## Write it

```astro
---
interface Props {
  number: string;
  title: string;
  summary: string;
  href: string;
}
const { number, title, summary, href } = Astro.props;
---

<article class="card">
  <b>{number}</b>
  <h2>{title}</h2>
  <p>{summary}</p>
  <a href={href}>Open chapter →</a>
</article>

<style>
  .card {
    display: grid;
    gap: 10px;
    padding: 22px;
    background: var(--paper);
  }
  b {
    color: var(--accent);
    font: var(--font-eyebrow);
  }
</style>
```

Rules that bite most often here:

- **No raw hex.** Tokens only. `check-tokens.mjs` will fail you.
- **No `client:*`** unless it is genuinely interactive, and say why in the PR.
- Keep the `gap:1px` over a coloured parent trick where the original used it —
  it is the house style, not a bug.
- Preserve every ARIA attribute from the markup you are replacing.

## Prove it

1. Render it at 560 / 800 / 1100 / 1600 px.
2. Tab to it. Focus ring visible (`outline: 3px solid #a7483f`).
3. Diff its rendered text against the markup it replaced.
4. Run
   [`../../checklists/before-component.md`](../../checklists/before-component.md).
5. `pnpm run verify` — green, with no assertion deleted.