seedproject-web/app/AGENTS.md

Instructions for Astro Theme Development

These instructions apply to all Astro theme work. Prioritize clean, reusable, accessible, fast, SEO-friendly code. Treat the theme as something that may be reused across multiple websites, not as a one-off implementation.

General Principles

• Prefer simple, maintainable Astro components over unnecessary abstractions.
• Keep the default Astro advantage: mostly static HTML, minimal JavaScript, and hydration only where needed.
• Do not add client-side JavaScript unless there is a clear user-facing reason.
• Avoid unnecessary dependencies. Before adding a package, check whether the same result can be achieved with Astro, HTML, CSS, or a small utility.
• Keep components reusable, documented, and easy to override.
• Use TypeScript where helpful, especially for props, content schemas, config objects, and reusable utilities.
• Favor progressive enhancement. The site should remain usable even if JavaScript fails.
• Keep markup clean, semantic, and easy to crawl.
• Never solve layout or behavior problems in a way that harms accessibility, SEO, or performance.
• Follow README layout as here https://github.com/andreialba/maria must include the title, preview image with a link to the preview URL, those cards with versions, preview link, short description of the theme, list of features, and how to set things up.
• Add MIT license under Andrei Alba

Astro-Specific Guidelines

• Use .astro components for static and content-focused UI.
• Use islands/client hydration only when interactivity is required.
• Avoid client:load unless the component truly needs to run immediately.
• Prefer client:visible, client:idle, or no hydration when possible.
• Keep layout components responsible for page structure, shared metadata, global slots, and theme-level wrappers.
• Keep UI components small and focused.
• Use Astro.props with typed props where possible.
• Use content collections for structured content like posts, pages, projects, docs, testimonials, FAQs, and changelogs.
• Validate frontmatter with schemas instead of relying on loose optional fields.
• Keep route structure clean and predictable.
• Do not hardcode production URLs inside components. Use site config, constants, or environment-aware helpers.
• Make sure the theme works with a configurable site value in astro.config.*.

Accessibility Requirements

• Use semantic HTML first. Do not use ARIA when a native HTML element solves the problem.
• Use landmarks properly: header, nav, main, section, article, aside, and footer where appropriate.
• Each page should have one clear h1.
• Preserve logical heading order. Do not skip heading levels for visual styling.
• All interactive elements must be keyboard accessible.
• Use real buttons for actions and real links for navigation.
• Every form control must have an associated label.
• Inputs, errors, help text, and validation states must be understandable to screen readers.
• Add visible focus styles. Never remove outlines without replacing them with an accessible focus state.
• Provide a skip link for keyboard users when the layout has repeated navigation.
• Use descriptive link text. Avoid vague text like “click here” or “read more” without context.
• Images must have useful alt text when meaningful.
• Decorative images should use empty alt text.
• Icons used as buttons or links must have accessible names.
• Ensure sufficient color contrast for text, icons, borders, and states.
• Do not rely on color alone to communicate meaning.
• Respect prefers-reduced-motion.
• Avoid auto-playing motion, carousels, or animations unless they are user-controlled and accessible.
• Modals, menus, accordions, tabs, dropdowns, and mobile navigation must handle focus, keyboard interaction, and escape/close behavior correctly.
• Test important templates with keyboard navigation and screen reader-friendly markup in mind.

SEO Requirements

• Every page should have a unique, descriptive <title>.
• Every indexable page should have a useful meta description.
• Use a reusable SEO or Head component for metadata.
• Include canonical URLs where appropriate.
• Support Open Graph metadata for social sharing.
• Support Twitter/X card metadata where appropriate.
• Use absolute URLs for canonical and social image URLs.
• Configure site in astro.config.* so canonical URLs and sitemap generation work correctly.
• Include sitemap support for production themes.
• Include sensible robots handling.
• Avoid duplicate metadata across pages.
• Avoid duplicate content caused by inconsistent trailing slashes, canonical paths, or pagination.
• Use clean, descriptive URLs.
• Add structured data where useful, such as WebSite, Organization, Article, BreadcrumbList, Product, FAQPage, or LocalBusiness, depending on the theme.
• Do not add fake schema data. Structured data must match visible page content.
• Use proper heading structure to reflect the content hierarchy.
• Ensure important content is present in the HTML, not hidden behind client-only rendering.
• Use descriptive image filenames where possible.
• Add alt text and dimensions for content images.
• Include pagination metadata where relevant.
• Support multilingual SEO only when the theme actually supports multiple languages. If it does, include proper lang, canonical, and alternate/hreflang handling.
• Keep internal links crawlable with real <a href=""> links.
• Avoid JavaScript-only navigation for normal pages.

Performance Requirements

• Keep JavaScript minimal.
• Avoid shipping framework runtime code unless needed.
• Hydrate components selectively.
• Prefer static rendering where possible.
• Avoid large global scripts.
• Avoid large CSS bundles.
• Keep CSS scoped, layered, or organized in a predictable way.
• Remove unused CSS and unused components.
• Optimize images with Astro’s image tools where appropriate.
• Always include image width and height to reduce layout shift.
• Use responsive images for large visual assets.
• Lazy-load below-the-fold images.
• Do not lazy-load critical above-the-fold hero images unless there is a good reason.
• Use modern image formats when appropriate.
• Avoid layout shifts from images, ads, embeds, cookie banners, and late-loading UI.
• Keep third-party scripts optional and documented.
• Load analytics, embeds, chat widgets, and marketing scripts only when explicitly enabled.
• Avoid blocking render with unnecessary scripts or styles.
• Keep Core Web Vitals in mind, especially LCP, CLS, and INP.

