docs(sphinx-ux-tabs): Document :class-container:, --large variant, deep-links, prehydrate

why: Four author-facing capabilities landed without reference docs;
make them discoverable.

what:
- Add :class-container: row to {tab-item} option table
- Add Size variants section to reference.md and how-to.md
- Add Persistence and deep-links section to reference.md and how-to.md
- Add Prehydrate subsection under JavaScript in reference.md
- Examples.md gains side-by-side default-vs-large tab-set and deep-link demo

Author: tony

docs/packages/sphinx-ux-tabs/examples.md

@@ -133,6 +133,93 @@ source ~/.config/fish/config.fish
 
 Click a tab in either tab-set; the other follows.
 
+## Size variants
+
+Default size — compact labels at `0.95em`:
+
+::::{tab-set}
+
+:::{tab-item} pip
+```console
+$ pip install gp-sphinx
+```
+:::
+
+:::{tab-item} uv
+```console
+$ uv add gp-sphinx
+```
+:::
+
+:::{tab-item} pipx
+```console
+$ pipx install gp-sphinx
+```
+:::
+
+::::
+
+`:class: gp-sphinx-tabs--large` — body-size labels with roomier
+padding:
+
+::::{tab-set}
+:class: gp-sphinx-tabs--large
+
+:::{tab-item} pip
+```console
+$ pip install gp-sphinx
+```
+:::
+
+:::{tab-item} uv
+```console
+$ uv add gp-sphinx
+```
+:::
+
+:::{tab-item} pipx
+```console
+$ pipx install gp-sphinx
+```
+:::
+
+::::
+
+## Deep-link to a tab
+
+::::{tab-set}
+:sync-group: example
+
+:::{tab-item} Python
+:sync: python
+```python
+print("hello world")
+```
+:::
+
+:::{tab-item} Rust
+:sync: rust
+```rust
+println!("hello world");
+```
+:::
+
+:::{tab-item} Go
+:sync: go
+```go
+fmt.Println("hello world")
+```
+:::
+
+::::
+
+Open this page with <a href="?example=python"><code>?example=python</code></a>
+to pre-select the Python tab via the sphinx-design URL form. The
+legacy sphinx-inline-tabs form is supported too:
+<a href="?tabs=Python"><code>?tabs=Python</code></a>. Either form
+writes through to `localStorage`, so the choice persists on subsequent
+visits.
+
 ## `:new-set:` breaks a consecutive run
 
 ```{eval-rst}

docs/packages/sphinx-ux-tabs/how-to.md

@@ -92,6 +92,59 @@ Later: see {ref}`the Python tab <py-tab>` for details.
 The label is the anchor — clicking the `{ref}` jumps to the tab's
 label, the radio remains in whichever state the user last selected.
 
+## Deep-link to a specific tab
+
+`sphinx-ux-tabs` reads two URL query-parameter forms on first paint and
+writes the resolved selection through to `localStorage`, so a link
+that sets a tab also persists the choice for the user's next visit.
+
+The label form deep-links by visible text — appropriate when the link
+target shouldn't care about authoring details:
+
+```
+https://example.org/install/?tabs=Python
+```
+
+The group form deep-links by the `:sync-group:` / `:sync:` pair —
+appropriate when more than one tab on the page shares a label, or when
+the link should target a specific sync-group:
+
+```
+https://example.org/install/?shell=zsh
+```
+
+Both forms persist to `localStorage` under the key
+`gp-sphinx-tabs.sync.<group>`, so the next page load on the same
+sync-group restores the user's last choice automatically. URL params
+apply on first paint only — subsequent SPA-nav events read from
+`localStorage`.
+
+## Use the larger size variant
+
+The default tab size is compact (`0.95em` labels) to match the
+workspace's tight prose rhythm. Use `:class: gp-sphinx-tabs--large` on
+the `{tab-set}` for callout sections, feature-comparison tables, or
+landing-page hero tabs — anywhere touch-target size or label
+prominence matters more than vertical economy.
+
+````markdown
+:::{tab-set}
+:class: gp-sphinx-tabs--large
+
+:::{tab-item} pip
+...
+:::
+
+:::{tab-item} uv
+...
+:::
+
+:::
+````
+
+The `:class:` option preserves the BEM `--` modifier verbatim — no
+extra escaping required.
+
 ## Use tabs after SPA navigation
 
 Tabs work without JS — the `:checked + label + .panel` selectors

docs/packages/sphinx-ux-tabs/reference.md

@@ -130,6 +130,73 @@ The first tab with `:selected:` wins. If none is selected, index 0 is
 checked. Multiple `:selected:` tabs emit a Sphinx warning under the
 subtype `gp-sphinx-tabs.tab`.
 
+## Size variants
+
+The default size renders labels at `0.95em` with tight padding to match
+the workspace's compact prose rhythm. Authors can opt into a larger
+size with `:class: gp-sphinx-tabs--large` on `{tab-set}` — labels paint
+at normal body size with roomier padding, suitable for callout
+sections, feature-comparison tables, or landing-page hero tabs.
+
+````markdown
+:::{tab-set}
+:class: gp-sphinx-tabs--large
+
+:::{tab-item} pip
+`pip install gp-sphinx`
+:::
+
+:::{tab-item} uv
+`uv add gp-sphinx`
+:::
+
+:::
+````
+
+The `:class:` option preserves BEM `--` modifiers verbatim.
+`sphinx-ux-tabs` uses a custom class-option parser specifically so the
+`gp-sphinx-tabs--large` token survives — docutils' built-in
+`class_option` would collapse the `--` to a single `-`.
+
+## Persistence and deep-links
+
+`sphinx-ux-tabs` persists each user's tab choice and accepts URL query
+parameters to deep-link a specific tab.
+
+### localStorage
+
+Every `:sync-group:` gets its own `localStorage` key under the
+namespace `gp-sphinx-tabs.sync.<group>`. On click, the JS writes the
+chosen `:sync:` ID under that key. On script-load and on every
+`gp-sphinx:navigated` event (workspace SPA navigation), the JS reads
+every distinct `data-sync-group` on the page and restores the saved
+selection.
+
+### URL query parameters
+
+URL query parameters take precedence over `localStorage` on first
+paint and write through to `localStorage` so the choice persists for
+subsequent visits. Two formats are accepted:
+
+```{list-table}
+:header-rows: 1
+:widths: 30 70
+
+* - Form
+  - Behaviour
+* - `?tabs=Label`
+  - sphinx-inline-tabs idiom — matches by tab label text,
+    case-insensitive. Pre-selects every label whose visible text equals
+    `Label`.
+* - `?<group>=<id>`
+  - sphinx-design idiom — matches by `:sync-group:` / `:sync:`.
+    Multiple `?key=val` pairs accumulate, one per distinct group.
+```
+
+URL parameters apply on first paint only. Subsequent SPA-nav events
+read from `localStorage` only — re-applying URL params on every
+navigation would let stale query strings override a fresh click.
+
 ## CSS classes
 
 ```{list-table}
