markawesome-skill 0.1.0

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

@@ -0,0 +1,240 @@
+# Interactive components
+
+Details · Accordion · Tabs · Dialog · Popover · Tooltip · Random content · Tree
+
+Most of these split a trigger from its body with a `>>>` line (see the shared
+`>>>` separator in `authoring.md`). Attributes are optional and order-independent.
+
+## Details
+
+One collapsible section. For a *group* of them, use an Accordion instead.
+
+- **Primary:** `^^^appearance? icon-placement? disabled? open? name:value? icon:expand:name? icon:collapse:name?`
+- **Alt:** `:::wa-details appearance? icon-placement? …`
+- Separate the summary from the content with `>>>`. Close with `^^^`.
+
+**Appearances:** `outlined` (default), `filled`, `filled-outlined`, `plain`.
+**Icon placement:** `end` (default), `start`.
+**Flags:** `disabled` (can't toggle), `open` (starts expanded).
+**Accordion grouping:** `name:value` gives several details the same group name so
+only one stays open (e.g. `name:faq`).
+**Custom toggle icons:** `icon:expand:name` and `icon:collapse:name`.
+
+```
+^^^icon:expand:plus icon:collapse:minus
+Show advanced options
+>>>
+These settings are optional. Most projects never change them.
+^^^
+```
+
+## Accordion
+
+A multi-section collapsible container — the grouped sibling of Details. Ideal for
+FAQs and doc sections.
+
+- **Primary:** `//////appearance? mode? icon-placement? heading:N?`
+- **Alt:** `:::wa-accordion appearance? mode? icon-placement? heading:N?`
+- The container fence is `//////` (**6 slashes**). Each item is a `///` block
+  (**3 slashes**) with an explicit `///` close. Item bodies are full Markdown and
+  may contain other components.
+
+**Container tokens** (bare, order-independent, rightmost wins):
+
+- **appearance:** `outlined` (default), `filled`, `filled-outlined`, `plain`.
+- **mode:** `multiple` (default — several open at once), `single` (one open at a
+  time, one always stays open), `single-collapsible` (one at a time, all can
+  close).
+- **icon-placement:** `end` (default), `start`.
+- **heading:N** — semantic heading level for item headers: `1`–`6` or `none`.
+
+**Item tokens** (leading, on the `///` header line): `expanded` (starts open),
+`disabled` (renders but can't toggle), `icon:name` (custom expand icon). The rest
+of the header line is the item's label.
+
+```
+//////filled single heading:3
+/// What is Web Awesome?
+A library of web components you can use anywhere.
+///
+/// expanded Is it free?
+The core library is free and open source.
+///
+//////
+```
+
+`wa-accordion` is experimental in Web Awesome, but everything here is declarative
+and static-site-safe.
+
+## Tabs
+
+Switchable panels for parallel alternatives — per-OS steps, multi-language code, A/B.
+
+- **Primary:** `++++++placement? activation? active? no-scroll-controls?`
+- **Alt:** `:::wa-tabs placement? activation? active? no-scroll-controls?`
+- The container fence is `++++++` (**6 pluses**). Each tab is `+++ Title` … `+++`.
+
+**Placements:** `top` (default), `bottom`, `start`, `end`.
+**Activation:** `auto` (default — switch on hover), `manual` (switch on click).
+**Active panel:** name it with `active` (e.g. `tab-1`, `tab-2`).
+**Flags:** `no-scroll-controls` (disable scroll arrows for overflowing tabs).
+**Per-tab flag:** `disabled` as a leading token on the `+++ ` header line.
+
+```
+++++++top manual
++++ macOS
+`brew install example`
++++
++++ Windows
+`winget install example`
++++
++++ disabled Linux (coming soon)
+Not yet available.
++++
+++++++
+```
+
+## Dialog
+
+Long supplementary content behind a trigger button — a modal.
+
+- **Primary:** `???params?`
+- **Alt:** `:::wa-dialog params?`
+- Separate the trigger button text from the dialog content with `>>>`. Close with
+  `???`.
+
+**Parameters:** `light-dismiss` (close on outside click), and a **bare CSS width
+value** to set the dialog width — `600px`, `50vw`, `40rem`, etc. (a bare
+number-with-unit token, not `width:…`).
+
+```
+???light-dismiss 600px
+Read the full changelog
+>>>
+## Changelog
+
+Every release, in detail. Supports full **Markdown** inside the dialog.
+???
+```
+
+## Popover
+
+Floating content attached to a trigger — richer than a tooltip (full Markdown,
+links). Works as a **block** or **inline**.
+
+- **Block primary:** `&&&placement? link? without-arrow? distance:N? skidding:N?`
+- **Inline:** `&&&trigger text >>> popover content&&&`
+- **Alt:** `:::wa-popover placement? …`
+- Block form separates trigger from content with `>>>`; close with `&&&`.
+
+**Placements:** `top` (default), `bottom`, `left`, `right`, plus the eight aligned
+variants (`top-start`, `top-end`, `right-start`, `right-end`, `bottom-start`,
+`bottom-end`, `left-start`, `left-end`).
+**Parameters:** `link` (render the trigger as a link instead of a button),
+`without-arrow` (hide the arrow), `distance:N` (offset away from the trigger, px),
+`skidding:N` (offset along the trigger, px; may be negative).
+
+```
+&&&bottom-start
+More info
+>>>
+Popover content with **Markdown**, [links](https://example.com), and lists.
+&&&
+```
+
+```
+Click &&&here >>> This is an inline popover!&&& to learn more.
+```
+
+Inline extras: inline code in the trigger (`` &&&`code` trigger >>> content&&& ``)
+and `\n` line breaks in the content.
+
+## Tooltip
+
+An inline glossary term / short definition on hover or focus. Declarative and
+zero-JavaScript: the anchor renders as a focusable, dotted-underlined span wired
+to the tip automatically.
+
+- **Inline primary:** `(((placement? distance:N? skidding:N? anchor >>> tip)))`
+- **Block alt:** `:::wa-tooltip placement? distance:N? skidding:N?` (anchor,
+  `>>>`, tip, `:::`).
+
+**Placements:** `top` (default), `bottom`, `left`, `right`, plus the eight aligned
+variants. **Parameters:** `distance:N`, `skidding:N` (leading tokens, before the
+anchor term).
+
+**Tip content** is plain text (HTML-escaped). Use `\n` for line breaks (rendered
+as `<br>`). Unlike a popover, a tooltip has no `link` or `without-arrow`.
+
+```
+Styling is handled by (((CSS >>> Cascading Style Sheets))) on the web.
+```
+
+```
+(((bottom-start Org number >>> NO: 9 digits\nSE: 10 digits)))
+```
+
+## Random content
+
+A container that shows one (or more) of its options at random and hides the rest,
+optionally rotating them — a rotating tips / testimonials / featured-content block
+with **zero JavaScript of your own** (Web Awesome's own runtime does the work).
+
+- **Primary:** `......params?` (**6 dots**)
+- **Alt:** `:::wa-random-content params?`
+- Separate each option with a `>>>` line. Close with `......`.
+
+**Parameters** (order-independent, on the opening fence):
+
+- **mode:** `unique` (WA default), `random`, or `sequence` — as a bare word or
+  `mode:random`.
+- **animation:** `none`, `fade`, `fade-up`, `fade-down`, `fade-left`,
+  `fade-right` — as a bare word or `animation:fade`.
+- **items:n** — how many children to show at once (a bare integer like `2` works).
+- **autoplay** — rotate the shown children automatically.
+- **autoplay-interval:value** — milliseconds between rotations (e.g.
+  `autoplay-interval:3000`).
+
+```
+......mode:random animation:fade
+> "This tool saved us days of work." — A happy user
+>>>
+> "Setup took five minutes." — Another happy user
+......
+```
+
+## Tree
+
+A `<wa-tree>` hierarchy rendered from a **nested Markdown bullet list** — file/
+directory layouts, taxonomies, nested navigation.
+
+- **Primary:** `||||||open?` (**6 pipes**)
+- **Alt:** `:::wa-tree open?`
+- Wrap a normal nested bullet list; close with `||||||`. Children are more-indented
+  list items (2- or 4-space indentation both work).
+
+**Fence token:** `open` (alias `expanded`) marks every branch (any node with
+children) expanded.
+**Per-node leading tokens** (on each list item, stripped from the label):
+`expanded` (force this branch open), `icon:name` (a leading folder/file icon).
+Colon-bearing labels like `cbc:ID` are kept verbatim — only a *leading* `icon:`
+token is treated as an icon.
+
+```
+||||||open
+- icon:folder src
+  - icon:file index.ts
+  - icon:file utils.ts
+- icon:file README.md
+||||||
+```
+
+**Display/navigation only:** Web Awesome's interactive tree selection
+(`selection`, `lazy`, `selected`) needs JavaScript and is deliberately omitted —
+this emits a static-safe tree (nesting, initial expand state, leading icons).
+
+> **WA runtime caveat (3.9.0):** `<wa-tree-item>` only honors a static `expanded`
+> on items visible at load, so `open` expands the **top-level** branches; deeper
+> branches stay collapsed until their parent is opened. The attribute is still
+> emitted on every branch (harmless and forward-compatible); full deep-expand-on-
+> load would need JavaScript.

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

@@ -0,0 +1,175 @@
+# Media & date components
+
+Carousel · Comparison · Video · Video playlist · Format date · Relative time
+
+## Carousel
+
+An image slider or content rotator with navigation — a gallery or step-by-step
+visual slides.
+
+- **Primary:** `~~~~~~params?` (**6 tildes**)
+- **Alt:** `:::wa-carousel params?`
+- Separate slides with `~~~` (**3 tildes**). Close with `~~~~~~`.
+
+**Parameters** (order-independent):
+
+- `navigation` — prev/next arrows.
+- `pagination` — dot indicators.
+- `loop` — infinite loop.
+- `autoplay` — auto-advance; `autoplay-interval:value` sets the ms between
+  advances (e.g. `5000`; default `3000`).
+- `mouse-dragging` — drag to slide.
+- `vertical` — vertical orientation.
+- `scroll-hint:value` — peek of the next slide.
+- `aspect-ratio:value` — e.g. `16/9`, `4/3`.
+- `slide-gap:value` — gap between slides.
+- `slides-per-page:n` — slides visible at once.
+- `slides-per-move:n` — slides advanced per move.
+
+```
+~~~~~~navigation pagination loop autoplay autoplay-interval:5000
+~~~
+![Dashboard](/img/slide-1.png)
+~~~
+~~~
+![Reports](/img/slide-2.png)
+~~~
+~~~~~~
+```
+
+## Comparison
+
+A before/after image comparison with a draggable slider. Requires **exactly two
+images**.
+
+- **Primary:** `|||position?`
+- **Alt:** `:::wa-comparison position?`
+- Close with `|||`. First image → `before` slot; second image → `after` slot.
+- Optional `position` (0–100) sets the initial slider position.
+
+```
+|||40
+![Before](/img/before.jpg)
+![After](/img/after.jpg)
+|||
+```
+
+## Video (Web Awesome Pro)
+
+Embed a single video as `<wa-video>`. **Requires a Web Awesome Pro kit** and is
+experimental.
+
+- **Primary:** `;;;controls:? preload:? flags?`
+- **Alt:** `:::wa-video controls:? preload:? flags?`
+- Close with `;;;`.
+
+**Body:** the first Markdown link `[Title](src)` supplies the video `title` and
+`src`; the first Markdown image `![alt](poster)` supplies the `poster`. A block
+with **no link (no `src`) is left untransformed**.
+
+**Parameters** (order-independent; invalid enum values dropped):
+
+- `controls:none|standard|full` — controls preset (default `standard`).
+- `preload:auto|metadata|none` — how the browser preloads (default `metadata`).
+- `autoplay`, `autoplay-muted`, `autoplay-on-visible`, `loop`, `muted`.
+
+```
+;;;controls:full
+[Product tour](/media/tour.mp4)
+![Poster](/media/tour-poster.jpg)
+;;;
+```
+
+v1 emits a single `src` (no `<source>`/`<track>` children yet). For a navigable
+set of videos, use a Video playlist.
+
+## Video playlist (Web Awesome Pro)
+
+Group multiple videos into `<wa-video-playlist>` with navigation. **Pro**,
+experimental.
+
+- **Primary:** `;;;;;;controls:?` (**6 semicolons**)
+- **Alt:** `:::wa-video-playlist controls:?`
+- Wrap each video in a bare `;;;` … `;;;` item between the `;;;;;;` fences (mirrors
+  the carousel `~~~`/`~~~~~~` structure). Each item follows the same body rules as
+  a single Video.
+
+**`controls:none|standard|full`** sets the preset for the whole playlist (default
+`full`); it is forwarded to every child, so the children omit their own
+`controls`.
+
+```
+;;;;;;controls:standard
+;;;
+[Part 1 — Intro](/media/part1.mp4)
+![Poster](/media/part1.jpg)
+;;;
+;;;
+[Part 2 — Setup](/media/part2.mp4)
+;;;
+;;;;;;
+```
+
+## Format date
+
+An absolute, locale-formatted date baked in at build time (`<wa-format-date>`).
+The browser formats it via `Intl.DateTimeFormat`. Works **inline** or as a block.
+
+- **Inline primary:** `[[[date style:preset? time:preset? granular? lang:locale?]]]`
+- **Block alt:** `:::wa-format-date date style:preset? …` (empty body, close `:::`).
+
+**The date** is an ISO 8601 date (`2026-06-26`) or datetime with a `T`
+(`2026-06-26T14:30:00Z`). Omit it to show the viewer's current time.
+
+**Presets:** `style:short|medium|long|full` and `time:short|medium|long|full`
+expand to granular attributes. A bare date defaults to `style:long`; `time:`
+without a date style emits time-only.
+
+**Granular overrides** (win over presets, rightmost wins): `weekday`, `era`,
+`year`, `month`, `day`, `hour`, `minute`, `second` (each an `Intl` value), plus
+`hour-format:auto|12|24`, `time-zone-name:short|long`, `time-zone:IANA`, and
+`lang:` / `locale:` for the locale. Unknown tokens and invalid enum values are
+silently dropped.
+
+```
+Published [[[2026-06-26 style:long]]].
+```
+
+```
+:::wa-format-date 2026-06-26 style:full lang:fr
+:::
+```
+
+## Relative time
+
+A relative "3 days ago"-style phrase, optionally live-ticking
+(`<wa-relative-time>`, via `Intl.RelativeTimeFormat`). Works **inline** or as a
+block.
+
+- **Inline primary:** prefix the date with `relative` —
+  `[[[relative date format:? numeric:? sync? lang:?]]]`.
+- **Block alt:** `:::wa-relative-time date format:? numeric:? sync?` (close `:::`).
+
+**Parameters:**
+
+- `format:long|short|narrow` — phrasing width (default `long`).
+- `numeric:auto|always` — `auto` allows "yesterday"/"tomorrow"; `always` forces
+  "1 day ago" (default `auto`).
+- `sync` — keep the phrase ticking live as time passes.
+- `lang:` / `locale:` — the locale.
+
+Date-formatting tokens (`style:`, `time:`, `month:`, …) are ignored in relative
+mode.
+
+```
+Updated [[[relative 2026-06-20]]].
+```
+
+```
+:::wa-relative-time 2026-06-20 sync
+:::
+```
+
+> **Static-site caveat (Format date & Relative time):** like `<wa-icon>`, both
+> render generated text into shadow DOM with **no light-DOM fallback** — with Web
+> Awesome's JavaScript disabled they show nothing. See `authoring.md`.

package/skills/markawesome/references/examples.md

@@ -0,0 +1,177 @@
+# Worked examples
+
+Three complete, generic pages showing how components compose. All content is a
+stand-in — swap in the real thing. These use only the primary shorthand syntax.
+
+## 1. Product landing page
+
+A hero call to action, a feature grid, a copy-me install command, and a
+before/after.
+
+````markdown
+# Acme Build
+
+Ship static sites faster.
+
+::::split
+@@@brand pill New — v2.0 @@@
+
+%%%brand icon:rocket
+[Get started](https://example.com/start)
+%%%
+::::
+
+:::success
+**Now 3× faster.** The v2 engine builds a 10,000-page site in under a minute.
+:::
+
+## Why Acme Build
+
+::::grid gap:l min:16rem
+===
+**Zero config**
+Sensible defaults out of the box — no setup file required.
+[Learn more](/docs/config)
+===
+
+===
+**Framework-agnostic**
+Works with any static site generator you already use.
+[See integrations](/docs/integrations)
+===
+
+===
+**Themeable**
+Restyle everything with design tokens, no CSS overrides.
+[Theming guide](/docs/theming)
+===
+::::
+
+## Install in one line
+
+<<<top copy-label="Copy install command"
+npm install acme-build
+<<<
+
+## See the difference
+
+The v2 redesign, side by side:
+
+|||50
+![Before](/img/v1.png)
+![After](/img/v2.png)
+|||
+````
+
+## 2. Docs — Getting started
+
+A prerequisites callout, per-OS install tabs, an optional advanced-config Details
+block, and inline tooltips for jargon.
+
+````markdown
+# Getting started
+
+Get a project running in about five minutes.
+
+:::warning
+You need (((Node.js >>> A JavaScript runtime built on V8))) 18 or newer. Check
+with `node --version` before you begin.
+:::
+
+## 1. Install
+
+++++++manual
++++ macOS
+<<<
+brew install acme-build
+<<<
++++
++++ Windows
+<<<
+winget install Acme.Build
+<<<
++++
++++ Linux
+<<<
+curl -fsSL https://example.com/install.sh | sh
+<<<
++++
+++++++
+
+## 2. Create a project
+
+<<<
+acme new my-site
+<<<
+
+## 3. Configure (optional)
+
+^^^
+Show advanced configuration
+>>>
+Most projects never touch these. Set them in `acme.config.js`:
+
+```js
+export default {
+  incremental: true,
+  concurrency: 8,
+};
+```
+^^^
+
+:::success
+That's it — run `acme dev` and open the local URL. You're building with
+(((SSG >>> Static Site Generator))) speed.
+:::
+````
+
+## 3. Changelog + FAQ
+
+A release with a relative-time stamp, tags for the kinds of change, and an FAQ
+accordion.
+
+````markdown
+# Release notes
+
+## v2.0.0 — [[[2026-06-26 style:long]]] ([[[relative 2026-06-26]]])
+
+::::cluster gap:xs
+@@@success Added @@@ @@@warning Changed @@@ @@@danger Removed @@@
+::::
+
+:::danger
+**Breaking:** the `legacy` build mode is removed. Migrate to the default engine
+before upgrading — see the migration guide.
+:::
+
+- @@@success Added @@@ incremental builds, on by default.
+- @@@warning Changed @@@ the config file format to ESM.
+- @@@danger Removed @@@ the deprecated `legacy` mode.
+
+## FAQ
+
+//////single heading:3
+/// Is v2 a drop-in upgrade?
+For most projects, yes — except the removed `legacy` mode noted above.
+///
+/// Do I need to change my config?
+The config file is now ESM (`export default { … }`). Rename it to
+`acme.config.js` and convert `module.exports` to `export default`.
+///
+/// expanded Where do I report bugs?
+On the issue tracker. Include your Acme Build version and a minimal repro.
+///
+//////
+````
+
+## What these demonstrate
+
+- **Layouts wrap components** — `::::grid` of cards, `::::cluster` of tags,
+  `::::split` for a header row.
+- **Callouts carry severity** — `:::success` for wins, `:::warning` for
+  prerequisites, `:::danger` for breaking changes.
+- **Tabs for parallel alternatives** — per-OS install steps the reader picks one
+  of.
+- **Copy buttons on every command** — nothing to hand-select.
+- **Accordion for the FAQ, Details for one optional aside** — group vs. single.
+- **Inline tooltips and dates** stay in the flow of prose.