forgegraph 0.3.0__tar.gz → 0.4.0__tar.gz

{forgegraph-0.3.0 → forgegraph-0.4.0}/.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: check-yaml
+        args: [--unsafe]          # syntax only, so specs may carry !var and !fix tags
       - id: check-toml
       - id: end-of-file-fixer
         exclude: \.md$|^(review|catalog|docs/visual-changelog)/

{forgegraph-0.3.0 → forgegraph-0.4.0}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written. From 0.2.0 on, each release's entry links its visual changelog: before and after images of every catalog card and regression graph that changed, made with `scripts/visual_changelog.py`.
 
+## 0.4.0 (2026-10-27)
+
+Images that changed: the [visual changelog](docs/visual-changelog/0.4.0.html).
+
+### Changed
+
+- **Breaking for existing specs and configs:** one built-in pack, `forgegraph_default`, replaces `forgegraph_base` and `forgegraph_base_2`. Its specs are `light_theme` (in place of `forgegraph_base/base_theme`), `compact_format` (`base_format`), `wide_format` (`base_layout_format`), `layout` (`layout_example`), `schedule` (`base_schedule`) and `graphspec_example`; `forgegraph_base_2` has no replacement. A main config listing `forgegraph_base` or `forgegraph_base_2` is an error: list `forgegraph_default` instead. light_theme draws 0.3's look. It fixes every text's font and gap, the palettes (the colors, line styles, marker shapes and fills that series take in turn), the ticks' direction, sides and algorithms, and the grid, so a GraphSpec that sets `grid.x.show` needs a theme that leaves it variable; a series may still set its own color, line style, marker shape and line width. The default layout draws no line between tiles and leaves 0.25 × the base size at the figure's edges.
+- The specification files, which define each kind, are in `src/forgegraph/specifications/`, and their pages in `docs/specifications/`; no spec can name or extend them. The built-in pack's pages are in `docs/packs/forgegraph_default/`, and the catalog page is `catalog/forgegraph_default.html`.
+- A category's brackets in a specification file say what the code reads about it, from a fixed set: its style, `same as <sibling>` for a category with a sibling's parameters, and `look from <theme category>` for a layer category whose look comes from the theme. Anything else there is an error, and descriptions are never read, so rewording one changes nothing.
+- A style's member that no file tags, itself or through a category inside `parameters`, is fixed or variable as its general parameter is: a fixed `text.font` fixes every text style's font, even where the theme sets the style's own.
+- `forgegraph schema <kind>` no longer says whether a parameter is fixed: it shows the kind's specification, which isn't what graphs are drawn with. `forgegraph schema graphspec` lists what a GraphSpec can set, and `forgegraph explain` shows what's fixed.
+- A reference layer's `fill.color` may be None: two lines with values make a band only when it isn't.
+- **Breaking for existing specs:** a GraphSpec lists its series by name under `series`, each drawn from its own column (by default, the column of its name) with its own settings: `aggregation`, `split`, `order`, `color`, `color_scale`, `line`, `marker`, `bar` and `value_label`, and the theme's variable series parameters it sets for itself. They replace `axis.*.data.aggregation`, `encoding.*` and `mark.*`; the value axis's `data.column` is None. `arrangement.base_axis`, `arrangement.stacking`, `arrangement.offset` and `arrangement.total.show` replace `series.base_axis`, `series.aggregation`, `series.offset` and `series.value_label.total.show`. A series' color, line style, marker shape and fill take `first`, `series`, a value or a column; series take palette colors in the order they're listed.
+- **Breaking for existing specs:** the `reference` layer replaces `reference_line`: `line_1` and `line_2`, each at a value or from a column, with its own `aggregation` and `offset` (aggregation styles), `scope`, line and label (with `label.inside`), and the `fill` of a band between them. The theme's `layer.reference` replaces `layer.reference_line`.
+- An aggregation style (`function`, `multiplier`, `percentile`) for a series, a reference line and error bars; functions include `percentile`, `stddev`, `stderr` and `ci`.
+- `line.interpolate` draws a series' line straight, in steps (`step_after`, `step_before`, `step_center`) or as a smooth curve that never overshoots its points.
+- A note and a reference layer's lines, labels and fill may set the theme's variable look for themselves.
+- A style key (one from `encoding.line.style.column`, `encoding.marker.shape.column` or `encoding.marker.fill.column`) follows `legend.key.title.text`, as the series' key does: `column_name`, the default, gives each key its own column's name, so default graphs are unchanged; `None` removes every key's title; a text titles one key, and with more than one key drawn it's an error. With no `encoding.color.column`, a style key's samples are drawn in the one series color, not the text color. `render --json` reports `style_keys`, the column each style key drawn explains (for a layout, each tile's), beside `labelling`.
+- A range type `date`: a date, or a date and time, as YAML's bare date (`2025-08-25`, `2025-08-25 06:00:00`) or ISO 8601 text (`"2025-08-25T06:00"`); a time with a zone is at its clock time, as the data's are. `axis.x.min`, `axis.x.max`, `axis.y.min` and `axis.y.max`, a reference line's `value` and `benchmark.value` take it: on a datetime axis or column, a date is drawn exactly where its day number is, and numbers keep working as day numbers. A date on an axis that isn't dates is an error naming the axis's type. Text that reads as a date is a reference line's column only if the data has a column of that name. Provenance records write dates as ISO 8601 text.
+- On a date value axis, what would draw nonsense is an error that says what to do: stacking (`series.aggregation` sum or percent), adding up rows (`axis.*.data.aggregation` sum), bars (`mark.bar.show`, which would start at 1970), and value labels without a date format. A reference line at a date column's aggregate is on a date axis only, at its mean, median, min or max, with multiplier 1. A date axis's `tick.label.format` must have a date directive.
+
+### Fixed
+
+- In a theme whose text is light, powers of ten on a log axis and superscripts in labels no longer give a `font-fallback` lint issue. They were always drawn in the theme's font and weight; the issue came from the faces matplotlib loads for maths but doesn't draw these with.
+- The `outside-limits` and `log-axis-values` lint checks count only data points. A reference line's ends and an error bar's ends no longer count as points outside a set axis limit, or as values of 0 or below on a log axis.
+- A style key on the benchmark's column matches the drawing: its entries are the groups the series are styled by, so a value after the benchmark no longer gets the next value's style, and the benchmark, drawn in its own style, has no style sample and is named once, by `legend.method`. When `legend.method: key` doesn't fit, the error says why: every position in `legend.key.positions` is taken or covers data, naming the position each style key took.
+- YAML's null (`null`, `~` or nothing) is None everywhere a spec can say None. `extends: null` failed with `KeyError: None`, and a file extending null wasn't required to list every parameter.
+- Computed values are compared with an axis's limits allowing for float noise: a value is past a limit only if it's past by more than 1e-9 of the axis's span, measured in powers of ten on a log axis. A stack that totals `axis.y.max` but for its last digits isn't reported by `outside-limits`; a reference line at a computed value that equals a set limit isn't an error; bars whose values are 0 but for float noise still stand on the axis; and a tick a hair past the end of the view, which matplotlib draws, is measured for layout and lint and counts when log labels choose between plain numbers and powers of ten.
+- Dates and times draw the same on y as on x: every value placed on an axis (the data, its aggregates, stacks, reference lines, error bars and limits) becomes a number the same way, so a date y axis has date ticks, a reference line at a date column's aggregate lands on it, and error bars from a date column's spread are in days. With value labels off, a date `tick.label.format` such as `"%H:%M"` on y is no longer refused as a number format; value labels and a reference line's value on a date axis are written in a date format.
+
 ## 0.3.0 (2026-10-25)
 
 Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).

