# 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 desktop/mobile navigation
├── pages/                    # Route pages (use .astro files)
│   ├── index.astro           # Home page
│   ├── qazk/index.astro      # Product center - industrial safety (工贸企业)
│   ├── property/index.astro  # Product center - smart property (物业楼宇)
│   ├── elderly/index.astro   # Product center - smart elderly care
│   ├── construction/index.astro # Product center - smart construction
│   ├── education/index.astro # Product center - smart campus
│   ├── kitchen/index.astro   # Product center - smart kitchen
│   ├── chemical/index.astro  # Product center - hazardous chemicals (危险化学品)
│   ├── fireworks/index.astro # Product center - fireworks (烟花爆竹)
│   ├── mining/index.astro    # Product center - non-coal mining (非煤矿山)
│   ├── customization/index.astro
│   ├── partnership/index.astro
│   └── intro/*/index.astro   # Intro/detail pages
├── components/
│   └── sections/             # Reusable section components
└── styles/styles.css        # Global styles

public/
├── img/
│   ├── property/             # Smart property page assets (webp)
│   ├── elderly/              # Smart elderly care page assets (webp preferred)
│   ├── construction/         # Smart construction page assets (webp preferred)
│   ├── education/            # Smart campus page assets (webp + svg)
│   ├── kitchen/              # Smart kitchen page assets (webp)
│   ├── chemical/             # Hazardous chemicals assets (hero.webp + architecture.webp)
│   ├── fireworks/            # Fireworks assets (hero.webp + architecture.webp)
│   ├── mining/               # Non-coal mining assets (hero.webp + architecture.webp)
│   └── ...
└── js/script.js
```

### High-risk industry modules pattern (chemical / fireworks / mining)

Each follows the same simplified 5-section layout (similar to construction):
1. `{Industry}Hero.astro` — IOC big-screen screenshot + 4 feature pills + 2 audience boxes (企业 / 监管赋能)
2. `{Industry}PainPoints.astro` — industry-specific pain points (4–6 items, distinct visual style per module)
3. `{Industry}Policy.astro` — industry-specific regulations (6–10 items, distinct layout per module)
4. `{Industry}Architecture.astro` — solution overview + system layer diagram + architecture image
5. `{Industry}Hardware.astro` — 6 key hardware solutions (text + icons, no images)

Hero images are IOC dashboard screenshots; architecture images are 3D scene illustrations of the facility.

## 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
- Product center uses dropdown/submenu in `Layout.astro`
- Current product nav IDs (9 modules in order): `qazk`, `property`, `elderly`, `kitchen`, `education`, `construction`, `chemical`, `fireworks`, `mining`
- Desktop dropdown renders as a 3×3 grid (`grid grid-cols-3` with fixed `w-[600px]`); mobile dropdown uses `grid-cols-3`
- 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`

#### Image optimization with Sharp

- Use Sharp for converting newly added PNG/JPG/JPEG assets to WebP before commit.
- Keep original design/source assets outside `public/` when possible; only optimized assets should be used by the website.
- Example (single folder conversion):

```bash
node --input-type=module -e "import sharp from 'sharp'; import { promises as fs } from 'node:fs'; import path from 'node:path'; const dir='public/img/kitchen'; const files=await fs.readdir(dir); for (const name of files){ const ext=path.extname(name).toLowerCase(); if(!['.png','.jpg','.jpeg'].includes(ext)) continue; const src=path.join(dir,name); const out=path.join(dir,path.basename(name,ext)+'.webp'); await sharp(src).webp({quality:82,effort:6}).toFile(out);}"
```

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