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