Add CSS-first styling and selectable PNG engines

[Alek99]

What changed

• add a CSS-first mark styling contract using standard paint properties: fill, stroke, stroke-width, independent fill/stroke/whole-mark opacity, gradients, dashes, and border radius
• carry supported styling consistently through WebGL, SVG, and the fast native raster exporter
• add a strict cross-renderer axis-style vocabulary with build-time validation, CSS px normalization, separate tick/tick-label paint, and grid dash/opacity support
• expand chrome-slot styling while removing the public mark_style state schema so Reflex remains responsible for reactive state and events
• add Engine.default and Engine.chromium for PNG export, with native export as the fast default and automatic installed-browser discovery for browser/CSS fidelity
• allow custom_css= for Chromium single and batch PNG export; native export rejects browser-only author stylesheets
• resolve complete chart-level color tokens such as var(--accent) in native SVG/PNG
• fix FacetChart.to_png() forwarding gl to a FacetGrid signature that previously did not accept it
• update examples, benchmarks, documentation, migration notes, smoke scripts, and public API checks

Why

XY should accept familiar CSS vocabulary that Reflex users and LLMs already understand instead of introducing an XY-specific styling language or duplicating Reflex conditions, event handling, and application state.

PNG export has a simple tradeoff: a millisecond-scale native default for normal use, plus an explicit Chromium engine when browser CSS, fonts, and WebGL fidelity matter.

User impact

chart.to_png()
chart.to_png(engine=xy.Engine.default)
chart.to_png(
    engine=xy.Engine.chromium,
    custom_css='[data-fc-slot="title"] { font-family: Inter; }',
)

For mark style={...}, use stroke on line-like marks and fill on filled marks. The legacy color= argument remains supported, but color is not a CSS paint alias inside style.

Axis style={...} now rejects unknown keys and invalid colors, directions, opacities, or lengths when the axis is created. Pixel properties accept numbers or values such as "3px".

Migration

• MarkStyle / mark_style(...) are removed; interaction styling stays in Reflex state, conditions, events, and ordinary CSS.
• PNG export now defaults to Engine.default (native). Use Engine.chromium for the installed-browser path.
• String engine values remain deprecated compatibility aliases.
• Browser executable parameters are replaced by automatic discovery or XY_BROWSER.
• custom_css= is Chromium-only for PNG export.

Review follow-ups addressed

• pin the intentional CSS rule that whole-mark opacity also dims area outlines
• validate and document every renderer-backed axis style key before rendering
• preserve separate pyplot tick-mark and tick-label colors/sizes
• align browser, SVG, and native fallback paint to the same blue-gray
• prove colorbar(show=False) clears generated colorbar options
• confirm stroke_perimeter=False is strictly validated as a boolean

Validation

• ruff check .
• ruff format --check .
• ty check
• scripts/check_public_api.py
• focused review suite: 173 passed, 1 skipped
• full suite: 1,693 passed, 63 skipped; one known pyplot timing guardrail failure
• static JS bundle freshness check
• native and Chromium PNG smoke exports both produced correctly sized, nonblank images

Known baseline CI noise

The remaining red checks were reproduced unchanged on current main and are not caused by this PR:

• tests/pyplot/test_perf_guardrail.py::test_pyplot_build_tracks_declarative[10000-60-1.6]
• CodSpeed test_first_payload_hexbin_core_2d payload assertion

[codspeed-hq]

Merging this PR will degrade performance by 85.49%

❌ 2 regressed benchmarks
✅ 78 untouched benchmarks
⏩ 1 skipped benchmark¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_first_payload_contour_core_2d	5.3 ms	58.6 ms	-91.02%
❌	test_first_payload_hexbin_core_2d	8 ms	34 ms	-76.55%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing feat/css-first-customizability (0b098c2) with main (dfd247b)²}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

2. No successful run was found on main (eb0c3f7) during the generation of this report, so dfd247b was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