@roxyapi/ui 0.8.0 → 0.9.0

package/AGENTS.md

@@ -122,16 +122,15 @@ Every chart endpoint accepts `timezone` as either a decimal-hour offset (`5.5` f
 
 ### 4. Secret key in the browser
 
-There are two key classes. **Secret keys are unprefixed** and grant full access; they belong server-side only (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions). **Publishable keys** are prefixed `pk_live_*` or `pk_test_*` and are safe in the browser; they are locked to an origin allowlist at the API gateway. For widgets, embeds, vanilla HTML, and `data-publishable-key` use the publishable key. For the typed SDK on a server, use the secret key.
+Secret keys (`sk_*`) grant full account access and are server side only. Call `createRoxy(process.env.ROXY_API_KEY!)` on your server (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions), then send the response, not the key, to the component. Never ship a secret key in a client bundle.
 
 ```ts
-// Server (Next.js route handler, Workers, Bun): secret key
+// Secret key: server side only
 const roxy = createRoxy(process.env.ROXY_API_KEY!);
-
-// Browser (widgets auto-mount): publishable key
-<div data-roxy-widget="natal-chart" data-publishable-key="pk_live_xxx" ...></div>
 ```
 
+For direct client-side calls, use a **publishable key** (`pk_live_*` / `pk_test_*`) instead. Publishable keys are browser-safe: mint one at `roxyapi.com/account`, register the origins you embed on, and the API gateway returns 403 for any other origin. See the client-side pattern below.
+
 ### 5. Missing `'use client'` in Next.js App Router
 
 The React components in `@roxyapi/ui-react` mount Custom Elements, which need the DOM. In the App Router, files that import them must declare `'use client'` at the top. Server Components can fetch with the SDK; the client component renders.
@@ -194,30 +193,30 @@ import type { NatalChartResponse } from '@roxyapi/sdk';
 
 ### Pattern 1: vanilla HTML, no build step
 
+Fetch on your server with the secret key, then inline the response into the component as a child `<script type="application/json" class="roxy-data">`. The component reads it on load. No key in the browser.
+
 ```html
 <script
 	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
 	crossorigin="anonymous"
 ></script>
 
-<roxy-natal-chart id="chart"></roxy-natal-chart>
-
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('pk_live_xxx');
-	const { data } = await roxy.astrology.generateNatalChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('chart').data = data;
-</script>
+<roxy-natal-chart>
+	<script type="application/json" class="roxy-data">
+		{ "planets": [ ... ], "houses": [ ... ], "aspects": [ ... ] }
+	</script>
+</roxy-natal-chart>
 ```
 
-### Pattern 2: React, with the typed SDK
+Setting the JavaScript `data` property always wins over the inlined JSON, so the same element also drives dynamic pages.
+
+### Pattern 2: React, interactive
+
+`<RoxyLocationSearch>` runs in the browser. On select, call your own route, which holds the secret key, and set the returned data on the chart. The key never reaches the client.
 
 ```tsx
 'use client';
 
-import { createRoxy } from '@roxyapi/sdk';
 import {
 	RoxyNatalChart,
 	RoxyLocationSearch,
@@ -225,18 +224,18 @@ import {
 } from '@roxyapi/ui-react';
 import { useState } from 'react';
 
-const roxy = createRoxy(process.env.NEXT_PUBLIC_ROXY_API_KEY!);
-
 export function BirthChartView() {
 	const [chart, setChart] = useState<RoxyNatalChartProps['data']>(undefined);
 
 	const onLocationSelect = async (e: CustomEvent<{ latitude?: number; longitude?: number; timezone?: number | string }>) => {
 		const { latitude, longitude, timezone } = e.detail;
 		if (latitude == null || longitude == null) return;
-		const { data } = await roxy.astrology.generateNatalChart({
-			body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
+		// Your route calls roxy.astrology.generateNatalChart with the secret key.
+		const res = await fetch('/api/natal-chart', {
+			method: 'POST',
+			body: JSON.stringify({ date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone }),
 		});
-		setChart(data);
+		setChart(await res.json());
 	};
 
 	return (
@@ -248,9 +247,11 @@ export function BirthChartView() {
 }
 ```
 
+For a static chart with no picker, fetch in a Server Component and pass `data` to a client component (Pattern 6).
+
 ### Pattern 3: schema-driven form
 
-`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. Listen for the `roxy-submit` event with the validated payload.
+`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. On `roxy-submit`, POST the validated values to your own route, which calls the SDK with the secret key, then set the returned data on the target component.
 
 ```html
 <roxy-endpoint-form
@@ -258,41 +259,42 @@ export function BirthChartView() {
 	method="POST"
 	submit-label="Generate kundli"
 ></roxy-endpoint-form>
+<roxy-vedic-kundli chart-style="south"></roxy-vedic-kundli>
 
 <script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('pk_live_xxx');
 	const form = document.querySelector('roxy-endpoint-form');
 	form.addEventListener('roxy-submit', async (e) => {
-		const { values } = e.detail;
-		const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({ body: values });
-		document.querySelector('roxy-vedic-kundli').data = kundli;
+		// Your route calls roxy.vedicAstrology.generateBirthChart with the secret key.
+		const res = await fetch('/api/kundli', { method: 'POST', body: JSON.stringify(e.detail.values) });
+		document.querySelector('roxy-vedic-kundli').data = await res.json();
 	});
 </script>
 ```
 
-### Pattern 4: widgets auto-mount (no JavaScript wiring)
+### Pattern 4: fully client-side with a publishable key (no server)
 
-Use a publishable key (`pk_live_*` or `pk_test_*`) for client-side embeds. Get one at <https://roxyapi.com/account>. Publishable keys are origin-restricted at the API gateway. Register the customer domain (e.g. `https://customer.com`) when creating the key, and the gateway will reject requests from any other origin. Never use a secret key in client-side code (secret keys are unprefixed and live server-side only).
+When you do not want a backend at all, mint a **publishable key** (`pk_live_*`) at `roxyapi.com/account`, register the origins you embed on, and call RoxyAPI directly from the browser. The publishable key is safe to ship in client code: it is origin-restricted (any other origin gets 403) and cannot read your account. `<roxy-location-search>` accepts the key via its `publishable-key` attribute and fetches geocoding itself; for the data endpoints you make a normal browser `fetch` with the key in the `X-API-Key` header, then assign the response to the rendering component.
 
 ```html
-<script
-	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js"
-	defer
-></script>
+<roxy-location-search publishable-key="pk_live_..."></roxy-location-search>
+<roxy-natal-chart></roxy-natal-chart>
 
-<div
-	data-roxy-widget="natal-chart"
-	data-publishable-key="pk_live_xxx"
-	data-date="1990-01-15"
-	data-time="14:30:00"
-	data-latitude="19.07"
-	data-longitude="72.88"
-	data-timezone="5.5"
-></div>
+<script type="module">
+	const chart = document.querySelector('roxy-natal-chart');
+	document.querySelector('roxy-location-search').addEventListener('roxy-location-select', async (e) => {
+		const { latitude, longitude, timezone } = e.detail;
+		if (latitude == null || longitude == null) return;
+		const res = await fetch('https://roxyapi.com/api/v2/astrology/natal-chart', {
+			method: 'POST',
+			headers: { 'X-API-Key': 'pk_live_...', 'Content-Type': 'application/json' },
+			body: JSON.stringify({ date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone }),
+		});
+		chart.data = await res.json(); // pass the unwrapped response, not an envelope
+	});
+</script>
 ```
 
-The auto-mount script reads `data-*` attributes, calls the matching endpoint, and renders the matching component.
+Rendering components do not fetch on their own; you set `data`. Only `<roxy-location-search>` (and `<roxy-endpoint-form>` for the spec) fetch internally. A zero-wiring `data-*` auto-mount that fetches and renders with no script is still on the roadmap.
 
 ### Pattern 5: MCP tool-call response
 
@@ -360,13 +362,13 @@ This is how the WordPress plugin renders: PHP fetches the response server-side,
 
 ## Theming and dark mode
 
-Components react to three signals in priority order. No events to dispatch. No JS bridge to write.
+Components react to three signals in priority order. No events to dispatch. No JS bridge to write. The CDN bundle (`dist/cdn/roxy-ui.js`) auto-loads the design tokens, so a single script tag yields full theming and dark mode with nothing else to add. The npm and React paths inherit the same tokens through the components; only set up `tokens.css` yourself if you import per component without the full bundle.
 
 | Signal | Where | Effect |
 |---|---|---|
 | `prefers-color-scheme: dark` | OS | Default. Follows user system setting. |
 | `data-theme="light"` or `data-theme="dark"` | `<html>` / `<body>` / any ancestor / the component itself | Wins over OS. Per-element override scope works. |
-| `.dark` class | Any ancestor | Equivalent to `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). |
+| `.dark` class | The component itself or any ancestor (typically `<html>`) | Same effect as `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). |
 
 To toggle at runtime:
 
