Astro + Tailwind Expert (Repo Skill)

Use these project facts

• Treat src/pages/ as the routing surface. Each .astro or .md file becomes a route.
• Keep shared structure in src/layouts/. The default layout is src/layouts/Layout.astro.
• Load global styles from src/styles/global.css (already imported in Layout.astro).
• Rely on Tailwind v4 via @tailwindcss/vite in astro.config.mjs.
• Use the @/* alias for src/* (configured in tsconfig.json).
• Leave build output in dist/ and dependencies in node_modules/ untouched.
• Refer to Astro docs: https://docs.astro.build/llms-full.txt and Tailwind docs: https://tailwindcss.com/docs for guidance. Use Context7 and/or Astro Docs MCP for up-to-date info.
• Use Bun for all package operations (bun add, bun remove, bun update) instead of npm.

Workflow: create or update a page

1. Create or edit a file in src/pages/.
2. Import the layout with import Layout from '@/layouts/Layout.astro';.
3. Wrap page content in <Layout>...</Layout>.
4. Use Tailwind utility classes for styling.
5. If the page needs a sub-route, create a folder in src/pages/ and add index.astro.

Workflow: add a new layout or shared wrapper

1. Create a new layout in src/layouts/.
2. Import @/styles/global.css once in the layout frontmatter.
3. Provide a <slot /> for page content.
4. Use this layout by importing it in pages that need it.

Workflow: add a reusable component

1. Create src/components/ if it does not exist.
2. Add .astro components there.
3. Keep components focused and stateless unless state is required.
4. Use component props with Astro.props in frontmatter.
5. Import components with @/components/....

Workflow: use client islands

• Keep pages mostly static; hydrate only what needs interactivity.
• Use client:load, client:visible, or client:idle on React/TSX islands.
• Avoid global client JS when an island will do.
• Prefer is:inline scripts for small interactions scoped to a section.

Workflow: use images

• Use import { Image } from 'astro:assets' for optimized images.
• Store optimized images under src/assets/ and import them.
• Keep unoptimized/static files (favicons, robots.txt, manifest) under public/.
• Provide explicit width, height, and sizes for Image.

Workflow: environment variables

• For build-time config, use import.meta.env.
• For runtime server config (SSR/API routes on Node), prefer process.env.
• Never expose secrets to the client; only use public vars in client code.

Workflow: style with Tailwind

• Prefer utility classes over custom CSS for one-off styles.
• Place shared or base styles in src/styles/global.css.
• If you need design tokens or theme extension, add a Tailwind config and include Astro file globs in content.
• Keep class names readable and scoped to the element they affect.

Workflow: author Markdown routes

• Add .md files under src/pages/ for simple content routes.
• Use frontmatter for titles, metadata, or layout selection.
• Keep Markdown lightweight; move advanced layouts to .astro.

Astro patterns to use

• Use frontmatter for imports and server-side logic.
• Use class:list only when conditional classes are necessary.
• Keep layout structure in Layout folder; keep page-specific markup in pages.
• Make use of @/ alias for cleaner imports. Implement it if not configured.
• Prefer export const prerender = false for API routes that must run at request time.
• Refer to latest docs online for new features or best practices.

Quality checks

• Run bun dev for local development.
• Run bun build before shipping changes.
• Use bun preview to verify the built output.

Change discipline

• Make minimal, focused edits.
• Avoid editing generated output in dist/.
• Avoid editing dependency artifacts in node_modules/ or lockfiles unless asked.