Skip to main content
Back to blog
astrodesign-systemsfrontend

Building a Reusable Component System with Astro

How to extract, abstract, and scale UI patterns into a composable design system using Astro's component model, content collections, and props-driven architecture.

By Alex Martin
Building a Reusable Component System with Astro

Why Abstraction Matters

Every codebase eventually reaches a tipping point where copy-pasting components becomes a liability. A hero section appears on the landing page, the about page, and a campaign page — each slightly different, each maintaining its own markup. When the design changes, you update three places instead of one.

Component abstraction solves this by turning patterns into parameterized building blocks. The design lives in one place; the content lives in another.

The Core Principle: Props Over Hardcode

The fastest way to make a component reusable is to identify every piece of content that might change and lift it into a prop.

Consider a feature card with a title, description, and icon. Instead of hardcoding the icon SVG path and the copy inside the component, you accept them as props:

---
interface Props {
  title: string;
  description: string;
  icon: string; // SVG path d="..."
}
const { title, description, icon } = Astro.props;
---
<div class="bg-accent-5 rounded-card p-6">
  <svg viewBox="0 0 24 24" class="w-8 h-8 text-accent-2">
    <path d={icon} />
  </svg>
  <h3 class="font-display font-bold text-xl mt-4">{title}</h3>
  <p class="text-text-secondary mt-2">{description}</p>
</div>

Now this card can render anything — from a pricing feature to a testimonial benefit — without touching the component file.

Structuring the System

A clean folder hierarchy makes the system self-documenting:

src/components/
  ui/        → atoms: Button, Badge, TagPill
  components/ → molecules: BlogCard, FeatureItem, TestimonialCard
  sections/  → organisms: Hero, BlogList, Features, CTA
  layout/    → page scaffolding: Header, Footer

The rule: each layer only imports from the layers below it. Sections import components and UI primitives. Pages import sections and layouts. This prevents circular dependencies and keeps components portable.

Variant Systems

A component without variants is a component you’ll clone. Add a variant prop from the start:

---
type Variant = 'centered' | 'split' | 'image-background';
interface Props { variant?: Variant; }
const { variant = 'centered' } = Astro.props;
---

Map variants to layout or style classes:

const layoutClass = {
  centered: 'text-center items-center',
  split: 'md:flex-row',
  'image-background': 'relative overflow-hidden',
}[variant];

This keeps the logic in the component, not scattered across calling pages.

Data-Driven Content with Collections

Astro’s Content Layer API is the final piece. Instead of hardcoding mock data in components, define a schema and let your content files drive the UI:

// src/content.config.ts
const features = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/features' }),
  schema: z.object({
    title: z.string(),
    icon: z.string(),
    order: z.number().default(0),
  }),
});

Then query and pass to a section:

---
const items = await getCollection('features');
---
<FeaturesSection items={items.map(e => e.data)} />

The component stays generic. The schema enforces content shape. The files carry the content. Each layer has one job.

Conclusion

A well-abstracted component system pays dividends on every new page. New sections emerge from combining primitives you already tested. Design changes cascade automatically. And onboarding a collaborator means showing them a data file, not explaining component internals.

Start small: extract one section you reuse more than once. Once it has clean props and a variant, the pattern becomes obvious and spreads naturally.

All posts