markawesome-skill 0.1.0

package/skills/markawesome/references/layouts.md

@@ -0,0 +1,137 @@
+# Layouts
+
+Grid · Stack · Cluster · Split · Flank · Frame
+
+Layouts use the `::::` (**quadruple colon**) fence and map to Web Awesome CSS
+utility containers (`<div class="wa-grid">`, etc.). They **wrap** components —
+put cards, callouts, tags inside a layout; never put a layout inside a component.
+Inner content is passed through untouched, so component `:::`/`===`/`@@@` syntax
+inside a layout transforms normally.
+
+- **Primary:** `::::type params?` … `::::`
+- **Alt:** `::::wa-type params?` … `::::`
+
+## Shared attributes (all six layouts)
+
+- **`gap:SIZE`** — spacing between items. Scale: `0`, `3xs`, `2xs`, `xs`, `s`,
+  `m`, `l`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`.
+- **`align:VALUE`** — align items: `start`, `end`, `center`, `stretch`,
+  `baseline`.
+- **`justify:VALUE`** — justify content: `start`, `end`, `center`,
+  `space-between`, `space-around`, `space-evenly`.
+
+Unknown gap/align/justify values are dropped, so a typo just has no effect.
+
+## Grid
+
+A responsive auto-wrapping grid — no media queries. The default layout for a
+*set* of cards.
+
+- **Extra attribute:** `min:CSS` — minimum column size before wrapping (e.g.
+  `min:300px`, `min:20ch`, `min:15rem`).
+
+```
+::::grid gap:l min:16rem
+===
+**Fast**
+Sub-second builds.
+===
+
+===
+**Themeable**
+Restyle with design tokens.
+===
+
+===
+**Portable**
+Works with any static site generator.
+===
+::::
+```
+
+## Stack
+
+A vertical stack with consistent spacing — use it to give a run of blocks even
+rhythm.
+
+```
+::::stack gap:m
+:::info
+First note.
+:::
+
+:::success
+Second note.
+:::
+::::
+```
+
+## Cluster
+
+Inline items that wrap — perfect for a tag cloud, a button row, or an icon list.
+
+```
+::::cluster gap:xs
+@@@brand Ruby @@@ @@@success Jekyll @@@ @@@neutral Markdown @@@ @@@warning Beta @@@
+::::
+```
+
+## Split
+
+Distributes items to opposite ends — the classic header / footer / nav-bar
+pattern.
+
+- **Extra modifiers:** `row` (horizontal, default) or `column` (vertical).
+
+```
+::::split
+**© 2026 Example, Inc.**
+
+[Privacy](/privacy) | [Terms](/terms)
+::::
+```
+
+## Flank
+
+A sidebar beside main content; the flank wraps below on small screens.
+
+- **Modifiers:** `start` (flank on the start side, default) or `end`.
+- **Extra attributes:** `size:CSS` (flank size, e.g. `size:200px`, `size:15rem`),
+  `content:PCT` (minimum content width, e.g. `content:70%`).
+
+```
+::::flank start size:220px gap:l
+![Avatar](/img/avatar.jpg)
+
+## About the author
+A short bio goes here, beside the portrait.
+::::
+```
+
+## Frame
+
+An aspect-ratio container for images and media.
+
+- **Modifiers:** `landscape` (16:9), `portrait` (9:16), `square` (1:1).
+- **Extra attribute:** `radius:SIZE` — `s`, `m`, `l`, `pill`, `circle`, `square`.
+
+```
+::::frame landscape radius:l
+<img src="/img/hero.jpg" alt="Product hero">
+::::
+```
+
+> **Frame + images:** use a raw `<img>` tag inside a frame. Markdown image syntax
+> may not be processed inside layout containers, so `![alt](src)` can fail to
+> render there — this is the one place to drop to HTML. Elsewhere, Markdown
+> images work normally.
+
+## Nesting
+
+- Components nest **inside** layouts: a `::::grid` of `===` cards, a `::::cluster`
+  of `@@@` tags, a `::::stack` of `:::` callouts.
+- Layouts may nest inside layouts when it genuinely helps (a `::::split` header
+  above a `::::grid` body), but keep it shallow — deep nesting is hard to read and
+  rarely necessary.
+- Do **not** nest a layout inside a component body (no `::::grid` inside a `===`
+  card). Component bodies hold prose and inline components, not block layouts.

package/skills/markawesome/references/when-to-use.md

@@ -0,0 +1,249 @@
+# When to use what — the decision guide
+
+This is the proactive core. Match the **shape of the content** in front of you to
+a component, reach for it, and write it. Every snippet below is generic — swap in
+the real content. For exact attributes, open the linked component reference.
+
+## Content shape → component
+
+### A paragraph that warns, cautions, or flags a prerequisite → Callout
+
+Prose like "Note that…", "Be careful…", "You must first…", "This will delete…"
+is a callout. Pick the type by severity:
+
+- `:::info` / `:::brand` — a neutral note or tip.
+- `:::success` — a confirmation, a "you're done" state.
+- `:::warning` — something that can go wrong or needs care.
+- `:::danger` — data loss, irreversible or destructive actions, errors.
+- `:::neutral` — a low-key aside.
+
+```
+:::warning
+Rotating your API key invalidates every existing token immediately. Update your
+deployed services before rotating.
+:::
+```
+
+→ `components-content.md`. Don't turn *every* sentence into a callout — reserve
+them for genuinely elevated information (see anti-patterns).
+
+### A bulleted list where each item is a self-contained unit → Card grid
+
+Three features, three pricing tiers, three linked resources — each with a title
+and a sentence or two — read far better as cards in a responsive grid than as a
+bullet list.
+
+```
+::::grid gap:l min:16rem
+===
+**Fast**
+Zero-config, sub-second builds.
+===
+
+===
+**Framework-agnostic**
+Works with any static site generator.
+===
+
+===
+**Themeable**
+Restyle everything with design tokens.
+===
+::::
+```
+
+→ `layouts.md` (grid) + `components-content.md` (card). One card alone is fine
+too; the grid is what makes a *set* of them shine.
+
+### "On macOS… / On Windows…", or the same thing in several languages → Tabs
+
+Parallel alternatives where the reader wants **one** of them — per-OS install
+steps, the same API call in curl / JS / Python, an A/B choice — are tabs.
+
+```
+++++++
++++ macOS
+`brew install example`
++++
++++ Windows
+`winget install example`
++++
+++++++
+```
+
+→ `components-interactive.md`. If the alternatives are meant to be read
+*together* (a comparison), use a table or a `::::grid` instead.
+
+### A list of question → answer pairs → Accordion
+
+An FAQ, a set of collapsible doc sections, "common problems" — a *group* of
+headers that expand — is an accordion. (One lone collapsible block is Details,
+below.)
+
+```
+//////single
+/// Is it free?
+The core library is free and open source.
+///
+/// Does it need a build step?
+No — it runs at your site's build time.
+///
+//////
+```
+
+→ `components-interactive.md`.
+
+### One block of optional / advanced / "click for details" content → Details
+
+A single spoiler, an advanced-config aside, a long stack trace you don't want
+inline — one collapsible section — is Details, not an accordion.
+
+```
+^^^
+Show the full configuration
+>>>
+```yaml
+verbose: true
+retries: 5
+```
+^^^
+```
+
+→ `components-interactive.md`.
+
+### A term that needs a short definition → Tooltip
+
+A jargon word, an acronym, a field whose format needs explaining — anything where
+you'd otherwise write "(i.e., …)" — is an inline tooltip.
+
+```
+Styled with (((CSS >>> Cascading Style Sheets))) and shipped as one file.
+```
+
+→ `components-interactive.md`. For a *rich* floating block (markdown, links) on
+hover, use a Popover instead.
+
+### A command, URL, token, or config value the reader will copy → Copy button
+
+Anything a reader will select-and-copy — an install command, a connection string,
+an API endpoint — should carry a copy button so they don't have to hand-select.
+
+```
+<<<
+npm install markawesome-js
+<<<
+```
+
+→ `components-content.md`.
+
+### A status or category label inline in prose or a heading → Tag or Badge
+
+- **Tag** (`@@@`) — a category/status label with a variant color: `New`, `Beta`,
+  `Deprecated`, a topic. Works inline mid-sentence or as a block.
+- **Badge** (`!!!`) — a compact count or status chip, often demanding attention
+  with `pulse` / `bounce` (a notification count, a "3 new" marker).
+
+```
+The @@@warning Deprecated @@@ endpoint is removed in v2.
+```
+
+→ `components-content.md`.
+
+### A call to action or a link that should look like a button → Button
+
+"Get started", "Download", "View docs" — a prominent link — is a button. Include
+a markdown link to make it navigate; omit it for a plain (JS-wired) button.
+
+```
+%%%brand
+[Get started](https://example.com/start)
+%%%
+```
+
+→ `components-content.md`.
+
+### A before/after pair of images → Comparison
+
+A redesign, a filter on/off, an edit diff — two images the reader drags between —
+is a comparison slider.
+
+```
+|||
+![Before](before.jpg)
+![After](after.jpg)
+|||
+```
+
+→ `components-media.md`.
+
+### A gallery or sequential visual steps → Carousel
+
+Multiple images or slides the reader pages through — a screenshot gallery, a
+step-by-step walkthrough — is a carousel.
+
+→ `components-media.md`.
+
+### A file/directory layout or nested hierarchy → Tree
+
+Anywhere you'd draw an ASCII file tree, or show nested navigation/taxonomy, use a
+Tree — it's just an indented bullet list inside a `||||||` fence.
+
+```
+||||||open
+- icon:folder src
+  - icon:file index.ts
+  - icon:file utils.ts
+- icon:file README.md
+||||||
+```
+
+→ `components-interactive.md`.
+
+### Rotating tips / testimonials / featured content → Random content
+
+A "tip of the day", a rotating testimonial, a featured item that varies per load
+— with **no JavaScript of your own** — is random content.
+
+→ `components-interactive.md`.
+
+### A published/updated date → Format date or Relative time
+
+"Published June 26, 2026" → `[[[2026-06-26 style:long]]]`. "Updated 3 days ago" →
+`[[[relative 2026-06-20]]]`. Both localize in the browser.
+
+→ `components-media.md`.
+
+### A sidebar-plus-content or header-with-actions section → Layout
+
+- Sidebar + main → `::::flank`.
+- Two things pushed to opposite ends (logo left, nav right; copyright + links) →
+  `::::split`.
+- A row of tags/buttons/icons that wraps → `::::cluster`.
+- Consistent vertical rhythm between blocks → `::::stack`.
+- A responsive card grid → `::::grid`.
+- An aspect-ratio media box → `::::frame`.
+
+→ `layouts.md`.
+
+## Anti-patterns — don't do these
+
+- **Don't wrap everything.** If every paragraph is a callout, none of them stand
+  out. Components are emphasis; emphasis is scarce. Plain prose is the default.
+- **Don't nest interactive triggers.** A dialog inside a tooltip, a popover
+  inside a popover, a tab group inside a single tab that only holds another tab
+  group — these confuse readers and sometimes the runtime. Keep one trigger deep.
+- **Layouts wrap components; components don't wrap layouts.** Put cards inside a
+  `::::grid`; don't put a `::::grid` inside a `===` card. Layout containers are
+  the outermost structure. (A callout or card body holds prose and inline
+  components, not another `::::` block.)
+- **Don't reach for a component when Markdown already says it.** A two-item list
+  doesn't need a grid. A single link doesn't need a button. A one-line note
+  doesn't need a callout. Use the plainest thing that reads well.
+- **Don't use Details for a group or Accordion for one item.** One collapsible →
+  Details (`^^^`). A set of collapsibles → Accordion (`//////`).
+- **Don't invent attributes or variants.** `:::caution` is not a callout type;
+  `@@@primary` is not a tag variant. Check the component reference — the engines
+  silently drop unknown tokens, so a typo just disappears.
+- **Don't put Markdown image syntax directly inside a `::::frame`.** Use a raw
+  `<img>` tag there (Markdown images may not be processed inside layout
+  containers). Elsewhere, Markdown images work normally.