A theme is one file, and the deck's settings are named as the deck's

content/command-line/theme.md

@@ -27,24 +27,52 @@ mdoffice theme deck.pptx                # the same run: init is the default
 The directory is the deck's own name without its extension, so `deck.pptx` gives `deck/` and
 `talks/talk.pptx` gives `talks/talk/`.
 
-**A theme that is already there is not replaced without being asked.** A theme is a directory of
-files somebody has edited, and replacing one is how an afternoon of work goes missing:
+**A theme that is already there is not replaced without being asked.** The theme's own files are
+in a directory somebody has edited, and replacing one is how an afternoon of work goes missing:
 
 ```text
 mdoffice theme: There is already a theme in "deck".
 mdoffice theme:   Pass --force to replace it.
 ```
 
+**A directory that holds a file of the old format is not written into.** A theme is one file,
+and the library refuses a theme that has a `layouts.yml`, a `text-styles.yml` or a `styles.yml`
+beside it — so a theme written into such a directory is a theme no deck can be drawn in. The
+command says so before it writes, and `--force` does not help: it says a theme is to be
+replaced, not that a file is to be deleted.
+
+```text
+mdoffice theme: The theme "deck" has a "layouts.yml" beside it. A theme is one file: move its content into the "layouts:" section of its "theme.yml", and delete the file.
+mdoffice theme:   The command will not write a theme beside a file of the old format.
+mdoffice theme:   Delete it, or move it out of the way.
+```
+
+**A theme the command wrote before no longer works.** It wrote three files — `theme.yml`,
+`layouts.yml` and `template.pptx` — and a theme with a `layouts.yml` beside it is a theme the
+library refuses. Move the content of the `layouts.yml` into the `layouts:` section of the
+`theme.yml` beside it, and delete the file.
+
 ## What is written
 
-Three files go into the directory.
+Two files go into the directory.
 
 | File | Holds |
 | --- | --- |
-| `theme.yml` | the colours, the fonts and the type scale |
-| `layouts.yml` | the layout roles, each pointed at a layout of the deck |
+| `theme.yml` | the colours, the fonts, the type scale and the layout roles |
 | `template.pptx` | the deck's own layouts, without its slides |
 
+A deck with no master has no template to write, so the directory holds the theme's file alone.
+
+**Every role is mapped.** The roles the deck's own layouts cover are named the deck's way, and
+the rest take the library's own names — the names the library draws the layouts it generates
+under. A theme's `layouts:` section is the whole mapping, so a role it leaves out is a role no
+slide can be drawn on. The roles the deck has no layout for are listed in the report, so that
+somebody can point them somewhere else, but they are mapped all the same.
+
+**Two roles may not share a name.** A name is one layout, and two roles on one name are drawn in
+the same geometry. A role whose library name is already the name of one of the deck's own layouts
+takes a name of its own instead, and the report says which role and why.
+
 **The theme is read back before the command reports success.** The library's own reader reads it
 and the library's own geometry reads the boxes of the template, so a theme this command cannot
 read is a failure here rather than a theme nobody can use.
@@ -61,8 +89,8 @@ largest type on the first slide, the body the size the prose is written at, and
 scale the sizes below the title.
 
 **The layouts** are mapped by the placeholders they hold, not by their names: a deck calls its
-layouts whatever it likes, and the same layout is called different things in two offices. A role
-the deck has no layout for is reported rather than pointed at a layout that is something else.
+layouts whatever it likes, and the same layout is called different things in two offices. The
+roles the deck has no layout for take the library's own names, and are listed in the report.
 
 **The template** is the deck's layouts without its slides, and without the pictures on them. A
 template places, and the slides of the deck it came from are not a placement.