{forgegraph-0.3.0 → forgegraph-0.4.0}/CONTRIBUTING.md

@@ -19,13 +19,12 @@ Mark a new test `@pytest.mark.slow` if it takes over a second (`uv run pytest --
 
 ## After changing a definition or how graphs are drawn
 
-Every parameter gets one catalog card, its value and baseline chosen by a rule (`src/forgegraph/catalog_build/cards.py`), so a new parameter needs no card of its own; the page shows the variable parameters' cards, and the perturbation test draws them all. It needs a baseline that shows it only if none does: the build (for a variable parameter) or the perturbation test (for any) names a parameter that changes no baseline's drawing, and the fix is a generic scenario added to the baselines in the matching catalog file under `src/forgegraph/catalogs/` (or a pack's `catalogs/`).
+Every parameter gets one catalog card, its value and baseline chosen by a rule (`src/forgegraph/catalog_build/cards.py`), so a new parameter needs no card of its own; the page shows the variable parameters' cards, and the perturbation test draws them all. It needs a baseline that shows it only if none does: the build (for a variable parameter) or the perturbation test (for any) names a parameter that changes no baseline's drawing, and the fix is a generic scenario added to the baselines in the matching catalog file under `src/forgegraph/specifications/catalogs/` (or the pack's `catalogs/`).
 
-Rebuild the catalogs (it keeps its review comments; Node 18+ is needed once it has some), and the image baselines if graphs look different on purpose:
+Rebuild the catalog (it keeps its review comments; Node 18+ is needed once it has some), the mirrors, and the image baselines if graphs look different on purpose:
 
 ```bash
 uv run forgegraph catalog build
-uv run forgegraph catalog build --pack forgegraph_base_2
 uv run python scripts/mirror_specs.py
 uv run python scripts/build_recreations.py --baselines
 ```
@@ -38,8 +37,8 @@ Open a GitHub issue describing the graph you need, ideally with an example image
 
 ## Releasing
 
-1. Set the new version in pyproject.toml and in each built-in pack's pack.yaml.
-2. Rebuild the catalogs and mirrors (above).
+1. Set the new version in pyproject.toml and in the built-in pack's pack.yaml, and for a new minor version, its `requires` (`">=0.4, <0.5"` for 0.4).
+2. Rebuild the catalog and mirrors (above).
 3. Write the visual changelog, `uv run python scripts/visual_changelog.py v<last version>`, and the CHANGELOG entry, linking it.
 4. Merge with CI green, and tag the merge commit `v<version>`.
 5. Run the Publish workflow.

{forgegraph-0.3.0 → forgegraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.3.0
+Version: 0.4.0
 Summary: Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
 Project-URL: Repository, https://github.com/sskaye/forgegraph
 Project-URL: Issues, https://github.com/sskaye/forgegraph/issues
@@ -106,12 +106,11 @@ name: voltage
 version: 0
 description: Cell voltage over a test, one line per cell.
 extends: None
-fixed_parameters: None
-variable_parameters:
+parameters: !var
     specifications:
         graph_type: xy
-        theme: forgegraph_base/base_theme
-        format: forgegraph_base/base_format
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
     text:
         title: Cell voltage
     data:
@@ -121,12 +120,9 @@ variable_parameters:
         x:
             data:
                 column: hours
-        y:
-            data:
-                column: voltage
-    encoding:
-        color:
-            column: cell
+    series:
+        voltage:
+            color: cell
 ```
 
 ```bash
@@ -135,7 +131,7 @@ forgegraph render voltage.yaml
 
 ## Packs and configs
 
-Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. The initial built-in packs are `forgegraph_base` and `forgegraph_base_2`, stored in src/forgegraph/packs.
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs: its theme, `light_theme`, its formats, `compact_format` for single graphs and `wide_format` for layouts, and a layout and a schedule to extend.
 
 A **config** lists the packs that may be used:
 
@@ -163,10 +159,9 @@ Every command takes `--help`, and `--json` for agents.
 
 ## Catalogs
 
-Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does. Download a page and open it in a browser.
+The built-in pack has a catalog: a page with a card for each parameter, showing what changing it does. Download it and open it in a browser.
 
-- [forgegraph_base](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base.html): ForgeGraph's own pack, with its graph types and layer types.
-- [forgegraph_base_2](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base_2.html): its own theme and format, and the same graph types and layer types drawn in them.
+- [forgegraph_default](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_default.html): its theme and formats, and ForgeGraph's graph types and layer types drawn in them.
 
 ## Your graphs are yours
 
@@ -174,7 +169,8 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 
 ## Documentation
 
-- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specs): every spec, a folder per kind.
+- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specifications): the file that defines each kind of spec, every parameter with its default, range and description.
+- [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).
 - [Contributing](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md): working on ForgeGraph itself.
 - Design record, in [docs/design](https://github.com/sskaye/forgegraph/blob/main/docs/design):
@@ -192,12 +188,13 @@ Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
   - **drawing/**: drawing, layout and lint. **layouts/**: `fg.layout` and layouts. **jobs/**: scheduled renders.
-  - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
-  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog_build/**: the catalog builder. **catalogs/**: each definition's catalog file.
+  - **specifications/**: the specification files, which define each kind of spec, and the graph types' and layer types' catalog files.
+  - **packs/**: packs and configs, and the built-in pack `forgegraph_default`. **fonts/**: bundled fonts and their licences.
+  - **catalog_build/**: the catalog builder.
   - **skill/forgegraph/**: the agent skill. `forgemark.py`: Forgemark's review-comment format, and its pinned tool.
 - **catalog/**: the generated catalog pages.
 - **examples/**: sample data; `packs/acme`, an example pack in a deliberately different style; and `layouts/`, a paper figure and a dashboard.
 - **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
 - **tests/**, **scripts/**: tests, and build and maintenance scripts.
-- **docs/**: the specifications, the design record and the visual changelogs. **review/**: each build phase's review pages.
+- **docs/**: the specifications' and packs' pages, the design record and the visual changelogs. **review/**: each build phase's review pages.
 

{forgegraph-0.3.0 → forgegraph-0.4.0}/README.md

@@ -76,12 +76,11 @@ name: voltage
 version: 0
 description: Cell voltage over a test, one line per cell.
 extends: None
-fixed_parameters: None
-variable_parameters:
+parameters: !var
     specifications:
         graph_type: xy
-        theme: forgegraph_base/base_theme
-        format: forgegraph_base/base_format
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
     text:
         title: Cell voltage
     data:
@@ -91,12 +90,9 @@ variable_parameters:
         x:
             data:
                 column: hours
-        y:
-            data:
-                column: voltage
-    encoding:
-        color:
-            column: cell
+    series:
+        voltage:
+            color: cell
 ```
 
 ```bash
@@ -105,7 +101,7 @@ forgegraph render voltage.yaml
 
 ## Packs and configs
 
-Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. The initial built-in packs are `forgegraph_base` and `forgegraph_base_2`, stored in src/forgegraph/packs.
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. ForgeGraph's built-in pack, `forgegraph_default`, is stored in src/forgegraph/packs: its theme, `light_theme`, its formats, `compact_format` for single graphs and `wide_format` for layouts, and a layout and a schedule to extend.
 
 A **config** lists the packs that may be used:
 
@@ -133,10 +129,9 @@ Every command takes `--help`, and `--json` for agents.
 
 ## Catalogs
 
-Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does. Download a page and open it in a browser.
+The built-in pack has a catalog: a page with a card for each parameter, showing what changing it does. Download it and open it in a browser.
 
-- [forgegraph_base](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base.html): ForgeGraph's own pack, with its graph types and layer types.
-- [forgegraph_base_2](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_base_2.html): its own theme and format, and the same graph types and layer types drawn in them.
+- [forgegraph_default](https://github.com/sskaye/forgegraph/blob/main/catalog/forgegraph_default.html): its theme and formats, and ForgeGraph's graph types and layer types drawn in them.
 
 ## Your graphs are yours
 
@@ -144,7 +139,8 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 
 ## Documentation
 
-- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specs): every spec, a folder per kind.
+- [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specifications): the file that defines each kind of spec, every parameter with its default, range and description.
+- [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).
 - [Contributing](https://github.com/sskaye/forgegraph/blob/main/CONTRIBUTING.md): working on ForgeGraph itself.
 - Design record, in [docs/design](https://github.com/sskaye/forgegraph/blob/main/docs/design):
@@ -162,12 +158,13 @@ Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
   - **drawing/**: drawing, layout and lint. **layouts/**: `fg.layout` and layouts. **jobs/**: scheduled renders.
-  - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
-  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog_build/**: the catalog builder. **catalogs/**: each definition's catalog file.
+  - **specifications/**: the specification files, which define each kind of spec, and the graph types' and layer types' catalog files.
+  - **packs/**: packs and configs, and the built-in pack `forgegraph_default`. **fonts/**: bundled fonts and their licences.
+  - **catalog_build/**: the catalog builder.
   - **skill/forgegraph/**: the agent skill. `forgemark.py`: Forgemark's review-comment format, and its pinned tool.
 - **catalog/**: the generated catalog pages.
 - **examples/**: sample data; `packs/acme`, an example pack in a deliberately different style; and `layouts/`, a paper figure and a dashboard.
 - **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
 - **tests/**, **scripts/**: tests, and build and maintenance scripts.
-- **docs/**: the specifications, the design record and the visual changelogs. **review/**: each build phase's review pages.
+- **docs/**: the specifications' and packs' pages, the design record and the visual changelogs. **review/**: each build phase's review pages.
 

{forgegraph-0.3.0 → forgegraph-0.4.0}/docs/design/architecture.md

@@ -31,10 +31,10 @@ Also:
 | Area | Decision |
 | --- | --- |
 | Renderer (D1) | matplotlib only; no interactivity in the MVP |
-| Core API (D2) | Spec-first: `render(spec)`; Python functions build specs. The definition files are the source; `forgegraph schema`, the catalog pages and the docs/specs mirrors are generated from them |
-| Style (D3) | Theme × format, layered and explainable; themes hold fixed parameters (graphs can't change them) and variable parameters with defaults (graphs can change them) |
+| Core API (D2) | Spec-first: `render(spec)`; Python functions build specs. The definition files are the source; `forgegraph schema`, the catalog pages and the docs/specifications mirrors are generated from them |
+| Style (D3) | Theme × format, layered and explainable; themes tag parameters !fix (graphs can't change them) or !var, with defaults (graphs can change them) |
 | Extension (D4) | Packs, data only, are the only source of named specs; the main and folder configs say which may be used, and a pack only a folder config lists is non-standard; graph types and layers stay in the core |
-| Graph types (D5) | Each graph type's and layer type's definition file (graph_types/xy.yaml, layers/<type>.yaml) is the source of truth |
+| Graph types (D5) | Each graph type's and layer type's definition file (specifications/graphtype_xy.yaml, specifications/layer_<type>.yaml) is the source of truth |
 | Review (D6) | Tabbed HTML catalog with Forgemark comments |
 | Input (D7) | A pandas DataFrame, from the Python API or a Parquet file named by the GraphSpec; an optional reference to the code that made it |
 | Labels (D8) | Lightweight sub/superscript markup, applied to explicit labels only |
@@ -54,7 +54,7 @@ Also:
 
 1. **The GraphSpec is the product.** Skill, notebooks, CLI, scheduler, dashboards and the future desktop app all produce or consume the same document. Python function calls build GraphSpecs; they are not a second code path.
 2. **Three tiers of control, no fourth.**
-   - **Fixed style**: house style, set by the theme and format (by the org, journal or user), never by an individual graph. Each value is a **parameter**, e.g. `plot_area.sides` or `series.colors`; a theme may also leave some parameters variable, for graphs to change.
+   - **Fixed style**: house style, set by the theme and format (by the org, journal or user), never by an individual graph. Each value is a **parameter**, e.g. `plot_area.border.sides` or `series.colors`; a theme may also leave some parameters variable, for graphs to change.
    - **Options**: what an individual graph may vary. Each is documented with a default, except the data itself (the data file and the required mappings such as `x` and `y`), which every graph must specify.
    - **Escape hatch**: raw matplotlib on a themed figure, always marked non-standard.
 3. **One source per fact; everything else is generated.** Each kind of document is defined by its definition file (§8): every parameter with its default, range and description. The code reads them; `forgegraph schema`, the catalog pages and the docs/specs mirrors are generated from them, and the skill reads them at run time. Nothing generated is edited by hand.
@@ -70,8 +70,8 @@ Also:
 | Term | What it is | Where it lives |
 | --- | --- | --- |
 | **GraphSpec** | One specific graph: data, graph type, column mappings, parameters, layers | a YAML file, embedded in the saved graph |
-| **Graph type** | A kind of graph (`xy`): the parameters a GraphSpec chooses, in its definition file, drawn by its module in drawing/ | `src/forgegraph/graph_types/<type>.yaml` (core only) |
-| **Layer** | An addition drawn on a graph (`reference_line`, `note`, `error_bar`), defined by its own file | `src/forgegraph/layers/<type>.yaml` (core only) |
+| **Graph type** | A kind of graph (`xy`): the parameters a GraphSpec chooses, in its definition file, drawn by its module in drawing/ | `src/forgegraph/specifications/graphtype_<type>.yaml` (core only) |
+| **Layer** | An addition drawn on a graph (`reference`, `note`, `error_bar`), defined by its own file | `src/forgegraph/specifications/layer_<type>.yaml` (core only) |
 | **GraphSpec to extend** | A GraphSpec without data, reused by others through `extends:`. E.g. "polarization curve" = `xy` + its columns + axis titles | a pack's `graphspecs/` |
 | **Theme** | The look: fixed style (fonts, palettes, spines, ticks, legend style), plus defaults for options | a pack's `themes/` |
 | **Format** | The destination: figure size, base font size, file types, dpi, provenance level | a pack's `formats/` |
@@ -106,19 +106,18 @@ Also:
 
 ### 3.1 What it looks like to use
 
-**GraphSpec** (docs/specs/graphspec/polarization.md lists every parameter):
+**GraphSpec** (docs/specifications/graphspec_example.md lists every parameter):
 
 ```yaml
 name: voltage
 version: 0
 description: Cell voltage over a test, one line per cell.
 extends: None
-fixed_parameters: None
-variable_parameters:
+parameters: !var
     specifications:
         graph_type: xy
-        theme: forgegraph_base/base_theme      # from a pack the configs allow
-        format: forgegraph_base/base_format
+        theme: forgegraph_default/light_theme      # from a pack the configs allow
+        format: forgegraph_default/compact_format
     text:
         title: Cell voltage
     data:
@@ -128,18 +127,17 @@ variable_parameters:
         x:
             data:
                 column: hours
-        y:
-            data:
-                column: voltage
-    encoding:
-        color: cell
+    series:
+        voltage:
+            color: cell
     layers:
         target:
-            type: reference_line
+            type: reference
             axis: y
-            value: 0.7
-            label:
-                text: Target
+            line_1:
+                value: 0.7
+                label:
+                    text: Target
 ```
 
 **Python:**
@@ -190,16 +188,18 @@ Interactivity is not part of the MVP. If it becomes a requirement later, the opt
 
 ### D3. Style resolution: theme × format, layered, explainable
 
-**One structure for every specification.** Themes, formats, graph types and GraphSpecs are written the same way, and each kind is defined by one file: the base pack's `themes/base_theme.yaml` and `formats/base_format.yaml` (in `src/forgegraph/packs/forgegraph_base/`), each graph type's own file (`graph_types/xy.yaml`) and an example GraphSpec that sets every parameter (the base pack's `graphspecs/polarization.yaml`). Every file has a header (`name`, `version`, `description`, `extends`) and two sections, `fixed_parameters` and `variable_parameters`, each holding categories of parameters. In a definition file every line, header included, gives its value and a comment `[RANGE]; DESCRIPTION`, and the code reads every definition, range included, from those files.
+**One structure for every specification.** Themes, formats, graph types and GraphSpecs are written the same way, and each kind is defined by one file in `src/forgegraph/specifications/`: `theme.yaml`, `format.yaml`, each graph type's own file (`graphtype_xy.yaml`) and an example GraphSpec (`graphspec_example.yaml`). A specification file only defines its kind: no spec can name or extend it, so it lists every parameter without having to be a usable look; the built-in pack, forgegraph_default, holds the specs graphs are drawn with. Every file has a header (`name`, `version`, `description`, `extends`) and `parameters`, one tree of categories of parameters. In a definition file every line, header included, gives its value and a comment `[RANGE]; DESCRIPTION`, and the code reads every definition, range included, from those files.
 
-- **Fixed:** a GraphSpec can't change it (principle 2). A different look needs a different theme, typically one that extends the house theme.
-- **Variable:** a GraphSpec may change it, under the same category; the file gives the value it has otherwise.
-- **extends:** every parameter a file doesn't list is inherited, fixed or variable as it was. With `extends: None` the file lists every parameter.
+- **!fix:** a GraphSpec can't change it (principle 2). A different look needs a different theme, typically one that extends the house theme.
+- **!var:** a GraphSpec may change it, under the same category; the file gives the value it has otherwise.
+- A tag goes before a value (`width: !var 0.15`) or on a category (`output: !var`), where it applies to everything inside unless a tag further in says otherwise. A tag with no value (`width: !var`) changes only the status.
+- **extends:** every parameter a file doesn't list is inherited, with its status. The nearest file that tags a parameter, or a category above it, decides its status. With `extends: None` the file lists every parameter and tags each, itself or through a category.
+- **Styles:** in a theme, a category marked `[text style]`, `[line style]` or `[series style]` has the parameters of `text`, `line` or `series`, and takes their values unless it, or a file nearer in the extends chain, sets its own; a GraphSpec's settings of them carry through too. A member that no file tags, itself or through a category inside `parameters`, has its general parameter's status, so a fixed `text.font` fixes every text style's font. A style's category leaves out the members what it draws has no use for (a tick mark has no corners), listed in spec/parameters.py, so setting one is an error.
 - In a theme or format, a graph type's name used as a heading holds parameters for that graph type only.
 
 Every size in a theme is a multiple of the format's base font ("tick labels = 0.9 × base"), so a theme renders correctly in any format. That matters because graphs go to many destinations, not mainly slides (so no `.pptx` export: the examples were collected on slides only for convenience).
 
-**The base theme** (forgegraph_base/base_theme): Roboto, a full box, outward ticks, the Okabe–Ito palette, a frameless key, direct labels where they fit. The `acme` example pack has a *deliberately different* house style (IBM Plex Serif, two sides of the box, a grid, Paul Tol's muted palette), so it shows that a pack can change the look completely.
+**The default theme** (forgegraph_default/light_theme): Roboto, semibold titles, a full box, outward ticks, the Okabe–Ito palette with a grey benchmark, a frameless key, direct labels where they fit. It fixes the font, the palette and its lists, the ticks' direction and algorithms, the grid and the series' lines. The `acme` example pack has a *deliberately different* house style (IBM Plex Serif, two sides of the box, a grid, Paul Tol's muted palette), so it shows that a pack can change the look completely.
 
 **Fonts and PDFs:**
 
@@ -223,7 +223,7 @@ acme-forgegraph/
 └── fonts/
 ```
 
-- **Packs are the only source of named specs.** Every theme, format, GraphSpec, layout or schedule that a file names, under specifications or in extends, comes from a pack and is named `pack/name`. ForgeGraph's own specs are the pack `forgegraph_base`: `base_theme`, `base_format`, `base_layout_format`, `base_layout`, `base_schedule` and example GraphSpecs. Specs of your own are a folder pack. The files you draw (GraphSpecs, layouts and schedules, a layout's tiles and a schedule's targets) are given by path.
+- **Packs are the only source of named specs.** Every theme, format, GraphSpec, layout or schedule that a file names, under specifications or in extends, comes from a pack and is named `pack/name`. ForgeGraph's own specs are the pack `forgegraph_default`: `light_theme`, `compact_format`, `wide_format`, `layout`, `schedule` and an example GraphSpec. Specs of your own are a folder pack. The files you draw (GraphSpecs, layouts and schedules, a layout's tiles and a schedule's targets) are given by path.
 - **Graph types and layer types** are ForgeGraph's code, not pack data, so they're named without a prefix (`xy`) and can always be used.
 - **The config says which packs may be used** (packs/__init__.py has the rules): the main config for all work, and a folder config, `forgegraph.toml`, for the files below it.
   - A pack only a folder config lists is non-standard: it works, but whatever is drawn with it is watermarked and its record names the pack. That way someone who can't change an organization's main config can still make and try a pack, and nothing drawn with it passes as standard.
@@ -241,7 +241,7 @@ acme-forgegraph/
 
 ### D5. Graph types and layer types: one definition file each
 
-A graph type is defined by its own file in `src/forgegraph/graph_types/`, starting with `xy.yaml`, and drawn by drawing/xy.py; a layer type by its file in `src/forgegraph/layers/`, drawn by drawing/layers.py. Its parameters are what a GraphSpec chooses for one graph: the data column for each axis, the encodings, the marks and the legend. Things drawn on top of the graph, including those computed from its data (error bars, a reference line at the mean, a fitted curve), are layers. A parameter defined as None with no None in its range is required: a GraphSpec must set it. Style values never live in a graph type: the renderer reads them from the theme, so the theme stays the single place where style values live. The graph code receives a DataFrame; loading and preparing data happens before it.
+A graph type is defined by its own file in `src/forgegraph/specifications/`, starting with `graphtype_xy.yaml`, and drawn by drawing/xy.py; a layer type by its file there (`layer_<type>.yaml`), drawn by drawing/layers.py. A category's brackets say what the code needs to know about it, from a fixed set: its style, `same as <sibling>` for a category with a sibling's parameters, and `look from <theme category>` for a layer category whose look comes from the theme. Descriptions are for people, and no code reads them. Its parameters are what a GraphSpec chooses for one graph: the data column for each axis, the encodings, the marks and the legend. Things drawn on top of the graph, including those computed from its data (error bars, a reference line at the mean, a fitted curve), are layers. A parameter defined as None with no None in its range is required: a GraphSpec must set it. Style values never live in a graph type: the renderer reads them from the theme, so the theme stays the single place where style values live. The graph code receives a DataFrame; loading and preparing data happens before it.
 
 **Series labels come from a set of labelling methods.** Each method either places every label cleanly or reports that it can't. The theme lists the methods it allows, in order of preference, and a graph's `legend.method: auto` uses the first that fits. A method chosen by name that doesn't fit, or `auto` with nothing that fits, is an error that says what to change: ForgeGraph never draws labels over data as a fallback. The first methods are:
 
@@ -249,9 +249,9 @@ A graph type is defined by its own file in `src/forgegraph/graph_types/`, starti
 - `key`: a key at the first of the GraphSpec's legend.key.positions that covers no data, or outside the plot area (legend.key.inside: false);
 - `none`.
 
-A single series is named too, unless its name is the y-axis title's text, which already names it. A numeric `encoding.color.column` is drawn on a color scale with a color bar, or with palette colors and labels when `encoding.color.type` is `categorical`; with lines shown, a line joins only points of one color.
+A single series is named too, unless its name is the y-axis title's text, which already names it. A series colored by a numeric column is drawn on a color scale with a color bar, or with palette colors and labels when its `color_scale` is `categorical`; with lines shown, a line joins only points of one color.
 
-Placement is deterministic. A direct label sits inside the plot, beside its own series, touching nothing; drawing/labels.py lists the rules. A key, and the style key that explains encoding.line.style.column, sits inside the plot area at the first position that covers no data, or outside it, with the figure laid out again around it; drawing/key.py places it. Existing labelling libraries (matplotlib-label-lines, adjustText) don't meet these rules.
+Placement is deterministic. A direct label sits inside the plot, beside its own series, touching nothing; drawing/labels.py lists the rules. A key, and the style key that explains line styles set by a column, sits inside the plot area at the first position that covers no data, or outside it, with the figure laid out again around it; drawing/key.py places it. Existing labelling libraries (matplotlib-label-lines, adjustText) don't meet these rules.
 
 ### D6. Review surface: tabbed HTML catalog, Forgemark comments
 
@@ -322,9 +322,8 @@ When a request isn't in the catalog, the agent says so plainly, then:
 name: lab_throughput
 version: 0
 description: Daily operations view of lab throughput.
-extends: forgegraph_base/base_layout
-fixed_parameters: None
-variable_parameters:
+extends: forgegraph_default/layout
+parameters:
     specifications:
         format: ops/dashboard
     separators:
@@ -352,9 +351,9 @@ variable_parameters:
                 icp_oes_01: runs_icp_oes_01.yaml
 ```
 
-**A layout arranges GraphSpecs.** A layout file (`*.layout.yaml`, docs/specs/layout/base_layout.md) holds only what's particular to several graphs together: the arrangement, and what separates the graphs. Text, colors, fonts and the look of each graph stay in each tile's GraphSpec and its theme, so a tile drawn alone and in a layout is the same graph. A layout has no per-tile settings and no text of its own.
+**A layout arranges GraphSpecs.** A layout file (`*.layout.yaml`, docs/specifications/layout_example.md) holds only what's particular to several graphs together: the arrangement, and what separates the graphs. Text, colors, fonts and the look of each graph stay in each tile's GraphSpec and its theme, so a tile drawn alone and in a layout is the same graph. A layout has no per-tile settings and no text of its own.
 
-- **Format, no theme.** The layout's format (by default the base pack's base_layout_format: the base format at 300 mm) sets the size and output of the whole figure, and replaces each tile's own format, so every tile is drawn at one base size. The layout can set the format's variable parameters, such as its file types. Each tile keeps its own theme.
+- **Format, no theme.** The layout's format (by default the default pack's wide_format: the compact format at 300 mm) sets the size and output of the whole figure, and replaces each tile's own format, so every tile is drawn at one base size. The layout can set the format's variable parameters, such as its file types. Each tile keeps its own theme.
 - **The grid.** grid.areas draws the grid as rows of tile names, as CSS `grid-template-areas`, matplotlib's `subplot_mosaic` and patchwork do: a name repeated over a rectangle of cells spans it, and `.` is a blank cell. column_widths and row_heights are ratios of plot boxes.
 - **Aligned plot boxes.** A tab's tiles are laid out together, as patchwork, egg and cowplot do: each column's and row's margins are the most room any of its tiles needs around its plot box, measured to the letters, so plot boxes line up across tiles whatever their tick labels. A spanning tile's plot box runs across the margins and gaps inside it. With the format's height auto, each row is as tall as its tiles' aspects need. Tiles are never shrunk to fit; a figure too small for them is an error naming them.
 - **Separators.** The gap between tiles, its color, and optionally a line along the middle of each gap between two tiles.
@@ -368,7 +367,7 @@ Paper figures and ops dashboards differ only in their format and defaults; examp
 
 ### D12. Scheduled graphs and dashboards
 
-A scheduled job is a **schedule file** (`*.schedule.yaml`, docs/specs/schedule/base_schedule.md): the GraphSpec and layout files to render, where to save them, and when. It extends the base schedule like any other spec, so it can be reviewed, kept in version control and checked like any parameter.
+A scheduled job is a **schedule file** (`*.schedule.yaml`, docs/specifications/schedule.md): the GraphSpec and layout files to render, where to save them, and when. It extends the default pack's schedule like any other spec, so it can be reviewed, kept in version control and checked like any parameter.
 
 - **Cadence.** `interval.count` counts `interval.unit` (minute, hour, day, week, month or year), and `at` says when in each unit, one time or a list: ":30", "06:00", "mon 06:00", "1 06:00", "Jan 1 06:00". `interval.count` divides 60, 24 and 12 for minutes, hours and months, and is 1 otherwise, so every form maps exactly onto every scheduler. Times are the machine's local time.
 - **`forgegraph job run lab.schedule.yaml`** runs a schedule once. Whatever the environment offers schedules that command: the machine's scheduler (launchd, systemd, cron, Task Scheduler), a GitHub Actions workflow, a Claude scheduled task. ForgeGraph writes no scheduler entries itself, so every user's path is the same.
@@ -382,7 +381,7 @@ A scheduled job is a **schedule file** (`*.schedule.yaml`, docs/specs/schedule/b
 
 ### D13. Provenance and reproducibility
 
-Every output embeds a provenance record, at its format's provenance.level (full, minimal or off), so a graph can be traced and redrawn; docs/specs/provenance/provenance.md lists what each level records.
+Every output embeds a provenance record, at its format's provenance.level (full, minimal or off), so a graph can be traced and redrawn; docs/specifications/provenance.md lists what each level records.
 
 - **Carriers.** Provenance is one JSON record written through matplotlib's own metadata support: a PNG text chunk, a JPEG comment, the TIFF image description, the SVG Dublin Core `Description` field, and the PDF Info dictionary. HTML pages carry it in `<script type="application/json">`. drawing/export.py writes it.
 - **Layouts.** A layout's files record the layout as written and, for each tab they show, each tile's GraphSpec file and the same entries as a GraphSpec's.
@@ -440,13 +439,13 @@ Every output embeds a provenance record, at its format's provenance.level (full,
 
 **Graph types:** `xy` draws lines, markers and bars: grouped, stacked, 100 % stacked and horizontal, with value labels.
 
-**Layers:** `reference_line` (horizontal or vertical, labelled), `note` (the "conditions" text block) and `error_bar`. Error bars are a layer, drawn from DataFrame columns or the spread of aggregated rows: the specification names their absence as a failing of Tableau.
+**Layers:** `reference` (horizontal or vertical lines, labelled, or a band between two; at a value, an aggregate, or following the data), `note` (the "conditions" text block) and `error_bar`. Error bars are a layer, drawn from DataFrame columns or the spread of aggregated rows: the specification names their absence as a failing of Tableau.
 
 | Capability | Status |
 | --- | --- |
 | lines and markers, color by a column, direct labels, a benchmark series | built |
 | markers-only scatter with many points | built |
-| replicates: several lines per color group (encoding.detail.column) | built |
+| replicates: several lines per color group (a series' split) | built |
 | line style by a column, with a key for the styles | built |
 | log axes, unit markup | built |
 | color by a numeric column, with a color bar | built |
@@ -494,20 +493,21 @@ Repo `sskaye/forgegraph`; distribution, import and CLI `forgegraph`. The README'
 
 ## 8. Specifications
 
-Each kind of document is specified by its definition file: every parameter with its default, range and description. The code reads it, and tests check the code against it, including the edges of every range. docs/specs/ mirrors each file for review.
+Each kind of document is specified by its definition file: every parameter with its default, range and description. The code reads it, and tests check the code against it, including the edges of every range. docs/specifications/ mirrors each file for review, and docs/packs/ each built-in pack's.
 
 | Specification | Definition file |
 | --- | --- |
-| **Theme** | src/forgegraph/packs/forgegraph_base/themes/base_theme.yaml |
-| **Format** | src/forgegraph/packs/forgegraph_base/formats/base_format.yaml |
-| **Graph type** | src/forgegraph/graph_types/xy.yaml |
-| **GraphSpec** | src/forgegraph/packs/forgegraph_base/graphspecs/polarization.yaml |
-| **Layer type** | src/forgegraph/layers/, a file per type |
-| **Layout** | src/forgegraph/packs/forgegraph_base/layouts/base_layout.yaml |
-| **Schedule** | src/forgegraph/packs/forgegraph_base/schedules/base_schedule.yaml |
-| **Pack and config** | src/forgegraph/packs/forgegraph_base/pack.yaml, src/forgegraph/packs/config.toml |
-| **Provenance record** | src/forgegraph/spec/provenance.yaml |
-| **Catalog** | src/forgegraph/catalogs/, and each pack's catalogs/ |
+| **Theme** | src/forgegraph/specifications/theme.yaml |
+| **Format** | src/forgegraph/specifications/format.yaml |
+| **Graph type** | src/forgegraph/specifications/graphtype_xy.yaml |
+| **GraphSpec** | src/forgegraph/specifications/graphspec_example.yaml |
+| **Layer type** | src/forgegraph/specifications/layer_<type>.yaml, a file per type |
+| **Layout** | src/forgegraph/specifications/layout_example.yaml |
+| **Schedule** | src/forgegraph/specifications/schedule.yaml |
+| **Pack and config** | src/forgegraph/specifications/pack.yaml, src/forgegraph/specifications/config.toml |
+| **Provenance record** | src/forgegraph/specifications/provenance.yaml |
+| **Styles** | src/forgegraph/specifications/styles.yaml |
+| **Catalog** | src/forgegraph/specifications/catalogs/, and each pack's catalogs/ |
 
 ---
 
@@ -574,12 +574,11 @@ Decisions made while building whose reasons aren't given above.
 - **The layout always fits its tick labels.** Tick labels can keep a layout from settling: a taller plot box gets more, wider labels, which make it shorter again. After 6 unsettled passes it lays out once more with, on each side, the most room either of the last two passes needed, so whichever labels the final draw has fit.
 - **Date axes use one calendar unit per axis.** matplotlib's automatic date ticks mix units (the 1st and 15th, labelled "Aug" and "15") and name the shared context in a corner. As in d3 and Vega-Lite, ticks are a calendar unit's boundaries, never finer than the data's spacing, with the next unit up on a second line where it changes, as Plotly and Datawrapper do. Weekly ticks fall on Mondays even when the data starts on another day, which reads more naturally than counting from the data's first day. ForgeGraph writes %-d, %-m and %-H itself, since strftime's differ by platform.
 - **The default palette is Okabe–Ito.** With 4 or more groups, color_blind's colors ran together in the skill evals: two blues and two greys. Okabe and Ito's palette keeps its first four colors distinct for color-blind readers.
-- **The base theme leaves line widths and marker sizes to the GraphSpec.** Agents in the skill evals needed smaller markers and thinner lines for dense data. Key samples have their own marker size, so shrinking the plot's markers leaves the key readable.
-- **forgegraph_base_2 follows matplotlib's output, not its style sheet's numbers.** matplotlib draws the style's font weight 350 with Source Sans 3 Light, so the theme uses light. Its gaps were measured from matplotlib's output and set to match, since matplotlib measures from text boxes and ForgeGraph from letters.
+- **The default theme leaves marker sizes and opacity to the GraphSpec.** Agents in the skill evals needed smaller markers for dense data. Key samples have their own marker size, so shrinking the plot's markers leaves the key readable.
 
 ### Names
 
-- **Parameter names follow Vega-Lite where a standard term exists** (encoding, mark, detail), keeping ForgeGraph's nesting, snake_case and units. A third of the parameters have no Vega-Lite equivalent, so its names weren't adopted wholesale. "Legend" is the umbrella for every way of naming what colors and styles mean, as in Vega-Lite.
+- **Parameter names follow Vega-Lite where a standard term exists** (axis, legend, aggregation), keeping ForgeGraph's nesting, snake_case and units. A third of the parameters have no Vega-Lite equivalent, so its names weren't adopted wholesale. "Legend" is the umbrella for every way of naming what colors and styles mean, as in Vega-Lite.
 - **Every size is × figure.base_size,** so a theme draws correctly in any format.
 - **The command is `forgegraph`.** `fg` is a built-in command in bash and zsh, and a shell runs its built-in before any program of that name.
 - **A tab's name is what its tab shows.** File names and links use it lowercased, with spaces as hyphens, so there's no separate label to keep in step.

forgegraph-0.4.0/docs/packs/acme/formats/slide.md

@@ -0,0 +1,14 @@
+# Pack example: acme/slide, a format
+
+This page mirrors examples/packs/acme/formats/slide.yaml, which is the specification. A test fails if they ever differ.
+
+name: slide          *# \[text\]; The name of the format.*\
+version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
+description: A full-width graph on a 16:9 slide.          *# \[text\]; The description of the format.*\
+extends: forgegraph_default/compact_format          *# \[None, format\]; Each parameter not listed is inherited from this format. If None, this file must list every parameter.*\
+ \
+parameters:          *# !var/!fix sets whether a GraphSpec or layout may change a property. Subcategories/parameters inherit the setting of the one above them unless explicitly overridden.*\
+    figure:\
+        width: 254          *# \[auto, float > 0\]; The figure's width in mm. auto calculates it from the height and plot_area.aspect_ratio. Width and height can't both be auto.*\
+        height: 143          *# \[auto, float > 0\]; The figure's height in mm. auto calculates it from the width and plot_area.aspect_ratio.*\
+        base_size: 20          *# \[float > 0\]; The base size in points. The sizes of text, lines, ticks and gaps are multiples of it.*

{forgegraph-0.3.0/docs/specs/pack → forgegraph-0.4.0/docs/packs}/acme/graphspecs/polarization-curve.md

@@ -1,36 +1,31 @@
-# Pack example: acme/polarization-curve, a GraphSpec to extend
+# Pack example: acme/polarization-curve, a GraphSpec
 
 This page mirrors examples/packs/acme/graphspecs/polarization-curve.yaml, which is the specification. A test fails if they ever differ.
 
 name: polarization-curve          *# \[text\]; The name of the GraphSpec.*\
-version: 0          *# \[int\]; The version number of the specification.*\
+version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
 description: Acme's polarization curve, cell voltage against current density, one line per cell.          *# \[text\]; The description of the GraphSpec.*\
 extends: None          *# \[None, graphspec\]; Each parameter not listed is inherited from this GraphSpec. If None, this file must list every parameter.*\
  \
-fixed_parameters: None          *# List of fixed parameters for the GraphSpec, None if none.*\
- \
-variable_parameters:          *# List of variable parameters for the GraphSpec, None if none.*\
+parameters: !var          *# !var/!fix sets whether a GraphSpec may change a property. Subcategories/parameters inherit the setting of the one above them unless explicitly overridden.*\
     specifications:\
         graph_type: xy          *# \[graph type\]; The graph type.*\
         theme: acme/acme          *# \[theme\]; The theme.*\
         format: acme/slide          *# \[format\]; The format.*\
     text:\
-        title: None          *# \[None, text\]; Graph title. None: none.*\
+        title: None          *# \[None, text\]; The graph's title. If None, there is no title.*\
     data:\
-        file: None          *# \[None, text\]; Parquet file holding the DataFrame to draw. None: passed through the Python API.*\
-        preprocessing: None          *# \[None, text\]; Where the code that made the data is. None: not given.*\
+        file: None          *# \[None, text\]; The Parquet file holding the DataFrame to draw. If None, the DataFrame is passed through the Python API.*\
+        preprocessing: None          *# \[None, text\]; Where the code that made the data is. If None, it's not given.*\
     axis:\
         x:\
             data:\
-                column: Current density (mA/cm²)          *# \[column\]; Horizontal axis column.*\
-            title: "Current density (mA/cm^2)"          *# \[None, column_name, text\]; Axis title.*\
+                column: Current density (mA/cm²)          *# \[None, column\]; The column on this axis when it's arrangement.base_axis.*\
+            title: "Current density (mA/cm^2)"          *# \[None, column_name, text\]; The axis title.*\
         y:\
-            data:\
-                column: Cell voltage (V)          *# \[columns\]; Vertical axis column.*\
-            title: column_name          *# \[None, column_name, text\]; Axis title.*\
-    encoding:\
-        color:\
-            column: Cell          *# \[None, column_name, column\]; A color per value of this column.*\
-    mark:\
-        marker:\
-            show: true          *# \[true, false\]; Draw markers.*
+            title: column_name          *# \[None, column_name, text\]; The axis title.*\
+    series:\
+        Cell voltage (V):\
+            color: Cell          *# \[series, hex color, column\]; The series' color.*\
+            marker:\
+                show: true          *# \[true, false\]; Whether to draw markers.*