feat(astro-builder): css-conventions skill + design system overhaul (v1.2.0)

.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"
       },

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

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:
 

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

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
 

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