company-website/AGENTS.md

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

# 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

---
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

<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