From: Danilo M. Date: Wed, 29 Apr 2026 14:05:31 +0000 (+0200) Subject: docs: add callout spec/plan, actions shortcode in bash-notes, fix IT trailing newline X-Git-Tag: release_29042026-1634^2~1 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=9f74b1a1b6b4dfdfaa3d4aecbf3bbc5215390f14;p=danix.xyz-2.git docs: add callout spec/plan, actions shortcode in bash-notes, fix IT trailing newline - docs/superpowers/specs/2026-04-29-callout-shortcode-design.md — approved design spec - docs/superpowers/plans/2026-04-29-callout-shortcode.md — implementation plan - content/en/articles/bash-notes: add actions download button - content/it/articles/bash-notes: fix missing trailing newline Co-Authored-By: Claude Sonnet 4.6 --- diff --git a/content/en/articles/bash-notes/index.md b/content/en/articles/bash-notes/index.md index c11c812..5a2e745 100644 --- a/content/en/articles/bash-notes/index.md +++ b/content/en/articles/bash-notes/index.md @@ -160,6 +160,8 @@ And the script will take care of putting everything back where it belongs. ### Installing +{{< actions inclass="border-2 shadow-xl mx-auto" outclass="flex justify-center" url="https://git.danix.xyz/?p=bash-notes.git;a=summary" desc="Download from Git Repository" >}} + Simply copy the script in your $PATH and make it executable, something like this should work: ```bash diff --git a/content/it/articles/bash-notes/index.md b/content/it/articles/bash-notes/index.md index db87caf..1e88c06 100644 --- a/content/it/articles/bash-notes/index.md +++ b/content/it/articles/bash-notes/index.md @@ -8,4 +8,4 @@ author = "Danilo M." +++ -TODO: Tradurre questo articolo dall'inglese all'italiano. +TODO: Tradurre questo articolo dall'inglese all'italiano. \ No newline at end of file diff --git a/docs/superpowers/plans/2026-04-29-callout-shortcode.md b/docs/superpowers/plans/2026-04-29-callout-shortcode.md new file mode 100644 index 0000000..ba772bf --- /dev/null +++ b/docs/superpowers/plans/2026-04-29-callout-shortcode.md @@ -0,0 +1,576 @@ +# 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" -}} + +
+
+ + {{ $title }} +
+
+ {{- .Inner | markdownify -}} +
+
+``` + +- [ ] **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** diff --git a/docs/superpowers/specs/2026-04-29-callout-shortcode-design.md b/docs/superpowers/specs/2026-04-29-callout-shortcode-design.md new file mode 100644 index 0000000..e9c6a3d --- /dev/null +++ b/docs/superpowers/specs/2026-04-29-callout-shortcode-design.md @@ -0,0 +1,225 @@ +# 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 ``. 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" -}} + +
+
+ + {{ $title }} +
+
+ {{ .Inner | markdownify }} +
+
+``` + +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)