git:20261009.4ed6af1 to git:20261012.6342afe

- # AGENTS.md — Bub Website

-

- > Guidelines for AI agents (Copilot, Claude Code, Cursor, etc.) working on the `website/` directory.

-

- ---

-

- ## Project Overview

-

- This is the **Bub marketing & docs site** — a static Astro site combining:

-

- - **Landing pages** (home, 404) with custom components — i18n via `src/i18n/`.

- - **Starlight docs** (`/docs/getting-started/…`, `/zh-cn/docs/getting-started/…`) auto-generated from `src/content/docs/` — i18n via Starlight built-in.

- - **Blog** (`/posts/…`, `/zh-cn/posts/…`) powered by Astro content collections — i18n via `src/i18n/`.

-

- Site URL: `https://bub.build`

-

- ---

-

- ## Tech Stack

-

- | Layer | Tool |

- |---------------|----------------------------------------|

- | Framework | **Astro 7** (static output, SSR landing pages via Cloudflare) |

- | Docs | **@astrojs/starlight** 0.42 |

- | Styling | **Tailwind CSS v4** via `@tailwindcss/vite` + `@astrojs/starlight-tailwind` |

- | Component lib | shadcn/ui conventions (base-vega style) |

- | Animations | `motion` (formerly Framer Motion) |

- | Code blocks | `astro-expressive-code` |

- | Fonts | Outfit Variable (sans), JetBrains Mono Variable (mono) |

- | Icons | **@lucide/astro** — see Icon section below |

- | Type checking | TypeScript strict mode |

-

- ---

-

- ## Package Manager

-

- **pnpm** — always use `pnpm` to install packages and run scripts.

-

- Use the version pinned in `package.json#packageManager`; CI reads the same field.

- `website/.node-version` is the single Node pin for this repository. Use Node

- 24.21.0 for development and deployment; `package.json#engines` and `engineStrict`

- enforce the dependency minimum (Node 22.19+ on the 22.x line, or Node 24+). Older

- Node versions can silently omit optional WASM dependencies before the build fails.

- Keep dependency overrides and build-script permissions in `pnpm-workspace.yaml`.

- Astro 7, `@astrojs/cloudflare` 14, and Starlight 0.42 use Vite 8 and the default

- Sätteri Markdown processor. Upgrade these packages together and do not restore

- the old Vite 7 override. `astro-mermaid` 2.1 supports this processor but requires

- Mermaid 10/11; keep Mermaid on 11 until the integration supports a newer major.

- Register Mermaid before Starlight. Preserve `compressHTML: true` to retain the

- site's HTML-aware spacing between inline elements.

- Keep both `current` and `wasm32` in `supportedArchitectures.cpu`: Starlight's

- HTML processors need Sätteri's WASI package when bundled for Cloudflare, while

- Node prerendering uses the native binding. Keep strict peer checks enabled.

- Keep `session: false` while the site has no server-side user state. The generated

- Cloudflare configuration should contain only `ASSETS`, without a `SESSION` KV binding.

-

