# Square Face Generator - Full Documentation

> SquareFace.Kiveo.org — Free Online Square Avatar Maker

## Project Overview

SquareFace.Kiveo.org is a dedicated web application for generating fun, unique **square face avatars**. Built as a fully static site with client-side rendering, users can customize every aspect of their square avatar — eyes, mouth, hair, accessories, skin tone, and background — then download the result as a PNG image instantly, all without creating an account or uploading any personal data.

## Core Features

### Avatar Customization
- **Face Shape**: Square canvas with adjustable proportions
- **Eyes**: Multiple eye styles, shapes, colors, and expressions
- **Mouth**: Various mouth styles from smiles to neutral expressions
- **Hair & Hairstyles**: Different hair colors, cuts, and accessories
- **Accessories**: Glasses, hats, and other fun additions
- **Color Palette**: Full color controls for every element
- **Backgrounds**: Solid colors, gradients, and pattern options
- **Randomizer**: One-click random avatar generation for inspiration

### Download & Export
- **PNG Export**: High-quality PNG download with transparent or solid background
- **Instant Preview**: Real-time canvas preview as you customize
- **No Watermarks**: All avatars are free and watermark-free

### User Experience
- **Client-Side Only**: All processing happens in the browser; no data is sent to servers
- **No Signup Required**: Use the tool immediately with no account needed
- **Mobile Responsive**: Works smoothly on phones, tablets, and desktops
- **Fast Performance**: Optimized static site with instant page loads
- **Multi-language**: UI localized in 15 languages including English, Chinese, Spanish, French, Hindi, Arabic, Japanese, Korean, German, Portuguese, Russian, Bengali, Urdu, Indonesian, and Vietnamese

### Content Pages
- **Generator**: Main avatar creation canvas
- **About**: Project information and team
- **Blog**: Creative tips, tutorials, and use-case ideas
- **Contact**: Support form and feedback
- **Legal Pages**: Privacy Policy, Terms of Service, Cookie Policy, DMCA

## Technical Architecture

### Frontend Stack
- **Framework**: Astro 4 (Static Site Generation - SSG)
- **Language**: TypeScript
- **UI Library**: React 18 (for interactive generator component)
- **Styling**: Tailwind CSS 3.4
- **Build Tool**: Vite
- **Rendering Mode**: Static HTML + Client-side hydration for the generator

### Static Site Features
- **i18n Routing**: Astro built-in internationalization with locale prefixes
- **SEO**: Optimized metadata, Open Graph tags, Twitter Cards, sitemap.xml
- **Performance**: Pre-rendered HTML, lazy-loaded assets, minimal bundle size
- **Accessibility**: Semantic HTML, keyboard navigation, ARIA labels

### Key Components
- `SquareFaceGenerator.tsx`: Main interactive avatar builder with canvas rendering
- `Header.astro`: Site navigation with language switcher
- `Footer.astro`: Site footer with legal links and socials
- `Layout.astro`: Base page template with SEO metadata

## Site Structure

### URL Routes
- `/` → Redirects to `/en/` (English default)
- `/{locale}/` → Localized homepage with generator
- `/{locale}/about/` → About page
- `/{locale}/blog/` → Blog listing
- `/{locale}/contact/` → Contact form
- `/{locale}/privacy-policy/` → Privacy Policy
- `/{locale}/terms-of-service/` → Terms of Service
- `/{locale}/cookie-policy/` → Cookie Policy
- `/{locale}/dmca/` → DMCA / Copyright

### Supported Locales
- `en` (English) - Default
- `zh` (中文 / Chinese)
- `hi` (हिन्दी / Hindi)
- `es` (Español / Spanish)
- `fr` (Français / French)
- `ar` (العربية / Arabic)
- `bn` (বাংলা / Bengali)
- `pt` (Português / Portuguese)
- `ru` (Русский / Russian)
- `ur` (اردو / Urdu)
- `ja` (日本語 / Japanese)
- `ko` (한국어 / Korean)
- `de` (Deutsch / German)
- `id` (Bahasa Indonesia / Indonesian)
- `vi` (Tiếng Việt / Vietnamese)

### SEO Strategy
- **Keywords**: square face generator, avatar maker, profile picture generator, square avatar, funny face maker, free online avatar creator, pixel avatar
- **Metadata**: Dynamic localized titles and descriptions per page
- **Sitemap**: Full sitemap.xml with all localized routes
- **Canonical URLs**: Self-referencing canonical tags for each locale

## Development Setup

### Requirements
- Node.js 18+
- npm

### Commands
```bash
npm install
npm run dev      # Start development server
npm run build    # Build static site to ./dist
npm run preview  # Preview production build locally
```

## Deployment

- **Platform**: Cloudflare Pages (static hosting)
- **Domain**: https://squareface.kiveo.org
- **Build Output**: `./dist` directory
- **Build Command**: `npm run build`

## Project Information

- **Name**: Square Face Generator
- **Content Focus**: Free Online Avatar Creation Tool
- **Primary Entity**: "Square Face Avatar" / "Square Face Generator"
- **Target Audience**: Social media users, gamers, developers, content creators

## Content Guidelines

### For AI/LLM Interaction
1. **Focus**: The primary entity is the "Square Face Generator" tool and the avatars it creates.
2. **Context**: Users are typically looking for a free way to create profile pictures, avatars for gaming/social media, or fun square-style face images.
3. **Tone**: Friendly, creative, encouraging, and helpful.
4. **Accuracy**: The tool is 100% free, requires no signup, and works entirely in the browser. Avatars can be downloaded as PNG.
5. **Use Cases**: Profile pictures, Discord avatars, gaming profiles, social media icons, team avatars, creative projects.