markawesome-skill 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `markawesome-skill` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-05
+
+### Added
+
+- Initial release of the `markawesome` Agent Skill.
+- `SKILL.md` routing body: what Markawesome is, the proactive behavioral
+  contract, a one-line "use when" roster for every component, the
+  progressive-disclosure index, and a companion-skills pointer to Web Awesome's
+  own `webawesome` / `webawesome-design` skills.
+- Reference files under `skills/markawesome/references/`:
+  - `when-to-use.md` — content-pattern → component decision guide plus
+    anti-patterns.
+  - `components-content.md` — callout, card, tag, badge, button, copy button,
+    icon.
+  - `components-interactive.md` — details, accordion, tabs, dialog, popover,
+    tooltip, random content, tree.
+  - `components-media.md` — carousel, comparison, video, video playlist, format
+    date, relative time.
+  - `layouts.md` — grid, stack, cluster, split, flank, frame, the shared gap
+    scale, and nesting rules.
+  - `authoring.md` — dual syntax, Markdown-in-blocks, image/link auto-detection,
+    the `>>>` separator, the Web Awesome 3.10.0 pin, and static-safety / Pro
+    caveats.
+  - `examples.md` — generic full-page worked examples (landing page, docs
+    getting-started, changelog + FAQ).
+- Distribution as an npm package (`files: ["skills", …]`) installable through the
+  `npx skills` CLI from GitHub or npm.

