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 viaastro-seo, forms viaastro-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-imagesskill - ❌ SEO markup not using
astro-seoskill - ❌ Missing required pages (404, Privacy Policy)
- ❌
client:loadwithout 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
// src/config/site.ts
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)
- pages.md — 404, 410, Privacy Policy (MUST exist)
- a11y.md — Accessibility requirements
- config.md — Config file templates
Required if Multi-Language
- i18n.md — Translation setup, hreflang
Conditional
Definition of Done
Architecture is complete when ALL are true:
- All pages render without JavaScript enabled
- PageSpeed ≥ 90 on both mobile and desktop
- No CLS on page load (test with throttled connection)
- All visible text comes from i18n dictionaries
- Required pages exist: 404, Privacy Policy
- Footer contains business data (name, address, phone, email)
- hreflang tags present if multi-language
- GTM fires correctly (test in GTM Preview)
- Cookie consent blocks tracking until accepted
- Site works on iOS Safari and Android Chrome
- Keyboard navigation works throughout
- Skip link present and functional