@@ -79,15 +107,64 @@ the file can be told apart from the numbers somebody chose.
 The command says what it read and where it read it from:
 
 ```text
-mdoffice theme: wrote the theme for "deck.pptx" into "deck".
+mdoffice theme: wrote the theme for "probe.pptx" into "/tmp/probe-theme".
 
-  theme.yml     the colours, the fonts and the type scale
-  layouts.yml   1 of the 8 layout roles mapped
-  template.pptx the deck's 1 layouts, without its 3 slides
+  theme.yml     the colours, the fonts, the type scale and the layout roles
+  template.pptx the deck's 3 layouts, without its 2 slides
 
   colours
-    dk1        #000000   the type
-    lt2        #000000   a filled block
+    dk1        #0D1B2A   the background of the slides
+    lt1        #F8FAFC   the type
+    accent1    #00B4D8   the colour the deck draws with
+    hlink      #00B4D8   the accent, as a link is drawn
+
+  type
+    heading        Cambria                  the face of the type at the title size
+    body           Calibri                  the face the deck writes its prose in
+    title          26pt                     the largest type on most of the slides
+    cover          26pt                     the largest type on the first slide
+    section        26pt                     the title on a slide that carries little else
+    body size      14pt                     the size the deck writes its prose at
+    headings       14pt                     the sizes below the title
+    leading        1.0                      the line spacing the deck sets
+    heading weight regular                  the weight of the headings
+    heading ink    ink                      the colour the headings are drawn in
+
+  roles
+    title       Titelfolie                 a title and a subtitle
+    content     Titel und Inhalt           a title and one column
+    two-column  Two Content                the library's own name
+    section     Section Header             the library's own name
+    blank       Leer                       nothing in it at all
+    image-text  Picture Left               the library's own name
+    image-title Picture with Caption       the library's own name
+    image-slide Full Bleed Picture         the library's own name
+
+  the deck's own layouts map 3 of the 8 roles; the library's own names map the other 5.
+
+  left at the library's default
+    colours  dk2 #44546A, lt2 #E7E6E6, accent2 #ED7D31, accent3 #A5A5A5, accent4 #FFC000, accent5 #5B9BD5, accent6 #70AD47, folHlink #954F72
+    type     margin, gutter, block, rule, mono
+
+  the deck has no layout for
+    two-column, section, image-text, image-title, image-slide
+
+  the template places 0 of the 3 roles the deck's own layouts map.
+```
+
+The report says how the roles were split, and it says it in two forms. A deck whose own layout
+is called the library's name for a role leaves that role to take a name of its own, and the
+report counts it apart from the two:
+
+```text
+  the deck's own layouts map 1 of the 8 roles; the library's own names map 6, and the rest take a name of their own.
+```
+
+A deck with no master has no template, and the report says so where the template's line would
+be:
+
+```text
+  the deck has no master, so the theme carries no template.
 ```
 
 The report goes to standard output, and the theme it writes is a directory the slides part

content/general/directives.md

@@ -84,6 +84,11 @@ Two of the eight are not the same in both halves. A `color` is a role, a theme s
 in Markdown Presentation, and six hexadecimal digits in Markdown Word. A `highlight` is drawn by
 Markdown Word and **refused by name** by Markdown Presentation, which has no way to write one.
 
+**A style's name is folded.** A theme that spells a style `Brand` has it under `:brand[…]` and
+`:Brand[…]` alike: a style's name is a word, and a word does not care about case. The refusal for
+a name the theme does not have spells the styles the way the theme wrote them, because that is
+the spelling the author has to change.
+
 Three forms, one grammar:
 
 | Written | Means |

content/general/files.md

@@ -62,7 +62,7 @@ as for a theme.
 
 | Role | What it is |
 | --- | --- |
-| `theme` | a file of a theme — its manifest, its slots, its layouts, its master |
+| `theme` | a file of a theme — its manifest and its master |
 | `picture` | an image a document names |
 | `document` | anything else a document names by path — a `.dotx`, a deck's templates file |
 
@@ -77,16 +77,24 @@ not compose the same ones.
 | The library wants | It asks | Which half |
 | --- | --- | --- |
 | the theme `corporate`'s manifest | `read('corporate/theme.yml', 'theme')` | both |
-| the theme `corporate`'s styles | `read('corporate/styles.yml', 'theme')` | both |
-| the theme `corporate`'s layouts | `read('corporate/layouts.yml', 'theme')` | slides |
-| the theme `corporate`'s text styles | `read('corporate/text-styles.yml', 'theme')` | slides |
+| the theme `corporate`'s old styles | `read('corporate/styles.yml', 'theme')` | both |
+| the theme `corporate`'s old layouts | `read('corporate/layouts.yml', 'theme')` | slides |
+| the theme `corporate`'s old text styles | `read('corporate/text-styles.yml', 'theme')` | slides |
 | the theme `corporate`'s master | `read('corporate/template.pptx', 'theme')` | slides |
 | the picture `logo.png` | `read('logo.png', 'picture')` | both |
 | the document's `report.dotx` | `read('report.dotx', 'document')` | Word |
 | the deck's templates file | `read('slides.md', 'document')` | slides |
 
