initial commit

1 files changed, 548 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-04-15-hugo-theme-design.md b/docs/superpowers/specs/2026-04-15-hugo-theme-design.md
new file mode 100644
index 0000000..2aa1ea1
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-15-hugo-theme-design.md
@@ -0,0 +1,548 @@
+# 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)