@@ -396,7 +398,7 @@ Every visible aspect of the chart is driven by `--roxy-*` CSS custom properties
 
 ## Domain ordering
 
-When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain.
+When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain.
 
 ## What not to ship
 

package/README.md

@@ -55,7 +55,7 @@ Light, dark, your brand. Override one CSS variable and every component updates.
 ```css
 :root {
   /* Surface */
-  --roxy-bg: #fafafa;
+  --roxy-bg: #ffffff;
   --roxy-fg: #0a0a0a;
   --roxy-muted: #71717a;
   --roxy-border: #e4e4e7;
@@ -66,13 +66,13 @@ Light, dark, your brand. Override one CSS variable and every component updates.
 
   /* Status (each has a -fg variant for WCAG-AA text contrast) */
   --roxy-success: #16a34a;
-  --roxy-warning: #f59e0b;
+  --roxy-warning: #ea580c;
   --roxy-danger: #dc2626;
-  --roxy-info: #2563eb;
+  --roxy-info: #0284c7;
 
   /* Shape + motion */
-  --roxy-radius-md: 12px;
-  --roxy-shadow-md: 0 4px 12px rgba(0,0,0,0.08);
+  --roxy-radius-md: 8px;
+  --roxy-shadow-md: 0 4px 6px -1px rgba(0,0,0,0.08), 0 2px 4px -2px rgba(0,0,0,0.06);
   --roxy-motion-duration: 200ms; /* 0ms when prefers-reduced-motion */
 }
 
@@ -221,42 +221,24 @@ Tables, cards, forms, and helper components in the [live demo](https://roxyapi.g
 
 ## Start with one component
 
-Vanilla HTML. No build step. Replace `YOUR_API_KEY` with a publishable key from <https://roxyapi.com/account>.
+Fetch with the typed SDK, pass `data` to the component. No glue code.
 
-```html
-<script
-	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
-	crossorigin="anonymous"
-	defer
-></script>
-<roxy-natal-chart id="chart"></roxy-natal-chart>
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('YOUR_API_KEY');
-	const { data } = await roxy.astrology.generateNatalChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('chart').data = data;
-</script>
-```
+```tsx
+import { createRoxy } from '@roxyapi/sdk';
+import { RoxyHoroscopeCard } from '@roxyapi/ui-react';
 