-The Word half's `styles.yml` carries `textStyles:` inside it; the slides half keeps the named
-styles in a `text-styles.yml` of their own. The finder is never told which is which — it is asked
+**Three of those names are asked for only so that they can be refused.** A theme is one file
+now, and `styles.yml`, `layouts.yml` and `text-styles.yml` are the format it used to be made
+of: the library asks the finder whether one of them is there, and refuses the theme when it
+is. The other five are read.
+
+The two halves part at the look: the Word half's `theme.yml` may carry `styles:`, and the slides
+half's may carry `dark:`, `colors:`, `fonts:`, `style:` and `layouts:`. Each half refuses the
+other's look, so one file cannot carry both. The keys they share — `name:`, `description:`,
+`author:` and `textStyles:` — are legal in both, and a file that carries only those is read by
+both, each half drawing it its own way. The finder is never told which is which — it is asked
 for a name.
 
 ## A finder answers; it does not refuse
@@ -299,20 +307,21 @@ theme: house
 
 A document whose theme came from a finder rather than from a directory.
 
-The theme's own `styles.yml` names the face and the colour of the heading, and the library
-asked the finder for both of them.
+The theme's own `theme.yml` names the face and the colour of the heading, and the library
+asked the finder for it.
 ````
 {% endexample %}
 
-And a deck, from the same source:
+And a deck, from the same source. The finder holds a theme for each half, because each carries
+the look of its own half:
 
 {% example "A deck whose theme came from a finder" %}
 ````md presentation finder
 ---
-theme: house
+theme: deck
 ---
 
-# The house style
+# The deck style
 
 ## A deck whose theme came from a finder
 

content/presentation/directives.md

