oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-slide/resources/design-doctrine.md

@@ -0,0 +1,260 @@
+# Design Doctrine — oma-slide
+
+> Anti-"AI slop" aesthetics, font rules, content-density modes, and accessibility requirements.
+> Read this document before writing any slide HTML. It defines the aesthetic contract for all
+> oma-slide generated decks.
+
+---
+
+## 1. The Anti-"AI Slop" Commitment
+
+Most AI-generated presentations are immediately recognizable: Inter or Roboto at arbitrary sizes,
+purple-to-blue linear gradients, white cards dropped on a gradient background, icon rows that
+feel copied from a template screenshot. These choices read as unowned — the visual equivalent of
+filler text.
+
+Every oma-slide deck must make a **committed aesthetic choice** and follow it through. That means:
+
+- A **distinctive typographic voice** — not the path of least resistance.
+- A **committed palette** — 2–4 colors with semantic roles, not "looks fine on screen."
+- An **atmospheric intention** — the deck should feel like something, not just contain information.
+
+The test: could this slide have come from a specific studio, designer, or publication? If yes,
+it is doing its job.
+
+---
+
+## 2. Typography Rules
+
+### 2a. Forbidden Defaults
+
+Do **not** use the following as the primary or display typeface:
+
+| Typeface | Why forbidden |
+|---|---|
+| Inter | Ubiquitous SaaS default; zero personality at display sizes |
+| Roboto | Google Material default; reads as a framework artifact |
+| Arial / Helvetica (unmodified) | Corporate filler; visually neutral to the point of invisibility |
+| Open Sans | Overused in educational/government templates |
+| Lato | Same problem as Open Sans |
+
+Using any of the above as a **body/fallback** in a font stack is acceptable. Using them as
+the **display/headline typeface** produces AI-slop output.
+
+### 2b. Distinctive Latin Display Fonts (encouraged)
+
+Choose from distinctive, well-crafted typefaces. Examples (all free via Google Fonts or equivalent CDN):
+
+| Typeface | Character | Good for |
+|---|---|---|
+| Playfair Display | Classical serif elegance | Editorial, advisory, literary |
+| Cormorant Garamond | Literary high-contrast serif | Scholarly, quiet luxury |
+| Fraunces | Optical-size serif with personality | Warm editorial, brand work |
+| Bricolage Grotesque | Variable grotesk with rhythm | Contemporary, design-led |
+| Bebas Neue | Condensed caps impact | Bold poster, headlines-only |
+| Shrikhand | Bold decorative display | Loud editorial, manifesto |
+| Space Grotesk | Technical yet warm | Tech, SaaS with voice |
+| Syne | Geometric with irregular flow | Indie, experimental |
+| Alfa Slab One | Slab-serif punch | Activist, campaign energy |
+| DM Serif Display | Transitional, refined | Professional with warmth |
+
+This is not an exhaustive list — use judgment. A face should be chosen because it serves the
+deck's mood, not because it is available.
+
+### 2c. CJK Decks — Pretendard Required
+
+Any deck whose content includes **Korean (한국어), Japanese (日本語), or Chinese (中文)** characters
+**must** include Pretendard Variable as the primary font. This is non-negotiable.
+
+```html
+<!-- In <head> -->
+<link rel="preconnect" href="https://cdn.jsdelivr.net" />
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable-dynamic-subset.min.css"
+/>
+```
+
+```css
+:root {
+  --font-body: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont,
+    "Apple SD Gothic Neo", "Noto Sans KR", "Noto Sans JP", "Noto Sans SC", sans-serif;
+  --font-display: "Pretendard Variable", Pretendard, sans-serif;
+}
+```
+
+Rationale: the system CJK font stack varies wildly across OS versions and produces
+inconsistent rendering at large display sizes. Pretendard is modern, variable, and has
+a dynamic subset CDN making it practical for web delivery.
+
+For bilingual EN/CJK decks: pair Pretendard with a compatible latin display face (e.g.,
+Bricolage Grotesque or a Grotesk that harmonizes with Pretendard's proportions).
+
+### 2d. Font Loading
+
+Load display fonts via `<link rel="preconnect">` + `<link rel="stylesheet">` in the `<head>`.
+The validator awaits `document.fonts.ready` before measuring geometry — so font choices directly
+affect overflow detection. Choose fonts early in the generation phase, not as an afterthought.
+
+---
+
+## 3. Color Palette Rules
+
+### 3a. Anti-Patterns to Avoid
+
+| Pattern | Why it fails |
+|---|---|
+| Purple-to-blue linear gradient background | The single most common AI-generated visual cliché |
+| Gradient orbs/blobs floating on white | Overused in SaaS landing-page design, reads as template |
+| Full-rainbow accent colors | Signals no palette decision was made |
+| Pure `#ffffff` background with no atmospheric treatment | Clinically neutral; no sense of material or surface |
+| Bright neon on black + one more neon (no restraint) | Every cyberpunk AI deck; needs commitment to be distinctive |
+
+### 3b. Committed Palette Structure
+
+A good palette has **semantic roles**, not just colors:
+
+```
+background   — the canvas; sets material and atmosphere
+text-primary — main readable content; must pass WCAG AA on background
+text-muted   — supporting text, captions; must pass WCAG AA
+accent       — maximum one primary accent; the deck's signature color
+accent-alt   — optional secondary accent; only if the design concept requires it
+```
+
+Name colors descriptively: `"Ink Navy (#1a2332)"` not `"dark blue"`. The name carries
+the palette intent.
+
+### 3c. WCAG AA Minimum
+
+All text must meet **WCAG 2.1 AA** contrast ratios:
+- Normal text (< 18 pt / < 14 pt bold): 4.5:1 contrast ratio
+- Large text (≥ 18 pt / ≥ 14 pt bold): 3:1 contrast ratio
+
+At 1920×1080, "normal" text corresponds to roughly ≤ 24 px; "large" text to ≥ 24 px.
+
+Use a contrast checker before finalizing a palette. If a design direction cannot meet AA, revise
+the palette — do not compromise accessibility for aesthetics.
+
+---
+
+## 4. Atmospheric Intention
+
+Atmosphere is the quality that makes a deck feel like it was designed rather than assembled.
+It comes from:
+
+- **Background treatment**: solid color, gradient with direction and purpose, subtle texture,
+  or photographic.
+- **Whitespace**: deliberate emptiness communicates confidence. Cramped slides communicate anxiety.
+- **Typographic hierarchy**: 2–3 sizes maximum per slide, each with a clear role.
+- **Layer logic** (from `fixed-stage.md`):
+  - z-index 0 — background
+  - z-index 10 — atmosphere (texture, overlay)
+  - z-index 100 — content
+  - z-index 200 — highlights/callouts
+
+The wildcard preview in Phase 2 is the appropriate place to introduce an unexpected atmospheric
+direction. The safe preset and bold template choices should stay within recognizable territory.
+
+---
+
+## 5. Content-Density Modes
+
+The `density` field in `meta.json` governs how slides are laid out and how much content they carry.
+Its values are the CLI enum `sparse | balanced | dense`: a speaker-led deck maps to `sparse`, a
+reading-first deck maps to `dense`, and `balanced` (the default) sits in between.
+
+### 5a. Speaker-Led (`sparse`)
+
+The presenter is the primary content delivery vehicle. Slides are visual anchors.
+
+| Element | Guidance |
+|---|---|
+| Headline | 1 short statement per slide; 64–120 px; ≤ 10 words |
+| Body text | 0–3 lines maximum; 32–48 px; no prose paragraphs |
+| Bullets | Avoid. Use one concept per slide instead. |
+| Visuals | Large, occupying ≥ 40% of the canvas |
+| Slide count | Allow 1 slide per 1–2 minutes of talk time |
+| Speaker notes | Extensive notes in `meta.json.speakerNotes[]` for the presenter |
+
+### 5b. Reading-First (`dense`)
+
+The deck is a self-contained document. Readers consume it without a presenter.
+
+| Element | Guidance |
+|---|---|
+| Headline | Clear, self-explanatory; 48–72 px |
+| Body text | Full sentences allowed; 28–36 px; max 8 lines per slide |
+| Bullets | Acceptable; ≤ 6 items; each bullet ≤ 20 words |
+| Visuals | Supporting; labeled with captions |
+| Slide count | Allow as many slides as the content requires |
+| Speaker notes | Optional; deck must stand alone without them |
+
+### 5c. Mixed Density
+
+Some decks mix modes (e.g., opener slides are sparse, data slides are dense). Apply the relevant
+mode rules per slide and record the overall dominant mode in `meta.json.density`
+(`sparse`, `balanced`, or `dense`).
+
+---
+
+## 6. Slide Count Guidance
+
+| Purpose | Sparse (speaker-led) | Dense (reading-first) |
+|---|---|---|
+| Pitch / investor (5 min) | 6–10 slides | 8–14 slides |
+| Internal report (15 min) | 12–18 slides | 18–30 slides |
+| Conference talk (30 min) | 20–35 slides | 30–50 slides |
+| Executive briefing (10 min) | 8–12 slides | 12–20 slides |
+| Product launch (standalone) | 10–16 slides | 16–28 slides |
+
+These are guidelines, not hard limits. Content scope governs slide count; do not pad or compress
+slides to hit a number.
+
+---
+
+## 7. What a Good Slide Looks Like
+
+A well-crafted slide satisfies all of these:
+
+1. **One idea** — a viewer can state the slide's point in one sentence.
+2. **Scannable hierarchy** — the largest element is the most important.
+3. **Comfortable empty space** — the canvas breathes; content does not fill edge to edge.
+4. **Consistent with the deck** — the color, font, and grid choices are the same as every other slide.
+5. **Readable at scale** — body text ≥ 28 px (doctrine floor; the validator's hard gate rejects only text below 18 px); the smallest legible text at 1920×1080 passes WCAG AA.
+
+---
+
+## 8. What Makes a Deck Feel Distinctive (not just acceptable)
+
+The difference between "it looks fine" and "this is well designed" is usually one of:
+
+- **Typographic commitment**: the display typeface is unmistakably itself at every size.
+- **Palette ownership**: the colors have a name and a reason; they could not have been chosen randomly.
+- **Compositional tension**: not every element is centered and balanced — some slides use asymmetry, large negative space, or a single dominant element to create visual interest.
+- **Atmospheric consistency**: the first slide and the last slide feel like they come from the same world.
+- **Motion that earns its place**: if there are animations, they reinforce the content rhythm — a fade-up for an incoming point, not a spin because CSS supports it.
+
+---
+
+## 9. Accessibility Requirements (WCAG AA)
+
+### 9a. Animation Performance
+
+Use `transform` + `opacity` only for animations. Avoid `width`, `height`, `margin`, `padding`
+transitions (these cause layout reflows and are expensive at 1920×1080).
+
+### 9b. Focus States
+
+Navigation controls (`.deck-nav button`) must have visible `:focus-visible` styles. The viewer
+is keyboard-navigable; sighted keyboard users must see which element has focus.
+
+### 9c. Fixed Stage Tradeoff
+
+The fixed 1920×1080 letterbox model is an accepted, conscious limitation:
+- On small mobile screens the stage scales down (text shrinks proportionally).
+- Screen readers receive the raw HTML structure, not the scaled layout.
+- Zoom interactions in browsers may distort the scaled stage.
+
+These are known tradeoffs of the stage model — do not attempt to work around them in generated
+HTML. Document this limitation when relevant to the user.

package/skills/oma-slide/resources/fixed-stage.md

@@ -0,0 +1,232 @@
+# Fixed-Stage Rules — oma-slide
+
+> The canonical reference for the 1920×1080 stage model, embedding instructions, px-authoring
+> conventions, and the CJK → Pretendard rule.
+
+## 1. The 1920×1080 Invariant
+
+All slides are authored at exactly **1920 × 1080 px**. This is non-negotiable:
+
+- The validator (`oma slide validate`) renders at 1920×1080 and checks geometry at that size;
+  it reports px→pt at 0.75 (1920×1080 px → 1440×810 pt at 96 dpi / 72 pt-per-inch).
+- The exporter (`oma slide export pdf|png`) captures at 1920×1080 before any post-processing.
+- PPTX export places each rasterized slide full-bleed on a LAYOUT_WIDE canvas
+  (13.333 in × 7.5 in = 960×540 pt) — pixel authoring only, no pt in HTML.
+- Do **not** author in percentages, `vw/vh`, or responsive units that reflow the layout.
+  Fixed `px` values only inside `.slide`.
+
+```
+Canvas size:  1920 px wide  ×  1080 px tall
+Aspect ratio: 16:9
+Validator pt: 1440 pt wide  ×  810 pt tall    (px × 0.75)
+PPTX layout:  13.333 in × 7.5 in (960×540 pt) — raster placed full-bleed
+```
+
+## 2. Stage Scaling — How It Works
+
+`deck-stage.js` computes:
+
+```js
+const scale = Math.min(viewportWidth / 1920, viewportHeight / 1080);
+```
+
+Then positions the `.deck-stage` element so it is centred (letterbox / pillarbox):
+
+```js
+offsetLeft = (viewportWidth  - 1920 * scale) / 2
+offsetTop  = (viewportHeight - 1080 * scale) / 2
+
+stageEl.style.transform = `scale(${scale})`;
+stageEl.style.left      = `${offsetLeft}px`;
+stageEl.style.top       = `${offsetTop}px`;
+```
+
+`transform-origin` is `top left` (set in `viewport-base.css`). This keeps the maths
+simple and avoids a secondary translate.
+
+The viewport background (`#000` default) fills the letterbox/pillarbox bars. You can change
+the background color of `.deck-viewport` in a theme without breaking the scale maths.
+
+## 3. Embedding into a Deck
+
+Paste or link the two shared assets into every deck's `<head>`. The `oma slide create` command
+copies them into the workdir automatically; `oma slide bundle` inlines them into the single-file
+output.
+
+### Option A — External files (development / per-slide workdir)
+
+```html
+<head>
+  <link rel="stylesheet" href="./viewport-base.css" />
+</head>
+<body>
+  <deck-stage>
+    <div class="deck-viewport">
+      <div class="deck-stage">
+        <section class="slide" id="slide-01">
+          <!-- 1920×1080 content here -->
+        </section>
+        <section class="slide" id="slide-02">
+          <!-- ... -->
+        </section>
+      </div>
+    </div>
+  </deck-stage>
+
+  <!-- Optional: speaker notes (JSON keyed by 0-based slide index) -->
+  <script type="application/json" id="speaker-notes">
+    { "0": "Opening remarks...", "1": "Second slide notes..." }
+  </script>
+
+  <script src="./deck-stage.js"></script>
+</body>
+```
+
+<!-- oma-docs:ignore-start -->
+### Option B — Inlined (single-file bundle — `out/deck.html`)
+<!-- oma-docs:ignore-end -->
+
+`oma slide bundle` inlines both files; the structure is the same but the
+`<link>` is replaced by `<style>...</style>` and `<script src>` becomes `<script>...</script>`.
+
+### Optional: nav controls + slide counter
+
+`deck-stage.js` looks for existing `.deck-nav` and `.deck-counter` elements.
+If none are present the viewer still works (keyboard/touch/wheel only).
+For `viewer.html`, the CLI injects:
+
+```html
+<nav class="deck-nav" aria-label="Slide navigation">
+  <button id="btn-prev" aria-label="Previous slide">&#8592;</button>
+  <button id="btn-next" aria-label="Next slide">&#8594;</button>
+</nav>
+<div class="deck-counter" role="status" aria-live="polite"></div>
+```
+
+## 4. px-Authoring Conventions
+
+| Element | Convention |
+|---|---|
+| Slide root | `position: absolute; inset: 0; width: 1920px; height: 1080px;` |
+| Safe zones | Left/right margin ≥ 80px; top/bottom margin ≥ 60px |
+| Body text | 28–36 px doctrine floor; heading 64–120 px. (The validator hard-fails only below 18 px — 18–27 px passes the gate but is reserved for captions/labels.) |
+| Icon / decorative image | explicit `width`/`height` in px |
+| Background gradients | allowed (CSS); rasterized to PNG at PPTX export |
+| Clipping / overflow | `overflow: hidden` on `.slide` prevents bleed-out |
+| Animations | `transform` + `opacity` only |
+
+### 8-px Grid
+
+Align all spacing, padding, and element positions to multiples of 8 px. This keeps designs
+crisp at all scale factors and maps cleanly to pt at PPTX export.
+
+### Z-index layers
+
+```
+0     background layer   (solid color, image, gradient)
+10    atmosphere layer   (subtle overlay, texture)
+100   content layer      (text, charts, icons)
+200   highlight layer    (callouts, badges)
+1000  overlay layer      (modal-style content, reserved)
+```
+
+## 5. Slide Visibility — Always Use .active / .visible
+
+**Never** toggle slides with `display:none` or `display:block`. Some layout classes from design
+themes may override that and reveal all slides at once.
+
+Use the CSS class protocol defined in `viewport-base.css`:
+
+| Class | Meaning |
+|---|---|
+| _(no class)_ | Hidden: `visibility:hidden; opacity:0; pointer-events:none` |
+| `.active` | Fully visible: `visibility:visible; opacity:1; pointer-events:auto` |
+| `.visible` | Fading out: `visibility:visible; opacity:0; pointer-events:none` |
+
+`deck-stage.js` manages these classes automatically. Slide authors do not need to set them.
+
+## 6. Validator Contract — data-om-validate
+
+`deck-stage.js` automatically annotates each `.slide` with:
+
+```html
+data-screen-label="Slide N / M"
+data-om-validate="no_overflowing_text,no_overlapping_text,slide_sized_text"
+```
+
+`oma slide validate` (puppeteer-core) reads these attributes to:
+
+1. Locate each slide in the rendered DOM.
+2. Know which checks to run (overflow / overlap / size checks).
+3. Report findings as `{ code, message, slide, selector?, rect? }`.
+
+**Do not remove or override `data-om-validate`** in authored slide HTML. If a slide intentionally
+clips text (e.g., a decorative element), annotate the clipping element with `data-om-no-check`
+to suppress false-positive overflow findings.
+
+## 7. CJK Content → Pretendard Required
+
+Any deck whose content contains Korean (한국어), Japanese (日本語), or Chinese (中文) characters
+**must** include Pretendard Variable as the primary font.
+
+```html
+<!-- In <head> — Pretendard via CDN (fallback to system CJK stack) -->
+<link rel="preconnect" href="https://cdn.jsdelivr.net" />
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable-dynamic-subset.min.css"
+/>
+```
+
+CSS font-family for CJK decks:
+
+```css
+:root {
+  --font-body: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont,
+    "Apple SD Gothic Neo", "Noto Sans KR", "Noto Sans JP", "Noto Sans SC", sans-serif;
+  --font-display: "Pretendard Variable", Pretendard, sans-serif;
+}
+```
+
+For latin-only decks, distinctive display fonts are encouraged (anti-"AI slop"):
+system-font-stack restriction applies only to the **body** font fallback, not to
+the chosen heading/display typeface.
+
+## 8. Print / Save-as-PDF
+
+Trigger with `Ctrl+P` / `Cmd+P` in the browser, or use `oma slide export pdf --mode print`.
+
+`deck-stage.js` removes the CSS transform before the print layout renders, so the browser
+sees the true 1920×1080 px layout. `viewport-base.css` `@media print` rules:
+
+- Remove `.deck-viewport` overflow/fixed positioning.
+- Remove transform from `.deck-stage`.
+- Make all `.slide` elements visible with `break-after: page`.
+- Hide `.deck-nav` and `.deck-counter`.
+
+Result: one clean 1920×1080 slide per printed page.
+
+## 9. Presenter View (embedded notes panel + postMessage API)
+
+The presenter view is an **embedded on-screen notes panel** — there is no separate
+presenter window. `deck-stage.js` reads speaker notes from
+`<script type="application/json" id="speaker-notes">` (a JSON object keyed by
+**0-based slide index** as a string: `"0"`, `"1"`, …). Press **`n`** to toggle a
+fixed, semi-transparent panel at the bottom of the viewport showing the current
+slide's note; it updates automatically on slide change, is hidden by default
+(never intercepts clicks when hidden), and is suppressed during print.
+
+For embedding integrations, `deck-stage.js` also posts on every slide change:
+
+```js
+window.parent.postMessage(
+  { type: "slideIndexChanged", index: N, total: M, note: "speaker note text" },
+  "*"
+);
+```
+
+The parent frame can navigate the iframe by posting:
+
+```js
+iframeEl.contentWindow.postMessage({ type: "navigateTo", index: N }, "*");
+```