dataface 0.1.2__py3-none-any.whl

dataface/agent_api/docs/yaml-reference.md

@@ -0,0 +1,2757 @@
+# Dataface YAML Schema Reference
+
+<a id="face"></a>
+## Face
+AuthoredFace (dataface) definition from YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `title` | str | ✓ | Dashboard title displayed at the top. |
+| `description` | str | ✓ | Description text for the dashboard. |
+| `tags` | list[str] | ✓ | Tags for categorization and search. |
+| `docs` | str | ✓ | Relative path under the docs site for the canonical doc page that explains this face. Surfaced as a 'Docs →' link in the playground gallery when DFT_DOCS_URL is set. |
+| `text` | str | ✓ | Markdown text content for text-only sections. |
+| `sources` | [SourcesSection](#sourcessection) | ✓ | Database source configuration. Use 'default:' to set the default source for all queries. |
+| `source` | str | ✓ | Default source name shorthand (equivalent to sources.default). Sets the connection for all queries. |
+| `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
+| `queries` | dict[str, [Query](#query) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
+| `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions referenced in the layout. |
+| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
+| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
+| `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid style layout with explicit row/column placement. |
+| `tabs` | [TabLayout](#tablayout) | ✓ | Tabbed navigation layout where each tab contains its own layout. |
+| `card_gap` | bool | ✓ | When True, adds gap between cards. Default: cards are edge-to-edge (0 gap). |
+| `chart_focus` | str | ✓ | Render only this named chart with its dependent variables (useful for embedding or SVG export). |
+| `details` | [FaceDetails](#facedetails) | ✓ | Collapsible section metadata. String shorthand: details: 'text' → FaceDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}. |
+| `id` | str | ✓ | Explicit ID for this face. Auto-generated from filename if omitted. |
+| `style` | [Style](#style) | ✓ | Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces. |
+| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). |
+| `height` | str \| int | ✓ | Height when nested (e.g., '300px' or an integer in pixels). |
+| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
+| `theme` | str | ✓ | Theme name (e.g., 'editorial', 'cream', 'stark'). |
+
+<a id="sourcessection"></a>
+## SourcesSection
+Sources section for faces.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `default` | str | ✓ | Default source name used for all queries that don't specify a source. |
+| `<name>` | [PostgresSourceConfig](#postgressourceconfig) \| [SnowflakeSourceConfig](#snowflakesourceconfig) \| [BigQuerySourceConfig](#bigquerysourceconfig) \| [RedshiftSourceConfig](#redshiftsourceconfig) \| [MySQLSourceConfig](#mysqlsourceconfig) \| [DuckDBSourceConfig](#duckdbsourceconfig) \| [CsvSourceConfig](#csvsourceconfig) \| [ParquetSourceConfig](#parquetsourceconfig) \| [JsonSourceConfig](#jsonsourceconfig) \| [HttpSourceConfig](#httpsourceconfig) \| [DbtProfileSourceConfig](#dbtprofilesourceconfig) | ✓ | Additional named entry. |
+
+<a id="variable"></a>
+## Variable
+Variable definition from YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `input` | enum: "auto", "select", "multiselect", "input", "text", "number", "textarea", "slider", "range", "date", "datepicker", "daterange", "checkbox", "radio" | ✓ | UI control type (select, multiselect, slider, daterange, etc.). 'auto' detects from options. |
+| `label` | str | ✓ | Display label shown above the input control. |
+| `description` | str | ✓ | Help text shown below the input control. |
+| `default` | Any | ✓ | Default value used when no URL param is set. |
+| `placeholder` | str | ✓ | Placeholder text shown in the input when empty. |
+| `required` | bool | ✓ | When True, a value must be provided before queries execute. |
+| `allow_null` | bool | ✓ | When True, 'null' is a valid selection (useful for optional filters). |
+| `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
+| `disabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Disable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. Absent variable in a string expression raises (use a default). |
+| `column` | str | ✓ | Column name in the query result to use as option values. |
+| `query` | str \| dict[str, Any] | ✓ | Query name or inline query definition for populating options. |
+| `dimension` | str | ✓ | MetricFlow dimension name for populating options. |
+| `measure` | str | ✓ | MetricFlow measure name for populating options. |
+| `model` | str | ✓ | dbt model name for populating options. |
+| `options` | [VariableOptions](#variableoptions) | ✓ | Static or query-driven option list configuration. |
+| `data_type` | str | ✓ | Upstream data-type hint preserved through migrations (e.g. 'string', 'number'). Informational; not currently consumed at compile time. |
+| `min` | int \| float | ✓ | Minimum value for slider/range inputs. |
+| `max` | int \| float | ✓ | Maximum value for slider/range inputs. |
+| `step` | int \| float | ✓ | Step size for slider/range inputs. |
+| `operator` | str | ✓ | SQL operator used when generating filter expressions (e.g., '=', 'IN', 'LIKE'). |
+
+<a id="query"></a>
+## Query
+AuthoredQuery definition from YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema_resolver" | ✓ | Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema_resolver. |
+| `source` | str \| dict[str, Any] | ✓ | Database source reference (name string) or inline source config dict. |
+| `target` | str | ✓ | dbt target name for dbt_model queries (defaults to 'dev'). |
+| `sql` | str | ✓ | SQL query string. Supports Jinja2 templates referencing variables. |
+| `setup_sql` | str | ✓ | Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION). |
+| `metrics` | list[str] | ✓ | MetricFlow metric names to query. |
+| `dimensions` | list[str] | ✓ | MetricFlow dimensions to include in the result. |
+| `time_grain` | enum: "day", "week", "month", "quarter", "year" | ✓ | MetricFlow time grain for time-series dimensions (day, week, month, quarter, year). |
+| `model` | str | ✓ | dbt model name to query directly. |
+| `columns` | list[str] | ✓ | Column subset to select from the dbt model. |
+| `url` | str | ✓ | HTTP endpoint URL for REST API queries. |
+| `method` | enum: "GET", "POST", "PUT", "DELETE", "PATCH" | ✓ | HTTP method for REST API queries (GET, POST, PUT, DELETE, PATCH). |
+| `headers` | dict[str, str] | ✓ | HTTP request headers for REST API queries. |
+| `params` | dict[str, Any] | ✓ | HTTP query string parameters for REST API queries. |
+| `body` | dict[str, Any] \| str | ✓ | HTTP request body for POST/PUT queries. |
+| `json_path` | str | ✓ | JSONPath expression to extract tabular data from HTTP response (http queries only). |
+| `file` | str | ✓ | Path to a CSV file for csv-type queries. |
+| `filter` | dict[str, Any] | ✓ | Row-level filter applied to CSV or values data. |
+| `delimiter` | str | ✓ | Column delimiter for CSV queries. Default: comma (','). |
+| `encoding` | str | ✓ | File encoding for CSV queries. Default: UTF-8. |
+| `schema` | str | ✓ | Schema name for schema_resolver queries (YAML key: schema). |
+| `table` | str | ✓ | Table name for schema_resolver queries. |
+| `column` | str | ✓ | Column name for schema_resolver queries. |
+| `rows` | list[dict[str, Any]] | ✓ | Inline data rows for values-type queries (list of row dicts). |
+| `values` | list[list[Any]] | ✓ | Inline column-oriented data for values-type queries (list of lists). |
+| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
+| `filters` | dict[str, Any] | ✓ | Jinja2 filter expressions applied to query results. |
+| `limit` | int | ✓ | Maximum number of rows returned. |
+| `pivot` | [Pivot](#pivot) | ✓ | Cross-tab pivot hint: transforms long-form SQL output into a wide table at render time (table consumers only). Does not affect SQL execution. |
+| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']). |
+
+<a id="barchart"></a>
+## BarChart
+Authored patch for bar and histogram charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "bar", "histogram" |  | Bar or histogram chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `size` | str | ✓ | Field used to size-encode data points (quantitative). |
+| `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
+| `style` | [BarChartStyle](#barchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="linechart"></a>
+## LineChart
+Authored patch for line charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "line" |  | Line chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `style` | [LineChartStyle](#linechartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="areachart"></a>
+## AreaChart
+Authored patch for area charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "area" |  | Area chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `size` | str | ✓ | Field used to size-encode data points (quantitative). |
+| `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
+| `style` | [AreaChartStyle](#areachartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="scatterchart"></a>
+## ScatterChart
+Authored patch for scatter charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "scatter" |  | Scatter chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `size` | str | ✓ | Field used to size-encode data points (quantitative). |
+| `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
+| `style` | [ScatterChartStyle](#scatterchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="heatmapchart"></a>
+## HeatmapChart
+Authored patch for heatmap charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "heatmap" |  | Heatmap chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `size` | str | ✓ | Field used to size-encode data points (quantitative). |
+| `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
+| `style` | [HeatmapChartStyle](#heatmapchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="piechart"></a>
+## PieChart
+Authored patch for pie and donut charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "pie", "donut" |  | Pie or donut chart type. |
+| `theta` | str |  | Field for angular encoding in pie (arc) charts. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `total` | [ChartTotal](#charttotal) | ✓ | Donut center total. |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `style` | [PieChartStyle](#piechartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="kpichart"></a>
+## KpiChart
+Authored patch for KPI (key performance indicator) charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "kpi" |  | KPI chart type. |
+| `value` | str |  | Column reference (string column name) for the headline number/text. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `label` | str | ✓ | KPI label rendered above the headline value. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format applied to the headline value: D3 format string, preset name, or FormatConfig object. |
+| `support` | [KpiSupportConfig](#kpisupportconfig) | ✓ | Optional support line beneath the KPI value. |
+| `style` | [KpiChartStyle](#kpichartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="tablechart"></a>
+## TableChart
+Authored patch for table charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "table" |  | Table chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `style` | [TableChartStyle](#tablechartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="pointmapchart"></a>
+## PointMapChart
+Authored patch for point_map and bubble_map charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "point_map", "bubble_map" |  | Point map or bubble map chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `projection` | str \| Projection | ✓ | Map projection name or Vega-Lite projection config. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `geo` | str \| dict[str, Any] | ✓ | GeoJSON field name or inline GeoJSON spec for geoshape charts. |
+| `geo_source` | str | ✓ | Named geographic data source for loading GeoJSON boundaries. |
+| `lookup` | str | ✓ | Data field to join against geographic data (map join key). |
+| `value` | str | ✓ | Data field mapped to the fill color. |
+| `latitude` | str | ✓ | Field containing latitude values for point/bubble maps. |
+| `longitude` | str | ✓ | Field containing longitude values for point/bubble maps. |
+| `size` | str | ✓ | Data field used to scale bubble radius (quantitative). Only meaningful on bubble_map. |
+| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Tile-layer configuration for the map background. |
+| `style` | [PointMapChartStyle](#pointmapchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="geoshapechart"></a>
+## GeoshapeChart
+Authored patch for map and geoshape charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "map", "geoshape" |  | Map or geoshape chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `projection` | str \| Projection | ✓ | Map projection name or Vega-Lite projection config. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `geo` | str \| dict[str, Any] | ✓ | GeoJSON field name or inline GeoJSON spec for geoshape charts. |
+| `geo_source` | str | ✓ | Named geographic data source for loading GeoJSON boundaries. |
+| `lookup` | str | ✓ | Data field to join against geographic data (map join key). |
+| `value` | str | ✓ | Data field mapped to the fill color. |
+| `latitude` | str | ✓ | Field containing latitude values for point/bubble maps. |
+| `longitude` | str | ✓ | Field containing longitude values for point/bubble maps. |
+| `style` | [GeoshapeChartStyle](#geoshapechartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="layeredchart"></a>
+## LayeredChart
+Authored patch for layered multi-mark charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "layered" |  | Layered chart type. |
+| `layers` | list[[Layer](#layer)] |  | Layers for multi-mark charts. Each layer is a chart definition. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | Shared X-axis field name for all layers. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration for the shared X axis. |
+| `x_domain` | enum: "union", "primary" | ✓ | Controls how x-values from multiple layer queries are combined. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached to the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format override. |
+| `style` | [LayeredChartStyle](#layeredchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="calloutchart"></a>
+## CalloutChart
+Static callout/message chart. Minimal — no chrome, no styling, no query.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "callout" |  | Callout chart type. |
+| `message` | str |  | Static message content. |
+| `title` | str | ✓ | Optional chart title shown above the message. |
+| `style` | [CalloutChartStyle](#calloutchartstyle) | ✓ | Chart-local style overrides (tone). |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+
+<a id="sparkbarchart"></a>
+## SparkBarChart
+Authored patch for spark_bar charts (compact horizontal bars).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "spark_bar" |  | SparkBar chart type. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis (label) field name. |
+| `y` | str \| list[str] | ✓ | Y-axis (value) field name(s). |
+| `style` | [SparkBarChartStyle](#sparkbarchartstyle) | ✓ | Chart-local style overrides. |
+
+<a id="foreachitem"></a>
+## ForeachItem
+Top-level foreach construct in a layout list.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `foreach` | [ForeachConfig](#foreachconfig) | foreach loop configuration with query, as, and items. |
+
+<a id="gridlayout"></a>
+## GridLayout
+Grid layout configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `items` | list[[GridItem](#griditem)] |  | List of grid items with position and span configuration. |
+| `columns` | int | ✓ | Number of grid columns (default: 24). |
+| `row_height` | str | ✓ | Default row height as a CSS value (e.g., '200px'). |
+| `gap` | enum: "sm", "md", "lg", "xl" | ✓ | Gap between grid cells (sm, md, lg, xl). |
+| `default_width` | int | ✓ | Default column span for items that don't specify width. |
+| `default_height` | int | ✓ | Default row span for items that don't specify height. |
+
+<a id="tablayout"></a>
+## TabLayout
+Tab layout configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `items` | list[[TabItem](#tabitem)] |  | List of tab items. |
+| `id` | str | ✓ | Variable name and URL param base for tab selection (auto-generated if omitted). |
+| `position` | enum: "top", "left" | ✓ | Tab bar position (top or left). |
+| `default` | str | ✓ | Default tab title to activate on load. |
+
+<a id="facedetails"></a>
+## FaceDetails
+Collapsible section metadata for a face.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `summary` | str |  | Label shown when the section is collapsed. |
+| `expanded_title` | str | ✓ | Label shown when the section is expanded. Defaults to summary. |
+| `expanded` | bool | ✓ | Whether the section is open by default. |
+
+<a id="style"></a>
+## Style
+Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `board` | [BoardStyle](#boardstyle) | ✓ | Face-level structural board dimensions. |
+| `background` | str | ✓ | Working-surface background color (board and card fills). |
+| `accent` | str | ✓ | Accent color token cascaded to sparklines, bars, and focus rings. |
+| `muted` | str | ✓ | Muted color token cascaded to spark backgrounds and bar tracks. |
+| `font` | [RootFontStyle](#rootfontstyle) | ✓ | Root font configuration including emoji mode. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Default border style cascaded to all chart cards. |
+| `box_shadow` | str | ✓ | CSS box shadow for chart cards; None means no shadow. |
+| `opacity` | float | ✓ | Default mark opacity (0–1). |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Board and face title style. |
+| `text` | [TextStyle](#textstyle) | ✓ | Markdown and plain text content style. |
+| `placeholder` | [PlaceholderStyle](#placeholderstyle) | ✓ | Placeholder overlay style for empty charts. |
+| `charts` | [ChartsStyle](#chartsstyle) | ✓ | Root of all chart-type styles and shared chart configuration. |
+| `layout` | [LayoutStyle](#layoutstyle) | ✓ | Layout container styles (rows, cols, grid, tabs, details). |
+| `variables` | [VariablesStyle](#variablesstyle) | ✓ | Variable controls chrome style. |
+| `page` | [PageStyle](#pagestyle) | ✓ | Page-level canvas style (behind the board). |
+| `formats` | dict[str, str] | ✓ | Format alias map; None means no aliases at this cascade level. |
+| `palettes` | dict[str, str] | ✓ | Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, negative, positive, warning, category, sequence, diverge. |
+| `roles` | dict[str, str] | ✓ | Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading |
+| `padding` | [SpacingValues](#spacingvalues) | ✓ | Per-face padding override (CSS shorthand or structured). |
+| `margin` | [SpacingValues](#spacingvalues) | ✓ | Per-face margin override (CSS shorthand or structured). |
+| `gap` | float | ✓ | Per-face gap between layout items in pixels. |
+| `color` | str | ✓ | Per-face text color override as a CSS color string. |
+
+<a id="singlerowboolprobe"></a>
+## SingleRowBoolProbe
+Single-row boolean query probe.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `query` | str | Name of the query to execute. |
+| `column` | str | Column in the single result row holding the boolean value. |
+
+<a id="postgressourceconfig"></a>
+## PostgresSourceConfig
+Postgres source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "postgres" |  | Source type identifier. |
+| `host` | str |  | Database host name or IP address. |
+| `dbname` | str |  | Database name (matches dbt 'dbname'). |
+| `user` | str |  | Database user name. |
+| `password` | str |  | Database password. |
+| `port` | int | ✓ | Database port number. |
+| `schema` | str | ✓ | Default schema for queries. |
+
+<a id="snowflakesourceconfig"></a>
+## SnowflakeSourceConfig
+Snowflake source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "snowflake" |  | Source type identifier. |
+| `account` | str |  | Snowflake account identifier (e.g. xy12345.us-east-1). |
+| `user` | str |  | Snowflake user name. |
+| `database` | str |  | Snowflake database name. |
+| `warehouse` | str |  | Snowflake virtual warehouse name. |
+| `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
+| `schema` | str | ✓ | Default schema for queries. |
+| `role` | str | ✓ | Snowflake role to assume for the session. |
+
+<a id="bigquerysourceconfig"></a>
+## BigQuerySourceConfig
+BigQuery source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "bigquery" |  | Source type identifier. |
+| `project` | str |  | GCP project ID. |
+| `dataset` | str |  | BigQuery dataset name (equivalent to schema). |
+| `keyfile` | str | ✓ | Path to service account JSON key file. |
+| `keyfile_json` | dict[str, Any] | ✓ | Inline service account JSON dict. |
+| `location` | str | ✓ | Dataset location (e.g. US, EU). |
+| `method` | enum: "oauth", "service-account", "service-account-json" | ✓ | dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise. |
+
+<a id="redshiftsourceconfig"></a>
+## RedshiftSourceConfig
+Redshift source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "redshift" |  | Source type identifier. |
+| `host` | str |  | Redshift cluster host name. |
+| `dbname` | str |  | Redshift database name. |
+| `user` | str |  | Redshift user name. |
+| `password` | str |  | Redshift password. |
+| `port` | int | ✓ | Redshift port number. |
+| `schema` | str | ✓ | Default schema for queries. |
+
+<a id="mysqlsourceconfig"></a>
+## MySQLSourceConfig
+MySQL source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "mysql" |  | Source type identifier. |
+| `host` | str |  | MySQL host name or IP address. |
+| `database` | str |  | MySQL database name. |
+| `user` | str |  | MySQL user name. |
+| `password` | str |  | MySQL password. |
+| `port` | int | ✓ | MySQL port number. |
+| `schema` | str | ✓ | Default schema for queries. |
+
+<a id="duckdbsourceconfig"></a>
+## DuckDBSourceConfig
+DuckDB source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "duckdb" |  | Source type identifier. |
+| `path` | str | ✓ | DuckDB file path or ':memory:' for an in-memory database. |
+| `schema` | str | ✓ | Default schema for unqualified table names (sets search_path). |
+
+<a id="csvsourceconfig"></a>
+## CsvSourceConfig
+CSV file source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "csv" |  | Source type identifier. |
+| `file` | str | ✓ | Local path to the CSV file. |
+| `url` | str | ✓ | Remote URL of the CSV file. |
+| `headers` | dict[str, str] | ✓ | HTTP headers for authenticated URLs. |
+| `delimiter` | str | ✓ | Field delimiter character. |
+| `encoding` | str | ✓ | File encoding. |
+
+<a id="parquetsourceconfig"></a>
+## ParquetSourceConfig
+Parquet file source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "parquet" |  | Source type identifier. |
+| `file` | str | ✓ | Local path to the Parquet file. |
+| `url` | str | ✓ | Remote URL of the Parquet file. |
+| `headers` | dict[str, str] | ✓ | HTTP headers for authenticated URLs. |
+
+<a id="jsonsourceconfig"></a>
+## JsonSourceConfig
+JSON file source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "json" |  | Source type identifier. |
+| `file` | str | ✓ | Local path to the JSON file. |
+| `url` | str | ✓ | Remote URL of the JSON file. |
+| `headers` | dict[str, str] | ✓ | HTTP headers for authenticated URLs. |
+| `json_path` | str | ✓ | JSONPath expression to extract the data array. |
+
+<a id="httpsourceconfig"></a>
+## HttpSourceConfig
+HTTP/REST API source configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "http" |  | Source type identifier. |
+| `url` | str |  | Base URL for HTTP requests. |
+| `headers` | dict[str, str] | ✓ | Default HTTP headers (e.g. Authorization). |
+
+<a id="dbtprofilesourceconfig"></a>
+## DbtProfileSourceConfig
+Reference to a dbt profile (for backward compatibility).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "dbt_profile" |  | Source type identifier. |
+| `profile` | str |  | dbt profile name from profiles.yml. |
+| `target` | str | ✓ | dbt target to use; defaults to the profile's default target. |
+
+<a id="variableoptions"></a>
+## VariableOptions
+Options configuration for variable inputs.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `static` | list[str \| int \| float] | ✓ | List of static option values (strings or numbers). |
+| `query` | str | ✓ | Query name whose result rows provide option values. |
+| `column` | str | ✓ | Column in the query result to use as option values. |
+| `label_column` | str | ✓ | Column in the query result to use as display labels (separate from values). |
+
+<a id="pivot"></a>
+## Pivot
+Query-level pivot rendering hint for cross-tab table layout.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `column` | str | Dimension whose distinct values become column headers in the cross-tab layout. |
+| `value` | str | Measure that fills each cell in the cross-tab layout. |
+
+<a id="filterdef"></a>
+## FilterDef
+One column→variable binding in chart.filters.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `op` | enum: "eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "not_in", "between" | ✓ | Comparison operator. Defaults to 'eq'. |
+| `var` | str | ✓ | Plain variable name (no Jinja). Set when the filter value is a dashboard variable reference. |
+| `template` | str | ✓ | Jinja template resolved at execute time. Only valid with op='eq'. Set when conditional-disable or complex expressions are needed. |
+
+<a id="fieldconditionalformatting"></a>
+## FieldConditionalFormatting
+Conditional formatting rules scoped to a single column.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `when` | list[[ConditionalRule](#conditionalrule)] | Ordered list of conditional rules. The first matching rule applies; a 'default: true' rule must be last. |
+
+<a id="chartsort"></a>
+## ChartSort
+Chart-level sort configuration for categorical axes.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `by` | str |  | Field name to sort by. |
+| `order` | enum: "asc", "desc" | ✓ | Sort direction (asc or desc). |
+
+<a id="chartlabels"></a>
+## ChartLabels
+Per-row text annotations rendered near each data anchor.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `template` | str |  | Jinja2 template for the label text. Row fields are available as variables. |
+| `where` | str | ✓ | Jinja2 boolean filter expression. Labels only render on rows where this is truthy. |
+
+<a id="chartdatatable"></a>
+## ChartDataTable
+Container for a chart's data_table block.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entries` | list[[ChartDataTableSource](#chartdatatablesource) \| [ChartDataTableAggregate](#chartdatatableaggregate) \| [ChartDataTablePerSeries](#chartdatatableperseries)] | List of data-table entries (source, aggregate, or per-series rows). |
+
+<a id="formatconfig"></a>
+## FormatConfig
+Format configuration for value display.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `spec` | str | ✓ | D3 format string (e.g., ',.0f'), preset name (e.g., 'currency'), or Excel pattern. |
+| `prefix` | str | ✓ | Custom prefix prepended to the formatted value (e.g., '$'). |
+| `suffix` | str | ✓ | Custom suffix appended to the formatted value (e.g., ' USD', '%'). |
+| `notation` | enum: "analytic", "narrative" | ✓ | Notation style: 'analytic' for SI-prefix (1 B, 1 M) or 'narrative' for prose-style (1bn, 1mn). |
+
+<a id="barchartstyle"></a>
+## BarChartStyle
+Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
+| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; None uses the renderer default (VL stacks by default). |
+| `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color field name. Ignored when stacking is off or no color. |
+| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for bar charts. |
+| `marks` | [BarChartMarksStyle](#barchartmarksstyle) | ✓ | Bar-family mark overrides. |
+
+<a id="linechartstyle"></a>
+## LineChartStyle
+Authored overlay for LineChartStyle. Line chart style: chart-level fields + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for line charts. |
+| `marks` | [LineChartMarksStyle](#linechartmarksstyle) | ✓ | Line-family mark overrides. |
+
+<a id="areachartstyle"></a>
+## AreaChartStyle
+Authored overlay for AreaChartStyle. Area chart style: chart-level fields + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for area charts; False overlaps silhouettes. |
+| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for area charts. |
+| `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | ✓ | Area-family mark overrides. |
+
+<a id="scatterchartstyle"></a>
+## ScatterChartStyle
+Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `marks` | [ScatterChartMarksStyle](#scatterchartmarksstyle) | ✓ | Scatter-family mark overrides. |
+
+<a id="heatmapchartstyle"></a>
+## HeatmapChartStyle
+Authored overlay for HeatmapChartStyle. Heatmap chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `cell_padding` | float | ✓ | Padding between heatmap cells in pixels. |
+| `color_scheme` | str | ✓ | Color scheme name for heatmap gradient (e.g. 'blues', 'viridis'). |
+| `marks` | [HeatmapChartMarksStyle](#heatmapchartmarksstyle) | ✓ | Heatmap-family mark overrides. |
+
+<a id="charttotal"></a>
+## ChartTotal
+Donut center total — opt-in summary at the center of a pie chart.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `label` | str | ✓ | Caption text displayed below the center total value. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format (D3 spec, preset, or FormatConfig). |
+
+<a id="piechartstyle"></a>
+## PieChartStyle
+Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (flat) + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Aspect ratio (width/height) of the pie chart viewport. |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `inner_radius` | float | ✓ | Hole-to-disk ratio 0–1 (inner radius / outer radius). None = solid pie (no hole). |
+| `total` | [TotalStyle](#totalstyle) | ✓ | Donut center total paint (value and label). |
+| `marks` | [PieChartMarksStyle](#piechartmarksstyle) | ✓ | Pie-family mark overrides. |
+
+<a id="kpisupportconfig"></a>
+## KpiSupportConfig
+Support-line block authored alongside a KPI's main value.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `value` | str | ✓ | Column reference (string column name) for the support number/text. |
+| `label` | str | ✓ | Trailing explainer text rendered beside the support value. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format (D3 spec, preset, or FormatConfig). |
+| `glyph` | str | ✓ | Optional prefix glyph (e.g. '▲', '▼', '●'). |
+| `tone` | enum: "positive", "negative", "warning" | ✓ | Semantic styling for the support value/glyph. |
+
+<a id="kpichartstyle"></a>
+## KpiChartStyle
+Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | KPI card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `value` | [KpiValueStyle](#kpivaluestyle) | ✓ | KPI headline value slot. |
+| `label` | [KpiSlotStyle](#kpislotstyle) | ✓ | KPI card label slot. |
+| `affix` | [KpiSlotStyle](#kpislotstyle) | ✓ | Currency/percent affix slot. |
+| `glyph` | [KpiSlotStyle](#kpislotstyle) | ✓ | Indicator glyph (▲▼●) slot. |
+| `min_card_width` | float | ✓ | Minimum KPI card width in pixels. |
+| `default_width` | float | ✓ | Default KPI card width in pixels. |
+| `default_height` | float | ✓ | Default KPI card height in pixels. |
+| `content_padding` | [SpacingValues](#spacingvalues) | ✓ | Inner inset (top/right/bottom/left) for KPI card content in pixels. |
+| `tones` | [KpiTonesStyle](#kpitonesstyle) | ✓ | Semantic tone color palette for KPI values and glyphs. |
+| `tone` | str | ✓ | Semantic tone selector (positive \| negative \| warning). None = default chrome. |
+
+<a id="tablechartstyle"></a>
+## TableChartStyle
+Authored overlay for TableChartStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Table outer border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Table background color; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Table text color override (CSS string) or gradient scale config; None uses the theme default. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `rule` | [TableRuleStyle](#tablerulestyle) | ✓ | Table rule style overrides (color). None = no override; inherits from theme. |
+| `outer_padding` | float | ✓ | Outer table padding in pixels. |
+| `bottom_padding` | float | ✓ | Extra bottom padding below the last row in pixels. |
+| `column_layout` | [TableColumnsStyle](#tablecolumnsstyle) | ✓ | Default column width and cell padding settings. |
+| `header` | [TableHeaderStyle](#tableheaderstyle) | ✓ | Table header row style. |
+| `row` | [TableRowStyle](#tablerowstyle) | ✓ | Table body row style. |
+| `row_numbers` | [TableRowNumbersStyle](#tablerownumbersstyle) | ✓ | Leading row-number column configuration. |
+| `title_row` | [TableTitleStyle](#tabletitlestyle) | ✓ | Table title row style. |
+| `wrap` | bool | ✓ | Allow cell text wrapping; false clips to single line. |
+| `pagination` | [PaginationConfig](#paginationconfig) | ✓ | Client-side pagination defaults for table charts. |
+| `column_defaults` | [TableColumnDefaultsConfig](#tablecolumndefaultsconfig) | ✓ | Table-level column defaults applied to every column; None means no defaults authored. |
+| `columns` | dict[str, Any] | ✓ | Per-column display configuration keyed by column name (label, format, width, etc.). |
+| `header_overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | ✓ | Table column header text overflow mode; None inherits from theme. |
+| `paginator` | [PaginatorStyle](#paginatorstyle) | ✓ | Visual style for the paginator control (chevrons + page numbers). |
+| `symbol_mode` | str | ✓ | Where to show currency-prefix and magnitude/unit suffix symbols in a numeric column. 'all' shows the full formatted value on every row; 'anchors' shows it only on the first data row and summary/total rows, stripping prefix and suffix from plain middle rows so the anchors guide the reader at the top and bottom of the value field. |
+| `more_rows` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the 'more rows' edge-case indicator. |
+| `empty_state` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the empty-state (no data) indicator. |
+| `spark` | [SparkStyle](#sparkstyle) | ✓ | Inline sparkline defaults for table cells. |
+| `text_baseline_offset` | float | ✓ | Vertical offset to align SVG text baseline with cell grid in pixels. |
+| `title_baseline_offset` | float | ✓ | Vertical offset to align SVG title baseline in pixels. |
+| `title_subtitle_gap` | float | ✓ | Gap between table title and subtitle lines in pixels. |
+| `subtitle` | [SubtitleStyle](#subtitlestyle) | ✓ | Table subtitle font-sizing constants. |
+
+<a id="basemapconfig"></a>
+## BasemapConfig
+Tile-layer configuration for point_map and bubble_map charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | str | ✓ | Tile provider type (e.g. 'mapbox', 'raster'). |
+| `style` | str | ✓ | Tile style URL (e.g. Mapbox style URI). |
+| `source` | str | ✓ | Named geographic boundary source (e.g. 'us-states') for overlay rendering. |
+| `attribution` | str | ✓ | Attribution text for the tile provider. |
+| `fill` | str | ✓ | Fill color for geographic boundary overlay. |
+| `stroke` | str | ✓ | Stroke color for geographic boundary overlay. |
+
+<a id="pointmapchartstyle"></a>
+## PointMapChartStyle
+Authored overlay for PointMapChartStyle. Point map chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `projection` | [ProjectionStyle](#projectionstyle) | ✓ | Vega-Lite projection configuration for this geo family. |
+| `basemap` | [BasemapStyle](#basemapstyle) | ✓ | Background map layer; None source = no topo layer. |
+| `marks` | [PointMapChartMarksStyle](#pointmapchartmarksstyle) | ✓ | Point-map-family mark overrides. |
+
+<a id="geoshapechartstyle"></a>
+## GeoshapeChartStyle
+Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `projection` | [ProjectionStyle](#projectionstyle) | ✓ | Vega-Lite projection configuration for this geo family. |
+| `basemap` | [BasemapStyle](#basemapstyle) | ✓ | Background map layer; None source = no topo layer. |
+| `color_scheme` | str | ✓ | Color scheme name for choropleth gradient. |
+| `marks` | [GeoshapeChartMarksStyle](#geoshapechartmarksstyle) | ✓ | Geoshape-family mark overrides. |
+
+<a id="layer"></a>
+## Layer
+A single layer in a layered chart authored YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | str |  | Mark type for this layer (bar, line, area, circle, square, tick, rule, trail, rect, image, scatter). |
+| `query` | str | ✓ | Query name for this layer's data (overrides chart-level query). |
+| `x` | str | ✓ | X-axis field name for this layer. |
+| `y` | str | ✓ | Y-axis field name for this layer. |
+| `label` | str | ✓ | Label field name for this layer. |
+| `color` | str | ✓ | Color data channel for this layer: bare field name only. |
+| `fill` | str | ✓ | Static fill color for this layer (hex string). Use for fixed-color marks; `color` is for data channels. |
+| `size` | str | ✓ | Size channel field name for this layer. |
+| `shape` | str | ✓ | Shape channel field name for this layer. |
+| `axis_y` | [LayerAxisYStyle](#layeraxisystyle) | ✓ | Y-axis settings for this layer (orientation, title). |
+
+<a id="layeredchartstyle"></a>
+## LayeredChartStyle
+Flat style patch for layered multi-mark charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding overrides. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style overrides. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style overrides. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
+| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
+| `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. |
+| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration. |
+| `marks` | [LayeredMarksStyle](#layeredmarksstyle) | ✓ | Per-mark-type style overrides (bar/line/area/point). |
+
+<a id="calloutchartstyle"></a>
+## CalloutChartStyle
+Authored overlay for CalloutChartStyle. Chart-family style for ``type: callout`` charts and runtime chart-error fallback cards.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `tone` | str | ✓ | Semantic tone for palette-role lookup (positive \| negative \| warning). Defaults to negative. |
+| `background` | str | ✓ | Callout card background color (negative.bg default). |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Callout card border style. |
+| `padding` | float | ✓ | Inner padding of the callout card in pixels. |
+| `section_gap` | float | ✓ | Vertical gap between callout title and message in pixels. |
+| `title` | [CalloutElementStyle](#calloutelementstyle) | ✓ | Callout title element style. |
+| `message` | [CalloutElementStyle](#calloutelementstyle) | ✓ | Callout message element style. |
+
+<a id="sparkbarchartstyle"></a>
+## SparkBarChartStyle
+Authored overlay for SparkBarChartStyle. Produced by cascade from theme YAML.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar` | [SparkBarBarStyle](#sparkbarbarstyle) | ✓ | Bar geometry (height, padding, color). |
+| `label` | [SparkBarChartLabelStyle](#sparkbarchartlabelstyle) | ✓ | Category-label column (visibility, reserved width). |
+| `count` | [SparkBarCountStyle](#sparkbarcountstyle) | ✓ | Count-value column (visibility, reserved width). |
+| `max_bars` | int | ✓ | Maximum number of bars to render. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Spark_bar font style overrides. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Spark_bar outer border style. |
+| `subtitle` | [SubtitleStyle](#subtitlestyle) | ✓ | Spark_bar subtitle font-sizing constants. |
+
+<a id="foreachconfig"></a>
+## ForeachConfig
+foreach loop configuration.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `query` | [ForeachQuery](#foreachquery) | Inline data source providing the rows to iterate over. |
+| `as` | str | Variable name bound to each row (accessible as {{ as.field }}). |
+| `items` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | Layout item templates resolved once per data row. |
+
+<a id="griditem"></a>
+## GridItem
+Grid layout item with position and span.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `item` | str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)] |  | Chart name or inline chart/face definition to place in this grid cell. |
+| `col` | int | ✓ | Column position (0-indexed). Auto-placed if omitted. |
+| `row` | int | ✓ | Row position (0-indexed). Auto-placed if omitted. |
+| `col_span` | int | ✓ | Number of columns to span (width in grid units). |
+| `row_span` | int | ✓ | Number of rows to span (height in grid units). |
+| `width` | int | ✓ | Alias for col_span (more intuitive name). |
+| `height` | int | ✓ | Alias for row_span (more intuitive name). |
+| `description` | str | ✓ | Optional metadata for AI search and context tooltips. |
+
+<a id="tabitem"></a>
+## TabItem
+Tab layout item.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `title` | str |  | Tab label displayed in the tab bar. |
+| `icon` | str | ✓ | Optional icon shown in the tab (e.g., emoji or icon name). |
+| `description` | str | ✓ | Optional metadata for AI search and context tooltips. |
+| `text` | str | ✓ | Markdown text content shown in this tab. |
+| `style` | [Style](#style) | ✓ | Style patch for this tab's content area. |
+| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout for this tab's content. |
+| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout for this tab's content. |
+| `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid layout for this tab's content. |
+| `tabs` | [TabLayout](#tablayout) | ✓ | Nested tab layout (tabs within tabs). |
+
+<a id="boardstyle"></a>
+## BoardStyle
+Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascade to child faces.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Board width in pixels. |
+| `default_height` | float | ✓ | Default row height in pixels. |
+| `min_height` | float | ✓ | Minimum row height in pixels. |
+| `margin` | float | ✓ | Board outer margin in pixels. |
+| `card_padding` | float | ✓ | Padding added to each card side in pixels. |
+| `card_gap` | float | ✓ | Gap between cards in pixels. |
+
+<a id="rootfontstyle"></a>
+## RootFontStyle
+Authored overlay for RootFontStyle. Root-level font configuration: FontStyle fields plus a required emoji mode.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `family` | str | ✓ | Font family name (e.g., 'sans-serif', 'Roboto'). |
+| `color` | str | ✓ | Text color as a CSS color string. |
+| `size` | float | ✓ | Font size in pixels. |
+| `weight` | str \| float | ✓ | Font weight (e.g., 'bold', 400, 700). |
+| `style` | enum: "normal", "italic" | ✓ | Font style (normal or italic). |
+| `decoration` | enum: "none", "line-through", "underline" | ✓ | Text decoration (underline, line-through, or none). |
+| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | ✓ | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
+| `emoji` | enum: "monochrome", "color", "system-default", "disabled" | ✓ | Emoji rendering mode for the dashboard font stack. |
+
+<a id="borderstyle"></a>
+## BorderStyle
+Box border. Does NOT cascade (ADR-003: box properties reset per level).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `radius` | float | ✓ | Border corner radius in pixels. |
+| `color` | str | ✓ | Border color (CSS color string). |
+| `width` | float | ✓ | Border width in pixels. |
+
+<a id="titlestyle"></a>
+## TitleStyle
+Authored overlay for TitleStyle. Board and face titles.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Title font style overrides. |
+| `line_height` | float | ✓ | Line height multiplier for titles and markdown headings. Headings typically want a tighter multiplier than body prose (~1.1-1.25 vs the body 1.5-1.6). |
+| `sizes` | list[float] | ✓ | Font sizes for the H1–H6 heading ramp, indexed by ``face.level - 1``. Combined with ``width_offsets`` at render time to size titles responsively by card width. |
+| `width_offsets` | [TitleWidthOffsetsStyle](#titlewidthoffsetsstyle) | ✓ | Additive level offsets by card width (tiny/narrow/medium/wide). Added to the title's base level before indexing ``sizes``. Consumed by chart_title_spec / face_title_spec. |
+| `min_height` | float | ✓ | Minimum title row height in pixels. |
+| `overflow` | str | ✓ | Text overflow mode (clip, truncate, wrap-two, wrap). |
+| `position` | [TitlePositionStyle](#titlepositionstyle) | ✓ | Vega-Lite title positioning: anchor, angle, offset, baseline. |
+| `level` | enum: "auto" | ✓ | Heading level override for face titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level. |
+| `subtitle` | [TitleSubtitleStyle](#titlesubtitlestyle) | ✓ | Subtitle font styles. |
+
+<a id="textstyle"></a>
+## TextStyle
+Authored overlay for TextStyle. Markdown / plain text content.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Text font style overrides. |
+| `line_height` | float | ✓ | Line height multiplier for text content. |
+| `align` | enum: "left", "center", "right" | ✓ | Text alignment for the face body-text block. |
+| `column` | [TextColumnStyle](#textcolumnstyle) | ✓ | Multi-column layout for the face body-text block. |
+
+<a id="placeholderstyle"></a>
+## PlaceholderStyle
+Authored overlay for PlaceholderStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Opacity of the placeholder overlay (0–1). |
+| `overlay` | [PlaceholderOverlay](#placeholderoverlay) | ✓ | Overlay text and background style. |
+
+<a id="chartsstyle"></a>
+## ChartsStyle
+Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared chart configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Shared axis style applied to all axes before per-axis overrides. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | X-axis style overrides applied after the shared axis. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Y-axis style overrides applied after the shared axis. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Quantitative axis style overrides applied after axis_x/axis_y. |
+| `view` | [ViewStyle](#viewstyle) | ✓ | Vega-Lite view dimensions and border. |
+| `autosize` | [AutosizeStyle](#autosizestyle) | ✓ | Vega-Lite autosize configuration. |
+| `marks` | [GlobalMarksStyle](#globalmarksstyle) | ✓ | Global mark defaults (tier-1 of the marks cascade). |
+| `bar` | [BarChartStyle](#barchartstyle) | ✓ | Bar chart style. |
+| `line` | [LineChartStyle](#linechartstyle) | ✓ | Line chart style. |
+| `area` | [AreaChartStyle](#areachartstyle) | ✓ | Area chart style. |
+| `scatter` | [ScatterChartStyle](#scatterchartstyle) | ✓ | Scatter chart style. |
+| `histogram` | [HistogramChartStyle](#histogramchartstyle) | ✓ | Histogram chart style. |
+| `heatmap` | [HeatmapChartStyle](#heatmapchartstyle) | ✓ | Heatmap chart style. |
+| `geoshape` | [GeoshapeChartStyle](#geoshapechartstyle) | ✓ | Geoshape (choropleth) chart style. |
+| `point_map` | [PointMapChartStyle](#pointmapchartstyle) | ✓ | Point map chart style. |
+| `boxplot` | [BoxplotChartStyle](#boxplotchartstyle) | ✓ | Boxplot chart style. |
+| `errorbar` | [ErrorbarChartStyle](#errorbarchartstyle) | ✓ | Error bar chart style. |
+| `errorband` | [ErrorbandChartStyle](#errorbandchartstyle) | ✓ | Error band chart style. |
+| `pie` | [PieChartStyle](#piechartstyle) | ✓ | Pie/donut chart style. |
+| `series_label` | [SeriesLabelStyle](#serieslabelstyle) | ✓ | Shared series-label typography for endpoint labels, stack labels, and slice callouts. |
+| `kpi` | [KpiChartStyle](#kpichartstyle) | ✓ | KPI card chart style. |
+| `table` | [TableChartStyle](#tablechartstyle) | ✓ | Table chart style. |
+| `spark_bar` | [SparkBarChartStyle](#sparkbarchartstyle) | ✓ | Spark_bar (full-chart horizontal bar) style. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Attached data_table strip style. |
+| `callout` | [CalloutChartStyle](#calloutchartstyle) | ✓ | Callout chart-family style for type:callout and runtime fallback cards. |
+
+<a id="layoutstyle"></a>
+## LayoutStyle
+Authored overlay for LayoutStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `rows` | [LayoutGapStyle](#layoutgapstyle) | ✓ | Row layout gap configuration. |
+| `cols` | [LayoutGapStyle](#layoutgapstyle) | ✓ | Column layout gap configuration. |
+| `grid` | [GridLayoutStyle](#gridlayoutstyle) | ✓ | Grid layout configuration. |
+| `tabs` | [TabsStyle](#tabsstyle) | ✓ | Tabs layout style. |
+| `details` | [DetailsStyle](#detailsstyle) | ✓ | Details (accordion) layout style. |
+
+<a id="variablesstyle"></a>
+## VariablesStyle
+Authored overlay for VariablesStyle. Variable controls chrome styling.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the variables control panel. |
+| `position` | enum: "top", "bottom", "title-inline" | ✓ | Variables strip placement: stacked under the title (top/bottom) or on one horizontal band with the face title (title-inline). |
+| `gap` | float | ✓ | Gap between variable controls in pixels. |
+| `label_position` | str | ✓ | Position of labels relative to their input controls (e.g. 'left', 'top'). |
+| `title_inline_title_max_width` | float | ✓ | When position is title-inline: max title column width in px. 0 means no cap (title uses remaining width after reserving space for variables). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Variables panel base font style overrides. |
+| `label` | [VariablesLabelStyle](#variableslabelstyle) | ✓ | Variable label typography. |
+| `value` | [VariablesValueStyle](#variablesvaluestyle) | ✓ | Variable value typography. |
+| `placeholder` | [VariablesPlaceholderStyle](#variablesplaceholderstyle) | ✓ | Style for unselected/hint text in variable inputs. |
+| `line_height` | float | ✓ | Line height for variable control text in pixels. |
+| `padding` | float | ✓ | Outer padding around the variables panel in pixels. |
+| `container_height` | float | ✓ | Height of the variables panel container in pixels. |
+| `container_padding` | float | ✓ | Inner padding of the variables panel container in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Variables panel border style. |
+| `control_gap` | float | ✓ | Gap between label and input within a single control in pixels. |
+| `input` | [InputStyle](#inputstyle) | ✓ | Input control style. |
+| `popover_rail_background` | str | ✓ | Background color for the preset rail (left column) inside the daterange chip's popover. Typically the theme's `surface-subtle` step — gray-50 on white-canvas themes, a cream-toned light on warm-canvas themes. Distinct from the popover card itself, which is always white-equivalent. |
+
+<a id="pagestyle"></a>
+## PageStyle
+Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `background` | str | ✓ | Page canvas background color (behind the face board). |
+
+<a id="spacingvalues"></a>
+## SpacingValues
+Pre-parsed CSS spacing (margin/padding).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `top` | float | ✓ | Top spacing in pixels. |
+| `right` | float | ✓ | Right spacing in pixels. |
+| `bottom` | float | ✓ | Bottom spacing in pixels. |
+| `left` | float | ✓ | Left spacing in pixels. |
+
+<a id="conditionalrule"></a>
+## ConditionalRule
+A single conditional formatting rule.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `eq` | Any | ✓ | Match rows where the column value equals this value. |
+| `ne` | Any | ✓ | Match rows where the column value does not equal this value. |
+| `lt` | int \| float | ✓ | Match rows where the column value is less than this number. |
+| `lte` | int \| float | ✓ | Match rows where the column value is less than or equal to this number. |
+| `gt` | int \| float | ✓ | Match rows where the column value is greater than this number. |
+| `gte` | int \| float | ✓ | Match rows where the column value is greater than or equal to this number. |
+| `between` | list[int \| float] | ✓ | Match rows where the column value falls in [low, high] (inclusive). |
+| `in` | list[Any] | ✓ | Match rows where the column value is in this list. |
+| `is_null` | bool | ✓ | Match null rows (true) or non-null rows (false). |
+| `default` | enum: "True" | ✓ | Catch-all rule that matches any row not matched by earlier rules. Must be the last entry. |
+| `background` | str | ✓ | Cell background color applied when the rule matches. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Font style overrides (color, weight, style, decoration) applied when the rule matches. |
+| `glyph` | str | ✓ | Glyph character prepended to the cell value when the rule matches. |
+| `glyph_color` | str | ✓ | Color for the glyph when the rule matches. Requires glyph to be set. |
+
+<a id="chartdatatablesource"></a>
+## ChartDataTableSource
+A data_table row that reads a column's raw per-x value.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `source` | str |  | Query column the row reads from (per-x raw value). |
+| `format` | str | ✓ | D3-style format string (Vega-Lite format parity). Optional. |
+| `label` | str | ✓ | Left-stub row label. Optional. |
+
+<a id="chartdatatableaggregate"></a>
+## ChartDataTableAggregate
+A data_table row that reads an aggregate of a column grouped by x.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `aggregate` | enum: "sum", "avg", "min", "max", "median", "count", "count_distinct" |  | Aggregate operation applied per x-group. One of: sum, avg, min, max, median, count, count_distinct. Exact names only — no aliases (spec G4). |
+| `source` | str |  | Query column being aggregated. Always required alongside `aggregate:` (spec G2). |
+| `format` | str | ✓ | D3-style format string for the aggregated value. |
+| `label` | str | ✓ | Column header label override for this row. |
+
+<a id="chartdatatableperseries"></a>
+## ChartDataTablePerSeries
+A data_table entry that expands into one row per color: series.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `per_series` | str |  | Query column the row reads from (per-x, per-series value). |
+| `by_measure` | bool | ✓ | When True, expand one row reading the named measure field directly (no color: groupby). Required for multi-y charts where each measure is its own y-field rather than a color-encoded series. |
+| `label` | str | ✓ | Row label displayed in the strip's label gutter. When None and by_measure=True, the per_series field name is used. Has no effect when by_measure=False (series name is the label). |
+| `format` | str | ✓ | D3-style format string (Vega-Lite format parity). Optional. |
+
+<a id="fontstyle"></a>
+## FontStyle
+Text appearance. Cascades as a unit (ADR-005: color inside font).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `family` | str | ✓ | Font family name (e.g., 'sans-serif', 'Roboto'). |
+| `color` | str | ✓ | Text color as a CSS color string. |
+| `size` | float | ✓ | Font size in pixels. |
+| `weight` | str \| float | ✓ | Font weight (e.g., 'bold', 400, 700). |
+| `style` | enum: "normal", "italic" | ✓ | Font style (normal or italic). |
+| `decoration` | enum: "none", "line-through", "underline" | ✓ | Text decoration (underline, line-through, or none). |
+| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | ✓ | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
+
+<a id="paddingstyle"></a>
+## PaddingStyle
+Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides required; theme YAML supplies defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `left` | float | ✓ | Left padding in pixels. |
+| `right` | float | ✓ | Right padding in pixels. |
+| `top` | float | ✓ | Top padding in pixels. |
+| `bottom` | float | ✓ | Bottom padding in pixels. |
+
+<a id="inferencestyle"></a>
+## InferenceStyle
+Authored overlay for InferenceStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `infer_zero_when_missing` | bool | ✓ | Auto-infer zero-baseline when not authored. |
+| `infer_fields_when_missing` | bool | ✓ | Auto-infer chart fields (x, y, etc.) when not authored. |
+| `infer_type_when_auto` | bool | ✓ | Auto-infer chart type when type is 'auto'. |
+
+<a id="legendstyle"></a>
+## LegendStyle
+Authored overlay for LegendStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `orient` | str | ✓ | Legend orientation (e.g. 'right', 'bottom'). |
+| `direction` | str | ✓ | Legend layout direction ('vertical' or 'horizontal'). |
+| `label` | [LegendElementStyle](#legendelementstyle) | ✓ | Legend label style. |
+| `title` | [LegendElementStyle](#legendelementstyle) | ✓ | Legend title style. |
+| `disable` | bool | ✓ | Suppress the legend entirely; None means legend is visible. |
+| `interactive_legend` | bool | ✓ | Emit a dft_legend point-selection param for single-click series toggle. |
+
+<a id="tooltipstyle"></a>
+## TooltipStyle
+Authored overlay for TooltipStyle. Tooltip rendering defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `format` | str | ✓ | Default tooltip value format string; theme always provides this. |
+
+<a id="stylecolorconfig"></a>
+## StyleColorConfig
+Chart-local style color: gradient scale for the color channel.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `scale` | [ScaleTargetConfig](#scaletargetconfig) | Continuous color scale applied to the chart's color channel. |
+
+<a id="axisstyle"></a>
+## AxisStyle
+Authored overlay for AxisStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `grid` | [AxisGridStyle](#axisgridstyle) | ✓ | Grid line style for this axis. |
+| `domain` | [AxisDomainStyle](#axisdomainstyle) | ✓ | Domain line style for this axis. |
+| `ticks` | [AxisTicksStyle](#axisticksstyle) | ✓ | Tick mark style for this axis. |
+| `label` | [AxisElementStyle](#axiselementstyle) | ✓ | Axis label style. |
+| `title` | [AxisElementStyle](#axiselementstyle) | ✓ | Axis title style. |
+| `orient` | enum: "left", "right", "top", "bottom", "auto" | ✓ | Axis orientation; auto flips y-axis when endpoint labels are present. |
+| `categorical_orient` | str | ✓ | Orientation for categorical y-axis (e.g. 'left'); None skips this VL property. |
+| `band_position` | float | ✓ | Band position within the step (0–1); None uses Vega-Lite's default. |
+| `offset` | float | ✓ | Pixel offset of the axis from its default position; None means no offset. |
+| `format` | str | ✓ | Tick value format string; None uses auto-format. |
+| `values` | list | ✓ | Explicit tick values; None uses Vega-Lite's auto tick values. |
+| `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | ✓ | Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Per-axis scale overrides; None means no override. |
+| `type` | enum: "auto", "ordinal", "temporal" | ✓ | Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain. |
+| `fill` | enum: "null", "zero", "linear", "step-after", "step-before", "step-center", "curve" | ✓ | Fill for synthesized missing-bucket rows: null, zero, linear, step-after / step-before / step-center (Looker step), or curve (smoothstep). |
+
+<a id="scalestyle"></a>
+## ScaleStyle
+Authored overlay for ScaleStyle. Scale configuration primitive.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `band_padding_inner` | float | ✓ | Inner padding fraction for band scales; None uses Vega-Lite's default. |
+| `band_padding_outer` | float | ✓ | Outer padding fraction for band scales; None uses Vega-Lite's default. |
+| `point_padding` | float | ✓ | Padding fraction for point scales; None uses Vega-Lite's default. |
+| `rect_band_padding_inner` | float | ✓ | Inner padding fraction for rect band scales; None uses Vega-Lite's default. |
+| `round` | bool | ✓ | Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding). |
+| `zero` | bool | ✓ | Force scale to include zero; None uses Vega-Lite's default. |
+| `clamp` | bool | ✓ | Clamp values to scale domain; None uses Vega-Lite's default (no clamping). |
+| `continuous_padding` | float | ✓ | Padding in pixels for continuous scales; None uses Vega-Lite's default. |
+| `band` | [ScaleBandStyle](#scalebandstyle) | ✓ | Band mark size constraints; None uses Vega-Lite's defaults. |
+| `quantile_count` | int | ✓ | Number of quantile buckets; None uses Vega-Lite's default. |
+| `quantize_count` | int | ✓ | Number of quantize buckets; None uses Vega-Lite's default. |
+| `use_unaggregated_domain` | bool | ✓ | Use unaggregated domain for scale extent; None uses Vega-Lite's default. |
+| `x_reverse` | bool | ✓ | Reverse the x-axis scale direction; None means no reversal. |
+| `type` | str | ✓ | Scale type override; None lets Vega-Lite infer from field type. |
+| `domain` | list | ✓ | Explicit scale domain values; None lets Vega-Lite auto-determine from data. |
+| `nice` | bool | ✓ | Round scale domain to nice values; None uses Vega-Lite's default. |
+| `padding` | float | ✓ | Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type. |
+
+<a id="datatablestyle"></a>
+## DataTableStyle
+Authored overlay for DataTableStyle. Attached data_table style. Lives at style.charts.data_table.*.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Data_table font style overrides. |
+| `divider` | [RuleStyle](#rulestyle) | ✓ | Rule at the boundary between the chart plot and the data strip. For position='bottom': rule sits above the strip (below the axis). For position='top': rule sits below the strip rows (above the plot top). |
+| `row` | [DataTableRowStyle](#datatablerowstyle) | ✓ | Data_table row padding and rule style. |
+| `label` | [DataTableLabelStyle](#datatablelabelstyle) | ✓ | Row label (series name) style. |
+| `number_align` | enum: "left", "right", "decimal" | ✓ | Alignment of numeric values in data_table cells. |
+| `padding_top` | float | ✓ | Padding above the topmost strip row in pixels. For position='bottom': gap between axis labels and the first row. For position='top': space above the topmost row (outer edge of strip). |
+| `padding_bottom` | float | ✓ | Padding below the last strip row in pixels. For position='bottom': space below the last row. For position='top': gap between the last row and the plot top edge. |
+| `label_max_lines` | int | ✓ | Number of x-axis label lines to reserve in the axis gap (only used for position='bottom'; ignored for position='top'). Typically 1 or 2. |
+| `position` | enum: "top", "bottom" | ✓ | Strip placement relative to the chart plot. 'top' places the strip above the plot (no x-axis gap needed); 'bottom' places it below with the x-axis between plot and strip. |
+
+<a id="endpointlabelsconfig"></a>
+## EndpointLabelsConfig
+Authored overlay for EndpointLabelsConfig. Endpoint label pane config — shared across line, area, and bar.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show endpoint labels; theme sets false, authors opt in per chart. |
+| `label_offset` | float | ✓ | Spacing in pixels between the chart pane and the label pane. |
+
+<a id="barchartmarksstyle"></a>
+## BarChartMarksStyle
+Authored overlay for BarChartMarksStyle. Bar-family mark overrides. Only bar and text (endpoint labels) are valid.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides for bar charts; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides for bar endpoint labels; None inherits global. |
+
+<a id="linechartmarksstyle"></a>
+## LineChartMarksStyle
+Authored overlay for LineChartMarksStyle. Line-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Line mark overrides; None inherits global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+| `rule` | [RuleMarkStyle](#rulemarkstyle) | ✓ | Rule mark overrides; None inherits global. |
+
+<a id="areachartmarksstyle"></a>
+## AreaChartMarksStyle
+Authored overlay for AreaChartMarksStyle. Area-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `area` | [AreaMarkStyle](#areamarkstyle) | ✓ | Area mark overrides; None inherits global. |
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Top-edge line mark overrides; None inherits global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+
+<a id="scatterchartmarksstyle"></a>
+## ScatterChartMarksStyle
+Authored overlay for ScatterChartMarksStyle. Scatter-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+
+<a id="heatmapchartmarksstyle"></a>
+## HeatmapChartMarksStyle
+Authored overlay for HeatmapChartMarksStyle. Heatmap-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `rect` | [RectMarkStyle](#rectmarkstyle) | ✓ | Rect mark overrides; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+
+<a id="totalstyle"></a>
+## TotalStyle
+Authored overlay for TotalStyle. Donut center total paint: value (the number) and label (the caption).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `value` | [TotalSlotStyle](#totalslotstyle) | ✓ | Style for the donut center value (the number). |
+| `label` | [TotalSlotStyle](#totalslotstyle) | ✓ | Style for the donut center label (the caption). |
+
+<a id="piechartmarksstyle"></a>
+## PieChartMarksStyle
+Authored overlay for PieChartMarksStyle. Pie/donut-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `slice` | [SliceMarkStyle](#slicemarkstyle) | ✓ | Slice mark overrides; None inherits global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+
+<a id="kpivaluestyle"></a>
+## KpiValueStyle
+Authored overlay for KpiValueStyle. KPI headline value slot: font. Theme populates font.size directly.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | KPI value font style; cascades from kpi.font. |
+
+<a id="kpislotstyle"></a>
+## KpiSlotStyle
+Authored overlay for KpiSlotStyle. KPI per-slot style for label, affix, and glyph slots.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Slot font style; cascades from kpi.font. |
+| `character` | str | ✓ | Glyph character to render (e.g. '▲'). None = no glyph. |
+
+<a id="kpitonesstyle"></a>
+## KpiTonesStyle
+Authored overlay for KpiTonesStyle. Semantic tone palette for KPI value/glyph and (eventually) tables.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `positive` | str | ✓ | Color for positive/good tone indicators. |
+| `negative` | str | ✓ | Color for negative/bad tone indicators. |
+| `warning` | str | ✓ | Color for warning/caution tone indicators. |
+
+<a id="tablerulestyle"></a>
+## TableRuleStyle
+Authored overlay for TableRuleStyle. Table rule color override block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Table rule color; None uses the theme default. |
+
+<a id="tablecolumnsstyle"></a>
+## TableColumnsStyle
+Authored overlay for TableColumnsStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `default_width` | float | ✓ | Default column width in pixels. |
+| `cell_padding` | float | ✓ | Horizontal padding inside table cells in pixels. |
+| `width_similarity_threshold` | float | ✓ | Auto-width columns whose min/max ratio >= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width. |
+
+<a id="tableheaderstyle"></a>
+## TableHeaderStyle
+Authored overlay for TableHeaderStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the header row (column labels + rule). Set to False on series-keyed tables where column meanings are obvious from context (e.g. donut-attached tables: swatch / share / name / value). Theme YAML supplies the UX default (true) via _base.yaml. |
+| `height` | float | ✓ | Header row height in pixels. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Header font style overrides. |
+| `font_compact` | [FontStyle](#fontstyle) | ✓ | Compact-tier font overrides applied when body size ≤11px; None means no compact override. |
+| `background` | str | ✓ | Header background color; None means no fill (rule alone separates header from body). |
+| `overflow` | str | ✓ | Header text overflow mode (clip, truncate, wrap). |
+| `rule` | [RuleStyle](#rulestyle) | ✓ | Header bottom rule style. |
+
+<a id="tablerowstyle"></a>
+## TableRowStyle
+Authored overlay for TableRowStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `height` | float | ✓ | Body row height in pixels. |
+| `stripe` | [TableRowStripeStyle](#tablerowstripestyle) | ✓ | Alternating row stripe style; None means no stripe. |
+| `rule` | [RuleStyle](#rulestyle) | ✓ | Row bottom rule style. |
+| `role` | str | ✓ | Default row role assignment; None means plain body row. |
+| `roles` | [TableRowRolesStyle](#tablerowrolesstyle) | ✓ | Per-role style overrides for summary and total rows. |
+
+<a id="tablerownumbersstyle"></a>
+## TableRowNumbersStyle
+Authored overlay for TableRowNumbersStyle. Leading row-number column (style.table.row_numbers).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show a leading row-number column; false by default. |
+| `header` | str | ✓ | Header label for the row-number column. |
+| `align` | enum: "left", "right" | ✓ | Text alignment for the row-number column. |
+
+<a id="tabletitlestyle"></a>
+## TableTitleStyle
+Authored overlay for TableTitleStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `height` | float | ✓ | Table title row height in pixels. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Table title font style overrides. |
+
+<a id="paginationconfig"></a>
+## PaginationConfig
+Authored overlay for PaginationConfig. Table pagination configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `enabled` | bool | ✓ | Enable client-side pagination for table charts. |
+| `page_size` | int | ✓ | Rows per page. When enabled and None, the renderer auto-fits page size to the cell — set explicitly to pin the page size. |
+
+<a id="tablecolumndefaultsconfig"></a>
+## TableColumnDefaultsConfig
+Authored overlay for TableColumnDefaultsConfig. Table-level defaults applied to every column unless overridden per-column.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `label` | str | ✓ | Override column header label text. |
+| `width` | int \| str | ✓ | Override column width in pixels (integer) or a CSS width string. |
+| `align` | enum: "left", "center", "right" | ✓ | Override cell text alignment (left, center, or right). |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Override cell value format (D3 format string or format config object). |
+| `background` | str | ✓ | Override cell background color (CSS color string). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Override cell font style (size, weight, color, family). |
+
+<a id="paginatorstyle"></a>
+## PaginatorStyle
+Authored overlay for PaginatorStyle. Visual style for the paginator control (chevrons + page numbers).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color_active` | str | ✓ | Current page and live chevron colour (theme body ink). |
+| `color_inactive` | str | ✓ | Other pages and ellipsis colour (theme secondary text). |
+| `color_disabled` | str | ✓ | Chevron colour when at first/last page (signals disabled by tone). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Paginator font overrides (size, family). |
+| `weight_active` | int | ✓ | Font weight for the current (selected) page number. |
+| `weight_inactive` | int | ✓ | Font weight for other pages and ellipsis. |
+| `weight_chevron` | int | ✓ | Font weight for the prev/next chevrons (live and disabled). Usually heavier than weight_active so the chevrons read as interactive affordances against the lighter page numbers. |
+| `item_width` | float | ✓ | Per-item slot width in pixels (drives layout step). |
+
+<a id="tableedgestyle"></a>
+## TableEdgeStyle
+Authored overlay for TableEdgeStyle. more_rows or empty_state edge-case UI.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Edge-case UI (more_rows / empty_state) font style overrides. |
+
+<a id="sparkstyle"></a>
+## SparkStyle
+Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Sparkline line/point color; cascade-managed (inherits from style.accent). |
+| `padding` | [SpacingValues](#spacingvalues) | ✓ | Cell padding around the sparkline in pixels. |
+| `empty` | [SparkEmptyStyle](#sparkemptystyle) | ✓ | Style for empty/no-data sparklines. |
+| `single_value` | [SparkSingleValueStyle](#sparksinglevaluestyle) | ✓ | Style for single-data-point sparklines. |
+| `columns` | [SparkColumnsStyle](#sparkcolumnsstyle) | ✓ | Style for column-type sparklines. |
+| `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | ✓ | Style for bar/bar-normalize sparklines. |
+| `area` | [SparkAreaStyle](#sparkareastyle) | ✓ | Style for area sparklines. |
+
+<a id="subtitlestyle"></a>
+## SubtitleStyle
+Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style; theme populates font.size directly. |
+
+<a id="projectionstyle"></a>
+## ProjectionStyle
+Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | str | ✓ | Vega-Lite projection type (e.g. 'mercator', 'albersUsa', 'equalEarth'). |
+
+<a id="basemapstyle"></a>
+## BasemapStyle
+Authored overlay for BasemapStyle. Background map layer for geo charts (especially point maps).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `source` | str | ✓ | Background topo source identifier; None means no base layer. |
+
+<a id="pointmapchartmarksstyle"></a>
+## PointMapChartMarksStyle
+Authored overlay for PointMapChartMarksStyle. Point map-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
+
+<a id="geoshapechartmarksstyle"></a>
+## GeoshapeChartMarksStyle
+Authored overlay for GeoshapeChartMarksStyle. Geoshape-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | ✓ | Geoshape mark overrides; None inherits global. |
+
+<a id="layeraxisystyle"></a>
+## LayerAxisYStyle
+Per-layer y-axis settings on a layered chart.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `orient` | enum: "left", "right" | ✓ | Y-axis side for this layer (left or right). |
+| `title` | str | ✓ | Y-axis title override for this layer. |
+
+<a id="layeredmarksstyle"></a>
+## LayeredMarksStyle
+Per-mark-type style overrides for layered charts.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides for bar layers. |
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Line mark overrides for line layers. |
+| `area` | [AreaMarkStyle](#areamarkstyle) | ✓ | Area mark overrides for area layers. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point/dot mark overrides shared across line and area layers. |
+
+<a id="calloutelementstyle"></a>
+## CalloutElementStyle
+Authored overlay for CalloutElementStyle. Font + y_offset for a callout title or message.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Element font style overrides. |
+| `y_offset` | float | ✓ | Vertical offset from the element's anchor in pixels. |
+
+<a id="sparkbarbarstyle"></a>
+## SparkBarBarStyle
+Authored overlay for SparkBarBarStyle. Bar geometry sub-block for SparkBarChartStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `height` | float | ✓ | Height of each bar in pixels. |
+| `padding` | float | ✓ | Vertical padding between bars in pixels. |
+| `color` | str | ✓ | Bar fill color; cascade-managed (inherits from style.accent). |
+| `background` | str | ✓ | Bar track background color; cascade-managed (inherits from style.muted). |
+
+<a id="sparkbarchartlabelstyle"></a>
+## SparkBarChartLabelStyle
+Authored overlay for SparkBarChartLabelStyle. Category-label sub-block for SparkBarChartStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show series label text next to bars. |
+| `width` | float | ✓ | Reserved width for bar label text in pixels. |
+
+<a id="sparkbarcountstyle"></a>
+## SparkBarCountStyle
+Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChartStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show count/value text next to bars. |
+| `width` | float | ✓ | Reserved width for bar count text in pixels. |
+
+<a id="foreachquery"></a>
+## ForeachQuery
+Inline data source for compile-time foreach loops.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `data` | list[dict[str, Any]] | ✓ | Inline row data for compile-time iteration. |
+| `static_data` | list[dict[str, Any]] | ✓ | Alias for data; inline row data for compile-time iteration. |
+
+<a id="titlewidthoffsetsstyle"></a>
+## TitleWidthOffsetsStyle
+Authored overlay for TitleWidthOffsetsStyle. Additive level offsets applied to a face/chart title's heading level, by card pixel width.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `tiny` | int | ✓ | Level offset for the tiny tier (cards narrower than ~360px). |
+| `narrow` | int | ✓ | Level offset for the narrow tier (cards ~360–559px). |
+| `medium` | int | ✓ | Level offset for the medium tier (cards ~560–1099px). |
+| `wide` | int | ✓ | Level offset for the wide tier (cards ~1100px and up). |
+
+<a id="titlepositionstyle"></a>
+## TitlePositionStyle
+Authored overlay for TitlePositionStyle. Vega-Lite title positioning pass-throughs grouped as a sub-object.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `anchor` | str | ✓ | Title anchor position; theme always sets this. |
+| `angle` | float | ✓ | Title rotation angle in degrees; None lets Vega-Lite choose. |
+| `offset` | float | ✓ | Title offset from its anchor in pixels; None uses Vega-Lite's default. |
+| `baseline` | str | ✓ | Title text baseline alignment; None uses Vega-Lite's default. |
+
+<a id="titlesubtitlestyle"></a>
+## TitleSubtitleStyle
+Authored overlay for TitleSubtitleStyle. VL subtitle font pass-through, grouped for consistency with TitleStyle.font.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style overrides (color, family, size, weight). |
+
+<a id="textcolumnstyle"></a>
+## TextColumnStyle
+Authored overlay for TextColumnStyle. Multi-column layout for face body text (CSS column-count/gap/rule/width).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `number` | int | ✓ | Fixed column count. None = single column. |
+| `gap` | float | ✓ | Gap between columns in pixels. None = use layout gap token. |
+| `rule` | str | ✓ | CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule. |
+| `width` | float | ✓ | Minimum column width in pixels for auto-column-count derivation. |
+
+<a id="placeholderoverlay"></a>
+## PlaceholderOverlay
+Authored overlay for PlaceholderOverlay.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `text` | str | ✓ | Placeholder overlay text shown on empty charts. |
+| `background` | str | ✓ | Overlay background color. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Overlay font style overrides. |
+
+<a id="viewstyle"></a>
+## ViewStyle
+Authored overlay for ViewStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `stroke` | str | ✓ | Plot area border stroke color; None means no border. |
+| `continuous_width` | float | ✓ | Default plot width for continuous (quantitative) scales in pixels. |
+| `continuous_height` | float | ✓ | Default plot height for continuous (quantitative) scales in pixels. |
+| `discrete_width` | float | ✓ | Default plot width for discrete (ordinal/nominal) scales in pixels; None means auto. |
+| `discrete_height` | float | ✓ | Default plot height for discrete (ordinal/nominal) scales in pixels; None means auto. |
+
+<a id="autosizestyle"></a>
+## AutosizeStyle
+Authored overlay for AutosizeStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | str | ✓ | Vega-Lite autosize type (e.g. 'fit', 'fit-x', 'pad'). |
+| `contains` | str | ✓ | What the autosize dimensions include ('content' or 'padding'). |
+| `resize` | bool | ✓ | Recompute autosize on each render cycle. |
+
+<a id="globalmarksstyle"></a>
+## GlobalMarksStyle
+Authored overlay for GlobalMarksStyle. Global mark defaults: one <Mark>MarkStyle per VL mark type.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Global bar mark defaults. |
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Global line mark defaults. |
+| `area` | [AreaMarkStyle](#areamarkstyle) | ✓ | Global area mark defaults. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Global point mark defaults. |
+| `slice` | [SliceMarkStyle](#slicemarkstyle) | ✓ | Global slice (arc/pie) mark defaults. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Global text mark defaults. |
+| `rule` | [RuleMarkStyle](#rulemarkstyle) | ✓ | Global rule mark defaults. |
+| `rect` | [RectMarkStyle](#rectmarkstyle) | ✓ | Global rect mark defaults. |
+| `circle` | [CircleMarkStyle](#circlemarkstyle) | ✓ | Global circle mark defaults. |
+| `square` | [SquareMarkStyle](#squaremarkstyle) | ✓ | Global square mark defaults. |
+| `tick` | [TickMarkStyle](#tickmarkstyle) | ✓ | Global tick mark defaults. |
+| `trail` | [TrailMarkStyle](#trailmarkstyle) | ✓ | Global trail mark defaults. |
+| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | ✓ | Global geoshape mark defaults. |
+| `image` | [ImageMarkStyle](#imagemarkstyle) | ✓ | Global image mark defaults. |
+| `boxplot` | [BoxplotMarkStyle](#boxplotmarkstyle) | ✓ | Global boxplot mark defaults. |
+| `errorbar` | [ErrorbarMarkStyle](#errorbarmarkstyle) | ✓ | Global errorbar mark defaults. |
+| `errorband` | [ErrorbandMarkStyle](#errorbandmarkstyle) | ✓ | Global errorband mark defaults. |
+
+<a id="scatterchartstyle"></a>
+## ScatterChartStyle
+Scatter chart style: chart-level fields + marks sub-block.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `marks` | ScatterChartMarksStyle | ✓ | Scatter-family mark overrides. |
+
+<a id="histogramchartstyle"></a>
+## HistogramChartStyle
+Authored overlay for HistogramChartStyle. Histogram chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `bin_maxbins` | int | ✓ | Maximum number of bins for auto-binning. |
+| `marks` | [HistogramChartMarksStyle](#histogramchartmarksstyle) | ✓ | Histogram-family mark overrides. |
+
+<a id="boxplotchartstyle"></a>
+## BoxplotChartStyle
+Boxplot chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `marks` | BoxplotChartMarksStyle | ✓ | Boxplot-family mark overrides. |
+
+<a id="errorbarchartstyle"></a>
+## ErrorbarChartStyle
+Error bar chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `marks` | ErrorbarChartMarksStyle | ✓ | Errorbar-family mark overrides. |
+
+<a id="errorbandchartstyle"></a>
+## ErrorbandChartStyle
+Error band chart style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Chart-level font overrides. |
+| `aspect_ratio` | float | ✓ | Chart aspect ratio (width/height). |
+| `min_height` | float | ✓ | Minimum chart height in pixels. |
+| `max_height` | float | ✓ | Maximum chart height in pixels. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Chart inner padding in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
+| `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
+| `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
+| `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
+| `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
+| `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
+| `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
+| `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
+| `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
+| `axis` | [AxisStyle](#axisstyle) | ✓ | Override applied to both x and y axes; None inherits global axis defaults. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type x-axis style overrides; None inherits global axis defaults. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type y-axis style overrides; None inherits global axis defaults. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type quantitative-axis overrides; None inherits global defaults. |
+| `axis_band` | [AxisStyle](#axisstyle) | ✓ | Per-chart-type categorical (band) axis overrides; None inherits global band defaults. |
+| `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
+| `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
+| `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
+| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
+| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `marks` | ErrorbandChartMarksStyle | ✓ | Errorband-family mark overrides. |
+
+<a id="serieslabelstyle"></a>
+## SeriesLabelStyle
+Authored overlay for SeriesLabelStyle. Series-label primitive — typography for any text mark that names a
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Series label font style overrides; cascade fills missing fields from charts.font. |
+
+<a id="layoutgapstyle"></a>
+## LayoutGapStyle
+Authored overlay for LayoutGapStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `gap` | float | ✓ | Gap between layout items in pixels. |
+
+<a id="gridlayoutstyle"></a>
+## GridLayoutStyle
+Authored overlay for GridLayoutStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `columns` | int | ✓ | Number of columns in the grid layout. |
+| `gap` | float | ✓ | Gap between grid cells in pixels. |
+
+<a id="tabsstyle"></a>
+## TabsStyle
+Authored overlay for TabsStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar_height` | float | ✓ | Tab bar height in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Tab bar border style. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Tab label font style overrides. |
+| `active_weight` | str | ✓ | Font weight for the active tab label. |
+| `inactive_weight` | str | ✓ | Font weight for inactive tab labels. |
+| `title_baseline_offset` | float | ✓ | Vertical offset to align SVG tab label baseline in pixels. |
+
+<a id="detailsstyle"></a>
+## DetailsStyle
+Authored overlay for DetailsStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `summary_height` | float | ✓ | Height of the details summary (collapsed) row in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Details element border style. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Details summary font style overrides. |
+| `arrow` | [DetailsArrowStyle](#detailsarrowstyle) | ✓ | Expand/collapse arrow glyph layout and font style. |
+| `label_x` | float | ✓ | X position of the details summary label text in pixels. |
+| `text_baseline_offset` | float | ✓ | Vertical offset to align SVG details text baseline in pixels. |
+| `content_y_offset` | float | ✓ | Y offset of the expanded details content area in pixels. |
+
+<a id="variableslabelstyle"></a>
+## VariablesLabelStyle
+Authored overlay for VariablesLabelStyle. Per-label font substyle for variable controls. Cascades from variables.font.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Variable label font style overrides. |
+
+<a id="variablesvaluestyle"></a>
+## VariablesValueStyle
+Authored overlay for VariablesValueStyle. Per-value font substyle for variable controls. Cascades from variables.font.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Variable value font style overrides. |
+| `numeric_variant` | enum: "normal", "tabular-nums" | ✓ | OpenType numeric feature for value displays ('normal' or 'tabular-nums'). |
+
+<a id="variablesplaceholderstyle"></a>
+## VariablesPlaceholderStyle
+Authored overlay for VariablesPlaceholderStyle. Per-placeholder font substyle for variable controls.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Variable placeholder-text font style overrides. |
+
+<a id="inputstyle"></a>
+## InputStyle
+Authored overlay for InputStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `height` | float | ✓ | Input control height in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Input border style. |
+| `focus_color` | str | ✓ | Input focus ring color; cascade-managed (inherits from style.accent). |
+| `background` | str | ✓ | Input background color. |
+| `padding` | [SpacingValues](#spacingvalues) | ✓ | Input inner padding in pixels. |
+| `widths` | [InputWidths](#inputwidths) | ✓ | Per-input-type default widths. |
+| `range` | [RangeDefaults](#rangedefaults) | ✓ | Range input default min/max/step values. |
+
+<a id="legendelementstyle"></a>
+## LegendElementStyle
+Authored overlay for LegendElementStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Legend element font style overrides. |
+| `padding` | float | ✓ | Padding between legend symbol and element text in pixels. |
+
+<a id="scaletargetconfig"></a>
+## ScaleTargetConfig
+Scale configuration for a single style target (background or color).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `palette` | list[str] \| list[float] \| str |  | Color palette: CSS color list for categorical, float list for relative stops, or a named Vega scheme. |
+| `domain` | enum: "data" | ✓ | Scale domain source ('data' uses the data extent; None uses explicit min/max). |
+| `min` | float \| int | ✓ | Minimum scale domain value (overrides data minimum). |
+| `max` | float \| int | ✓ | Maximum scale domain value (overrides data maximum). |
+| `null_color` | str | ✓ | Color assigned to null values. |
+| `hinge` | enum: "auto" | ✓ | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
+| `arm_mode` | enum: "asymmetric", "symmetric" | ✓ | How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms). |
+
+<a id="axisgridstyle"></a>
+## AxisGridStyle
+Authored overlay for AxisGridStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show grid lines; None inherits from parent axis. |
+| `opacity` | float | ✓ | Grid line opacity; None uses Vega-Lite's default. |
+| `width` | float | ✓ | Grid line width in pixels; None uses Vega-Lite's default. |
+| `color` | str | ✓ | Grid line color; None uses Vega-Lite's default. |
+| `dash` | list[float] | ✓ | Dash pattern for grid lines; None renders a solid line. |
+| `zero` | [AxisGridZeroStyle](#axisgridzerostyle) | ✓ | Zero-baseline gridline style; None inherits from parent axis. |
+
+<a id="axisdomainstyle"></a>
+## AxisDomainStyle
+Authored overlay for AxisDomainStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the axis domain line; None inherits from parent axis. |
+| `width` | float | ✓ | Domain line width in pixels; None uses Vega-Lite's default. |
+| `color` | str | ✓ | Domain line color; None uses Vega-Lite's default. |
+
+<a id="axisticksstyle"></a>
+## AxisTicksStyle
+Authored overlay for AxisTicksStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show axis ticks; None inherits from parent axis. |
+| `color` | str | ✓ | Tick color; None uses Vega-Lite's default. |
+| `size` | float | ✓ | Tick length in pixels; None uses Vega-Lite's default. |
+| `width` | float | ✓ | Tick stroke width in pixels; None uses Vega-Lite's default. |
+| `count` | int | ✓ | Target number of quantitative y-axis ticks. When set, the renderer computes explicit tickValues so VL emits exactly this many ticks — VL's tickCount is advisory and frequently ignored. |
+
+<a id="axiselementstyle"></a>
+## AxisElementStyle
+Authored overlay for AxisElementStyle. Axis label or title: font + padding + VL-passthrough.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Axis element font style overrides. |
+| `padding` | float | ✓ | Padding between axis labels and ticks in pixels; None inherits from parent axis. |
+| `max_width` | float | ✓ | Maximum label width in pixels; None uses Vega-Lite's default (180px). |
+| `angle` | float | ✓ | Label rotation angle in degrees; None uses Vega-Lite's default. |
+| `align` | str | ✓ | Horizontal text alignment of labels; None uses Vega-Lite's default. |
+| `baseline` | str | ✓ | Vertical text baseline of labels; None uses Vega-Lite's default. |
+| `overlap` | enum: "smart", "parity", "greedy", "allow" | ✓ | Label overlap reduction strategy; None uses Vega-Lite's per-scale default. |
+| `separation` | float | ✓ | Minimum pixel separation between labels; None uses Vega-Lite's default (0px). |
+| `visible` | bool | ✓ | Show axis labels; None uses Vega-Lite's default (labels shown). |
+| `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | ✓ | Label cadence for temporal axes; None inherits from the parent axis time_unit. |
+| `expr` | str | ✓ | Custom Vega expression for label text; None uses smart temporal defaults when applicable. |
+| `bound` | bool \| float | ✓ | Hide labels that overflow the axis range; None uses Vega-Lite's default. |
+| `flush` | bool \| float | ✓ | Align first/last label flush with the scale range; None uses Vega-Lite's default. |
+| `offset` | float | ✓ | Pixel offset of the label from its tick anchor; None uses Vega-Lite's default. |
+| `line_height` | float | ✓ | Line height for multi-line labels in pixels; None uses Vega-Lite's default. |
+| `anchor` | enum: "start", "middle", "end" | ✓ | Label anchor position; None uses Vega-Lite's default. |
+| `tilt_increments` | list[float] | ✓ | Descending tilt angles for smart label overlap on discrete x-axes; None disables the picker. |
+
+<a id="scalebandstyle"></a>
+## ScaleBandStyle
+Authored overlay for ScaleBandStyle. Band mark size constraints (min/max pixel width for band-scale marks).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `min_size` | float | ✓ | Minimum band mark width in pixels; None uses Vega-Lite's default. |
+| `max_size` | float | ✓ | Maximum band mark width in pixels; None uses Vega-Lite's default. |
+
+<a id="rulestyle"></a>
+## RuleStyle
+Authored overlay for RuleStyle. Shared rule-line primitive: width, color, continuous mode.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Rule line width in pixels. |
+| `color` | str | ✓ | Rule color; None inherits from theme. |
+| `continuous` | bool | ✓ | Draw a continuous full-width rule (true) or only under columns (false). |
+
+<a id="datatablerowstyle"></a>
+## DataTableRowStyle
+Authored overlay for DataTableRowStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `padding` | [DataTableRowPaddingStyle](#datatablerowpaddingstyle) | ✓ | Row padding style. |
+| `rule` | [RuleStyle](#rulestyle) | ✓ | Row bottom rule style. |
+
+<a id="datatablelabelstyle"></a>
+## DataTableLabelStyle
+Authored overlay for DataTableLabelStyle. Row label styling.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Row label font style overrides. |
+
+<a id="barmarkstyle"></a>
+## BarMarkStyle
+Authored overlay for BarMarkStyle. Bar mark geometry and stroke. Chart-level bar fields live on BarChartStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `border` | [BorderStyle](#borderstyle) | ✓ | Bar border style (color/width also serve as the bar stroke). |
+| `padding` | float | ✓ | Padding around bar marks in pixels. |
+| `size` | float | ✓ | Bar width in pixels (fixed-width mode). |
+| `band_width` | float | ✓ | Bar width as a fraction of the band step (0–1). |
+
+<a id="textmarkstyle"></a>
+## TextMarkStyle
+Authored overlay for TextMarkStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Text mark font style overrides. |
+| `align` | str | ✓ | Horizontal text alignment for text marks. |
+
+<a id="linemarkstyle"></a>
+## LineMarkStyle
+Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. Point mark lives on PointMarkStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Line stroke style. |
+| `curve` | str | ✓ | Line interpolation curve (e.g. 'linear', 'monotone'). |
+| `halo_multiplier` | float | ✓ | Halo stroke width multiplier relative to stroke.width; 0 disables the halo. |
+
+<a id="pointmarkstyle"></a>
+## PointMarkStyle
+Authored overlay for PointMarkStyle. Point mark style (data-point markers on line/area/scatter charts).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `size` | float | ✓ | Point size in square pixels; 0 disables points on line charts. |
+| `color` | str | ✓ | Point color; None inherits the series color. |
+| `shape` | str | ✓ | Point shape (e.g. 'circle', 'square'); None uses VL default. |
+| `opacity` | float | ✓ | Point opacity 0–1; None uses VL default. |
+| `filled` | bool | ✓ | Whether points are filled; None uses VL default. |
+| `fill` | str | ✓ | Point interior fill color; only applied when filled=false. |
+
+<a id="rulemarkstyle"></a>
+## RuleMarkStyle
+Authored overlay for RuleMarkStyle. Rule (reference line) mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="areamarkstyle"></a>
+## AreaMarkStyle
+Authored overlay for AreaMarkStyle. Area mark fill opacity, stroke, and halo.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Area fill opacity (0–1). |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Area top-edge stroke style. |
+| `halo_multiplier` | float | ✓ | Halo stroke width multiplier relative to stroke.width; 0 disables the halo. |
+
+<a id="rectmarkstyle"></a>
+## RectMarkStyle
+Authored overlay for RectMarkStyle. Rect mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="totalslotstyle"></a>
+## TotalSlotStyle
+Authored overlay for TotalSlotStyle. Theme slot for one text element of the donut center total.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Donut center total element font style overrides. |
+
+<a id="slicemarkstyle"></a>
+## SliceMarkStyle
+Authored overlay for SliceMarkStyle. Pie/donut slice mark — mark-level paint and layout only.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `gap` | float | ✓ | Angular gap between slices in radians. |
+| `corner_radius` | float | ✓ | Corner radius of arc slices in pixels. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Arc slice stroke style. |
+| `labels` | [SliceLabelsStyle](#slicelabelsstyle) | ✓ | Per-slice label style. |
+
+<a id="tablerowstripestyle"></a>
+## TableRowStripeStyle
+Authored overlay for TableRowStripeStyle. Alternating row stripe style.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Alternating stripe background color; None means no alternating row fill. |
+
+<a id="tablerowrolesstyle"></a>
+## TableRowRolesStyle
+Authored overlay for TableRowRolesStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `summary` | [TableRowRoleStyle](#tablerowrolestyle) | ✓ | Style for summary role rows. |
+| `total` | [TableRowRoleStyle](#tablerowrolestyle) | ✓ | Style for total role rows. |
+
+<a id="sparkemptystyle"></a>
+## SparkEmptyStyle
+Authored overlay for SparkEmptyStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `inset_x` | float | ✓ | Horizontal inset for the empty sparkline placeholder in pixels. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Empty-state placeholder stroke style. |
+
+<a id="sparksinglevaluestyle"></a>
+## SparkSingleValueStyle
+Authored overlay for SparkSingleValueStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `inset_x` | float | ✓ | Horizontal inset for the single-value sparkline in pixels. |
+| `marker_radius` | float | ✓ | Radius of the single-value marker circle in pixels. |
+
+<a id="sparkcolumnsstyle"></a>
+## SparkColumnsStyle
+Authored overlay for SparkColumnsStyle. Inline `spark.type: columns` (multi-value vertical bars) defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `gap` | float | ✓ | Gap between column bars in pixels. |
+| `padding` | float | ✓ | Horizontal outer padding of the columns sparkline in pixels. |
+| `min_bar_height` | float | ✓ | Minimum rendered bar height in pixels. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Column bar border style. |
+
+<a id="sparkbarcellstyle"></a>
+## SparkBarCellStyle
+Authored overlay for SparkBarCellStyle. Inline `spark.type: bar` and `bar-normalize` (single horizontal bar) defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `background` | str | ✓ | Track background color; cascade-managed (inherits from style.muted). |
+| `color` | str | ✓ | Bar fill color; cascade-managed (inherits from style.accent). |
+| `default_max` | float | ✓ | Default maximum value for bar scale when no explicit max is authored. |
+| `border` | [BorderStyle](#borderstyle) | ✓ | Spark bar border style. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Spark bar cell font style overrides. |
+| `label` | [SparkBarLabelStyle](#sparkbarlabelstyle) | ✓ | Spark bar inline label style. |
+
+<a id="sparkareastyle"></a>
+## SparkAreaStyle
+Authored overlay for SparkAreaStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `fill_opacity` | float | ✓ | Spark area fill opacity (0–1). |
+
+<a id="geoshapemarkstyle"></a>
+## GeoshapeMarkStyle
+Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark boundary stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Geoshape boundary stroke style. |
+
+<a id="circlemarkstyle"></a>
+## CircleMarkStyle
+Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="squaremarkstyle"></a>
+## SquareMarkStyle
+Authored overlay for SquareMarkStyle. Square mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="tickmarkstyle"></a>
+## TickMarkStyle
+Authored overlay for TickMarkStyle. Tick mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="trailmarkstyle"></a>
+## TrailMarkStyle
+Authored overlay for TrailMarkStyle. Trail mark opacity and stroke.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
+| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+
+<a id="imagemarkstyle"></a>
+## ImageMarkStyle
+Authored overlay for ImageMarkStyle. Image mark aspect ratio preservation.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `aspect` | bool | ✓ | Preserve image aspect ratio when scaling. |
+
+<a id="boxplotmarkstyle"></a>
+## BoxplotMarkStyle
+Authored overlay for BoxplotMarkStyle. Boxplot composite mark whisker extent.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `extent` | str | ✓ | Boxplot whisker extent ('min-max' or a k-IQR multiplier as string). |
+
+<a id="errorbarmarkstyle"></a>
+## ErrorbarMarkStyle
+Authored overlay for ErrorbarMarkStyle. Error bar composite mark tick visibility.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `ticks` | bool | ✓ | Show tick marks at the ends of error bar whiskers. |
+
+<a id="errorbandmarkstyle"></a>
+## ErrorbandMarkStyle
+Authored overlay for ErrorbandMarkStyle. Error band composite mark fill opacity.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Error band fill opacity (0–1). |
+
+<a id="histogramchartmarksstyle"></a>
+## HistogramChartMarksStyle
+Authored overlay for HistogramChartMarksStyle. Histogram-family mark overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides; None inherits global. |
+| `rule` | [RuleMarkStyle](#rulemarkstyle) | ✓ | Rule mark overrides; None inherits global. |
+
+<a id="detailsarrowstyle"></a>
+## DetailsArrowStyle
+Authored overlay for DetailsArrowStyle. Layout and font style for the expand/collapse arrow chevron.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `x` | float | ✓ | X position of the arrow in pixels. |
+| `font` | [DetailsArrowFontStyle](#detailsarrowfontstyle) | ✓ | Arrow glyph font style. |
+
+<a id="inputwidths"></a>
+## InputWidths
+Authored overlay for InputWidths.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `text` | float | ✓ | Default width for text inputs in pixels. |
+| `number` | float | ✓ | Default width for number inputs in pixels. |
+| `range` | float | ✓ | Default width for range inputs in pixels. |
+| `slider_value_min` | float | ✓ | Minimum width for slider value display in pixels. |
+| `checkbox` | float | ✓ | Default width for checkbox inputs in pixels. |
+| `daterange` | float | ✓ | Default width for daterange chip triggers in pixels. |
+
+<a id="rangedefaults"></a>
+## RangeDefaults
+Authored overlay for RangeDefaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `default_min` | float | ✓ | Default minimum value for range inputs. |
+| `default_max` | float | ✓ | Default maximum value for range inputs. |
+| `default_step` | float | ✓ | Default step size for range inputs. |
+
+<a id="axisgridzerostyle"></a>
+## AxisGridZeroStyle
+Authored overlay for AxisGridZeroStyle. Zero-baseline gridline color and width overrides.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Color of the zero-baseline grid line; None inherits from parent axis. |
+| `width` | float | ✓ | Width of the zero-baseline grid line in pixels; None inherits from parent axis. |
+
+<a id="datatablerowpaddingstyle"></a>
+## DataTableRowPaddingStyle
+Authored overlay for DataTableRowPaddingStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `vertical` | float | ✓ | Vertical (top/bottom) padding inside data_table rows in pixels. |
+| `horizontal` | float | ✓ | Horizontal (left/right) padding inside data_table rows in pixels. |
+
+<a id="strokestyle"></a>
+## StrokeStyle
+Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark families.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Stroke color as a CSS color string. |
+| `width` | float | ✓ | Stroke width in pixels. |
+| `cap` | enum: "butt", "round", "square" | ✓ | Stroke line cap style (butt, round, or square). |
+| `join` | enum: "miter", "round", "bevel" | ✓ | Stroke line join style (miter, round, or bevel). |
+| `dasharray` | str | ✓ | SVG stroke-dasharray pattern (e.g. '4 2'). |
+
+<a id="slicelabelsstyle"></a>
+## SliceLabelsStyle
+Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offsets for per-slice text.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `offset` | float | ✓ | Radial offset of slice labels from the arc in pixels. |
+| `block_height` | float | ✓ | Reserved height per label block in pixels. |
+| `line_height` | float | ✓ | Line height for multi-line slice labels in pixels. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. |
+
+<a id="tablerowrolestyle"></a>
+## TableRowRoleStyle
+Authored overlay for TableRowRoleStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `rule_width` | float | ✓ | Rule width above rows with this role in pixels. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Per-role font style override; None uses the default row font. |
+| `background` | str | ✓ | Per-role row background color; None means no override. |
+
+<a id="sparkbarlabelstyle"></a>
+## SparkBarLabelStyle
+Authored overlay for SparkBarLabelStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `inset_x` | float | ✓ | Horizontal inset for the spark bar label in pixels. |
+| `fill` | str | ✓ | Label text fill color. |
+| `fill_opacity` | float | ✓ | Label text fill opacity (0–1). |
+| `min_size` | float | ✓ | Minimum bar fill width required to show the label in pixels. |
+| `height_offset` | float | ✓ | Vertical offset of the label from its bar top in pixels. |
+
+<a id="detailsarrowfontstyle"></a>
+## DetailsArrowFontStyle
+Authored overlay for DetailsArrowFontStyle. Font style for the expand/collapse arrow glyph.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `size` | float | ✓ | Font size of the arrow glyph in pixels. |
+
+<a id="chart"></a>
+## Chart
+Discriminated union of per-family chart patches. type: is mandatory; missing or unknown type raises ValidationError.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "bar", "line", "area", "circle", "square", "tick", "rule", "trail", "rect", "arc", "boxplot", "errorbar", "errorband", "geoshape", "image", "table", "kpi", "callout", "scatter", "heatmap", "pie", "donut", "histogram", "map", "point_map", "bubble_map", "spark_bar", "layered", "auto" |  | Bar or histogram chart type. |
+| `theta` | str |  | Field for angular encoding in pie (arc) charts. |
+| `value` | str |  | Column reference (string column name) for the headline number/text. |
+| `layers` | list[[Layer](#layer)] |  | Layers for multi-mark charts. Each layer is a chart definition. |
+| `message` | str |  | Static message content. |
+| `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
+| `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
+| `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
+| `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
+| `query` | str \| dict[str, Any] | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `link` | str | ✓ | Click-through URL template for drill-down links. |
+| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
+| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
+| `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
+| `x` | str | ✓ | X-axis field name from the query result. |
+| `y` | str \| list[str] | ✓ | Y-axis field name(s). Accepts a single field or list for multi-series charts. |
+| `x_label` | str | ✓ | Custom label for the X axis. |
+| `y_label` | str | ✓ | Custom label for the Y axis. |
+| `color` | str | ✓ | Color data channel: bare field name only. |
+| `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
+| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
+| `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format: D3 format string, preset name, or FormatConfig object. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `size` | str | ✓ | Field used to size-encode data points (quantitative). |
+| `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
+| `style` | [BarChartStyle](#barchartstyle) | ✓ | Chart-local style overrides. |
+| `total` | [ChartTotal](#charttotal) | ✓ | Donut center total. |
+| `label` | str | ✓ | KPI label rendered above the headline value. |
+| `support` | [KpiSupportConfig](#kpisupportconfig) | ✓ | Optional support line beneath the KPI value. |
+| `projection` | str \| Projection | ✓ | Map projection name or Vega-Lite projection config. |
+| `geo` | str \| dict[str, Any] | ✓ | GeoJSON field name or inline GeoJSON spec for geoshape charts. |
+| `geo_source` | str | ✓ | Named geographic data source for loading GeoJSON boundaries. |
+| `lookup` | str | ✓ | Data field to join against geographic data (map join key). |
+| `latitude` | str | ✓ | Field containing latitude values for point/bubble maps. |
+| `longitude` | str | ✓ | Field containing longitude values for point/bubble maps. |
+| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Tile-layer configuration for the map background. |
+| `x_domain` | enum: "union", "primary" | ✓ | Controls how x-values from multiple layer queries are combined. |
+
+<a id="paginationconfig"></a>
+## PaginationConfig
+Table pagination configuration.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `enabled` | bool | ✓ | Enable client-side pagination for table charts. |
+| `page_size` | int | ✓ | Rows per page. When enabled and None, the renderer auto-fits page size to the cell — set explicitly to pin the page size. |