diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 0e21a13..86a042b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -27,7 +27,7 @@
     {
       "name": "astro-builder",
       "description": "Build Astro 6 static content sites with Claude. Enforces best practices for i18n, content collections, the page-views pattern, and design systems. Starts with /astro-builder:init to configure your project.",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "author": {
         "name": "pcamarajr"
       },
diff --git a/.gitignore b/.gitignore
index 0677f2a..51c9cd7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,9 @@
 .claude/settings.local.json
 .worktrees/
 .cost-log/
+
+# Personal-knowledge memory system (local-only, see personal-knowledge-cli)
+.claude/CLAUDE.md
+.claude/skills/memory/
+.claude/skills/import-memories/
+.claude/skills/init-memory/
diff --git a/README.md b/README.md
index 63b5cb3..760da0f 100644
--- a/README.md
+++ b/README.md
@@ -114,7 +114,7 @@ Install:
 Astro 6 site builder plugin that scaffolds and evolves static content sites using the page-views pattern, i18n, content collections, and quality gates.
 
 - **Best for:** creating or restructuring Astro content architectures
-- **Key skills:** `init`, `init project`, `init lighthouse`, `new-page`, `new-content-type`, `translate`, `audit`
+- **Key skills:** `init`, `init project`, `init lighthouse`, `new-page`, `new-content-type`, `translate`, `audit`, `css-conventions` (auto-applied)
 
 Install:
 
diff --git a/astro-builder/README.md b/astro-builder/README.md
index 749f10b..fc6c396 100644
--- a/astro-builder/README.md
+++ b/astro-builder/README.md
@@ -49,6 +49,7 @@ If you want the fastest start, begin from the ready template:
 | `/astro-builder:new-content-type` | Add a new content collection with schema, utilities, and example content |
 | `/astro-builder:translate` | Localize a content entry or i18n JSON to another locale |
 | `/astro-builder:audit` | Audit for anti-patterns, missing translations, schema errors, and build failures |
+| `css-conventions` _(auto-applied)_ | Enforces CSS discipline whenever styles are written: token-only values, scoped `<style>` blocks, Tier-1 modern CSS, no Tailwind / CSS-in-JS / preprocessors, and a CSS-first interactivity ladder |
 
 ### Examples
 
@@ -147,10 +148,11 @@ Two agents work behind the scenes:
 ```
 your-project/
 ├── CLAUDE.md                          ← Project rules for Claude Code
+├── src/styles/global.css              ← Tokens, reset, base, utilities (@layer)
 └── .astro-builder/
     ├── style-guide.md                 ← Voice, tone, writing conventions
     ├── content-schema.md              ← Content types, fields, relationships
-    ├── design-system.md               ← Colors, typography, component patterns
+    ├── design-system.md               ← Token index (mirrors global.css)
     └── anti-patterns.md               ← What to avoid in this project
 ```
 
diff --git a/astro-builder/docs/init-templates/CLAUDE.md.template b/astro-builder/docs/init-templates/CLAUDE.md.template
index d1acfa1..9eb5254 100644
--- a/astro-builder/docs/init-templates/CLAUDE.md.template
+++ b/astro-builder/docs/init-templates/CLAUDE.md.template
@@ -88,12 +88,27 @@ Three layers — never collapse them:
 - Config: `astro.config.ts` (never `.mjs`)
 - Node.js: 22 LTS
 
+### CSS conventions
+
+All CSS work in this project follows the **`css-conventions` skill** from the `astro-builder`
+plugin. It fires every time CSS is written, reviewed, or refactored — and before adding any
+JavaScript to a component. Key rules:
+
+- **Tokens only:** every color, font, font size, spacing value, radius, and shadow comes from
+  CSS custom properties in `src/styles/global.css`. No raw hex/rgb/px values in component CSS.
+- **Single global stylesheet:** `src/styles/global.css` with `@layer reset, tokens, base, utilities`. No other global CSS files. No CSS Modules, no `<style is:global>`, no sibling `.css` files.
+- **Component CSS** lives in Astro scoped `<style>` blocks only.
+- **No Tailwind, no utility-class libraries, no CSS-in-JS, no preprocessors.**
+- **Interactivity ladder:** before adding `client:*` to a component, walk CSS → vanilla `<script>` → island. Most chrome (focus reveal, hover, accordion, tabs, modals, theme toggle) needs no island.
+
+See `.astro-builder/design-system.md` for the token index.
+
 ## Project-specific context
 
 See `.astro-builder/` for full context:
 
 - `.astro-builder/content-schema.md` — Content types, fields, relationships
-- `.astro-builder/design-system.md` — Colors, typography, component patterns
+- `.astro-builder/design-system.md` — Token namespaces and component patterns (index for `src/styles/global.css`)
 - `.astro-builder/style-guide.md` — Voice, tone, writing conventions
 - `.astro-builder/anti-patterns.md` — What to avoid in this specific project
 
diff --git a/astro-builder/docs/init-templates/design-system.md.template b/astro-builder/docs/init-templates/design-system.md.template
index 48864b6..d1217cc 100644
--- a/astro-builder/docs/init-templates/design-system.md.template
+++ b/astro-builder/docs/init-templates/design-system.md.template
@@ -1,68 +1,116 @@
 # Design System
 
-Defines the visual language for {{SITE_NAME}}: colors, typography, spacing, and component patterns.
-Generated by `astro-builder`. Update by re-running `/astro-builder:init` or editing directly.
+The visual language for {{SITE_NAME}}: tokens, typography, and component patterns.
+
+Generated by `astro-builder`. Update by re-running `/astro-builder:init` or editing
+`src/styles/global.css` and this file in sync.
+
+> **Source of truth:** `src/styles/global.css` contains the actual CSS custom properties. This file
+> is the human-readable index. When tokens change, update both.
+>
+> **Authoring rule:** every color, font family, font size, spacing value, border radius, and box
+> shadow used in component CSS must reference one of the six token namespaces below. See the
+> `css-conventions` skill for the full rule set.
 
 ## Visual style
 
 **Aesthetic**: {{VISUAL_STYLE}}
 **Description**: {{VISUAL_STYLE_DESCRIPTION}}
 
-## Colors
+---
+
+## Token namespaces
+
+Six canonical namespaces. Components reference these — never raw values.
+
+### `--color-*` — colors
 
 | Token | Value | Usage |
 |-------|-------|-------|
-| `--color-primary` | `{{PRIMARY_COLOR}}` | CTAs, links, highlights, accent |
-| `--color-primary-dark` | `{{PRIMARY_DARK}}` | Hover states for primary |
 | `--color-bg` | `{{BG_COLOR}}` | Page background |
 | `--color-surface` | `{{SURFACE_COLOR}}` | Cards, panels |
 | `--color-text` | `{{TEXT_COLOR}}` | Body text |
 | `--color-text-muted` | `{{TEXT_MUTED}}` | Secondary text, captions |
+| `--color-primary` | `{{PRIMARY_COLOR}}` | CTAs, links, accents |
+| `--color-primary-dark` | `{{PRIMARY_DARK}}` | Hover state for primary |
 | `--color-border` | `{{BORDER_COLOR}}` | Borders, dividers |
+| `--color-focus` | `{{FOCUS_COLOR}}` | Focus rings |
+| `--color-error` | `{{ERROR_COLOR}}` | Errors, destructive actions |
+| `--color-success` | `{{SUCCESS_COLOR}}` | Success states |
+
+Dark mode handled via `@media (prefers-color-scheme: dark)` in `global.css`.
+
+### `--font-*` — font family stacks
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--font-display` | `{{DISPLAY_FONT}}, {{DISPLAY_FALLBACK}}` | Headings, hero text |
+| `--font-body` | `{{BODY_FONT}}, {{BODY_FALLBACK}}` | Body copy, UI |
+| `--font-mono` | `{{MONO_FONT}}, ui-monospace, monospace` | Code blocks, technical text |
+
+Fonts loaded via {{FONT_SOURCE}}.
+
+### `--text-*` — font sizes
+
+| Token | Size | Weight | Usage |
+|-------|------|--------|-------|
+| `--text-xs` | `0.75rem` | 400 | Labels, captions |
+| `--text-sm` | `0.875rem` | 400 | Secondary text |
+| `--text-base` | `1rem` | 400 | Body copy |
+| `--text-lg` | `1.125rem` | 400 | Lead text |
+| `--text-xl` | `1.25rem` | 600 | Subheadings |
+| `--text-2xl` | `1.5rem` | 700 | H3 |
+| `--text-3xl` | `1.875rem` | 700 | H2 |
+| `--text-4xl` | `2.25rem` | 800 | H1 |
 
-All color tokens are defined as CSS custom properties in `src/styles/global.css`.
+Consider `clamp()` for fluid sizes — e.g. `--text-4xl: clamp(2rem, 5vw, 3rem)`.
 
-## Typography
+### `--space-*` — spacing scale
 
-| Role | Font | Fallback |
-|------|------|---------|
-| Display / headings | {{DISPLAY_FONT}} | {{DISPLAY_FALLBACK}} |
-| Body / prose | {{BODY_FONT}} | {{BODY_FALLBACK}} |
-| Code / mono | {{MONO_FONT}} | `monospace` |
+| Token | Size | Usage |
+|-------|------|-------|
+| `--space-xs` | `0.25rem` (4px) | Hairline gaps |
+| `--space-sm` | `0.5rem` (8px) | Tight padding, icon-text gap |
+| `--space-md` | `1rem` (16px) | Default padding, paragraph spacing |
+| `--space-lg` | `1.5rem` (24px) | Section internal spacing |
+| `--space-xl` | `2rem` (32px) | Major section spacing |
+| `--space-2xl` | `3rem` (48px) | Between hero and content |
+| `--space-3xl` | `5rem` (80px) | Top-level page rhythm |
 
-Fonts are loaded via {{FONT_SOURCE}} (Google Fonts / system / self-hosted).
+Use for `margin`, `padding`, and `gap` — never raw `px` or `rem` values.
 
-### Type scale
+### `--radius-*` — border radius
 
-| Name | Size | Weight | Usage |
-|------|------|--------|-------|
-| `--text-xs` | 0.75rem | 400 | Labels, captions |
-| `--text-sm` | 0.875rem | 400 | Secondary text |
-| `--text-base` | 1rem | 400 | Body copy |
-| `--text-lg` | 1.125rem | 400 | Lead text |
-| `--text-xl` | 1.25rem | 600 | Subheadings |
-| `--text-2xl` | 1.5rem | 700 | H3 |
-| `--text-3xl` | 1.875rem | 700 | H2 |
-| `--text-4xl` | 2.25rem | 800 | H1 |
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--radius-sm` | `{{RADIUS_SM}}` | Inputs, small chips |
+| `--radius-md` | `{{RADIUS_MD}}` | Cards, panels |
+| `--radius-lg` | `{{RADIUS_LG}}` | Modals, hero blocks |
+| `--radius-full` | `9999px` | Pills, avatars |
 
-## Borders and spacing
+### `--shadow-*` — box shadows
 
-- **Border style**: {{BORDER_STYLE}} (e.g. `3px solid var(--color-border)`)
-- **Border radius**: {{BORDER_RADIUS}} (e.g. `0` for sharp, `0.5rem` for rounded)
-- **Shadow style**: {{SHADOW_STYLE}} (e.g. `4px 4px 0 black` for hard/neobrutalist)
-- **Base spacing unit**: `0.25rem` (4px) — use multiples
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--shadow-sm` | `{{SHADOW_SM}}` | Subtle elevation (chips, buttons on hover) |
+| `--shadow-md` | `{{SHADOW_MD}}` | Cards, dropdowns |
+| `--shadow-lg` | `{{SHADOW_LG}}` | Modals, popovers |
+
+---
 
 ## Component patterns
 
+These compose tokens — they don't introduce new raw values.
+
 ### Cards
 
 ```css
 .card {
   background: var(--color-surface);
-  border: {{BORDER_STYLE}};
-  border-radius: {{BORDER_RADIUS}};
-  box-shadow: {{SHADOW_STYLE}};
-  padding: 1.5rem;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-sm);
+  padding: var(--space-lg);
 }
 ```
 
@@ -78,25 +126,38 @@ Fonts are loaded via {{FONT_SOURCE}} (Google Fonts / system / self-hosted).
 
 ```css
 .tag {
-  background: {{TAG_BG}};
-  color: {{TAG_TEXT}};
+  background: color-mix(in oklch, var(--color-primary) 15%, transparent);
+  color: var(--color-primary);
   font-size: var(--text-xs);
   font-weight: 600;
-  padding: 0.125rem 0.5rem;
-  border-radius: {{BORDER_RADIUS}};
+  padding: var(--space-xs) var(--space-sm);
+  border-radius: var(--radius-full);
 }
 ```
 
-## Accessibility
+---
+
+## Accessibility baseline
 
-- All interactive elements have `:focus-visible` styles.
-- Color contrast ratio meets WCAG AA (4.5:1 for body text).
-- `prefers-reduced-motion` — disable transitions/animations.
-- Skip navigation link present in `BaseLayout.astro`.
+Enforced in `global.css` under `@layer base`:
+
+- All interactive elements have `:focus-visible` styles (2px outline in `--color-focus`).
+- Color contrast meets WCAG AA (4.5:1 for body text).
+- `prefers-reduced-motion` disables non-essential transitions and animations.
+- Skip-navigation link present in `BaseLayout.astro`.
+
+---
 
 ## CSS approach
 
 {{CSS_APPROACH}}
 
-All global tokens and reset rules live in `src/styles/global.css`.
-Component-scoped styles use Astro's `<style>` blocks (scoped by default).
+All global tokens and resets live in `src/styles/global.css`, organized as:
+
+```css
+@layer reset, tokens, base, utilities;
+```
+
+Component styles live in Astro scoped `<style>` blocks (one per `.astro` file). See the
+`css-conventions` skill for the full discipline (scoping, naming, selectors, anti-Tailwind,
+interactivity ladder, modern-feature checklist).
diff --git a/astro-builder/docs/init-templates/global.css.template b/astro-builder/docs/init-templates/global.css.template
new file mode 100644
index 0000000..0c2389e
--- /dev/null
+++ b/astro-builder/docs/init-templates/global.css.template
@@ -0,0 +1,216 @@
+/* {{SITE_NAME}} — global styles
+ *
+ * Generated by astro-builder. Source of truth for design tokens.
+ * See .astro-builder/design-system.md for the human-readable index.
+ *
+ * Cascade order: reset → tokens → base → utilities
+ * Component styles live in Astro scoped <style> blocks, not here.
+ */
+
+@layer reset, tokens, base, utilities;
+
+/* ───────────────────────── reset ───────────────────────── */
+
+@layer reset {
+  *, *::before, *::after {
+    box-sizing: border-box;
+  }
+
+  * {
+    margin: 0;
+    padding: 0;
+  }
+
+  html {
+    -webkit-text-size-adjust: 100%;
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  body {
+    min-height: 100svh;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+  }
+
+  img, picture, video, canvas, svg {
+    display: block;
+    max-width: 100%;
+    height: auto;
+  }
+
+  input, button, textarea, select {
+    font: inherit;
+    color: inherit;
+  }
+
+  button {
+    background: none;
+    border: none;
+    cursor: pointer;
+  }
+
+  a {
+    color: inherit;
+    text-decoration: none;
+  }
+}
+
+/* ───────────────────────── tokens ───────────────────────── */
+
+@layer tokens {
+  :root {
+    color-scheme: light dark;
+
+    /* --color-* */
+    --color-bg: {{BG_COLOR}};
+    --color-surface: {{SURFACE_COLOR}};
+    --color-text: {{TEXT_COLOR}};
+    --color-text-muted: {{TEXT_MUTED}};
+    --color-primary: {{PRIMARY_COLOR}};
+    --color-primary-dark: {{PRIMARY_DARK}};
+    --color-border: {{BORDER_COLOR}};
+    --color-focus: {{FOCUS_COLOR}};
+    --color-error: {{ERROR_COLOR}};
+    --color-success: {{SUCCESS_COLOR}};
+
+    /* --font-* */
+    --font-display: {{DISPLAY_FONT}}, {{DISPLAY_FALLBACK}};
+    --font-body: {{BODY_FONT}}, {{BODY_FALLBACK}};
+    --font-mono: {{MONO_FONT}}, ui-monospace, SFMono-Regular, Menlo, monospace;
+
+    /* --text-* */
+    --text-xs: 0.75rem;
+    --text-sm: 0.875rem;
+    --text-base: 1rem;
+    --text-lg: 1.125rem;
+    --text-xl: 1.25rem;
+    --text-2xl: 1.5rem;
+    --text-3xl: 1.875rem;
+    --text-4xl: 2.25rem;
+
+    /* --space-* */
+    --space-xs: 0.25rem;
+    --space-sm: 0.5rem;
+    --space-md: 1rem;
+    --space-lg: 1.5rem;
+    --space-xl: 2rem;
+    --space-2xl: 3rem;
+    --space-3xl: 5rem;
+
+    /* --radius-* */
+    --radius-sm: {{RADIUS_SM}};
+    --radius-md: {{RADIUS_MD}};
+    --radius-lg: {{RADIUS_LG}};
+    --radius-full: 9999px;
+
+    /* --shadow-* */
+    --shadow-sm: {{SHADOW_SM}};
+    --shadow-md: {{SHADOW_MD}};
+    --shadow-lg: {{SHADOW_LG}};
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --color-bg: {{BG_COLOR_DARK}};
+      --color-surface: {{SURFACE_COLOR_DARK}};
+      --color-text: {{TEXT_COLOR_DARK}};
+      --color-text-muted: {{TEXT_MUTED_DARK}};
+      --color-border: {{BORDER_COLOR_DARK}};
+    }
+  }
+}
+
+/* ───────────────────────── base ───────────────────────── */
+
+@layer base {
+  body {
+    background: var(--color-bg);
+    color: var(--color-text);
+    font-family: var(--font-body);
+    font-size: var(--text-base);
+  }
+
+  :is(h1, h2, h3, h4, h5, h6) {
+    font-family: var(--font-display);
+    line-height: 1.15;
+    text-wrap: balance;
+  }
+
+  h1 { font-size: var(--text-4xl); }
+  h2 { font-size: var(--text-3xl); }
+  h3 { font-size: var(--text-2xl); }
+  h4 { font-size: var(--text-xl); }
+  h5 { font-size: var(--text-lg); }
+  h6 { font-size: var(--text-base); }
+
+  :is(p, li, blockquote) {
+    text-wrap: pretty;
+  }
+
+  a {
+    color: var(--color-primary);
+    text-underline-offset: 0.15em;
+  }
+
+  a:hover {
+    color: var(--color-primary-dark);
+    text-decoration: underline;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--color-focus);
+    outline-offset: 2px;
+  }
+
+  ::selection {
+    background: color-mix(in oklch, var(--color-primary) 25%, transparent);
+  }
+
+  code, pre, kbd, samp {
+    font-family: var(--font-mono);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}
+
+/* ───────────────────────── utilities ───────────────────────── */
+
+@layer utilities {
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .skip-link {
+    position: absolute;
+    inset-block-start: var(--space-sm);
+    inset-inline-start: var(--space-sm);
+    padding: var(--space-sm) var(--space-md);
+    background: var(--color-surface);
+    color: var(--color-text);
+    border-radius: var(--radius-sm);
+    box-shadow: var(--shadow-md);
+    transform: translateY(-200%);
+    transition: transform 150ms ease;
+    z-index: 100;
+  }
+
+  .skip-link:focus-visible {
+    transform: translateY(0);
+  }
+}
diff --git a/astro-builder/skills/audit/SKILL.md b/astro-builder/skills/audit/SKILL.md
index 60dc952..c4faa6d 100644
--- a/astro-builder/skills/audit/SKILL.md
+++ b/astro-builder/skills/audit/SKILL.md
@@ -13,8 +13,10 @@ Read:
 2. `.astro-builder/anti-patterns.md` — project-specific anti-patterns.
 3. `.astro-builder/content-schema.md` — expected content structure.
 4. `.astro-builder/style-guide.md` — writing rules.
-5. `astro.config.ts` — i18n config, integrations, adapter.
-6. `src/content.config.ts` — collection schemas.
+5. `.astro-builder/design-system.md` — token namespaces.
+6. `src/styles/global.css` — token source of truth.
+7. `astro.config.ts` — i18n config, integrations, adapter.
+8. `src/content.config.ts` — collection schemas.
 
 Also read the canonical Astro 6 anti-patterns from `docs/astro-patterns.md`.
 
@@ -45,6 +47,29 @@ For each content collection defined in `src/content.config.ts`:
 - Check that `tags` are arrays (not strings).
 - Flag any files with frontmatter errors.
 
+## Step 4.5 — CSS conventions audit
+
+Read `.astro-builder/design-system.md` to learn the project's token names. Then sweep the codebase for `css-conventions` skill violations. Report findings as P1 unless noted.
+
+Run these greps (adjust shell-globbing as needed):
+
+| Violation | Pattern | Severity |
+|---|---|---|
+| `!important` used | `grep -rn "!important" src --include="*.astro" --include="*.css"`. Allowed only inside `@media (prefers-reduced-motion: reduce)` blocks. | P1 |
+| Tailwind / utility framework | `grep -rn -E "@tailwind\|@apply\|tailwindcss" src package.json` | P0 |
+| CSS-in-JS or preprocessor | `grep -rn -E "styled-components\|@emotion\|sass\|less\|stylus" package.json` | P0 |
+| CSS Modules / sibling .css | find files matching `**/*.module.css` or component-named `.css` siblings | P1 |
+| `<style is:global>` in component | `grep -rn "style is:global" src --include="*.astro"` (outside `src/layouts/BaseLayout.astro` if used to import global.css) | P1 |
+| Inline `style=` with standard properties | `grep -rnE "style=\"[^\"]*[a-z-]+:" src --include="*.astro"`. Only custom-property assignments (`style="--x: ..."`) are allowed. | P1 |
+| Raw hex colors outside global.css | `grep -rn -E "#[0-9a-fA-F]{3,8}" src --include="*.astro"` — flag any in `<style>` blocks. | P1 |
+| Raw `rgb(` / `rgba(` / `hsl(` outside global.css | `grep -rn -E "rgba?\(\|hsla?\(" src --include="*.astro"` in `<style>` blocks | P1 |
+| ID selectors for styling | `grep -rn -E "^\s*#[a-z]" src --include="*.astro"` in `<style>` blocks | P2 |
+| Nesting deeper than 2 levels | manual inspection of any `<style>` block flagged by the file scan | P2 |
+
+For each violation, link to the specific file:line and quote the offending fragment in the report.
+
+---
+
 ## Step 5 — Style guide audit
 
 Read `.astro-builder/style-guide.md` and check a sample of 5 content files per collection:
diff --git a/astro-builder/skills/css-conventions/SKILL.md b/astro-builder/skills/css-conventions/SKILL.md
new file mode 100644
index 0000000..c552508
--- /dev/null
+++ b/astro-builder/skills/css-conventions/SKILL.md
@@ -0,0 +1,331 @@
+---
+description: >
+  Use this skill whenever writing, reviewing, or refactoring CSS in this astro-builder project —
+  in Astro scoped `<style>` blocks, in `src/styles/global.css`, in component style attributes, or
+  anywhere a color, size, spacing value, animation, or layout decision is being made. Also trigger
+  before adding interactivity to any component: walk the CSS → vanilla `<script>` → Astro island
+  ladder before reaching for `client:*`. This skill enforces six disciplines (tokens, scoping, file
+  location, selectors, naming, anti-Tailwind) plus a Tier-1 modern-CSS feature checklist. Never
+  reach for legacy patterns (px-based media queries, CSS-in-JS, utility frameworks, preprocessors)
+  when native modern CSS can express the same thing.
+---
+
+# CSS Conventions — astro-builder
+
+The single source of truth for how CSS is authored in an astro-builder project. Fires every time
+CSS is written, reviewed, or refactored. Six disciplines, one modern-features checklist, one
+interactivity ladder.
+
+---
+
+## Step 1 — Resolve the project's browser tier
+
+Read in this order, stop at first match:
+
+1. `package.json` → `browserslist` field
+2. `.browserslistrc` file
+3. `astro.config.ts` → `build.target` (Astro defaults to `'baseline-widely-available'` ≈ Tier 1)
+4. **No config found → assume Tier 1** (astro-builder default).
+
+Map to tier:
+
+| Tier | Resolves to roughly | Stance |
+|------|---------------------|--------|
+| **Tier 1** (default) | Chrome 125+ / Safari 17.5+ / Firefox 128+ | Use everything stable. Two mandatory fallbacks (Step 4). |
+| **Tier 2** | Chrome 111+ / Safari 16.4+ / Firefox 113+ | Use most modern features. Wrap `field-sizing`, `@scope`, `@starting-style`, `transition-behavior: allow-discrete`, scroll-driven animations, `:popover-open` in `@supports`. |
+| **Tier 3** | Chrome 105+ / Safari 15+ / Firefox 110+ | Be selective. Wrap OKLCH, `color-mix`, `:has()`, container queries, `@layer` in `@supports`. |
+
+When uncertain, run `npx browserslist` in the project root.
+
+---
+
+## Step 2 — Apply the six disciplines
+
+Every CSS change must satisfy all six. They are not negotiable.
+
+### 2.1 — Token discipline
+
+All values in these six domains must come from CSS custom properties defined in
+`src/styles/global.css`:
+
+| Namespace | Domain |
+|-----------|--------|
+| `--color-*` | every color (background, text, border, shadow color, outline, ...) |
+| `--font-*` | font family stacks |
+| `--text-*` | font sizes |
+| `--space-*` | spacing scale (margin, padding, gap) |
+| `--radius-*` | border-radius |
+| `--shadow-*` | box-shadow |
+
+**Rules:**
+
+- Raw hex / rgb / hsl / oklch literals in those domains: **forbidden outside `global.css`**.
+- Raw pixel/rem values for font-size, spacing scale, or radius: **forbidden outside `global.css`**.
+- If the value you need isn't in the design system, add a token to `global.css` first, then use it.
+- Document new tokens in `.astro-builder/design-system.md`.
+
+**Allowed raw values (not design-system axes):**
+
+- One-off layout dimensions: `width`, `height`, `max-width`, `min-height`, positional `top/left/right/bottom`, container `inline-size` thresholds. These are component-specific, not design-system axes.
+- Math primitives inside `clamp()` / `min()` / `max()`: vw/vh/em/% units expressing layout fluidity.
+- Z-index values (use a documented z-index scale if the project has one; otherwise raw integers).
+- Animation durations and easings (consider promoting to `--motion-*` tokens if reused 3+ times).
+
+### 2.2 — Scoping & file location
+
+- **One global stylesheet only:** `src/styles/global.css`. No `reset.css`, `typography.css`, etc.
+- **`global.css` structure:** four `@layer` declarations, in this order:
+  ```css
+  @layer reset, tokens, base, utilities;
+
+  @layer reset { /* normalize / box-sizing / element resets */ }
+  @layer tokens { :root { /* all --color-*, --font-*, --text-*, --space-*, --radius-*, --shadow-* */ } }
+  @layer base { /* element selectors only: body, h1–h6, a, button, ::selection, focus styles, prefers-reduced-motion */ }
+  @layer utilities { /* tiny, deliberate set: .sr-only, .skip-link */ }
+  ```
+- **No class selectors in `@layer base`.** Classes belong to scoped component CSS.
+- **All component CSS lives in the component's `<style>` block.** One `.astro` file = one `<style>` block.
+
+**Forbidden:**
+
+- CSS Modules (`*.module.css`).
+- Sibling `.css` files paired with a component.
+- `<style is:global>` inside components — if it needs to be global, it belongs in `global.css`.
+- Inline `style=""` with standard CSS properties.
+
+**Single exception:** inline `style=""` may set **CSS custom properties only**, never standard
+properties. This is the legitimate channel for dynamic values (scroll progress, anchor positioning
+target IDs, runtime theming):
+
+```astro
+<div style={`--scroll-progress: ${progress}`}>
+```
+
+### 2.3 — Class naming
+
+- **kebab-case:** `.card-actions`, never `.cardActions` or `.card_actions`.
+- **Semantic, not visual:** `.muted`, never `.gray-text`. `.actions`, never `.flex-row-end`.
+- **Brief inside scoped components.** Single words when unambiguous (`.title`, `.input`, `.actions`).
+  Compound only when needed (`.form-actions`, `.nav-link`).
+- **No BEM.** `__element` / `--modifier` syntax is redundant — Astro scopes for you.
+- **No utility-class names.** `.mt-4`, `.text-lg`, `.flex`, `.gap-2`, etc. are forbidden.
+- **Global utilities** (`@layer utilities`) stay semantic: `.sr-only`, `.skip-link`.
+
+### 2.4 — Selectors & specificity
+
+- **`!important` is forbidden.** Cascade fights are solved by adjusting `@layer` order in `global.css`.
+- **Nesting maximum 2 levels deep** inside scoped CSS. Enough for `&:hover` / `& .child`, no deeper.
+- **No ID selectors for styling** (`#foo`). IDs are reserved for anchor targets and JS hooks.
+- **Universal selector `*`** only allowed in `@layer reset` (e.g. `*, *::before, *::after { box-sizing: border-box }`). Forbidden in component CSS.
+- **Prefer `:is()` / `:where()`** for grouped selectors. Use `:where()` to keep specificity at zero for defaults that should be easy to override.
+
+### 2.5 — Anti-Tailwind / framework discipline
+
+**Forbidden — never install, never reference:**
+
+| Category | Examples |
+|---|---|
+| Utility-class frameworks | Tailwind (`tailwindcss`, `@tailwind`, `tailwind.config.*`, `@apply`), UnoCSS, Tachyons, Open Props utilities, Bootstrap utilities |
+| Component-class frameworks | Bulma, Pico, DaisyUI, Bootstrap |
+| CSS-in-JS | styled-components, emotion, stitches, vanilla-extract |
+| Preprocessors | Sass, Less, Stylus |
+
+The native equivalents are already in CSS (`@layer`, nesting, `color-mix()`, relative color syntax,
+container queries, custom properties). Preprocessors add a build step that obscures the platform.
+
+### 2.6 — Modern CSS feature checklist
+
+Before finalizing any CSS, run through this. Each item has a minimum tier — items at or below the
+project's tier are free to use; items above require an `@supports` wrapper or a graceful fallback.
+
+#### Color & theming
+- [ ] **CSS custom properties** for repeated values — *Tier 1–3*
+- [ ] **OKLCH** for color definitions — *Tier 2+*
+- [ ] **`color-mix()`** for tints/shades/opacity variants — *Tier 2+*
+- [ ] **Relative color syntax** (`oklch(from var(--c) l c h)`) — *Tier 1+*
+- [ ] **`light-dark()`** — *Tier 1, with mandatory fallback (Step 4)*
+- [ ] **`accent-color`** for native form controls — *Tier 2+*
+
+#### Layout & sizing
+- [ ] **`clamp()`** for fluid typography and spacing — *Tier 2+*
+- [ ] **`min()` / `max()`** for bounded sizing — *Tier 2+*
+- [ ] **Dynamic viewport units** (`svh`, `dvh`, `lvh`) instead of `100vh` — *Tier 2+*
+- [ ] **Container queries** for component-level responsiveness instead of viewport media queries — *Tier 2+*
+- [ ] **`subgrid`** when grid children must align across rows/columns — *Tier 2+*
+- [ ] **`aspect-ratio`** instead of the padding-top hack — *Tier 2+*
+- [ ] **`field-sizing: content`** for auto-resizing inputs/textareas — *Tier 1+*
+- [ ] **`margin-trim`** instead of `:last-child` overrides — *Tier 1+*
+
+#### Selectors & logic
+- [ ] **`:has()`** for conditional parent/sibling styling instead of JS class toggling — *Tier 2+*
+- [ ] **`:is()` / `:where()`** to reduce selector repetition — *Tier 2+*
+- [ ] **`@layer`** for cascade management instead of specificity hacks — *Tier 2+*
+- [ ] **`@scope`** for component-scoped styles (rarely needed — Astro scopes automatically) — *Tier 1+*
+- [ ] **CSS nesting** (`&`) instead of repeated selectors — *Tier 2+*
+
+#### Animation & transitions
+- [ ] **Scroll-driven animations** for scroll-linked effects instead of IntersectionObserver + JS — *Tier 2+*
+- [ ] **`@starting-style`** for enter animations on newly displayed elements — *Tier 2+*
+- [ ] **`transition-behavior: allow-discrete`** to animate `display: none` toggling — *Tier 2+*
+- [ ] **`view-transition-name`** for page/component transitions instead of JS animation libraries — *Tier 2+*
+- [ ] **`offset-path`** to animate elements along a curve — *Tier 2+*
+- [ ] **`interpolate-size: allow-keywords`** to animate `height: auto` — *Tier 0 with `@supports`*
+- [ ] Always respect **`prefers-reduced-motion`** — *Tier 1–3*
+
+#### Typography
+- [ ] **`text-wrap: balance`** on headings — *Tier 2+*
+- [ ] **`text-wrap: pretty`** on body paragraphs — *Tier 1+*
+- [ ] **`cap` / `lh` / `rex` units** for cap-height / line-height-relative sizing — *Tier 2+*
+- [ ] **`@font-face size-adjust`** to normalize font fallbacks — *Tier 2+*
+- [ ] **`::marker`** to style list bullets — *Tier 2+*
+
+#### Positioning
+- [ ] **`inset` shorthand** instead of top/right/bottom/left longhand — *Tier 2+*
+- [ ] **Logical properties** (`margin-inline`, `padding-block`) for i18n-ready layouts — *Tier 2+*
+- [ ] **`scroll-margin` / `scroll-padding`** for sticky-header anchor offsets — *Tier 2+*
+- [ ] **Anchor positioning** for tooltips / popovers / dropdowns — *Tier 1, non-critical UI only (Step 4)*
+
+#### Visual effects
+- [ ] **`backdrop-filter`** for frosted glass / blur overlays — *Tier 2+*
+- [ ] **`mix-blend-mode`** + **`isolation`** for CSS compositing — *Tier 2+*
+- [ ] **`clip-path`** for shape masking instead of SVG wrappers — *Tier 2+*
+
+#### Component patterns
+- [ ] **`env(safe-area-inset-*)`** for iOS notch / Dynamic Island safe areas — *Tier 2+*
+- [ ] **`scrollbar-color` / `scrollbar-width`** instead of `::-webkit-scrollbar` — *Tier 2+*
+- [ ] **`overscroll-behavior`** on modals/drawers — *Tier 2+*
+- [ ] **`@media (hover: hover)`** to scope hover effects away from touch — *Tier 2+*
+- [ ] **`@media (pointer: coarse)`** for larger touch targets — *Tier 2+*
+- [ ] **`@media (prefers-contrast: more)`** for accessibility — *Tier 2+*
+
+#### Architecture
+- [ ] **`@property`** for typed custom properties that need transitions — *Tier 2+*
+- [ ] **`content-visibility: auto`** on off-screen heavy sections — *Tier 2+*
+- [ ] **`::backdrop`** for dialog/popover overlay styling — *Tier 2+*
+- [ ] **`:popover-open`** for native popover state — *Tier 1+*
+
+---
+
+## Step 3 — Mandatory fallbacks (always, even at Tier 1)
+
+Two features in the Tier-1 checklist have functional-break failure modes for users on slightly
+older browsers (~12% of real-world traffic). Both require fallbacks regardless of tier.
+
+### 3.1 — `light-dark()` always pairs with `prefers-color-scheme`
+
+`light-dark()` returns invalid in Safari 16.x, breaking dark-mode color rendering. Never use it
+bare. Either define dark colors via a media query and skip `light-dark()`, or wrap:
+
+```css
+:root {
+  --color-bg: white;
+  --color-text: black;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: black;
+    --color-text: white;
+  }
+}
+
+/* Optional progressive enhancement using light-dark() */
+@supports (color: light-dark(white, black)) {
+  :root {
+    color-scheme: light dark;
+    --color-bg: light-dark(white, black);
+    --color-text: light-dark(black, white);
+  }
+}
+```
+
+### 3.2 — Anchor positioning only for non-critical UI
+
+Anchor positioning is Chrome-only as of Tier 1's floor (no Safari/Firefox support yet in stable).
+Use it only where a position fallback to default location is acceptable:
+
+- ✅ Decorative tooltips that enhance but aren't required for understanding.
+- ✅ Hover hints on icons.
+- 🔴 Never: form validation popovers, menu dropdowns that users must reach, command palettes.
+
+For critical UI, use `position: absolute` with manual coordinates or the Popover API's default
+top-layer placement.
+
+---
+
+## Step 4 — Interactivity ladder
+
+Before adding any JavaScript to a component, walk the ladder. Move to the next tier only when the
+current tier truly cannot express the behavior.
+
+### Tier 1 — CSS only
+
+Try these first:
+
+| Behavior | CSS pattern |
+|---|---|
+| Focus reveal | `:focus-within` on the form/section wrapper |
+| Value reveal | `:not(:has(:placeholder-shown))`, `:valid`, `:invalid` |
+| Accordion / collapsible | `<details>` / `<summary>` |
+| Tabs | radio inputs + `:checked` + sibling selectors |
+| Hover chrome | `@media (hover: hover)` + `:hover` / `:focus-visible` |
+| Carousel (content) | `scroll-snap-type` + scroll-driven animations for pagination state |
+| Mobile nav drawer | `:popover-open` + `<button popovertarget>` (with native popover), or checkbox-hack as fallback |
+| Tooltips (decorative) | anchor positioning + `:hover` / `:focus-visible` |
+| Entrance animations | `@starting-style` + `transition-behavior: allow-discrete` |
+| Exit animations | `transition-behavior: allow-discrete` on `display` transitions |
+| Sticky reveal on scroll | scroll-driven animations |
+
+### Tier 2 — Vanilla `<script>` in the `.astro` component
+
+Use when CSS truly can't express the behavior and side effects are bounded. **Not an island** —
+just a `<script>` block in the Astro component. No framework, no hydration.
+
+| Behavior | Pattern |
+|---|---|
+| Theme toggle / persistence | Read/write `localStorage`, set `data-theme` on `<html>`. Apply in a sync script in `<head>` to avoid flash. |
+| Modal open/close | Native `<dialog>` + `dialog.showModal()` / `dialog.close()` |
+| Copy-to-clipboard | `navigator.clipboard.writeText()` on click |
+| Smooth-scroll with offset | When CSS `scroll-margin` is insufficient |
+| Analytics events | Click/scroll listeners that post to an analytics endpoint |
+| ARIA-correct tablist | When the radio-button tabs pattern doesn't meet accessibility requirements |
+| Native popover programmatic control | `popover.showPopover()` / `.hidePopover()` |
+
+### Tier 3 — Astro island (last resort)
+
+Add `client:load` / `client:idle` / `client:visible` / `client:only` to a framework component
+**only** when:
+
+- Stateful UI with derived state across multiple inputs (complex form validation, multi-step wizard).
+- Real-time updates from a data source (live feeds, chat, websocket-driven UI).
+- Interactive data visualization where the framework's reactivity is the cleanest expression.
+- A third-party widget requires the framework wrapper (rare).
+
+For everything else, descend the ladder.
+
+---
+
+## Step 5 — Reference files
+
+Load these on demand for exact syntax, browser version floors, and `@supports` patterns:
+
+- `references/color.md` — OKLCH, `color-mix`, relative color, `light-dark`
+- `references/layout.md` — `clamp`, container queries, subgrid, `field-sizing`, dvh units, math functions
+- `references/selectors.md` — `:has()`, `@layer`, `@scope`, nesting
+- `references/animation.md` — scroll-driven, `@starting-style`, view transitions, `offset-path`
+- `references/typography.md` — `text-wrap`, `cap` unit, `font-size-adjust`, `::marker`
+- `references/positioning.md` — anchor positioning, logical properties, `scroll-margin`
+- `references/misc.md` — `@property`, `content-visibility`, popover, `backdrop-filter`, blend modes, `clip-path`
+- `references/components.md` — `accent-color`, `env()`, media features, scrollbar, `margin-trim`, scroll-snap
+
+Load only the file relevant to the feature you're using. Do not load all references at once.
+
+---
+
+## Constraints
+
+- Always follow MDN Web API references for browser/web API usage.
+- Always follow the Astro 6 documentation: https://docs.astro.build/llms-small.txt
+- All token names use the six canonical namespaces. Inventing a new namespace (e.g. `--ui-*`, `--page-*`) is forbidden.
+- The `.astro-builder/design-system.md` file is the human-readable index of tokens. `global.css` is the source of truth.
+- When new tokens are needed, add to `global.css` first, then document in `design-system.md`.
diff --git a/astro-builder/skills/css-conventions/references/animation.md b/astro-builder/skills/css-conventions/references/animation.md
new file mode 100644
index 0000000..aba5f7f
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/animation.md
@@ -0,0 +1,195 @@
+# Animation & Transitions — Modern CSS Reference
+
+## Scroll-Driven Animations
+**Tier**: 2+ | Chrome 115, Edge 115, Firefox 110, Safari 18 (partial)
+
+Link animations directly to scroll position — no IntersectionObserver or scroll JS needed.
+
+```css
+/* Scroll progress bar */
+@keyframes grow-bar {
+  from { transform: scaleX(0); }
+  to   { transform: scaleX(1); }
+}
+
+.progress-bar {
+  animation: grow-bar linear;
+  animation-timeline: scroll(root);
+  transform-origin: left;
+}
+
+/* Fade in elements as they enter the viewport */
+@keyframes fade-in {
+  from { opacity: 0; translate: 0 2rem; }
+  to   { opacity: 1; translate: 0 0; }
+}
+
+.section {
+  animation: fade-in linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 30%;
+}
+
+/* Named timeline — share one scroll timeline across elements */
+.scroll-container {
+  scroll-timeline-name: --gallery;
+  scroll-timeline-axis: inline;
+  overflow-x: scroll;
+}
+
+.gallery-item {
+  animation: slide-in linear;
+  animation-timeline: --gallery;
+}
+```
+
+**`@supports` guard**:
+```css
+@supports (animation-timeline: scroll()) {
+  .progress-bar {
+    animation: grow-bar linear;
+    animation-timeline: scroll(root);
+  }
+}
+```
+
+---
+
+## `@starting-style`
+**Tier**: 2+ | Chrome 117, Edge 117, Safari 17.5, Firefox 129
+
+Define the style an element transitions *from* when it's first displayed. Enables pure-CSS enter animations.
+
+```css
+dialog {
+  transition: opacity 0.3s, transform 0.3s, display 0.3s allow-discrete, overlay 0.3s allow-discrete;
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Starting state — what it transitions FROM on entry */
+@starting-style {
+  dialog[open] {
+    opacity: 0;
+    transform: translateY(-1rem);
+  }
+}
+
+/* Exit transition */
+dialog:not([open]) {
+  opacity: 0;
+  transform: translateY(-1rem);
+}
+```
+
+---
+
+## `transition-behavior: allow-discrete`
+**Tier**: 2+ | Chrome 117, Safari 17.5, Firefox 129
+
+Required to animate elements in/out of `display: none`.
+
+```css
+.drawer {
+  display: none;
+  opacity: 0;
+  transform: translateX(-100%);
+  transition:
+    display    0.3s allow-discrete,
+    opacity    0.3s,
+    transform  0.3s,
+    overlay    0.3s allow-discrete;
+}
+
+.drawer.is-open {
+  display: block;
+  opacity: 1;
+  transform: translateX(0);
+}
+
+@starting-style {
+  .drawer.is-open {
+    opacity: 0;
+    transform: translateX(-100%);
+  }
+}
+```
+
+---
+
+## View Transitions
+**Tier**: 2+ (same-document) | Chrome 111, Safari 18, Firefox 128
+
+Animate between two states of a page or component.
+
+```css
+.hero-image {
+  view-transition-name: hero;
+}
+
+::view-transition-old(hero) {
+  animation: 300ms ease-out fade-out;
+}
+
+::view-transition-new(hero) {
+  animation: 300ms ease-in fade-in;
+}
+
+/* Cross-document (MPA) */
+@view-transition {
+  navigation: auto;
+}
+```
+
+JS trigger for same-document:
+```js
+document.startViewTransition(() => {
+  updateContent();
+});
+```
+
+---
+
+## `offset-path` — Motion Path
+**Tier**: 2+ | Chrome 115, Safari 15.4, Firefox 72
+
+```css
+@keyframes move-along {
+  from { offset-distance: 0%; }
+  to   { offset-distance: 100%; }
+}
+
+.icon {
+  offset-path: path("M 10,80 C 40,10 65,10 95,80 S 150,150 180,80");
+  offset-rotate: auto;
+  animation: move-along 2s linear infinite;
+}
+
+.orbiter {
+  offset-path: circle(40% at center);
+  animation: move-along 3s linear infinite;
+}
+```
+
+---
+
+## `prefers-reduced-motion`
+**Tier**: 1–3 (always include)
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Or opt-in pattern */
+@media (prefers-reduced-motion: no-preference) {
+  .hero { animation: slide-in 0.6s ease both; }
+}
+```
+
+> Note: this is the **only** allowed `!important` in astro-builder CSS — accessibility reset for reduced motion is the platform convention.
diff --git a/astro-builder/skills/css-conventions/references/color.md b/astro-builder/skills/css-conventions/references/color.md
new file mode 100644
index 0000000..1d25379
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/color.md
@@ -0,0 +1,134 @@
+# Color & Theming — Modern CSS Reference
+
+## CSS Custom Properties
+**Tier**: 1–3 (universal)
+
+```css
+:root {
+  --color-brand: oklch(0.6 0.2 260);
+  --space-md: 1rem;
+  --radius-sm: 0.375rem;
+}
+```
+
+---
+
+## OKLCH Color Space
+**Tier**: 2+ | Chrome 111, Safari 15.4, Firefox 113
+
+Perceptually uniform — equal lightness steps look visually equal. Better for gradients, palettes, and accessible contrast.
+
+```css
+/* oklch(lightness chroma hue) */
+/* lightness: 0–1, chroma: 0–0.4, hue: 0–360 */
+
+.button {
+  background: oklch(0.6 0.2 260);   /* a rich blue */
+  color: oklch(0.98 0 0);           /* near-white */
+}
+
+/* Gradient that stays vivid (no grey muddy middle) */
+.gradient {
+  background: linear-gradient(
+    to right,
+    oklch(0.6 0.2 30),   /* orange */
+    oklch(0.6 0.2 260)   /* blue */
+  );
+}
+```
+
+**`@supports` guard for Tier 3**:
+```css
+.button { background: hsl(220 70% 50%); }
+@supports (color: oklch(0 0 0)) {
+  .button { background: oklch(0.6 0.2 260); }
+}
+```
+
+---
+
+## `color-mix()`
+**Tier**: 2+ | Chrome 111, Safari 16.2, Firefox 113
+
+Mix two colors in any color space. Replaces SCSS `mix()` and manual rgba opacity tricks.
+
+```css
+:root {
+  --color-brand: oklch(0.6 0.2 260);
+  --color-brand-light: color-mix(in oklch, var(--color-brand) 30%, white);
+  --color-brand-dark:  color-mix(in oklch, var(--color-brand) 70%, black);
+  --color-brand-muted: color-mix(in oklch, var(--color-brand), transparent 40%);
+}
+```
+
+---
+
+## Relative Color Syntax
+**Tier**: 1+ | Chrome 119, Safari 16.4, Firefox 128
+
+Derive a new color from an existing one by modifying individual channels.
+
+```css
+:root { --color-brand: oklch(0.6 0.2 260); }
+
+.muted    { color: oklch(from var(--color-brand) l 0.05 h); }  /* desaturate */
+.lighter  { color: oklch(from var(--color-brand) calc(l + 0.2) c h); }
+.opposite { color: oklch(from var(--color-brand) l c calc(h + 180)); }
+```
+
+**`@supports` guard**:
+```css
+@supports (color: oklch(from red l c h)) {
+  .muted { color: oklch(from var(--color-brand) l 0.05 h); }
+}
+```
+
+---
+
+## `light-dark()` Function
+**Tier**: 1+ | Chrome 123, Safari 17.5, Firefox 120
+
+> **astro-builder requires a fallback for this feature regardless of tier.** Safari 16.x returns
+> invalid for `light-dark()`, breaking dark-mode color rendering. See `SKILL.md` Step 3.1.
+
+Single declaration that adapts to `prefers-color-scheme` and `color-scheme` property. Replaces dual `@media` blocks.
+
+```css
+:root {
+  /* Always define base + media-query fallback first */
+  --color-bg: #ffffff;
+  --color-text: #111111;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #1a1a1a;
+    --color-text: #eeeeee;
+  }
+}
+
+/* Progressive enhancement */
+@supports (color: light-dark(#000, #fff)) {
+  :root {
+    color-scheme: light dark; /* required */
+    --color-bg: light-dark(#ffffff, #1a1a1a);
+    --color-text: light-dark(#111111, #eeeeee);
+  }
+}
+```
+
+---
+
+## `accent-color`
+**Tier**: 2+ | Chrome 93, Safari 15.4, Firefox 92
+
+One-line theming for native form controls.
+
+```css
+:root {
+  accent-color: var(--color-primary);
+}
+
+input[type="range"]    { accent-color: oklch(0.7 0.15 150); }
+input[type="checkbox"] { accent-color: var(--color-primary); }
+```
diff --git a/astro-builder/skills/css-conventions/references/components.md b/astro-builder/skills/css-conventions/references/components.md
new file mode 100644
index 0000000..0ba4588
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/components.md
@@ -0,0 +1,178 @@
+# Component Patterns — Modern CSS Reference
+
+## `accent-color`
+**Tier**: 2+ | Chrome 93, Safari 15.4, Firefox 92
+
+One-line theming for native form controls: checkboxes, radios, range inputs, progress bars.
+
+```css
+:root {
+  accent-color: var(--color-primary);
+}
+
+input[type="range"]    { accent-color: oklch(0.7 0.15 150); }
+input[type="checkbox"] { accent-color: var(--color-primary); }
+```
+
+---
+
+## `env()` Variables
+**Tier**: 2+ | Chrome 69, Safari 11.1, Firefox 65
+
+Access environment variables — critical for iOS safe areas (notch, Dynamic Island, home indicator).
+
+```css
+.navbar {
+  padding-top: env(safe-area-inset-top);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+.bottom-nav {
+  padding-bottom: max(env(safe-area-inset-bottom), var(--space-m));
+}
+
+:root {
+  --safe-top:    env(safe-area-inset-top, 0px);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
+}
+```
+
+Requires `<meta name="viewport" content="viewport-fit=cover">` to activate safe areas.
+
+---
+
+## Media Feature Queries — Beyond Viewport Size
+
+### `(hover: hover)` and `(pointer: fine)`
+**Tier**: 2+ | Chrome 41, Safari 9, Firefox 64
+
+```css
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+  .button:hover { background: var(--color-primary-dark); }
+}
+
+@media (pointer: coarse) {
+  .button { min-height: 44px; padding-inline: var(--space-m); }
+}
+
+@media (pointer: fine) {
+  .data-table td { padding: var(--space-xs) var(--space-s); }
+}
+```
+
+### `(prefers-contrast: more)`
+**Tier**: 2+ | Chrome 96, Safari 14.1, Firefox 101
+
+```css
+@media (prefers-contrast: more) {
+  :root {
+    --color-text: #000000;
+    --color-bg:   #ffffff;
+  }
+
+  .button {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+}
+```
+
+### `(display-mode: standalone)`
+**Tier**: 2+ | Chrome 45, Safari 13, Firefox 89
+
+```css
+@media (display-mode: standalone) {
+  .install-banner { display: none; }
+  .navbar { padding-top: env(safe-area-inset-top); }
+}
+```
+
+### `(scripting: none)`
+**Tier**: 1+ | Chrome 120, Safari 17, Firefox 113
+
+Progressive enhancement — show fallback content when JS is unavailable.
+
+```css
+.accordion-content { display: none; }
+
+@media (scripting: none) {
+  .accordion-content { display: block; }
+  .accordion-toggle  { display: none; }
+}
+```
+
+---
+
+## `scrollbar-color` / `scrollbar-width`
+**Tier**: 2+ | Chrome 121, Safari 18.2, Firefox 64
+
+Style scrollbars natively — no `::-webkit-scrollbar` hack needed.
+
+```css
+:root {
+  scrollbar-color: var(--color-primary) transparent;
+  scrollbar-width: thin;
+}
+
+.sidebar {
+  scrollbar-color: var(--color-text-muted) transparent;
+  scrollbar-width: thin;
+  overflow-y: auto;
+}
+
+.carousel {
+  scrollbar-width: none;
+  overflow-x: scroll;
+}
+```
+
+---
+
+## `margin-trim`
+**Tier**: 1+ | Safari 16.4, Chrome 130 (Firefox in progress)
+
+Remove the leading/trailing margin of children at the container edge.
+
+```css
+.card-body {
+  margin-trim: block;
+}
+
+.tag-list {
+  display: flex;
+  margin-trim: inline;
+}
+```
+
+**`@supports` guard**:
+```css
+@supports (margin-trim: block) {
+  .card-body { margin-trim: block; }
+}
+```
+
+---
+
+## Scroll Snap (carousels & galleries)
+**Tier**: 2+
+
+```css
+.carousel {
+  display: flex;
+  overflow-x: scroll;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+  scrollbar-width: none;
+}
+
+.carousel-item {
+  scroll-snap-align: start;
+  flex: 0 0 100%;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .carousel { scroll-behavior: auto; }
+}
+```
diff --git a/astro-builder/skills/css-conventions/references/layout.md b/astro-builder/skills/css-conventions/references/layout.md
new file mode 100644
index 0000000..59e4229
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/layout.md
@@ -0,0 +1,186 @@
+# Layout & Sizing — Modern CSS Reference
+
+## `min()`, `max()`, `clamp()`
+**Tier**: 2+ | Chrome 79, Safari 11.1, Firefox 75
+
+Replace breakpoint-heavy sizing with fluid, math-driven values.
+
+```css
+/* clamp(min, preferred, max) */
+h1 { font-size: clamp(1.5rem, 4vw + 1rem, 3.5rem); }
+.container { width: clamp(320px, 90%, 1200px); }
+
+/* min() — never exceeds the smallest value */
+.sidebar { width: min(300px, 100%); }
+
+/* max() — never goes below the largest value */
+.hero { padding: max(2rem, 5vh); }
+
+/* Fluid spacing tokens — define once in global.css */
+:root {
+  --space-s: clamp(0.75rem, 1.5vw, 1rem);
+  --space-m: clamp(1rem,    2vw,   1.5rem);
+  --space-l: clamp(1.5rem,  4vw,   3rem);
+}
+```
+
+---
+
+## Container Queries
+**Tier**: 2+ | Chrome 105, Safari 16, Firefox 110
+
+Style components based on their container size, not the viewport.
+
+```css
+.card-wrapper {
+  container-type: inline-size;
+  container-name: card;
+}
+
+@container card (min-width: 400px) {
+  .card { display: grid; grid-template-columns: 1fr 2fr; }
+}
+
+@container (min-width: 600px) {
+  .card-title { font-size: var(--text-2xl); }
+}
+```
+
+### Container Query Units
+```css
+/* cqw = 1% of container width, cqh = 1% of container height */
+.card-heading {
+  font-size: clamp(1rem, 4cqw, 2rem);
+}
+```
+
+---
+
+## Subgrid
+**Tier**: 2+ | Chrome 117, Safari 16, Firefox 71
+
+Align grid items across nested grid contexts.
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: auto auto auto;
+  gap: var(--space-m);
+}
+
+.card {
+  display: grid;
+  grid-row: span 3;
+  grid-template-rows: subgrid;
+}
+```
+
+---
+
+## `aspect-ratio`
+**Tier**: 2+ | Chrome 88, Safari 15, Firefox 89
+
+Replace the padding-top hack entirely.
+
+```css
+.video  { aspect-ratio: 16 / 9; width: 100%; }
+.avatar { aspect-ratio: 1; border-radius: 50%; }
+```
+
+---
+
+## `field-sizing: content`
+**Tier**: 1+ | Chrome 123 (Safari / Firefox in progress)
+
+Auto-resize `<input>` and `<textarea>` to fit their content — no JS needed.
+
+```css
+textarea {
+  field-sizing: content;
+  min-height: 3lh;
+  max-height: 20lh;
+  resize: none;
+}
+
+input[type="text"] {
+  field-sizing: content;
+  min-width: 10ch;
+}
+```
+
+**`@supports` guard for Tier 2/3**:
+```css
+@supports (field-sizing: content) {
+  textarea { field-sizing: content; resize: none; }
+}
+```
+
+---
+
+## Intrinsic Sizing Keywords
+**Tier**: 2+ | broadly supported
+
+```css
+.sidebar  { width: min-content; }
+.tag      { width: max-content; }
+.card     { width: fit-content(400px); }
+```
+
+---
+
+## Dynamic Viewport Units
+**Tier**: 2+ | Chrome 108, Safari 15.4, Firefox 101
+
+Solve the classic `100vh` mobile browser bar problem.
+
+```css
+.hero    { height: 100svh; } /* always fully visible */
+.overlay { height: 100dvh; } /* tracks actual available height */
+.panel   { min-height: 100svh; max-height: 100lvh; }
+```
+
+---
+
+## CSS Math Functions — `round()`, `mod()`, `rem()`, `abs()`, `sign()`
+**Tier**: 2+ | Chrome 125, Safari 15.4, Firefox 118
+
+```css
+.card {
+  width: round(var(--container-width), 8px); /* snap to 8px grid */
+}
+
+.font { font-size: round(nearest, 1.7rem, 0.25rem); }
+.box  { width: round(up, 33.3%, 1px); }
+
+.offset { translate: abs(var(--x)) 0; }
+
+.arrow {
+  rotate: calc(sign(var(--delta)) * 45deg);
+}
+```
+
+---
+
+## `margin-trim`
+**Tier**: 1+ | Safari 16.4, Chrome 130 (Firefox in progress)
+
+Remove the leading/trailing margin of children at the container edge.
+
+```css
+.card-body {
+  margin-trim: block;
+}
+
+.tag-list {
+  display: flex;
+  margin-trim: inline;
+}
+```
+
+**`@supports` guard**:
+```css
+@supports (margin-trim: block) {
+  .card-body { margin-trim: block; }
+}
+```
diff --git a/astro-builder/skills/css-conventions/references/misc.md b/astro-builder/skills/css-conventions/references/misc.md
new file mode 100644
index 0000000..3e19463
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/misc.md
@@ -0,0 +1,246 @@
+# Miscellaneous — Modern CSS Reference
+
+## `@property`
+**Tier**: 2+ | Chrome 85, Safari 16.4, Firefox 128
+
+Define typed custom properties. Enables transitions on custom properties and prevents inheritance.
+
+```css
+@property --angle {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+.button {
+  --angle: 0deg;
+  background: conic-gradient(from var(--angle), var(--color-primary), var(--color-accent));
+  transition: --angle 1s;
+}
+
+.button:hover { --angle: 360deg; }
+
+/* Clamped/ranged custom properties */
+@property --progress {
+  syntax: "<percentage>";
+  inherits: false;
+  initial-value: 0%;
+}
+```
+
+---
+
+## `content-visibility`
+**Tier**: 2+ | Chrome 85, Edge 85, Firefox 125 (Safari partial)
+
+Skip rendering off-screen content. Significant performance boost for long pages.
+
+```css
+.page-section {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 400px;
+}
+
+.offscreen-panel {
+  content-visibility: hidden;
+}
+```
+
+---
+
+## `overscroll-behavior`
+**Tier**: 2+ | Chrome 63, Safari 16, Firefox 59
+
+Stop scroll events from propagating to the page when a scrollable element hits its boundary.
+
+```css
+.modal {
+  overflow-y: auto;
+  overscroll-behavior-y: contain;
+}
+
+.carousel {
+  overflow-x: scroll;
+  overscroll-behavior-x: contain;
+}
+
+html {
+  overscroll-behavior: none;
+}
+```
+
+---
+
+## `::backdrop`
+**Tier**: 2+ | Chrome 67, Safari 15.4, Firefox 47
+
+Style the backdrop of `<dialog>`, fullscreen elements, or popovers.
+
+```css
+dialog::backdrop {
+  background: oklch(0 0 0 / 0.5);
+  backdrop-filter: blur(4px);
+  transition: opacity 0.3s;
+}
+
+[popover]::backdrop {
+  background: transparent;
+}
+```
+
+---
+
+## Popover API
+**Tier**: 1+ | Chrome 114, Safari 17, Firefox 125
+
+Native popovers without JS positioning libraries.
+
+```html
+<button popovertarget="my-menu">Open</button>
+<div id="my-menu" popover>Menu content</div>
+```
+
+```css
+[popover] {
+  opacity: 0;
+  transform: translateY(-0.5rem);
+  transition: opacity 0.2s, transform 0.2s,
+              display 0.2s allow-discrete,
+              overlay 0.2s allow-discrete;
+}
+
+[popover]:popover-open {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: translateY(-0.5rem);
+  }
+}
+```
+
+---
+
+## `scroll-snap`
+**Tier**: 2+ | Chrome 69, Safari 11, Firefox 68
+
+```css
+.carousel {
+  display: flex;
+  overflow-x: scroll;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+}
+
+.carousel-item {
+  scroll-snap-align: start;
+  flex: 0 0 100%;
+}
+```
+
+---
+
+## `image-set()`
+**Tier**: 2+ | Chrome 113, Safari 17.2, Firefox 89
+
+Responsive images in CSS — like `srcset` for background images.
+
+```css
+.hero {
+  background-image: image-set(
+    url("hero.avif") type("image/avif"),
+    url("hero.webp") type("image/webp"),
+    url("hero.jpg")  type("image/jpeg")
+  );
+}
+```
+
+---
+
+## `backdrop-filter`
+**Tier**: 2+ | Chrome 76, Safari 9 (prefixed), Firefox 103
+
+```css
+.navbar {
+  background: oklch(1 0 0 / 0.7);
+  backdrop-filter: blur(12px) saturate(180%);
+  -webkit-backdrop-filter: blur(12px) saturate(180%);
+}
+
+.glass-card {
+  background: oklch(1 0 0 / 0.15);
+  backdrop-filter: blur(16px) brightness(1.1);
+  border: 1px solid oklch(1 0 0 / 0.3);
+}
+```
+
+---
+
+## `mix-blend-mode` + `isolation`
+**Tier**: 2+ | Chrome 41, Safari 8, Firefox 32
+
+```css
+.blend-title {
+  mix-blend-mode: multiply;
+  color: var(--color-primary);
+}
+
+.card {
+  isolation: isolate;
+}
+
+.card-overlay {
+  mix-blend-mode: overlay;
+  background: oklch(0.6 0.2 30 / 0.5);
+}
+```
+
+---
+
+## `clip-path` with `path()` and `shape()`
+**Tier**: `path()` Tier 2+ | `shape()` Tier 1 (Chrome 132+)
+
+```css
+.avatar   { clip-path: circle(50%); }
+.chevron  { clip-path: polygon(0 0, 100% 0, 85% 100%, 15% 100%); }
+
+.blob {
+  clip-path: path("M 0,100 C 20,80 80,80 100,100 L 100,0 L 0,0 Z");
+}
+
+@supports (clip-path: shape(from 0% 0%, line to 100% 0%)) {
+  .card {
+    clip-path: shape(
+      from 0% 0%,
+      line to 100% 0%,
+      line to 100% calc(100% - 2rem),
+      arc to 0% calc(100% - 2rem) of 2rem cw,
+      close
+    );
+  }
+}
+```
+
+---
+
+## `border-image` Gradient Borders
+**Tier**: 2+ | Chrome 56, Safari 9.1, Firefox 50
+
+```css
+.card {
+  border: 2px solid transparent;
+  border-image: linear-gradient(135deg, var(--color-primary), var(--color-accent)) 1;
+}
+
+/* Rounded gradient border — needs background-clip */
+.rounded-gradient-border {
+  background:
+    linear-gradient(var(--color-bg), var(--color-bg)) padding-box,
+    linear-gradient(135deg, var(--color-primary), var(--color-accent)) border-box;
+  border: 2px solid transparent;
+  border-radius: var(--radius-lg);
+}
+```
diff --git a/astro-builder/skills/css-conventions/references/positioning.md b/astro-builder/skills/css-conventions/references/positioning.md
new file mode 100644
index 0000000..591ee36
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/positioning.md
@@ -0,0 +1,129 @@
+# Positioning — Modern CSS Reference
+
+## Anchor Positioning
+**Tier**: 1+ | Chrome 125, Edge 125 (Safari / Firefox in progress)
+
+> **astro-builder rule:** use only for **non-critical UI** (decorative tooltips, hover hints).
+> For form validation popovers, menu dropdowns, or any UI users must reach, use `position: absolute`
+> with manual coordinates or the Popover API's default top-layer placement. See `SKILL.md` Step 3.2.
+
+Position an element relative to any other element on the page — no JS `getBoundingClientRect()` needed.
+
+```css
+/* 1. Name the anchor */
+.trigger {
+  anchor-name: --my-anchor;
+}
+
+/* 2. Position relative to it */
+.tooltip {
+  position: absolute;
+  position-anchor: --my-anchor;
+
+  top:    anchor(bottom);
+  left:   anchor(center);
+  translate: -50% 0;
+  margin-top: var(--space-xs);
+}
+
+/* 3. Fallback positions */
+@position-try --flip-above {
+  top:    auto;
+  bottom: anchor(top);
+  margin-top: 0;
+  margin-bottom: var(--space-xs);
+}
+
+.tooltip {
+  position-try-fallbacks: --flip-above, --flip-left;
+  position-try-order: most-width;
+}
+```
+
+**`@supports` guard**:
+```css
+@supports (anchor-name: --x) {
+  .tooltip {
+    position: absolute;
+    position-anchor: --my-anchor;
+    top: anchor(bottom);
+  }
+}
+```
+
+---
+
+## `inset` Shorthand
+**Tier**: 2+ | Chrome 87, Safari 14.1, Firefox 87
+
+```css
+.overlay { inset: 0; }
+.modal   { inset: var(--space-m); }
+.tooltip { inset: auto auto 0 50%; } /* top right bottom left */
+```
+
+---
+
+## Logical Properties
+**Tier**: 2+ | Chrome 89, Safari 15, Firefox 87
+
+Writing-mode aware layout — essential for i18n (RTL, vertical text).
+
+```css
+/* Physical → Logical mapping */
+/* margin-left   → margin-inline-start */
+/* margin-right  → margin-inline-end */
+/* margin-top    → margin-block-start */
+/* margin-bottom → margin-block-end */
+
+.card {
+  margin-inline:  auto;
+  margin-block:   var(--space-m);
+  padding-inline: var(--space-l);
+  padding-block:  var(--space-m);
+
+  border-inline-start: 3px solid var(--color-primary);
+}
+
+.icon {
+  inline-size:  1.5rem;
+  block-size:   1.5rem;
+  max-inline-size: 100%;
+}
+```
+
+---
+
+## `position: sticky` with Logical Offsets
+**Tier**: 2+
+
+```css
+.sticky-header {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 10;
+}
+```
+
+---
+
+## `scroll-margin` / `scroll-padding`
+**Tier**: 2+ | Chrome 69, Safari 14.1, Firefox 68
+
+Offset scroll-to-anchor positions — essential when a sticky header covers anchor targets.
+
+```css
+:root { --header-height: 4rem; }
+
+html { scroll-padding-top: var(--header-height); }
+
+.section {
+  scroll-margin-top: calc(var(--header-height) + var(--space-m));
+}
+
+html { scroll-behavior: smooth; }
+
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+}
+```
diff --git a/astro-builder/skills/css-conventions/references/selectors.md b/astro-builder/skills/css-conventions/references/selectors.md
new file mode 100644
index 0000000..52cb90c
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/selectors.md
@@ -0,0 +1,146 @@
+# Selectors & Logic — Modern CSS Reference
+
+## `:has()` Selector
+**Tier**: 2+ | Chrome 105, Safari 15.4, Firefox 121
+
+The "parent selector". Conditionally style an element based on what it contains, or based on a sibling.
+
+```css
+/* Style a card that contains an image */
+.card:has(img) { grid-template-columns: 1fr 2fr; }
+
+/* Form field with error */
+.field:has(input:invalid) label { color: var(--color-error); }
+
+/* Nav item that is or contains the current page link */
+.nav-item:has(> [aria-current="page"]) {
+  background: var(--color-active-bg);
+  font-weight: 600;
+}
+
+/* Select the label BEFORE a focused input (sibling, not parent) */
+:has(+ input:focus) { color: var(--color-primary); }
+
+/* Table row that has a checked checkbox */
+tr:has(input[type="checkbox"]:checked) {
+  background: color-mix(in oklch, var(--color-primary) 10%, transparent);
+}
+```
+
+**`@supports` guard**:
+```css
+@supports selector(:has(a)) {
+  .card:has(img) { grid-template-columns: 1fr 2fr; }
+}
+```
+
+---
+
+## `:is()` and `:where()`
+**Tier**: 2+ | Chrome 88, Safari 14, Firefox 78
+
+Group selectors without repeating them. `:is()` keeps specificity of highest selector. `:where()` has zero specificity.
+
+```css
+/* Instead of h1 a, h2 a, h3 a, h4 a */
+:is(h1, h2, h3, h4) a { color: var(--color-primary); }
+
+/* Zero-specificity reset */
+:where(ul, ol) { list-style: none; margin: 0; padding: 0; }
+```
+
+---
+
+## CSS Nesting
+**Tier**: 2+ | Chrome 112, Safari 17.2, Firefox 117
+
+Native `&` nesting — no preprocessor required. Inside astro-builder, **max 2 levels deep**.
+
+```css
+.card {
+  padding: var(--space-m);
+  border-radius: var(--radius-md);
+
+  & .card-title {
+    font-size: var(--text-xl);
+  }
+
+  &:hover {
+    box-shadow: var(--shadow-md);
+  }
+
+  @media (min-width: 40rem) {
+    display: grid;
+    grid-template-columns: 1fr 2fr;
+  }
+}
+```
+
+---
+
+## `@layer`
+**Tier**: 2+ | Chrome 99, Safari 15.4, Firefox 97
+
+Explicit cascade layer ordering. astro-builder mandates four layers in `global.css`:
+
+```css
+@layer reset, tokens, base, utilities;
+
+@layer reset {
+  *, *::before, *::after { box-sizing: border-box; }
+}
+
+@layer tokens {
+  :root {
+    --color-primary: oklch(0.6 0.2 260);
+    /* ... */
+  }
+}
+
+@layer base {
+  body { font-family: var(--font-body); color: var(--color-text); }
+}
+
+@layer utilities {
+  .sr-only { position: absolute; width: 1px; height: 1px; clip: rect(0,0,0,0); }
+}
+```
+
+Component-scoped `<style>` blocks don't need `@layer` — Astro's scoping handles isolation.
+
+---
+
+## `@scope`
+**Tier**: 1+ | Chrome 118, Safari 17.4 (Firefox in progress)
+
+Rarely needed in astro-builder — Astro's scoped `<style>` blocks already isolate styles.
+Use only when you genuinely need scope-within-scope (e.g. a content-rendered article needs its
+own scoping inside a layout's scoped block).
+
+```css
+@scope (.prose) to (.no-prose) {
+  h2 { font-size: var(--text-2xl); }
+  p  { color: var(--color-text-muted); }
+}
+```
+
+**`@supports` guard**:
+```css
+@supports at-rule(@scope) {
+  @scope (.prose) { h2 { font-size: var(--text-2xl); } }
+}
+```
+
+---
+
+## `:nth-child(An+B of S)`
+**Tier**: 1+ | Chrome 111, Safari 9, Firefox 113
+
+Filter `nth-child` by a selector — skip non-matching siblings when counting.
+
+```css
+/* Every other .post (ignores .ad elements in the count) */
+.post:nth-child(2n of .post) {
+  background: var(--color-surface);
+}
+```
diff --git a/astro-builder/skills/css-conventions/references/typography.md b/astro-builder/skills/css-conventions/references/typography.md
new file mode 100644
index 0000000..2d85dec
--- /dev/null
+++ b/astro-builder/skills/css-conventions/references/typography.md
@@ -0,0 +1,165 @@
+# Typography — Modern CSS Reference
+
+## `text-wrap: balance`
+**Tier**: 2+ | Chrome 114, Safari 17.5, Firefox 121
+
+Evenly distributes words across lines in headings. Eliminates awkward single-word orphans.
+Use on headings — browser limits it to ~6 lines for performance.
+
+```css
+h1, h2, h3, h4, .card-title, .hero-headline {
+  text-wrap: balance;
+}
+```
+
+---
+
+## `text-wrap: pretty`
+**Tier**: 1+ | Chrome 117, Edge 117 (Safari / Firefox in progress)
+
+Like `balance` but for body text — prevents orphaned last words. No line limit.
+
+```css
+p, li, blockquote {
+  text-wrap: pretty;
+}
+```
+
+**Combined pattern**:
+```css
+:is(h1, h2, h3, h4, h5, h6, .heading) { text-wrap: balance; }
+:is(p, li, blockquote, figcaption)     { text-wrap: pretty; }
+```
+
+---
+
+## `cap` and `lh` Units
+**Tier**: 2+ | Chrome 109, Safari 16.4, Firefox 110 (`cap`); Chrome 109, Safari 17, Firefox 120 (`lh`)
+
+- `cap` = height of a capital letter in the current font
+- `lh` = current `line-height`
+- `rlh` = root `line-height`
+- `rex` = x-height of root font
+
+```css
+/* Icon aligned to cap height */
+.icon {
+  width: 1cap;
+  height: 1cap;
+  vertical-align: middle;
+}
+
+/* Textarea min/max in line units */
+textarea {
+  min-height: 3lh;
+  max-height: 20lh;
+}
+
+/* Consistent rhythm */
+.section {
+  padding-block: 2rlh;
+}
+```
+
+---
+
+## `font-size-adjust`
+**Tier**: 2+ | Chrome 127, Safari 17, Firefox 118 (`from-font` value)
+
+Normalizes x-height across font fallbacks so text doesn't jump size while the web font loads.
+
+```css
+body {
+  font-family: var(--font-body);
+  font-size-adjust: from-font;
+}
+
+/* Or manual value */
+body {
+  font-size-adjust: 0.52;
+}
+```
+
+---
+
+## `hyphenate-limit-chars`
+**Tier**: 2+ | Chrome 109, Safari 17 (Firefox partial)
+
+```css
+p {
+  hyphens: auto;
+  hyphenate-limit-chars: 8 4 3;
+}
+```
+
+---
+
+## `initial-letter`
+**Tier**: 1+ | Chrome 110, Safari 9 (prefixed), Firefox 130
+
+Drop caps natively.
+
+```css
+p::first-letter {
+  initial-letter: 3;
+  color: var(--color-primary);
+  margin-right: 0.125em;
+}
+```
+
+---
+
+## `::marker`
+**Tier**: 2+ | Chrome 86, Safari 14.1, Firefox 68
+
+Style list bullets and numbers without `::before` hacks.
+
+```css
+li::marker {
+  color: var(--color-primary);
+  font-size: 0.75em;
+}
+
+ol li::marker {
+  color: var(--color-primary);
+  font-weight: 700;
+}
+
+ul.checklist li::marker {
+  content: "✓ ";
+  color: oklch(0.6 0.2 145);
+}
+```
+
+---
+
+## `counter()` / `counter-reset` / `counter-increment`
+**Tier**: 2+ | broadly supported
+
+CSS-only numbered steps without JS or manual numbering.
+
+```css
+.steps { counter-reset: step; }
+
+.steps li {
+  counter-increment: step;
+}
+
+.steps li::before {
+  content: "Step " counter(step);
+  display: block;
+  font-weight: 700;
+  color: var(--color-primary);
+}
+
+/* Nested counters — "1.1", "1.2", "2.1" */
+ol {
+  counter-reset: section;
+  list-style: none;
+}
+
+ol li { counter-increment: section; }
+ol li::before {
+  content: counters(section, ".") " ";
+}
+```
diff --git a/astro-builder/skills/init/SKILL.md b/astro-builder/skills/init/SKILL.md
index 79a34ba..440d82f 100644
--- a/astro-builder/skills/init/SKILL.md
+++ b/astro-builder/skills/init/SKILL.md
@@ -37,7 +37,7 @@ Try to read `CLAUDE.md` → check if it was generated by astro-builder (look for
 
 | Round | Complete when |
 |-------|---------------|
-| project | `CLAUDE.md` exists AND all four files exist: `.astro-builder/style-guide.md`, `.astro-builder/content-schema.md`, `.astro-builder/design-system.md`, `.astro-builder/anti-patterns.md` |
+| project | `CLAUDE.md` exists AND all five files exist: `.astro-builder/style-guide.md`, `.astro-builder/content-schema.md`, `.astro-builder/design-system.md`, `.astro-builder/anti-patterns.md`, `src/styles/global.css` |
 | lighthouse | `.astro-builder/lighthouse.json` exists AND `.astro-builder/pre-push.sh` exists AND `.husky/pre-push` exists |
 
 Use 🔄 (started) when some but not all required files for a round exist.
diff --git a/astro-builder/skills/init/rounds/project.md b/astro-builder/skills/init/rounds/project.md
index b2d2494..a505d41 100644
--- a/astro-builder/skills/init/rounds/project.md
+++ b/astro-builder/skills/init/rounds/project.md
@@ -37,11 +37,14 @@ Ask what types of content the site will publish. Examples: articles, tutorials,
 - How is it related to other content types (e.g. articles reference glossary entries)?
 
 ### 2.4 Design system
-Ask the user if they have a design reference (Figma, existing CSS, a brand guide URL, or a screenshot folder). If yes, read or fetch it. If no, ask:
-- Primary color (hex or description)?
-- Typography: display font + body font (or "system defaults")?
-- Visual style: minimal, neobrutalist, editorial, clean SaaS, playful?
-- Border style: rounded, sharp, none?
+Ask the user if they have a design reference (Figma, existing CSS, a brand guide URL, or a screenshot folder). If yes, read or fetch it. Otherwise gather the minimum set needed to populate the six token namespaces:
+
+- **Primary color** (hex or description) — used as `--color-primary`; `--color-primary-dark` is derived via `color-mix(in oklch, primary 80%, black)`.
+- **Visual style** — minimal, neobrutalist, editorial, clean SaaS, playful. Drives radius scale (`--radius-*`) and shadow scale (`--shadow-*`).
+- **Display font** + **body font** (or "system defaults"). `--font-mono` always defaults to `ui-monospace, SFMono-Regular, Menlo, monospace`.
+- **Dark mode**: ask if the site should respect `prefers-color-scheme: dark`. Default yes.
+
+Derive the rest. Use OKLCH for all colors. Pick neutral defaults (`--color-bg: white`, `--color-text: #111`, etc.) unless the user provides specifics.
 
 ### 2.5 Component library
 This plugin defaults to custom CSS. Ask the user if they plan to use a different approach. Do not suggest or recommend any library — only mention that custom CSS is the default. Accept whatever the user answers and record it; do not block or warn unless they name a JS-first framework (Next UI, Chakra, etc.), in which case note that heavy JS-first libraries conflict with the Astro 6 + minimal JS constraint.
@@ -58,7 +61,7 @@ Ask where the site will be deployed: Vercel, Netlify, Cloudflare Pages, GitHub P
 
 ## Phase 3 — Generate artifacts
 
-After completing the interview, generate the following files. Confirm with the user before writing: "I'm ready to generate your configuration. This will create `CLAUDE.md` and a `.astro-builder/` folder. Proceed?"
+After completing the interview, generate the following files. Confirm with the user before writing: "I'm ready to generate your configuration. This will create `CLAUDE.md`, a `.astro-builder/` folder, and `src/styles/global.css`. Proceed?"
 
 ### Files to create:
 
@@ -68,10 +71,12 @@ After completing the interview, generate the following files. Confirm with the u
 
 **`.astro-builder/content-schema.md`** — All content types, their fields, relationships, and i18n strategy. Use `docs/init-templates/content-schema.md.template`.
 
-**`.astro-builder/design-system.md`** — Colors, typography, spacing, component patterns. Use `docs/init-templates/design-system.md.template`.
+**`.astro-builder/design-system.md`** — Token namespaces and component patterns. Use `docs/init-templates/design-system.md.template`. The human-readable index for `src/styles/global.css` — keep them in sync.
 
 **`.astro-builder/anti-patterns.md`** — Project-specific anti-patterns derived from the Astro 6 canonical list plus any project-specific rules the user defined.
 
+**`src/styles/global.css`** — Site-wide CSS. Use `docs/init-templates/global.css.template`. Defines all six token namespaces (`--color-*`, `--font-*`, `--text-*`, `--space-*`, `--radius-*`, `--shadow-*`) under `@layer tokens`, plus the four-layer cascade (`reset`, `tokens`, `base`, `utilities`). Derive `--color-primary-dark` via `color-mix(in oklch, var(--color-primary) 80%, black)`. Populate dark-mode overrides if the user opted in. This file is the source of truth for tokens — component CSS in `<style>` blocks references these.
+
 ## Phase 4 — Validate and scaffold
 
 After writing the files:
@@ -82,8 +87,9 @@ After writing the files:
    ```
 2. Verify that `astro.config.ts` (not `.mjs`) exists. If not, offer to create it.
 3. Verify that `src/content.config.ts` exists. If not, offer to create it based on the content schema.
-4. Run `pnpm install` if dependencies need updating.
-5. Run `pnpm build` and report any errors. Fix them autonomously if possible.
+4. Verify `src/styles/global.css` exists and contains `@layer reset, tokens, base, utilities;` plus all six token namespaces (`--color-*`, `--font-*`, `--text-*`, `--space-*`, `--radius-*`, `--shadow-*`). Verify `BaseLayout.astro` (or the root layout) imports it: `import '../styles/global.css'`.
+5. Run `pnpm install` if dependencies need updating.
+6. Run `pnpm build` and report any errors. Fix them autonomously if possible.
 
 ## Phase 5 — Completion summary
 
@@ -98,6 +104,7 @@ Created:
   • .astro-builder/content-schema.md
   • .astro-builder/design-system.md
   • .astro-builder/anti-patterns.md
+  • src/styles/global.css
 ```
 
 What's next? Run `/astro-builder:init lighthouse` to add automated Lighthouse auditing on git push.