Design-led Astro Starter is a reusable Astro 7 starter for content-driven sites, bundling a documented visual system, ten swappable theme palettes, MDX blog posts, RSS, and sitemap support.
What is the Design-led Astro Starter?
Design-led Astro Starter is an open-source website starter built on Astro 7 and TypeScript. It takes configuration files and MDX posts as input and produces a static content site with blog, design-system pages, theme switching, an RSS feed, and a sitemap. The starter is MIT-licensed and includes both English and Chinese README documentation.
Key Features
- Ten theme palettes — Retro Blue (default), Minimal Mono, Forest Green, Vellum Ink, Creator Yellow, Precision Orange, Comic Pulp, Midnight Pastel, Sky Blue, and Signal Red; all override the same semantic CSS tokens so components keep working across themes.
- Astro 7 + TypeScript — built on Astro 7 with TypeScript, Tailwind CSS v4 via @tailwindcss/vite, and Sharp for local image processing.
- MDX blog and content layer — sample posts in src/content/post/ use MDX with frontmatter; the Astro Content Layer manages them, and RSS and sitemap are generated automatically.
- Design-system documentation — docs/DESIGN.md contains visual-system rules for people and coding agents, and the /design route renders it in the browser.
- Elements reference page — the /elements route is a component and token reference, useful for checking available UI pieces.
- Configuration-driven customization — site title, canonical URL, SEO metadata, and source link live in src/config/site.js; themes are configured in src/config/themes.js.
- Theme switcher with production off-switch — visitors can change themes via the switcher; set showThemeSwitcher and persistUserSelection to false after choosing a defaultThemeId to lock one palette in production.
- RSS and sitemap support — route /rss.xml serves the feed, and the build generates a sitemap and Open Graph metadata when PUBLIC_SITE_URL is set.
Who is this starter for?
Developers who want a content-first Astro site with a real design system, and teams that need to deliver multiple theme variants without changing components. The starter suits these specific roles:
- Frontend developers starting a new content site with Astro can clone this starter, run pnpm install and pnpm dev, and edit config files instead of building from scratch.
- Design-focused agencies can use the documented visual system and theme tokens to deliver client sites with a consistent, reusable design language.
- Bloggers and content teams benefit from the sample MDX posts, RSS feed, and easy route structure for article listing and individual pages.
- Production engineers can disable the theme switcher and set PUBLIC_SITE_URL to generate canonical URLs, sitemap, and Open Graph metadata.
What can you do with the Design-led Astro Starter?
- Content-driven marketing sites: use the /, /blog, and /design routes as the skeleton for a company or portfolio site, replacing the generic copy and images.
- Theme experimentation: preview ten palettes with the theme switcher, then set a default theme in src/config/themes.js for a consistent look.
- Design-system showcase: use the /elements and /design pages to display components, tokens, and visual rules to stakeholders or developers.
- Self-documenting projects: set up docs/DESIGN.md as the source of truth for design decisions, readable both by humans and coding agents.
How does the theme system work?
All ten themes define their colors and type styles as semantic tokens in src/styles/themes.css; components reference those tokens, so switching themes changes the whole site without touching component markup. The default theme is set with defaultThemeId in src/config/themes.js, and the switcher can be hidden and user preference persistence turned off for production.
Pricing
Free. The starter is open source under the MIT license, with no paid tiers or premium features described in the repository.
FAQ
Is the Design-led Astro Starter free?
Yes, it is distributed under the MIT license, so it can be used freely in commercial and personal projects without a paid license.
What tech stack does it use?
It uses Astro 7, TypeScript, Tailwind CSS v4 with @tailwindcss/vite, MDX, Astro Content Layer, RSS, sitemap, and Sharp for local image processing.
How do I change the default theme?
Set defaultThemeId in src/config/themes.js to one of the ten theme identifiers (for example, Retro Blue is the default). If you want to lock the theme in production, also set showThemeSwitcher and persistUserSelection to false.
What routes are included?
The starter includes / (overview), /blog (article listing), /blog/[slug] (individual article), /design (design documentation), /elements (component and token reference), and /rss.xml (RSS feed).
How do I deploy the starter?
Run pnpm build and pnpm preview after setting PUBLIC_SITE_URL to the final deployment URL. The official demo deploys the repo unchanged to Vercel at https://ricoui-astro-starter.vercel.app/ for theme-directory review, then a separate deployment after customization.
