path: root/WEEK3-START.md

# Week 3 Quick Start Guide

## ⚠️ IMPORTANT: Git Branching Workflow

Before starting Week 3, create a new feature branch for this week's work:

```bash
# Create and switch to Week 3 branch
git checkout -b week-3-cards-nav

# Verify you're on the new branch
git branch -v
```

**Why branching?**
- Keeps each week's work isolated
- Allows code review before merging to master
- Easy to rollback if issues arise
- Clean git history

**At end of Week 3:**
- Review all changes: `git diff master..week-3-cards-nav`
- Test thoroughly in the branch
- Merge back to master when ready: `git checkout master && git merge week-3-cards-nav`

**For detailed workflow:**
- See `GIT-WORKFLOW.md` for complete documentation
- See `GIT-WORKFLOW-QUICK-REF.md` for common commands

**Note:** Weeks 1-2 were completed on master (before branching policy). Week 3+ will follow weekly branching.

---

## Before You Start

Read these files in order:
1. `PROGRESS-STATUS.txt` — Overall progress (you are here: 33% complete)
2. `WEEKS1-2-SUMMARY.md` — What was accomplished
3. `COLOR-REFERENCE.md` — Handy color lookup

## Development Setup

```bash
# Start Hugo dev server
hugo server --bind=0.0.0.0 --baseURL=http://localhost:1313

# In another terminal, watch CSS changes
npm run watch

# Or build CSS once
npm run build
```

Access site at: http://localhost:1313

## Components to Build (Week 3)

### 1. Article Card Component (~2 hours)

**File:** `themes/danix-xyz-hacker/assets/css/main.css` (add to `@layer components`)

**CSS structure:**
```css
.card {
  @apply border border-border rounded-lg overflow-hidden transition-all duration-200;
  box-shadow: 0 0 20px var(--accent-glow);
}

.card:hover {
  transform: translateY(-2px);
  box-shadow: 0 0 30px var(--accent-glow);
}

.card-image {
  @apply aspect-video object-cover w-full;
}

.card-body {
  @apply p-5 md:p-6 space-y-3;
}

.card-title {
  @apply text-xl font-semibold;
}

.card-excerpt {
  @apply text-text-dim text-sm line-clamp-3;
}

.card-footer {
  @apply flex items-center justify-between gap-4;
}
```

**Usage in templates:**
```html
<article class="card">
  <img src="..." alt="..." class="card-image">
  <div class="card-body">
    <h3 class="card-title">Article Title</h3>
    <p class="card-excerpt">Excerpt text...</p>
    <div class="card-footer">
      <span class="badge badge-tech">Tech</span>
      <a href="..." class="btn btn-sm">Read More</a>
    </div>
  </div>
</article>
```

**Test at:**
- `/en/articles/` (article list)
- All responsive breakpoints
- Dark and light modes

---

### 2. Navigation Header (~1.5 hours)

**File:** Likely `themes/danix-xyz-hacker/layouts/partials/header.html` (check if exists)

**CSS structure:**
```css
.header {
  @apply fixed top-0 left-0 right-0 z-40;
}

.header-nav {
  @apply hidden md:flex items-center gap-6;
}

.nav-link {
  @apply text-text hover:text-accent transition-colors;
}

.header-actions {
  @apply flex items-center gap-4;
}
```

**Components to include:**
- Logo/site name
- Navigation links (Articles, About, Contact)
- Theme toggle button (use `.btn-icon`)
- Language switcher (if needed)
- Hamburger button (mobile-only)

**Test:**
- Mobile (320px) — hamburger visible
- Tablet (768px) — transition point
- Desktop (1060px+) — full nav visible

---

### 3. Hamburger Menu (~1.5 hours)

**File:** New JS file `themes/danix-xyz-hacker/assets/js/hamburger.js`

**Functionality:**
- Click hamburger → overlay slides in
- Click close/backdrop → overlay slides out
- ESC key → close
- Smooth animation (200–300ms)
- Body scroll locked when open

**CSS:**
```css
.menu-overlay {
  @apply fixed inset-0 bg-bg z-30 transition-opacity duration-200;
}

.menu-overlay.hidden {
  display: none;
}

.menu-nav {
  @apply flex flex-col gap-4 p-6;
}

.menu-nav a {
  @apply text-lg font-semibold hover:text-accent transition-colors;
}
```

