bonny-slide-system

name

bonny-slide-system

description

Build, critique, and iterate bilingual 繁中 + English UX/product slides and decks (HTML per-slide, single-scroll HTML, PDF, or PPTX). The agent READS specs/ and BUILDS with assets/. Use for UX/product storytelling, workshop and workflow slides, design-system decks, reference-image learning, and intention-routed generated editorial explainers. Every deck must record a per-slide illustration decision; human/agent workflows, conversational worked examples, workshop facilitation, and scattered-input transformations require a fresh built-in image-generation call unless precise data must stay native. Never silently substitute reused artwork, CSS, SVG, or a hand-built diagram. Also runs in training mode: when the user says "training"/"訓練" or sends reference slides or images to learn from, do not build a deck - read the references for intention, trigger, layout logic and component craft, and register the pattern into specs/ so the planner can route to it next time.

Bonny Slide System — agent skill

When to use

Any time the user wants to make, fix, or critique slides/decks for UX or product work, bilingual 繁中 (primary) + English (supporting) — or wants to train the system by sending reference slides and images to learn from. Check which mode you are in before doing anything (next section).

How this skill is organized

• specs/ — the LLM-readable design system you READ each run. Source of truth for rules: foundations/ (color-discipline, themes-and-modes, typography, spacing-grid, layout-balance, iconography, imagery, generated-editorial-explainer, plain-language, storytelling, self-critique, source-sync, learn-from-image) · themes/ · tokens/ · components/ · layouts/ · slide-plan.md · content-map.md · audit.md · spec-template.md · _catalog.md · preferences.md (taste from A/B rounds).
• specs/generated-router.md — the complete intention→pattern index, compiled from every spec's intent + triggers frontmatter (machine form: system/router.json). This is the authoritative list of what exists; content-map.md is the narrative layer that adds detection heuristics and component pairings. Both are kept in sync by the compiler's --check, which fails on routing drift.
• system/ — canonical machine-readable tokens, 25 hypertokens, 44 connected catalog recipes, and JSON schemas. resolved-recipes.json records selectors and managed properties for every slot. Inspect one with python scripts/resolve_recipe.py <pattern> --theme light; see specs/tokens/recipes.md. migrationStatus is engineering metadata only and never affects component/layout selection.
• scripts/compile_system.py — the deterministic compiler. It generates CSS, the PPTX bridge, the router, and a Markdown reference; generated files are never edited by hand. --check fails on token and routing drift.
• specs/generated-class-coverage.md — which catalogued patterns can actually be built from assets/base.css, and which need classes that exist only inside their own example (machine form: system/class-manifest.json). A pattern with gaps has to be reinvented on every build, so treat its gaps as the implementation backlog. base.css stays hand-written — this is a usage contract, never codegen.
• scripts/sync_examples.py — keeps current examples on one theme plus the generated bundle, preserving authored <style data-slide> overrides. --check is part of the central check command. Reusable device/gallery styles are scoped to their layout; frozen _ab/_audit history is excluded unless --include-archives is explicitly requested.
• scripts/validate_layout.py — the layout gate. Renders a built slide and measures balance, distribution, and density against foundations/layout-balance.md, so those rules are enforced rather than merely described.
• assets/ — the CSS you BUILD with. base.css is the compatibility/component layer and imports the generated foundations + hypertokens + recipe bindings; load ONE generated theme file (tokens-light.css / tokens-dark.css). For self-contained HTML, inline the import-free generated assets/generated/base-bundle.css plus one theme.
• examples/ — rendered reference slides; examples/deck-demo/ + deck-demo-scroll.html = a full short deck showing how layouts chain (pacing, bridges, dividers). pptx/ — token-mirrored python bridge for .pptx.

Two modes — read the request before building anything

This skill runs in one of two modes. Decide which before doing any work.

The user says	Mode	What it means
"make a slide/deck", a topic, a source file	build	Produce slides. Follow the operating procedure below.
"training" / "訓練", or sends reference images or slides to learn from	training	Do not build a deck. Grow the library from what they sent.

Training mode is not slide-making. The user is teaching the system, so the output is a change to specs/, not a deck. Never answer a training request with a slide; never silently fold a sent image into a build. If the intent is ambiguous — an image arrives with no instruction — ask which one, because the two produce completely different artifacts.

Training mode procedure

1. Read each reference for all five things in specs/foundations/learn-from-image.md — intention, trigger, layout logic, component craft, and the intention↔component rationale. Structure only: colours are recorded as token roles, never hex. A reference in any language teaches STRUCTURE only — the deck's output language is a separate, declared decision (default 繁中 + English).
2. Dedupe against specs/_catalog.md → existing (add to learned_from) · variant (extend the spec) · new (create one from specs/spec-template.md).
3. Register it so it is actually reachable. A pattern the planner cannot find does not exist:
   • intent + triggers frontmatter on the spec — the router is compiled from these
   • a row in specs/_catalog.md and a row in specs/content-map.md, keyed on intention
   • a render-validated example, referenced by example:
4. Close the loop — run the gates. python scripts/compile_system.py --check must pass: it fails on a stable layout with no content-map.md row, an unresolvable depends_on, a duplicate trigger, or a trigger in a language the router does not match on. Then python scripts/validate_layout.py <example>.
5. Report what the system learned — the new/updated pattern, its intention, its triggers, and what will now route to it. The point of training is that the next deck reaches for it automatically.

Implementation debt is part of training. If the new pattern needs CSS, add it to assets/base.css — not only to the example. specs/generated-class-coverage.md tracks patterns whose CSS lives only in their example; those cannot be rebuilt by the agent and must be reinvented every time, which is how consistency drifts.

Operating procedure (every deck)

1. Inputs: audience/room; one theme (mode + accent) — ask if unstated; the content/source. Ask the user for any real assets the deck needs — screenshots, logos, photos, data (specs/foundations/imagery.md).

2. Load rules — the core set only, then more on demand. Reading everything before building cost ~168 KB and most of it did not apply to the slide in hand. Read these seven every time (~25 KB): storytelling · plain-language · spacing-grid · typography · color-discipline · themes-and-modes · layout-balance, plus the chosen specs/themes/<theme>.md. Lock the theme deck-wide. For taste read specs/generated-preferences-digest.md (3.6 KB), not the 51 KB preferences.md — open that only when a specific component decision turns on a worked round.

   Open the rest only when the trigger fires:

   read this	when
   layout-choice.md	the router leaves two or more candidates
   imagery.md	the user supplied real screenshots, photos or logos
   iconography.md	the slide uses icons
   generated-editorial-explainer.md	a page routed to the illustration/explainer route
   self-critique.md	the review pass, after the deck renders
   audit.md	the delivery check, at the end
   learn-from-image.md	training mode only — never during a build
   source-sync.md	the deck restates an external source of truth

   Nothing in the conditional set changes how a page is laid out; each governs a decision you may never face on a given deck. Reading it anyway is the single largest avoidable cost in a build.

3. Outline — structure first: turn the file into a page-by-page plan with specs/slide-plan.md (one claim per slide; order method → range → relationships → conclusion per ; place covers/section-covers/bridges). Run the editorial-explainer suitability gate after naming each intention. Save every yes/no decision in the deck's ; each record includes , , , and . — record it as and generate. Do not dodge it by swapping to a text-only layout; that turns a routing decision into a silent visual compromise. Covers, section covers, bridges, agenda and closing pages are always , reason — their job is punctuation, not explanation. A hard candidate may use only with an explicit precision override. An omitted decision is a build error.

Golden rules (never break)

• One theme per deck — color is a separate layer; layouts/components stay theme-agnostic.
• 4-color discipline — accent is the only chromatic color.
• 繁中 primary + English supporting by default — a deck in another language is fine when the user asks for one; declare it (validate_layout --lang). That is an output constraint, enforced at render time. Routing triggers are deliberately multilingual — 繁中, English and Korean — because intention does not change with the language it is written in, and much of this library was learned from Korean reference decks. Deleting that vocabulary deleted recognition, not risk.
• One claim per slide; plain-language titles; purposeful icons, one style.
• A generated editorial explainer must be genuinely generated. Canonical images are style reference only; CSS/SVG recreation, reference reuse, grayscale filtering, and contain-fit gutters fail.
• No silent illustration bypass. Every slide appears in illustration-plan.json; any gate: yes page must have a local fresh asset, built-in generator provenance, a valid variant, and matching HTML placement.
• Hard candidates are machine-checked. A hard candidate cannot use gate: no without an allowed precision override. Split mixed workflow + table pages into a generated overview and a native evidence slide.
• For a system/decision, show the reasoning before the conclusion.

Learning loop (gets smarter from the user's slides)

The user keeps sending reference slide images. Each one grows the library — follow specs/foundations/learn-from-image.md:

1. Read the intention, not just the look. For each image extract five things: its intention (the job it does to the audience), the trigger (what content should summon this layout next time), the layout logic, the component craft (how each component is shown), and the intention↔component rationale (why those components achieve the job).
2. Learn structure, not color. Color is a separate theme layer, so record colors only as token roles — never hex/px. Every learned pattern stays theme-agnostic and reusable under any theme.
3. Dedupe vs specs/_catalog.md → existing (add to learned_from) · todo (write it now) · variant (extend the spec) · new (create one via spec-template.md, filling intent, triggers, and the Intention & rationale section).
4. Register & reach it: update _catalog.md (learned_from: ImgN) and add/refresh a content-map.md row keyed on intention so the planner reaches for it when that intention recurs.
5. Audit + sync the new spec/example (audit.md, foundations/source-sync.md). More images → denser intention→layout map + rationale library → better autonomous planning and building.

Extending the system

• New component/layout → copy specs/spec-template.md, fill it, add a class to assets/base.css (or include inline CSS in the spec example), update specs/_catalog.md. todo items in the catalog are built by composing existing base.css primitives per their spec until a class exists.
• New theme → copy a specs/themes/*.md, keep the role names, one accent. Run audit.md.

Changelog

Version history lives in CHANGELOG.md — it is not needed at build time.