- Check the [Astro migration guide](https://docs.astro.build/en/guides/upgrade-to/v7/)

- and [Starlight changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md)

- when updating this stack. Starlight 0.42's mobile menu uses `.sl-menu-button` and

- `sl-sidebar-pane:popover-open`; it requires Chromium 116+, Safari 17+, or Firefox 125+.

-

- ```bash

- pnpm install # install deps

- pnpm dev # dev server

- pnpm build # production build

- pnpm preview # preview production build

- ```

-

- ## Image Handling

-

- - Prefer the standard `Image` component from `astro:assets` for local raster assets used by pages and shared UI.

- - Do not replace local logo or illustration components with raw `<img>` just to work around Cloudflare adapter behavior.

- - The repository intentionally splits image handling in `astro.config.mjs`:

- - `BUB_ASTRO_IMAGE_MODE=dev`: Cloudflare image service, so `make docs` works under Node without `cloudflare:workers` import failures.

- - `BUB_ASTRO_IMAGE_MODE=build`: compile-time optimization with passthrough runtime, so `make docs-test`, `make docs-preview`, and production serve stable built asset URLs.

- - `Makefile` is the source of truth for that mode selection. `process.argv` command detection only exists as a fallback for direct `pnpm dev` / `pnpm build` usage inside `website/`.

- - If you change adapter image settings, re-verify all three paths: `make docs`, `make docs-test`, and `make docs-preview`.

-

- ---

-

- ## Directory Structure

-

- ```

- website/

- ├── astro.config.mjs # Astro + Starlight + Tailwind config (locales, sidebar translations)

- ├── components.json # shadcn/ui settings (base-vega style)

- ├── package.json

- ├── tsconfig.json # strict, path alias @/* → src/*

- ├── public/ # static assets (logos, favicon)

- ├── src/

- │ ├── content.config.ts # Content collections: docs (Starlight), i18n (Starlight), posts (blog)

- │ ├── components/ # shared Astro components

- │ │ ├── ui/ # primitives (Icon, SectionHeading)

- │ │ ├── NavBar.astro

- │ │ ├── Footer.astro

- │ │ ├── Hero.astro

- │ │ ├── Features.astro

- │ │ ├── HookIntro.astro

- │ │ ├── TapeModel.astro

- │ │ ├── Testimonials.astro

- │ │ ├── Contributors.astro

- │ │ ├── PostCard.astro

- │ │ └── ThemeToggle.astro

- │ ├── content/

- │ │ ├── docs/ # [Zone 1] Starlight content collection

- │ │ │ ├── docs/ # EN docs — maps to /docs/… routes

- │ │ │ │ ├── getting-started/

- │ │ │ │ ├── concepts/

- │ │ │ │ ├── guides/

- │ │ │ │ └── extending/

- │ │ │ └── zh-cn/ # Chinese translations

- │ │ │ └── docs/

- │ │ │ ├── getting-started/

- │ │ │ ├── concepts/

- │ │ │ └── …

- │ │ ├── i18n/ # [Zone 1] Starlight UI string overrides — BCP-47 filenames

- │ │ │ └── zh-CN.json # ⚠️ ONLY for Starlight UI — never duplicate into src/i18n/

- │ │ └── posts/ # [Zone 3] Blog posts

- │ │ ├── en/ # English posts

- │ │ └── zh-cn/ # Chinese posts

- │ ├── i18n/ # [Zone 2] Custom page i18n module (NOT for Starlight docs)

- │ │ ├── ui.ts # Flat-key UI strings: nav, footer, 404, posts, site meta

- │ │ ├── utils.ts # getLangFromUrl, useTranslations, getNavProps, etc.

- │ │ └── landing-page.ts # Single source of truth for all landing-page copy (both locales)

- │ ├── layouts/

- │ │ ├── BaseLayout.astro # Shared HTML shell (head, nav, footer, scripts)

- │ │ ├── LandingLayout.astro

- │ │ ├── PostLayout.astro

- │ │ └── PostListLayout.astro

- │ ├── pages/

- │ │ ├── 404.astro # 404 page (custom page, uses Zone 2 i18n)

- │ │ └── [...locale]/ # Dynamic locale routing — generates EN (root) + ZH-CN variants

- │ │ ├── index.astro # Landing page (both locales via getStaticPaths)

- │ │ └── posts/

- │ │ ├── index.astro # Post list (both locales via getStaticPaths)

- │ │ └── [slug].astro # Single post (both locales via getStaticPaths)

- │ └── styles/

- │ └── global.css # Tailwind v4 + Starlight bridge + CSS custom properties

- └── DESIGN.md # Visual design guide

- ```

-

- ---

-

- ## i18n Architecture

-

- > **Design reference**: This architecture follows patterns from the [Starlight docs site](https://github.com/withastro/starlight/tree/main/docs) and the [Astro docs site](https://github.com/withastro/docs). Both use Starlight for documentation and separate systems for non-doc pages. Study those repos when in doubt.

-

- ### Three zones, clear boundaries

-

- The site has **three distinct i18n zones**. Each zone has its own translation mechanism. **Never mix them.**

-

- | Zone | Pages | i18n mechanism | String source |

- |------|-------|---------------|---------------|

- | **1 — Starlight docs** | `/docs/…`, `/zh-cn/docs/…` (all under `src/content/docs/`) | Starlight built-in i18n | `src/content/i18n/{locale}.json` + sidebar `translations` in config |

- | **2 — Custom pages** | Landing (`/`, `/zh-cn/`), 404 | Project's own `src/i18n/` module | `src/i18n/ui.ts` + `src/i18n/landing-page.ts` |

- | **3 — Blog** | `/posts/…`, `/zh-cn/posts/…` | Content collection + project `src/i18n/` | Post markdown in `src/content/posts/{locale}/`, UI strings in `ui.ts` |

-

- ### Zone 1 — Starlight docs i18n

-

- Follows the **exact pattern** from [`withastro/starlight/docs`](https://github.com/withastro/starlight/tree/main/docs).

-

- **Locale configuration** — `astro.config.mjs`:

- - English is the **`root` locale** — content files live under `src/content/docs/docs/` (e.g., `docs/getting-started/run-bub-locally.mdx`).

- - Other locales get **subdirectories**: `src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx`.

- - The inner `docs/` directory creates the `/docs/` URL prefix — this nesting namespaces docs routes.

- - This keeps the URL scheme consistent: `/docs/…` for docs, `/posts/…` for blog.

-

- ```js

- // astro.config.mjs

- locales: {

- root: { label: 'English', lang: 'en' }, // ← root = no prefix for EN docs

- 'zh-cn': { label: '简体中文', lang: 'zh-CN' },

- },

- ```

-

- **Starlight UI string overrides** — `src/content/i18n/{locale}.json`:

- - File names use **BCP-47 language tags** (e.g., `zh-CN.json`, not `zh-cn.json`).

- - Override Starlight's built-in UI strings (theme toggle, nav labels, pagination, 404 text, etc.).

- - Extend with custom keys via `i18nSchema({ extend: z.object({...}) })` in `content.config.ts` (see [Starlight docs `content.config.ts`](https://github.com/withastro/starlight/blob/main/docs/src/content.config.ts) and [Astro docs `i18n-schema.ts`](https://github.com/withastro/docs/blob/main/src/content/i18n-schema.ts) for examples).

- - **Do NOT** put these strings in `src/i18n/ui.ts` — that's Zone 2 only.

-

- **Sidebar translations** — inline in `astro.config.mjs`:

- - Uses the `translations` property on each sidebar group/item.

- - Keys are **BCP-47 language tags** (e.g., `'zh-CN'`), NOT URL-slug locale keys.

- - This matches the Starlight docs pattern where sidebar labels carry translation maps inline.

-

- ```js

- sidebar: [{

- label: 'Getting Started',

- translations: { 'zh-CN': '快速开始' },

- items: [{ autogenerate: { directory: 'docs/getting-started' } }],

- }]

- ```

-

- Starlight 0.39+ requires autogenerated entries inside `items`. Keep the group

- label and its translations on the parent; set `autogenerate.collapsed` explicitly

- if generated subgroups should start collapsed.

-

- **Content schema** — `src/content.config.ts`:

- - Uses `docsLoader()` + `docsSchema()` from `@astrojs/starlight/loaders` and `@astrojs/starlight/schema`.

- - Uses `i18nLoader()` + `i18nSchema()` for the i18n collection.

- - Import Zod from `astro/zod`, using `z.url()` for URL fields.

- - Extend the i18n schema with a Zod object if custom Starlight component overrides need translated keys.

- - Extend the docs schema if docs need custom frontmatter fields.

-

- ### Zone 2 — Custom page i18n (`src/i18n/`)

-

- For pages **outside Starlight** (landing page, 404). Starlight has no control over these pages.

-

- **`[...locale]` rest-param routing** — All custom pages live under `src/pages/[...locale]/`. A single page file generates both locales via `getStaticPaths()`:

-

- ```ts

- // In any page under src/pages/[...locale]/

- export function getStaticPaths() {

- return Object.keys(languages).map((lang) => ({

- params: { locale: lang === defaultLang ? undefined : lang },

- props: { locale: lang as Locale },

- }));

- }

- // → generates / (en, root)

- // → generates /zh-cn/ (zh-cn)

- ```

-

- **Never duplicate a page file per locale** — use this pattern instead. The 404 page is the only exception (lives at `src/pages/404.astro` root because Astro requires it there).

-

- | File | Purpose |

- |--------------------|---------|

- | `ui.ts` | **Flat-key** UI string dictionary for shared UI: site meta, nav, footer, 404, post list, language switcher. English is source of truth; other locales override selectively. |

- | `utils.ts` | `getLangFromUrl()`, `useTranslations()`, `useTranslatedPath()`, `getNavProps()`, `getAlternateLocaleHref()` helpers. |

- | `landing-page.ts` | **Single source of truth for all landing-page copy** — both locales. Structured data (feature arrays with icons/colors, testimonials, hook stages, hero text, CTAs). |

-

- > **Convention** (from Astro docs pattern): Landing-page components (Hero, Features, HookIntro, TapeModel, Testimonials) are **pure presentation** — they receive all text/content via props from `landing-page.ts`. They have no hardcoded text defaults. Non-landing UI strings (nav, footer, 404, posts) go in `ui.ts` and are accessed via `t()`.

-

- ### Zone 3 — Blog i18n

-

- Blog posts are a **content collection** (`src/content/posts/{locale}/`). The collection schema includes a `locale` field to identify the language. Blog UI strings (page titles, back-links, etc.) live in `src/i18n/ui.ts` (Zone 2), not in Starlight's i18n.

-

- ### Boundary rules

-

- | ✅ Do | ❌ Don't |

- |-------|----------|

- | Put Starlight UI overrides in `src/content/i18n/` | Duplicate Starlight keys into `src/i18n/ui.ts` |

- | Put nav/footer/404/post-list strings in `src/i18n/ui.ts` | Put custom page strings in `src/content/i18n/` |

- | Put landing-page structured copy in `src/i18n/landing-page.ts` | Put landing text in `ui.ts` or Starlight i18n |

- | Use `[...locale]` rest-param pages for custom pages | Duplicate page files per locale (e.g., `zh-cn/posts/`) |

- | Use `translations` on sidebar items in `astro.config.mjs` | Create separate sidebar translation files for 2 locales |

- | Use BCP-47 tags (`zh-CN`) in Starlight config/i18n files | Use URL slugs (`zh-cn`) in Starlight i18n JSON filenames |

- | Use URL slugs (`zh-cn`) in directory paths and page routes | Use BCP-47 tags in directory/route paths |

-

- ### Adding a UI string (non-landing pages)

-

- 1. Add the English string to `ui.ts` under the `en` object.

- 2. Add the translation under the target locale.

- 3. Use `const t = useTranslations(locale); t('your.key')` in any `.astro` file.

-

- ### Adding landing-page content

-

- 1. Add the English content to `landing-page.ts` under the `en` section.

- 2. Add the translation under the target locale section.

- 3. Pass as props from the page to the component via `getLandingPageCopy(locale)`.

-

- ### Adding a Starlight UI string override

-

- 1. Add the translated string to `src/content/i18n/zh-CN.json` (or the target locale file).

- 2. If the key is custom (not a built-in Starlight key), define it in the Zod extension inside `content.config.ts` via `i18nSchema({ extend: z.object({ 'your.key': z.string().optional() }) })`.

- 3. Reference: [Starlight i18n docs](https://starlight.astro.build/guides/i18n/).

-

- ### Adding a new locale

-

- 1. **Starlight zone**: Add the locale to `astro.config.mjs` `locales`. Create `src/content/docs/<locale>/docs/` with translated docs. Create `src/content/i18n/<BCP-47>.json` for UI overrides.

- 2. **Custom page zone**: Add the locale key to `languages` in `ui.ts`. Add translations in `ui.ts` and `landing-page.ts`. The `[...locale]` pages auto-generate routes via `getStaticPaths()`.

- 3. **Blog zone**: Create `src/content/posts/<locale>/` with translated posts.

-

- ### URL scheme

-

- - English (default): **no prefix** — `/`, `/posts/`, `/docs/getting-started/`, etc.

- - Chinese: `/zh-cn/`, `/zh-cn/posts/`, `/zh-cn/docs/getting-started/`, etc.

- - Starlight docs have a `/docs/` prefix via the `docs/` content subdirectory.

- - Custom pages (landing, blog) use `[...locale]` rest-param routing — one page file generates both `/` and `/zh-cn/` variants.

-

- ### Locale key conventions

-

- | Context | Key format | Example |

- |---------|-----------|---------|

- | URL paths & directory names | lowercase slug | `zh-cn` |

- | `astro.config.mjs` locale keys | lowercase slug | `'zh-cn': { ... }` |

- | `astro.config.mjs` sidebar `translations` keys | BCP-47 | `'zh-CN': '快速开始'` |

- | `src/content/i18n/` filenames | BCP-47 | `zh-CN.json` |

- | HTML `lang` attribute | BCP-47 | `zh-CN` |

- | `src/i18n/ui.ts` locale keys | lowercase slug | `'zh-cn': { ... }` |

-

- ### Adding a new page

-

- **Custom page** (landing/blog style):

- 1. Create `src/pages/[...locale]/<path>.astro` with `getStaticPaths()` generating all locales.

- 2. Import and wrap with the appropriate layout (BaseLayout, PostLayout, etc.).

- 3. Extract text into `ui.ts` (Zone 2) with appropriate flat keys.

- 4. Run `pnpm build` to verify.

-

- **Starlight doc page**:

- 1. Create the English file in `src/content/docs/docs/<section>/<slug>.md`.

- 2. Create the Chinese translation in `src/content/docs/zh-cn/docs/<section>/<slug>.md`.

- 3. Sidebar item is auto-generated if the parent group uses `autogenerate`. Otherwise add to `sidebar` in `astro.config.mjs` with `translations`.

- 4. Run `pnpm build` to verify.

-

- ### Adding a new component

-

- 1. Create in `src/components/`.

- 2. **No hardcoded text defaults** — components are pure presentation. Accept all text/content via props.

- 3. Let the caller pass content via `getLandingPageCopy()` or `t()` from the page level.

- 4. Add `data-reveal` if the component should animate on scroll.

-

- ### Common mistakes

-

- | Mistake | Fix |

- |---------|-----|

- | Writing `<!doctype html>` in a page | Use BaseLayout |

- | Hardcoding nav/footer props in a page | Use `getNavProps()` |

- | Adding nested objects to `ui.ts` | Use flat `'section.key'` format |

- | Using non-Lucide icon libraries | Use `@lucide/astro` via `Icon.astro` |

- | Adding `dark:text-*` for themed colors | Use semantic tokens (`text-foreground`) that auto-switch |

- | Duplicating scroll-reveal `<script>` | BaseLayout includes it |

- | Putting landing text in `ui.ts` | Use `landing-page.ts` — `ui.ts` is for shared UI only |

- | Hardcoding English in component defaults | Components are pure presentation; all text from i18n |

- | Duplicating a page file per locale | Use `[...locale]` rest-param routing with `getStaticPaths()` |

- | Putting custom page strings in `src/content/i18n/` | Zone 1 only. Custom pages use `src/i18n/` (Zone 2) |

- | Putting Starlight overrides in `src/i18n/ui.ts` | Zone 2 only. Starlight uses `src/content/i18n/` (Zone 1) |

- | Naming i18n JSON with URL slugs (`zh-cn.json`) | Use BCP-47 (`zh-CN.json`) for Starlight i18n files |

- | Using BCP-47 in directory paths (`docs/zh-CN/`) | Use lowercase slugs (`docs/zh-cn/`) for directories |

- | Using `'zh-cn'` in sidebar `translations` keys | Use BCP-47 (`'zh-CN'`) |

- | Adding hue/chroma to Starlight color overrides | Site is monochrome — keep oklch with 0 chroma |

- | Adding new `--sl-color-*` overrides without checking the existing unlayered block | Edit the existing `:root { --sl-color-* }` / `.dark, [data-theme="dark"] { --sl-color-* }` blocks — they override the bridge for correct monochrome contrast |

- | Importing `@import "tailwindcss"` in `global.css` | Use `tailwindcss/theme.css` + `tailwindcss/utilities.css` in proper layers — full import brings Preflight that breaks Starlight/EC |

-

- ---

-

- ## Icons — @lucide/astro

-

- All icons come from **Lucide** via `@lucide/astro`. The project wraps them in `src/components/ui/Icon.astro` which handles camelCase → PascalCase name mapping.

-

- ```astro

- <Icon name="arrowUpRight" size={15} />

- <Icon name="github" size={14} /> <!-- special-cased brand icon -->

- ```

-

- - Use **camelCase** icon names (e.g., `arrowUpRight`, `radioTower`, `fileSearch`).

- - Browse icons at https://lucide.dev/icons.

- - The GitHub brand icon is manually defined inside `Icon.astro` (not a Lucide built-in).

-

- ---

-

- ## Theme System — CSS Custom Properties

-

- The design system uses **oklch** color tokens defined in `src/styles/global.css`.

-

- ### Light / Dark

-

- - Light tokens in `:root { }`.

- - Dark tokens in `.dark, [data-theme="dark"] { }` — both selectors are needed to cover landing pages (`.dark` class) and Starlight docs (`[data-theme]` attribute). `ThemeToggle.astro` sets both.

- - Theme toggle logic lives in `ThemeToggle.astro` (in `NavBar.astro`), with an inline init script in `BaseLayout.astro` `<head>` to prevent FOUC.

- - Stored in `localStorage` under key `bub-theme`.

-

- ### Core tokens (selection)

-

- | Token | Usage |

- |----------------------|------------------------------------|

- | `--background` | Page background |

- | `--foreground` | Primary text |

- | `--primary` | CTA buttons, active states |

- | `--primary-foreground` | Text on primary backgrounds |

- | `--secondary` | Hover backgrounds, cards |

- | `--muted-foreground` | Secondary text, meta info |

- | `--border` | All borders |

- | `--card` / `--card-foreground` | Card surfaces |

- | `--chart-1` … `--chart-5` | Accent colors for charts/tags |

-

- ### Fonts

-

- | CSS var | Font | Usage |

- |-----------------|--------------------------|----------------------|

- | `--font-sans` | Outfit Variable | Body, headings |

- | `--font-mono` | JetBrains Mono Variable | Code, badges, labels |

-

- ### Starlight + Tailwind v4 integration

- Starlight ships with a blue accent (hue 224/234) and blue-tinted grays. The main site is **monochrome** (all oklch colors have `0` chroma). The bridge is `@astrojs/starlight-tailwind` — it reads `--color-accent-*` and `--color-gray-*` from the `@theme` block and generates `--sl-color-*` variables in `@layer utilities`. However, the bridge's mapping (e.g. `--sl-color-accent` ← `--color-accent-600`) does not produce the right contrast for a monochrome theme, so **manual unlayered `--sl-*` overrides are still required** for precise control. Unlayered CSS always beats `@layer utilities`.

- **Reference:** [Starlight CSS + Tailwind guide](https://starlight.astro.build/guides/css-and-tailwind/)

- **How `global.css` is structured (follow this order):**

- ```

- 1. Font imports (@import "@fontsource-variable/…")

- 2. Cascade layer ordering: @layer base, starlight, theme, components, utilities;

- 3. Starlight bridge: @import '@astrojs/starlight-tailwind';

- 4. Tailwind layers: @import 'tailwindcss/theme.css' layer(theme);

- @import 'tailwindcss/utilities.css' layer(utilities);

- 5. @theme inline { … } — fonts, Starlight color scales, site design tokens, radius

- 6. :root { … } — raw light tokens (unlayered)

- 7. .dark, [data-theme="dark"] { … } — raw dark tokens (unlayered)

- 8. :root { --sl-font/color overrides } — unlayered to beat bridge @layer utilities

- 9. .dark, [data-theme="dark"] { --sl-color-* overrides }

- 10. @layer base { … } — Tailwind preflight + site base resets (lowest priority)

- ```

- **Why this order matters:**

- | Layer | Contains | Priority |

- |---|---|---|

- | `@layer base` | Site resets (`* { border-border }`, body bg/text, etc.) | Lowest |

- | `@layer starlight` | Starlight + expressive-code styles | Overrides `base` |

- | `@layer theme` | Tailwind theme variables | Overrides `starlight` |

- | `@layer utilities` | Tailwind utilities | Overrides `theme` |

- | Unlayered CSS | Raw tokens, `--sl-font-*` / `--sl-color-*` overrides, `@media` queries | Highest |

- **Key rules:**

- - **NEVER use `@import "tailwindcss"`** — it brings in the full Preflight reset that conflicts with Starlight and astro-expressive-code. Only import `tailwindcss/theme.css` and `tailwindcss/utilities.css` in their proper layers.

- - **Define Starlight colors via `@theme` scales** — `--color-accent-50` through `--color-accent-950` and `--color-gray-50` through `--color-gray-950`. The bridge reads these and generates `--sl-color-*` in `@layer utilities`.

- - **Override `--sl-*` colors and fonts manually (unlayered)** — the bridge's auto-mapped values don't produce the right contrast for the monochrome theme. Unlayered `:root` / `.dark, [data-theme="dark"]` blocks with explicit `--sl-color-*` values win over the bridge's `@layer utilities` output.

- - **Import `tailwindcss/preflight.css` in `@layer base`** — restores box-sizing, link resets, and other base styles that the split Tailwind import omits. Because `base` is the lowest layer, EC and Starlight styles still override it.

- - **The `@layer base` `*` reset is safe** — because EC styles live in `@layer starlight.components` (higher priority), they always win.

- **Starlight color scales (in `@theme`):**

- Both scales use pure neutral oklch values (0 chroma) to match the site's monochrome identity:

- | Scale | Example values | Starlight usage |

- |---|---|---|

- | `--color-accent-50` … `--color-accent-950` | oklch(0.985 0 0) → oklch(0.145 0 0) | Links, highlights, active nav items |

- | `--color-gray-50` … `--color-gray-950` | oklch(0.985 0 0) → oklch(0.145 0 0) | Backgrounds, text, borders |

- > **Do NOT** add hue or chroma to these scales — the entire site identity is neutral/monochrome. Aside callout colors (orange, green, blue, purple, red) are intentionally left at Starlight defaults for semantic clarity.

- **How to customize Starlight appearance going forward:**

- 1. To change Starlight's gray palette → update `--color-gray-*` values in `@theme inline`.

- 2. To change Starlight's accent color → update `--color-accent-*` values in `@theme inline`.

- 3. To change fonts → update `--font-sans` / `--font-mono` in `@theme inline` AND `--sl-font` / `--sl-font-mono` in the unlayered `:root` block.

- 4. To add site-specific overrides that should beat Starlight → put them **unlayered** (outside any `@layer`).

- 5. To add base resets that Starlight/EC can override → put them in `@layer base`.

- **Overriding expressive-code on custom pages (e.g., Hero):**

- When using `<Code />` from `astro-expressive-code` outside Starlight docs, override EC's CSS custom properties in the component's scoped `<style>` block:

- .hero-terminal :global(.expressive-code) {

- --ec-codeBg: var(--card);

- --ec-frm-edTabBarBg: var(--secondary);

- /* … etc. — see Hero.astro for the full list */

- }

- ```

-

- Scoped Astro styles are unlayered, so they beat both `@layer base` and `@layer starlight`.

-

- ### Radius

-

- Radius tokens follow a scale: `--radius-sm` through `--radius-4xl`, all computed from `--radius: 0.625rem`.

-

- ---

-

- ## Layout Hierarchy

-

- ```

- BaseLayout.astro ← HTML shell, <head>, NavBar, Footer, scroll-reveal, back-to-top

- ├── LandingLayout.astro ← Hero + section components

- ├── PostLayout.astro ← Single blog post with article styles

- ├── PostListLayout.astro ← Blog listing page

- └── (404.astro uses BaseLayout directly)

- **All pages go through BaseLayout.** Never duplicate `<!doctype>`, `<head>`, `NavBar`, `Footer`, or scroll-reveal scripts.

-

- ---

-

- ## Coding Conventions

- - **Astro components** for static content; avoid client-side JS unless interactive.

- - **Tailwind utility classes** for styling; avoid custom CSS unless for animations.

- - `class:list` for conditional classes.

- - Props interfaces at the top of the frontmatter.

- - `data-reveal` attribute on elements that should animate on scroll.

- - Keep line length ≤ 120 chars.

- ---

- ## Before Committing

- 1. `pnpm build` — must pass with no errors.

- 2. Check for hardcoded nav props — use `getNavProps()` from `i18n/utils.ts`.

- 3. Check for duplicated HTML shell — compose on `BaseLayout`.

- 4. Ensure all user-visible strings use the correct zone:

- - **Zone 1** (Starlight docs): UI overrides in `src/content/i18n/`, sidebar translations inline in config.

- - **Zone 2** (Custom pages): Landing copy → `landing-page.ts`, shared UI strings → `ui.ts`.

- - **Zone 3** (Blog): Post content in `src/content/posts/{locale}/`, UI strings in `ui.ts`.

- - Never duplicate text across zones.