# Rule: Astro

Binding for every `.astro` file.

## Zero JS is the default

A component ships no JavaScript unless it has a `client:*` directive. Seven of
this site's ten pages ship no JS today and must continue to.

- Never add `client:load` without justifying it in the PR description.
- Prefer, in order: no JS → `client:visible` → `client:idle` → `client:load`.
- An island is a **leaf**, not a wrapper. Hydrate the tab panel, not the page.

## Islands in this project

Only these need interactivity. Anything else claiming island status is wrong:

| Island                            | Why                                | Directive        |
| --------------------------------- | ---------------------------------- | ---------------- |
| Guide phase/tab switchers         | click-driven panel swap            | `client:visible` |
| Review desk catalog + file viewer | search, filter, fetch source files | `client:load`    |
| Vote widget                       | talks to the vote API              | `client:visible` |
| Language toggle                   | swaps EN/PT across the page        | `client:idle`    |

## Structure

```astro
---
// 1. imports
// 2. Props interface
// 3. destructure Astro.props
// 4. derived values — no side effects, no fetch in components
---

<!-- markup -->
<style>
  /* component-scoped */
</style>
```

- Typed props always: `interface Props { … }`, then `const { … } = Astro.props`.
- Data loading belongs in `src/content/` collections or the page frontmatter,
  not inside a component.
- No barrel files (`index.ts` re-export hubs). They cost tree-shaking and invite
  cycles.

## Content collections

All copy lives in `src/content/`, typed with a Zod schema in
`src/content/config.ts`. The review desk's `catalog.js` maps onto a collection
almost one-to-one — do that rather than importing a 27 KB JS file.

## Styles

- Component styles go in the component's `<style>` block. Astro scopes them.
- Only tokens and true resets live in global CSS.
- Do not port `responsive.css` verbatim. It is an override layer whose reason
  for existing disappears once layout is componentized. Port what a component
  needs, prove the rest is dead, delete it.

## URLs and the base path

The site is served from `/ai-for-dummies/`. Set `base` in `astro.config.mjs` and
never hand-write an absolute internal path. Use `import.meta.env.BASE_URL`.

Existing routes are load-bearing and must not change, including trailing slashes
and the review desk's query params.

## Never

- No UI framework (React/Vue/Svelte) unless a task brief explicitly calls for
  it. Astro components plus a little vanilla JS cover everything here.
- No CSS framework. This site has a hand-built visual identity — see
  [`theming.md`](theming.md).
- No external runtime requests. Self-host. `audit-ui.mjs` enforces it.