python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/smart-art.md

@@ -0,0 +1,75 @@
+# SmartArt text substitution (Phase 8)
+
+Full SmartArt creation is intentionally **out of scope** — the layout
+algorithms are proprietary and non-trivial to reverse-engineer.
+
+What `python-pptx2` *does* support is text substitution inside an
+*existing* template's SmartArt. The classic use case: a corporate
+org-chart template whose names need refreshing every quarter.
+
+## Iterating SmartArt on a slide
+
+```python
+prs = Presentation("org-chart-template.pptx")
+slide = prs.slides[0]
+
+for sa in slide.smart_art:
+    print("nodes:", sa.texts)
+```
+
+`slide.smart_art` is a `SmartArtCollection`. Each item is a
+`SmartArtShape` with:
+
+- `texts` — ordered list of node text strings
+- `set_text(values, *, strict=True)` — replaces node text in document
+  order without touching layout, style, or color parts
+
+## Replacing names
+
+```python
+slide.smart_art[0].set_text(["Alex", "Priya", "Sam", "Lin", "Jordan"])
+```
+
+By default `set_text` is `strict=True` and raises if `len(values)`
+doesn't match the number of nodes in the diagram. Pass
+`strict=False` to truncate / pad with the existing text instead:
+
+```python
+slide.smart_art[0].set_text(["Alex", "Priya"], strict=False)
+```
+
+## Round-trip
+
+`DiagramDataPart` and its sibling part classes are registered so the
+SmartArt `diagrams/data#.xml`, `layout#`, `quickStyle#`, and `colors#`
+parts are handled as typed `XmlPart` subclasses. Reads never mutate.
+
+## What this is not
+
+- **No creation.** You can't build a new SmartArt graphic from
+  scratch. Author it in PowerPoint as a template, then use this API to
+  refresh it.
+- **No structural edits.** Adding/removing nodes is not supported. The
+  list you pass to `set_text` must align with the existing nodes.
+- **No styling changes.** Color and quick-style parts are left alone.
+
+## End-to-end: refresh a quarterly org chart
+
+```python
+from pptx2 import Presentation
+
+prs = Presentation("org-chart-template.pptx")
+slide = prs.slides[0]
+
+names = [
+    "Alex Halwell",       # CEO
+    "Priya Shah",         # COO
+    "Sam Tucker",         # CFO
+    "Lin Chen",           # CTO
+    "Jordan Reyes",       # CRO
+    "Morgan Patel",       # CMO
+]
+slide.smart_art[0].set_text(names)
+
+prs.save("org-chart-2026q2.pptx")
+```

pptx2/skill/references/space-aware-authoring.md

