I Rebuilt Our Company Website With Astro and Claude Code - Here's What Actually Worked

We had an 85-page company website on Typedream. It was slow, messy, and impossible to maintain. Pages were duplicated, the design was inconsistent, and every small change meant logging into a drag-and-drop editor that fought you at every step.

So I decided to rebuild the whole thing. From scratch. Using Astro, Tailwind, and Claude Code as my main coding partner.

Two months later we had a 30-page site that loads faster, ranks better, and actually converts. Here's what I learned along the way — the stuff that worked, the stuff that didn't, and practical tips if you want to try the same thing.

Why Astro

If you haven't tried Astro, it's a web framework that ships zero JavaScript by default. You write components, and Astro renders them to static HTML. When you need interactivity — a mobile menu, a calculator, a form — you add a "React Island" that hydrates only that component.

For a content-heavy site like ours, this is perfect. Most of our pages are guides, service descriptions, and comparisons. They don't need JavaScript. The few interactive bits (contact form, mobile navigation) get React, and everything else stays as fast static HTML.

Our Lighthouse scores went from "meh" to consistently 95+ across the board. Not because we did anything clever, but because Astro's architecture just doesn't ship unnecessary code.

The stack

• Astro 5 with server mode (for forms and dynamic content)
• React only for interactive islands
• Tailwind CSS with a custom design system
• Supabase for contact form submissions
• Plus Jakarta Sans loaded locally (no Google Fonts dependency — GDPR matters in Finland)

Why Claude Code

I've used Copilot, ChatGPT, Cursor — all of them. Claude Code is the one I kept coming back to, and here's why: it actually reads your whole project.

When I say "update the pricing on the Claude guide page," it doesn't just find-and-replace a number. It reads the layout, understands the component structure, checks the data layer, and makes changes that are consistent with how the rest of the site works.

That said, Claude Code is not magic. It's a very capable tool that still needs a human who knows what they want. The biggest mistake I see people make is treating AI coding tools like a vending machine — put in a vague request, get out a website. That's how you end up with generic-looking sites that all feel the same.

Setting up your project for AI-assisted development

This is the part nobody talks about. The quality of your AI-generated code depends almost entirely on how you set up your project. Here's what made the biggest difference for us:

1. Write a proper CLAUDE.md

This is a file in your project root that tells Claude Code how your project works. Ours includes:

• The tech stack and how things connect
• Our design system rules (colors, shadows, typography, spacing)
• Content guidelines (tone of voice, SEO rules, author information)
• File structure conventions

Think of it as onboarding documentation, except your coworker is an AI that reads it every single time. The better this file is, the less you repeat yourself.

2. Create a design system before you start coding

This was probably our most important decision. Before writing a single component, we defined:

• Exact color values — not "use blue" but #0066FF for accent, rgba(255,255,255,0.5) for card backgrounds
• Shadow definitions — we call our style "minimalistic claymorphism." Two shadows: a subtle outer shadow and a thin white border. No complex inset shadows, no neumorphism
• Typography scale — font sizes, weights, line-heights, letter-spacing for every heading level
• Border radius — from 12px for buttons to 24px for large cards
• Spacing system — consistent padding and gap values

Why does this matter for AI-assisted development? Because when Claude Code has specific design tokens to work with, it generates components that actually look consistent. Without a design system, every component looks slightly different — different shadows, different spacing, different border radius. That's the "AI slop" look that people recognize instantly.

3. Build reusable components first

Before creating any pages, we built a library of Astro components:

src/components/
├── ui/          # Card, Alert, Stats, FeatureList, PricingCard...
├── seo/         # Breadcrumbs, Schema, AuthorBox, FAQSection...
├── layout/      # Header, Footer, MobileMenu (React)...
└── sections/    # CTASection, HeroSection...

Each component follows the design system strictly. When I then ask Claude Code to "create a new service page," it composes from these existing building blocks rather than inventing new styles.

4. Use specialized layouts

We have five layout templates, each designed for a specific content type:

• OpasLayout — for guides (sticky table of contents on desktop)
• PalveluLayout — for service pages (hero, schema, CTA)
• BlogLayout — for articles (author box, reading time)
• TyokaluLayout — for tools and calculators
• LandingLayout — for the homepage (free-form structure)

The layouts handle all the repetitive stuff automatically: breadcrumbs, structured data, meta tags, default CTAs. Content creators (human or AI) just focus on the actual content.

The workflow that actually works

Here's my daily workflow with Claude Code on this project:

For new pages: I write a brief with the target keywords, the intended audience, the page structure (which H2 sections I want), and which layout to use. Claude Code creates the page using existing components and the design system. I then review and adjust the content, especially anything related to pricing or specific claims.

