--- /dev/null
+# Callout Shortcode Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `{{< callout >}}` Hugo shortcode with 6 semantic types (note, tip, info, warning, danger, success), CSS-only styling, full i18n (EN/IT), and WCAG AA compliance.
+
+**Architecture:** Single shortcode template (`callout.html`) emits semantic HTML with type-derived CSS classes. All visual styling lives in `main.css` via CSS custom properties — no inline styles or Hugo logic in the template. Colors reuse existing theme tokens (`--accent`, `--accent2`, `--type-link`, `--type-life`); only `--callout-danger` is a hardcoded exception (red, approved).
+
+**Tech Stack:** Hugo templating, Tailwind CSS (`@apply`), CSS custom properties, Feather Icons (already loaded site-wide), i18n YAML.
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `themes/danix-xyz-hacker/assets/css/main.css` | **Modify (Task 0)** | Fix drifted `html.theme-light` vars to match THEMING-STANDARD |
+| `themes/danix-xyz-hacker/layouts/shortcodes/callout.html` | **Create** | Shortcode template — HTML structure, ARIA, icon+title, markdown body |
+| `themes/danix-xyz-hacker/assets/css/main.css` | **Modify (Tasks 1–2)** | `--callout-*` CSS vars in `:root` + `html.theme-light`; `.callout` + `.callout-*` component classes |
+| `themes/danix-xyz-hacker/assets/css/main.min.css` | **Rebuild** | Compiled output — regenerated via `npm run build` |
+| `themes/danix-xyz-hacker/i18n/en.yaml` | **Modify** | 6 English callout title keys |
+| `themes/danix-xyz-hacker/i18n/it.yaml` | **Modify** | 6 Italian callout title keys |
+| `i18n/en.yaml` | **Modify** | Mirror keys (content repo overrides theme i18n) |
+| `i18n/it.yaml` | **Modify** | Mirror keys (content repo overrides theme i18n) |
+| `SHORTCODES.md` | **Modify** | Document callout shortcode before "Future Shortcodes" section |
+
+---
+
+## Task 0: Fix drifted `html.theme-light` vars in `main.css`
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/assets/css/main.css` (lines 35–62, `html.theme-light` block)
+
+The current `html.theme-light` block has values that differ from THEMING-STANDARD.md. This task corrects the drift before any callout work builds on top.
+
+**Current vs correct values:**
+
+| Variable | Current in main.css | THEMING-STANDARD correct value |
+|----------|--------------------|---------------------------------|
+| `--bg` | `#ffffff` | `#f0f4f8` |
+| `--bg2` | `#f8f9fa` | `#e2eaf4` |
+| `--bg2-rgb` | `248, 249, 250` | `232, 234, 244` |
+| `--surface` | `#f0f3f7` | `#d4dff0` |
+| `--surface-rgb` | `240, 243, 247` | `212, 223, 240` |
+| `--border` | `#d9dfe8` | `#a8bdd8` |
+| `--accent` | `#9333ea` | `#7c3aed` |
+| `--accent-rgb` | `147, 51, 234` | `124, 58, 237` |
+| `--accent2` | `#10b981` | `#008f5a` |
+| `--accent-glow` | `rgba(147, 51, 234, 0.1)` | `rgba(124, 58, 237, 0.1)` |
+| `--text` | `#1f2937` | `#0d1b2a` |
+| `--text-dim` | `#374151` | `#2e4a6a` |
+| `--muted` | `#d1d5db` | `#6888a8` |
+| `--type-tech` | `#7c3aed` | `#7c3aed` ✓ same |
+| `--type-life` | `#d97706` | `#d97706` ✓ same |
+| `--type-quote` | `#008f5a` | `#008f5a` ✓ same |
+| `--type-link` | `#0284c7` | `#0284c7` ✓ same |
+| `--type-photo` | `#be185d` | `#be185d` ✓ same |
+
+- [ ] **Step 1: Replace the entire `html.theme-light` block**
+
+Find and replace the `html.theme-light { ... }` block (lines 35–62) with:
+
+```css
+/* Light theme overrides */
+html.theme-light {
+ --bg: #f0f4f8;
+ --bg2: #e2eaf4;
+ --bg2-rgb: 232, 234, 244;
+ --surface: #d4dff0;
+ --surface-rgb: 212, 223, 240;
+ --border: #a8bdd8;
+ --accent: #7c3aed;
+ --accent-rgb: 124, 58, 237;
+ --accent2: #008f5a;
+ --accent-glow: rgba(124, 58, 237, 0.1);
+ --text: #0d1b2a;
+ --text-dim: #2e4a6a;
+ --muted: #6888a8;
+ /* Article type colors - light */
+ --type-tech: #7c3aed;
+ --type-life: #d97706;
+ --type-quote: #008f5a;
+ --type-link: #0284c7;
+ --type-photo: #be185d;
+ /* Article type text colors - light (mixed for WCAG AA) */
+ --type-tech-text: #ffffff;
+ --type-life-text: #000000;
+ --type-quote-text: #000000;
+ --type-link-text: #000000;
+ --type-photo-text: #ffffff;
+}
+```
+
+Also find the `@media (prefers-color-scheme: light)` block (lines ~64–91) and apply the same value corrections there — it mirrors `html.theme-light` for the no-JS fallback.
+
+- [ ] **Step 2: Rebuild CSS and do a visual check**
+
+```bash
+npm run build
+hugo server
+```
+
+Open the site and toggle light mode. Confirm: background is now a slightly blue-tinted off-white (`#f0f4f8`) rather than pure white. Text is darker navy (`#0d1b2a`). No layout breakage.
+
+- [ ] **Step 3: Commit the fix**
+
+```bash
+cd /home/danix/Programming/GIT/danix2-hugo-theme
+git add assets/css/main.css
+git commit -m "fix: align html.theme-light CSS vars with THEMING-STANDARD.md"
+git push origin master
+```
+
+---
+
+## Task 1: Add CSS variables to `main.css`
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/assets/css/main.css` (lines 6–34 `:root` block, lines 35–62 `html.theme-light` block)
+
+- [ ] **Step 1: Add `--callout-*` vars to `:root` block**
+
+In `themes/danix-xyz-hacker/assets/css/main.css`, find the `:root` block. After the `--type-photo-text: #000000;` line (line 31), add:
+
+```css
+ /* Callout shortcode colors */
+ --callout-note: var(--accent);
+ --callout-tip: var(--accent2);
+ --callout-info: var(--type-link);
+ --callout-warning: var(--type-life);
+ --callout-danger: #ef4444;
+ --callout-success: var(--accent2);
+```
+
+- [ ] **Step 2: Add `--callout-danger` override to `html.theme-light` block**
+
+In `html.theme-light` (lines 35–62), after `--type-photo-text: #ffffff;` (line 61), add:
+
+```css
+ /* Callout shortcode colors */
+ --callout-danger: #ef4444;
+```
+
+Note: all other `--callout-*` vars resolve automatically via `--accent`, `--accent2`, `--type-link`, `--type-life` which already have light overrides. Only danger needs explicit repeat since it's hardcoded.
+
+- [ ] **Step 3: Verify vars resolve correctly in both themes**
+
+Run `hugo server` and in browser devtools inspect `:root` computed styles — confirm `--callout-note` resolves to `#a855f7` in dark and `#9333ea` in light.
+
+---
+
+## Task 2: Add `.callout` component CSS
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/assets/css/main.css` (after toast block, ~line 1724)
+
+- [ ] **Step 1: Add callout component block at end of file, before the `prefers-reduced-motion` block**
+
+Find the `/* Motion Safety */` comment (line ~1708). Insert the following block immediately before it:
+
+```css
+/* ============================================================
+ Callout Shortcode
+ ============================================================ */
+
+.callout {
+ @apply relative my-6 py-3 px-4 rounded-r-md;
+}
+
+.callout::after {
+ content: '';
+ position: absolute;
+ bottom: 0;
+ left: 0;
+ width: 50%;
+ height: 1px;
+ background: linear-gradient(to right, var(--callout-color), transparent);
+}
+
+.callout-title {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ margin-bottom: 0.375rem;
+}
+
+.callout-title span {
+ font-family: var(--font-mono, 'JetBrains Mono', monospace);
+ font-size: 11px;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.08em;
+ color: var(--callout-color);
+}
+
+.callout-title svg,
+.callout-title i {
+ width: 14px;
+ height: 14px;
+ color: var(--callout-color);
+ flex-shrink: 0;
+}
+
+.callout-body {
+ color: var(--text);
+ font-size: 0.875rem;
+ line-height: 1.6;
+}
+
+.callout-body p:last-child {
+ margin-bottom: 0;
+}
+
+/* Type variants — sets --callout-color for border, title, icon, and ::after gradient */
+.callout-note { --callout-color: var(--callout-note); border-left: 4px solid var(--callout-note); background: rgba(168, 85, 247, 0.08); }
+.callout-tip { --callout-color: var(--callout-tip); border-left: 4px solid var(--callout-tip); background: rgba(0, 255, 136, 0.08); }
+.callout-info { --callout-color: var(--callout-info); border-left: 4px solid var(--callout-info); background: rgba(56, 189, 248, 0.08); }
+.callout-warning { --callout-color: var(--callout-warning); border-left: 4px solid var(--callout-warning); background: rgba(245, 158, 11, 0.08); }
+.callout-danger { --callout-color: var(--callout-danger); border-left: 4px solid var(--callout-danger); background: rgba(239, 68, 68, 0.08); }
+.callout-success { --callout-color: var(--callout-success); border-left: 4px solid var(--callout-success); background: rgba(0, 255, 136, 0.08); }
+
+/* Light mode — reduce opacity to 0.06 per theming standard
+ rgba values derived from THEMING-STANDARD.md corrected vars:
+ --accent #7c3aed, --accent2 #008f5a, --type-link #0284c7, --type-life #d97706 */
+html.theme-light .callout-note { background: rgba(124, 58, 237, 0.06); } /* #7c3aed */
+html.theme-light .callout-tip { background: rgba(0, 143, 90, 0.06); } /* #008f5a */
+html.theme-light .callout-info { background: rgba(2, 132, 199, 0.06); } /* #0284c7 */
+html.theme-light .callout-warning { background: rgba(217, 119, 6, 0.06); } /* #d97706 */
+html.theme-light .callout-danger { background: rgba(239, 68, 68, 0.06); } /* #ef4444 */
+html.theme-light .callout-success { background: rgba(0, 143, 90, 0.06); } /* #008f5a */
+```
+
+- [ ] **Step 2: Rebuild CSS**
+
+```bash
+npm run build
+```
+
+Expected: no errors, `themes/danix-xyz-hacker/assets/css/main.min.css` updated.
+
+- [ ] **Step 3: Verify `.callout-*` classes in compiled output**
+
+```bash
+grep -c "callout" themes/danix-xyz-hacker/assets/css/main.min.css
+```
+
+Expected: number > 0 (classes present in output).
+
+---
+
+## Task 3: Create the shortcode template
+
+**Files:**
+- Create: `themes/danix-xyz-hacker/layouts/shortcodes/callout.html`
+
+- [ ] **Step 1: Create `callout.html`**
+
+```html
+{{- $type := .Get "type" | default "note" -}}
+{{- $title := .Get "title" | default (i18n (printf "callout_%s" $type)) -}}
+{{- $role := cond (eq $type "danger") "alert" "note" -}}
+{{- $icons := dict "note" "edit-2" "tip" "zap" "info" "info" "warning" "alert-triangle" "danger" "x-circle" "success" "check-circle" -}}
+{{- $icon := index $icons $type | default "info" -}}
+
+<div class="callout callout-{{ $type }}" role="{{ $role }}">
+ <div class="callout-title">
+ <i data-feather="{{ $icon }}" class="w-3.5 h-3.5" aria-hidden="true"></i>
+ <span>{{ $title }}</span>
+ </div>
+ <div class="callout-body">
+ {{- .Inner | markdownify -}}
+ </div>
+</div>
+```
+
+- [ ] **Step 2: Verify Hugo renders it without errors**
+
+Add a test callout to any article's `index.md` temporarily:
+
+```markdown
+{{< callout type="warning" >}}
+Test warning callout.
+{{< /callout >}}
+```
+
+Run `hugo server` — confirm no template errors in terminal output.
+
+- [ ] **Step 3: Remove test callout from article**
+
+Revert the temporary test addition.
+
+---
+
+## Task 4: Add i18n keys — theme repo
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/i18n/en.yaml`
+- Modify: `themes/danix-xyz-hacker/i18n/it.yaml`
+
+- [ ] **Step 1: Add English keys to `themes/danix-xyz-hacker/i18n/en.yaml`**
+
+Append at end of file:
+
+```yaml
+# Callout shortcode titles
+callout_note: "Note"
+callout_tip: "Tip"
+callout_info: "Info"
+callout_warning: "Warning"
+callout_danger: "Danger"
+callout_success: "Success"
+```
+
+- [ ] **Step 2: Add Italian keys to `themes/danix-xyz-hacker/i18n/it.yaml`**
+
+Append at end of file:
+
+```yaml
+# Titoli shortcode callout
+callout_note: "Nota"
+callout_tip: "Suggerimento"
+callout_info: "Informazione"
+callout_warning: "Attenzione"
+callout_danger: "Pericolo"
+callout_success: "Successo"
+```
+
+- [ ] **Step 3: Verify i18n resolution**
+
+Run `hugo server` with an Italian article that contains `{{< callout type="note" >}}test{{< /callout >}}`. Confirm title shows "Nota" on the IT page and "Note" on the EN page.
+
+---
+
+## Task 5: Add i18n keys — content repo
+
+**Files:**
+- Modify: `i18n/en.yaml`
+- Modify: `i18n/it.yaml`
+
+(Content repo i18n overrides theme i18n. Must mirror keys here.)
+
+- [ ] **Step 1: Add English keys to `i18n/en.yaml`**
+
+Append at end of file:
+
+```yaml
+# Callout shortcode titles
+callout_note: "Note"
+callout_tip: "Tip"
+callout_info: "Info"
+callout_warning: "Warning"
+callout_danger: "Danger"
+callout_success: "Success"
+```
+
+- [ ] **Step 2: Add Italian keys to `i18n/it.yaml`**
+
+Append at end of file:
+
+```yaml
+# Titoli shortcode callout
+callout_note: "Nota"
+callout_tip: "Suggerimento"
+callout_info: "Informazione"
+callout_warning: "Attenzione"
+callout_danger: "Pericolo"
+callout_success: "Successo"
+```
+
+---
+
+## Task 6: Commit theme repo changes
+
+**Files:** `themes/danix-xyz-hacker/` (all modified files)
+
+- [ ] **Step 1: Stage and commit in theme repo**
+
+```bash
+cd /home/danix/Programming/GIT/danix2-hugo-theme
+git add assets/css/main.css assets/css/main.min.css layouts/shortcodes/callout.html i18n/en.yaml i18n/it.yaml
+git commit -m "feat: add callout shortcode (note/tip/info/warning/danger/success)
+
+- Single shortcode with type param, CSS-only variants
+- Left border + fading bottom border design
+- Colors mapped to existing theme tokens (--accent, --accent2, --type-link, --type-life)
+- --callout-danger: #ef4444 hardcoded exception (approved)
+- role=alert for danger, role=note for all others (WCAG AA)
+- aria-hidden on Feather icons
+- EN/IT i18n keys, title param overridable"
+git push origin master
+```
+
+Expected: push succeeds to `danix_git:danix2-hugo-theme`.
+
+---
+
+## Task 7: Document in SHORTCODES.md
+
+**Files:**
+- Modify: `SHORTCODES.md`
+
+- [ ] **Step 1: Add Callout section before "Future Shortcodes"**
+
+Find the `## Future Shortcodes` heading in `SHORTCODES.md`. Insert the following section immediately before it:
+
+```markdown
+## Callout
+
+Display a semantic callout box for notes, tips, warnings, and other inline asides. All 6 types are styled via CSS — no extra configuration required.
+
+### Syntax
+
+```
+{{< callout type="note" >}}
+Your content here. Supports **markdown**.
+{{< /callout >}}
+```
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `type` | Yes | — | One of: `note`, `tip`, `info`, `warning`, `danger`, `success` |
+| `title` | No | Translated label for type | Overrides the default title |
+
+### Examples
+
+Note:
+```
+{{< callout type="note" >}}
+This behavior changed in v2.0. Check the migration guide before upgrading.
+{{< /callout >}}
+```
+
+Tip:
+```
+{{< callout type="tip" >}}
+Pass `--fast` to skip the slow validation step in dev.
+{{< /callout >}}
+```
+
+Info:
+```
+{{< callout type="info" >}}
+This feature is available on all plans including the free tier.
+{{< /callout >}}
+```
+
+Warning:
+```
+{{< callout type="warning" >}}
+Watch out for this edge case when deploying to production.
+{{< /callout >}}
+```
+
+Danger:
+```
+{{< callout type="danger" >}}
+This action is irreversible. All data will be permanently deleted.
+{{< /callout >}}
+```
+
+Success:
+```
+{{< callout type="success" >}}
+Build completed. 234 pages generated in 392ms.
+{{< /callout >}}
+```
+
+Custom title:
+```
+{{< callout type="warning" title="Heads up" >}}
+Custom title overrides the default i18n label.
+{{< /callout >}}
+```
+
+### Accessibility Notes
+
+- `role="alert"` on `danger` type — screen readers announce immediately
+- `role="note"` on all other types — non-intrusive
+- Feather icons are decorative (`aria-hidden="true"`) — title text always conveys the type
+
+### Common `type` Values
+
+| Type | Color | Feather Icon | Use for |
+|------|-------|-------------|---------|
+| `note` | Purple (`--accent`) | `edit-2` | Extra context, side remarks |
+| `tip` | Green (`--accent2`) | `zap` | Best practices, shortcuts |
+| `info` | Cyan (`--type-link`) | `info` | Neutral information |
+| `warning` | Amber (`--type-life`) | `alert-triangle` | Potential pitfalls |
+| `danger` | Red (`#ef4444`) | `x-circle` | Destructive actions, breaking changes |
+| `success` | Green (`--accent2`) | `check-circle` | Confirmed results, completed steps |
+```
+
+Also remove `Callout` from the `## Future Shortcodes` section bullet list.
+
+---
+
+## Task 8: Commit and push content repo
+
+**Files:** `i18n/en.yaml`, `i18n/it.yaml`, `SHORTCODES.md`, `themes/danix-xyz-hacker` (submodule pointer)
+
+- [ ] **Step 1: Stage and commit content repo**
+
+```bash
+cd /home/danix/Programming/GIT/danix.xyz-hacker-theme
+git add themes/danix-xyz-hacker i18n/en.yaml i18n/it.yaml SHORTCODES.md
+git commit -m "feat: callout shortcode — i18n keys, docs, bump theme submodule"
+git push origin master
+```
+
+---
+
+## Task 9: Full verification
+
+- [ ] **Step 1: Render all 6 types and verify visuals**
+
+Add to a test article:
+
+```markdown
+{{< callout type="note" >}}Note body{{< /callout >}}
+{{< callout type="tip" >}}Tip body{{< /callout >}}
+{{< callout type="info" >}}Info body{{< /callout >}}
+{{< callout type="warning" >}}Warning body{{< /callout >}}
+{{< callout type="danger" >}}Danger body{{< /callout >}}
+{{< callout type="success" >}}Success body{{< /callout >}}
+```
+
+Run `hugo server`. Open article in browser. Confirm:
+- Left border visible in type color
+- Fading bottom gradient visible (50% width, type color → transparent)
+- Title row: Feather icon + uppercase label in type color
+- Body text in `var(--text)` (light on dark bg)
+
+- [ ] **Step 2: Toggle light theme — verify opacity and colors**
+
+Click theme toggle. Confirm:
+- Background opacity visibly lower (0.06 vs 0.08)
+- Border/icon/title colors shift (e.g. note purple goes from `#a855f7` to `#9333ea`)
+- Body text readable against light background (`#1f2937` on `#ffffff`)
+
+- [ ] **Step 3: Test `title` param override**
+
+```markdown
+{{< callout type="warning" title="Heads up" >}}
+Custom title test.
+{{< /callout >}}
+```
+
+Confirm title shows "Heads up" not "Warning".
+
+- [ ] **Step 4: Test on IT language page**
+
+Open an Italian article with a callout. Confirm title shows "Attenzione" for warning, "Nota" for note, etc.
+
+- [ ] **Step 5: Test markdown in body**
+
+```markdown
+{{< callout type="tip" >}}
+Use **bold**, `code`, and [links](https://example.com) inside callouts.
+{{< /callout >}}
+```
+
+Confirm markdown renders correctly inside `.callout-body`.
+
+- [ ] **Step 6: Verify invalid type gracefully degrades**
+
+```markdown
+{{< callout type="unknown" >}}
+Fallback test.
+{{< /callout >}}
+```
+
+Confirm: renders with class `callout-unknown` (no CSS = unstyled but not broken), title falls back to empty string (i18n key not found). No Hugo build error.
+
+- [ ] **Step 7: Clean up test callouts from articles**
--- /dev/null
+# Callout Shortcode — Design Spec
+
+**Date:** 2026-04-29
+**Status:** Approved
+
+---
+
+## Context
+
+Articles on danix.xyz need a way to call out notes, tips, warnings, and other semantic asides inline. No callout shortcode exists yet. SHORTCODES.md lists it as a planned future shortcode. This spec defines the design, CSS architecture, A11y requirements, and shortcode API.
+
+---
+
+## Approach
+
+**Single shortcode + CSS-only variants** (Approach C from brainstorm).
+
+One `callout.html` template handles all 6 types. Type-specific styling lives entirely in `main.css` via CSS custom properties and Tailwind utility classes. No inline style logic in the template. CSS rebuild required after adding new types.
+
+Chosen over:
+- Single shortcode with inline Hugo logic (more template complexity)
+- Separate shortcode per type (6 files, duplicated logic)
+
+---
+
+## Shortcode API
+
+```
+{{< callout type="note" >}}
+Content here. Supports **markdown**.
+{{< /callout >}}
+
+{{< callout type="danger" title="Custom heading" >}}
+Overrides the default i18n title.
+{{< /callout >}}
+```
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `type` | Yes | — | One of: `note`, `tip`, `info`, `warning`, `danger`, `success` |
+| `title` | No | i18n key for type | Overrides the default translated title |
+
+---
+
+## Visual Design
+
+**Layout:** Left border accent (4px solid, type color) + fading bottom border (gradient left→transparent, 50% width, 1px, type color). Subtle background tint. Rounded on right side only (`border-radius: 0 6px 6px 0`).
+
+**Title row:** Feather icon (14×14, `aria-hidden="true"`) + uppercase label in `font-family: var(--font-mono)` (JetBrains Mono), 11px, 0.08em letter-spacing, type color.
+
+**Body text:** `var(--text)`, 14px, 1.6 line-height. Supports markdown via `.Inner | markdownify`.
+
+**Spacing:** `my-6` vertical margin, `py-3 px-4` inner padding.
+
+**Background opacity:** dark 0.08, light 0.06 — consistent with existing toast/badge pattern.
+
+---
+
+## Color System
+
+All colors via CSS custom properties. No hardcoded hex except the approved Danger exception.
+
+### CSS Variables (added to `main.css`)
+
+```css
+/* Dark mode (:root) */
+--callout-note: var(--accent); /* purple #a855f7 */
+--callout-tip: var(--accent2); /* green #00ff88 */
+--callout-info: var(--type-link); /* cyan #38bdf8 */
+--callout-warning: var(--type-life); /* amber #f59e0b */
+--callout-danger: #ef4444; /* red — approved exception, universally semantic */
+--callout-success: var(--accent2); /* green #00ff88 */
+
+/* Light mode (html.theme-light) */
+--callout-note: var(--accent); /* purple #7c3aed */
+--callout-tip: var(--accent2); /* green #008f5a */
+--callout-info: var(--type-link); /* cyan #0284c7 */
+--callout-warning: var(--type-life); /* amber #d97706 */
+--callout-danger: #ef4444; /* red — same in both themes */
+--callout-success: var(--accent2); /* green #008f5a */
+```
+
+### Tailwind Classes (added to `main.css` via `@apply`)
+
+```css
+.callout { @apply relative my-6 py-3 px-4 rounded-r-md; }
+
+/* Each type sets --callout-color so ::after gradient picks it up automatically */
+.callout-note { --callout-color: var(--callout-note); border-left: 4px solid var(--callout-note); background: rgba(168,85,247,0.08); }
+.callout-tip { --callout-color: var(--callout-tip); border-left: 4px solid var(--callout-tip); background: rgba(0,255,136,0.08); }
+.callout-info { --callout-color: var(--callout-info); border-left: 4px solid var(--callout-info); background: rgba(56,189,248,0.08); }
+.callout-warning { --callout-color: var(--callout-warning); border-left: 4px solid var(--callout-warning); background: rgba(245,158,11,0.08); }
+.callout-danger { --callout-color: var(--callout-danger); border-left: 4px solid var(--callout-danger); background: rgba(239,68,68,0.08); }
+.callout-success { --callout-color: var(--callout-success); border-left: 4px solid var(--callout-success); background: rgba(0,255,136,0.08); }
+```
+
+The fading bottom border is a `::after` pseudo-element:
+```css
+.callout::after {
+ content: '';
+ position: absolute;
+ bottom: 0; left: 0;
+ width: 50%; height: 1px;
+ background: linear-gradient(to right, var(--callout-color), transparent);
+}
+```
+
+**Light mode background opacity** — reduce to 0.06 per theming standard (light needs less emphasis).
+rgba values use THEMING-STANDARD.md corrected light vars: `--accent #7c3aed`, `--accent2 #008f5a`, `--type-link #0284c7`, `--type-life #d97706`.
+
+**Prerequisite:** `html.theme-light` in `main.css` must first be corrected to match THEMING-STANDARD.md (see implementation plan Task 0).
+
+```css
+html.theme-light .callout-note { background: rgba(124,58,237,0.06); } /* #7c3aed */
+html.theme-light .callout-tip { background: rgba(0,143,90,0.06); } /* #008f5a */
+html.theme-light .callout-info { background: rgba(2,132,199,0.06); } /* #0284c7 */
+html.theme-light .callout-warning { background: rgba(217,119,6,0.06); } /* #d97706 */
+html.theme-light .callout-danger { background: rgba(239,68,68,0.06); } /* #ef4444 */
+html.theme-light .callout-success { background: rgba(0,143,90,0.06); } /* #008f5a */
+```
+
+---
+
+## Feather Icons per Type
+
+| Type | Feather icon name | Rationale |
+|------|-------------------|-----------|
+| note | `edit-2` | Writing/annotation |
+| tip | `zap` | Quick insight |
+| info | `info` | Standard info |
+| warning | `alert-triangle` | Universal warning symbol |
+| danger | `x-circle` | Stop/error |
+| success | `check-circle` | Confirmed/done |
+
+Icons rendered inline as `<i data-feather="icon-name" class="w-3.5 h-3.5" aria-hidden="true"></i>`. Feather is already loaded site-wide via `baseof.html`.
+
+---
+
+## i18n Keys
+
+Added to all 4 i18n files: `themes/danix-xyz-hacker/i18n/en.yaml`, `it.yaml` and content repo `i18n/en.yaml`, `it.yaml`.
+
+```yaml
+# en.yaml
+callout_note: "Note"
+callout_tip: "Tip"
+callout_info: "Info"
+callout_warning: "Warning"
+callout_danger: "Danger"
+callout_success: "Success"
+
+# it.yaml
+callout_note: "Nota"
+callout_tip: "Suggerimento"
+callout_info: "Informazione"
+callout_warning: "Attenzione"
+callout_danger: "Pericolo"
+callout_success: "Successo"
+```
+
+---
+
+## Accessibility
+
+- `role="note"` on all types — semantic, non-intrusive to screen readers
+- `role="alert"` on `danger` type only — interrupts screen readers immediately (appropriate for critical warnings)
+- `aria-hidden="true"` on all Feather icons — decorative
+- Title text always present (i18n fallback) — color never used alone to convey meaning (WCAG 1.4.1)
+- Body text uses `var(--text)` — verified ≥4.5:1 contrast ratio against `var(--bg)` in both themes per THEMING-STANDARD.md
+- No animations — `prefers-reduced-motion` not required, but `::after` pseudo is static CSS, no transitions added
+
+---
+
+## Files to Create / Modify
+
+| File | Action | Notes |
+|------|--------|-------|
+| `themes/danix-xyz-hacker/layouts/shortcodes/callout.html` | **Create** | Shortcode template |
+| `themes/danix-xyz-hacker/assets/css/main.css` | **Modify** | Add `--callout-*` vars + `.callout-*` classes |
+| `themes/danix-xyz-hacker/i18n/en.yaml` | **Modify** | Add 6 callout title keys |
+| `themes/danix-xyz-hacker/i18n/it.yaml` | **Modify** | Add 6 callout title keys (Italian) |
+| `i18n/en.yaml` | **Modify** | Mirror keys in content repo |
+| `i18n/it.yaml` | **Modify** | Mirror keys in content repo |
+| `SHORTCODES.md` | **Modify** | Document callout shortcode |
+
+CSS rebuild required (`npm run build`) after CSS changes.
+
+---
+
+## Shortcode Template Sketch
+
+```html
+{{- $type := .Get "type" | default "note" -}}
+{{- $title := .Get "title" | default (i18n (printf "callout_%s" $type)) -}}
+{{- $role := cond (eq $type "danger") "alert" "note" -}}
+
+<div class="callout callout-{{ $type }}" role="{{ $role }}">
+ <div class="callout-title">
+ <i data-feather="{{ /* icon per type */ }}" class="w-3.5 h-3.5" aria-hidden="true"></i>
+ <span>{{ $title }}</span>
+ </div>
+ <div class="callout-body">
+ {{ .Inner | markdownify }}
+ </div>
+</div>
+```
+
+Icon selection via Hugo `dict` lookup — no if/else chain:
+```
+{{- $icons := dict "note" "edit-2" "tip" "zap" "info" "info" "warning" "alert-triangle" "danger" "x-circle" "success" "check-circle" -}}
+{{- $icon := index $icons $type | default "info" -}}
+```
+
+---
+
+## Verification
+
+1. Run `hugo server` — render an article with all 6 callout types
+2. Toggle dark/light theme — verify colors switch correctly via CSS vars
+3. Override title with `title="Custom"` — verify it replaces i18n default
+4. Screen reader test: `danger` type must announce immediately (`role="alert"`); others must not interrupt
+5. Run `npm run build` — verify CSS compiles without errors and Tailwind includes all `.callout-*` classes
+6. Check light theme backgrounds use lower opacity (0.06) vs dark (0.08)
