# Portfolio Website — Documentation

**Version:** 1.0.0
**Last Updated:** August 27, 2026
**Author:** Lurkawindo / LurkaTheme
**License:** MIT / Personal Use

---

## 📋 Table of Contents

1. [Overview](#1-overview)
2. [Tech Stack](#2-tech-stack)
3. [File Structure](#3-file-structure)
4. [Getting Started](#4-getting-started)
5. [Design Philosophy](#5-design-philosophy)
6. [Color System](#6-color-system)
7. [Typography](#7-typography)
8. [Section Breakdown](#8-section-breakdown)
9. [Customization Guide](#9-customization-guide)
10. [Adding New Projects](#10-adding-new-projects)
11. [Form Integration](#11-form-integration)
12. [Deployment](#12-deployment)
13. [Browser Support](#13-browser-support)
14. [Performance Tips](#14-performance-tips)
15. [Accessibility](#15-accessibility)
16. [Credits & CDN Sources](#16-credits--cdn-sources)
17. [Troubleshooting](#17-troubleshooting)
18. [FAQ](#18-faq)

---

## 1. Overview

A handcrafted, organic-feeling personal portfolio website designed to feel human, warm, and uniquely "you" — deliberately avoiding the generic AI-template aesthetic (no glassmorphism, no neon glows, no rigid symmetry).

**Key Features:**
- Responsive layout powered by Bootstrap 5.3
- Isotope.js-powered project filter with smooth shuffle animation
- Typed.js hero text animation
- AOS (Animate On Scroll) for subtle scroll reveals
- Warm, paper-like color palette with soft shadows
- Fully customizable via CSS variables

---

## 2. Tech Stack

| Technology     | Version | Purpose                          | CDN / Source |
|----------------|---------|----------------------------------|--------------|
| HTML5          | 5       | Semantic structure               | Native       |
| CSS3           | 3       | Styling with custom properties   | Native       |
| JavaScript     | ES6+    | Interactivity                    | Native       |
| Bootstrap      | 5.3.2   | Responsive grid & navbar         | jsdelivr     |
| Isotope        | 3.x     | Portfolio filter/shuffle         | unpkg        |
| AOS            | 2.3.1   | Scroll animations                | unpkg        |
| Typed.js       | 2.1.0   | Hero typing effect               | unpkg        |
| FontAwesome    | 6.5.1   | Icons                            | cdnjs        |
| Google Fonts   | —       | Plus Jakarta Sans + Inter        | fonts.googleapis.com |

---

## 3. File Structure

```
portfolio/
│
├── index.html          # Main HTML structure
├── style.css           # All custom styles + CSS variables
├── script.js           # Vanilla JS logic + library initializations
├── assets/             # (Create this folder)
│   ├── images/         # Your photos, project thumbnails
│   ├── fonts/          # Custom fonts (if any)
│   └── docs/           # CV/resume PDF
└── DOCUMENTATION.md    # This file
```

---

## 4. Getting Started

### Option A: Local Development (Recommended)

1. **Download or clone** the project files
2. **Open `index.html`** in any modern browser — no build step required
3. **Edit files** in your preferred code editor (VS Code, Sublime, etc.)
4. **Optional:** Use a local server for best experience:
   ```bash
   # With Python
   python -m http.server 8000

   # With Node.js (npx)
   npx serve

   # With VS Code "Live Server" extension
   # Right-click index.html → "Open with Live Server"
   ```

### Option B: Direct Deployment

Upload `index.html`, `style.css`, and `script.js` to any static host (Netlify, Vercel, GitHub Pages, Cloudflare Pages).

---

## 5. Design Philosophy

### What this site IS:
- ✅ Warm, paper-like, organic
- ✅ Asymmetrical with playful rotations
- ✅ Soft, natural drop shadows
- ✅ Generous whitespace
- ✅ Handcrafted-feeling details (squiggles, dashed borders)
- ✅ Accessible contrast ratios

### What this site is NOT:
- ❌ Glassmorphism / frosted glass
- ❌ Neon glows or cyberpunk aesthetics
- ❌ Perfect symmetry or rigid grids
- ❌ Dark-mode-first
- ❌ Generic Bootstrap look

---

## 6. Color System

All colors are defined as CSS variables in `style.css` inside `:root`. To re-theme the entire site, edit only this block.

### Default Palette (Warm Cream + Coral)

```css
:root {
  --bg:         #FAF7F2;   /* warm cream background */
  --bg-alt:     #F3EEE4;   /* slightly deeper cream */
  --surface:    #FFFFFF;   /* cards */

  --ink:        #1F1B16;   /* near-black, warm */
  --ink-soft:   #5C564C;   /* muted text */
  --ink-faint:  #9A9284;   /* placeholders, hints */

  --coral:        #FF6B6B; /* primary accent (buttons, links) */
  --coral-soft:   #FFE4E4; /* coral background tint */
  --indigo:       #4338CA; /* secondary accent */
  --indigo-soft:  #E7E4FB;
  --sage:         #86A789; /* tertiary accent */
  --sage-soft:    #E4EFE5;
  --amber:        #E8A33D;
  --amber-soft:   #FBF0D9;

  --line:         #E8E2D5; /* warm divider lines */
}
```

### Variable Naming Convention

| Variable      | Usage                                                |
|---------------|------------------------------------------------------|
| `--bg`        | Main page background                                 |
| `--bg-alt`    | Alternate section backgrounds (for visual rhythm)    |
| `--surface`   | Cards, modals, elevated elements                     |
| `--ink`       | Primary text color                                   |
| `--ink-soft`  | Secondary/muted text                                 |
| `--ink-faint` | Placeholders, captions, hints                        |
| `--coral`     | **Primary accent** — main buttons, links, highlights |
| `--coral-soft`| Soft tinted backgrounds for tags/pills               |
| `--indigo`    | Secondary accent — used sparingly                    |
| `--sage`      | Tertiary accent — success states, icons              |
| `--amber`     | Quaternary accent — warnings, badges                 |
| `--line`      | Borders, dividers                                    |

### Alternative Palettes (Ready to Use)

Five complete alternative palettes are provided in the project. To switch:

1. Open `style.css`
2. Find the `:root { ... }` block (around line 10)
3. Replace its contents with one of these:

**Palette 1 — Forest & Terracotta (Earthy)**
```css
--bg: #F5F1EA; --bg-alt: #EBE4D6; --surface: #FDFCF9;
--ink: #2A241C; --ink-soft: #5E5547; --ink-faint: #9A8F7E;
--coral: #C65D3A; --coral-soft: #F4DDD0;
--indigo: #2D5F4F; --indigo-soft: #D6E5DE;
--sage: #D4A574; --sage-soft: #F0E2CE;
--amber: #C9922A; --amber-soft: #F5E8C8;
--line: #DDD3BF;
```

**Palette 2 — Ocean & Sand (Coastal)**
```css
--bg: #F6F8F7; --bg-alt: #E9EEEC; --surface: #FFFFFF;
--ink: #1A2632; --ink-soft: #4A5B6B; --ink-faint: #8896A3;
--coral: #0E7C7B; --coral-soft: #D4E8E7;
--indigo: #E07856; --indigo-soft: #FADED2;
--sage: #6B9AC4; --sage-soft: #DCE7F1;
--amber: #D9A441; --amber-soft: #F6E8C6;
--line: #D8DFE0;
```

**Palette 3 — Plum & Peach (Editorial)**
```css
--bg: #FAF6F4; --bg-alt: #F1EAE5; --surface: #FFFFFF;
--ink: #2B1E2A; --ink-soft: #5E4F5C; --ink-faint: #9A8B97;
--coral: #8B3A62; --coral-soft: #F0D9E2;
--indigo: #E89B6C; --indigo-soft: #FCE4D3;
--sage: #6B7FA3; --sage-soft: #DDE3ED;
--amber: #C9922A; --amber-soft: #F5E8C8;
--line: #E3D8D2;
```

**Palette 4 — Mustard & Charcoal (Bold)**
```css
--bg: #F7F5F0; --bg-alt: #EDE8DC; --surface: #FFFDF8;
--ink: #1F1D1A; --ink-soft: #55504A; --ink-faint: #928A7E;
--coral: #D4952A; --coral-soft: #F5E4C0;
--indigo: #3D3A35; --indigo-soft: #E5E1DA;
--sage: #A85C3B; --sage-soft: #EDD5C7;
--amber: #7A8B5C; --amber-soft: #E0E6D2;
--line: #DDD5C4;
```

**Palette 5 — Moss & Clay (Artisan)**
```css
--bg: #F4F1EA; --bg-alt: #E8E2D4; --surface: #FCFAF5;
--ink: #2C2820; --ink-soft: #5A5344; --ink-faint: #918878;
--coral: #6B7F4A; --coral-soft: #DDE4CE;
--indigo: #B8654A; --indigo-soft: #EDD4C7;
--sage: #8E7A5C; --sage-soft: #E3DACC;
--amber: #C9882A; --amber-soft: #F3E2BE;
--line: #D9D0BE;
```

**Yellow-Themed Palettes (Bonus)**
- Honey & Ink: `--coral: #D99F2A;` on warm ivory
- Sunflower & Olive: `--coral: #E8B93D;` with olive green
- Lemon & Slate: `--coral: #F2C94C;` with cool slate
- Butter & Cocoa: `--coral: #F5D76E;` with cocoa brown

> ⚠️ **Accessibility Note:** Yellow is a light color. Never use it for text on white backgrounds — it fails WCAG contrast requirements. Yellow should only be used for buttons, tags, and decorative elements (with dark text on top).

---

## 7. Typography

### Font Stack

| Role      | Font              | Weights Used |
|-----------|-------------------|--------------|
| Headings  | Plus Jakarta Sans | 500, 600, 700, 800 |
| Body      | Inter             | 300, 400, 500, 600 |

### Type Scale

```
h1: clamp(2.4rem, 5vw, 3.8rem) — Hero name
h2: clamp(1.8rem, 3.5vw, 2.6rem) — Section titles
h3: 1.25rem — Card titles
body: 16px / 1.65 line-height
```

### To Change Fonts

1. Update the Google Fonts link in `<head>`:
   ```html
   <link href="https://fonts.googleapis.com/css2?family=YOUR_FONT&display=swap" rel="stylesheet" />
   ```
2. Update the `font-family` in `style.css`:
   ```css
   h1, h2, h3 { font-family: 'YOUR_FONT', sans-serif; }
   body       { font-family: 'YOUR_FONT', sans-serif; }
   ```

---

## 8. Section Breakdown

### 8.1 Navbar (`#mainNav`)
- Sticky top, light background
- Shrinks on scroll (`.scrolled` class added via JS)
- Mobile hamburger collapses via Bootstrap
- "Download CV" button on the right

**To edit links:** Modify `<ul class="navbar-nav">` in `index.html` (lines ~40-50).

### 8.2 Hero (`#home`)
- Split layout: text left, portrait right
- Typed.js cycles through job titles
- Animated waving emoji 👋
- Organic blob shape behind portrait (CSS morph animation)
- Mouse-parallax effect on portrait (desktop only)

**To change typed phrases:** Edit the `strings` array in `script.js` → Typed.js initialization.

### 8.3 About (`#about`)
- Bio text + stats row (projects, years, subs)
- Skills card with pill-shaped tags (slightly rotated for charm)

**To add a skill:** Add a new `<span class="skill-pill primary">Skill Name</span>` inside `.skills-list`.
Classes: `primary` (coral), `secondary` (indigo), `accent` (sage), `neutral` (gray).

### 8.4 Education (`#education`)
- Vertical timeline with gradient line
- Each entry is a soft-shadowed card
- Year badge in coral pill

**To add an entry:** Duplicate a `.timeline-item` block and update content.

### 8.5 Projects (`#projects`) — Isotope Grid
- Filter buttons at top
- Masonry layout via Isotope
- Smooth shuffle animation on filter change

**Category classes:**
- `.cat-web` → Web Apps
- `.cat-mobile` → Mobile
- `.cat-uiux` → UI/UX
- `.cat-tools` → Tools

See [Section 10](#10-adding-new-projects) for full instructions.

### 8.6 YouTube (`#youtube`)
- Grid of video thumbnail cards
- Hover play button overlay
- "Visit Channel" CTA

**To add a video:** Duplicate a `.yt-card` block and update image/link.

### 8.7 Contact (`#contact`)
- Left: Contact info card (email, location, availability, phone)
- Right: Contact form with bottom-border inputs

**Form handling:** See [Section 11](#11-form-integration).

### 8.8 Footer
- Brand, quick links, social icons
- Dynamic copyright year via JavaScript

---

## 9. Customization Guide

### Quick Checklist

- [ ] Replace profile image (`.hero-portrait` in `index.html`)
- [ ] Update name, bio, and typed phrases
- [ ] Add your real social media URLs
- [ ] Replace CV download link (`href="#"` on `.btn-cv`)
- [ ] Update skills list
- [ ] Edit education timeline entries
- [ ] Replace project cards with your own work
- [ ] Update YouTube thumbnails
- [ ] Fill in contact info (email, phone, location)
- [ ] Connect contact form to a real backend
- [ ] Choose your color palette
- [ ] Update footer brand name

### Replace Placeholder Images

Search for `https://images.unsplash.com/` in `index.html` and replace each URL with your own image path:

```html
<!-- Before -->
<img src="https://images.unsplash.com/photo-..." alt="..." />

<!-- After -->
<img src="assets/images/my-photo.jpg" alt="..." />
```

---

## 10. Adding New Projects

### Step 1: Choose a Category

Each project must belong to one (or more) of these classes:

| Class       | Filter Button | Use For |
|-------------|---------------|---------|
| `.cat-web`  | Web Apps      | Websites, SaaS, web apps |
| `.cat-mobile` | Mobile      | iOS/Android apps |
| `.cat-uiux` | UI / UX       | Design case studies |
| `.cat-tools`| Tools         | Utilities, libraries |

A project can have multiple classes: `<article class="iso-item cat-web cat-tools">`.

### Step 2: Copy This Template

```html
<article class="iso-item cat-web">
  <div class="project-card">
    <div class="project-img">
      <img src="assets/images/project-name.jpg" alt="Project preview" />
      <span class="project-tag-corner">Web App</span>
    </div>
    <div class="project-body">
      <h3>Project Name</h3>
      <p>Short description — one or two sentences.</p>
      <div class="project-tags">
        <span>React</span><span>Node.js</span><span>Postgres</span>
      </div>
      <div class="project-links">
        <a href="https://github.com/you/project"><i class="fa-brands fa-github me-1"></i>Code</a>
        <a href="https://project.com"><i class="fa-solid fa-arrow-up-right-from-square me-1"></i>Live</a>
      </div>
    </div>
  </div>
</article>
```

### Step 3: Add a New Category (Optional)

If you want a new filter category (e.g., "Open Source"):

1. Add a filter button in `.filter-bar`:
   ```html
   <button class="filter-btn" data-filter=".cat-oss">Open Source</button>
   ```
2. Use the matching class on your project cards: `.cat-oss`
3. Isotope picks it up automatically — no JS changes needed.

### Step 4: Image Recommendations

- **Aspect ratio:** 16:10 (e.g., 800×500 px)
- **Format:** WebP preferred, fallback to JPG
- **Max file size:** < 200 KB per image
- **Naming:** `project-name.jpg` (lowercase, hyphens)

---

## 11. Form Integration

The contact form is currently a **demo** (shows success message but doesn't send data).

### Option A: Formspree (Easiest, No Backend)

1. Sign up at https://formspree.io
2. Create a form → get your endpoint ID
3. In `script.js`, find the form submit handler and uncomment:
   ```javascript
   fetch('https://formspree.io/f/YOUR_ID', {
     method: 'POST',
     headers: { 'Accept': 'application/json' },
     body: new FormData(form)
   });
   ```

### Option B: Netlify Forms (If Hosting on Netlify)

Add `netlify` attribute to the form tag:
```html
<form class="contact-form" id="contactForm" netlify novalidate>
```
Netlify auto-detects and handles submissions.

### Option C: Custom Backend

Replace the fetch call with your API endpoint:
```javascript
fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name, email, subject, message })
});
```

---

## 12. Deployment

### GitHub Pages (Free)

1. Push code to a GitHub repo
2. Settings → Pages → Source: `main` branch, `/root`
3. Your site is live at `https://username.github.io/repo-name`

### Netlify (Free, Recommended)

1. Drag-and-drop your project folder at https://app.netlify.com/drop
2. OR connect your GitHub repo for auto-deploys
3. Add a custom domain in Site Settings

### Vercel (Free)

1. Import your GitHub repo at https://vercel.com
2. Framework: "Other"
3. Deploy

### Cloudflare Pages (Free)

1. Connect repo at https://pages.cloudflare.com
2. Build command: (leave empty)
3. Output directory: `/`

---

## 13. Browser Support

| Browser          | Version | Status |
|------------------|---------|--------|
| Chrome           | 90+     | ✅ Full |
| Firefox          | 90+     | ✅ Full |
| Safari           | 14+     | ✅ Full |
| Edge             | 90+     | ✅ Full |
| Mobile Safari    | iOS 14+ | ✅ Full |
| Chrome Android   | 90+     | ✅ Full |

IE11 is **not supported** (uses CSS variables, modern JS).

---

## 14. Performance Tips

### Image Optimization
- Use WebP format with JPG fallback
- Resize images to display size (don't serve 4000px images at 800px wide)
- Use `loading="lazy"` on below-fold images:
  ```html
  <img src="..." loading="lazy" alt="..." />
  ```

### Font Optimization
- Google Fonts links already use `display=swap` for fast loading
- Consider self-hosting fonts for production

### Reduce Animations (Optional)
For users who prefer reduced motion, add to `style.css`:
```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## 15. Accessibility

This site is built with accessibility in mind:

- ✅ Semantic HTML5 (`<header>`, `<section>`, `<article>`, `<nav>`)
- ✅ ARIA labels on icon-only buttons
- ✅ Sufficient color contrast (WCAG AA)
- ✅ Keyboard-navigable
- ✅ Focus states visible
- ✅ `alt` text on all images
- ✅ Form labels properly associated

### To Test Accessibility
- Run Lighthouse (Chrome DevTools → Lighthouse → Accessibility)
- Use axe DevTools browser extension
- Navigate with Tab key only

---

## 16. Credits & CDN Sources

### Libraries (via CDN)
- Bootstrap 5.3.2 — https://getbootstrap.com
- Isotope 3.x — https://isotope.metafizzy.co
- AOS 2.3.1 — https://michalsnik.github.io/aos/
- Typed.js 2.1.0 — https://mattboldt.com/demos/typed-js/
- FontAwesome 6.5.1 — https://fontawesome.com

### Fonts
- Plus Jakarta Sans — https://fonts.google.com/specimen/Plus+Jakarta+Sans
- Inter — https://fonts.google.com/specimen/Inter

### Stock Images (placeholders, replace with your own)
- Unsplash — https://unsplash.com

---

## 17. Troubleshooting

### "Isotope grid isn't aligning properly"
→ Make sure images have loaded. Add `imagesLoaded` library if needed:
```html
<script src="https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js"></script>
```
Then in `script.js`:
```javascript
imagesLoaded(grid, () => iso.layout());
```

### "Typed.js isn't showing"
→ Check browser console for errors. Ensure the element with `id="typed"` exists.

### "AOS animations not firing"
→ Make sure `aos.css` is loaded in `<head>` and `AOS.init()` runs after DOM load.

### "Colors look wrong after changing palette"
→ Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R).

### "Mobile nav doesn't close after clicking a link"
→ Ensure Bootstrap's JS bundle is loaded before `script.js`.

### "Form submits but no data received"
→ Check your Formspree/dashboard endpoint. Verify CORS if using custom backend.

---

## 18. FAQ

**Q: Can I use this for commercial projects?**
A: Yes, if you're the author. The design is yours to customize.

**Q: Do I need to keep the CDN links?**
A: No. For production, consider self-hosting libraries for reliability.

**Q: How do I change the brand name "alex.morgan"?**
A: Search for `alex` in `index.html` (appears in navbar and footer).

**Q: Can I add a blog section?**
A: Yes. Create a new `<section>` following the same pattern as existing sections.

**Q: How do I change the hero blob color?**
A: Edit `.portrait-blob { background: var(--coral-soft); }` in `style.css`.

**Q: The portrait rotation looks weird on my photo**
A: Adjust `transform: rotate(2deg)` on `.hero-portrait` — try `0deg` or `-2deg`.

**Q: Can I disable the mouse parallax?**
A: Yes. Delete the mousemove listener in `script.js` (section 9 of the file).

---

## 📝 Changelog

### v1.0.0 (2026-08-27)
- Initial release
- 8 sections: Navbar, Hero, About, Education, Projects, YouTube, Contact, Footer
- 5 color palettes + 4 yellow-themed options
- Isotope filter/shuffle
- Typed.js hero
- AOS scroll animations
- Fully responsive

---

## 📞 Support

visit our site for contact

---

**Made with ☕ and curiosity.**