@@ -0,0 +1,249 @@
+# Space-aware authoring
+
+This is the **headline reason `python-pptx2` exists**. Generated decks
+break in two predictable ways:
+
+1. Text overflows its container.
+2. Boxes sit off the slide.
+
+The library gives you three layered tools to prevent both — used in
+this order, they catch ~all real-world cases:
+
+1. **Pre-flight measurement** — choose a font size that fits *before*
+   committing the text.
+2. **Auto-fit on the text frame** — let PowerPoint shrink the font on
+   the way down if the text is dynamic.
+3. **The linter** — catch what slipped through, before save.
+
+Use all three. They compose. None of them require Microsoft PowerPoint
+to be installed.
+
+## 1. Pre-flight measurement: pick the right size up front
+
+`TextFrame.fit_text(...)` measures with Pillow font metrics and sets
+the largest whole-point font size that fits the box:
+
+```python
+from pptx2.util import Inches, Pt
+
+box = slide.shapes.add_textbox(Inches(1), Inches(2), Inches(8), Inches(1.5))
+tf = box.text_frame
+tf.text = dynamic_title
+
+# Largest whole-point size ≤ max_size that fits in the box's extents
+tf.fit_text(font_family="Inter", max_size=44, bold=True)
+```
+
+`fit_text` also sets `auto_size = MSO_AUTO_SIZE.NONE`, so PowerPoint
+won't second-guess the size at render time, and returns the point size
+it applied.
+
+### The guarantee is only as good as the font metrics
+
+**Read this before trusting `fit_text` with a brand font.** The fit is
+computed from the metrics of the font *on the machine running the
+build*. If the requested family isn't installed — the usual case for a
+display face like Instrument Serif or Inter inside a container or CI
+runner — measurement silently falls back to Pillow's bundled default
+font. You still get a number, and it's usually in the right
+neighbourhood, but it is an **estimate**: a wider real face can still
+overflow the box.
+
+python-pptx2 makes that visible rather than silent:
+
+```python
+from pptx2.text.fonts import font_is_installed, installed_font_families
+
+font_is_installed("Inter", bold=True)   # -> False in most containers
+installed_font_families()               # what this machine can actually measure
+```
+
+* Naming a family that isn't installed emits a `FontMetricsWarning`.
+  Omitting the argument does not — no particular face was asked for —
+  but passing `"Calibri"` explicitly does, because that's a request
+  like any other.
+* `strict=True` turns any fallback into a `ValueError`, so a build that
+  must be exact fails loudly instead of shipping a guess.
+
+Three ways to keep the guarantee, best first:
+
+```python
+# 1. Ship the metrics with the build — exact, works anywhere
+tf.fit_text("Instrument Serif", max_size=44,
+            font_file="fonts/InstrumentSerif-Regular.ttf")
+
+# 2. Fail the build rather than ship an estimate
+tf.fit_text("Inter", max_size=24, strict=True)
+
+# 3. Degrade deliberately to a family you know is present
+family = "Inter" if font_is_installed("Inter") else "DejaVu Sans"
+tf.fit_text(family, max_size=24)
+```
+
+When none of those apply, treat the display-font sizes as
+hand-tunable and verify with a real render
+(`pptx2.render.render_slides`, needs LibreOffice). Note that
+`slide.lint()` is **not** affected — its overflow check uses a
+font-agnostic character-width heuristic — which is why layer 3 below
+still earns its keep when the metrics are approximate.
+
+For finer control (e.g. you want to size text *for* a known box but
+leave styling to a recipe), use the underlying fitter directly:
+
+```python
+from pptx2.text.layout import TextFitter
+
+best_pt = TextFitter.best_fit_font_size(
+    text="Q4 2026 Customer Outcomes Review",
+    extents=(Inches(8), Inches(1.5)),
+    max_size=44,
+    font_file="/usr/share/fonts/truetype/inter/Inter-Bold.ttf",
+)
+```
+
+`best_fit_font_size` returns an int point size; the caller decides what
+to do with it.
+
+## 2. Auto-fit: let PowerPoint shrink at render time
+
+When the text isn't fully known at authoring time (or you want
+PowerPoint to adapt as the user edits the deck), set
+`text_frame.auto_size`:
+
+```python
+from pptx2.enum.text import MSO_AUTO_SIZE
+
+# Shrink the text to fit
+tf.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
+
+# Or grow the shape to fit the text
+tf.auto_size = MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT
+
+# Or do nothing (the default — overflowing text is just clipped)
+tf.auto_size = MSO_AUTO_SIZE.NONE
+```
+
+`TEXT_TO_FIT_SHAPE` is the right default for headline / KPI / bullet
+cards where the box geometry is fixed and the text is dynamic.
+`SHAPE_TO_FIT_TEXT` is the right default for body copy where the box
+should grow vertically.
+
+> ⚠ `auto_size` is rendered by PowerPoint itself — `python-pptx2` only
+> writes the flag.  If you want determinism (CI screenshots, PDF
+> export pipelines), prefer `fit_text` so the size is baked into the
+> XML.
+
+## 3. The linter: catch what slipped through
+
+Run `slide.lint()` before save. It uses Pillow font metrics so it
+catches overflow even on auto-fit text frames, and it knows the slide's
+real dimensions so off-slide shapes are caught regardless of slide
+size:
+
+```python
+from pptx2.lint import OffSlide, TextOverflow, ShapeCollision
+from pptx2.exc import LintError
+
+errors = []
+for slide in prs.slides:
+    report = slide.lint()
+
+    # Cheap auto-fix first (currently nudges off-slide shapes back in)
+    report.auto_fix()
+
+    # Re-collect what's left
+    for issue in slide.lint().issues:
+        if issue.severity.value == "error":
+            errors.append(issue)
+
+if errors:
+    raise LintError("; ".join(str(e) for e in errors))
+
+prs.save("out.pptx")
+```
+
+For decks built through `pptx2.compose.from_spec(...)`, fold the linter
+into the spec itself:
+
+```python
+prs = from_spec({
+    "slides": [...],
+    "lint": "raise",          # also "warn", "off"
+})
+```
+
+## Putting it together: a robust headline
+
+```python
+from pptx2 import Presentation
+from pptx2.enum.text import MSO_AUTO_SIZE
+from pptx2.util import Inches
+
+def add_headline(prs, slide, text):
+    box = slide.shapes.add_textbox(
+        Inches(0.6), Inches(0.4),
+        Inches(prs.slide_width.inches - 1.2), Inches(1.2),
+    )
+    tf = box.text_frame
+    tf.word_wrap = True
+    tf.text = text
+
+    # 1. Pre-flight size pass — bakes a determined size into the XML
+    tf.fit_text(font_family="Inter", max_size=44, bold=True)
+
+    # 2. Belt-and-braces: if the user later types more, PowerPoint
+    #    will shrink rather than overflow.
+    tf.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
+
+    return box
+
+# 3. Linter as the safety net at save time
+for slide in prs.slides:
+    slide.lint().auto_fix()
+
+prs.save("headline.pptx")
+```
+
+## Geometry helpers — never hand-place EMUs
+
+Off-slide shapes nearly always come from arithmetic mistakes when
+positioning. Use the design layer's `Grid` and `Stack` instead of
+adding `Inches(...)`s by hand:
+
+```python
+from pptx2.design.layout import Grid, Stack
+from pptx2.util import Pt
+
+# 12-column grid with a uniform gutter and outer margin
+grid = Grid(slide, cols=12, rows=6, gutter=Pt(12), margin=Pt(48))
+grid.place(card1, col=0, row=0, col_span=6, row_span=4)
+grid.place(card2, col=6, row=0, col_span=6, row_span=4)
+
+# Vertical cursor with a known total width
+stack = Stack(direction="vertical", gap=Pt(8),
+              left=Pt(48), top=Pt(48), width=Pt(600))
+stack.place(title, height=Pt(64))
+stack.place(body,  height=Pt(280))
+```
+
+Both compute geometry from the slide's actual dimensions, so you can't
+accidentally walk off the right edge — and they're pure arithmetic
+(no XML reads or writes) until `place()` is called.
+
+## Why not just slap `auto_size = SHAPE_TO_FIT_TEXT` on everything?
+
+It's tempting, but it fights with the design. A "Customer impact"
+title that grows to two lines pushes the body content down, which
+might collide with a chart, which the linter then flags. The chain
+keeps moving the failure further from the cause.
+
+The robust pattern is:
+
+- **Fixed geometry, fixed font size** for branded slides where the
+  designer made a deliberate choice. Use `fit_text` to *verify* the
+  size still fits when content is dynamic.
+- **`TEXT_TO_FIT_SHAPE`** as the catch-all for headlines / KPI cards.
+- **`SHAPE_TO_FIT_TEXT`** only when the slide is a "wall of text" type
+  where vertical growth is acceptable.
+- **Linter at the end**, always — it's the only thing that sees the
+  *whole* slide instead of one shape at a time.

