NEED
Defines a production-ready Astro.js theme with React islands, Sveltia-CMS, ImageKit CDN, and full PWA/SEO/accessibility features.
What this file does
Defines a production-ready Astro.js theme with React islands, Sveltia-CMS, ImageKit CDN, and full PWA/SEO/accessibility features.
When to use it
- Building a content site with Astro and React
- Needing a CMS-backed static site with GraphQL
- Requiring ImageKit CDN with Cloudflare failover
- Implementing a mobile-first, PWA-ready blog or news site
Assumes this stack
I'll analyze the requirements and create a comprehensive implementation plan, making sure to include all requested features while removing the specified elements.
Astro.js Theme with React Components & Sveltia-CMS Integration
[COMPLETED] Framework & Core Architecture
Description
A production-ready Astro.js (v4.x) theme optimized for Cloudflare Pages deployment with React components for interactive elements and Sveltia-CMS as the backend.
Implementation
- Configure Astro.js with the
@astrojs/cloudflareadapter for edge deployment - Use React for interactive components with partial hydration ("islands architecture")
- Set up GraphQL client (Apollo or urql) for Sveltia-CMS integration
- Implement TypeScript for type safety throughout the codebase
- Configure proper ESM modules with tree-shaking to minimize bundle size
Considerations
- Ensure proper environment variable handling for different environments
- Implement code splitting for React components to reduce initial payload
- Create consistent state management approach across components
- Establish clear hydration boundaries to prevent unnecessary client-side JavaScript
[COMPLETED] Asset Management System
Description
A robust asset delivery system with ImageKit as primary CDN and Cloudflare as automatic failover.
Implementation
- Integrate ImageKit SDK for image transformation and delivery
- Create an automated failover detection system that monitors ImageKit bandwidth usage
- Implement automatic switching to Cloudflare CDN when ImageKit bandwidth approaches 24GB limit
- Develop custom React components for optimized image handling with srcset
- Configure Brotli compression for all text-based assets
- Set AVIF as the default image format with WebP and JPEG fallbacks
Considerations
- Implement proper caching strategies with cache busting mechanisms
- Create bandwidth monitoring system for ImageKit with thresholds
- Ensure smooth transition between CDNs without user-facing disruption
- Set up proper error handling for failed image loads
Navigation Systems
[COMPLETED] Navigation Systems
Description
Two complementary navigation systems: traditional mega-menu and personalized recommendations.
Implementation
-
Mega Menu:
- Create accessible multi-level navigation structure
- Implement proper ARIA roles and keyboard navigation
- Build responsive layouts that adapt to all device sizes
- Fetch navigation structure from Sveltia-CMS
-
Personalized Recommendations:
- Track article views in localStorage with proper categorization
- Implement GraphQL queries to fetch related content based on tags/categories
- Create relevancy scoring algorithm for content recommendations
- Build real-time update mechanism via client-side AJAX
- Implement SSR fallback for first-time visitors
Considerations
- Ensure privacy compliance with cookie consent for tracking
- Build fallback mechanism for users without JavaScript
- Implement proper focus management for keyboard users
- Create clear visual hierarchy for navigation elements
[COMPLETED] SEO Optimization
Description
Comprehensive SEO implementation with metadata, structured data, and sitemap generation.
Implementation
-
Dynamic Metadata:
- Create SEO component system for title tags (50-60 characters)
- Generate meta descriptions (150-160 characters)
- Implement canonical URLs, meta robots tags
- Add Open Graph and Twitter Card metadata
- Configure article-specific metadata (published date, author)
- Add alternate language, RSS/Atom, and pagination meta tags
-
Structured Data:
- Implement JSON-LD schemas for:
- Article, Organization, BreadcrumbList, FAQPage, WebPage
- ImageObject, Person, VideoObject, Product, Rating/Review
- SiteNavigationElement, SearchAction
- Implement JSON-LD schemas for:
-
Sitemap & Robots.txt:
- Auto-generate sitemap.xml with priority, change frequency, last modified
- Include image, video, and news sitemap data
- Create robots.txt with appropriate directives and sitemap references
Considerations
- Ensure proper fallback values for missing metadata
- Validate structured data against Schema.org specifications
- Implement automatic updates of sitemap on content changes
[COMPLETED] Enhanced Mobile Responsiveness
Description
Mobile-first design approach with advanced responsiveness techniques for all device types.
Implementation
- Create fluid typography system using CSS clamp() functions
- Implement CSS Grid and Flexbox layouts for responsive design
- Define custom breakpoints for mobile, tablet, desktop, and large desktop
- Optimize touch targets (minimum 44×44px) for mobile interfaces
- Create mobile-specific navigation patterns
- Implement content prioritization for small screens
- Use responsive images with proper art direction via picture element
- Create mobile-optimized forms with appropriate input types
- Add orientation change handling with content reflow
- Implement variable fonts for weight/width optimization
- Use content-visibility for offscreen content
- Add mobile-specific gestures and interactions
- Create device-specific enhancements for notches and foldable displays
- Implement container queries for component-level responsiveness
- Add keyboard avoidance techniques for mobile forms
- Create mobile-specific loading states and skeleton screens
- Implement low-data mode detection
- Optimize for 60fps scrolling performance
Considerations
- Test across multiple device types and screen sizes
- Ensure accessibility is maintained on all viewports
- Balance feature richness with performance
[COMPLETED] Security Implementation
Description
Comprehensive security measures to protect the application and user data.
Implementation
- Configure strict Content Security Policy (CSP) headers
- Set up CORS, X-XSS-Protection, and HSTS headers
- Implement Cloudflare WAF rules for attack protection
- Create bot management system with proper crawler allowlists/denylists
- Set up CSRF protection for form submissions
- Implement advanced security policies for authentication flows
- Configure proper HTTPS redirects and certificate handling
Considerations
- Regular security audits and updates
- Balance security with performance
- Implement proper logging for security events
[COMPLETED] Analytics & Monitoring
Description
Complete analytics and error tracking system with privacy compliance.
Implementation
- Integrate Google Analytics with cookie consent mechanism
- Configure Sentry for error logging with source maps
- Create custom event tracking for important user interactions
- Implement performance monitoring for core web vitals
Considerations
- Ensure GDPR and other privacy regulation compliance
- Balance analytics needs with user privacy
- Set up proper alerting for critical errors
[COMPLETED] Progressive Web App Features
Description
Full PWA support for offline capabilities and app-like experience.
Implementation
- Create web app manifest with appropriate icons and metadata
- Implement service worker with strategic caching:
- Cache-first for static assets
- Network-first for dynamic content
- Build offline page and content availability
- Add "Add to Home Screen" prompt
- Implement background sync for offline actions
Considerations
- Test offline functionality across browsers
- Create update notification system for service worker
- Balance cache size with device storage constraints
[COMPLETED] UI/UX Features
Description
Rich, interactive UI elements to enhance user experience and engagement.
Implementation
- Create mobile-only "Flash Feed" with gradient-glow button
- Implement dark/light mode toggle with system preference detection
- Add reading progress bar for articles
- Create scroll-triggered animations with IntersectionObserver
- Implement lazy loading for images and components
- Add Lottie micro-animations for interactive elements
- Implement glassmorphism effects with fallbacks
- Create gradient overlays with customizable color schemes
- Add 3D flip effects for interactive cards
- Implement parallax scrolling for featured images
Considerations
- Ensure all animations are accessible (respects reduced motion)
- Test performance impact of animations
- Create fallbacks for older browsers
[COMPLETED] Accessibility Implementation
Description
WCAG 2.1 AA compliance throughout the application.
Implementation
- Use proper semantic HTML elements
- Add ARIA roles and attributes for interactive elements
- Implement keyboard navigation with visible focus states
- Create skip links for screen reader users
- Ensure proper heading hierarchy
- Implement sufficient color contrast
- Add text alternatives for non-text content
- Ensure proper form labels and error messages
Considerations
- Test with screen readers and keyboard-only navigation
- Create accessible alternatives for complex interactions
- Ensure animations respect user preferences
[COMPLETED] Documentation
Description
Detailed documentation for setup, customization, and maintenance.
Implementation
- Add inline documentation for all files
- Create step-by-step deployment instructions
- Document theme customization options
- Provide architectural decision explanations
- Create troubleshooting guide
Considerations
- Keep documentation up-to-date with code changes
- Make documentation accessible to different skill levels
- Include visual diagrams where helpful
What's inside
12 completed sections covering architecture, assets, navigation, SEO, mobile, security, analytics, PWA, UI/UX, accessibility, and documentation.
Change this for your project
- Replace
@astrojs/cloudflareadapter if deploying elsewhere - Replace
ImageKitreferences with your own CDN provider - Replace
Sveltia-CMSwith your own CMS backend - Replace
Google AnalyticsandSentrywith your own monitoring tools
Where it goes
Save in docs/ or the repository root. Gives agents and new contributors a map of the codebase.
Worth borrowing
- CDN failover logic with bandwidth monitoring thresholds
- Mobile-only Flash Feed with gradient-glow button
- Fluid typography using CSS clamp() and container queries
Related Documents
Design Document: BharatSeva AI
Describes a 10-agent AWS system that helps India's informal workers access government schemes via voice-first, serverless architecture.
OpenClaw Enterprise Transformation Plan
Transforms a single-user AI agent into a dual-mode platform supporting both viral open-source and Fortune 500 enterprise deployments through phased security, IAM, audit, multi-tenancy, and Kubernetes features.
Qwen Image and Edit: Open-sourcing and Local GGUF Generations with Lightning
Documents the Qwen-Image and Qwen-Image-Edit models, covering architecture, training, benchmarks, ComfyUI setup, and prompting techniques for local GGUF deployment.
Qwen3-TTS — Model Reference
Documents the architecture, weights, tokenizer, and inference algorithm for implementing Qwen3-TTS from scratch.