add AGENT.md
This commit is contained in:
201
AGENTS.md
Normal file
201
AGENTS.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user