package/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Janne Warén
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# markawesome-skill
+
+An [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
+that teaches an AI assistant to **author and review
+[Markawesome](https://github.com/jannewaren/markawesome)-flavoured Markdown** —
+the terse syntax (`:::`, `===`, `@@@`, `!!!`, `%%%`, `^^^`, `++++++`, `&&&`, …)
+that the **markawesome** (Ruby) and **markawesome-js** (Node) engines transform
+into [Web Awesome](https://webawesome.com/) web components.
+
+It does two things:
+
+1. **Recognizes opportunities proactively** — while you write or review Markdown,
+   it spots prose that would read better as a component and suggests it unprompted
+   ("this warning should be a `:::danger` callout"; "these three features want a
+   `::::grid` of `===` cards").
+2. **Writes the exact syntax** — every component's delimiter, attributes, and when
+   to reach for it, verified against both engines so it never emits syntax only
+   one accepts.
+
+The skill is **pure Markdown knowledge** — no build step, and installing it needs
+no clone of the Ruby or JS engine.
+
+## Install
+
+The skill installs with [`npx skills`](https://github.com/vercel-labs/skills) —
+the same CLI Web Awesome ships their skill with.
+
+### Recommended — one line, from GitHub
+
+```bash
+npx skills add jannewaren/markawesome-skill
+```
+
+No `npm install`, no engine clone. This symlinks the skill into each detected
+agent's directory (`.claude/skills/markawesome`, `.agents/skills/markawesome`, …).
+
+### From npm
+
+```bash
+npm install markawesome-skill
+npx skills experimental_sync          # auto-discovers skills/markawesome/
+# …or point at it explicitly:
+npx skills add ./node_modules/markawesome-skill/skills/markawesome
+```
+
+> **Reality check:** `npx skills` has **no npm-registry resolver**. A bare package
+> name — `npx skills add markawesome-skill` — does **not** work: the CLI falls
+> through to `git clone` and fails. The true one-liner is the **GitHub** form
+> above; npm distribution is `install` + `experimental_sync` (or a path `add`).
+
+## Companion skills
+
+This is the **authoring layer** — which Markawesome Markdown to write, and when.
+For the underlying `<wa-*>` component APIs and for page layout / theming / brand
+color, also install Web Awesome's own skills:
+
+- **`webawesome`** — the individual `<wa-*>` component APIs.
+- **`webawesome-design`** — page layout, theming, and design tokens.
+
+This skill deliberately does not duplicate their content.
+
+## What's inside
+
+```
+skills/markawesome/
+├── SKILL.md                         # routing body + the proactive "brain"
+└── references/
+    ├── when-to-use.md               # content-pattern → component decision guide
+    ├── components-content.md        # callout, card, tag, badge, button, copy button, icon
+    ├── components-interactive.md    # details, accordion, tabs, dialog, popover, tooltip, random content, tree
+    ├── components-media.md          # carousel, comparison, video, playlist, format date, relative time
+    ├── layouts.md                   # grid, stack, cluster, split, flank, frame
+    ├── authoring.md                 # dual syntax, caveats, the WA 3.10.0 pin
+    └── examples.md                  # generic full-page worked examples
+```
+
+## The Markawesome ecosystem
+
+This skill is the **teaching layer** for a family of repositories that keep the
+same Markdown dialect in lockstep:
+
+| Repo | Role |
+|------|------|
+| [`markawesome`](https://github.com/jannewaren/markawesome) | Authors the syntax (Ruby engine) |
+| [`markawesome-js`](https://github.com/jannewaren/markawesome-js) | Authors the syntax (Node engine) |
+| [`jekyll-webawesome`](https://github.com/jannewaren/jekyll-webawesome) | Uses it (Jekyll integration) |
+| [`eleventy-plugin-webawesome`](https://github.com/jannewaren/eleventy-plugin-webawesome) | Uses it (Eleventy integration) |
+| [`markawesome-vscode`](https://github.com/jannewaren/markawesome-vscode) | Produces it (editor tooling) |
+| **`markawesome-skill`** | **Teaches it (AI authoring skill)** |
+
+Because the two engines accept byte-for-byte identical input, everything the skill
+documents works in both the Ruby and Node worlds. See the
+[live examples site](https://jannewaren.github.io/jekyll-webawesome/) to watch the
+Markdown render into components side by side.
+
+## License
+
+[MIT](LICENSE.txt) © Janne Warén

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "markawesome-skill",
+  "version": "0.1.0",
+  "description": "AI authoring skill for Markawesome Markdown — proactively suggests and writes the terse syntax that markawesome / markawesome-js transform into Web Awesome components.",
+  "keywords": [
+    "markawesome",
+    "web-awesome",
+    "webawesome",
+    "markdown",
+    "web-components",
+    "agent-skills",
+    "skills"
+  ],
+  "author": {
+    "name": "Janne Warén",
+    "email": "janne.waren@iki.fi"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jannewaren/markawesome-skill.git"
+  },
+  "homepage": "https://github.com/jannewaren/markawesome-skill",
+  "bugs": {
+    "url": "https://github.com/jannewaren/markawesome-skill/issues"
+  },
+  "files": [
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/markawesome/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: markawesome
+description: >-
+  Authors and reviews Markawesome-flavoured Markdown — a terse syntax
+  (:::, ===, @@@, !!!, %%%, ^^^, ++++++, &&&, and more) that the markawesome
+  and markawesome-js engines transform into Web Awesome web components
+  (callouts, cards, tabs, accordions, tags, badges, buttons, tooltips,
+  carousels, and grid/stack/cluster/split/flank/frame layouts). Use when
+  writing, editing, or reviewing Markdown for a site built with markawesome,
+  markawesome-js, jekyll-webawesome, or eleventy-plugin-webawesome — and
+  proactively whenever plain prose would read better as a component (a warning
+  as a callout, a feature list as a card grid, alternatives as tabs, a glossary
+  term as a tooltip). Covers which component to reach for, when, and its exact
+  syntax.
+license: MIT
+metadata:
+  author: Janne Warén
+  version: "0.1.0"
+  homepage: https://github.com/jannewaren/markawesome-skill
+---
+
+# Markawesome authoring
+
+Markawesome is a terse Markdown dialect that the **markawesome** (Ruby) and
+**markawesome-js** (Node) engines transform into [Web Awesome](https://webawesome.com/)
+web components. It powers the **jekyll-webawesome** and **eleventy-plugin-webawesome**
+static-site integrations. Both engines accept **byte-for-byte identical** input,
+so everything documented here works in either world.
+
+## Behavioral contract (be proactive)
+
+When writing, editing, or reviewing Markdown for one of these projects:
+
+1. **Scan prose for component opportunities and act on them.** Don't wait to be
+   asked. A paragraph that warns wants a `:::warning` callout; a bulleted feature
+   list wants a `::::grid` of `===` cards; "on macOS… on Windows…" wants
+   `++++++` tabs; a copy-me command wants a `<<<` copy button; a defined term
+   wants a `(((term >>> definition)))` tooltip. Suggest the change and write it.
+2. **Prefer terse Markawesome syntax over raw `<wa-*>` HTML.** If you would reach
+   for a Web Awesome web component, write the Markawesome delimiter instead. Drop
+   to raw HTML only for something Markawesome has no syntax for.
+3. **Default to the primary shorthand delimiters** (`:::`, `===`, `@@@`, …). The
+   `:::wa-*` / `::::wa-*` alternative forms exist for readability or disambiguation;
+   reach for them only when the shorthand is ambiguous in context.
+4. **Keep the Markdown valid.** Never break a table, list, or fenced code block.
+   Component syntax inside a fenced ``` block is **not** transformed (it is
+   protected), so use fences to show Markawesome examples literally.
+5. **Never invent attributes.** Every delimiter, variant, size, and flag is
+   enumerated in the reference files. If it isn't listed there, an engine will
+   reject or ignore it — verify before you emit it.
+
+## Component roster — recognize the opportunity
+
+Each row is enough to *spot* a candidate without loading a reference. Load the
+referenced file for exact attributes before writing anything non-trivial.
+
+| Delimiter | Component | Reach for it when… | Reference |
+|-----------|-----------|--------------------|-----------|
+| `:::info` `:::success` `:::warning` `:::danger` `:::neutral` `:::brand` | Callout | highlighting a note, tip, prerequisite, warning, or error | components-content |
+| `===` | Card | a self-contained unit (feature, product, link preview), esp. inside a grid | components-content |
+| `@@@` | Tag | a status/category label — New, Beta, Deprecated, a topic (inline or block) | components-content |
+| `!!!` | Badge | a compact count/status chip, often with `pulse`/`bounce` attention | components-content |
+| `%%%` | Button | a call-to-action or link that should look like a button | components-content |
+| `<<<` | Copy button | a command, URL, or config value users will copy-paste | components-content |
+| `$$$name` / `:::wa-icon` | Icon | an inline decorative icon, or a labeled block icon | components-content |
+| `^^^` | Details | one collapsible block of optional/advanced info | components-interactive |
+| `//////` | Accordion | a *group* of collapsible sections — FAQ, doc sections | components-interactive |
+| `++++++` | Tabs | switchable alternatives — multi-language code, per-OS steps, A/B | components-interactive |
+| `???` | Dialog | long supplementary content hidden behind a trigger button | components-interactive |
+| `&&&` | Popover | hover/click floating content (rich markdown block, or inline) | components-interactive |
+| `(((` | Tooltip | an inline glossary term / short definition on hover | components-interactive |
+| `......` | Random content | rotating tips/testimonials/featured content (zero-JS) | components-interactive |
+| `\|\|\|\|\|\|` | Tree | a file/dir hierarchy or nested navigation from a bullet list | components-interactive |
+| `~~~~~~` | Carousel | an image gallery or step-by-step visual slides | components-media |
+| `\|\|\|` | Comparison | a before/after two-image slider | components-media |
+| `;;;` / `;;;;;;` | Video / Playlist | embedded video(s) — Web Awesome **Pro** | components-media |
+| `[[[…]]]` | Format date / Relative time | a localized absolute or "3 days ago" date | components-media |
+| `::::grid` `::::stack` `::::cluster` `::::split` `::::flank` `::::frame` | Layouts | arranging the above (card grids, sidebars, tag clusters) | layouts |
+
+## Where to read what
+
+Load only what the task needs — the references are one level deep, each
+self-contained:
+
+- **`references/when-to-use.md`** — the decision guide: content shape → component,
+  why, a generic snippet, and the anti-patterns. Read this first when deciding
+  *whether* and *which*.
+- **`references/components-content.md`** — callout, card, tag, badge, button,
+  copy button, icon.
+- **`references/components-interactive.md`** — details, accordion, tabs, dialog,
+  popover, tooltip, random content, tree.
+- **`references/components-media.md`** — carousel, comparison, video, video
+  playlist, format date, relative time.
+- **`references/layouts.md`** — the six `::::` layouts, the shared gap scale,
+  `align`/`justify`, and nesting.
+- **`references/authoring.md`** — dual syntax, Markdown-inside-blocks, image/link
+  auto-detection, the `>>>` separator, front matter, the Web Awesome 3.10.0 pin,
+  and static-safety / Pro caveats.
+- **`references/examples.md`** — full generic pages combining many components.
+
+## Companion skills
+
+This is the **authoring layer** — which Markawesome Markdown to write, and when.
+It does not document the underlying `<wa-*>` component APIs or page-level design.
+For those, also install Web Awesome's own skills:
+
+- **`webawesome`** — the individual `<wa-*>` component APIs (props, slots, events).
+- **`webawesome-design`** — page layout, theming, design tokens, and brand color.
+
+Reach for them when the work goes beyond emitting Markawesome Markdown (custom
+component behavior, `<wa-page>` scaffolding, a theme). This skill deliberately
+does not duplicate their content.

package/skills/markawesome/references/authoring.md

@@ -0,0 +1,116 @@
+# Authoring conventions & caveats
+
+Cross-cutting rules that apply to every component. Read this once; it explains the
+mechanics the per-component references assume.
+
+## Dual syntax: primary shorthand vs. `:::wa-*` alternative
+
+Every component accepts two equivalent spellings:
+
+- **Primary** — the terse delimiter: `:::info`, `===`, `@@@brand`, `%%%`, `^^^`,
+  `//////`, `++++++`, `&&&`, `(((…)))`, `[[[…]]]`, `::::grid`.
+- **Alternative** — an explicit `:::wa-component` (or `::::wa-layout`) form:
+  `:::wa-callout info`, `:::wa-card`, `:::wa-tag brand`, `::::wa-grid`.
+
+**Default to the primary shorthand.** Reach for the `:::wa-*` form only when the
+shorthand would be ambiguous or hard to read in context — for instance when a line
+could be mistaken for something else, or when a reviewer benefits from the
+component name spelled out. Both produce identical HTML; the choice is purely
+readability.
+
+## Markdown renders inside component bodies
+
+The body of a component (a callout, a card, a tab panel, an accordion item, a
+dialog, a details block) is **full Markdown** — headings, lists, links, emphasis,
+inline code, even other components all work inside. Only the *inner* content of
+components is rendered; the surrounding page Markdown is left for your site's own
+Markdown processor.
+
+Exceptions where the body is **plain text, not Markdown**:
+
+- **Tooltip** tip content is plain text (HTML-escaped); `\n` becomes `<br>`.
+- **Tree** labels are plain text (a leading `icon:name` token aside).
+
+## The `>>>` separator
+
+`>>>` on its own splits a **trigger from its body** inside these blocks:
+
+- **Details** (`^^^`) — summary `>>>` content.
+- **Dialog** (`???`) — trigger-button text `>>>` dialog content.
+- **Popover** (`&&&`) — trigger `>>>` content (inline form too:
+  `&&&trigger >>> content&&&`).
+- **Tooltip** (`(((…)))`) — anchor `>>>` tip.
+- **Random content** (`......`) — separates each option from the next.
+
+It only has meaning **inside** one of those blocks. Elsewhere `>` is an ordinary
+Markdown blockquote.
+
+## Image & link auto-detection in cards
+
+A card (`===`) reads its body positionally — you don't name slots:
+
+- First **Markdown image** → the media slot.
+- First **bold line** (`**Title**`, *not* a `#` heading) → the header slot.
+- A **trailing Markdown link** on its own line → a footer button.
+- Everything else → the body.
+
+Buttons (`%%%`) and videos (`;;;`) similarly pick up a Markdown link in their body
+to become clickable / sourced. See the per-component references for specifics.
+
+## Code fences are protected
+
+Anything inside a fenced ``` code block is **not** transformed — the engines
+replace fenced blocks with placeholders before running, then restore them. So to
+show Markawesome syntax literally in documentation, put it in a fenced block (as
+this skill's references do). Inline code (`` `like this` ``) is likewise safe.
+
+## Front matter is SSG-specific
+
+Markawesome transforms the Markdown **body**, not the YAML front matter. How front
+matter works — permalinks, layouts, collections, data — is defined by your static
+site generator, not by Markawesome:
+
+- **Jekyll** (via `jekyll-webawesome`) — Jekyll/Liquid front matter and layouts.
+- **Eleventy** (via `eleventy-plugin-webawesome`) — Eleventy front matter and
+  templating.
+
+Author the component syntax in the body; leave front-matter conventions to the
+host SSG's own docs.
+
+## Web Awesome version pin: 3.10.0
+
+The ecosystem's examples sites pin **Web Awesome 3.10.0** in their CDN URLs, and
+this skill's attribute vocabulary (icon families, animations, the `xs–xl` size
+scale, canvas sizing) matches that release. If a project pins a different Web
+Awesome version, some newer families/animations may not exist there — validate
+against the version the site actually loads.
+
+## Static-safety & Pro caveats
+
+Most components are **declarative and static-site-safe** — they render correctly
+with only the Web Awesome library on the page and no JavaScript of your own.
+Know the exceptions:
+
+- **Web Awesome Pro required:** Video (`;;;`) and Video playlist (`;;;;;;`) emit
+  `<wa-video>` / `<wa-video-playlist>`, which are Pro (and experimental). They do
+  nothing on a free kit.
+- **No light-DOM fallback (needs Web Awesome's JS to show anything):** Icon
+  (`$$$` / `:::wa-icon`), Format date (`[[[…]]]`), and Relative time
+  (`[[[relative …]]]`) render generated content into shadow DOM. With Web
+  Awesome's JavaScript disabled they show nothing.
+- **Fires an event but doesn't act on its own:** a Tag's `with-remove` × button
+  fires `wa-remove` but doesn't remove the tag without your listener.
+- **Declarative-safe but note the runtime quirk:** Tree (`||||||`) expands only
+  top-level branches on load (WA 3.9.0); Random content (`......`) and Accordion
+  (`//////`) are experimental in Web Awesome but fully declarative here.
+
+When a page must work with scripting disabled, prefer the declarative-safe
+components and avoid the shadow-DOM-only ones for essential content.
+
+## The lockstep guarantee
+
+The **markawesome** (Ruby) and **markawesome-js** (Node) engines accept
+byte-for-byte identical input. Everything in these references works in both, so a
+document authored for a Jekyll site transforms identically on an Eleventy site.
+Never emit a delimiter or attribute that only one engine supports — if it isn't in
+these references, don't use it.

package/skills/markawesome/references/components-content.md

@@ -0,0 +1,258 @@
+# Content components
+
+Callout · Card · Tag · Badge · Button · Copy button · Icon
+
+Every component has a **primary** shorthand delimiter and an equivalent
+**`:::wa-*` alternative**. All attributes are optional and order-independent
+(rightmost wins on conflict). Inner content is full Markdown. Unknown tokens are
+silently dropped, so a mistyped variant simply vanishes — spell them exactly.
+
+## Callout
+
+Draw attention to elevated information with a colored, icon-led block.
+
+- **Primary:** `:::type size? appearance? family? variant? animation? icon:name?`
+- **Alt:** `:::wa-callout type size? appearance? family? variant? animation? icon:name?`
+- Close with `:::`.
+
+**Types** (the first token; sets color + default icon):
+
+| Type | Color | Default icon | Use for |
+|------|-------|--------------|---------|
+| `info` / `brand` | blue | `circle-info` | notes, tips (`info` is an alias for `brand`) |
+| `success` | green | `circle-check` | confirmations, "done" states |
+| `warning` | yellow | `triangle-exclamation` | things that need care |
+| `danger` | red | `circle-exclamation` | data loss, errors, destructive actions |
+| `neutral` | gray | `gear` | low-key asides |
+
+**Sizes:** `xs`, `s`, `m`, `l`, `xl` (Web Awesome 3.x five-step scale) plus the
+legacy `small` / `medium` / `large` aliases.
+
+**Appearances:** `accent`, `filled`, `outlined`, `plain`, `filled-outlined`.
+
+**Icon overrides** (the callout's leading icon):
+
+- `icon:name` — swap the icon glyph (e.g. `icon:rocket`, `icon:shield`).
+- `family` — icon family: `classic`, `sharp`, `duotone`, `sharp-duotone`,
+  `brands`, plus the WA 3.10.0 families `mosaic`, `pixel`, `vellum`, `slab-duo`,
+  `slab-press-duo`, `chisel`, `etch`, `graphite`, `jelly`, `jelly-duo`,
+  `jelly-fill`, `notdog`, `notdog-duo`, `slab`, `slab-press`, `thumbprint`,
+  `utility`, `utility-duo`, `utility-fill`, `whiteboard`.
+- `variant` — Font Awesome weight: `thin`, `light`, `regular`, `solid`,
+  `semibold`.
+- `animation` — `beat`, `fade`, `beat-fade`, `bounce`, `flip`, `shake`, `spin`,
+  `spin-pulse`, `spin-reverse`, plus WA 3.10.0's `flip-360`, `spin-snap`,
+  `spin-snap-4`, `spin-snap-8`, `buzz`, `float`, `jello`, `swing`, `wag`.
+  Animation needs no Pro kit — e.g. `:::warning shake`.
+- `canvas` — icon sizing box: `fixed` (default), `auto`, `square`, `roomy`.
+
+```
+:::success l icon:trophy
+**Deploy succeeded.** Your site is live at the production URL.
+:::
+```
+
+```
+:::warning shake
+This warning's icon animates. Family/variant glyph changes depend on your
+Font Awesome kit tier; animation and canvas work with any kit.
+:::
+```
+
+## Card
+
+A flexible container with optional media, header, body, and footer slots — the
+building block of a `::::grid`.
+
+- **Primary:** `===appearance? orientation?`
+- **Alt:** `:::wa-card appearance? orientation?`
+- Close with `===`.
+
+**Appearances:** `outlined` (default), `filled`, `filled-outlined`, `plain`,
+`accent`. **Orientation:** `vertical` (default), `horizontal` (media and content
+side by side).
+
+**Composition is auto-detected from the body** (this is the part people get
+wrong):
+
+- The **first Markdown image** `![alt](src)` becomes the **media** slot.
+- The **first bold line** `**Title**` becomes the **header** slot. (It must be a
+  bold line on its own — *not* a `#` heading.)
+- A **trailing Markdown link** on its own line becomes a **footer** button.
+- Everything else is the body.
+
+```
+===
+![Chart](/img/analytics.png)
+**Analytics**
+Track visits, referrers, and conversions in real time.
+[Learn more](/docs/analytics)
+===
+```
+
+```
+===horizontal accent
+**Horizontal card**
+Media and content sit side by side.
+===
+```
+
+## Tag
+
+A small colored label for a category or status. Works **inline** in a sentence or
+as a **block**.
+
+- **Primary:** `@@@variant? appearance? size? pill? with-remove? icon:name?`
+- **Alt:** `:::wa-tag variant? appearance? size? pill? with-remove? icon:name?`
+- Inline form opens and closes on one line: `@@@variant Label @@@`.
+
+**Variants:** `brand`, `success`, `neutral`, `warning`, `danger`.
+**Appearances:** `accent`, `filled`, `outlined`, `filled-outlined`.
+**Sizes:** `xs`, `s`, `m`, `l`, `xl` plus legacy `small` / `medium` / `large`.
+**Flags:** `pill` (rounded), `with-remove` (adds a × button).
+**Icon:** `icon:name` places an icon inside the tag.
+
+```
+The @@@success icon:check Stable @@@ API and the @@@warning Beta @@@ API differ.
+```
+
+```
+@@@brand pill icon:star
+Featured
+@@@
+```
+
+> **`with-remove` caveat:** the × button only *fires* a `wa-remove` event — Web
+> Awesome does not remove the tag for you. On a page with no JavaScript beyond
+> the Web Awesome library it is inert. Add your own `wa-remove` listener to make
+> it functional. The markup is valid either way.
+
+## Badge
+
+A compact count/status chip, often used to grab attention.
+
+- **Primary:** `!!!variant? appearance? attention? pill?`
+- **Alt:** `:::wa-badge variant? appearance? attention? pill?`
+- Close with `!!!`.
+
+**Variants:** `brand`, `success`, `neutral`, `warning`, `danger`.
+**Appearances:** `accent`, `filled`, `outlined`, `filled-outlined`.
+**Attention:** `none`, `pulse`, `bounce`. **Flags:** `pill`.
+
+```
+!!!brand pulse
+New
+!!!
+```
+
+Tag vs. badge: reach for a **tag** for a category/status label in flowing content,
+a **badge** for a small attention-grabbing count or "new" marker (badges carry
+the `pulse`/`bounce` animations).
+
+## Button
+
+A styled button — a link when it wraps a Markdown link, a plain button otherwise.
+
+- **Primary:** `%%%variant? appearance? size? pill? caret? loading? disabled? target? download? icon:name? icon:end:name?`
+- **Alt:** `:::wa-button variant? appearance? size? pill? caret? loading? disabled? …`
+- Close with `%%%`.
+
+**Variants:** `brand`, `success`, `neutral`, `warning`, `danger`.
+**Appearances:** `accent`, `filled`, `outlined`, `filled-outlined`, `plain`.
+**Sizes:** `xs`, `s`, `m`, `l`, `xl` plus legacy `small` / `medium` / `large`.
+**Flags:** `pill`, `caret` (dropdown indicator), `loading`, `disabled`.
+
+**Link behavior** (link-form buttons only — the body holds a Markdown link).
+These are **bare tokens**, not `key=value` pairs:
+
+- `_blank`, `_self`, `_parent`, `_top` set the anchor target; `_blank` also adds
+  `rel="noopener noreferrer"` automatically.
+- `download` makes the link download its target instead of navigating.
+
+**Icons:** `icon:name` for a start icon, `icon:end:name` for an end icon (or the
+explicit `icon:start:name`); combine both.
+
+```
+%%%brand icon:rocket
+[Get started](https://example.com/start)
+%%%
+```
+
+```
+%%%neutral outlined icon:end:arrow-right _blank
+[Read the docs](https://example.com/docs)
+%%%
+```
+
+```
+%%%success download
+[Download sample](/files/sample.zip)
+%%%
+```
+
+## Copy button
+
+A button that copies text to the clipboard — attach it to any command, URL, or
+value the reader will copy. The display supports Markdown while the copied text
+stays raw.
+
+- **Primary:** `<<<placement? tooltip:full|copy|none? duration? disabled? copy-label? success-label? error-label? from?`
+- **Alt:** `:::wa-copy-button placement? tooltip:full|copy|none? …`
+- Close with `<<<`.
+
+**Tooltip placement:** `top` (default), `right`, `bottom`, `left`.
+**Tooltip mode:** `tooltip:full` (default — hover/focus + copy feedback),
+`tooltip:copy` (feedback only), `tooltip:none` (no tooltip).
+**Feedback duration:** a bare number is the success-message duration in ms
+(e.g. `2000`).
+**Custom labels:** `copy-label="…"`, `success-label="…"`, `error-label="…"`.
+**Copy from another element:** `from="element-id"` (also `from="input.value"`,
+`from="link[href]"`). **Flags:** `disabled`.
+
+```
+<<<top copy-label="Copy install command"
+npm install markawesome-js
+<<<
+```
+
+## Icon
+
+A standalone Web Awesome `<wa-icon>` — inline and decorative, or a labeled block.
+
+- **Inline** `$$$name` — name only, decorative, no attributes; use mid-prose:
+  `Click the $$$gear icon.`
+- **Block** `:::wa-icon name family? variant? animation? canvas?` — the first
+  token is the icon name; the rest are optional, order-independent attributes. A
+  non-empty block body becomes the icon's accessible `label`; an empty body
+  leaves it presentational. Close with `:::`.
+
+**Icon attributes** (same vocabulary as the callout icon overrides):
+
+- **family** — `classic`, `sharp`, `duotone`, `sharp-duotone`, `brands`, plus the
+  WA 3.10.0 families (`mosaic`, `pixel`, `vellum`, `slab-duo`, `slab-press-duo`,
+  `chisel`, `etch`, `graphite`, `jelly`, `jelly-duo`, `jelly-fill`, `notdog`,
+  `notdog-duo`, `slab`, `slab-press`, `thumbprint`, `utility`, `utility-duo`,
+  `utility-fill`, `whiteboard`).
+- **variant** (Font Awesome weight) — `thin`, `light`, `regular`, `solid`,
+  `semibold`.
+- **animation** — `beat`, `fade`, `beat-fade`, `bounce`, `flip`, `shake`, `spin`,
+  `spin-pulse`, `spin-reverse`, `flip-360`, `spin-snap`, `spin-snap-4`,
+  `spin-snap-8`, `buzz`, `float`, `jello`, `swing`, `wag`.
+- **canvas** (sizing box) — `fixed` (default), `auto`, `square`, `roomy`.
+
+Animation and canvas work with any kit; family/variant glyph changes depend on
+the kit's Font Awesome tier.
+
+```
+Enable it under the $$$gear Settings menu.
+```
+
+```
+:::wa-icon bell shake
+Notifications
+:::
+```
+
+> **Static-site caveat:** an icon renders its glyph into shadow DOM with no
+> light-DOM fallback — with Web Awesome's JavaScript disabled it shows nothing.
+> See `authoring.md`.