path: root/docs/superpowers/plans/2026-04-29-callout-shortcode.md

# 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**