Marcos Paulo
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 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 `vote-service/` | `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.
|