skilldrop-cli 1.1.3 → 1.2.0

package/packs/design/skills/deck-builder/reference.md

@@ -1,180 +0,0 @@
-# deck-builder — design reference
-
-## Color palette principles
-
-A presentation palette needs five roles. If the user gives you fewer than five colors, derive the missing ones following these rules:
-
-| Role | Where it's used | Picking rule |
-|---|---|---|
-| **primary** | Title bars, section dividers, big-number captions | The user's brand colour, or the dominant colour in their material |
-| **secondary** | Sparingly — second-tier emphasis, alt charts | Analogous or complementary to primary; ~30° apart on the wheel |
-| **accent** | Highlight bars, the actual big numbers, quote bars | High-saturation pop colour; should NOT match background or primary |
-| **background** | Slide background | Near-white (#FFFFFF or #F8F9FA) for most decks; near-black for dark-mode decks |
-| **text** | Body text, bullet text | ≥ 4.5:1 contrast against background. Default `#222222` on white, `#EAEAEA` on dark |
-
-### Hard rules
-
-- **Contrast ≥ 4.5:1** between text and background (WCAG AA). If the user-supplied palette fails this, *substitute* and explain — don't ship an unreadable deck.
-- **Never put primary text on primary background** — use white-on-primary or vice versa for title bars/section slides.
-- **Accent appears on ≤ 20% of slides.** It's a pop colour, not a body colour.
-
-### Preset palettes
-
-These are bundled in [`templates/palettes.json`](templates/palettes.json) and selectable by name:
-
-| Name | When to use |
-|---|---|
-| `corporate-blue` | Default for B2B / enterprise audiences when no brand colour is given |
-| `monochrome` | When the deck needs to feel restrained / when content is sensitive |
-| `vibrant` | Internal / sales / pitch decks — energetic |
-| `dark-mode` | Engineering audiences who prefer dark, or for live demos |
-| `editorial` | Long-form / read-ahead decks with lots of text |
-| `forest` | Calm, nature-leaning — sustainability, long-horizon programmes |
-| `sunset` | Warm, narrative-leaning — story-first sales and internal decks |
-
-## Layout → content matching
-
-The biggest deck-design mistake is "everything is a bulleted content slide". Use this mapping to pick the right layout for the content:
-
-| Content shape | Right layout | Wrong layout |
-|---|---|---|
-| One key takeaway you want to land | `big_number` | `content` (gets lost in bullets) |
-| A list of 2–6 related points | `content` | `two_column` (over-engineered) |
-| A comparison (us vs. them, before vs. after) | `two_column` | `content` with sub-bullets |
-| A pithy customer / SME quote | `quote` | `content` ("Customer says…") |
-| 3+ comparable figures over time or category | `chart` | `content` with numbers in bullets |
-| Row-and-column data, ≤ 12 rows | `table` | `two_column` faked with aligned bullets |
-| An architecture / flow / screenshot | `image` | describing the diagram in prose |
-| A topic break / new section | `section` | another title slide |
-| First slide | `title` | jumping straight into `content` |
-| Final slide with The Ask | `closing` | `content` titled "Thank you" |
-
-## Per-audience density rules
-
-How many bullets a slide can carry without falling apart, by audience:
-
-| Audience | Bullets / slide | Words / bullet | Slide-title style |
-|---|---|---|---|
-| `exec` | 3 max | ≤ 8 | Assertion ("Postgres meets latency target") |
-| `board` | 3 max | ≤ 6 | Outcome ("$24M ARR protected by Q3") |
-| `technical` | 5–6 | ≤ 14 | Descriptive ok ("Migration approach") |
-| `sales` | 3–4 | ≤ 10 | Benefit-led ("Cut close time by 40%") |
-| `internal` | 4–5 | ≤ 12 | Topic ok ("Q3 priorities") |
-| `investor` | 3–4 | ≤ 10 | Assertion + number where possible |
-| `partner` | 3–4 | ≤ 10 | Mutual benefit ("Joint customers see X") |
-| `customer` | 3–4 | ≤ 12 | Outcome for them ("You'll save…") |
-
-## Slide-count budgets
-
-| Audience / format | Slide count target | Hard upper bound |
-|---|---|---|
-| `exec` quick update (5 min) | 5 | 8 |
-| `exec` decision review (15 min) | 8–10 | 12 |
-| `board` quarterly (20 min) | 10 | 15 |
-| `technical` design review (30 min) | 12–15 | 20 |
-| `sales` first pitch (15 min) | 8 | 12 |
-| `investor` Series-style | 10–12 | 15 |
-| `internal` team alignment | 5–8 | 10 |
-
-If the user's content can't fit in the upper bound, *say so* — recommend splitting into two decks rather than cramming.
-
-## Speaker notes patterns
-
-Every slide should have notes. The pattern that works:
-
-1. **Hook sentence** — what the presenter opens with on this slide.
-2. **Key emphasis** — which bullet/number to dwell on.
-3. **Transition** — one sentence that flows into the next slide.
-
-Speaker notes should be *what's not on the slide*, not a redundant copy.
-
-## Common gotchas
-
-- **Don't centre body text.** Centred bullets are harder to scan. Reserve centring for `big_number`, `quote`, and `title`/`closing` slides.
-- **Don't underline links** — coloured-and-bold is the modern convention.
-- **Don't use both italic and bold** in the same sentence for emphasis.
-- **Don't mix serif and sans-serif** unless you really know what you're doing.
-- **Slide numbers** — include them for decks > 10 slides; omit for short decks.
-
-## Brand templates
-
-A template is inherited, not imitated: `template` points the build at a `.pptx` or `.potx`, and
-the deck is generated on that file's masters, theme fonts, theme colours, logos and slide size.
-Sample slides shipped inside the template are dropped; its layouts are kept.
-
-### The layout map
-
-`layout_map` binds each logical layout to one of the template's layout names (or its index).
-Discover them with `--list-layouts`. Matching is exact name first, then case-insensitive, then
-substring — so `"content": "Title and Content"` and `"content": "title and content"` both hit.
-
-| Logical layout | What to map it to | If unmapped |
-|---|---|---|
-| `title` | The template's title/cover layout | Built-in cover — **loses the brand**, always map it |
-| `section` | Section header / divider | Built-in divider — always map it |
-| `content` | Title and content / title and bullets | Built-in — always map it |
-| `two_column` | Two content / comparison | Built-in two-column; acceptable |
-| `closing` | Closing / thank-you / title-only | Built-in — always map it |
-| `image` | Picture with caption (best), else title-only | Image drawn into the content area |
-| `big_number`, `quote`, `table`, `chart` | Title-only | Drawn into the claimed content area; fine |
-
-Placeholders are filled, not replaced — the run keeps the template's font, so the deck inherits
-the brand's typography instead of Calibri. Placeholders left unfilled are deleted, so no
-"Click to add text" ghosts survive. For `big_number`, `quote`, `table`, `chart` and `image`, the
-largest empty body (or picture) placeholder is claimed for its rectangle and removed, so custom
-content lands where the template intended content to go.
-
-### Template gotchas
-
-- **Slide size comes from the template.** `aspect` is ignored, with a warning. A 4:3 corporate
-  master produces a 4:3 deck — tell the user rather than silently letting it look cramped.
-- **Charts and tables are drawn, not templated.** They take palette colours, not theme colours.
-  Supply brand hexes alongside the template so they match.
-- **Slide numbers:** if the template's master already stamps them, the script does not add its
-  own.
-- **A template that fails to open** is a hard error, never a silent fall-back to the built-in
-  design — a deck that quietly lost its branding is worse than a failed build.
-
-## Charts
-
-`chart` types: `column`, `bar`, `line`, `stacked_column`, `stacked_bar`, `pie`, `doughnut`.
-
-| Question the slide answers | Type |
-|---|---|
-| How does this compare across categories? | `column` (≤ 7 categories) or `bar` (longer labels) |
-| How has this moved over time? | `line` |
-| What is the mix of a whole? | `pie`, and only with ≤ 5 slices |
-| How does the mix change across categories? | `stacked_column` |
-
-### Hard rules
-
-- **Every chart carries a `takeaway`** — the sentence the audience should leave with, above the
-  plot. A chart without one makes the audience do the analysis live.
-- **Every chart carries a `source`.** No source means the number is unverifiable, which on a
-  board deck means it is indefensible.
-- **Never chart invented numbers.** If the user supplied three figures, chart three figures.
-  A forecast is labelled a forecast, in the series name.
-- **`null` is the right value for a gap.** Padding a short series with zeroes draws a cliff that
-  didn't happen.
-- **Pie charts cap at 5 slices.** More than that, use `bar` sorted descending.
-- **One chart per slide.** Two charts is two slides, or a `two_column` with the takeaway split.
-
-## Tables
-
-- **≤ 12 data rows.** Past that it belongs in the appendix or an attached spreadsheet.
-- **≤ 5 columns** at 16:9, ≤ 4 at 4:3. Wider than that and the font drops below readable.
-- **Put the column the audience cares about last or first**, never buried in the middle.
-- **Cells are values, not sentences.** A table cell running to two lines means the content is
-  prose and wants a `content` slide.
-- Font size auto-shrinks past 7 and past 10 rows; header row takes `primary`, body rows zebra
-  against `#F2F4F8`.
-
-## Images
-
-- **Raster only.** `python-pptx` reads PNG/JPG/GIF/BMP/TIFF. SVG, EMF and PDF raise on import —
-  export to PNG at 2× the slide size before building.
-- **Relative paths resolve against the spec file**, not the working directory.
-- `position: "left"` / `"right"` pairs the image with bullets on the other half;
-  `"full"` (default) gives it the whole content area.
-- A missing or unreadable image draws a bordered placeholder box naming the file, and warns.
-  That box is a build artefact, never a deliverable — resolve it before the deck is presented.

package/packs/design/skills/deck-builder/requirements.txt

@@ -1,3 +0,0 @@
-# Pinned, not ranged: an open range lets a future release install itself unreviewed.
-# python-pptx 1.0.2 requires Python >= 3.8.
-python-pptx==1.0.2