@@ -140,6 +207,8 @@ subtype `gp-sphinx-tabs.tab`.
   - Applied to
 * - `gp-sphinx-tabs`
   - Outer tab-set container.
+* - `gp-sphinx-tabs--large`
+  - Modifier on `gp-sphinx-tabs` opting into the larger size variant.
 * - `gp-sphinx-tabs__input`
   - Hidden radio input (`<input type="radio">`).
 * - `gp-sphinx-tabs__label`
@@ -191,6 +260,24 @@ The shipped sync JS is page-scoped, idempotent, and SPA-aware:
 Tabs work without the JS — pure CSS handles single-page switching.
 The JS is only needed for cross-tab-set sync.
 
+### Prehydrate
+
+Pages that host sync'd tabs receive a small inline `<head>` payload —
+a `<script data-cfasync="false">` and a `<style>` block under
+`@layer gp-sphinx-tabs-prehydrate`. The script reads URL query
+parameters and `localStorage`, then sets
+`<html data-gp-sphinx-tabs-sync-<group>="<id>">` before any stylesheet
+loads. The CSS layer's attribute selectors then paint the saved
+label colour and panel visibility on the first frame, so the user
+never sees the server-rendered default tab flash to the saved
+selection.
+
+`data-cfasync="false"` opts the inline script out of Cloudflare Rocket
+Loader so it runs synchronously as written. Pages without sync'd tabs
+carry zero prehydrate payload — the prehydrate injection short-circuits
+when the post-transform records no `(sync_group, sync_id)` pairs for
+the page.
+
 ## Python API
 
 ```{eval-rst}