docs: update SHORTCODES.md for upgraded actions CTA block

Documents new `use`, `caption` parameters, icon/behavior mapping table,
and updated examples. Removes outdated outclass/inclass usage examples.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 32 insertions, 40 deletions

diff --git a/SHORTCODES.md b/SHORTCODES.md
index 691e45a..96fb59b 100644
--- a/SHORTCODES.md
+++ b/SHORTCODES.md
@@ -401,69 +401,61 @@ The only way to do great work is to love what you do.
 
 ## Actions
 
-Display a styled action button, typically used for downloads or calls-to-action.
+Display a visually prominent CTA (Call To Action) card. Renders a styled block with an optional description and a primary button. Generic enough for downloads, external links, git repos, or any CTA.
 
 ### Syntax
 
 ```
-{{< actions url="https://example.com/file.zip" desc="Download File" >}}
+{{< actions url="https://example.com" desc="Button label" use="site" caption="Short description." >}}
 ```
 
 ### Parameters
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| url | Yes | URL the button links to |
-| desc | No | Button label text (default: "Download") |
-| outclass | No | CSS classes for the wrapper div |
-| inclass | No | CSS classes for the anchor link element |
-
-### Example
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `url` | Yes | — | URL the button links to |
+| `desc` | No | i18n `actions_cta` ("Open link" / "Apri il link") | Button label text |
+| `use` | No | `"site"` | Intent: drives icon and `download` attribute. See table below. |
+| `caption` | No | — | Short plain-text description rendered above the button |
+| `outclass` | No | — | Extra CSS classes on the outer `.cta-block` wrapper |
+| `inclass` | No | — | Extra CSS classes on the `<a>` button element |
+
+### `use` Values
+
+| Value | Feather Icon | HTML `download` attr | Use for |
+|-------|-------------|----------------------|---------|
+| `site` (default) | `external-link` | No | External websites, pages |
+| `download` | `download` | Yes | Actual file downloads (.zip, .tar.gz, etc.) |
+| `repo` | `git-branch` | No | Git repositories, source code |
+| `mail` | `mail` | No | Email addresses (`mailto:` links) |
 
-Basic download button:
-```
-{{< actions url="https://github.com/user/project/archive.zip" desc="Download ZIP" >}}
-```
+### Examples
 
-Centered button:
+Link to an external site:
 ```
-{{< actions url="https://example.com/file.zip" desc="Download" outclass="flex justify-center" >}}
+{{< actions url="https://packages.danix.xyz" desc="Visit the repository" use="site" caption="Official package repository for Slackware64-current." >}}
 ```
 
-Right-aligned button:
+File download:
 ```
-{{< actions url="https://example.com/file.zip" desc="Download" outclass="flex justify-end" >}}
+{{< actions url="https://github.com/user/project/archive.zip" desc="Download ZIP" use="download" caption="Grab the latest release." >}}
 ```
 
-Extra vertical spacing:
+Git repository:
 ```
-{{< actions url="https://example.com/file.zip" desc="Download" outclass="my-10" >}}
+{{< actions url="https://git.danix.xyz/?p=bash-notes.git;a=summary" desc="View on Git Repository" use="repo" caption="Source code and full history available on the danix.xyz git server." >}}
 ```
 
-Centered with extra spacing:
+Minimal (no caption, default label):
 ```
-{{< actions url="https://example.com/file.zip" desc="Download" outclass="flex justify-center my-10" >}}
+{{< actions url="https://example.com" >}}
 ```
 
-### Common `outclass` Values (wrapper `<div>`)
-
-| Class | Effect |
-|-------|--------|
-| `flex justify-center` | Center button horizontally |
-| `flex justify-end` | Align button to the right |
-| `flex justify-start` | Align button to the left (default flow) |
-| `my-4` / `my-6` / `my-10` | Vertical margin (small / default / large) |
-| `flex justify-center my-10` | Centered with large vertical spacing |
-
-### Common `inclass` Values (anchor `<a>`)
+### Accessibility Notes
 
-| Class | Effect |
-|-------|--------|
-| `text-sm` | Smaller button text |
-| `text-lg` | Larger button text |
-| `px-6 py-3` | Larger padding |
-| `w-full justify-center` | Full-width button |
-| `font-bold` | Bold label text |
+- Button uses `.btn.btn-primary` — inherits focus ring and keyboard states
+- Icon is `aria-hidden="true"` — button label always conveys intent
+- `download` attribute is only added when `use="download"`, ensuring correct browser behavior for file links
 
 ## Callout