From e5087defa43210bf8f0386331f53aca29b64386e Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 09:24:14 +0200
Subject: [PATCH 1/6] chore: gitignore personal-knowledge memory paths

The `memory` MCP / personal-knowledge-cli scaffolds private,
user-local files into the repo working tree (`.claude/CLAUDE.md`
fence, `.claude/skills/{memory,import-memories,init-memory}/`).
Exclude them so a wayward `git add .` can't push a contributor's
private memory store config into this public marketplace repo.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .gitignore | 6 ++++++
 1 file changed, 6 insertions(+)

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/

From 266c59449d4a7fb9f21c93a2d3be7edf7524c46b Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 15:29:02 +0200
Subject: [PATCH 2/6] feat(astro-builder): add css-conventions skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports and adapts the css-modern-features skill from fe-nuance-nextjs-UAT into
an astro-builder-native discipline skill. Fires whenever CSS is written,
reviewed, or refactored — and before adding any JavaScript to a component.

Enforces six disciplines: token usage, scoping & file location, class naming,
selector & specificity limits, anti-Tailwind / anti-CSS-in-JS, and a Tier-1
modern-CSS feature checklist. Adds an Astro-native three-tier interactivity
ladder (CSS → vanilla script → island) replacing the React-state ladder from
the original. Tier-1 baseline with mandatory fallbacks for light-dark() and
anchor positioning to keep older Safari users readable.

Includes 8 reference files (color, layout, selectors, animation, typography,
positioning, misc, components) loaded on demand for exact syntax and browser
support floors.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 astro-builder/skills/css-conventions/SKILL.md | 331 ++++++++++++++++++
 .../css-conventions/references/animation.md   | 195 +++++++++++
 .../css-conventions/references/color.md       | 134 +++++++
 .../css-conventions/references/components.md  | 178 ++++++++++
 .../css-conventions/references/layout.md      | 186 ++++++++++
 .../skills/css-conventions/references/misc.md | 246 +++++++++++++
 .../css-conventions/references/positioning.md | 129 +++++++
 .../css-conventions/references/selectors.md   | 146 ++++++++
 .../css-conventions/references/typography.md  | 165 +++++++++
 9 files changed, 1710 insertions(+)
 create mode 100644 astro-builder/skills/css-conventions/SKILL.md
 create mode 100644 astro-builder/skills/css-conventions/references/animation.md
 create mode 100644 astro-builder/skills/css-conventions/references/color.md
 create mode 100644 astro-builder/skills/css-conventions/references/components.md
 create mode 100644 astro-builder/skills/css-conventions/references/layout.md
 create mode 100644 astro-builder/skills/css-conventions/references/misc.md
 create mode 100644 astro-builder/skills/css-conventions/references/positioning.md
 create mode 100644 astro-builder/skills/css-conventions/references/selectors.md
 create mode 100644 astro-builder/skills/css-conventions/references/typography.md

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, ".") " ";
+}
+```

From e0b55820c61dd7ef6417d86fd4e3c7ad28dfe7a9 Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 15:29:13 +0200
Subject: [PATCH 3/6] feat(astro-builder): expand design system to six token
 namespaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates design-system.md.template and adds a new global.css.template so init
scaffolds the full token surface the css-conventions skill expects:
--color-*, --font-*, --text-*, --space-*, --radius-*, --shadow-*.

global.css.template ships with the four canonical @layer declarations
(reset, tokens, base, utilities), dark-mode overrides via
prefers-color-scheme, focus-visible, prefers-reduced-motion, and tiny
utilities (.sr-only, .skip-link).

design-system.md.template becomes the human-readable index for global.css —
documents each token namespace as a table and keeps component patterns
(card, button, tag) referencing tokens, not raw values.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../init-templates/design-system.md.template  | 149 ++++++++----
 .../docs/init-templates/global.css.template   | 216 ++++++++++++++++++
 2 files changed, 321 insertions(+), 44 deletions(-)
 create mode 100644 astro-builder/docs/init-templates/global.css.template

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);
+  }
+}

From f1b15526a7517ac92bb7b6f43b3c274b654bb843 Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 15:29:23 +0200
Subject: [PATCH 4/6] feat(astro-builder): wire init to scaffold global.css

The project round now writes src/styles/global.css from the new template as
part of Phase 3, alongside the existing .astro-builder/ artifacts. Phase 4
gains a validation step ensuring the four @layer declarations and all six
token namespaces are present, and that BaseLayout imports global.css.

Interview gathers the minimum input needed to populate every namespace
(primary color, visual style, fonts, optional dark mode); the rest is
derived (e.g. --color-primary-dark via color-mix in oklch).

CLAUDE.md.template now includes a CSS conventions section that points new
projects at the css-conventions skill, summarizing the discipline (tokens
only, scoped <style>, no Tailwind, interactivity ladder).

Status dashboard's "project" round completion check now requires
src/styles/global.css alongside the .astro-builder/ files.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../docs/init-templates/CLAUDE.md.template    | 17 ++++++++++++-
 astro-builder/skills/init/SKILL.md            |  2 +-
 astro-builder/skills/init/rounds/project.md   | 25 ++++++++++++-------
 3 files changed, 33 insertions(+), 11 deletions(-)

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/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.

From e8da8c4cb9a1bac6244f30fd4ae8b43f618fd745 Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 15:29:34 +0200
Subject: [PATCH 5/6] feat(astro-builder): add CSS-conventions audit step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

audit/SKILL.md gains a new Step 4.5 — CSS conventions audit — that sweeps
the codebase for violations of the css-conventions skill: !important, raw
hex/rgb/hsl values outside global.css, Tailwind/utility frameworks,
CSS-in-JS, preprocessors, .module.css files, <style is:global> in
components, inline style="" with standard properties, ID selectors for
styling, and nesting deeper than 2 levels.

P0 for outright forbidden frameworks (Tailwind, CSS-in-JS, preprocessors).
P1 for token / scoping violations. P2 for nesting / ID selectors.

Step 1 also now loads design-system.md and global.css to learn the
project's token names before sweeping.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 astro-builder/skills/audit/SKILL.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

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:

From dfca8c14cbb15478c1dd810dbbc673f6e3e121a7 Mon Sep 17 00:00:00 2001
From: Pedro Camara Junior <pcamarajr@gmail.com>
Date: Sun, 24 May 2026 15:30:39 +0200
Subject: [PATCH 6/6] chore: bump astro-builder to 1.2.0

Adds the css-conventions skill to the registry and documents it in both
the plugin and root READMEs. Updates the "What gets generated by /init"
section to include src/styles/global.css.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json | 2 +-
 README.md                       | 2 +-
 astro-builder/README.md         | 4 +++-
 3 files changed, 5 insertions(+), 3 deletions(-)

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/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
 ```