pptx2/skill/references/tables.md

@@ -0,0 +1,244 @@
+# Tables
+
+Most of the table API is unchanged from upstream `python-pptx`. The
+post-fork additions are `cell.format(...)` / `table.format_cells(...)`
+styling, `Cell.borders`, and `Table.fit_to_box` — reach for those before
+dropping to raw fill/font mutation.
+
+## Adding a table
+
+```python
+from pptx2.util import Inches, Pt
+from pptx2.dml.color import RGBColor
+
+shape = slide.shapes.add_table(
+    rows=4, cols=3,
+    left=Inches(1), top=Inches(2),
+    width=Inches(8), height=Inches(3),
+)
+table = shape.table
+```
+
+## Headers and cell text
+
+```python
+HEADERS = ["Metric", "Value", "Δ QoQ"]
+for col, label in enumerate(HEADERS):
+    table.cell(0, col).text = label
+
+ROWS = [
+    ("ARR",         "$182M", "+27%"),
+    ("NDR",         "131%",  "+3%"),
+    ("CAC payback", "8 mo",  "−1 mo"),
+]
+for r, row in enumerate(ROWS, start=1):
+    for c, value in enumerate(row):
+        table.cell(r, c).text = value
+```
+
+## Column widths and row heights
+
+```python
+table.columns[0].width = Inches(3.5)
+table.columns[1].width = Inches(2.5)
+table.columns[2].width = Inches(2.0)
+
+table.rows[0].height = Inches(0.6)
+for r in range(1, len(table.rows)):
+    table.rows[r].height = Inches(0.5)
+```
+
+## Styling cells: `format` and `format_cells`
+
+`cell.format(...)` sets fill and text styling in one call, using the
+same keyword vocabulary as `slide.shapes.add_text(...)`. Every argument
+is optional and `None` means "leave alone", so calls layer:
+
+```python
+table.cell(0, 0).format(
+    fill="#1F2937",        # hex / (r, g, b) / RGBColor — or "none"
+    color="#FFFFFF",       # text colour
+    font="Inter",
+    size_pt=12,
+    bold=True,
+    italic=False,
+    align="center",        # left / center / right / justify
+    anchor="middle",       # top / middle / bottom
+    margin=(2, 8, 2, 8),   # points: scalar, or (top, right, bottom, left)
+    word_wrap=True,
+)
+```
+
+`table.format_cells(rows=..., cols=..., ...)` applies the same keywords
+across a selection. `rows` / `cols` each accept `None` (all), an `int`
+(negative counts from the end), a `slice`, or any iterable of indices —
+so a whole table's look is a handful of calls:
+
+```python
+table.format_cells(rows=0, fill="#1F2937", color="#FFFFFF", bold=True)
+table.format_cells(rows=slice(1, None), size_pt=11, anchor="middle")
+table.format_cells(rows=range(2, len(table.rows), 2), fill="#F6F7F9")  # banding
+table.format_cells(cols=-1, align="right")                            # numbers
+```
+
+Both return the cell / table, so they chain. Spanned (merged-away)
+cells are skipped; style the merge origin instead.
+
+Either order works — style an empty header row and then assign
+`cell.text`, or populate first and style afterwards. The formatting is
+recorded as the cell's text-body defaults (`<a:lstStyle>`) as well as on
+its current runs, and a text replacement leaves those defaults alone.
+
+> A cell's vertical anchor and insets live on `<a:tcPr>`, not on its
+> text frame's `<a:bodyPr>` — PowerPoint reads the cell properties and
+> ignores the body ones. `format(anchor=..., margin=...)` writes them to
+> the right place; setting `cell.text_frame.vertical_anchor` does not.
+
+The low-level surface is still there when you need it
+(`cell.fill.solid()`, `cell.vertical_anchor = MSO_VERTICAL_ANCHOR.MIDDLE`,
+per-run `font` objects) — `format` just removes the loop.
+
+## Built-in banding and header toggles
+
+Before hand-styling every cell, check whether the table style already
+does it. These six booleans drive the banding and emphasis that the
+applied table style defines, so one flag replaces a loop:
+
+```python
+tbl.first_row   = True    # emphasise the header row
+tbl.last_row    = False   # emphasise a totals row
+tbl.first_col   = True    # emphasise the label column
+tbl.last_col    = False
+tbl.horz_banding = True   # alternating row shading
+tbl.vert_banding = False  # alternating column shading
+```
+
+`banded_rows` / `banded_cols` are aliases for the two banding flags.
+They only have a visible effect when the table still carries a style
+that defines banded formatting — see the next section.
+
+## Walking every cell
+
+`iter_cells()` flattens the grid so you don't nest two loops, and it
+skips nothing:
+
+```python
+for cell in tbl.iter_cells():
+    cell.margin_left = Inches(0.08)   # also margin_right/top/bottom
+```
+
+Merged regions need care when reading: a merged block reports one
+*origin* cell plus the cells it swallowed.
+
+```python
+cell = tbl.cell(0, 0)
+cell.is_merge_origin   # True on the top-left cell of a merged block
+cell.is_spanned        # True on the cells the merge absorbed
+cell.span_height       # rows covered (1 when unmerged)
+cell.span_width        # columns covered
+```
+
+Write text to the *origin* cell; a spanned cell's text is not rendered.
+
+## Detaching the default table style
+
+Every table created via `slide.shapes.add_table(...)` is born with
+the "Medium Style 2 — Accent 1" `tableStyleId` attached. The style
+ships a banded-row overlay that PowerPoint and LibreOffice render
+on top of any per-cell fills you set — and that overlay survives
+`table.horz_banding = False` and `table.first_row = False`, because
+those flags only suppress `bandRow` / `firstRow` markup, not the
+style's own banding rules.
+
+When you want full control of every cell's appearance, detach the
+default style outright:
+
+```python
+table.clear_style()                       # drops <a:tableStyleId>
+table.format_cells(fill="#FFFFFF")        # now every cell is yours
+```
+
+## Cell borders (Phase 4 — post-fork addition)
+
+`cell.borders` exposes per-edge `LineFormat` proxies plus convenience
+helpers. Backed by the OOXML `a:lnL/lnR/lnT/lnB/lnTlToBr/lnBlToTr`
+children of `a:tcPr`.
+
+### Per-edge
+
+```python
+cell.borders.left.color.rgb       = RGBColor(0xE5, 0xE7, 0xEB)
+cell.borders.left.width           = Pt(0.5)
+cell.borders.bottom.color.rgb     = RGBColor(0x1F, 0x29, 0x37)
+cell.borders.bottom.width         = Pt(1.5)
+cell.borders.diagonal_down.color.rgb = RGBColor(0xEF, 0x44, 0x44)
+```
+
+### All edges in one call
+
+```python
+cell.borders.all(width=Pt(0.5), color=RGBColor(0xE5, 0xE7, 0xEB))
+cell.borders.outer(width=Pt(1.0), color=RGBColor(0x1F, 0x29, 0x37))
+cell.borders.none()                # clears every edge
+```
+
+### Zebra-striped borders pattern
+
+```python
+LIGHT = RGBColor(0xE5, 0xE7, 0xEB)
+DARK  = RGBColor(0x1F, 0x29, 0x37)
+
+# Header row — bottom edge dark
+for col in range(len(HEADERS)):
+    table.cell(0, col).borders.bottom.color.rgb = DARK
+    table.cell(0, col).borders.bottom.width     = Pt(1.5)
+
+# Body rows — light row separator
+for r in range(1, len(table.rows)):
+    for c in range(len(HEADERS)):
+        cell = table.cell(r, c)
+        cell.borders.bottom.color.rgb = LIGHT
+        cell.borders.bottom.width     = Pt(0.5)
+```
+
+## Reading borders
+
+Reads on an unset edge return a `LineFormat` without mutating the XML.
+Be careful with the falsy check: an unset `width` reads back as `Emu(0)`,
+**not** `None`, so `is None` never fires:
+
+```python
+if not cell.borders.bottom.width:      # unset reads Emu(0), never None
+    print("inherits border from style")
+```
+
+## Rotated / stacked cell text
+
+Use `cell.text_direction` for matrix-style or rotated column headers:
+
+```python
+cell.text_direction = "rotate90"    # "horizontal" (default), "rotate90",
+cell.text_direction = "stacked"     # "rotate270", "stacked"
+cell.vertical_anchor = MSO_ANCHOR.MIDDLE   # t / ctr / b within the cell
+```
+
+Reading returns the friendly string (`"horizontal"` when unset); assigning
+`"horizontal"` or `None` clears it. Maps to `<a:tcPr vert="…">` /
+`anchor="…"` — schema-valid and round-trip clean.
+
+## Built-in table styles
+
+Apply any of PowerPoint's ~70 built-in table styles by name or GUID:
+
+```python
+table.style = "Medium Style 2 - Accent 1"      # friendly name
+table.style = "Table Grid"
+table.style = "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}"  # raw GUID also OK
+print(table.style)        # -> friendly name (or raw GUID / None)
+table.style = None        # detach (same as table.clear_style())
+```
+
+Discover valid names via `from pptx2.table_styles import TABLE_STYLES`.
+An unknown name raises `ValueError` with a "did you mean" suggestion.
+Writing just the style GUID is schema-valid — nothing is added to
+`tableStyles.xml`.

