| name | astro-architecture |
| description | Technical architecture for Astro lead generation websites. Use when setting up new projects, configuring build tools, or establishing project foundations. For images use astro-images skill. For SEO use astro-seo skill. |
Astro Architecture Skill
Technical foundation for high-performance, accessible, translation-ready lead gen sites.
Core Rules (Non-Negotiable)
- Astro static or hybrid only — No SPA routing, no client-side frameworks
- TypeScript strict mode — Always enabled, no
any
- All text from i18n — No hardcoded strings in components
- Mobile-first CSS — Base styles for mobile,
md: and up for larger
- Performance is build-time — No runtime optimization hacks
- One source of truth — All site data in
site.ts
- Skill boundaries — Images via
astro-images, SEO via astro-seo, forms via astro-forms
Forbidden (STOP)
STOP and reassess if any of these occur:
- ❌ Client-side routing framework (React Router, etc.)
- ❌ UI component library (shadcn, DaisyUI, Chakra)
- ❌ Inline business logic in
<script> tags
- ❌ Hardcoded translations in components
- ❌ Images not using
astro-images skill
- ❌ SEO markup not using
astro-seo skill
- ❌ Missing required pages (404, Privacy Policy)
- ❌
client:load without explicit justification
- ❌ External fonts via Google Fonts API (self-host instead)
- ❌ PageSpeed score below 90
Tech Stack
| Layer | Technology |
|---|
| Framework | Astro (latest stable) |
| Styling | Tailwind CSS (latest stable) |
| Language | TypeScript (strict) |
| Deploy | Cloudflare Pages |
| Forms | astro-forms skill |
| Calculator | lead-gen-calculator skill |
| Images | astro-images skill |
| SEO | astro-seo skill |
| UX | astro-ux skill |
Performance Targets
| Metric | Target | FAIL if |
|---|
| PageSpeed (mobile) | ≥ 95 | < 90 |
| PageSpeed (desktop) | ≥ 95 | < 90 |
| Load time (desktop) | < 0.8s | > 1.5s |
| Load time (mobile) | < 1.4s | > 1.9s |
| LCP | < 1.5s | > 3s |
| CLS | < 0.1 | > 0.25 |
| Total JS | < 50KB | > 100KB |
Browser Compatibility
Must work on:
- Chrome, Firefox, Safari, Edge, Opera, Brave
- iOS Safari (all versions), Android Chrome, Samsung Internet
- Old devices: iOS 12+, Android 7+
FAIL if site breaks on any of these.
File Structure
src/
├── config/
│ └── site.ts # ALL site data
├── i18n/
│ ├── ui.ts # UI strings
│ ├── en.json # English
│ └── [lang].json # Other languages
├── layouts/
│ ├── BaseLayout.astro # HTML shell
│ └── LandingLayout.astro
├── pages/
│ ├── index.astro
│ ├── thank-you.astro
│ ├── privacy-policy.astro # REQUIRED
│ ├── 404.astro # REQUIRED
│ ├── 410.astro # REQUIRED
│ └── [lang]/ # Translated pages
│ └── index.astro
├── components/
│ ├── sections/ # From astro-ux
│ ├── ui/
│ ├── layout/
│ │ ├── Header.astro
│ │ ├── Footer.astro # Must have business data
│ │ └── MobileMenu.astro
│ └── common/
│ └── LanguageSwitcher.astro
├── actions/ # From astro-forms
├── lib/
│ ├── i18n.ts # Translation helpers
│ └── gtm.ts # GTM/GA4 helpers
├── styles/
│ └── global.css
└── assets/
├── fonts/ # Self-hosted fonts
└── images/
Central Config
export const site = {
name: "Business Name",
phone: "+44 XXX XXX XXXX",
email: "info@example.com",
address: "123 Street, City, Postcode",
colors: {
primary: "#1C202F",
secondary: "#E5F2FF",
accent: "#FF6B35",
},
defaultLocale: 'en',
locales: ['en', 'hu', 'es'] as const,
gtm: {
id: "GTM-XXXXXXX",
cookieYesId: "XXXXXXXX",
},
social: {
google: { rating: 4.9, count: 270 },
},
};
References
Required (Always Read)
Required if Multi-Language
- i18n.md — Translation setup, hreflang
Conditional
- gtm.md — Only if GTM/GA4 tracking enabled
- fonts.md — Only if custom fonts used
Definition of Done
Architecture is complete when ALL are true:
