path: root/docs/superpowers/specs/2026-04-15-hugo-theme-design.md

# danix.xyz Hugo Theme Design Specification

**Date**: April 15, 2026  
**Project**: Hugo theme for personal portfolio/blog (https://danix.xyz)  
**Philosophy**: Slackware-style (clean, essential, no bloat) with hacker/open-source aesthetic

---

## 1. Project Overview

danix.xyz is a **portfolio/blog site** with bilingual support (Italian/English). The theme must:
- Deliver a modern, distinctive visual experience
- Reuse font stack and color palette foundations from danix.me (but not replicate the design)
- Support flexible, easy-to-configure content structure
- Maintain accessibility (WCAG 2.1 AA)
- Be responsive (mobile-first)

---

## 2. Architecture & Tech Stack

### Theme Foundation
- **Hugo (Extended)** with Hugo Pipes for asset processing and minification
- **Tailwind CSS** (utility-first, @apply for semantic components)
- **Alpine.js** for interactive elements (menu toggle, language switching, theme switching)
- **Vanilla JS** for minimal optimizations where Alpine isn't needed
- **Chroma** (Hugo's built-in syntax highlighter) for code blocks

### Configuration-Driven Design
**All major configuration** (menus, static pages, content types, theme options) lives in **hugo.toml**. This enables:
- Easy addition of new static pages without touching code
- Extensible article type system
- Theme option management in one place

### Multilingual Support (i18n)
- **Structure**: `i18n/it.yaml` and `i18n/en.yaml` for all UI strings
- **Default**: Italian (IT)
- **Supported**: English (EN)
- **Scope**: Navigation labels, button text, page headings, form labels, error messages
- **Language switching**: Toggle in hamburger menu with state persistence

---

## 3. Content Structure

### 3.1 Landing Page (`/`)
**Source**: `content/_index.md` (front-matter + markdown)

**Components**:
- Hero section: Profile photo, name, brief bio (multilingual)
- Two CTAs: "Read Articles" → `/articles/` | "Get in Touch" → `/is/here/`
- Clean, centered layout
- No feed or preview content

**Layout**: Full-width, centered, vertical spacing emphasizes simplicity

---

### 3.2 Articles Section (`/articles/`)

#### List View
- **Sorting**: Reverse chronological (newest first)
- **Pinned posts**: One post can stay at top via `pinned: true` in front-matter
- **Display**: Title + date + type badge + excerpt (optional)
- **Type badge colors**: Each article type has a distinct visual identifier

#### Article Types (5)
1. **Life** — Generic blog posts, personal thoughts, reflections
2. **Photo** — Single image or gallery, visual-focused
3. **Link** — External URL with commentary
4. **Quote** — Pull quote with author attribution
5. **Tech** — Code snippets, technical content, tutorials

Color mapping:

| Type | Dark Mode | Light Mode | Use |
|---|---|---|---|
| **Life** | `#f59e0b` (Amber) | `#d97706` (Amber) | Personal essays, life updates |
| **Photo** | `#ec4899` (Pink) | `#be185d` (Pink) | Photo essays, galleries |
| **Link** | `#38bdf8` (Cyan) | `#0284c7` (Cyan) | Bookmarks, external links |
| **Quote** | `#00ff88` (Green) | `#008f5a` (Green) | Quotes, inspirational content |
| **Tech** | `#a855f7` (Purple) | `#7c3aed` (Purple) | Technical articles, tutorials |

Each type gets an optimized single-article template.

#### Single Article View
**Source**: `content/articles/[slug]/index.md` (Page Bundles)

**Layout**: 
- **Desktop (1024px+)**: Two-column (main content + sticky sidebar)
- **Mobile (<768px)**: Single column (sidebar moves to bottom)

**Main Content**:
- Type badge (e.g., "TECH")
- Title (h1)
- Metadata: Published date, updated date (if applicable), reading time
- Article content (markdown with syntax-highlighted code blocks)
- Tags (bottom of content)

**Sidebar** (responsive positioning):
- **Share section**: Twitter, Facebook, Copy Link buttons
- **Article info**: Published date, updated date, reading time, category
- **Related posts**: Links to 2-3 related articles
- Desktop: Sticky positioning (stays visible during scroll)
- Mobile: Flows to bottom of page

**Syntax Highlighting**:
- Language: Chroma (built-in Hugo)
- Trigger: Markdown code fences with language tag (```go, ```python, etc.)
- Theme: Custom CSS matching danix.xyz colors (purple accent #a855f7, green highlights #00ff88)
- Options: Line numbers configurable in hugo.toml

---

### 3.3 Static Pages

**URLs & Examples**:
- `/is/` — About page
- `/is/here/` — Contact page  
- `/is/legal/` — Privacy policy

**Configuration**: All static page URLs defined in `hugo.toml` menus section. Adding new pages:
1. Create markdown file in `content/pages/[slug]/index.md`
2. Add menu entry to hugo.toml
3. Theme automatically routes and renders

**Layout**: Same two-column + sidebar structure as articles (desktop/mobile responsive)

**Sidebar content** (per page):
- About: Social links, skills, CV download, contact info
- Contact: Email, response time, availability, social profiles
- Legal: Last updated date, version info

---

## 4. Navigation & Menu System

### Top Navigation (Desktop)
- Logo/brand name on left
- Menu items on right: Articles | About | Contact | Hamburger icon
- Sticky positioning (stays visible while scrolling)
- Light hover states

### Hamburger Menu (Mobile + Desktop Open)
**Trigger**: Hamburger icon (≡) top right

**Full-screen overlay with**:
- Main menu (Articles, About, Contact, Privacy, etc.)
- Language switcher (IT/EN) with flag icons
- Theme toggle (☀️ / 🌙)
- Close button (X or backdrop click)

**Alpine.js handling**:
- Toggle class on `<html>` element to show/hide overlay
- Language change: Update current language variable, navigate or reload
- Theme change: Toggle `theme-light` / `theme-dark` class on `<html>`

---

## 5. Design & Visual Identity

### Color Palette

#### Dark Mode (Primary)
- **Background**: #060b10 (deepest), #0c1520 (bg2), #101e2d (surface)
- **Borders**: #182840
- **Text**: #c4d6e8 (primary), #7a9bb8 (dim)
- **Accent**: #a855f7 (purple primary), #00ff88 (green secondary)
- **Glow**: rgba(168, 85, 247, 0.12)

#### Light Mode
- **Background**: #f0f4f8 (lightest), #e2eaf4 (bg2), #d4dff0 (surface)
- **Borders**: #a8bdd8
- **Text**: #0d1b2a (primary), #2e4a6a (dim)
- **Accent**: #7c3aed (purple primary), #008f5a (green secondary)
- **Glow**: rgba(124, 58, 237, 0.1)

### Typography

- **Headings**: Oxanium (sans-serif, distinctive, hacker-like)
- **Body text**: IBM Plex Sans (modern, readable, professional)
- **Code/Monospace**: JetBrains Mono (code blocks, inline code, terminal-style elements)

**Font stack fallback**:
```
Oxanium, sans-serif
IBM Plex Sans, system-ui, sans-serif
JetBrains Mono, Courier New, monospace
```

### Visual Elements

- **Dot-grid background**: Subtle radial-gradient pattern (repeating dots)
  - Dark: rgba(168, 85, 247, 0.07) dots on #060b10
  - Light: rgba(124, 58, 237, 0.07) dots on #f0f4f8
  
- **Smooth transitions**: All interactive elements (200ms ease)

- **Minimal glow effects**: Accent color glows on headings, badges, links (0 0 40px with low opacity)

- **Clean borders**: 1px solid with accent color at 15-30% opacity

- **Card/container styling**: 
  - Subtle background tint (accent color at 8-12% opacity)
  - Border with accent at 20% opacity
  - Border-radius: 0.4rem
  - Shadow: None (keep clean)

### Aesthetic Direction

**Inspiration**: Open-source/hacker community aesthetic + Slackware philosophy

**Characteristics**:
- Clean, minimal, no unnecessary decoration
- Modern but with technical roots (monospace touches, terminal vibes)
- Purple + green color combination (distinctive, hacker-like)
- Clear hierarchy and purpose for every element
- Responsive and fast (no bloat)

---

## 5.1 Icons & Icon Fonts

### Philosophy: Premium Monochrome Design

Icons are part of the visual language, not decorative afterthoughts. The danix.xyz icon system uses **Feather Icons** for consistency:

**Why Feather Icons:**
- Minimalist aesthetic, premium appearance (not clipart-style)
- Monochrome by default (pairs with any color)
- Perfect stroke weight (1.5px) for clarity without heaviness
- Comprehensive library (290+ icons covering common use cases)
- Themeable via CSS (color, stroke, size all controllable)
- Responsive at any size (crisp from 16px to 48px+)

**Design principle:** Icons should be subtle, functional, and never draw more attention than the content they support.

### Icon Sizing Scale

Icons scale responsively based on context:

```
16px (0.85rem)  — Small metadata, secondary actions
20px (1.15rem)  — Default, most contexts
24px (1.4rem)   — Buttons, interactive elements
32px (1.9rem)   — Large buttons, featured actions
48px (2.8rem)   — Hero elements, major CTAs
```

### Icon Colors: Context-Dependent Theming

Icons inherit or explicitly use colors based on context. **Never use hard-coded colors—always use CSS custom properties:**

### Icon Stroke: Weight and Line Style

**Feather icons use consistent stroke properties:**

**When to adjust stroke:**
- Keep stroke-width at 1.5 for almost all cases
- Only adjust if icon appears too thin or thick at specific sizes
- Test at actual display size before adjusting

### Article Metadata Icons

**Common metadata icons:**

| Icon | Name | Usage | Example |
|---|---|---|---|
| 📅 | `calendar` | Publication date | "2026-04-08" |
| ⏱️ | `clock` | Read time | "5 min read" |
| ✍️ | `user` | Author name | "By Danilo M." |
| 🏷️ | `tag` | Article category/type | "TECH" badge |
| 🔗 | `link` | External link | "Read on source" |

## 6. Responsive Design

### Breakpoints

- **Mobile**: < 768px
- **Tablet**: 768px - 1023px  
- **Desktop**: 1024px+

### Mobile-First Approach

**Default (mobile)**:
- Single column layout
- Hamburger menu for navigation
- Sidebar content (articles) moves to bottom
- Touch-friendly button sizes

**Tablet (768px+)**:
- Slightly increased padding/spacing
- Wider content area
- Sidebar still below on tablets

**Desktop (1024px+)**:
- Two-column layout (main + sidebar)
- Full navigation visible
- Sidebar sticky positioning (desktop articles/pages)
- Optimized spacing and readability

---

## 7. Interactive Features

### Alpine.js Interactions

1. **Hamburger Menu Toggle**
   - Click hamburger icon → overlay slides in / fades
   - Click backdrop or close button → overlay closes
   - Escape key closes overlay
   - Body scroll disabled while overlay open

2. **Language Switcher**
   - Click language button (IT/EN) → switch language
   - Persist preference to localStorage
   - Page reloads with new language (or client-side routing if SPA-like)

3. **Theme Toggle**
   - Click sun/moon icon → toggle between dark/light
   - Persist to localStorage
   - Immediate class change on `<html>` element (no flash via inline script)

4. **Contact Form** (shortcode-based)
   - AJAX submission to `contact.php` (backend)
   - Show loading state, success message, error handling
   - Translated labels and error messages via i18n

### No-JS Fallback

- Navigation: Form-based or server-side page reload
- Theme: CSS media query `prefers-color-scheme` as fallback
- Menu: Full-page navigation links

---

## 8. Article Type Templates

### Life
**Layout**: Standard article (title, content, metadata, tags, sidebar)

**Front-matter**:
```yaml
type: life
title: Article Title
date: 2026-04-12
pinned: false
draft: false
tags: [tag1, tag2]
categories: [life]
description: Short description
```

### Photo
**Layout**: Standard article with image/gallery focus
**Front-matter**: Same as Life, but emphasizes `featured_image`

### Link
**Layout**: Title + external link button + commentary
**Front-matter**:
```yaml
type: link
title: Interesting Read
external_url: https://example.com
link_title: Read on Example Site
```

### Quote
**Layout**: Large blockquote, author attribution, minimal text
**Front-matter**:
```yaml
type: quote
title: Quote Title
quote_text: "The quote itself..."
quote_author: Author Name
```

### Tech
**Layout**: Standard article with code blocks, syntax-highlighted
**Front-matter**: Same as Life, supports multiple code blocks

---

## 9. Configuration (hugo.toml)

### Key Sections

#### Languages
```toml
[languages.it]
languageName = "IT"
contentDir = "content/it"

[languages.en]
languageName = "EN"
contentDir = "content/en"
```

#### Menus
```toml
[[menus.main]]
name = "Articles"
url = "/articles/"
weight = 1

[[menus.main]]
name = "About"
url = "/is/"
weight = 2

[[menus.footer]]
name = "Privacy"
url = "/is/legal/"
```

#### Theme Params
```toml
[params]
# Site metadata
siteName = "danix.xyz"
author = "Danilo Macrì"
description = "Portfolio and blog"

# Theme options
syntaxHighlight = true
lineNumbers = false
readingTime = true
shareButtons = true
relatedPosts = true

# Colors (optional overrides)
primaryAccent = "#a855f7"
secondaryAccent = "#00ff88"
```

---

## 10. Accessibility (WCAG 2.1 AA)

- **Color contrast**: All text meets 4.5:1 (AA) for body text, 3:1 for larger text
- **Semantic HTML**: Proper heading hierarchy, landmark regions, form labels
- **Keyboard navigation**: All interactive elements accessible via keyboard
- **Focus indicators**: Visible focus states on links and buttons
- **Alt text**: Images have descriptive alt text
- **Skip link**: Skip to main content link (hidden but keyboard-accessible)
- **ARIA labels**: Where needed for icon buttons (hamburger, theme toggle)

---

## 11. Implementation Priorities

### Phase 1 (MVP)
- Basic layout (landing, articles list, single article, static pages)
- Navigation and menu system
- Bilingual support (i18n)
- Dark/light theme toggle
- Mobile responsive

### Phase 2
- Article type-specific templates
- Pinned post support
- Sidebar with metadata and sharing
- Related posts section
- Syntax highlighting

### Phase 3 (Nice to have)
- Contact form (AJAX)
- Comment system (optional)
- Search functionality
- Analytics integration
- Sitemap and RSS feeds

---

## 12. Extensibility

### Adding New Static Pages
1. Create file in `content/pages/[slug]/index.md`
2. Add menu entry in hugo.toml
3. Theme automatically routes (no template changes needed)

### Adding New Article Types
1. Define in hugo.toml under `[params.articleTypes]`
2. Create partial template if special layout needed
3. Use in front-matter `type: newtype`

### Customizing Sidebar
1. Define per-page in front-matter (e.g., `showSharing: true`, `showMetadata: true`)
2. Sidebar partial checks flags and renders accordingly
3. No CSS changes needed

---

## 13. File Structure (Overview)

```
themes/danix-xyz-hacker/
├── layouts/
│   ├── index.html (landing page)
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── single.html (articles/pages)
│   │   └── list.html (articles list)
│   ├── articles/
│   │   ├── single.html (article types dispatch)
│   │   └── [type]/single.html (type-specific)
│   └── partials/
│       ├── header.html
│       ├── footer.html
│       ├── nav.html
│       ├── sidebar.html
│       └── article-types/
│           ├── life.html
│           ├── photo.html
│           ├── link.html
│           ├── quote.html
│           └── tech.html
├── assets/
│   ├── css/
│   │   ├── main.scss
│   │   ├── tailwind.css
│   │   └── chroma-custom.css
│   └── js/
│       ├── main.js
│       └── alpine-setup.js
├── static/
│   └── (images, fonts, files)
├── i18n/
│   ├── it.yaml
│   └── en.yaml
└── hugo.toml
```

---

## 14. Success Criteria

- ✅ Landing page with hero + CTAs
- ✅ Articles list (reverse chrono, pinned support)
- ✅ 5 article types with optimized templates
- ✅ Static pages with custom URLs (all from config)
- ✅ Bilingual (IT/EN) with language switcher
- ✅ Dark/light theme toggle
- ✅ Responsive (mobile-first, desktop sidebar)
- ✅ Syntax highlighting for code blocks
- ✅ Sidebar with share/metadata (sticky desktop, bottom mobile)
- ✅ WCAG 2.1 AA accessibility
- ✅ Zero unnecessary dependencies (Slackware philosophy)