pptx2/skill/references/theme.md

@@ -0,0 +1,127 @@
+# Themes (Phase 6 + 7)
+
+`Presentation.theme` returns a `Theme` proxy that's both readable and
+writable. Theme parts are loaded as a typed `ThemePart(XmlPart)` so
+writes round-trip on save.
+
+## Reading the palette
+
+```python
+from pptx2.enum.dml import MSO_THEME_COLOR
+
+accent1 = prs.theme.colors[MSO_THEME_COLOR.ACCENT_1]    # → RGBColor
+accent2 = prs.theme.colors[MSO_THEME_COLOR.ACCENT_2]
+bg1     = prs.theme.colors[MSO_THEME_COLOR.BACKGROUND_1]    # canonical lt1
+text1   = prs.theme.colors[MSO_THEME_COLOR.TEXT_1]          # canonical dk1
+hyper   = prs.theme.colors[MSO_THEME_COLOR.HYPERLINK]
+follow  = prs.theme.colors[MSO_THEME_COLOR.FOLLOWED_HYPERLINK]
+```
+
+The six accent slots, the dk1/dk2/lt1/lt2 background slots, and the
+hyperlink slots are addressable.
+
+## Reading fonts
+
+```python
+major = prs.theme.fonts.major     # heading font (str)
+minor = prs.theme.fonts.minor     # body font  (str)
+```
+
+## Writing the palette
+
+```python
+from pptx2.dml.color import RGBColor
+
+prs.theme.colors[MSO_THEME_COLOR.ACCENT_1] = RGBColor(0x4F, 0x9D, 0xFF)
+prs.theme.colors[MSO_THEME_COLOR.ACCENT_2] = RGBColor(0x10, 0xB9, 0x81)
+```
+
+Alias slots (`BACKGROUND_1` / `BACKGROUND_2` / `TEXT_1` / `TEXT_2`)
+resolve to their canonical `lt1` / `lt2` / `dk1` / `dk2` target.
+
+## Writing fonts
+
+```python
+prs.theme.fonts.major = "Inter"
+prs.theme.fonts.minor = "Inter"
+```
+
+Rewrites the `<a:majorFont>/<a:minorFont>/<a:latin typeface=…/>`
+typeface.
+
+## Bulk-copy from another theme
+
+```python
+brand = Presentation("brand.potx")
+prs.theme.apply(brand.theme)        # copies palette + major/minor fonts
+```
+
+## Theme-aware color resolution
+
+`pptx2.inherit.resolve_color` returns the effective `RGBColor` for any
+`ColorFormat` (or the lazy proxy on `Font.color` / `LineFormat.color`).
+Explicit RGB values are returned as-is, scheme colors resolve through
+the theme, and unset colors return `None` without mutating XML:
+
+```python
+from pptx2.inherit import resolve_color
+
+rgb = resolve_color(run.font.color, theme=prs.theme)
+if rgb is None:
+    print("inherits from layout/master")
+else:
+    print("effective color:", rgb)
+```
+
+`brightness` is honoured by blending toward white or black, mirroring
+PowerPoint's `lumMod` / `lumOff` model.
+
+> ⚠ Full placeholder-walking (`slide → layout → master`) is *not*
+> implemented; this resolver covers the 80% case (theme-color lookup)
+> without touching XML.
+
+## End-to-end: rebrand a deck
+
+```python
+from pptx2 import Presentation
+from pptx2.dml.color import RGBColor
+from pptx2.enum.dml import MSO_THEME_COLOR
+
+prs = Presentation("input.pptx")
+
+# Punchy palette
+prs.theme.colors[MSO_THEME_COLOR.ACCENT_1] = RGBColor(0xFF, 0x66, 0x00)
+prs.theme.colors[MSO_THEME_COLOR.ACCENT_2] = RGBColor(0x12, 0x1E, 0x4D)
+prs.theme.colors[MSO_THEME_COLOR.HYPERLINK] = RGBColor(0x12, 0x1E, 0x4D)
+
+# Inter everywhere
+prs.theme.fonts.major = "Inter"
+prs.theme.fonts.minor = "Inter"
+
+prs.save("rebranded.pptx")
+```
+
+Anything in the deck that referenced `accent1` / `accent2` /
+`majorFont` / `minorFont` will pick up the new values automatically.
+
+## Dark mode & palette-from-seed
+
+Flip a deck to a dark palette in one call (backgrounds/text invert,
+accents stay AA-legible):
+
+```python
+prs.theme.to_dark_mode()                 # in place; returns the Theme
+prs.theme.to_dark_mode(min_contrast=7.0) # AAA accents
+```
+
+Bootstrap a whole palette from one brand colour:
+
+```python
+from pptx2.design.tokens import DesignTokens
+
+tokens = DesignTokens.from_seed("#3B5BDB", harmony="triadic")
+tokens.palette["primary"]                          # == the seed
+tokens.validate_color_blindness("deuteranopia")    # -> [(name_a, name_b), ...]
+```
+
+`from_seed` is deterministic and accepts hex / `RGBColor` / `(r, g, b)`.