@aivorynet/slaide 1.0.2 → 1.0.4

package/skills/slaide/grammar.md

@@ -0,0 +1,183 @@
+# slaide grammar (v1)
+
+A formal grammar for the `.slaide` document layer. Notation: EBNF — `=` defines, `|` alternation, `{ }` zero-or-more, `[ ]` optional, `( )` grouping, `"x"` literal, `…` charset prose. The Markdown *inside* slot content is CommonMark and is not re-specified here; this grammar defines slaide' structural envelope, sigils, and the inline/attribute extensions, plus the master value forms.
+
+This file is the **precise structural reference**. For what each construct *does* — usage, examples, the full transition/entrance catalogs, chart/image/media options, and the `validate` diagnostic codes — see [spec.md](spec.md); for master semantics (colours, type scale, layouts, slot styles) see [themes.md](themes.md). The token sets are generated from the engine (`src/vocab.ts`) and kept in sync by `test/docs-sync.test.ts`.
+
+## 1. Document
+
+```ebnf
+deck            = [ headmatter ] , slide , { separator , slide } , [ NL ] ;
+headmatter      = fence , config-block , fence ;
+slide           = [ frontmatter ] , body ;
+frontmatter     = config-block , fence ;          (* see §2 detection rule *)
+separator       = NL , fence ;                     (* a line that is exactly "---" *)
+fence           = "---" , EOL ;
+NL              = newline ;
+```
+
+A deck is an optional headmatter block, then one or more slides separated by a bare `---` line. `headmatter` is the first fenced config block. Each slide is an optional fenced frontmatter block followed by a body.
+
+## 2. Frontmatter-vs-body detection (the load-bearing rule)
+
+A block immediately after a separator (or the leading fence) is **frontmatter** iff **both**:
+1. every non-blank, non-`#comment` line matches `config-line` (a `key:`/`~key:`/list-continuation), **and**
+2. it is terminated by a `fence` before the body begins.
+
+Otherwise the block is `body`. Consequences the parser guarantees:
+- The **first** config-like fenced block in the file is `headmatter`.
+- A body whose first line merely *contains* a colon (e.g. `We offer: Tooling`) is **not** frontmatter (it is not `key:`-only and has no trailing fence).
+- A config-shaped block whose keys are **none of** the known slide keys (`layout`, `background`, `transition`, `variant`, `chrome`, `footer`, `logo`, `morph`, …) is still read as frontmatter, **but** the compiler emits an `ambiguous-frontmatter` warning — so a spec-sheet body (`Name: …` / `Founded: …`) eaten as config is no longer silent.
+- To force a body that would otherwise look config-like, escape its first line with a leading backslash (`\Name: Acme`) or precede the slide with an empty frontmatter (`---` `---`).
+- Malformed YAML in a config block emits a `bad-config` warning (with the parser message) instead of silently rendering with defaults.
+
+```ebnf
+config-block    = { config-line | comment | blank } ;
+config-line     = [ "~" ] , key , ":" , [ value ] , EOL ;
+key             = ident ;
+comment         = "#" , … , EOL ;
+ident           = letter , { letter | digit | "-" | "_" } ;
+```
+
+`value` and nested structures follow YAML. A leading `~` on a key marks a **cascading** default (applies to this slide and all following until overridden); a bare key is **scoped** to its slide.
+
+## 3. Fences vs code
+
+`---` is a separator **only outside** a fenced code region. Inside ```` ``` ```` / `~~~` fences it is literal text.
+
+```ebnf
+code-fence      = ("```" | "~~~") , [ info-string ] , EOL , { any-line } , ("```" | "~~~") , EOL ;
+```
+
+A code fence whose `info-string` is a renderable type is rendered, not listed as code: `svg` (inline vector), `embed` (its body is a URL → sandboxed `<iframe>`), `widget` (its body is HTML/JS → `sandbox="allow-scripts"` srcdoc iframe, theme tokens injected), `mermaid` (diagram DSL → inline SVG), `echart` (ECharts `option` as JSON/YAML → inline SVG). Other info-strings render as code. CommonMark GFM pipe tables are supported as ordinary body content.
+
+Media uses the image syntax with a media extension: `![alt](clip.mp4)` / `![alt](track.mp3)` → `<video>`/`<audio>` (see §6).
+
+## 4. Body
+
+```ebnf
+body            = { region-marker | note | content-line } ;
+region-marker   = "::" , WS , slot-name , WS , "::" , EOL ;
+slot-name       = ident ;                          (* valid names are per-layout *)
+note            = "???" , [ WS ] , inline-text , EOL , { non-blank-line } ;
+content-line    = markdown-line ;                  (* CommonMark, with §5–§7 extensions *)
+```
+
+- `region-marker` routes following content into the named slot until the next marker or separator. Content before any marker → the layout's main slot.
+- `note` (a `???` line and its continuation until a blank line) is a speaker note: shown in the presenter overlay, omitted from audience view and PDF.
+
+### 4.1 Build sigil
+
+```ebnf
+build           = content , WS , ">>>" , EOL ;
+```
+
+A list item or block ending with `>>>` becomes an incremental build step. Steps auto-number in document order (a shared per-slide counter); identical effective step → simultaneous. In PDF all builds are settled (shown).
+
+### 4.2 Escaping sigils
+
+A leading backslash turns a slaide sigil into literal content (the backslash is removed):
+
+| Write | Renders as | Instead of |
+|---|---|---|
+| `\:: word ::` | literal `:: word ::` | a region marker |
+| `\??? text` | literal `??? text` body | a speaker note |
+| `… \>>>` | literal trailing `>>>` | a build step |
+| `\[text]{.cls}` | literal `[text]{.cls}` | a styled span (and skips class validation) |
+| `\Name: Acme` (first body line) | body line | frontmatter (see §2) |
+
+## 5. Inline styled spans
+
+```ebnf
+span            = "[" , inline-text , "]" , "{" , class , { class } , "}" ;
+class           = "." , class-name ;
+class-name      = ident ;                           (* resolved against the master *)
+```
+
+Classes chain (`[40-80%]{.grad-purple .huge}`). Resolution (see themes.md → *Marks / utility classes*):
+- `.grad` → brand gradient text; `.grad-<name>` → named gradient text.
+- `.<color>` → text color, where `<color>` is a `palette` key, `roles` name, or a literal CSS colour.
+- `.xs .sm .md .lg .xl .xxl .huge` → font-size (type-scale steps `small`…`stat`).
+- `.bold`, `.muted`, and image utilities `.round`, `.cover`, `.shadow`.
+
+A class that is **none** of the above (e.g. a typo like `.xxlarge` or `.grad-teel`) emits an `unknown-class` / `unknown-gradient` warning rather than silently degrading to inert/invisible CSS. Run `slaide slots <deck>` to print the legal slot, colour, gradient and size names for a deck's master; `slaide validate <deck> [--strict]` surfaces all diagnostics (`--strict` makes warnings fail).
+
+## 6. Image & attribute brace
+
+```ebnf
+image           = "![" , alt , "](" , src , [ WS , quoted ] , ")" , [ attr-brace ] ;
+attr-brace      = "{" , WS , { attr , WS } , "}" ;
+attr            = id-attr | class | kv-attr | anchor-attr ;
+id-attr         = "#" , ident ;
+kv-attr         = key , "=" , value-token ;         (* e.g. width=170px — unquoted, units ok *)
+anchor-attr     = "anchor" , ":" , WS , '"' , pct , WS , pct , WS , pct , WS , pct , '"' ;
+value-token     = { non-space-non-brace } ;
+pct             = number , "%" ;
+```
+
+One brace may mix `#id`, `.class`, `key=value`, and `anchor:"…"` in any order. `#id` enables shared-element **morph** to a same-id element on the next slide (`transition: morph`).
+
+## 7. Placeholders
+
+```ebnf
+placeholder     = "{{" , WS , ph-name , WS , "}}" ;
+ph-name         = ident ;
+```
+
+Substituted at compile time inside chrome bands and master text. Names: `page`, `total`, `pagePadded`, `totalPadded`, `date`, `title`, `author`, `slideTitle`, `footer`, plus any scalar headmatter/frontmatter key. Unknown names resolve to empty (with a warning).
+
+## 8. Master (`*.slaide.yaml`) value forms
+
+The master is YAML; this section pins the slaide-specific value vocabulary (see themes.md for full semantics).
+
+```ebnf
+master          = mapping of:
+                  "schema" , "name" , [ "description" ] ,
+                  [ "canvas" ] , [ "fonts" ] , [ "typeScale" ] , [ "colors" ] ,
+                  [ "gradients" ] , [ "tokens" ] , [ "backgrounds" ] ,
+                  [ "variants" ] , [ "transitions" ] , [ "chrome" ] , [ "ui" ] , [ "layouts" ] ;
+ui              = { [ "progress": boolean ] } ;     (* web position indicator; default true *)
+
+typeScale       = { "base": dim , "ratio": number , "steps": { step-name : (integer | dim) } } ;
+dim             = number , ("px"|"em"|"rem"|"%"|"vw"|"vh") ;
+color-ref       = "{palette." , ident , "}" | "{" , ident , "}" | css-color ;
+gradient-ref    = "{gradients." , ident , "}" | gradient-name ;
+
+layout          = { "areas": [ area-row , { area-row } ] ,
+                    [ "rows" ] , [ "cols" ] , [ "gap" ] , [ "padding" ] ,
+                    [ "align": ("start"|"center"|"end") ] ,
+                    [ "background": bg-name ] ,
+                    [ "chrome": ("both"|"header"|"footer"|"false") ] ,
+                    [ "logo": false ] ,
+                    "slots": { slot-name : slot } } ;
+area-row        = string ;                          (* space-separated slot names; rectangular *)
+slot            = { "type": slot-type , [ "style": style-map ] } ;
+slot-type       = "title"|"subtitle"|"body"|"image"|"media"|"quote"|"caption"| ident ;
+style-map       = { style-key : style-val } ;
+style-key       = "font"|"size"|"color"|"fill"|"align"|"valign"|"justify"
+                | "weight"|"leading"|"transform"|"italic"|"maxw"|"box" ;
+
+chrome          = { [ "header": band ] , [ "footer": band ] ,
+                    [ "logo": svg-string ] , [ "logoPos": corner ] } ;
+band            = { [ "left": tmpl ] , [ "center": tmpl ] , [ "right": tmpl ] } ;
+tmpl            = string ;                           (* Markdown-inline + placeholders *)
+corner          = "top-left"|"top-right"|"bottom-left"|"bottom-right" ;
+```
+
+## 9. Reserved tokens (summary)
+
+| Token | Context | Meaning |
+|---|---|---|
+| `---` | line | slide separator / config fence (outside code fences) |
+| `:: name ::` | line | region/slot marker |
+| `>>>` | end of line/item | build step |
+| `???` | line start | speaker note |
+| `~key:` | frontmatter | cascading default |
+| `[t]{.c}` | inline | styled span |
+| `{#id .c k=v anchor:"…"}` | after image | attributes |
+| `{{name}}` | chrome/master text | placeholder |
+| `![alt](x.mp4\|.mp3)` | inline | video / audio |
+| ```` ```svg ```` | fence | inline vector embed |
+| ```` ```embed ```` / ```` ```widget ```` | fence | sandboxed iframe (URL / inline JS) |
+| ```` ```mermaid ```` / ```` ```echart ```` | fence | chart → inline SVG (diagram / data viz) |
+| `\` (leading) | before a sigil | escape to literal (`\::`, `\???`, `\>>>`, `\[t]{.c}`) |

package/skills/slaide/reference.md

@@ -40,22 +40,37 @@ My Talk
 | Key | Values | Meaning |
 |---|---|---|
 | `layout` | a master layout name | Which grid to use. |
-| `transition` | `none`,`fade`,`slide-left/right/up/down`,`zoom`,`morph` | Transition **into** this slide. |
+| `transition` | a transition name (§3.1) | Transition **into** this slide. |
+| `transition-ms` | milliseconds | Duration override for this slide's transition. |
+| `transition-ease` | a CSS easing | Easing override (`ease`, `cubic-bezier(…)`). |
 | `background` | a master background name | Override the layout's background. |
 | `variant` | a master variant name | Scoped token overrides (e.g. a light section). |
 | `morph` | an id | Participate in a shared-element morph. |
 | `footer` | inline Markdown | Per-slide footer; also `{{footer}}`. |
 | `chrome` | `both`,`header`,`footer`,`none`,`false` | Header/footer visibility this slide. |
 | `logo` | `false` | Hide the corner logo this slide. |
+| `notes` | inline Markdown | Speaker note for this slide (frontmatter form of a `???` line). |
 | *any other scalar* | — | Available as a `{{placeholder}}`. |
 
 **Cascade vs scope:** a bare key (`transition: zoom`) is this-slide-only; a `~`-prefixed key cascades to this slide and every later one until overridden (also valid in headmatter).
 
+### 3.1 Transition names
+
+`transition:` takes one of these built-ins; per-slide `transition-ms` / `transition-ease` override timing, and the master's `transitions: { default, duration }` sets the deck-wide default.
+
+| Group | Names |
+|---|---|
+| Fades | `none`, `fade`, `dissolve`, `fade-through-black` (alias `fade-black`) |
+| Slides | `slide-left` (alias `slide`), `slide-right`, `slide-up`, `slide-down` |
+| Push/cover | `push`, `cover`, `reveal` |
+| Scale/3-D | `zoom`, `zoom-out`, `flip` |
+| Shared-element | `morph` — pairs a `{#id}` image (or a `morph:` id) with the same id on the next slide |
+
 ## 4. Slide body
 
 - **Regions:** `:: name ::` on its own line routes following Markdown into slot `name`. Text before any marker → the main slot (`body`, else the first slot).
 - **Markdown:** standard CommonMark — headings, lists, **bold**, *italic*, `code`, fences, > quotes, links, tables, images. (A single newline is a space; blank line = new paragraph.)
-- **Builds `>>>`:** end an item/block with `>>>` to reveal it; steps auto-number in order, same step = simultaneous. PDF shows all.
+- **Builds `>>>`:** end an item/block with `>>>` to reveal it; steps auto-number in order, same step = simultaneous. PDF shows all. Add an entrance and timing after the sigil (§4.7).
 - **Notes `??? …`:** a `???` line (until a blank line) is a speaker note — presenter overlay only, hidden from audience and PDF.
 
 ### 4.1 Inline styled spans — `[text]{.class …}`
@@ -114,6 +129,17 @@ Both render to **theme-coloured inline SVG** (web/PDF/PNG/PPTX); `slaide build`
 
 GFM pipe tables, styled by the master; use `[cell]{.class}` spans for emphasis.
 
+### 4.7 Build entrances — `>>> <entrance> [opts]`
+
+A bare `>>>` reveals with the default entrance (`fade-up`). Name an entrance right after the sigil, optionally with `delay=`, `dur=` and `ease=` (bare numbers are milliseconds): `- Big reveal >>> zoom-in delay=200 dur=600`. An unknown name warns (`unknown-entrance`) and falls back to the default. A master `animations:` block can define custom entrances too.
+
+| Group | Names |
+|---|---|
+| Fades | `fade`, `fade-up`, `fade-down`, `fade-left`, `fade-right`, `blur-in` |
+| Slides | `slide-in-left`, `slide-in-right`, `slide-in-up`, `slide-in-down`, `rise` |
+| Scale | `zoom-in`, `zoom-out`, `pop` |
+| Instant | `none` |
+
 ## 5. Layers
 
 Each slide composites **background → content → chrome** by paint order. Backgrounds come from the master (per layout or per slide); content flows through the layout's named slots; chrome sits on top.
@@ -175,3 +201,33 @@ footer: A first deck
 ```
 
 See [themes.md](themes.md) to author a master.
+
+## 10. Diagnostics — what `validate` reports
+
+`slaide validate <deck>` prints line-numbered diagnostics; `--strict` makes every warning fail. **Errors** fail regardless of `--strict`; everything else is a **warning** (a real render defect even when the deck "looks valid"). Every code:
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `parse-error` | error | The source could not be parsed at all. |
+| `empty-deck` | error | No slides were found. |
+| `no-master` | error | The deck's `master:` could not be resolved. |
+| `unknown-layout` | error | A slide's `layout:` names no layout in the master. |
+| `no-headmatter` | warning | No leading `---` deck headmatter block (e.g. `master:`). |
+| `bad-config` | warning | A headmatter/frontmatter block is not valid YAML (rendered with defaults). |
+| `ambiguous-frontmatter` | warning | A config-shaped **body** was eaten as frontmatter — escape the first line with `\` or add an explicit `---`. |
+| `unknown-transition` | warning | A `transition:` names no built-in transition (§3.1). |
+| `unknown-background` | warning | A `background:` names no master background. |
+| `unknown-variant` | warning | A `variant:` names no master variant. |
+| `unknown-slot` | warning | Content routed to a slot the chosen layout doesn't define (dropped silently). |
+| `unknown-class` | warning | An inline `[x]{.cls}` is not a size / `.bold` / `.muted` / `.grad` / master colour / CSS colour. |
+| `unknown-gradient` | warning | A `.grad-<name>` or slot `fill:` names no master gradient (text gets no fill — often invisible). |
+| `unknown-color` | warning | A slot `color:`/`box:` names no master role/palette or CSS colour (falls back to a literal, often invisible). |
+| `unknown-entrance` | warning | A `>>> <name>` build entrance isn't a known effect (§4.7). |
+| `stray-build` | warning | A `>>>` on a non-list line (headings, bold labels, paragraphs). |
+| `low-contrast` | warning | Resolved text ≈ its background (dark-on-dark / light-on-light) — bind a `variant:` or set an explicit `color:`. |
+| `bad-chart` | warning | An ````echart` option didn't parse — rendered as a plain code block instead. |
+| `bad-animation` | warning | A master `animations:` entry is missing its required keyframes/`hidden` state. |
+| `unknown-token` | warning | A master token reference names nothing. |
+| `token-cycle` | warning | A master token references itself in a cycle. |
+| `non-embeddable-font` | warning | A font won't embed in `.pptx` — PowerPoint will substitute it. |
+| `unknown-placeholder` | warning | A `{{name}}` resolves to nothing (renders empty). |

package/skills/slaide/themes.md

@@ -47,12 +47,14 @@ colors:
     accent:     "{palette.brand}"
 layouts:
   cover:
-    align: center
-    areas: ["title", "subtitle"]
+    areas: ["title visual", "subtitle visual"]
     rows: "auto auto"
+    cols: "1.1fr 0.9fr"
+    gap: "0.5em 3em"
     slots:
       title:    { type: title,    style: { font: display, size: h1, weight: "900" } }
       subtitle: { type: subtitle, style: { size: h3, color: accent } }
+      visual:   { type: image,    style: { valign: center } }
   title-content:
     areas: ["title", "body"]
     rows: "auto 1fr"
@@ -69,7 +71,7 @@ layouts:
 
 ## fonts / typeScale
 
-**Use real Google Fonts only** (`provider: google`) — pick families that actually exist on Google Fonts and embed (avoid **JetBrains Mono**, which doesn't). A `display` (headings) + a `sans` (body) is plenty; add a `mono` role only if the deck shows code. A `provider: system`/`local` font that isn't a common system font (Arial, Calibri, Georgia…) **warns** (`non-embeddable-font`): it won't embed in the `.pptx`, so PowerPoint substitutes it off your machine.
+**Use real Google Fonts only** (`provider: google`) — pick families that actually exist on Google Fonts. A `display` + `sans` is plenty; add `mono` only if the deck shows code. A `provider: system`/`local` font that isn't a common system font (Arial, Calibri, Georgia…) **warns** (`non-embeddable-font`): it won't embed in `.pptx`.
 
 ```yaml
 fonts:
@@ -195,6 +197,7 @@ layouts:
 | `box` | surface panel (bg + padding + radius) | `true`, a colour role/palette name (preferred), a **named master gradient** (`box: brand` → padded, rounded, gradient hero/closing panel), or a raw hex / CSS colour / gradient |
 | `bg` | background of the slot region | any CSS colour / gradient (literal) |
 | `anchor` | absolutely position the slot | `"x% y% w% h%"` of the canvas |
+| `pad` / `opacity` / `radius` / `border` / `rotate` | fine control — padding / opacity / border-radius / border / rotation (also emitted by the importer) | CSS values (`rotate` accepts a bare deg or a full `transform`) |
 
 `color:`/`box:`/`fill:` are validated against the master — an unresolved name warns, so `validate` can't call an invisible-text slide valid. Run `slaide slots` for legal names.
 
@@ -208,8 +211,19 @@ Inline `[text]{.class}` resolves against this master: **colour** = any `palette`
 
 ## Tips for AI authors
 
-- Reference **roles** and **scale steps**, not raw hex/px, so a reskin is a palette swap. Add a layout by adding an `areas` map + `slots` — no code.
-- **Cards (`box:`) — kill hollow tops.** A `box:` is bg + padding + radius only (solid colour — **no gradient/shadow/border**). With no `valign` a card **stretches to its grid row** and pins text to the top — hollow in a tall `1fr` row. Two fixes: **`valign: center`** shrinks the card to its content and centres it; or, to keep a row of cards equal height, put them in an **`auto`** row and centre that block with spacer rows (`rows: "auto 1fr auto 1fr"`). On a light ground, tint the card surface off-white vs the page so it reads.
-- **Signature, not just tidy:** give the deck one repeated motif (a faint logo-derived shape or a recurring accent panel) and vary composition slide to slide. Make the **cover and closing command** — don't leave half the canvas empty: pair a strong text column with a full-height brand/gradient panel or full-bleed motif.
-- **Inline `svg` needs a size:** give the `<svg>` explicit `width`/`height`, or a centered zero-size SVG collapses and vanishes.
-- **A deck about slaide itself?** Use the shipped brand in the sibling `slaide-hugo` repo (`themes/slaide/assets/css/slaide.css` `:root`; `static/images/slaide-*.svg`): slate-azure gradient `#243B6B→#3E6FB0→#6FA8DC` on cream `#FBF7F0` / ink `#15120E`; IBM Plex Sans + JetBrains Mono + Fraunces.
+- Use **roles** and **scale steps**, not raw hex/px — reskin = palette swap.
+- **Cards (`box:`):** bg + padding + radius only (no gradient/shadow/border). Without `valign` a card stretches full-height and pins text top (hollow). Fix: `valign: center` to shrink-wrap, or put cards in an `auto` row with `1fr` spacers. Tint card surface off-white vs the page.
+- **Cover = dramatic hero.** Visual slot FILLS — bold brand SVG, product mock, or illustrated motif at ≥ half the slide, not a small icon. Think Apple keynote: few bold shapes at large scale. Centred text on a gradient is a section divider, not a cover. Never `.grad` text on a gradient bg (vanishes). **Closing** = bold CTA or contact slide (name/role/email/URL for pitch/agency decks). Both must feel intentional.
+- **Brand ground dominates.** Most slides use the brand's background role (warm cream, tinted neutral — not generic white). Dark/gradient = accent moments only (cover, one stat, closing).
+- **No text-only slides — no exceptions.** Every content slide needs a visual: ` ```echart ` for data, inline ` ```svg ` for diagrams/mockups (preferred — precise, brand-styled), `box:` cards, or a stat callout. A comparison/pro-con slide is NOT exempt: use cards, a table, or SVG icons. Mix visual types across the deck — all-SVG or all-cards = monotone.
+- **Vary composition.** Never repeat the same layout archetype — two text+visual slides need structurally different layouts (not image-left twice). Mix archetypes, alternate dark/light grounds. One slide should break the pattern — oversized `.grad` stat, serif quote owning the canvas, or full-bleed visual.
+- **One idea per slide.** Each slide delivers one clear message (4 bullets max). The visual and text reinforce the SAME idea — if the visual still communicates without the text, that's right.
+- **Size contrast.** Pair `hero`/`stat` scale with body text. At least one slide MUST feature a single big number or statement using `.huge` or `.stat` — the audience remembers ONE number from every deck. No decorative accent lines under titles (AI tell).
+- **Use every font role** defined in the master (serif, display, mono).
+- **Whitespace.** `--slide-padding` ≥ 96px, `gap` ≥ 2em. `auto` rows for content, `1fr` spacers to centre. Cards need `pad`.
+- **Avoid `<a>` links in slides.** They aren't clickable during presentations and their `link` role color can override slot `color:`. Write URLs as plain text; style with `[text]{.class}` spans.
+- **Muted text must read at projection scale.** Keep well above 2.5:1 contrast. Never use light-ground `muted` inside a dark `box:`/`bg:` card — set explicit light `color:` instead.
+- **Inline SVG:** explicit `width`/`height` required (collapses without them). Images fill their container (the layout controls sizing via grid areas + padding).
+- **Academic / teaching decks** (symposia, lectures, workshops): clarity over flash. Favour ` ```svg ` / ` ```mermaid ` diagrams for processes and systems, ` ```echart ` for data/results. Use `>>>` heavily for progressive build. Larger body text (≥ h3). Section dividers between topics. End with summary/takeaways/questions, not a sales CTA. High-contrast, clean backgrounds.
+- **Financial / board reports**: data credibility first. Heavy ` ```echart ` (bar, line, waterfall, pie). Stats use `.huge` with exact numbers. Comparison tables via `box:` card grids (Plan vs Actual). Conservative palette — dark text on light ground, accent on KPI highlights only. Section dividers per business unit or period. Cover = clean title + period, not a hero. End with outlook/risks.
+- **A deck about slaide?** Brand from `slaide-hugo` repo: azure `#243B6B→#3E6FB0→#6FA8DC`, cream `#FBF7F0`, ink `#15120E`; IBM Plex Sans + JetBrains Mono + Fraunces.