Font Optimization

• Prefer self-hosted fonts for production themes.
• Use only the font families actually needed by the theme.
• Include only the font weights and styles actually used.
• Prefer modern formats such as woff2.
• Use font-display: swap or another intentional rendering strategy.
• Preload only critical fonts used above the fold.
• Do not preload every font file.
• Define fallback font stacks that closely match the custom font metrics.
• Avoid layout shift caused by late-loading fonts.
• Do not load fonts from external providers by default unless the user explicitly chooses that option.
• Keep font configuration centralized so users can replace or disable custom fonts easily.

CSS and Design System Guidelines

• Use design tokens or CSS custom properties for colors, spacing, typography, radii, shadows, and layout values.
• Keep theme customization simple.
• Avoid scattering hardcoded colors and spacing values throughout components.
• Support light and dark modes only if the theme is designed for both.
• Respect user system preference when dark mode is supported.
• Ensure color tokens meet accessibility contrast requirements.
• Keep responsive behavior consistent across components.
• Use fluid and responsive typography where appropriate.
• Avoid unnecessary wrappers and deeply nested markup.
• Keep animations subtle, optional, and respectful of reduced-motion preferences.

Content and Markdown Guidelines

• Content should be easy to manage through Markdown, MDX, or content collections.
• Validate required frontmatter fields.
• Provide sensible defaults for optional metadata.
• Avoid requiring users to duplicate the same SEO fields in many places when defaults can be generated safely.
• Support draft or unpublished content only when the theme explicitly needs it.
• Make dates, authors, categories, tags, and excerpts consistent.
• Make sure generated archive, tag, category, author, and pagination pages have useful metadata.
• Avoid rendering empty UI sections when content is missing.

Image and Media Guidelines

• Use optimized local images where possible.
• Provide responsive sizes for theme-controlled images.
• Include alt text fields in content schemas where images are user-provided.
• Do not use background images for meaningful content unless an accessible text alternative exists.
• Avoid enormous default hero images.
• Provide predictable aspect ratios to prevent layout shift.
• Lazy-load media that is not immediately visible.
• Make video/audio embeds accessible with labels, captions, transcripts, or surrounding explanatory content when relevant.

Component Guidelines

• Components should have clear responsibilities.
• Props should be typed and documented when not obvious.
• Use sensible defaults.
• Avoid components that silently fail or render broken markup when required props are missing.
• Avoid coupling generic components to one specific page.
• Keep class names predictable.
• Make components easy to copy, remove, or override.
• Do not introduce global side effects from small components.
• For interactive components, document keyboard behavior and accessibility expectations.

Forms

• Use semantic form markup.
• Every input must have a label.
• Required fields must be indicated accessibly.
• Error messages must be connected to the relevant fields.
• Success and error states should be announced or clearly visible.
• Do not rely only on placeholder text as a label.
• Use appropriate input types such as email, tel, url, search, and number.
• Keep forms usable without unnecessary JavaScript where possible.
• Do not include a form provider by default unless it is configurable.

Navigation

• Use real links for navigation.
• Mark the current page or section when possible.
• Ensure mobile navigation works with keyboard and screen readers.
• Trap focus only when appropriate, such as inside an open modal menu.
• Restore focus after closing menus or dialogs when relevant.
• Make dropdowns and submenus accessible.
• Do not hide navigation from assistive technology unless it is truly inactive.

Build, Config, and DX

• Keep configuration centralized and documented.
• Provide clear theme constants for site name, default title, description, social links, navigation, and footer data.
• Avoid requiring users to edit many files for common changes.
• Use environment variables only where they are actually needed.
• Do not expose secrets in client-side code.
• Keep the README accurate.
• Include setup, development, build, preview, customization, and deployment instructions.
• Add comments only where they clarify non-obvious decisions.
• Keep generated examples realistic and production-friendly.
• Make sure the theme builds cleanly without warnings or broken links.

Testing and QA Checklist

Before considering work complete, verify:

• The project builds successfully.
• Pages render without console errors.
• No unnecessary client JavaScript is shipped.
• Navigation works with keyboard only.
• Focus states are visible.
• Forms have labels and accessible states.
• Images have correct alt text and dimensions.
• Metadata is present and unique per page.
• Canonical URLs are correct.
• Sitemap generation works.
• Social preview metadata is valid.
• The layout is responsive.
• Dark mode works if supported.
• Reduced motion is respected.
• Lighthouse or similar checks do not reveal obvious accessibility, SEO, or performance issues.
• There are no broken internal links.
• There is no placeholder content left in production-facing defaults.

Things to Avoid

• Do not use <div> and <span> for everything when semantic HTML exists.
• Do not add ARIA roles to elements that already have correct native semantics.
• Do not remove focus outlines without accessible replacements.
• Do not add heavy animation libraries for simple transitions.
• Do not add global JavaScript for isolated UI behavior.
• Do not load all font weights “just in case.”
• Do not load external fonts by default.
• Do not use client-only rendering for content that should be crawlable.
• Do not hide important content behind JavaScript.
• Do not hardcode metadata across every page.
• Do not ship large demo assets as required production assets.
• Do not introduce dependencies without a clear reason.
• Do not sacrifice accessibility for visual polish.

Preferred Outcome

The final Astro theme should be fast, accessible, SEO-ready, easy to customize, and pleasant to maintain. It should provide strong defaults while staying lightweight and flexible.