dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/style/compiled.py

@@ -0,0 +1,3399 @@
+"""Style model skeleton — bare nouns per ADR-001.
+
+Stage: COMPILE
+Purpose: Define the target Pydantic model architecture for style.
+
+Pattern (ADR-006):
+  XX        — validated from theme YAML. Required fields; no fallbacks.
+  XXPatch   — generated mechanically via build_patch_model(). Never hand-duplicated.
+  ResolvedXX — final merged result after cascade. Sole type render/sizing accepts.
+
+Leaf types:
+  FontStyle{family, color, size, weight, style, decoration}  — text appearance, cascades (ADR-005)
+  BorderStylePatch{radius, color, width}  — hand-written all-Optional patch; carries from_css()
+  BorderStyle{width, color, radius}  — resolved border, all required (ADR-003)
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from dataface.core.compile.models.factories import (
+    build_patch_model,
+    build_patch_model_ext,
+    register_as_own_patch,
+)
+from dataface.core.compile.models.primitives import (
+    BorderStyle,
+    FontStyle,
+    FormatConfig,
+    RuleStyle,
+    SpacingValues,
+    StrokeStyle,
+    StyleColorConfig,
+)
+
+# =============================================================================
+# OVERFLOW NORMALIZATION
+# =============================================================================
+
+_OVERFLOW_VALUES: frozenset[str] = frozenset({"clip", "truncate", "wrap-two", "wrap"})
+
+
+def _normalize_overflow_value(value: Any) -> Any:
+    """Normalize overflow mode: snake_case → kebab-case, lower, validate."""
+    if value is None or not isinstance(value, str):
+        return value
+    normalized = value.strip().lower().replace("_", "-")
+    if normalized in _OVERFLOW_VALUES:
+        return normalized
+    raise ValueError(
+        f"Invalid overflow mode {value!r}. Valid values: clip, truncate, wrap-two, wrap."
+    )
+
+
+VALID_FONT_WEIGHTS: frozenset[str] = frozenset(
+    {"normal", "bold", "100", "200", "300", "400", "500", "600", "700", "800", "900"}
+)
+
+
+def font_weight_as_css(w: str | float) -> str:
+    """Normalize a FontStyle.weight value to a CSS font-weight string."""
+    if isinstance(w, float) and w == int(w):
+        return str(int(w))
+    return str(w)
+
+
+class PaddingStyle(BaseModel):
+    """Per-chart padding inset (px). All 4 sides required; theme YAML supplies defaults.
+
+    The board layer adds ``card_padding`` to each side additively so per-chart
+    padding composes with the global card layout rather than replacing it.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    left: float = Field(description="Left padding in pixels.")
+    right: float = Field(description="Right padding in pixels.")
+    top: float = Field(description="Top padding in pixels.")
+    bottom: float = Field(description="Bottom padding in pixels.")
+
+
+# =============================================================================
+# BODY TEXT / COLUMN LAYOUT (per-face CSS-chrome, not theme-cascaded)
+# =============================================================================
+
+# Supported SVG stroke styles for column rules. "none"/"hidden" and decorative styles
+# (double, groove, ridge, inset, outset) are deliberately omitted — they have no SVG
+# equivalent and would silently render as solid lines.
+_COLUMN_RULE_SVG_STYLES = frozenset({"solid", "dashed", "dotted"})
+
+# Valid hex color lengths: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+_COLUMN_RULE_HEX_RE = re.compile(
+    r"^#[0-9a-fA-F]{3,4}$|^#[0-9a-fA-F]{6}$|^#[0-9a-fA-F]{8}$"
+)
+
+
+class TextColumnStyle(BaseModel):
+    """Multi-column layout for face body text (CSS column-count/gap/rule/width).
+
+    Two orthogonal controls:
+    - ``number``: fixed column count. None = not set.
+    - ``width``: minimum column width (px). None = not set. When set,
+      column count auto-derives as ``floor((available - gap) / (width + gap))``.
+
+    When both are set, ``number`` acts as a ceiling on the auto-derived count.
+    When neither is set, text renders as a single column.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    number: int | None = Field(
+        default=None, ge=1, description="Fixed column count. None = single column."
+    )
+    gap: float | None = Field(
+        default=None,
+        description="Gap between columns in pixels. None = use layout gap token.",
+    )
+    rule: str | None = Field(
+        default=None,
+        description="CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule.",
+    )
+    width: float | None = Field(
+        default=None,
+        gt=0,
+        description="Minimum column width in pixels for auto-column-count derivation.",
+    )
+
+    @field_validator("rule")
+    @classmethod
+    def _validate_rule_parseable(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        tokens = v.strip().split()
+        widths = [t for t in tokens if re.match(r"^\d+(?:\.\d+)?px$", t)]
+        colors = [t for t in tokens if _COLUMN_RULE_HEX_RE.match(t)]
+        styles = [t for t in tokens if t in _COLUMN_RULE_SVG_STYLES]
+        remainder = [
+            t for t in tokens if t not in widths and t not in colors and t not in styles
+        ]
+        if remainder:
+            raise ValueError(
+                f"column.rule contains unrecognized tokens {remainder!r} in {v!r}. "
+                f"Expected format: '<N>px [solid|dashed|dotted] #<hexcolor>'."
+            )
+        if len(colors) != 1:
+            raise ValueError(
+                f"column.rule must have exactly one hex color (got {colors!r}): {v!r}"
+            )
+        if len(widths) != 1:
+            raise ValueError(
+                f"column.rule must have exactly one px width (got {widths!r}): {v!r}"
+            )
+        if len(styles) > 1:
+            raise ValueError(
+                f"column.rule must have at most one style keyword (got {styles!r}): {v!r}"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _validate_column_settings(self) -> TextColumnStyle:
+        multi = (self.number is not None and self.number > 1) or self.width is not None
+        if self.gap is not None and not multi:
+            raise ValueError("column.gap requires column.number > 1 or column.width")
+        if self.rule is not None and not multi:
+            raise ValueError("column.rule requires column.number > 1 or column.width")
+        return self
+
+    @property
+    def has_overrides(self) -> bool:
+        """True when multi-column layout is configured."""
+        return (self.number is not None and self.number > 1) or self.width is not None
+
+
+def compute_text_column_count(
+    col: TextColumnStyle, available_width: float, gap: float
+) -> int:
+    """Auto-derive column count from width, with number as ceiling.
+
+    When only width is set: count = max(1, floor((available - gap) / (width + gap))).
+    When only number is set: count = number.
+    When both are set: count = min(number, auto-derived).
+    When neither is set: single column.
+
+    ``gap`` must be resolved by the caller (fallback to layout gap token if None).
+    """
+    if col.width is not None:
+        auto = max(1, int((available_width - gap) / (col.width + gap)))
+        return min(col.number, auto) if col.number is not None else auto
+    if col.number is not None:
+        return col.number
+    return 1
+
+
+def _coerce_gap(v: Any) -> float | None:
+    """Coerce gap value from int, float, or CSS px string."""
+    if v is None:
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    if isinstance(v, str):
+        m = re.search(r"(\d+(?:\.\d+)?)", v)
+        if m:
+            return float(m.group(1))
+    raise ValueError(f"Cannot parse gap from {v!r}")
+
+
+# =============================================================================
+# COMPILEDSTYLE TREE
+# =============================================================================
+
+# Board / face dimensions
+
+
+class RootFontStyle(FontStyle):
+    """Root-level font configuration: FontStyle fields plus a required emoji mode.
+
+    The ``emoji`` field is only meaningful at the root — nested FontStyle instances in the
+    cascade (axis label, legend, title, etc.) do not carry it. ``extra='forbid'``
+    is inherited from FontStyle so nested fonts reject ``emoji:`` at construction.
+    """
+
+    emoji: Literal["monochrome", "color", "system-default", "disabled"] = Field(
+        description="Emoji rendering mode for the dashboard font stack."
+    )
+
+
+class BoardStyle(BaseModel):
+    """Face-level structural dimensions. Do NOT cascade to child faces."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    width: float = Field(description="Board width in pixels.")
+    default_height: float = Field(description="Default row height in pixels.")
+    min_height: float = Field(description="Minimum row height in pixels.")
+    margin: float = Field(description="Board outer margin in pixels.")
+    card_padding: float = Field(
+        description="Padding added to each card side in pixels."
+    )
+    card_gap: float = Field(description="Gap between cards in pixels.")
+
+
+# Title / text
+
+
+class TitleWidthOffsetsStyle(BaseModel):
+    """Additive level offsets applied to a face/chart title's heading level, by card pixel width.
+
+    Added to the base heading level before indexing into ``style.title.sizes``.
+    Tier width breakpoints are constants in ``typography.py``; only the per-tier
+    offset lives here so themes own the full type stack without duplicating the
+    ``sizes`` ramp.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    tiny: int = Field(
+        description="Level offset for the tiny tier (cards narrower than ~360px)."
+    )
+    narrow: int = Field(
+        description="Level offset for the narrow tier (cards ~360–559px)."
+    )
+    medium: int = Field(
+        description="Level offset for the medium tier (cards ~560–1099px)."
+    )
+    wide: int = Field(
+        description="Level offset for the wide tier (cards ~1100px and up)."
+    )
+
+
+class TitlePositionStyle(BaseModel):
+    """Vega-Lite title positioning pass-throughs grouped as a sub-object."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    anchor: str = Field(description="Title anchor position; theme always sets this.")
+    # Only set in themes that override angle; None lets Vega-Lite choose.
+    angle: float | None = Field(
+        default=None,
+        description="Title rotation angle in degrees; None lets Vega-Lite choose.",
+    )
+    # Default theme supplies 10; None means inherit Vega-Lite's built-in default.
+    offset: float | None = Field(
+        default=None,
+        description="Title offset from its anchor in pixels; None uses Vega-Lite's default.",
+    )
+    # Only set in themes that override baseline; None lets Vega-Lite choose.
+    baseline: str | None = Field(
+        default=None,
+        description="Title text baseline alignment; None uses Vega-Lite's default.",
+    )
+
+
+class TitleSubtitleStyle(BaseModel):
+    """VL subtitle font pass-through, grouped for consistency with TitleStyle.font."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # FontStyle is an all-Optional overlay; default_factory creates an empty
+    # instance that the cascade fills from theme YAML (same pattern as TitleStyle.font).
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Subtitle font style overrides (color, family, size, weight).",
+    )
+
+
+class TitleStyle(BaseModel):
+    """Board and face titles."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Title font style overrides."
+    )
+    line_height: float = Field(
+        description=(
+            "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] = Field(
+        description=(
+            "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 = Field(
+        description=(
+            "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 = Field(description="Minimum title row height in pixels.")
+    overflow: str = Field(
+        description="Text overflow mode (clip, truncate, wrap-two, wrap)."
+    )
+    position: TitlePositionStyle = Field(
+        description="Vega-Lite title positioning: anchor, angle, offset, baseline."
+    )
+    # Author/theme override for heading level. "auto" = compute from titled-ancestor count;
+    # an integer locks all titles in this scope to that H-level and propagates to descendants.
+    # Theme YAML supplies "auto" as the universal default.
+    level: int | Literal["auto"] = Field(
+        description=(
+            "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."
+        ),
+    )
+    # VL subtitle font config (ADR-005: color inside font)
+    subtitle: TitleSubtitleStyle = Field(
+        default_factory=TitleSubtitleStyle,
+        description="Subtitle font styles.",
+    )
+
+    @field_validator("level", mode="before")
+    @classmethod
+    def _validate_level(cls, value: Any) -> Any:
+        if value == "auto":
+            return value
+        if isinstance(value, int):
+            if value < 1:
+                raise ValueError(f"style.title.level must be >= 1, got {value!r}")
+            return value
+        if isinstance(value, str):
+            raise ValueError(
+                f"style.title.level must be 'auto' or a positive integer, got {value!r}"
+            )
+        return value
+
+    @field_validator("overflow", mode="before")
+    @classmethod
+    def _normalize_overflow(cls, value: Any) -> Any:
+        return _normalize_overflow_value(value)
+
+    @model_validator(mode="after")
+    def _validate_level_within_ramp(self) -> TitleStyle:
+        if isinstance(self.level, int) and self.level > len(self.sizes):
+            raise ValueError(
+                f"style.title.level={self.level} exceeds the H-ramp "
+                f"(sizes has {len(self.sizes)} entries; valid range is 1..{len(self.sizes)})"
+            )
+        return self
+
+
+class TextStyle(BaseModel):
+    """Markdown / plain text content."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Text font style overrides."
+    )
+    line_height: float = Field(description="Line height multiplier for text content.")
+    align: Literal["left", "center", "right"] = Field(
+        description="Text alignment for the face body-text block."
+    )
+    column: TextColumnStyle = Field(
+        default_factory=TextColumnStyle,
+        description="Multi-column layout for the face body-text block.",
+    )
+
+
+# Callout chart
+
+
+class CalloutElementStyle(BaseModel):
+    """Font + y_offset for a callout title or message."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Element font style overrides."
+    )
+    y_offset: float = Field(
+        description="Vertical offset from the element's anchor in pixels."
+    )
+
+
+class CalloutChartStyle(BaseModel):
+    """Chart-family style for ``type: callout`` charts and runtime chart-error fallback cards.
+
+    Background/border/text colors are resolved from ``{tone}.*`` palette roles
+    (bg, border, solid, text) at render time.  This model carries structural
+    defaults (padding, section_gap, font metrics) plus the semantic tone selector.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Semantic palette selector. None → "negative" at render time.
+    tone: str | None = Field(
+        default=None,
+        description="Semantic tone for palette-role lookup (positive | negative | warning). Defaults to negative.",
+    )
+    background: str = Field(
+        description="Callout card background color (negative.bg default)."
+    )
+    border: BorderStyle = Field(description="Callout card border style.")
+    padding: float = Field(description="Inner padding of the callout card in pixels.")
+    section_gap: float = Field(
+        description="Vertical gap between callout title and message in pixels."
+    )
+    title: CalloutElementStyle = Field(description="Callout title element style.")
+    message: CalloutElementStyle = Field(description="Callout message element style.")
+
+
+# Placeholder
+
+
+class PlaceholderOverlay(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    text: str = Field(description="Placeholder overlay text shown on empty charts.")
+    background: str = Field(description="Overlay background color.")
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Overlay font style overrides."
+    )
+
+
+class PlaceholderStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float = Field(description="Opacity of the placeholder overlay (0–1).")
+    overlay: PlaceholderOverlay = Field(
+        description="Overlay text and background style."
+    )
+
+
+# Axis
+
+
+class AxisGridZeroStyle(BaseModel):
+    """Zero-baseline gridline color and width overrides.
+
+    Nested sub-object under AxisGridStyle.zero. Quantitative axes only —
+    band axes never tick at value=0.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # All fields nullable — cascade fills from parent axis into axis_x/y/quantitative.
+    color: str | None = Field(  # None inherits from parent axis zero.color
+        default=None,
+        description="Color of the zero-baseline grid line; None inherits from parent axis.",
+    )
+    width: float | None = Field(  # None inherits from parent axis zero.width
+        default=None,
+        description="Width of the zero-baseline grid line in pixels; None inherits from parent axis.",
+    )
+
+
+class AxisGridStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # All fields are nullable in AxisGridStyle so the cascade can fill
+    # missing values from parent `axis` into `axis_x` / `axis_y` /
+    # `axis_quantitative`. The base `axis` slot must have all fields non-None;
+    # `_build_resolved_axis` validates this at resolve time.
+    visible: bool | None = Field(
+        default=None, description="Show grid lines; None inherits from parent axis."
+    )
+    opacity: float | None = Field(
+        default=None, description="Grid line opacity; None uses Vega-Lite's default."
+    )
+    width: float | None = Field(
+        default=None,
+        description="Grid line width in pixels; None uses Vega-Lite's default.",
+    )
+    color: str | None = Field(
+        default=None, description="Grid line color; None uses Vega-Lite's default."
+    )
+    dash: list[float] | None = Field(
+        default=None,
+        description="Dash pattern for grid lines; None renders a solid line.",
+    )
+    # Zero-baseline sub-block. None on child axes means "no override at this level";
+    # the cascade fills individual zero.* fields from the parent axis.
+    zero: AxisGridZeroStyle | None = (
+        Field(  # None — no zero-baseline authored at this level
+            default=None,
+            description="Zero-baseline gridline style; None inherits from parent axis.",
+        )
+    )
+
+
+class AxisDomainStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Nullable so the cascade can fill missing values from parent `axis`.
+    visible: bool | None = Field(
+        default=None,
+        description="Show the axis domain line; None inherits from parent axis.",
+    )
+    width: float | None = Field(
+        default=None,
+        description="Domain line width in pixels; None uses Vega-Lite's default.",
+    )
+    color: str | None = Field(
+        default=None, description="Domain line color; None uses Vega-Lite's default."
+    )
+
+
+class AxisTicksStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Nullable so the cascade can fill `visible` from parent `axis`.
+    visible: bool | None = Field(
+        default=None, description="Show axis ticks; None inherits from parent axis."
+    )
+    color: str | None = Field(
+        default=None, description="Tick color; None uses Vega-Lite's default."
+    )
+    size: float | None = Field(
+        default=None,
+        description="Tick length in pixels; None uses Vega-Lite's default.",
+    )
+    width: float | None = Field(
+        default=None,
+        description="Tick stroke width in pixels; None uses Vega-Lite's default.",
+    )
+    count: int | None = Field(
+        default=None,
+        description=(
+            "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."
+        ),
+    )
+
+
+class AxisElementStyle(BaseModel):
+    """Axis label or title: font + padding + VL-passthrough."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Axis element font style overrides."
+    )
+    padding: float | None = Field(
+        default=None,
+        description="Padding between axis labels and ticks in pixels; None inherits from parent axis.",
+    )
+    max_width: float | None = Field(
+        default=None,
+        description="Maximum label width in pixels; None uses Vega-Lite's default (180px).",
+    )
+    angle: float | None = Field(
+        default=None,
+        description="Label rotation angle in degrees; None uses Vega-Lite's default.",
+    )
+    align: str | None = Field(
+        default=None,
+        description="Horizontal text alignment of labels; None uses Vega-Lite's default.",
+    )
+    baseline: str | None = Field(
+        default=None,
+        description="Vertical text baseline of labels; None uses Vega-Lite's default.",
+    )
+    # "smart" → omit labelOverlap from VL spec (gets per-scale adaptive default).
+    # "allow" → emit labelOverlap: false (no reduction; labels may overlap).
+    # "parity" / "greedy" → pass through as-is.
+    # Raw true/false rejected — use named strings.
+    overlap: Literal["smart", "parity", "greedy", "allow"] | None = Field(
+        default=None,
+        description="Label overlap reduction strategy; None uses Vega-Lite's per-scale default.",
+    )
+    separation: float | None = Field(
+        default=None,
+        description="Minimum pixel separation between labels; None uses Vega-Lite's default (0px).",
+    )
+    visible: bool | None = Field(
+        default=None,
+        description="Show axis labels; None uses Vega-Lite's default (labels shown).",
+    )
+    # Optional label cadence for temporal axes. None inherits from the parent
+    # axis time_unit, except yearweek defaults to month labels.
+    time_unit: (
+        Literal[
+            "auto",
+            "year",
+            "yearquarter",
+            "yearmonth",
+            "yearweek",
+            "yearmonthdate",
+            "monthofyear",
+            "dayofweek",
+            "dayofmonth",
+            "dayofyear",
+            "hourofday",
+            "none",
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description="Label cadence for temporal axes; None inherits from the parent axis time_unit.",
+    )
+    # When None and the parent axis has a temporal time_unit, the render layer
+    # fills in a smart conditional labelExpr — see render/chart/time_unit_detect.py.
+    expr: str | None = Field(
+        default=None,
+        description="Custom Vega expression for label text; None uses smart temporal defaults when applicable.",
+    )
+    # Positioning knobs — all None means VL per-axis defaults apply.
+    bound: bool | float | None = Field(
+        default=None,
+        description="Hide labels that overflow the axis range; None uses Vega-Lite's default.",
+    )
+    flush: bool | float | None = Field(
+        default=None,
+        description="Align first/last label flush with the scale range; None uses Vega-Lite's default.",
+    )
+    offset: float | None = Field(
+        default=None,
+        description="Pixel offset of the label from its tick anchor; None uses Vega-Lite's default.",
+    )
+    line_height: float | None = Field(
+        default=None,
+        description="Line height for multi-line labels in pixels; None uses Vega-Lite's default.",
+    )
+    anchor: Literal["start", "middle", "end"] | None = Field(default=None, description="Label anchor position; None uses Vega-Lite's default.")  # fmt: skip
+    # Descending tilt ladder consulted by overlap="smart" on discrete x-axes.
+    # The picker walks this list and chooses the first angle whose label widths
+    # fit at the chart's drawable width; fall-through uses the last entry and
+    # downgrades overlap to "parity". None means picker is disabled (used on
+    # y-axis and any axis the resolver does not target).
+    tilt_increments: list[float] | None = Field(
+        default=None,
+        min_length=1,
+        description="Descending tilt angles for smart label overlap on discrete x-axes; None disables the picker.",
+    )
+
+    @field_validator("overlap", mode="before")
+    @classmethod
+    def _reject_bool_overlap(cls, v: object) -> object:
+        if v is True:
+            raise ValueError(
+                'overlap: true is ambiguous — use "smart" for per-scale adaptive '
+                '(the most likely intent) or "parity" for the literal VL true '
+                "semantic (drop every other label on any scale)."
+            )
+        if v is False:
+            raise ValueError(
+                'overlap: false reads backwards — use "allow" to permit labels '
+                "to overlap (no reduction)."
+            )
+        return v
+
+
+class ScaleBandStyle(BaseModel):
+    """Band mark size constraints (min/max pixel width for band-scale marks)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min_size: float | None = Field(  # None = no min constraint; authored overlay
+        default=None,
+        description="Minimum band mark width in pixels; None uses Vega-Lite's default.",
+    )
+    max_size: float | None = Field(  # None = no max constraint; authored overlay
+        default=None,
+        description="Maximum band mark width in pixels; None uses Vega-Lite's default.",
+    )
+
+
+class ScaleStyle(BaseModel):
+    """Scale configuration primitive.
+
+    Used both at chart-level (``style.scale`` — applies to both x and y) and
+    per-axis (``style.axis_x.scale``, ``style.axis_y.scale`` — overrides on
+    that channel only). Per-axis values win on conflict.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    band_padding_inner: float | None = Field(
+        default=None,
+        description="Inner padding fraction for band scales; None uses Vega-Lite's default.",
+    )
+    band_padding_outer: float | None = Field(
+        default=None,
+        description="Outer padding fraction for band scales; None uses Vega-Lite's default.",
+    )
+    point_padding: float | None = Field(
+        default=None,
+        description="Padding fraction for point scales; None uses Vega-Lite's default.",
+    )
+    rect_band_padding_inner: float | None = Field(
+        default=None,
+        description="Inner padding fraction for rect band scales; None uses Vega-Lite's default.",
+    )
+    round: bool | None = Field(
+        default=None,
+        description="Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).",
+    )
+    zero: bool | None = Field(
+        default=None,
+        description="Force scale to include zero; None uses Vega-Lite's default.",
+    )
+    clamp: bool | None = Field(
+        default=None,
+        description="Clamp values to scale domain; None uses Vega-Lite's default (no clamping).",
+    )
+    continuous_padding: float | None = Field(
+        default=None,
+        description="Padding in pixels for continuous scales; None uses Vega-Lite's default.",
+    )
+    band: ScaleBandStyle | None = Field(  # None = no band size constraint authored
+        default=None,
+        description="Band mark size constraints; None uses Vega-Lite's defaults.",
+    )
+    quantile_count: int | None = Field(
+        default=None,
+        description="Number of quantile buckets; None uses Vega-Lite's default.",
+    )
+    quantize_count: int | None = Field(
+        default=None,
+        description="Number of quantize buckets; None uses Vega-Lite's default.",
+    )
+    use_unaggregated_domain: bool | None = Field(
+        default=None,
+        description="Use unaggregated domain for scale extent; None uses Vega-Lite's default.",
+    )
+    x_reverse: bool | None = Field(
+        default=None,
+        description="Reverse the x-axis scale direction; None means no reversal.",
+    )
+    type: str | None = Field(
+        default=None,
+        description="Scale type override; None lets Vega-Lite infer from field type.",
+    )
+    domain: list | None = Field(
+        default=None,
+        description="Explicit scale domain values; None lets Vega-Lite auto-determine from data.",
+    )
+    nice: bool | None = Field(
+        default=None,
+        description="Round scale domain to nice values; None uses Vega-Lite's default.",
+    )
+    # Unified shortcut. Maps to VL ``scale.padding``, which Vega-Lite itself
+    # dispatches per scale type: bandPaddingOuter for band, pointPadding for
+    # point, continuousPadding for continuous. Note that VL interprets this
+    # in pixels for continuous scales but as a fraction (0..1) for band/point.
+    padding: float | None = Field(
+        default=None,
+        description="Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type.",
+    )
+
+
+class RangeStylePatch(BaseModel):
+    """Chart-local palette/range overlay — no theme cascade.
+
+    Sets VL range.category, diverging, heatmap, ramp per chart.
+    Theme-level categorical palette is set via ChartsStyle.palette, not this type.
+    All fields optional; None means "not overridden at this level".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    category: list[str] | None = Field(
+        default=None,
+        description="Per-chart categorical color palette (list of CSS color strings).",
+    )
+    diverging: list[str] | None = Field(
+        default=None, description="Per-chart diverging color scale colors."
+    )
+    heatmap: list[str] | None = Field(
+        default=None, description="Per-chart heatmap color scale colors."
+    )
+    ramp: list[str] | None = Field(
+        default=None, description="Per-chart sequential color ramp colors."
+    )
+
+
+# RangeStylePatch has no compiled counterpart — it IS the authored-overlay shape.
+# Register it as its own patch so build_patch_model doesn't synthesise a
+# double-suffixed RangeStylePatchPatch when processing CartesianChartStyle fields.
+register_as_own_patch(RangeStylePatch)
+
+
+class TooltipStyle(BaseModel):
+    """Tooltip rendering defaults."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    format: str = Field(
+        description="Default tooltip value format string; theme always provides this."
+    )
+
+
+class AxisStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    grid: AxisGridStyle = Field(
+        default_factory=AxisGridStyle, description="Grid line style for this axis."
+    )
+    domain: AxisDomainStyle = Field(
+        default_factory=AxisDomainStyle, description="Domain line style for this axis."
+    )
+    ticks: AxisTicksStyle = Field(description="Tick mark style for this axis.")
+    label: AxisElementStyle = Field(
+        default_factory=AxisElementStyle, description="Axis label style."
+    )
+    title: AxisElementStyle = Field(
+        default_factory=AxisElementStyle, description="Axis title style."
+    )
+    # "auto" → "right" by default; flips to "left" when chart has right-edge
+    # series labels (e.g. line endpoint labels). VL passthrough for explicit values.
+    orient: Literal["left", "right", "top", "bottom", "auto"] | None = Field(
+        default=None,
+        description="Axis orientation; auto flips y-axis when endpoint labels are present.",
+    )
+    # Only populated on axis_y in theme YAML; None on shared/x/quantitative/band
+    # axes means "skip this VL property" matching the VL config emit layer.
+    categorical_orient: str | None = Field(
+        default=None,
+        description="Orientation for categorical y-axis (e.g. 'left'); None skips this VL property.",
+    )
+    band_position: float | None = Field(
+        default=None,
+        description="Band position within the step (0–1); None uses Vega-Lite's default.",
+    )
+    offset: float | None = Field(
+        default=None,
+        description="Pixel offset of the axis from its default position; None means no offset.",
+    )
+    # Encoding-level passthrough: applied to encoding.y.axis, not config.axis
+    format: str | None = Field(
+        default=None, description="Tick value format string; None uses auto-format."
+    )
+    values: list | None = Field(
+        default=None,
+        description="Explicit tick values; None uses Vega-Lite's auto tick values.",
+    )
+    # Time-unit bucketing for temporal x axes (auto-detected when None or "auto").
+    # "none" disables bucketing (continuous temporal). VL timeUnit values otherwise.
+    time_unit: (
+        Literal[
+            "auto",
+            "year",
+            "yearquarter",
+            "yearmonth",
+            "yearweek",
+            "yearmonthdate",
+            "monthofyear",
+            "dayofweek",
+            "dayofmonth",
+            "dayofyear",
+            "hourofday",
+            "none",
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description="Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data.",
+    )
+    # Per-axis scale overrides — applied to encoding.{x,y}.scale, win over
+    # the chart-level ``style.scale`` when both are set.
+    scale: ScaleStyle | None = Field(
+        default=None, description="Per-axis scale overrides; None means no override."
+    )
+
+    # Authored opt-in scale type for bucketed-time x-axes (axis_x only).
+    # None/"auto" = ordinal when time_unit resolves to a bucketed-calendar
+    # grain, temporal for continuous date. "temporal" forces the temporal
+    # escape-hatch path. "ordinal" forces ordinal. Author always wins.
+    type: Literal["auto", "ordinal", "temporal"] | None = Field(
+        default=None,
+        description="Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain.",
+    )
+    # Fill mode for missing time buckets on ordinal bucketed-time x-axes.
+    # "null" → synthesized rows carry null measures; line/area breaks at gap.
+    # "zero" → synthesized rows carry 0 measures; event-count charts opt in.
+    # linear / step-* / curve → fill interior synthetic buckets (Looker-aligned names).
+    # Required; theme YAML supplies the default ("null") via axis_x.fill.
+    fill: Literal[
+        "null",
+        "zero",
+        "linear",
+        "step-after",
+        "step-before",
+        "step-center",
+        "curve",
+    ] = Field(
+        description=(
+            "Fill for synthesized missing-bucket rows: null, zero, linear, "
+            "step-after / step-before / step-center (Looker step), or curve (smoothstep)."
+        ),
+    )
+
+    @field_validator("fill", mode="before")
+    @classmethod
+    def _yaml_null_is_null_fill_mode(cls, value: object) -> object:
+        # Theme YAML uses `fill: null` for the null fill mode; YAML parses that as None.
+        if value is None:
+            return "null"
+        return value
+
+
+# Patch type generated here so chart-type styles (Bar, Line, Area, Scatter, Arc)
+# can reference it as a per-chart-type axis sentinel field.
+# TYPE_CHECKING stub mirrors the DataTable/Table pattern — gives mypy a proper
+# class (with accurate field names from AxisStyle) while the runtime uses
+# the dynamically created patch model from build_patch_model().
+if TYPE_CHECKING:
+
+    class AxisStylePatch(AxisStyle):
+        pass
+
+else:
+    AxisStylePatch = build_patch_model(AxisStyle)
+
+
+# Legend
+
+
+class LegendElementStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Legend element font style overrides.",
+    )
+    padding: float = Field(
+        description="Padding between legend symbol and element text in pixels."
+    )
+
+
+class LegendStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    orient: str = Field(description="Legend orientation (e.g. 'right', 'bottom').")
+    direction: str = Field(
+        description="Legend layout direction ('vertical' or 'horizontal')."
+    )
+    label: LegendElementStyle = Field(description="Legend label style.")
+    title: LegendElementStyle = Field(description="Legend title style.")
+    disable: bool | None = Field(
+        default=None,
+        description="Suppress the legend entirely; None means legend is visible.",
+    )
+    interactive_legend: bool = Field(
+        description="Emit a dft_legend point-selection param for single-click series toggle.",
+    )
+
+
+# Inference
+
+
+class InferenceStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Engine behavior flags — not visual style. Code defaults are canonical;
+    # themes may override but most don't need to.
+    infer_zero_when_missing: bool = Field(
+        default=True, description="Auto-infer zero-baseline when not authored."
+    )
+    infer_fields_when_missing: bool = Field(
+        default=True,
+        description="Auto-infer chart fields (x, y, etc.) when not authored.",
+    )
+    infer_type_when_auto: bool = Field(
+        default=True, description="Auto-infer chart type when type is 'auto'."
+    )
+
+
+def _coerce_pagination_value(v: Any) -> Any:
+    """Expand pagination shorthand: int → page_size, bool → enabled."""
+    if isinstance(v, bool):
+        return {"enabled": v}
+    if isinstance(v, int):
+        return {"enabled": True, "page_size": v}
+    return v
+
+
+class PaginationConfig(BaseModel):
+    """Table pagination configuration.
+
+    Controls client-side row paging for table charts. This is a presentation
+    concern (how many rows to show per page), distinct from query-level ``limit``
+    which controls how many rows are *fetched*.
+
+    Shorthand forms are normalised by a ``field_validator`` on the containing
+    style model:
+    - ``pagination: 25``   → PaginationConfig(enabled=True, page_size=25)
+    - ``pagination: true``  → PaginationConfig(enabled=True)
+    - ``pagination: false`` → PaginationConfig(enabled=False)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(
+        default=True, description="Enable client-side pagination for table charts."
+    )
+    page_size: int | None = Field(
+        default=None,
+        description=(
+            "Rows per page. When enabled and None, the renderer auto-fits page size "
+            "to the cell — set explicitly to pin the page size."
+        ),
+    )
+
+    @field_validator("page_size")
+    @classmethod
+    def _page_size_positive(cls, v: int | None) -> int | None:
+        if v is not None and v < 1:
+            raise ValueError("page_size must be a positive integer")
+        return v
+
+
+# Per-chart-type styles
+
+
+class EndpointLabelsConfig(BaseModel):
+    """Endpoint label pane config — shared across line, area, and bar.
+
+    When visible, a separate pane is emitted alongside the main chart with one
+    text mark per series. For line/area and vertical stacked/grouped bar, the
+    pane is hconcat to the right, anchored at the family's "trailing-x" slice
+    (endpoint, segment midpoint, or bar top). For horizontal stacked bar, the
+    pane is vconcat above the chart, with each label centered on its segment
+    midpoint in the top categorical row. Typography is sourced from
+    ``style.charts.series_label.font.*``.
+
+    Theme-tunable: all fields live in theme YAML.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Render-visibility toggle. Theme writes false; authors flip to true per chart.
+    visible: bool = Field(
+        description="Show endpoint labels; theme sets false, authors opt in per chart."
+    )
+    # Spacing (px) between the chart pane and the label pane —
+    # passed through as the hconcat or vconcat spacing depending on orientation.
+    label_offset: float = Field(
+        description="Spacing in pixels between the chart pane and the label pane."
+    )
+
+
+class TextMarkStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Text mark font style overrides."
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    align: str | None = Field(
+        default=None, description="Horizontal text alignment for text marks."
+    )
+
+
+class SeriesLabelStyle(BaseModel):
+    """Series-label primitive — typography for any text mark that names a
+    data series, regardless of placement.
+
+    Endpoint labels (line/area), direct stack labels (bar-stacked), and slice
+    callouts (pie) all read their typography from this single primitive.
+    Placement is family-specific; typography is shared.
+
+    No ``align`` field: alignment is a placement decision owned by the
+    family-specific renderer (endpoint labels left-anchor in their pane;
+    callouts anchor along their leader line; etc.).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Empty FontStyle starter; cascade fills missing fields from
+    # ``charts.font`` in ``_apply_cascade`` (same pattern as
+    # ``TextMarkStyle.font`` and ``TotalSlotStyle.font``).
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Series label font style overrides; cascade fills missing fields from charts.font.",
+    )
+
+
+class TotalSlotStyle(BaseModel):
+    """Theme slot for one text element of the donut center total."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Empty FontStyle starter; cascade fills missing fields from
+    # ``charts.font`` (same pattern as KpiStyle).
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Donut center total element font style overrides.",
+    )
+
+
+class TotalStyle(BaseModel):
+    """Donut center total paint: value (the number) and label (the caption)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: TotalSlotStyle = Field(
+        description="Style for the donut center value (the number)."
+    )
+    label: TotalSlotStyle = Field(
+        description="Style for the donut center label (the caption)."
+    )
+
+
+class SliceLabelsStyle(BaseModel):
+    """Pie labels: typography + positioning offsets for per-slice text."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    offset: float = Field(
+        description="Radial offset of slice labels from the arc in pixels."
+    )
+    block_height: float = Field(
+        description="Reserved height per label block in pixels."
+    )
+    line_height: float = Field(
+        description="Line height for multi-line slice labels in pixels."
+    )
+    # Empty FontStyle starter; the resolve cascade fills missing fields
+    # from the parent ``charts.font``. Pattern matches KpiStyle /
+    # LegendStyle.
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Slice label font style overrides."
+    )
+
+
+# =============================================================================
+# CHART-FAMILY STYLE BASE CLASS HIERARCHY (ADR-015)
+#
+# Private bases (leading underscore — never authored directly):
+#   _ChartStyleBase             → required geometry/frame fields (cascade source)
+#   _ChartStyleBaseAllOptional  → all-optional variant (per-family base);
+#                                 None on any field = inherit from ChartsStyle
+#     _CartesianChartStyle      → bar/line/area/scatter/histogram/heatmap/… (axis_x/y)
+#     _RadialChartStyle         → pie/donut (inner_radius, total)
+#     _GeoChartStyle            → geoshape/point_map (projection, basemap)
+#   KpiChartStyle, TableChartStyle inherit _ChartStyleBaseAllOptional directly
+#   (no palette, legend, tooltip, or marks pipeline)
+# =============================================================================
+
+
+class ProjectionStyle(BaseModel):
+    """Vega-Lite map projection configuration for geo chart families."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(
+        description="Vega-Lite projection type (e.g. 'mercator', 'albersUsa', 'equalEarth')."
+    )
+
+
+class BasemapStyle(BaseModel):
+    """Background map layer for geo charts (especially point maps).
+
+    ``source`` is the topography source identifier. None means no background
+    topo layer — the chart renders points or shapes on a blank canvas.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # None = no background layer. Point maps may omit the basemap entirely
+    # when the data projection is self-explanatory (e.g. lat/lng scatter).
+    source: str | None = Field(
+        default=None,
+        description="Background topo source identifier; None means no base layer.",
+    )
+
+
+class _ChartStyleBase(BaseModel):
+    """Required geometry/frame fields — the cascade source for all chart families.
+
+    ``ChartsStyle`` inherits this class to supply the authoritative global values.
+    ``_ChartStyleBaseAllOptional`` (generated via ``build_patch_model``) is used as
+    the per-family base, where ``None`` on any field means "inherit from
+    ``ChartsStyle`` via the cascade".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Chart-level font overrides.",
+    )
+    aspect_ratio: float = Field(description="Chart aspect ratio (width/height).")
+    min_height: float = Field(description="Minimum chart height in pixels.")
+    max_height: float = Field(description="Maximum chart height in pixels.")
+    padding: PaddingStyle = Field(description="Chart inner padding in pixels.")
+    border: BorderStyle = Field(description="Chart card border style.")
+    animation_duration: float = Field(
+        description="Vega-Lite animation duration in milliseconds."
+    )
+
+    # Color palette — accepts an explicit list of stops or a categorical
+    # palette name (e.g. ``"category-10"``). The string form is expanded to
+    # the palette's stops at validation time so the field always materializes
+    # as ``list[str]`` downstream.
+    # ``| str`` is present so generated patch models (which don't inherit the
+    # validator) accept string palette names; the cascade expands them.
+    palette: list[str] | str = Field(
+        description="Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time."
+    )
+
+    @field_validator("palette", mode="before")
+    @classmethod
+    def _expand_palette_name(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            from dataface.core.compile.palette import palette as resolve_palette
+
+            return resolve_palette(value)
+        return value
+
+    # Dash palette for line-family marks. None means "no strokeDash encoding";
+    # themes that want dash-based categorical distinction set this. Cascade-
+    # managed sentinel — the render layer reads None and skips emission.
+    dashes: list[list[int]] | None = Field(
+        default=None,
+        description="Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission.",
+    )
+
+    # Inference
+    inference: InferenceStyle = Field(
+        default_factory=InferenceStyle, description="Engine inference behavior flags."
+    )
+
+    # Legend
+    legend: LegendStyle = Field(description="Chart legend style.")
+
+    # Tooltip
+    tooltip: TooltipStyle = Field(description="Chart tooltip style.")
+
+    # Cascade-managed sentinels — chart-local paint and typography overrides.
+    # None propagates unchanged through the cascade; no theme-level default
+    # exists for these per-chart fields. ChartsStyle inherits these as optional
+    # fields that theme YAML may omit.
+    background: str | None = Field(
+        default=None,
+        description="Chart-local background color override; None inherits from theme.",
+    )
+    # StyleColorConfig enables gradient-scale color mode (style.color: {scale: ...}).
+    # The cascade stores only str values in MergedChartsStyle.color (see style_cascade.py);
+    # StyleColorConfig is consumed ephemerally by normalize_chart_channels in the pipeline.
+    color: str | StyleColorConfig | None = Field(
+        default=None,
+        description="Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.",
+    )
+    title: TitleStyle | None = Field(
+        default=None,
+        description="Chart-level title style override; None inherits the theme title style.",
+    )
+
+
+# All-optional variant of _ChartStyleBase — per-family styles use this as their base.
+# None on any field is a cascade sentinel meaning "inherit from ChartsStyle global".
+# build_patch_model_ext with is_recursive=True converts nested BaseModel fields to
+# their patch types (e.g. LegendStyle -> LegendStylePatch | None), so per-family
+# theme overrides like bar.legend.disable: false validate cleanly with partial dicts.
+if TYPE_CHECKING:
+
+    class _ChartStyleBaseAllOptional(_ChartStyleBase):
+        pass
+
+else:
+    _ChartStyleBaseAllOptional = build_patch_model_ext(
+        _ChartStyleBase, is_recursive=True
+    )
+
+
+class _CartesianChartStyle(_ChartStyleBaseAllOptional):
+    """Cartesian families: bar, line, area, scatter, histogram, heatmap, boxplot, errorbar/band.
+
+    Shared axis tier — theme YAML populates per-family axis overrides here.
+    """
+
+    axis: AxisStylePatch | None = Field(
+        default=None,
+        description="Override applied to both x and y axes; None inherits global axis defaults.",
+    )
+    axis_x: AxisStylePatch | None = Field(
+        default=None,
+        description="Per-chart-type x-axis style overrides; None inherits global axis defaults.",
+    )
+    axis_y: AxisStylePatch | None = Field(
+        default=None,
+        description="Per-chart-type y-axis style overrides; None inherits global axis defaults.",
+    )
+    axis_quantitative: AxisStylePatch | None = Field(
+        default=None,
+        description="Per-chart-type quantitative-axis overrides; None inherits global defaults.",
+    )
+    axis_band: AxisStylePatch | None = Field(
+        default=None,
+        description="Per-chart-type categorical (band) axis overrides; None inherits global band defaults.",
+    )
+    number_format: str | None = Field(
+        default=None,
+        description="Default number format for axes and tooltips (D3 format string); None inherits from theme.",
+    )
+    time_format: str | None = Field(
+        default=None,
+        description="Default time format for temporal axes (D3 time format string); None inherits from theme.",
+    )
+    scale: ScaleStyle | None = Field(
+        default=None,
+        description="Chart-type encoding scale overrides applied to both x and y; None means no override.",
+    )
+    range: RangeStylePatch | None = Field(
+        default=None,
+        description="Color range/palette overrides for this chart type; None means no override.",
+    )
+    data_table: DataTableStylePatch | None = Field(
+        default=None,
+        description="Per-chart-type data_table style override; None uses the universal style.charts.data_table.",
+    )
+
+
+class _RadialChartStyle(_ChartStyleBaseAllOptional):
+    """Radial families: pie, donut."""
+
+    # Optional sentinel: None means 'no inner radius' (solid pie); float means donut.
+    # The None state is meaningful in the resolved model — NOT a 'theme failed to populate'
+    # fallback. Cascade preserves None through merge so the renderer can branch on solid
+    # vs. donut without re-reading raw YAML.
+    inner_radius: float | None = Field(
+        default=None,
+        ge=0,
+        le=1,
+        description="Hole-to-disk ratio 0–1 (inner radius / outer radius). None = solid pie (no hole).",
+    )
+    total: TotalStyle = Field(description="Donut center total paint (value and label).")
+
+
+class _GeoChartStyle(_ChartStyleBaseAllOptional):
+    """Geo families: geoshape (choropleth), point_map.
+
+    ``geo_source`` is intentionally absent — it is a chart-root channel field
+    (on ``_GeoChartFields``), not a style concern.
+    ``color_scheme`` is choropleth-specific — declared on ``GeoshapeChartStyle`` leaf only.
+    """
+
+    projection: ProjectionStyle = Field(
+        description="Vega-Lite projection configuration for this geo family."
+    )
+    basemap: BasemapStyle = Field(
+        default_factory=BasemapStyle,
+        description="Background map layer; None source = no topo layer.",
+    )
+
+
+# =============================================================================
+# MARK STYLE CLASSES (<Mark>MarkStyle)
+#
+# One class per VL mark type. Each carries ONLY mark-level properties
+# (geometry, opacity, stroke) — no chart-level concerns (axis, legend, etc.).
+#
+# ALL fields are Optional (None = "not specified in this tier"). These types
+# serve as cascade-tier containers in the three-tier mark cascade:
+#   tier-1 GlobalMarksStyle → tier-2 <Family>ChartMarksStyle → tier-3 face override
+# None means "inherit from a lower-numbered tier", not "theme failed to populate".
+# resolve_mark(global, family) merges tiers using deep_merge (exclude_unset).
+#
+# GlobalMarksStyle aggregates all 17 marks; per-family ChartMarksStyle
+# exposes only the marks that family actually emits.
+# =============================================================================
+
+
+class BarMarkStyle(BaseModel):
+    """Bar mark geometry and stroke. Chart-level bar fields live on BarChartStyle.
+
+    All fields None = "not set at this tier; inherit from global".
+    resolve_mark() merges the final value across tiers.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    border: BorderStyle | None = Field(
+        default=None,
+        description="Bar border style (color/width also serve as the bar stroke).",
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    padding: float | None = Field(
+        default=None, description="Padding around bar marks in pixels."
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    size: float | None = Field(
+        default=None, description="Bar width in pixels (fixed-width mode)."
+    )
+    # Bar width as a fraction of the band step (0..1). Maps to VL
+    # ``mark.width: {band: N}`` and works on temporal/utc x scales so
+    # time-unit bars can preserve gaps while keeping consistent column widths.
+    # Cascade tier sentinel: None means "not specified at this tier".
+    band_width: float | None = Field(
+        default=None,
+        description="Bar width as a fraction of the band step (0–1).",
+    )
+
+
+class LineMarkStyle(BaseModel):
+    """Line mark stroke, interpolation, and halo. Point mark lives on PointMarkStyle.
+
+    All fields None = "not set at this tier; inherit from global".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    stroke: StrokeStyle | None = Field(default=None, description="Line stroke style.")
+    # Cascade tier sentinel: None means "not specified at this tier".
+    curve: str | None = Field(
+        default=None,
+        description="Line interpolation curve (e.g. 'linear', 'monotone').",
+    )
+    # Halo: a knockout-coloured line drawn behind the foreground line so that
+    # crossings read cleanly. ``halo_multiplier`` of 0 disables it; otherwise
+    # the halo stroke width and (when points are enabled) halo point size are
+    # ``base * halo_multiplier``. Halo colour is the chart's effective background.
+    # Cascade tier sentinel: None means "not specified at this tier".
+    halo_multiplier: float | None = Field(
+        default=None,
+        description="Halo stroke width multiplier relative to stroke.width; 0 disables the halo.",
+    )
+
+
+class AreaMarkStyle(BaseModel):
+    """Area mark fill opacity, stroke, and halo.
+
+    All fields None = "not set at this tier; inherit from global".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    opacity: float | None = Field(default=None, description="Area fill opacity (0–1).")
+    # Cascade tier sentinel: None means "not specified at this tier".
+    stroke: StrokeStyle | None = Field(
+        default=None, description="Area top-edge stroke style."
+    )
+    # Halo: a knockout-coloured stroke drawn behind the foreground area's top-edge
+    # line so that crossings between series read cleanly.
+    # Cascade tier sentinel: None means "not specified at this tier".
+    halo_multiplier: float | None = Field(
+        default=None,
+        description="Halo stroke width multiplier relative to stroke.width; 0 disables the halo.",
+    )
+
+
+class PointMarkStyle(BaseModel):
+    """Point mark style (data-point markers on line/area/scatter charts).
+
+    All fields are Optional. None = "not specified / inherit from global or VL default".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    size: float | None = Field(
+        default=None,
+        description="Point size in square pixels; 0 disables points on line charts.",
+    )
+    # None = inherits from chart encoding color channel (VL default behavior)
+    color: str | None = Field(
+        default=None, description="Point color; None inherits the series color."
+    )
+    # None = VL default shape for point marks
+    shape: str | None = Field(
+        default=None,
+        description="Point shape (e.g. 'circle', 'square'); None uses VL default.",
+    )
+    # None = VL default opacity; scatter theme populates; line renderer forces 1 for halo clarity
+    opacity: float | None = Field(
+        default=None, description="Point opacity 0–1; None uses VL default."
+    )
+    # None = VL default fill; scatter theme populates
+    filled: bool | None = Field(
+        default=None, description="Whether points are filled; None uses VL default."
+    )
+    # None = no fill override; theme sets theme.background so hollow points get
+    # a solid background automatically when filled=false.
+    fill: str | None = Field(
+        default=None,
+        description="Point interior fill color; only applied when filled=false.",
+    )
+
+
+class SliceMarkStyle(BaseModel):
+    """Pie/donut slice mark — mark-level paint and layout only.
+
+    No chart geometry (aspect_ratio, inner_radius), no sub-components (total).
+    All fields None = "not set at this tier; inherit from global".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    gap: float | None = Field(
+        default=None, description="Angular gap between slices in radians."
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    corner_radius: float | None = Field(
+        default=None, description="Corner radius of arc slices in pixels."
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    stroke: StrokeStyle | None = Field(
+        default=None, description="Arc slice stroke style."
+    )
+    # Cascade tier sentinel: None means "not specified at this tier".
+    labels: SliceLabelsStyle | None = Field(
+        default=None, description="Per-slice label style."
+    )
+
+
+class RuleMarkStyle(BaseModel):
+    """Rule (reference line) mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade-managed sentinels: None until _fill_stroke_color sets stroke.color.
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class RectMarkStyle(BaseModel):
+    """Rect mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class CircleMarkStyle(BaseModel):
+    """Circle mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class SquareMarkStyle(BaseModel):
+    """Square mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class TickMarkStyle(BaseModel):
+    """Tick mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class TrailMarkStyle(BaseModel):
+    """Trail mark opacity and stroke."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    opacity: float | None = Field(
+        default=None,
+        description="Mark opacity (0–1); None means not overridden at this level.",
+    )
+    stroke: StrokeStyle | None = Field(
+        default=None,
+        description="Mark stroke style; None means not overridden at this level.",
+    )
+
+
+class GeoshapeMarkStyle(BaseModel):
+    """Geoshape (choropleth) mark boundary stroke.
+
+    Cascade tier sentinel: None means "not specified at this tier".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    stroke: StrokeStyle | None = Field(
+        default=None, description="Geoshape boundary stroke style."
+    )
+
+
+class ImageMarkStyle(BaseModel):
+    """Image mark aspect ratio preservation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    aspect: bool | None = Field(
+        default=None, description="Preserve image aspect ratio when scaling."
+    )
+
+
+class BoxplotMarkStyle(BaseModel):
+    """Boxplot composite mark whisker extent."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    extent: str | None = Field(
+        default=None,
+        description="Boxplot whisker extent ('min-max' or a k-IQR multiplier as string).",
+    )
+
+
+class ErrorbarMarkStyle(BaseModel):
+    """Error bar composite mark tick visibility."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    ticks: bool | None = Field(
+        default=None,
+        description="Show tick marks at the ends of error bar whiskers.",
+    )
+
+
+class ErrorbandMarkStyle(BaseModel):
+    """Error band composite mark fill opacity."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade tier sentinel: None means "not specified at this tier".
+    opacity: float | None = Field(
+        default=None, description="Error band fill opacity (0–1)."
+    )
+
+
+# =============================================================================
+# GLOBAL MARKS STYLE
+# =============================================================================
+
+
+class GlobalMarksStyle(BaseModel):
+    """Global mark defaults: one <Mark>MarkStyle per VL mark type.
+
+    Tier 1 of the three-tier mark cascade:
+        GlobalMarksStyle → <Family>ChartMarksStyle → face-local marks patch.
+
+    Keys match VL mark type names. ``text`` is the renamed ``label`` slot.
+    All 17 fields have default_factory so the theme YAML can omit rarely-styled
+    marks (image, boxplot, etc.) without breaking validation.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    bar: BarMarkStyle = Field(
+        default_factory=BarMarkStyle,
+        description="Global bar mark defaults.",
+    )
+    line: LineMarkStyle = Field(
+        default_factory=LineMarkStyle,
+        description="Global line mark defaults.",
+    )
+    area: AreaMarkStyle = Field(
+        default_factory=AreaMarkStyle,
+        description="Global area mark defaults.",
+    )
+    point: PointMarkStyle = Field(
+        default_factory=PointMarkStyle,
+        description="Global point mark defaults.",
+    )
+    slice: SliceMarkStyle = Field(
+        default_factory=SliceMarkStyle,
+        description="Global slice (arc/pie) mark defaults.",
+    )
+    # `text` is the renamed `label` slot. ChartsStyle rejects the old `label` key.
+    text: TextMarkStyle = Field(
+        default_factory=TextMarkStyle,
+        description="Global text mark defaults.",
+    )
+    rule: RuleMarkStyle = Field(
+        default_factory=RuleMarkStyle,
+        description="Global rule mark defaults.",
+    )
+    rect: RectMarkStyle = Field(
+        default_factory=RectMarkStyle,
+        description="Global rect mark defaults.",
+    )
+    circle: CircleMarkStyle = Field(
+        default_factory=CircleMarkStyle,
+        description="Global circle mark defaults.",
+    )
+    square: SquareMarkStyle = Field(
+        default_factory=SquareMarkStyle,
+        description="Global square mark defaults.",
+    )
+    tick: TickMarkStyle = Field(
+        default_factory=TickMarkStyle,
+        description="Global tick mark defaults.",
+    )
+    trail: TrailMarkStyle = Field(
+        default_factory=TrailMarkStyle,
+        description="Global trail mark defaults.",
+    )
+    geoshape: GeoshapeMarkStyle = Field(
+        default_factory=GeoshapeMarkStyle,
+        description="Global geoshape mark defaults.",
+    )
+    image: ImageMarkStyle = Field(
+        default_factory=ImageMarkStyle,
+        description="Global image mark defaults.",
+    )
+    boxplot: BoxplotMarkStyle = Field(
+        default_factory=BoxplotMarkStyle,
+        description="Global boxplot mark defaults.",
+    )
+    errorbar: ErrorbarMarkStyle = Field(
+        default_factory=ErrorbarMarkStyle,
+        description="Global errorbar mark defaults.",
+    )
+    errorband: ErrorbandMarkStyle = Field(
+        default_factory=ErrorbandMarkStyle,
+        description="Global errorband mark defaults.",
+    )
+
+
+# =============================================================================
+# PER-FAMILY MARKS CONTAINERS (<Family>ChartMarksStyle)
+#
+# Each exposes ONLY the mark types that the family actually emits.
+# extra="forbid" ensures typos or wrong-family marks are caught at schema time.
+# All fields default to None (theme may omit family-level mark overrides).
+# =============================================================================
+
+
+class BarChartMarksStyle(BaseModel):
+    """Bar-family mark overrides. Only bar and text (endpoint labels) are valid."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    bar: BarMarkStyle | None = Field(
+        default=None,
+        description="Bar mark overrides for bar charts; None inherits global.",
+    )
+    text: TextMarkStyle | None = Field(
+        default=None,
+        description="Text mark overrides for bar endpoint labels; None inherits global.",
+    )
+
+
+class LineChartMarksStyle(BaseModel):
+    """Line-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    line: LineMarkStyle | None = Field(
+        default=None, description="Line mark overrides; None inherits global."
+    )
+    point: PointMarkStyle | None = Field(
+        default=None, description="Point mark overrides; None inherits global."
+    )
+    text: TextMarkStyle | None = Field(
+        default=None, description="Text mark overrides; None inherits global."
+    )
+    rule: RuleMarkStyle | None = Field(
+        default=None,
+        description="Rule mark overrides; None inherits global.",
+    )
+
+
+class AreaChartMarksStyle(BaseModel):
+    """Area-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    area: AreaMarkStyle | None = Field(
+        default=None, description="Area mark overrides; None inherits global."
+    )
+    line: LineMarkStyle | None = Field(
+        default=None, description="Top-edge line mark overrides; None inherits global."
+    )
+    point: PointMarkStyle | None = Field(
+        default=None, description="Point mark overrides; None inherits global."
+    )
+    text: TextMarkStyle | None = Field(
+        default=None, description="Text mark overrides; None inherits global."
+    )
+
+
+class ScatterChartMarksStyle(BaseModel):
+    """Scatter-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    point: PointMarkStyle | None = Field(
+        default=None, description="Point mark overrides; None inherits global."
+    )
+    text: TextMarkStyle | None = Field(
+        default=None, description="Text mark overrides; None inherits global."
+    )
+
+
+class PieChartMarksStyle(BaseModel):
+    """Pie/donut-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    slice: SliceMarkStyle | None = Field(
+        default=None, description="Slice mark overrides; None inherits global."
+    )
+    text: TextMarkStyle | None = Field(
+        default=None,
+        description="Text mark overrides; None inherits global.",
+    )
+
+
+class HistogramChartMarksStyle(BaseModel):
+    """Histogram-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    bar: BarMarkStyle | None = Field(
+        default=None, description="Bar mark overrides; None inherits global."
+    )
+    rule: RuleMarkStyle | None = Field(
+        default=None,
+        description="Rule mark overrides; None inherits global.",
+    )
+
+
+class HeatmapChartMarksStyle(BaseModel):
+    """Heatmap-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    rect: RectMarkStyle | None = Field(
+        default=None, description="Rect mark overrides; None inherits global."
+    )
+    text: TextMarkStyle | None = Field(
+        default=None,
+        description="Text mark overrides; None inherits global.",
+    )
+
+
+class GeoshapeChartMarksStyle(BaseModel):
+    """Geoshape-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    geoshape: GeoshapeMarkStyle | None = Field(
+        default=None, description="Geoshape mark overrides; None inherits global."
+    )
+
+
+class PointMapChartMarksStyle(BaseModel):
+    """Point map-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    point: PointMarkStyle | None = Field(
+        default=None, description="Point mark overrides; None inherits global."
+    )
+
+
+class BoxplotChartMarksStyle(BaseModel):
+    """Boxplot-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    boxplot: BoxplotMarkStyle | None = Field(
+        default=None, description="Boxplot mark overrides; None inherits global."
+    )
+
+
+class ErrorbarChartMarksStyle(BaseModel):
+    """Errorbar-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    errorbar: ErrorbarMarkStyle | None = Field(
+        default=None, description="Errorbar mark overrides; None inherits global."
+    )
+
+
+class ErrorbandChartMarksStyle(BaseModel):
+    """Errorband-family mark overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    errorband: ErrorbandMarkStyle | None = Field(
+        default=None, description="Errorband mark overrides; None inherits global."
+    )
+
+
+# =============================================================================
+# PER-FAMILY CHART STYLE LEAVES (<Family>ChartStyle)
+# =============================================================================
+
+
+class BarChartStyle(_CartesianChartStyle):
+    """Bar chart style: chart-level fields + marks sub-block."""
+
+    # Cascade-managed sentinels — None means "not overridden at this tier".
+    orientation: Literal["horizontal", "vertical", "auto"] | None = Field(
+        default=None,
+        description="Preferred bar orientation; None uses the renderer default (vertical).",
+    )
+    stack: bool | Literal["zero", "normalize", "center"] | None = Field(
+        default=None,
+        description="Default stack mode for bar charts; None uses the renderer default (VL stacks by default).",
+    )
+    stack_order: Literal["value", "data", "alphabetical"] | None = Field(
+        default=None,
+        description=(
+            "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: same opt-in feature as line/area. When enabled on a
+    # multi-series stacked or grouped column chart, a right-side label pane
+    # replaces the categorical legend with direct segment/bar labels.
+    endpoint_labels: EndpointLabelsConfig = Field(
+        description="Endpoint label pane configuration for bar charts."
+    )
+    marks: BarChartMarksStyle = Field(
+        default_factory=BarChartMarksStyle,
+        description="Bar-family mark overrides.",
+    )
+
+
+class LineChartStyle(_CartesianChartStyle):
+    """Line chart style: chart-level fields + marks sub-block."""
+
+    endpoint_labels: EndpointLabelsConfig = Field(
+        description="Endpoint label pane configuration for line charts."
+    )
+    marks: LineChartMarksStyle = Field(
+        default_factory=LineChartMarksStyle,
+        description="Line-family mark overrides.",
+    )
+
+
+class AreaChartStyle(_CartesianChartStyle):
+    """Area chart style: chart-level fields + marks sub-block."""
+
+    # Stack default for the area family. ``False`` disables stacking
+    # (overlapping silhouettes); a string mode is passed through to VL.
+    # Used when a chart doesn't author ``chart.stack`` explicitly.
+    stack: bool | Literal["zero", "normalize", "center"] = Field(
+        description="Default stack mode for area charts; False overlaps silhouettes."
+    )
+    endpoint_labels: EndpointLabelsConfig = Field(
+        description="Endpoint label pane configuration for area charts."
+    )
+    marks: AreaChartMarksStyle = Field(
+        default_factory=AreaChartMarksStyle,
+        description="Area-family mark overrides.",
+    )
+
+
+class ScatterChartStyle(_CartesianChartStyle):
+    """Scatter chart style: chart-level fields + marks sub-block."""
+
+    marks: ScatterChartMarksStyle = Field(
+        default_factory=ScatterChartMarksStyle,
+        description="Scatter-family mark overrides.",
+    )
+
+
+class PieChartStyle(_RadialChartStyle):
+    """Pie/donut chart style: geometry + total (flat) + marks sub-block.
+
+    ``total`` stays flat at this level per ADR-005 (compositional slot, not a VL mark).
+    ``inner_radius`` is on _RadialChartStyle (cascade sentinel: None = solid pie).
+    """
+
+    aspect_ratio: float = Field(
+        description="Aspect ratio (width/height) of the pie chart viewport."
+    )
+    marks: PieChartMarksStyle = Field(
+        default_factory=PieChartMarksStyle,
+        description="Pie-family mark overrides.",
+    )
+
+
+class HistogramChartStyle(_CartesianChartStyle):
+    """Histogram chart style."""
+
+    bin_maxbins: int = Field(description="Maximum number of bins for auto-binning.")
+    marks: HistogramChartMarksStyle = Field(
+        default_factory=HistogramChartMarksStyle,
+        description="Histogram-family mark overrides.",
+    )
+
+
+class HeatmapChartStyle(_CartesianChartStyle):
+    """Heatmap chart style."""
+
+    cell_padding: float = Field(description="Padding between heatmap cells in pixels.")
+    color_scheme: str = Field(
+        description="Color scheme name for heatmap gradient (e.g. 'blues', 'viridis')."
+    )
+    marks: HeatmapChartMarksStyle = Field(
+        default_factory=HeatmapChartMarksStyle,
+        description="Heatmap-family mark overrides.",
+    )
+
+
+class GeoshapeChartStyle(_GeoChartStyle):
+    """Geoshape (choropleth) chart style.
+
+    ``color_scheme`` is choropleth-specific; only this leaf, not _GeoChartStyle base.
+    """
+
+    color_scheme: str = Field(description="Color scheme name for choropleth gradient.")
+    marks: GeoshapeChartMarksStyle = Field(
+        default_factory=GeoshapeChartMarksStyle,
+        description="Geoshape-family mark overrides.",
+    )
+
+
+class PointMapChartStyle(_GeoChartStyle):
+    """Point map chart style."""
+
+    marks: PointMapChartMarksStyle = Field(
+        default_factory=PointMapChartMarksStyle,
+        description="Point-map-family mark overrides.",
+    )
+
+
+class BoxplotChartStyle(_CartesianChartStyle):
+    """Boxplot chart style."""
+
+    marks: BoxplotChartMarksStyle = Field(
+        default_factory=BoxplotChartMarksStyle,
+        description="Boxplot-family mark overrides.",
+    )
+
+
+class ErrorbarChartStyle(_CartesianChartStyle):
+    """Error bar chart style."""
+
+    marks: ErrorbarChartMarksStyle = Field(
+        default_factory=ErrorbarChartMarksStyle,
+        description="Errorbar-family mark overrides.",
+    )
+
+
+class ErrorbandChartStyle(_CartesianChartStyle):
+    """Error band chart style."""
+
+    marks: ErrorbandChartMarksStyle = Field(
+        default_factory=ErrorbandChartMarksStyle,
+        description="Errorband-family mark overrides.",
+    )
+
+
+class ChartsStyle(_ChartStyleBase):
+    """Registry of all chart-type styles plus shared chart configuration.
+
+    Inherits ``_ChartStyleBase`` — geometry/frame fields (aspect_ratio, min_height,
+    max_height, padding, border, animation_duration, font) are populated by theme
+    YAML at the global ``charts:`` level and serve as the cascade source for
+    per-family defaults. ``height`` and ``width`` are NOT in the style cascade —
+    they live only at chart root in the authored YAML.
+
+    Per-family styles inherit ``_ChartStyleBaseAllOptional`` (all-optional variant);
+    the cascade fills their ``None`` sentinels from the values here.
+
+    The ``marks:`` block holds global mark defaults (tier-1 of the three-tier mark
+    cascade). ADR-015: legacy top-level VL mark fields (circle, square, label, tick,
+    rule, trail, rect, geoshape, image, boxplot, errorbar, errorband, map) are removed.
+    Use ``marks.circle``, ``marks.text``, etc. instead.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_legacy_mark_keys(cls, data: Any) -> Any:
+        """Reject keys renamed/moved in ADR-015 with actionable hints."""
+        if not isinstance(data, dict):
+            return data
+        hints: list[str] = []
+        if "label" in data:
+            hints.append("'label' was renamed to 'text' under marks: → marks.text.*")
+        if "map" in data:
+            hints.append("'map' was renamed to 'geoshape' (the chart family)")
+        if hints:
+            raise ValueError(
+                "ChartsStyle: renamed/moved keys detected. " + "; ".join(hints)
+            )
+        return data
+
+    # Axis sections
+    axis: AxisStyle = Field(
+        description="Shared axis style applied to all axes before per-axis overrides."
+    )
+    axis_x: AxisStyle = Field(
+        description="X-axis style overrides applied after the shared axis."
+    )
+    axis_y: AxisStyle = Field(
+        description="Y-axis style overrides applied after the shared axis."
+    )
+    axis_quantitative: AxisStyle = Field(
+        description="Quantitative axis style overrides applied after axis_x/axis_y."
+    )
+
+    # View / autosize
+    view: ViewStyle = Field(description="Vega-Lite view dimensions and border.")
+    autosize: AutosizeStyle = Field(description="Vega-Lite autosize configuration.")
+
+    # Global mark defaults — tier-1 of the three-tier mark cascade
+    marks: GlobalMarksStyle = Field(
+        default_factory=GlobalMarksStyle,
+        description="Global mark defaults (tier-1 of the marks cascade).",
+    )
+
+    # Primary chart families
+    bar: BarChartStyle = Field(description="Bar chart style.")
+    line: LineChartStyle = Field(description="Line chart style.")
+    area: AreaChartStyle = Field(description="Area chart style.")
+    scatter: ScatterChartStyle = Field(description="Scatter chart style.")
+    histogram: HistogramChartStyle = Field(description="Histogram chart style.")
+    heatmap: HeatmapChartStyle = Field(description="Heatmap chart style.")
+    geoshape: GeoshapeChartStyle = Field(
+        description="Geoshape (choropleth) chart style."
+    )
+    point_map: PointMapChartStyle = Field(description="Point map chart style.")
+    boxplot: BoxplotChartStyle = Field(description="Boxplot chart style.")
+    errorbar: ErrorbarChartStyle = Field(description="Error bar chart style.")
+    errorband: ErrorbandChartStyle = Field(description="Error band chart style.")
+    pie: PieChartStyle = Field(description="Pie/donut chart style.")
+
+    # Series-label primitive — typography for series-naming text marks
+    # (endpoint labels, direct stack labels, slice callouts).
+    series_label: SeriesLabelStyle = Field(
+        description="Shared series-label typography for endpoint labels, stack labels, and slice callouts."
+    )
+
+    # Non-Vega chart types (required — theme pipeline always populates)
+    kpi: KpiChartStyle = Field(description="KPI card chart style.")
+    table: TableChartStyle = Field(description="Table chart style.")
+    spark_bar: SparkBarChartStyle = Field(
+        description="Spark_bar (full-chart horizontal bar) style."
+    )
+
+    # Attached data_table primitive (per-chart strip; populated by the theme cascade).
+    data_table: DataTableStyle = Field(description="Attached data_table strip style.")
+
+    # Callout chart-family style (type: callout and runtime chart-error fallback)
+    callout: CalloutChartStyle = Field(
+        description="Callout chart-family style for type:callout and runtime fallback cards."
+    )
+
+
+# KPI
+
+
+class SubtitleStyle(BaseModel):
+    """Subtitle font style for chart subtitles (Table, SparkBar).
+
+    Theme YAML populates font.size directly — no delta/floor math.
+    Values live in stark.yaml style.charts.*.subtitle.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # FontStyle is all-Optional (it's a patch type); default_factory=FontStyle
+    # creates an empty overlay that the theme YAML fills with font.size.
+    # Same justified exception as KpiValueStyle.font.
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Subtitle font style; theme populates font.size directly.",
+    )
+
+
+class KpiValueStyle(BaseModel):
+    """KPI headline value slot: font. Theme populates font.size directly."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="KPI value font style; cascades from kpi.font.",
+    )
+
+
+class KpiSlotStyle(BaseModel):
+    """KPI per-slot style for label, affix, and glyph slots."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Slot font style; cascades from kpi.font.",
+    )
+    # Authored glyph character (e.g. '▲', '▼', '●'). None = no glyph rendered.
+    # Only meaningful on the `glyph` slot — ignored on label/affix slots.
+    character: str | None = Field(
+        default=None,
+        description="Glyph character to render (e.g. '▲'). None = no glyph.",
+    )
+
+
+class KpiTonesStyle(BaseModel):
+    """Semantic tone palette for KPI value/glyph and (eventually) tables.
+
+    Colors are theme tokens — the renderer reads them through this model
+    rather than hardcoding hexes, so themes can rebrand the semantic
+    vocabulary without touching the renderer.
+
+    v1: three tones only — positive, negative, warning.
+    KPIs without tone use default chrome colors.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    positive: str = Field(description="Color for positive/good tone indicators.")
+    negative: str = Field(description="Color for negative/bad tone indicators.")
+    warning: str = Field(description="Color for warning/caution tone indicators.")
+
+
+class KpiChartStyle(_ChartStyleBaseAllOptional):
+    """Produced by cascade from theme YAML.
+
+    Four per-slot font blocks (value, label, affix, glyph) plus a parent
+    ``font`` that cascades into every slot and doubles as the support-row
+    font. Concrete pixel values live in ``stark.yaml``.
+
+    * ``font`` — parent cascade base; also the support row (small text under value)
+    * ``value.font`` — headline number typography; size/weight from theme (authoritative)
+    * ``label.font`` — card label typography; cascades from ``kpi.font``
+    * ``affix.font`` — currency/percent affixes; cascades from ``kpi.font``
+    * ``glyph.font`` — indicator glyphs (▲▼●); cascades from ``kpi.font``
+    * ``content_padding`` — per-side inner inset for the value/label/support text block
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: KpiValueStyle = Field(description="KPI headline value slot.")
+    label: KpiSlotStyle = Field(description="KPI card label slot.")
+    affix: KpiSlotStyle = Field(description="Currency/percent affix slot.")
+    glyph: KpiSlotStyle = Field(
+        # Indicator glyphs (▲▼●) sit next to the value as markers, not second
+        # headlines — drawn at body/narrow tier so a triangle's visual mass
+        # doesn't compete with the digits.
+        description="Indicator glyph (▲▼●) slot.",
+    )
+    min_card_width: float = Field(description="Minimum KPI card width in pixels.")
+    default_width: float = Field(description="Default KPI card width in pixels.")
+    default_height: float = Field(description="Default KPI card height in pixels.")
+    border: BorderStyle = Field(description="KPI card border style.")
+    content_padding: SpacingValues = Field(
+        description="Inner inset (top/right/bottom/left) for KPI card content in pixels."
+    )
+    tones: KpiTonesStyle = Field(
+        description="Semantic tone color palette for KPI values and glyphs."
+    )
+    # Semantic tone selector (positive/negative/warning). None = no tone applied.
+    # Moved here from chart root (ADR-001: paint → style:).
+    tone: str | None = Field(
+        default=None,
+        description="Semantic tone selector (positive | negative | warning). None = default chrome.",
+    )
+
+
+# Table
+
+
+class TableColumnsStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    default_width: float = Field(description="Default column width in pixels.")
+    cell_padding: float = Field(
+        description="Horizontal padding inside table cells in pixels."
+    )
+    width_similarity_threshold: float = Field(
+        ge=0.0,
+        le=1.0,
+        description=(
+            "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."
+        ),
+    )
+
+
+class TableHeaderStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    visible: bool = Field(
+        description=(
+            "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 = Field(description="Header row height in pixels.")
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Header font style overrides."
+    )
+    font_compact: FontStyle | None = Field(
+        default=None,
+        description="Compact-tier font overrides applied when body size ≤11px; None means no compact override.",
+    )  # None = no compact-tier override; header uses font at all body sizes
+    # None = no header fill. Header rule alone separates header from body.
+    # Themes may set a fill (cream, dark) when paper-warmth or
+    # contrast demands it.
+    background: str | None = Field(
+        default=None,
+        description="Header background color; None means no fill (rule alone separates header from body).",
+    )
+    overflow: str = Field(
+        description="Header text overflow mode (clip, truncate, wrap)."
+    )
+    rule: RuleStyle = Field(description="Header bottom rule style.")
+
+
+class TableRowRoleStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    rule_width: float = Field(
+        description="Rule width above rows with this role in pixels."
+    )
+    font: FontStyle | None = Field(
+        default=None,
+        description="Per-role font style override; None uses the default row font.",
+    )
+    background: str | None = Field(
+        default=None,
+        description="Per-role row background color; None means no override.",
+    )
+
+
+class TableRowRolesStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    summary: TableRowRoleStyle = Field(description="Style for summary role rows.")
+    total: TableRowRoleStyle = Field(description="Style for total role rows.")
+
+
+class TableRowStripeStyle(BaseModel):
+    """Alternating row stripe style."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    color: str | None = Field(  # None = no alternating row fill
+        default=None,
+        description="Alternating stripe background color; None means no alternating row fill.",
+    )
+
+
+class TableRowStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    height: float = Field(description="Body row height in pixels.")
+    stripe: TableRowStripeStyle | None = Field(  # None = no alternating row fill
+        default=None,
+        description="Alternating row stripe style; None means no stripe.",
+    )
+    rule: RuleStyle = Field(description="Row bottom rule style.")
+    role: str | None = Field(
+        default=None,
+        description="Default row role assignment; None means plain body row.",
+    )
+    roles: TableRowRolesStyle = Field(
+        description="Per-role style overrides for summary and total rows."
+    )
+
+
+class TableTitleStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    height: float = Field(description="Table title row height in pixels.")
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Table title font style overrides."
+    )
+
+
+class TableEdgeStyle(BaseModel):
+    """more_rows or empty_state edge-case UI."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Edge-case UI (more_rows / empty_state) font style overrides.",
+    )
+
+
+class SparkEmptyStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    inset_x: float = Field(
+        description="Horizontal inset for the empty sparkline placeholder in pixels."
+    )
+    stroke: StrokeStyle = Field(description="Empty-state placeholder stroke style.")
+
+    @model_validator(mode="after")
+    def _require_stroke_fields(self) -> SparkEmptyStyle:
+        s = self.stroke
+        missing = [
+            f
+            for f, v in [
+                ("color", s.color),
+                ("width", s.width),
+                ("dasharray", s.dasharray),
+            ]
+            if v is None
+        ]
+        if missing:
+            raise ValueError(
+                f"spark.empty.stroke.{missing[0]} is required (renderer reads color/width/dasharray)"
+            )
+        return self
+
+
+class SparkSingleValueStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    inset_x: float = Field(
+        description="Horizontal inset for the single-value sparkline in pixels."
+    )
+    marker_radius: float = Field(
+        description="Radius of the single-value marker circle in pixels."
+    )
+
+
+class SparkColumnsStyle(BaseModel):
+    """Inline `spark.type: columns` (multi-value vertical bars) defaults."""
+
+    model_config = ConfigDict(extra="forbid")
+    gap: float = Field(description="Gap between column bars in pixels.")
+    padding: float = Field(
+        description="Horizontal outer padding of the columns sparkline in pixels."
+    )
+    min_bar_height: float = Field(description="Minimum rendered bar height in pixels.")
+    border: BorderStyle = Field(description="Column bar border style.")
+
+
+class SparkBarLabelStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    inset_x: float = Field(
+        description="Horizontal inset for the spark bar label in pixels."
+    )
+    fill: str = Field(description="Label text fill color.")
+    fill_opacity: float = Field(description="Label text fill opacity (0–1).")
+    min_size: float = Field(
+        description="Minimum bar fill width required to show the label in pixels."
+    )
+    height_offset: float = Field(
+        description="Vertical offset of the label from its bar top in pixels."
+    )
+
+
+class SparkBarCellStyle(BaseModel):
+    """Inline `spark.type: bar` and `bar-normalize` (single horizontal bar) defaults.
+
+    The variant decides whether the background track is drawn:
+    `bar` paints only the fill; `bar-normalize` paints a track + fill.
+    Style sub-keys are shared between both variants.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+    background: str | None = Field(
+        default=None,
+        description="Track background color; cascade-managed (inherits from style.muted).",
+    )
+    color: str | None = Field(
+        default=None,
+        description="Bar fill color; cascade-managed (inherits from style.accent).",
+    )
+    default_max: float = Field(
+        description="Default maximum value for bar scale when no explicit max is authored."
+    )
+    border: BorderStyle = Field(description="Spark bar border style.")
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Spark bar cell font style overrides.",
+    )
+    label: SparkBarLabelStyle = Field(description="Spark bar inline label style.")
+
+
+class SparkAreaStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    fill_opacity: float = Field(description="Spark area fill opacity (0–1).")
+
+
+class SparkStyle(BaseModel):
+    """Inline sparkline defaults (inside table cells)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    color: str | None = Field(
+        default=None,
+        description="Sparkline line/point color; cascade-managed (inherits from style.accent).",
+    )
+    padding: SpacingValues = Field(
+        description="Cell padding around the sparkline in pixels."
+    )
+    empty: SparkEmptyStyle = Field(description="Style for empty/no-data sparklines.")
+    single_value: SparkSingleValueStyle = Field(
+        description="Style for single-data-point sparklines."
+    )
+    columns: SparkColumnsStyle = Field(description="Style for column-type sparklines.")
+    bar: SparkBarCellStyle = Field(
+        description="Style for bar/bar-normalize sparklines."
+    )
+    area: SparkAreaStyle = Field(description="Style for area sparklines.")
+
+
+class TableRowNumbersStyle(BaseModel):
+    """Leading row-number column (style.table.row_numbers).
+
+    When ``show=True`` the renderer injects a synthetic column at index 0
+    that displays the absolute 1-based row index in the original unpaginated
+    dataset. Pagination is continuous: page 2 of a 10-per-page table starts
+    at 11. The column is transparent to ``style.columns`` (not listed), to
+    conditional_formatting rules keyed by column name, and to data-pipeline
+    transforms — it exists only in the chart layer.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Feature toggle — False is the opt-out default; not a visual theme value.
+    visible: bool = Field(
+        default=False, description="Show a leading row-number column; false by default."
+    )
+    # Fixed column header label — not a theme style value.
+    header: str = Field(
+        default="#", description="Header label for the row-number column."
+    )
+    # Fixed alignment for the row-number column — not a theme style value.
+    align: Literal["left", "right"] = Field(
+        default="right", description="Text alignment for the row-number column."
+    )
+
+
+class PaginatorStyle(BaseModel):
+    """Visual style for the paginator control (chevrons + page numbers).
+
+    Distinct from PaginationConfig which controls *behaviour* (enabled,
+    page_size). PaginatorStyle owns the look: colour ramp across the three
+    item states (active, inactive, disabled), font sizing, weight contrast
+    between the current page and its neighbours, and the slot width that
+    drives the hit target.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    color_active: str = Field(
+        description="Current page and live chevron colour (theme body ink)."
+    )
+    color_inactive: str = Field(
+        description="Other pages and ellipsis colour (theme secondary text)."
+    )
+    color_disabled: str = Field(
+        description="Chevron colour when at first/last page (signals disabled by tone)."
+    )
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Paginator font overrides (size, family).",
+    )
+    weight_active: int = Field(
+        description="Font weight for the current (selected) page number."
+    )
+    weight_inactive: int = Field(
+        description="Font weight for other pages and ellipsis."
+    )
+    weight_chevron: int = Field(
+        description=(
+            "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 = Field(
+        description="Per-item slot width in pixels (drives layout step)."
+    )
+
+
+class TableRuleStyle(BaseModel):
+    """Table rule color override block."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    color: str | None = Field(  # None = use theme default
+        default=None, description="Table rule color; None uses the theme default."
+    )
+
+
+class TableColumnDefaultsConfig(BaseModel):
+    """Table-level defaults applied to every column unless overridden per-column.
+
+    Only fields that are meaningful as uniform defaults are included.
+    Data-dependent fields (link, header_link, spark, scale, glyph, glyph_color,
+    header_overflow) are excluded — they depend on per-column data shape or
+    interaction intent.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    label: str | None = Field(
+        default=None,
+        description="Override column header label text.",
+    )
+    width: int | str | None = Field(
+        default=None,
+        description="Override column width in pixels (integer) or a CSS width string.",
+    )
+    align: Literal["left", "center", "right"] | None = Field(
+        default=None,
+        description="Override cell text alignment (left, center, or right).",
+    )
+    format: str | FormatConfig | None = Field(
+        default=None,
+        description="Override cell value format (D3 format string or format config object).",
+    )
+    background: str | None = Field(
+        default=None, description="Override cell background color (CSS color string)."
+    )
+    font: FontStyle | None = Field(
+        default=None,
+        description="Override cell font style (size, weight, color, family).",
+    )
+
+
+class TableChartStyle(_ChartStyleBaseAllOptional):
+    model_config = ConfigDict(extra="forbid")
+
+    # Color overrides (None = inherit from theme)
+    background: str | None = Field(
+        default=None, description="Table background color; None inherits from theme."
+    )
+    # str → text color; StyleColorConfig → gradient scale for the color channel.
+    color: str | StyleColorConfig | None = Field(
+        default=None,
+        description="Table text color override (CSS string) or gradient scale config; None uses the theme default.",
+    )
+    rule: TableRuleStyle | None = Field(  # None = no rule color override
+        default=None,
+        description="Table rule style overrides (color). None = no override; inherits from theme.",
+    )
+
+    outer_padding: float = Field(description="Outer table padding in pixels.")
+    bottom_padding: float = Field(
+        description="Extra bottom padding below the last row in pixels."
+    )
+    # Layout/structural column settings (width budget, cell padding, clustering).
+    # Renamed from 'columns' to avoid collision with the per-column display config.
+    column_layout: TableColumnsStyle = Field(
+        description="Default column width and cell padding settings."
+    )
+    header: TableHeaderStyle = Field(description="Table header row style.")
+    row: TableRowStyle = Field(description="Table body row style.")
+    row_numbers: TableRowNumbersStyle = Field(
+        default_factory=TableRowNumbersStyle,
+        description="Leading row-number column configuration.",
+    )
+    title_row: TableTitleStyle = Field(description="Table title row style.")
+    border: BorderStyle = Field(description="Table outer border style.")
+    wrap: bool = Field(
+        description="Allow cell text wrapping; false clips to single line."
+    )
+    pagination: PaginationConfig = Field(
+        description="Client-side pagination defaults for table charts."
+    )
+    # Cascade-managed sentinels — None means "not overridden at this tier".
+    column_defaults: TableColumnDefaultsConfig | None = Field(
+        default=None,
+        description="Table-level column defaults applied to every column; None means no defaults authored.",
+    )
+    columns: dict[str, Any] | None = Field(
+        default=None,
+        description="Per-column display configuration keyed by column name (label, format, width, etc.).",
+    )
+    header_overflow: Literal["clip", "truncate", "wrap-two", "wrap"] | None = Field(
+        default=None,
+        description="Table column header text overflow mode; None inherits from theme.",
+    )
+    paginator: PaginatorStyle = Field(
+        description="Visual style for the paginator control (chevrons + page numbers)."
+    )
+    symbol_mode: str = Field(
+        description=(
+            "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 = Field(
+        description="Style for the 'more rows' edge-case indicator."
+    )
+    empty_state: TableEdgeStyle = Field(
+        description="Style for the empty-state (no data) indicator."
+    )
+    spark: SparkStyle = Field(description="Inline sparkline defaults for table cells.")
+
+    # SVG layout constants (all-config per ADR-002)
+    text_baseline_offset: float = Field(
+        description="Vertical offset to align SVG text baseline with cell grid in pixels."
+    )
+    title_baseline_offset: float = Field(
+        description="Vertical offset to align SVG title baseline in pixels."
+    )
+    title_subtitle_gap: float = Field(
+        description="Gap between table title and subtitle lines in pixels."
+    )
+    subtitle: SubtitleStyle = Field(description="Table subtitle font-sizing constants.")
+
+
+# ── data_table (attached chart primitive) ───────────────────────────────────
+# ADR-006: no column-header row; `divider:` styles the strip-top rule only.
+# Styleable leaves (spec §4.3): font, divider, row, label, number_align,
+# padding_top, padding_bottom. Defaults are conservative — themes tighten.
+
+
+class DataTableRowPaddingStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    vertical: float = Field(
+        description="Vertical (top/bottom) padding inside data_table rows in pixels."
+    )
+    horizontal: float = Field(
+        description="Horizontal (left/right) padding inside data_table rows in pixels."
+    )
+
+
+class DataTableRowStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    padding: DataTableRowPaddingStyle = Field(description="Row padding style.")
+    rule: RuleStyle = Field(description="Row bottom rule style.")
+
+
+class DataTableLabelStyle(BaseModel):
+    """Row label styling.
+
+    The row label's side (left-gutter or right-gutter) is a pure function of
+    the chart's resolved ``axis_y.orient`` — there is no authorable
+    ``position`` or ``align`` override. The compiler derives both from the
+    axis orientation at render time:
+
+    - ``axis_y.orient == "right"`` → label at ``spec_width + axis_y.label.padding``,
+      ``mark.align = "left"`` (text-anchor start, extends rightward).
+    - ``axis_y.orient == "left"`` → label at ``-axis_y.label.padding``,
+      ``mark.align = "right"`` (text-anchor end, extends leftward).
+
+    ``extra="forbid"`` rejects any YAML that still authors the deleted
+    ``position`` or ``align`` fields with a ``ValidationError`` at compile time.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Row label font style overrides."
+    )
+
+
+class DataTableStyle(BaseModel):
+    """Attached data_table style. Lives at style.charts.data_table.*.
+
+    Also nestable under per-chart-type blocks (bar.data_table, line.data_table,
+    area.data_table) for per-chart-type overrides per ADR-002.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Data_table font style overrides."
+    )
+    divider: RuleStyle = Field(
+        description=(
+            "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 = Field(description="Data_table row padding and rule style.")
+    label: DataTableLabelStyle = Field(description="Row label (series name) style.")
+    number_align: Literal["left", "right", "decimal"] = Field(
+        description="Alignment of numeric values in data_table cells."
+    )
+    padding_top: float = Field(
+        description=(
+            "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 = Field(
+        description=(
+            "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."
+        )
+    )
+    # Number of x-axis label lines to reserve above the strip. Vega emits an
+    # array label expression (e.g. ['Jan', '2024']) at year boundaries, so the
+    # strip must reserve space for 2 lines even on months that emit a single
+    # line — otherwise the strip overlaps labels at year ticks. Set to 1 if the
+    # theme is known to emit only single-line labels (e.g. year-only cadence).
+    label_max_lines: int = Field(
+        description=(
+            "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: Literal["top", "bottom"] = Field(
+        description=(
+            "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."
+        )
+    )
+
+
+if TYPE_CHECKING:
+
+    class DataTableStylePatch(DataTableStyle):
+        pass
+
+else:
+    DataTableStylePatch = build_patch_model(DataTableStyle)
+
+
+# Table charts use row-count sizing; aspect-ratio fields from the base class
+# are meaningless and excluded to prevent silent no-ops.
+_TABLE_CHART_STYLE_SIZING: frozenset[str] = frozenset(
+    {"aspect_ratio", "min_height", "max_height"}
+)
+
+# Patch type for chart-local table style overrides.
+# At runtime `build_patch_model_ext(TableChartStyle, exclude=_TABLE_CHART_STYLE_SIZING)`
+# returns a Pydantic class structurally equivalent to `TableChartStyle` but with every
+# field made Optional (and nested models recursed the same way), minus the sizing
+# fields that don't apply to tables.  Mypy can't follow the dynamic `create_model`
+# call, so under TYPE_CHECKING we declare the patch as a subclass of the compiled
+# class. That gives callers accurate field names, nested-model types, and completion;
+# every field on `TableChartStyle` already has a default, so required-vs-optional
+# drift between the static stub and the runtime patch is moot.
+# `no-redef` is required because mypy sees the class definition under
+# TYPE_CHECKING and the runtime assignment as two declarations of the same
+# symbol — that's intentional, not accidental rebinding.
+if TYPE_CHECKING:
+
+    class TableChartStylePatch(TableChartStyle):
+        pass
+
+else:
+    TableChartStylePatch = build_patch_model_ext(
+        TableChartStyle, exclude=_TABLE_CHART_STYLE_SIZING
+    )
+
+
+# Spark bar (full chart, not inline)
+
+
+class SparkBarBarStyle(BaseModel):
+    """Bar geometry sub-block for SparkBarChartStyle."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    height: float = Field(description="Height of each bar in pixels.")
+    padding: float = Field(description="Vertical padding between bars in pixels.")
+    # Cascade-managed sentinels: filled from style.accent / style.muted in token cascade.
+    color: str | None = Field(
+        default=None,
+        description="Bar fill color; cascade-managed (inherits from style.accent).",
+    )
+    background: str | None = Field(
+        default=None,
+        description="Bar track background color; cascade-managed (inherits from style.muted).",
+    )
+
+
+class SparkBarChartLabelStyle(BaseModel):
+    """Category-label sub-block for SparkBarChartStyle.
+
+    Not to be confused with SparkBarLabelStyle, which is the in-cell bar
+    sparkline label inside table cells.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    visible: bool = Field(description="Show series label text next to bars.")
+    width: float = Field(description="Reserved width for bar label text in pixels.")
+
+
+class SparkBarCountStyle(BaseModel):
+    """Count-value sub-block for SparkBarChartStyle."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    visible: bool = Field(description="Show count/value text next to bars.")
+    width: float = Field(description="Reserved width for bar count text in pixels.")
+
+
+class SparkBarChartStyle(BaseModel):
+    """Produced by cascade from theme YAML."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    bar: SparkBarBarStyle = Field(description="Bar geometry (height, padding, color).")
+    label: SparkBarChartLabelStyle = Field(
+        description="Category-label column (visibility, reserved width)."
+    )
+    count: SparkBarCountStyle = Field(
+        description="Count-value column (visibility, reserved width)."
+    )
+    max_bars: int = Field(description="Maximum number of bars to render.")
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Spark_bar font style overrides."
+    )
+    border: BorderStyle = Field(description="Spark_bar outer border style.")
+    subtitle: SubtitleStyle = Field(
+        description="Spark_bar subtitle font-sizing constants."
+    )
+
+
+# View / autosize
+
+
+class ViewStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    stroke: str | None = Field(
+        description="Plot area border stroke color; None means no border."
+    )
+    continuous_width: float = Field(
+        description="Default plot width for continuous (quantitative) scales in pixels."
+    )
+    continuous_height: float = Field(
+        description="Default plot height for continuous (quantitative) scales in pixels."
+    )
+    discrete_width: float | None = Field(
+        default=None,
+        description="Default plot width for discrete (ordinal/nominal) scales in pixels; None means auto.",
+    )
+    discrete_height: float | None = Field(
+        default=None,
+        description="Default plot height for discrete (ordinal/nominal) scales in pixels; None means auto.",
+    )
+
+
+class AutosizeStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(
+        description="Vega-Lite autosize type (e.g. 'fit', 'fit-x', 'pad')."
+    )
+    contains: str = Field(
+        description="What the autosize dimensions include ('content' or 'padding')."
+    )
+    resize: bool = Field(description="Recompute autosize on each render cycle.")
+
+
+# Layout
+
+
+class LayoutGapStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    gap: float = Field(description="Gap between layout items in pixels.")
+
+
+class GridLayoutStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    columns: int = Field(description="Number of columns in the grid layout.")
+    gap: float = Field(description="Gap between grid cells in pixels.")
+
+
+class TabsStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    bar_height: float = Field(description="Tab bar height in pixels.")
+    border: BorderStyle = Field(description="Tab bar border style.")
+    font: FontStyle = Field(
+        default_factory=FontStyle, description="Tab label font style overrides."
+    )
+    active_weight: str = Field(description="Font weight for the active tab label.")
+    inactive_weight: str = Field(description="Font weight for inactive tab labels.")
+    # SVG layout constants
+    title_baseline_offset: float = Field(
+        description="Vertical offset to align SVG tab label baseline in pixels."
+    )
+
+
+class DetailsArrowFontStyle(BaseModel):
+    """Font style for the expand/collapse arrow glyph."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    size: float = Field(description="Font size of the arrow glyph in pixels.")
+
+
+class DetailsArrowStyle(BaseModel):
+    """Layout and font style for the expand/collapse arrow chevron."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    x: float = Field(description="X position of the arrow in pixels.")
+    font: DetailsArrowFontStyle = Field(description="Arrow glyph font style.")
+
+
+class DetailsStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    summary_height: float = Field(
+        description="Height of the details summary (collapsed) row in pixels."
+    )
+    border: BorderStyle = Field(description="Details element border style.")
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Details summary font style overrides.",
+    )
+    # SVG layout constants
+    arrow: DetailsArrowStyle = Field(
+        description="Expand/collapse arrow glyph layout and font style."
+    )
+    label_x: float = Field(
+        description="X position of the details summary label text in pixels."
+    )
+    text_baseline_offset: float = Field(
+        description="Vertical offset to align SVG details text baseline in pixels."
+    )
+    content_y_offset: float = Field(
+        description="Y offset of the expanded details content area in pixels."
+    )
+
+
+class LayoutStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    rows: LayoutGapStyle = Field(description="Row layout gap configuration.")
+    cols: LayoutGapStyle = Field(description="Column layout gap configuration.")
+    grid: GridLayoutStyle = Field(description="Grid layout configuration.")
+    tabs: TabsStyle = Field(description="Tabs layout style.")
+    details: DetailsStyle = Field(description="Details (accordion) layout style.")
+
+
+# Variables chrome
+
+
+class InputWidths(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    text: float = Field(description="Default width for text inputs in pixels.")
+    number: float = Field(description="Default width for number inputs in pixels.")
+    range: float = Field(description="Default width for range inputs in pixels.")
+    slider_value_min: float = Field(
+        description="Minimum width for slider value display in pixels."
+    )
+    checkbox: float = Field(description="Default width for checkbox inputs in pixels.")
+    daterange: float = Field(
+        description="Default width for daterange chip triggers in pixels."
+    )
+
+
+class RangeDefaults(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    default_min: float = Field(description="Default minimum value for range inputs.")
+    default_max: float = Field(description="Default maximum value for range inputs.")
+    default_step: float = Field(description="Default step size for range inputs.")
+
+
+class InputStyle(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    height: float = Field(description="Input control height in pixels.")
+    border: BorderStyle = Field(description="Input border style.")
+    focus_color: str | None = Field(
+        default=None,
+        description="Input focus ring color; cascade-managed (inherits from style.accent).",
+    )
+    background: str = Field(description="Input background color.")
+    padding: SpacingValues = Field(description="Input inner padding in pixels.")
+    widths: InputWidths = Field(description="Per-input-type default widths.")
+    range: RangeDefaults = Field(description="Range input default min/max/step values.")
+
+
+class PageStyle(BaseModel):
+    """Page-level (outer HTML canvas) styling.
+
+    Distinct from the top-level `background` which is the working-surface color
+    (board/card fills). `page.background` is the off-white canvas behind the face.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    background: str = Field(
+        description="Page canvas background color (behind the face board)."
+    )
+
+
+class VariablesLabelStyle(BaseModel):
+    """Per-label font substyle for variable controls. Cascades from variables.font."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade-starter: _apply_cascade fills from variables.font, then root.
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Variable label font style overrides.",
+    )
+
+
+class VariablesValueStyle(BaseModel):
+    """Per-value font substyle for variable controls. Cascades from variables.font."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade-starter: _apply_cascade fills from variables.font, then root.
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Variable value font style overrides.",
+    )
+    # OpenType numeric feature for slider, number, and date-range value displays.
+    numeric_variant: Literal["normal", "tabular-nums"] = Field(
+        description="OpenType numeric feature for value displays ('normal' or 'tabular-nums')."
+    )
+
+
+class VariablesPlaceholderStyle(BaseModel):
+    """Per-placeholder font substyle for variable controls.
+
+    Placeholder = unselected/hint text in variable inputs (e.g. "-- All --" in
+    a select before the user picks a value). Reads lighter than the selected-value
+    text so the strip is scannable. Cascades from variables.font like value/label.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Cascade-starter: _apply_cascade fills from variables.font, then root.
+    font: FontStyle = Field(
+        default_factory=FontStyle,
+        description="Variable placeholder-text font style overrides.",
+    )
+
+
+class VariablesStyle(BaseModel):
+    """Variable controls chrome styling.
+
+    Note: the old chart_themes system had separate `variables.background`
+    (container bg) and `variables.input_background` (input bg) fields that were
+    sometimes distinct (e.g., cream). In the unified model both collapse
+    to `input.background` — by design, the container and input share the same
+    background. If distinct container vs. input backgrounds are needed in future,
+    add `container_background: str | None` here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    visible: bool = Field(description="Show the variables control panel.")
+    position: Literal["top", "bottom", "title-inline"] = Field(
+        description="Variables strip placement: stacked under the title (top/bottom) "
+        "or on one horizontal band with the face title (title-inline)."
+    )
+    gap: float = Field(description="Gap between variable controls in pixels.")
+    label_position: str = Field(
+        description="Position of labels relative to their input controls (e.g. 'left', 'top')."
+    )
+    title_inline_title_max_width: float = Field(
+        description=(
+            "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 = Field(
+        default_factory=FontStyle,
+        description="Variables panel base font style overrides.",
+    )
+    label: VariablesLabelStyle = Field(description="Variable label typography.")
+    value: VariablesValueStyle = Field(description="Variable value typography.")
+    placeholder: VariablesPlaceholderStyle = Field(
+        description="Style for unselected/hint text in variable inputs."
+    )
+    line_height: float = Field(
+        description="Line height for variable control text in pixels."
+    )
+    padding: float = Field(
+        description="Outer padding around the variables panel in pixels."
+    )
+    container_height: float = Field(
+        description="Height of the variables panel container in pixels."
+    )
+    container_padding: float = Field(
+        description="Inner padding of the variables panel container in pixels."
+    )
+    border: BorderStyle = Field(description="Variables panel border style.")
+    control_gap: float = Field(
+        description="Gap between label and input within a single control in pixels."
+    )
+    input: InputStyle = Field(description="Input control style.")
+    popover_rail_background: str = Field(
+        description=(
+            "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."
+        )
+    )
+
+
+# =============================================================================
+# Style ROOT
+# =============================================================================
+
+
+class Style(BaseModel):
+    """Authoritative compiled style. Built from a single theme YAML file.
+
+    All sections present with defaults matching themes/stark.yaml.
+    This is the 'compiled from theme' layer — not yet resolved/cascaded.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    board: BoardStyle = Field(description="Face-level structural board dimensions.")
+    background: str = Field(
+        description="Working-surface background color (board and card fills)."
+    )
+    # Semantic color tokens — set once at root level, cascade to all UI chrome.
+    # accent: spark.color, spark.bar.color, spark_bar.bar.color, focus_color
+    # muted: spark.bar.background, spark_bar.bar.background
+    # font.color: tick.stroke.color, rule.stroke.color
+    accent: str = Field(
+        description="Accent color token cascaded to sparklines, bars, and focus rings."
+    )
+    muted: str = Field(
+        description="Muted color token cascaded to spark backgrounds and bar tracks."
+    )
+    font: RootFontStyle = Field(
+        description="Root font configuration including emoji mode."
+    )
+    border: BorderStyle = Field(
+        description="Default border style cascaded to all chart cards."
+    )
+    box_shadow: str | None = Field(
+        default=None,
+        description="CSS box shadow for chart cards; None means no shadow.",
+    )
+    opacity: float = Field(description="Default mark opacity (0–1).")
+    title: TitleStyle = Field(description="Board and face title style.")
+    text: TextStyle = Field(description="Markdown and plain text content style.")
+    placeholder: PlaceholderStyle = Field(
+        description="Placeholder overlay style for empty charts."
+    )
+    charts: ChartsStyle = Field(
+        description="Root of all chart-type styles and shared chart configuration."
+    )
+    layout: LayoutStyle = Field(
+        description="Layout container styles (rows, cols, grid, tabs, details)."
+    )
+    variables: VariablesStyle = Field(description="Variable controls chrome style.")
+    page: PageStyle = Field(description="Page-level canvas style (behind the board).")
+    # Cascade-managed sentinel — None means "no aliases at this cascade level" (not empty).
+    # The default theme always supplies this; face YAML patches may omit it (→ None).
+    # deep_merge key-wise merges face-level aliases onto theme aliases so face keys win
+    # while unredefined theme keys propagate. None is intentional here — unlike other
+    # Compiled fields the theme populates, this sentinel distinguishes "no override"
+    # from "empty override" across every cascade step, not just the base.
+    formats: dict[str, str] | None = Field(
+        default=None,
+        description="Format alias map; None means no aliases at this cascade level.",
+    )
+    # Theme palette role assignments.
+    # Open dict: role name → palette file name. No enforced enum.
+    # Default theme seeds conventional roles (chrome, negative, positive, warning,
+    # category, sequence, diverge). Child themes may override individual roles.
+    # None = not authored at this cascade level.
+    palettes: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Theme palette role assignments: open dict mapping role name to palette file name. "
+            "Default seed: chrome, negative, positive, warning, category, sequence, diverge."
+        ),
+    )
+    # Top-level theme role shortcuts.
+    # Optional bare aliases: e.g. ink → chrome.heading. Face authors write the
+    # bare name; resolver dispatches via the dotted palette address.
+    # None = no top-level aliases at this cascade level.
+    roles: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Optional top-level theme role aliases: bare name → role.alias. "
+            "e.g. ink: chrome.heading"
+        ),
+    )
+    # Not theme-populated; per-face authored CSS-chrome. None = no padding override.
+    padding: SpacingValues | None = Field(
+        default=None,
+        description="Per-face padding override (CSS shorthand or structured).",
+    )
+    # Not theme-populated; per-face authored CSS-chrome. None = no margin override.
+    margin: SpacingValues | None = Field(
+        default=None,
+        description="Per-face margin override (CSS shorthand or structured).",
+    )
+    # Not theme-populated; per-face gap override in pixels. None = use layout gap token.
+    gap: float | None = Field(
+        default=None, description="Per-face gap between layout items in pixels."
+    )
+    # Not theme-populated; per-face text color override. None = inherit from theme.
+    color: str | None = Field(
+        default=None, description="Per-face text color override as a CSS color string."
+    )
+
+
+# =============================================================================
+# FORWARD-REF RESOLUTION
+#
+# ChartsStyle references ViewStyle, AutosizeStyle, KpiChartStyle, TableChartStyle,
+# SparkBarChartStyle, and DataTableStyle — all defined after ChartsStyle in this
+# file. With `from __future__ import annotations`, pydantic stores these as
+# ForwardRefs until model_rebuild() resolves them. Rebuilding here (after all
+# classes are defined) ensures that build_patch_model() in authored.py sees
+# resolved annotations when it is called at module-import time.
+# =============================================================================
+
+ChartsStyle.model_rebuild()
+
+
+# =============================================================================
+# PRE-GENERATED PATCH TYPES
+# =============================================================================