Imported from esezak/esezak.github.io (AGENTS.md). Install upstream with npx skills add esezak/esezak.github.io. Copyright stays with the author.

AGENTS.md — Portfolio / CV Website

Project Overview

A personal portfolio and CV website designed to showcase projects, skills, and experience to recruiters. Hosted on GitHub Pages as a statically exported Next.js application.

Tech Stack

Coding Standards

1. Documentation

• Every exported function/component must have a JSDoc comment explaining its purpose, parameters, and return value.
• Every file must begin with a one-line comment describing what it contains.
• Variable and function names must be self-documenting (projectCards not pc).

2. SOLID Principles

3. Code Style

• Use TypeScript strict mode ("strict": true in tsconfig.json).
• Prefer const over let; never use var.
• Use arrow functions for components and callbacks.
• Keep files under 200 lines; split into smaller modules when they grow.
• Use named exports (avoid export default except for pages).

Internationalization (i18n)

Architecture

/public/locales
  /en
    common.json      ← shared keys (nav, footer, buttons)
    hero.json         ← hero section text
    about.json        ← about section text
    skills.json       ← skills section text
    projects.json     ← projects section text
    experience.json   ← experience section text
    education.json    ← education section text
    contact.json      ← contact section text
  /tr
    common.json
    hero.json
    about.json
    skills.json
    projects.json
    experience.json
    education.json
    contact.json

Rules

1. Default language is English (en).
2. Language switcher must be always visible in the navigation bar and use recognisable country flag icons (🇬🇧 / 🇹🇷) so that even users who cannot read the current language can switch.
3. Adding a new language requires only:
   • Creating a new folder under /public/locales/<code>/ with the same JSON files.
   • Adding the locale code + flag to a single config array in src/config/i18n.ts.
4. All user-facing strings must come from locale files — no hard-coded text in components.

Theming

Colour Tokens

Themes are defined via CSS custom properties in :root / [data-theme="dark"].

Dark Theme (JetBrains Darcula-inspired)

Light Theme

Rules

1. Theme toggle must be always visible in the navigation bar (sun/moon icon).
2. Selected theme persists across sessions via localStorage.
3. Default to dark theme unless the user's OS preference is light.
4. All colour references in CSS must use var(--token) — never raw hex values.

Project Structure

cv-site/
├── public/
│   ├── images/              ← project thumbnails, profile photo
│   ├── flags/               ← language flag SVGs
│   └── resumes/             ← Ege_Resume_EN.pdf, Ege_Resume_TR.pdf
├── src/
│   ├── app/
│   │   ├── layout.tsx       ← root layout (providers, nav, footer)
│   │   └── page.tsx         ← single-page home (all sections)
│   ├── components/
│   │   ├── layout/          ← Header, Footer, Navigation, ThemeToggle, LanguageSwitcher
│   │   ├── sections/        ← Hero, About, Skills, Projects, Experience, Education, Contact
│   │   └── ui/              ← Button, Card, SectionWrapper, Badge, IconLink
│   ├── config/
│   │   ├── i18n.ts          ← supported locales, default locale
│   │   ├── navigation.ts    ← nav links config
│   │   └── site.ts          ← site-wide metadata (name, description, socials)
│   ├── context/
│   │   ├── ThemeContext.tsx  ← theme provider + hook
│   │   └── I18nContext.tsx   ← i18n provider + hook
│   ├── data/
│   │   ├── projects.ts      ← project card data (title key, image, repo URL)
│   │   ├── skills.ts        ← skills data
│   │   └── experience.ts    ← experience data
│   ├── hooks/
│   │   ├── useTranslation.ts
│   │   └── useTheme.ts
│   ├── types/
│   │   └── index.ts         ← shared TypeScript interfaces
│   └── styles/
│       ├── globals.css       ← CSS reset, theme variables, typography
│       ├── layout.css        ← header, footer, nav styles
│       ├── sections.css      ← section-specific styles
│       └── components.css    ← reusable component styles
├── .github/
│   └── workflows/
│       └── deploy.yml        ← GitHub Pages deploy action
├── AGENTS.md
├── README.md
├── next.config.js
├── tsconfig.json
└── package.json

Modularity Rules

Adding / Removing a Section

1. Create or delete the component in src/components/sections/.
2. Add or remove the corresponding locale keys in each /public/locales/<lang>/ file.
3. Add or remove the section from the page composition in src/app/page.tsx.
4. Optionally update src/config/navigation.ts to show/hide the nav link.

Adding a New Page

1. Create a new folder under src/app/<page-name>/ with a page.tsx.
2. Add the route to src/config/navigation.ts.
3. Add locale keys under a new JSON file per language folder.

Adding a New Language

1. Copy /public/locales/en/ to /public/locales/<code>/ and translate the values.
2. Add the locale entry (code + flag) to the array in src/config/i18n.ts.

Animations

• Use Framer Motion for all section entrance animations and page transitions.
• Sections should animate in on scroll (fade-up with stagger).
• Navigation transitions should have a smooth cross-fade.
• Keep animations subtle and professional — this is a recruitment-facing site, not a game.

Deployment (GitHub Pages)

1. next.config.js must set output: 'export' for static HTML generation.
2. A GitHub Actions workflow (.github/workflows/deploy.yml) automatically builds and deploys on push to main.
3. The repo must have GitHub Pages enabled under Settings → Pages → Source: GitHub Actions.

Agent Behavioural Rules

1. Ask before acting — if any user requirement is ambiguous, ask for clarification before writing code.
2. No hallucination — only reference real APIs, libraries, and techniques. If unsure, research first.
3. Document everything — every function, component, and config must have clear comments or JSDoc.
4. Follow SOLID — keep components small, configurable, and decoupled.
5. Use semantic HTML — proper heading hierarchy, landmarks, alt text, ARIA labels.
6. Accessibility — keyboard navigable, sufficient colour contrast, screen- reader friendly.