@@ -128,7 +128,7 @@ it.
 
 The three forms and the eight attributes are the suite's, and are on
 [How directives work](/directives/#a-word-in-a-style). The named styles come from the theme's
-`text-styles.yml` — see [Text styles](/presentation/themes/#text-styles).
+`textStyles:` section — see [Text styles](/presentation/themes/#text-styles).
 
 **What this half does with a name it does not know is the opposite of the Word half's: it refuses
 it**, and the message names the styles the theme does have. Every inline directive in a deck is a
@@ -256,7 +256,7 @@ splits here the way it does there.
 
 ## Frontmatter directives
 
-Every key of every slide's frontmatter must be one of these fifteen:
+Every key of every slide's frontmatter must be one of these sixteen:
 
 <!-- reference: presentation.frontmatter -->
 
@@ -272,6 +272,7 @@ Every key of every slide's frontmatter must be one of these fifteen:
 | `template` | string, or a list of them | none | any |
 | `templates-file` | string | none | **first only** |
 | `template-settings` | mapping | none | a definition |
+| `deck-settings` | mapping | none | **first only** |
 | `background` | string | none | any |
 | `background-gradient` | string | none | any |
 | `background-angle` | integer | 180 | any |
@@ -281,6 +282,15 @@ Every key of every slide's frontmatter must be one of these fifteen:
 The layout roles are listed with the [themes](/presentation/themes/#layout-roles). Anything else —
 including Slidev's own `two-cols` — is refused with the list of what would have worked.
 
+**`theme-variables:` is the theme's own values for one slide.** It is a `theme.yml` in miniature
+— the same keys, the same names, the same spelling — and what a slide may put in it is on
+[A slide's own values](/presentation/themes/#a-slides-own-values).
+
+**The ordinary keys are the slide's own, wherever they are written.** A key that holds somebody
+else's settings says whose: `template-settings:` says the template's, and `deck-settings:` says
+the deck's. That is what tells a definition from a slide and a slide from a deck — see
+[The deck's own settings](#the-decks-own-settings).
+
 **A background is one colour or one gradient.** `background-gradient` takes the stops of the
 gradient, one after another with a comma between them, and a stop may carry the place it is at
 as a percentage of the gradient — `accent1@50` is that stop at half of the way.
@@ -294,7 +304,8 @@ package's own [README](https://github.com/markdown-office/markdown-presentation#
 
 A deck directive on a later slide is refused by name, because it is nearly always a slide that
 was meant to be the first one. The deck's own frontmatter **is the first slide's**, so `theme:`,
-`author:`, `description:` and `templates-file:` belong on the slide that opens the deck.
+`author:`, `description:`, `templates-file:` and `deck-settings:` belong on the slide that opens
+the deck.
 
 {% example %}
 ````md presentation "The four keys that describe a deck"
@@ -323,6 +334,69 @@ Lead with the renewal number. It is the one people remember.
 ````
 {% endexample %}
 
+## The deck's own settings
+
+**A deck's settings are the deck's, and they are named as the deck's.** Every slide is drawn
+with them, and they go under `deck-settings:`, which holds the same keys a slide's own settings
+do:
+
+```markdown
+---
+theme: corporate-dark
+deck-settings:
+  background: "#101014"
+  theme-variables:
+    colors:
+      accent1: "#123456"
+---
+```
+
+`deck-settings:` is the deck's alone, so it is refused on any slide but the first — the way
+`theme:` is. It holds the five settings — `background`, `background-gradient`,
+`background-angle`, `background-radial` and `theme-variables` — and a key that is not one of
+them is refused by name rather than left out, so that a typo in a deck's settings is a failure
+and not a setting that does nothing.
+
+**The precedence is slide → template → deck → theme.** A slide's own settings are laid over the
+template's, and the template's over the deck's, and the deck's over the theme's — and one value
+laid over another leaves the rest alone: a slide that names one colour leaves the other eleven
+as they were.
+
+That is the whole of the rule, and it is one rule: **the ordinary keys are the slide's own,
+wherever they are written; a key that holds somebody else's settings says whose.** A slide that
+draws a template and names a `background:` of its own is therefore a slide, and is drawn with
+it.
+
+{% example "A deck whose accent every slide is drawn with" %}
+````md presentation
+---
+theme: corporate-dark
+deck-settings:
+  theme-variables:
+    colors:
+      accent1: "#123456"
+---
+
+# The quarter
+
+## What changed
+
+- Two products shipped
+
+---
+
+## What it cost
+
+- Two engineers, for a quarter
+
+---
+
+## What happens next
+
+- A second release
+````
+{% endexample %}
+
 ## Slide templates
 
 The furniture of a deck — the wordmark (a company's name on a slide, with its mark), the rule, the
@@ -368,8 +442,8 @@ template-settings:
 ```
 
 The ordinary keys mean the **slide's** own everywhere, which is what tells a definition from a
-slide: a slide that draws a template and names a `background:` of its own is a slide, and is
-drawn with it.
+slide. A template's settings are laid over the slide's, and the deck's over the template's —
+see [The deck's own settings](#the-decks-own-settings).
 
 {% example "A deck whose wordmark is written once" %}
 ````md presentation
@@ -412,9 +486,9 @@ template: [brand, page]
 ```
 
 **`layout:` and `template:` are independent.** `layout:` chooses the geometry — the role the
-theme's `layouts.yml` maps onto a box on the page — and `template:` adds furniture on top of it.
-`layout: blank` with `template: brand` is a slide with no furniture of its own and the wordmark
-drawn where the template puts it.
+theme's `layouts:` section maps onto a box on the page — and `template:` adds furniture on top
+of it. `layout: blank` with `template: brand` is a slide with no furniture of its own and the
+wordmark drawn where the template puts it.
 
 The chrome is drawn **over** what the slide placed itself, so a full-bleed picture is behind the
 wordmark and not over it.

content/presentation/errors.md

@@ -36,7 +36,7 @@ is about both libraries, is on [Errors in general](/errors/).
 | `FencedFrontmatter` | a ```` ```yaml ```` block at the top of a slide |
 | `MalformedTheme` | a theme file is not shaped like one |
 | `ThemeNotFound` | a theme name resolves to nothing — the message lists the ones that do |
-| `UnknownStyleSlot` | `styles.yml` names a slot that does not exist |
+| `RetiredThemeFile` | a file of the old theme format is beside the theme — the message says what to do with it |
 | `MalformedTemplate` | a `template.pptx` is not one |
 | `MalformedShape` | a free shape has an attribute it does not read, or a value it cannot be |
 | `UnknownTextStyle` | an inline style names a style the theme does not have — the message names the styles |