For updates: I describe what needs to change and why. "The Claude pricing changed, update the Claude guide and the comparison pages." Claude Code finds all the relevant files, updates them consistently, and I verify.

For new components: I describe the component, reference a similar existing one, and specify which design tokens to use. "Create a Timeline component similar to FeatureList but vertical, with a show-more button. Use the clay shadow and accent color for the connector line."

What I never do: I never ask Claude Code to "make it look nice" or "design a landing page." Vague aesthetic requests produce vague results. The more specific you are about the visual system, the better the output.

Managing 85 redirects without losing SEO

One thing that scared me about the migration was losing our existing search rankings. We had 85 pages, many with organic traffic, and we were consolidating them into 30.

We handled it with Astro's middleware:

// middleware.ts — simplified example
const redirectMap: Record<string, string> = {
  '/tekoalysovellukset': '/oppaat/ai-tyokalut-vertailu',
  '/mita-tekoly-on/neuroverkko': '/oppaat/llm',
  '/kokeile-tekoalya': '/oppaat/ai-tyokalut-vertailu',
  // ... 82 more
};

Every old URL returns a proper 301 redirect. We mapped each old page to the most relevant new page, not just the homepage. This preserved most of our link equity and kept Google happy.

The result? Our impressions grew roughly 10x in the first two months, and our average search position improved from around page 2 to the top half of page 1. Consolidating 85 thin pages into 30 comprehensive ones actually helped our SEO — Google seems to prefer fewer, better pages over many shallow ones.

The design philosophy: avoiding AI slop

Every AI-built website looks the same. You've seen them: purple gradients, generic hero illustrations, "Revolutionize your workflow" headlines, emoji bullets everywhere. It's become so recognizable that people call it "AI slop."

We deliberately went the other direction:

• No emojis as icons. We use simple symbols like ◎, ▦, ↗ or proper SVGs
• No gradients. Our background is a flat warm gray (#EAEAEC) with semi-transparent white cards
• No stock illustrations. Real screenshots, real product images
• No hype copy. We write in first person ("We offer..." not "AImiten offers...") and we're honest about limitations
• Claymorphism, not neumorphism. Subtle outer shadows with a thin white border, giving depth without screaming "look at my CSS"

The irony is that building with AI makes it even more important to have strong design opinions. Claude Code will happily generate generic-looking components if you let it. The design system is your defense against mediocrity.

One unexpected benefit: AI crawlers love clean Astro sites

We made a deliberate choice to allow AI crawlers (GPTBot, ClaudeBot, PerplexityBot) in our robots.txt. As an AI consulting company, we want to appear in AI-generated answers, not just traditional search results.

Clean HTML, proper heading structure, schema markup, and fast load times — all things Astro gives you out of the box — seem to help with what people call GEO (Generative Engine Optimization). Our AI tools comparison guide regularly gets cited in AI search results, which drives a meaningful amount of traffic.

Tips if you're doing this yourself

Start with the design system, not the pages. Spend a day defining your visual language. Every hour you spend here saves ten hours of inconsistency fixes later.

Keep your CLAUDE.md updated. When you make a design decision or establish a new pattern, add it to the file. Future-you (and Claude Code) will thank you.

Don't let AI write your marketing copy. Use it for structure, components, and repetitive code. But headlines, value propositions, and anything customer-facing should sound like a human wrote it — because a human should write it.

Prerender what you can. Astro lets you mark individual pages as prerendered even in server mode. For content that doesn't change often (guides, service pages), this gives you static-site speed with server-side capabilities where you need them.

Build for content updates. We update our guides weekly — new model releases, pricing changes, feature announcements. The component architecture makes this fast. Updating a price in our data layer automatically updates it across all pages that reference it. If you're in a fast-moving space like AI, this kind of automation is worth the initial setup.

Use layouts aggressively. The more your layouts handle automatically (breadcrumbs, schema, CTAs, author boxes), the less can go wrong when creating new pages. Our Claude guide and our AI coaching page look completely different but share the same structural guarantees.

Was it worth it?

Two months in, the numbers speak for themselves. Search visibility grew 10x. Session duration doubled. Bounce rate dropped. And most importantly, I can update any page in minutes instead of fighting a no-code editor.

The combination of Astro's performance-first architecture and Claude Code's project-wide understanding is genuinely powerful. But the key insight is this: AI coding tools amplify your decisions, good and bad. A solid design system and clear project structure turn Claude Code into an incredibly productive partner. Without them, you just get fast-generated mediocrity.

If you're considering a similar rebuild, start with the foundation. The code will follow.

---

I'm Sampsa, CEO at AImiten. We help companies figure out how to actually use AI — not just talk about it. If you're curious, check out what we do.