-> **Unwrap `data` before passing to the component.** The SDK returns `{ data, error, request, response }`. Pass the envelope and the chart renders `[object Object]`. This is the most common integration bug.
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
-Want a Vedic kundli instead? Same shape, different SDK method:
+const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
 
-```html
-<roxy-vedic-kundli id="kundli" chart-style="south"></roxy-vedic-kundli>
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('YOUR_API_KEY');
-	const { data } = await roxy.vedicAstrology.generateBirthChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('kundli').data = data;
-</script>
+return <RoxyHoroscopeCard data={data} />;
 ```
 
-In production, geocode the user's city with `<roxy-location-search>` (see [Quick start](#quick-start)) instead of hardcoding coordinates.
+Then expand into natal charts, kundli, dasha, tarot, and every other domain. The SDK returns `data`, the component renders it; the same pairing holds for all 32 components.
+
+> **Pass `data`, not the envelope.** The SDK returns `{ data, error, request, response }`. Pass `data`, or the component renders `[object Object]`. This is the most common integration bug.
+
+The key stays on your server. Vanilla HTML or a server-rendered page fetches the same way, then [inlines the JSON into the component](#server-rendered-no-javascript-wiring): no build step, no key in the browser. Try every component in the [live demo](https://roxyapi.github.io/ui/), each with Preview, Code, and shadcn tabs and a live color customizer.
 
 ## Install
 
@@ -312,7 +294,12 @@ Always call `/location/search` first. Every chart endpoint expects latitude, lon
 
 Server-rendered and cached pages (WordPress, JSX SSR, static HTML) cannot always run JavaScript to set the `data` property per element. Render the response into a child `<script type="application/json" class="roxy-data">` on the server instead. The component reads it on load. No per-element script, no API key in the browser.
 
+Load the bundle once anywhere on the page. It registers every `roxy-*` element and loads the design tokens, so every component on the page renders themed, in light or dark, from that single tag. Nothing else to add.
+
 ```html
+<!-- Once per page: defines every roxy-* element -->
+<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js" crossorigin="anonymous" defer></script>
+
 <roxy-natal-chart>
 	<script type="application/json" class="roxy-data">
 		{ "planets": [ ... ], "houses": [ ... ], "aspects": [ ... ] }
@@ -464,7 +451,48 @@ const { data: cc } = await roxy.tarot.castCelticCross({
 <RoxyTarotSpread data={cc} />
 ```
 
-### 5. Biorhythm (daily, forecast)
+### 5. Human Design (bodygraph)
+
+The breakout 2026 self-knowledge category, computed from the same ephemeris as Western astrology plus the I Ching gate wheel and chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots ship the full bodygraph first. No coordinates needed; Human Design uses the birth instant, not the observer location.
+
+```tsx
+import { RoxyBodygraph } from '@roxyapi/ui-react';
+
+// Full bodygraph. The head term every Human Design app leads with ("human design chart").
+// Type, strategy, authority, profile, the nine centers, channels, and every gate
+// activation in one call. Pass the birth instant only, no latitude or longitude.
+const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
+  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+});
+<RoxyBodygraph data={bodygraph} />
+```
+
+### 6. Forecast (transits, cross-domain timeline)
+
+The first cross-domain, stateless forecast in the catalog: one call merges Western transits, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Forecast feeds, transit alerts, and timing tools are the buyers. Acquire on the high-volume `astrology transits` search, convert on the cross-domain timeline no competitor ships. No coordinates needed.
+
+```tsx
+import { RoxyForecastTimeline } from '@roxyapi/ui-react';
+
+// Transit forecast. The demand leader. Western transit-to-natal aspects, sign
+// ingresses, and retrograde stations over the window.
+const { data: transits } = await roxy.forecast.forecastTransits({
+  body: { birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 } },
+});
+<RoxyForecastTimeline data={transits} />
+
+// Cross-domain timeline. The same window merged with Vedic dasha boundaries and
+// biorhythm critical days into one significance-scored timeline.
+const { data: timeline } = await roxy.forecast.generateTimeline({
+  body: {
+    birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+    domains: ['western', 'vedic', 'biorhythm'],
+  },
+});
+<RoxyForecastTimeline data={timeline} />
+```
+
+### 7. Biorhythm (daily, forecast)
 
 Zero competition domain. Steady search volume with the top Google result being a static calculator page. Pure land-grab for wellness, productivity, sports, and couples apps.
 
@@ -485,7 +513,7 @@ const { data: forecast } = await roxy.biorhythm.getForecast({
 <RoxyBiorhythmChart data={forecast} mode="forecast" />
 ```
 
-### 6. I Ching (cast a reading, hexagram lookup)
+### 8. I Ching (cast a reading, hexagram lookup)
 
 Meditation apps, decision-making tools, and wisdom chatbots. `i ching API` and `hexagram API` are the keywords.
 
@@ -505,12 +533,11 @@ const { data: random } = await roxy.iching.getRandomHexagram();
 
 ## API keys
 
-Get keys at <https://roxyapi.com/account>.
+Get a key at <https://roxyapi.com/account>.
 
-- **Secret key** (server-side only). Use in Node, Bun, Hono, Next.js route handlers, Workers. Never commit, never ship in client bundles.
-- **Publishable key** (`pk_live_*` / `pk_test_*`). Safe in browsers, locked to the origins you register on the key. Use with the widgets auto-mount script for WordPress, Shopify, static HTML, embed scenarios. The API gateway rejects requests from any origin not on the allowlist.
+Two key types. **Secret keys** (`sk_*`) grant full account access: use them server side only (Node, Bun, Hono, Next.js route handlers, Workers). Never commit one, never ship one in a client bundle. **Publishable keys** (`pk_live_*` / `pk_test_*`) are browser-safe: mint one, register the origins you embed on, and any other origin gets a 403 at the gateway. Use a publishable key when you call RoxyAPI directly from the browser with no backend.
 
-For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your server env. For the widgets auto-mount path (`data-publishable-key="pk_live_xxx"`), use a publishable key with your domain registered on it.
+Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK examples on this page. For direct client-side embedding with no backend, use a publishable key (see the fully client-side pattern in [`AGENTS.md`](AGENTS.md)).
 
 ## Distribution
 
@@ -520,7 +547,7 @@ For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your se
 | npm `@roxyapi/ui-react` | `npmjs.com/package/@roxyapi/ui-react` |
 | jsDelivr CDN (full bundle) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js` |
 | jsDelivr CDN (per component) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/components/{name}.js` |
-| Widgets auto-mount | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
+| Widgets auto-mount (with browser keys, coming soon) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
 | shadcn registry | `npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/{name}.json` |
 
 ## Components
@@ -574,7 +601,7 @@ For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your se
 
 ## Theming
 
-Every component reads from `--roxy-*` CSS custom properties. Override globally on `:root` or per element. Light + dark defaults, container queries for responsive layouts at 320px and up. See [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md) for the full token reference.
+Every component reads from `--roxy-*` CSS custom properties. Override globally on `:root` or per element. Light + dark defaults, container queries for responsive layouts at 320px and up. The CDN bundle auto-loads these tokens; your `:root { --roxy-* }` overrides always win over the defaults. See [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md) for the full token reference.
 
 ```css
 :root {
@@ -657,7 +684,7 @@ Persist the choice in `localStorage` from your own code; the components do not o
 <details>
 <summary><strong>How big is each component? What is the bundle cost?</strong></summary>
 
-Per-component bundles run 6-10 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles) stays well under the 150 KB CI cap, around 45 KB gzipped today. The React package loads the runtime on mount, so a route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
+Per-component bundles run 6-10 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles, and the inlined design tokens) stays well under the 150 KB CI cap, around 54 KB gzipped today. The React package loads the runtime on mount, so a route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
 </details>
 
 <details>
@@ -770,7 +797,7 @@ Components ship in Shadow DOM for style isolation; Tailwind utilities are scoped
 <details>
 <summary><strong>What is the security model for API keys?</strong></summary>
 
-Two key classes. Secret keys (unprefixed) live server-side only and grant full access. Publishable keys (`pk_live_*` / `pk_test_*`) are browser-safe and locked to an origin allowlist registered on the key. The API gateway rejects requests from any other origin and counts the failed attempt against the rate limit, so a stolen key cannot be brute-fired from elsewhere.
+Two key types. Secret keys (`sk_*`) live server side only and grant full access, so never ship one in a client bundle: fetch on your server and pass the rendered response, not the key, to the browser. Publishable keys (`pk_live_*` / `pk_test_*`) are browser-safe for direct client-side embedding: they carry an origin allowlist, so a key leaked to any other origin returns 403 instead of working. Mint either at `roxyapi.com/account`.
 
 For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from the CDN. Subresource Integrity hashes are available via the jsDelivr SRI API for any pinned version.
 </details>
@@ -781,11 +808,11 @@ For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from
 Semver. Pre-1.0, minor bumps may include breaking changes (we will note them in the changelog). Patch bumps are always backwards-compatible. Pin a concrete version in production code:
 
 ```bash
-npm install @roxyapi/ui@0.1.x
+npm install @roxyapi/ui@0.8.x
 ```
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.1.5/dist/cdn/roxy-ui.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.8.0/dist/cdn/roxy-ui.js"></script>
 ```
 
 The `@latest` URL on this page is for paste-friendly marketing; production code should pin.

package/THEMING.md

@@ -1,6 +1,6 @@
 # Theming Roxy UI
 
-Every Roxy UI component reads its colors, fonts, spacing, and motion from a single set of CSS custom properties on `:host`. Override them at `:root` to brand the whole library, or scope to one element to skin a single component.
+Every Roxy UI component reads its colors, fonts, spacing, and motion from a single set of `--roxy-*` CSS custom properties. Override them at `:root` to brand the whole library, or scope to one element to skin a single component. Custom properties inherit through the Shadow DOM boundary, so a value set on `:root` or any light-DOM ancestor reaches every component. The CDN bundle auto-loads the token defaults; your `:root` overrides always win over them.
 
 ## Token reference
 
@@ -99,18 +99,20 @@ roxy-natal-chart {
 
 ### Dark mode
 
-Three opt-in mechanisms work out of the box.
+Three opt-in mechanisms work out of the box. The CDN bundle auto-loads the tokens, so all three work from one script tag; on the npm path the full `@roxyapi/ui` import pulls the same tokens in.
 
 ```css
 /* System preference: nothing to do */
 
-/* data-theme on the document */
+/* data-theme on the document, an ancestor, or the element itself */
 :root[data-theme='dark'] { /* automatic */ }
 
-/* Tailwind dark class on an ancestor */
-.dark roxy-natal-chart { /* automatic */ }
+/* Tailwind dark class on the document, an ancestor, or the element itself */
+.dark { /* automatic */ }
 ```
 
+Tokens set on the `:root` / `.dark` / `[data-theme]` light-DOM element inherit through the shadow boundary into every component, so a `.dark` class anywhere above a component themes it. Per-element scope works too: `<roxy-natal-chart data-theme="dark">` runs one chart in dark on an otherwise light page.
+
 ### Map Tailwind tokens
 
 Tailwind users can map our tokens to theirs in five lines of `globals.css`. Pick the syntax that matches your Tailwind version.