New features, improvements, and fixes in every AstroDeck release.
v4.0.1
LatestPatch
Accessibility and canonical URL fixes
Fixed
Demo site canonical, Open Graph, sitemap and robots.txt URLs use https://www.astrodeck.dev, the host the site is served on (the apex domain redirects)
Comparison section: the yes/no icons are announced as images (role="img"), and the scrollable table can be reached with the keyboard
Code blocks on the docs and components pages and scrollable demo regions can be reached with the keyboard
Changelog page: the breaking-changes heading meets the contrast minimum; 404 page: the contact link is underlined, not marked by color alone
Changelog page lists the four 4.0.0 "Added" entries that were only in CHANGELOG.md; a test now keeps both changelogs in sync
v4.0.0
Major
Agent-first website builder kit
Breaking changes / Migrating from 3.x
!Brand, URL, navigation and footer moved from Header, Footer and SEO components into src/config/site.ts and src/config/site-url.mjs. Pages pass plain titles; the layout applies titleTemplate
!Section props: Hero and HeroGradient badge is an object, LogoCloud requires logos, AIFeature is replaced by IntegrationGrid, Contact renders a form only with a form prop, Newsletter requires action, ContentBlock takes an optional image, Features icons are IconName values
!Removed .cursorrules, .windsurfrules and .cursor/rules: Cursor and Windsurf read AGENTS.md
!Removed the Claude Code slash commands (/new-page, /new-section, /theme, /audit, /launch-check, /plenum), the old Claude skills, the astrodeck agent and the six review agents: use the skills in .agents/skills/ and the optional astrodeck-reviewer subagent
!.claude/skills/ is generated: edit .agents/skills/, then run npm run sync:agents. Your own Claude-only skills can live directly in .claude/skills/; the sync leaves folders it does not manage alone
!site.social entries no longer take an icon field (it was never rendered); social links render as text links in the footer
!npm run theme now fails on light-mode primaries that are too bright for text on the background (for example #f97316) and prints a darker suggestion
!npm run check:kpis is replaced by npm run verify; npm run validate is now verify without the build
!The system/ design docs are replaced by .agents/skills/astrodeck-build-site/references/design-system.md
/new-page, /new-section, /theme
/audit, /launch-check, /plenum
npm run check:kpis
After (4.0)
astrodeck-new-page, astrodeck-new-section, astrodeck-theme
vibe2prod, astrodeck-reviewer (Claude Code)
npm run verify
Added
Agent-first workflow: download AstroDeck, open it in your coding agent, describe your site. The astrodeck-build-site skill runs adaptive intake, a structured brief in PROJECT.md, demo cleanup, site config, theme, pages composed from registry sections, npm run verify, the vibe2prod audit and a handover summary
AGENTS.md rewritten as a compact index (golden rules, commands, task → skill, Astro 7 / Tailwind 4 notes). Read natively by Codex, Cursor, GitHub Copilot and Windsurf, by Claude Code via @AGENTS.md in CLAUDE.md, by Gemini CLI via .gemini/settings.json
Portable Agent Skills in .agents/skills/: astrodeck-build-site (intake, brief template, content rules, design system, quality checklist, five site recipes), astrodeck-new-page, astrodeck-new-section, astrodeck-theme, astrodeck-cleanup. .claude/skills/ is a generated mirror (npm run sync:agents)
brief/ drop folder for briefing material (texts, PDFs, DESIGN.md, logos, images, links)
vibe2prod v0.9.2 bundled in .agents/skills/vibe2prod/ (MIT, license included); npm run setup:audit installs its runtime (Lighthouse, axe CLI, Playwright + Chromium)
Central site config src/config/site.ts and src/config/site-url.mjs: name, URL, description, language, title template, logo, navigation, footer, social links, contact, OG image, feature flags
npm run theme: OKLCH color tokens for light and dark mode from a brand color or a DESIGN.md, with a WCAG contrast gate and suggestions
npm run starter:clean (--dry-run, --yes, --keep-blog): removes the demo in one step, driven by starter.manifest.json
npm run verify: Prettier, ESLint, astro check, design lint, docs lint, registry check, skills mirror check, tests, build and checks on the built HTML (one h1, unique titles, meta descriptions, internal links, alt text). npm run verify -- --starter also fails on demo leftovers
npm run lint:design (rules shared with the Claude Code hook), npm run lint:docs (dead paths, version and count drift, skill front matter), npm run check:registry (files, props, page templates, recipes)
Registry entries with useWhen hints and usage examples; IntegrationGrid section; icon set in src/lib/icons.ts
.mcp.json with the Astro Docs MCP and shadcn MCP servers; setup for Codex, Cursor and VS Code in docs/agents/mcp-setup.md; supported agents in docs/agents/supported-agents.md
Eval cases in evals/ (one-sentence brief, Markdown brief, DESIGN.md) for rerunning the workflow with any agent
Optional Claude Code review subagent astrodeck-reviewer
npm run icons: renders the PNG icons and a social image (public/og.png, brand color + logo mark) from public/favicon.svg
src/config/ui.ts: built-in interface text (skip link, menu and theme buttons, contact labels and form, 404 page) in one place, so non-English sites need no component edits
Contact section: hours (opening hours) and mapUrl props; Hero: plain prop without the decorative grid; Features: columns prop (2 or 3)
Built-HTML checks: link-scheme (spaces in tel:/mailto: links) and meta-length (home title 30–60 characters, descriptions 50–160, as in vibe2prod)
Changed
All sections are data-driven: content comes in through props, no AstroDeck copy inside components; forms post to an endpoint you configure
Demo pages use fictional brands and mark demo-only content with data-demo; demo CTAs link where their label says
astrodeck.dev rewritten for 4.0: home page, docs (workflow, config, theme, cleanup, verify, vibe2prod, supported agents, migration), pages overview, section library with the registry snippet per component, llms.txt
README rewritten user-first; CONTRIBUTING points to AGENTS.md and the skill references; maintainer docs in docs/maintainers/
Design rules consolidated into .agents/skills/astrodeck-build-site/references/design-system.md, aligned with the code
Fixed
Missing or duplicate h1 on several demo pages, dead demo links and decorative icons with alt text (found by the built-HTML check)
Contact section without a form no longer leaves an empty column; IntegrationGrid opens only external links in a new tab and renders items without href as plain cards
RSS language is derived from site.locale instead of a hardcoded -us suffix
Found in the 4.0 dogfood runs (docs/maintainers/dogfood-4.0.md): npm test no longer fails after npm run theme or with a template-literal titleTemplate; .vibe2prod/ audit output is ignored by Git, Prettier and ESLint; Contact tel: links strip spaces (invalid HTML); the skip link is no longer hidden behind the sticky header when focused; scroll-reveal content is visible without JavaScript; long words in Hero and Features headings no longer overflow on narrow phones; the starter's placeholder values in src/config/site.ts carry TODO(brief) markers, so a forgotten "Your Site" shows up in the handover check
Footer renders site.social and site.contact (email, phone) when set, as documented
npm run theme also checks the primary color as text on the background (WCAG AA 4.5:1) and suggests a darker shade when it fails; npm run theme and npm run icons accept a globals.css with Windows (CRLF) line endings
npm run sync:agents no longer deletes your own skills in .claude/skills/; it only mirrors the skills that exist in .agents/skills/
Contact and Newsletter forms use native browser validation (no novalidate), so required fields cannot be sent empty
Updated Astro from 7.3.1 to 7.4.7 — includes fixes for XSS via unescaped script/style content in JSX/MDX rendering and CSS injection in View Transitions
Updated Tailwind CSS from 4.3.3 to 4.3.4
Updated @astrojs/react to 6.0.6 and @astrojs/sitemap to 3.7.4; markdown-it and sanitize-html patched
Patched postcss-selector-parser (used by @tailwindcss/typography) against a CPU exhaustion issue
Now requires Node.js 22.23.4 or higher (Astro 7.4 requirement) — engines field and README updated
v3.5.0
Minor
React 19, LLM-Readable Docs, CI & Blog Extras
Upgraded to React 19.2 — shadcn/ui components migrated to the React 19 type APIs (ComponentRef, SubmitEvent)
New /llms.txt and /llms-full.txt (generated from AGENTS.md + README at build time) so AI agents can read the docs directly
GitHub Actions CI workflow runs the full validate pipeline and the build on every push and pull request
New npm run check (astro check) and npm run validate — one command for convention checks, lint, format, and Astro type checking
KPI script now detects registry drift: every section, UI component, and layout must be catalogued in src/registry.json
Blog: reading time on posts and the post list, related posts by shared tags, optimized cover images via the image() schema helper, full article content in the RSS feed
Shared Head component for all layouts; noindex prop available on every layout
Web manifest, PNG favicon fallback, and apple-touch-icon; security headers via vercel.json
Fixed nested links on tag pages and a missing main landmark on the auth layout; sitemap no longer stamps every page with the build date
v3.4.1
Patch
Astro 7.3.1, Blog SEO & Registry Completion
Updated Astro from 7.2.0 to 7.3.1, @astrojs/react to 6.0.5, @astrojs/sitemap to 3.7.4, and all Radix UI packages to their latest patches — npm audit reports 0 vulnerabilities
Blog posts now emit article Open Graph metadata (og:type, published time, author) and BlogPosting JSON-LD structured data
Component registry (src/registry.json) is complete again: HeroGradient, HeroSplit, Accordion, Dialog, DropdownMenu, Select, Tabs, and Tooltip added, Hero prompt prop documented
Accessibility: icon button and select demo on the Components page now have accessible names — Lighthouse Accessibility 100 on every page
Docs updated to the current stack (Astro 7, Vite 8) in AGENTS.md, README, CONTRIBUTING, and the AI agent definitions
Build output (dist/) is no longer tracked in git
v3.4.0
Minor
Astro 7.2 & Tailwind CSS 4.3.3 Update
Updated Astro from 6.4.4 to 7.2.0 (new Rust-based compiler, Vite 8)
Updated Tailwind CSS from 4.3.0 to 4.3.3
Updated @astrojs/react from 5.x to 6.0.2, @astrojs/rss to 4.0.19, @astrojs/sitemap to 3.7.3
Demo video embedded on the homepage and at the top of the README
v3.3.0
Minor
AI-First Homepage
Homepage repositioned around AI-assisted websites: new headline and audience-focused copy (company sites, blogs, portfolios)
Copyable starter prompt in the hero — hand your coding agent a working kickoff prompt instead of downloading manually
New FAQ section on the homepage, including FAQPage structured data
Feature cards now explain the real differentiators: guardrails, one design system, dual With-AI/Manual docs, one-command quality checks
AI section reframed from standards talk to problem/solution, with an honest note on tool integration depth
Stats section now shows Lighthouse-100 proof instead of repeating the AI tool list
v3.2.0
Minor
AI Layer v2 & Production-Readiness Pass
Geist brand fonts now active site-wide (were loaded but never applied)
New convention guard hook for Claude Code — blocks deprecated Astro patterns and design-system drift automatically
New npm run check:kpis — one command for all static convention checks (colors, inline styles, deprecated imports, alt texts, meta descriptions)
Slash commands accept arguments (/new-page, /new-section, /theme, /plenum); review agents are now strictly read-only
Accessibility & validity: 0 W3C errors, Lighthouse Accessibility and Best Practices at 100, WCAG 2.5.8 tap-target sizes on all nav and footer links
Browser theming (theme-color light/dark, color-scheme) and WebSite JSON-LD structured data
Vercel Analytics only renders on Vercel deployments — no more 404 console error on local preview or other hosts
sitemap.xml now emitted alongside sitemap-index.xml; ESLint and Prettier pass cleanly across the entire codebase
v3.1.5
Patch
Astro 6.4.4 & Tailwind CSS 4.3.0 Update
Updated Astro from 6.1.10 to 6.4.4
Updated Tailwind CSS from 4.2.4 to 4.3.0
v3.1.4
Patch
Astro 6.1.10 & Tailwind CSS 4.2.4 Update
Updated Astro from 6.1.7 to 6.1.10
Updated Tailwind CSS from 4.2.2 to 4.2.4
Added DESIGN.md handling note to AGENTS.md (instructs agents how to apply a Google Stitch DESIGN.md when dropped in)