astro-batavia

name	astro-batavia
description	specialized skill for developing and maintaining the Astro Batavia multilingual blog platform.

astro-batavia

Expert guidance for the Astro Batavia codebase, focusing on i18n, Tailwind CSS v4, and Astro-specific patterns.

When to use

Use this skill for any task involving code modifications, feature additions, or bug fixes within the Astro Batavia repository. It is particularly critical when:

• Adding or modifying paginated routes (Manual Pagination).
• Updating styles or theme configuration (CSS-only).
• Working with multilingual content or translations.
• Creating new UI components (Astro/Vanilla JS).
• Implementing loading states using the custom Skeleton system.

Instructions

1. Internationalization (i18n)

• Translations: UI strings are managed in src/i18n/ui.ts. Always add new strings there for all supported languages (en, es, ja).
• Path Generation: Use getLocalizedPath(path, lang) from @/i18n/utils to generate links. Avoid hardcoding /en/ or /es/.
• Validation: Use isValidLanguage(lang) when handling [lang] parameters in getStaticPaths.

2. Styling with Tailwind CSS v4

• CSS-Only Config: All configuration MUST happen in src/styles/global.css. Never create a tailwind.config.mjs file.
• Theme Extensions: Add colors, fonts, and animations to the @theme block in global.css.
• Utility Layers: Use @layer base, @layer components, and @layer utilities within global.css to organize custom CSS.

3. Pagination & Routing

• Filename Constraints: Astro's paginate() helper ONLY works if the filename contains [page] or [...page].
• Manual Pagination: For index.astro or [slug].astro files requiring pagination, manually slice the data and construct the Page object. Ensure url.prev and url.next are correctly localized.
• First Page URLs: Always ensure the first page links to the base directory (e.g., /blog/) and NOT to /blog/1.

4. Component Standards

• Component Style: Keep components as .astro files with Vanilla JS <script> tags for interactivity. Avoid React/Islands.
• Images: Use <Picture> component from astro:assets for automatic optimization.
• Typography: Prefer components in src/components/ui/typography/ for consistent text styling.
• Skeleton System:
  • All loading states must use the src/components/ui/Skeleton.astro primitive or pre-built specialized skeletons from src/components/ui/skeletons/.
  • Use SkeletonLoader.astro for global page transition skeletons.

5. Build & Validation

• Linting: Run npm run lint before finalizing changes.
• Formatting: Run npm run format to ensure code style consistency.
• Build Test: Run npm run build:only to verify the build pipeline.