docs: redesign the XY information architecture and chart gallery (#64)

* docs: redesign XY documentation

* docs: adapt gallery charts for dark mode

* docs: polish gallery toolbar states

* docs: add uv-first install tabs

* docs: render the first chart live

* docs: sync hero toolbar with color mode

* docs: render core concepts composition live

* docs: group live examples in docdemos

* chore: satisfy CI formatting checks

Author: Alek99

docs/api-reference/changelog.md

@@ -0,0 +1,43 @@
+---
+title: Changelog
+description: Review migration notes and notable changes in the XY alpha series.
+---
+
+# Changelog
+
+The canonical, complete history lives in the repository's
+[CHANGELOG.md](https://github.com/reflex-dev/xy/blob/main/CHANGELOG.md). It
+follows Keep a Changelog; semantic-versioning compatibility becomes the firm
+contract at 1.0. Before 1.0, a minor release can contain breaking changes.
+
+## Current Unreleased Migration Notes
+
+- The fluent public `Figure` builder has been removed. Build with declarative
+  chart and component factories; use `Chart` for display, export, streaming,
+  and readout. `Chart.figure()` remains an advanced internal-engine escape
+  hatch.
+- Mark `style=` now uses paint-specific CSS: `stroke` for line-like marks and
+  `fill` for filled marks. The legacy factory `color=` argument remains, but
+  `color` is not an alias inside a style dictionary.
+- The former `MarkStyle`/`mark_style()` state-styling surface is removed.
+  Framework applications should derive ordinary props and styles from
+  application state.
+- PNG export defaults to the browser-free native renderer. Select
+  `Engine.chromium` for browser CSS/WebGL fidelity.
+- Chromium PNG accepts `custom_css=`. Native PNG rejects author CSS; complete
+  chart-level tokens can still resolve through renderable chart styles.
+- Browser executable parameters were replaced by automatic discovery or the
+  `XY_BROWSER` environment variable.
+
+## Recent Additions
+
+The current alpha line added the compact accessible toolbar and editable lasso
+selection, the versioned binary frame transport, declarative statistical and
+density families, facets, live `Chart.append()`/`pick()`/`select_range()`,
+browser-free native PNG, pure SVG export, CSS-compiled mark styling, and the
+experimental `xy.pyplot` compatibility layer.
+
+Read [Chart methods](/docs/xy/api-reference/figure-methods/),
+[Mark styles](/docs/xy/styling/mark-styles/), and
+[Limitations and alpha status](/docs/xy/api-reference/limitations-and-alpha-status/)
+when upgrading code across alpha releases.

docs/api-reference/chart-factories.md

@@ -0,0 +1,54 @@
+---
+title: Chart Factories
+description: Reference XY chart containers, shared props, and facet construction.
+---
+
+# Chart Factories
+
+Chart factories compose marks, axes, annotations, and chrome into a public
+`Chart`. The generated inventory below follows the same taxonomy as the
+[Chart Gallery](/docs/xy/charts/). Its names, signatures, and defaults come
+directly from XY's public Python callables.
+
+Use `chart()` when different mark kinds share a panel. A family container is
+usually clearer when the children represent one chart family.
+
+## Generated Factory API
+
+~~~python exec
+from xy_docs.api_reference import chart_containers_api, chart_factories_api
+~~~
+
+~~~python eval
+chart_factories_api()
+~~~
+
+Annotation-only compositions use the neutral `chart()` container, so that
+factory appears under Annotations. It also appears beside `facet_chart()` in
+Facets and Layers because layered marks use the same neutral container.
+
+## Shared Chart Props
+
+~~~python eval
+chart_containers_api()
+~~~
+
+The “Shared chart props” table is generated from the public `Chart`
+constructor. Every ordinary factory accepts those props through `**props`;
+`facet_chart` exposes its grid controls directly in its generated factory
+table and forwards the remaining props to each panel.
+
+## Facet Constraints
+
+`facet_chart` requires `by=` values or a column name resolved from chart-level
+`data=`. Its width and height must be positive integer pixel counts; panel
+columns and gap are integers. Marks that use row-aligned raw channels must use
+compatible arrays or column names so each panel can be subset safely.
+
+Shared facet axes coordinate panel domains and browser viewport changes.
+`FacetChart` supports display, export, and memory reporting, but does not expose
+`Chart.append()`, `pick()`, or `select_range()`.
+
+See [Composition model](/docs/xy/core-concepts/) for usage and
+[Chart methods](/docs/xy/api-reference/figure-methods/) for the returned
+objects.

docs/api-reference/components.md

@@ -0,0 +1,71 @@
+---
+title: Contributing
+description: Set up XY development, run the right gates, and prepare a focused change.
+---
+
+# Contributing
+
+XY welcomes focused bug fixes, documentation improvements, tests, and chart
+surface work. The canonical contributor guide is
+[CONTRIBUTING.md](https://github.com/reflex-dev/xy/blob/main/CONTRIBUTING.md);
+the engineering version contains the complete release and browser checklists.
+
+## Local Setup
+
+~~~bash
+git clone https://github.com/reflex-dev/xy.git
+cd xy
+uv venv
+uv pip install -e ".[dev]"
+make check
+~~~
+
+Source development needs Python 3.11+, a Rust toolchain for the native core,
+and Node 18+ for bundle checks. Confirm the active compute backend explicitly:
+
+~~~bash
+python -c "import xy.kernels as k; print(k.BACKEND)"
+~~~
+
+The supported value is `native`. An unavailable core should raise a clear
+import error rather than silently selecting another backend.
+
+## Choose the Focused Gate
+
+| Change | Check |
+| --- | --- |
+| Fast local verification | `make check` |
+| Production-facing change | `make check-full` |
+| Public docs, examples, or claims | `make check-docs` |
+| Public exports or annotations | `make check-api` |
+| Lazy imports and dependency boundaries | `make check-import` |
+| Validation and mutation behavior | `make check-errors` |
+| Standalone HTML and text safety | `make check-security` |
+| Browser lifecycle and interaction | `make check-browser CHROMIUM=/path/to/chrome` |
+
+Run `make check-claims` before publishing performance prose. Every comparison
+must name the chart type, data size and shape, representation mode, backend,
+render target, and whether browser time-to-first-render is included.
+
+## Adding a Chart Type
+
+A complete chart-family contribution normally spans:
+
+1. Builder validation and rollback tests.
+2. Canonical column ingest or an aggregate kernel.
+3. Payload metadata with an explicit direct, decimated, density, sampled, or
+   adaptive mode.
+4. Renderer support or reuse of an existing primitive.
+5. Standalone/export coverage, including hostile text values.
+6. A declarative factory and generated API documentation.
+7. A normal-size visual example, plus a benchmark only when the methodology is
+   honest and reproducible.
+
+Keep generated assets derived from their source generator, preserve lazy
+`import xy` behavior, and include new public symbols in `xy.__all__` with type
+surface tests.
+
+Before opening a pull request, read the relevant architecture material in the
+repository and open a focused
+[GitHub issue](https://github.com/reflex-dev/xy/issues/new) when the desired
+behavior changes a public contract.

docs/api-reference/contributing.md

@@ -0,0 +1,79 @@
+---
+title: Events and Callbacks
+description: Reference core Chart callbacks, Selection payloads, browser events, and adapter names.
+---
+
+# Events and Callbacks
+
+Core `Chart` callbacks run in Python through a live notebook widget or framework
+transport. Browser interactions continue to work in standalone HTML, but a
+self-contained file has no Python process to call.
+
+## Core Python Callbacks
+
+| Chart prop | Python payload |
+| --- | --- |
+| `on_hover` | Exact canonical row dictionary for the hovered point |
+| `on_click` | Exact canonical row dictionary for the clicked point |
+| `on_brush` | Selection geometry: normalized `x0`/`x1`/`y0`/`y1` or a `polygon` |
+| `on_select` | A `Selection` with canonical row indices grouped by trace |
+| `on_view_change` | Normalized `x0`, `x1`, `y0`, `y1`, and `source` |
+
+Supplying a callback enables its corresponding browser interaction. Callback
+payload details are still experimental during the alpha series.
+
+Hover and click rows contain `trace`, canonical `index`, `x`, `y`, `x_kind`,
+and `y_kind`. Depending on the mark's channels, they can also contain
+`color_value`, `color_category`, or `size_value`. These are data dictionaries,
+not DOM event objects or formatted tooltip strings.
+
+~~~python
+import xy
+
+
+def selected(selection: xy.Selection) -> None:
+    print(len(selection), selection.per_trace)
+
+
+chart = xy.scatter_chart(
+    xy.scatter([0, 1, 2], [2, 4, 3]),
+    on_select=selected,
+)
+~~~
+
+## Selection
+
+`Selection` exposes:
+
+- `per_trace` — `{trace_id: numpy_uint32_indices}` in canonical row space.
+- `index` — all selected indices concatenated; use `per_trace` when trace
+  identity matters.
+- `xy(trace_id=0)` — canonical f64 x/y arrays for one selected trace.
+- `len(selection)` — total selected rows across traces.
+
+Clearing selection delivers an empty `Selection`. `Chart.select_range()`
+returns the same type without requiring a browser gesture.
+
+## Browser DOM Events
+
+The client dispatches bubbling custom events from the chart root:
+
+| Event | Detail |
+| --- | --- |
+| `xy:hover` | Resident or exact `row`, `trace`, `index`, viewport, and optional `exact` flag |
+| `xy:click` | Data-space `x`/`y`, optional row hit, trace/index, and viewport |
+| `xy:select` | Selected `total`, viewport, and range or polygon when resolved locally |
+| `xy:view_change` | `x0`, `x1`, `y0`, `y1`, and interaction `source` |
+
+A live hover can emit an immediate resident readout followed by an exact update.
+Consumers that only need the canonical Python row should use `on_hover`.
+
+## Reflex Adapter Events
+
+The separate `reflex-xy` adapter intentionally uses semantic component props:
+`on_point_hover`, `on_point_click`, `on_select_end`, and `on_view_change`.
+Those are adapter props, not aliases accepted by core `Chart`. See the
+[Reflex integration](/docs/xy/integrations/reflex/) for state-backed payloads.
+
+Linked charts broadcast viewport ranges only. They do not automatically link
+selection state or cross-filter data.