**Test:**
- Click hamburger → menu appears
- Click close → menu disappears
- Press ESC → menu disappears
- Mobile responsive
- Scroll locked when open

---

### 4. Breadcrumb Navigation (~1 hour)

**File:** `themes/danix-xyz-hacker/layouts/partials/breadcrumb.html` (new)

**CSS:**
```css
.breadcrumb {
  @apply flex items-center gap-2 text-sm text-text-dim;
}

.breadcrumb a {
  @apply hover:text-accent transition-colors;
}

.breadcrumb-separator {
  @apply opacity-50;
}
```

**Usage:**
```html
<nav class="breadcrumb">
  <a href="/">Home</a>
  <span class="breadcrumb-separator">/</span>
  <a href="/articles/">Articles</a>
  <span class="breadcrumb-separator">/</span>
  <span>Article Title</span>
</nav>
```

**Test:**
- Appears on article detail pages
- Links work
- Mobile responsive
- Visible in dark/light modes

---

## Workflow

1. **Read existing templates** to understand structure
2. **Add CSS** to `main.css` in `@layer components`
3. **Update templates** to use new component classes
4. **Rebuild CSS:** `npm run build`
5. **Test in browser:**
   - Dark mode (homepage)
   - Light mode (toggle button)
   - Mobile, tablet, desktop
   - Keyboard navigation
   - Click/hover interactions
6. **Check git diff** for anything unexpected
7. **Commit** with clear message

## Quick Commands

```bash
# Build CSS
npm run build

# Watch CSS for changes (recommended during development)
npm run watch

# Start Hugo server
hugo server

# Check git status
git status

# See what changed in CSS
git diff themes/danix-xyz-hacker/assets/css/main.css
```

## Checklist for Week 3

Component Implementation:
- [ ] Article card component (CSS)
- [ ] Card hover effects (lift, shadow)
- [ ] Integration into article list template
- [ ] Navigation header (HTML + CSS)
- [ ] Logo and nav links
- [ ] Theme toggle button
- [ ] Hamburger menu (CSS + JS)
- [ ] Menu overlay styling
- [ ] Menu close button
- [ ] Breadcrumb component (CSS)
- [ ] Integration into article detail page

Testing:
- [ ] Dark mode: All components visible
- [ ] Light mode: All components visible
- [ ] Mobile (320px): All responsive
- [ ] Tablet (768px): Hamburger → nav transition
- [ ] Desktop (1060px+): Full nav visible, hamburger hidden
- [ ] Keyboard navigation: Tab through all interactive elements
- [ ] Focus states: Visible on all buttons/links
- [ ] Click interactions: All buttons/menus work
- [ ] CSS build: No errors, <200ms

Documentation:
- [ ] Update WEEKS1-2-SUMMARY.md with Week 3 progress
- [ ] Create week3_complete.md in memory/
- [ ] Update memory/MEMORY.md with Week 3 reference

---

## Key Principles

✅ **Always use CSS variables** — Never hard-code colors  
✅ **Build on existing components** — Buttons, badges already done  
✅ **Mobile-first** — Start with smallest screen, expand up  
✅ **Dark/light mode** — Test both modes  
✅ **Accessibility** — Tab, focus, aria-labels  
✅ **Smooth animations** — 200-300ms transitions, GPU acceleration  
✅ **Keep it simple** — No bloat, Slackware philosophy  

## Reference

- `COLOR-REFERENCE.md` — All 30 CSS colors
- `WEEK2-IMPLEMENTATION.md` — Button/badge patterns
- `COMPONENT-TEST.md` — Testing checklist template

## Still Stuck?

Check existing partials:
```bash
ls themes/danix-xyz-hacker/layouts/partials/
```

Look for patterns in existing components:
```bash
grep "class=\"card" themes/danix-xyz-hacker/layouts/**/*.html
grep "@apply" themes/danix-xyz-hacker/assets/css/main.css
```

---

## Estimated Time

- Article cards: 2 hours
- Navigation header: 1.5 hours
- Hamburger menu: 1.5 hours
- Breadcrumbs: 1 hour
- Testing & refinement: 1–2 hours

**Total: 7–8 hours**

Good luck! You've got this. 🚀