# AGENTS.md

This file provides guidelines for agentic coding agents working in this repository.

## Tech Stack

- **Framework**: Astro 5.7.3 - Static site generator
- **Styling**: Tailwind CSS 3.4.19 with custom theme
- **Package Manager**: pnpm 10.29.2
- **TypeScript**: 5.9.3 with @astrojs/check
- **Icons**: FontAwesome 4.7.0 (CDN)

## Build & Development Commands

```bash
# Development
pnpm dev              # Start dev server at http://localhost:4321
pnpm start            # Alias for pnpm dev

# Build & Quality
pnpm build            # Run astro check then build (production)
pnpm preview          # Preview production build locally

# Direct Astro commands
pnpm astro <command>  # Run any astro command directly
```

**Note**: No test framework is currently configured. When adding tests, first check with the maintainers.

## Project Structure

```
src/
├── layouts/Layout.astro      # Main layout with navigation
├── pages/                    # Route pages (use .astro files)
│   ├── index.astro           # Home page
│   └── [route]/index.astro
├── components/
│   └── sections/            # Reusable section components
└── styles/styles.css        # Global styles
```

## Code Style Guidelines

### Astro Components

- File extension: `.astro`
- Frontmatter uses `---` delimiters
- Import components at the top of the frontmatter section
- Use TypeScript for type annotations in frontmatter and `<script>` tags

```astro
---
import { someComponent } from '../components/some-component.astro';

interface Props {
  title: string;
  activeNav?: string;
}

const { title, activeNav = 'home' } = Astro.props;
---
```

### Imports

- Import Astro components with relative paths: `import Component from '../components/Component.astro'`
- Import external libraries normally: `import { defineConfig } from 'astro/config'`
- No default exports in components (Astro handles this)

### Styling with Tailwind CSS

- Use Tailwind utility classes for all styling
- Custom colors available: `primary` (#165DFF), `secondary` (#36D399), `dark` (#1E293B), `light` (#F8FAFC)
- Custom font family: `font-inter` (Inter, system-ui, sans-serif)
- Responsive design: mobile-first approach with `md:`, `lg:` breakpoints
- Hover states: `hover:`, `group-hover:`
- Transitions: `transition-all duration-300` for consistent animation timing

### Naming Conventions

- **Components**: PascalCase (e.g., `Hero.astro`, `DataVisualization.astro`)
- **Pages**: index.astro in route directories
- **Props**: camelCase (e.g., `activeNav`, `title`)
- **IDs for CSS/JS**: kebab-case (e.g., `data-visualization`, `contact-info`)
- **CSS classes**: Tailwind utilities only (custom classes in `<style>` tags for animations)
- **Functions**: camelCase (e.g., `getNavLinkClass`)

### Layout Pattern

- All pages use `<Layout>` component with `activeNav` prop for navigation highlighting
- Navigation items defined in Layout.astro: home, qazk, customization, partnership
- Main content wrapped in `<main>` tag

```astro
<Layout title="Page Title" activeNav="nav-id">
  <main>
    <Content />
  </main>
</Layout>
```

### Scripts

- Inline scripts: use `<script is:inline>` for critical initialization
- Regular scripts: use `<script>` tag without attributes
- Wrap in IIFE to avoid global scope pollution: `(function() { ... })();`
- Use TypeScript annotations in script tags
- Event listeners: use `{ passive: true }` for scroll events where applicable

### TypeScript

- Enable type checking by running `astro check` before builds
- Use interfaces for component props
- Type DOM elements with assertions when needed: `(element as HTMLElement)`

### Accessibility

- Use semantic HTML: `<section>`, `<header>`, `<nav>`, `<main>`, `<footer>`
- Include `alt` attributes on images
- Use ARIA labels where needed
- Ensure keyboard navigation works

### Images

- Prefer WebP format for images: `image.webp`
- Place images in `public/img/` directory
- Reference with absolute paths: `/img/image.webp`
- Use responsive sizing classes: `w-full h-full object-cover`

### Color Usage

- Primary actions: `bg-primary` (#165DFF)
- Secondary/success: `text-secondary` (#36D399)
- Backgrounds: `bg-slate-50`, `bg-white`, `bg-dark`
- Text: `text-gray-900`, `text-gray-600`, `text-white`
- Gradients: `bg-gradient-to-r from-blue-600 to-indigo-600`

### Icons

- Use FontAwesome 4.7.0 via CDN
- Class pattern: `fa fa-icon-name`
- Size classes: `text-lg`, `text-xl`, `text-2xl`

### Animation Patterns

- Use Tailwind `transition-all duration-300` for consistent animations
- Hover effects: `group-hover:scale-[1.02]`, `hover:shadow-lg`
- Keyframe animations in `<style>` tags for complex animations
- Fade/scale transforms common

### Responsive Design

- Mobile-first approach
- Breakpoints: `sm:` (640px), `md:` (768px), `lg:` (1024px)
- Hidden elements: `hidden lg:block` (hide on mobile)
- Container: `max-w-7xl mx-auto px-4 lg:px-0`
- Grid layouts: `grid-cols-1 md:grid-cols-2 lg:grid-cols-4`

### Error Handling

- Astro handles most errors at build time
- Graceful degradation for optional features
- Check for element existence before DOM manipulation: `if (element) { ... }`

### File Organization

- Keep components focused and single-purpose
- Section components in `src/components/sections/`
- Each page imports its required sections
- Shared layout handles navigation and footer
- Static assets in `public/` directory

## Adding New Pages

1. Create directory in `src/pages/[route]/`
2. Create `index.astro` file
3. Import `Layout` and use appropriate `activeNav` value
4. Add navigation item to `Layout.astro`'s `navItems` array
5. Import and render section components as needed

## Adding New Section Components

1. Create `.astro` file in `src/components/sections/`
2. Use PascalCase naming
3. Export component (Astro handles this automatically)
4. Import in pages where needed
5. Use semantic `<section>` tag with ID for navigation
6. Follow Tailwind styling patterns

## Environment Variables

- Store in `.env` file
- Access in Astro frontmatter: `import.meta.env.VARIABLE_NAME`
- Commit `.env.example` if needed (currently not present)

## Deployment

- Build output: `dist/` directory
- Static site generation - deploy to any static hosting
- No server-side rendering requirements