@roxyapi/ui 0.0.1 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md
+
+This file teaches AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI) how to use Roxy UI when integrating RoxyAPI into a project.
+
+## Identity
+
+Roxy UI is the official web component library for the RoxyAPI catalog. Components and helpers cover Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, with the location helper for geocoding. New endpoints regenerate component types automatically.
+
+## Decision tree for picking a component
+
+Use the table below. Match the user request against the endpoint, render the matching component.
+
+<!-- BEGIN:COMPONENTS -->
+| Element | Domain | Endpoint(s) | What it renders |
+|---|---|---|---|
+| `<roxy-natal-chart>` | Western | POST /astrology/natal-chart | Natal chart wheel with planet glyphs and aspect lines |
+| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly} | Daily, weekly, or monthly horoscope card |
+| `<roxy-synastry-chart>` | Western | POST /astrology/synastry | Dual-wheel synastry with inter-aspects table |
+| `<roxy-compatibility-card>` | Cross | POST /astrology/compatibility-score, /numerology/compatibility, /biorhythm/compatibility | Score card with category breakdown |
+| `<roxy-moon-phase>` | Western | GET /astrology/moon-phase/{current,upcoming,calendar/...} | Moon phase card and calendar |
+| `<roxy-vedic-kundli>` | Vedic | POST /vedic-astrology/birth-chart | South or North Indian kundli |
+| `<roxy-panchang-table>` | Vedic | POST /vedic-astrology/panchang/{basic,detailed} | 15+ muhurtas in detailed mode |
+| `<roxy-dasha-timeline>` | Vedic | POST /vedic-astrology/dasha/{current,major,sub/...} | Vimshottari mahadasha + antardasha + pratyantardasha |
+| `<roxy-dosha-card>` | Vedic | POST /vedic-astrology/dosha/{manglik,kalsarpa,sadhesati} | Presence, severity, remedies, scoped effects |
+| `<roxy-guna-milan>` | Vedic | POST /vedic-astrology/compatibility | 36-point Ashtakoota with eight sub-scores |
+| `<roxy-kp-planets-table>` | Vedic (KP) | POST /vedic-astrology/kp/planets | Sub-lord and sub-sub-lord columns |
+| `<roxy-numerology-card>` | Numerology | POST /numerology/{life-path,expression,personal-year,chart} | Life path, expression, personal year, full chart |
+| `<roxy-tarot-card>` | Tarot | GET /tarot/cards/{id}, POST /tarot/daily | Single card with upright and reversed flip |
+| `<roxy-tarot-spread>` | Tarot | POST /tarot/spreads/{three-card,celtic-cross,love}, /tarot/yes-no, /tarot/draw | Spreads with positions and reading |
+| `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
+| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram with trigrams, judgment, image, changing lines |
+| `<roxy-endpoint-form>` | Helper | Any endpoint via x-roxy-ui hints | Schema-driven form, emits roxy-submit |
+| `<roxy-location-search>` | Helper | GET /location/search | Debounced city search input, emits roxy-location-select |
+| `<roxy-data>` | Helper | Any response shape | Generic fallback renderer for unknown shapes |
+<!-- END:COMPONENTS -->
+
+## Integration patterns
+
+### Pattern 1: vanilla HTML, no build step
+
+```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">
+	const res = await fetch('https://roxyapi.com/api/v2/astrology/natal-chart', {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', 'X-API-Key': 'roxy_xxx' },
+		body: JSON.stringify({
+			date: '1990-01-15',
+			time: '14:30:00',
+			latitude: 28.6139,
+			longitude: 77.209,
+			timezone: 5.5,
+		}),
+	});
+	const data = await res.json();
+	document.getElementById('chart').data = data;
+</script>
+```
+
+### Pattern 2: React, with the typed SDK
+
+```tsx
+import { createRoxy } from '@roxyapi/sdk';
+import { RoxyNatalChart, RoxyLocationSearch } 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(null);
+
+	const onLocationSelect = async (e: CustomEvent<{ latitude: number; longitude: number; timezone: string }>) => {
+		const { data } = await roxy.astrology.generateNatalChart({
+			body: { date: '1990-01-15', time: '14:30:00', ...e.detail },
+		});
+		setChart(data);
+	};
+
+	return (
+		<div>
+			<RoxyLocationSearch onroxy-location-select={onLocationSelect} />
+			{chart && <RoxyNatalChart data={chart} />}
+		</div>
+	);
+}
+```
+
+### 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.
+
+```html
+<roxy-endpoint-form
+	data-endpoint="vedic-astrology/birth-chart"
+	method="POST"
+	submit-label="Generate kundli"
+></roxy-endpoint-form>
+
+<script type="module">
+	const form = document.querySelector('roxy-endpoint-form');
+	form.addEventListener('roxy-submit', async (e) => {
+		const { endpoint, values } = e.detail;
+		const res = await fetch(`https://roxyapi.com/api/v2/${endpoint}`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json', 'X-API-Key': 'roxy_xxx' },
+			body: JSON.stringify(values),
+		});
+		const kundli = await res.json();
+		document.querySelector('roxy-vedic-kundli').data = kundli;
+	});
+</script>
+```
+
+### Pattern 4: widgets auto-mount (no JavaScript wiring)
+
+Use the publishable key flow for vibecoder embeds.
+
+```html
+<script
+	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js"
+	defer
+></script>
+
+<div
+	data-roxy-widget="natal-chart"
+	data-publishable-key="pk_live_xxx"
+	data-date="1990-01-15"
+	data-time="14:30:00"
+	data-latitude="28.6139"
+	data-longitude="77.209"
+	data-timezone="5.5"
+></div>
+```
+
+The auto-mount script reads `data-*` attributes, calls the matching endpoint, and renders the matching component.
+
+## Rules every agent must follow
+
+- Always call `/location/search` first before any chart endpoint that takes latitude, longitude, or timezone. Use `<roxy-location-search>` for the input UI.
+- Pass the response object directly. Components are stateless; they do not fetch internally except for `<roxy-location-search>`, `<roxy-endpoint-form>`, and the widgets auto-mount script.
+- Use the typed SDK from `@roxyapi/sdk` so prop shapes match the spec automatically.
+- Theming is CSS custom properties on `:root` or per element. Do not write Tailwind classes inside the components; the shadow DOM ignores them.
+- Honor reduced motion. The library already respects `prefers-reduced-motion: reduce` and the `--roxy-motion-duration` variable.
+- A11y violations are CI failures. Do not paste over `role` or `aria-*` attributes; the components emit them correctly already.
+
+## 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.
+
+## What not to ship
+
+- Do not bundle `@roxyapi/ui` and `@roxyapi/ui-react` together; they are decoupled by design.
+- Use `@roxyapi/ui-react` for React projects. Use `@roxyapi/ui` directly elsewhere.
+- Do not write your own kundli component. The lifted layout in `<roxy-vedic-kundli>` is the canonical RoxyAPI render path.
+- Do not call astrology endpoints with hardcoded coordinates. Always geocode first via `<roxy-location-search>` or `roxy.location.searchCities()`.
+
+## Where to look next
+
+- Component source: `packages/ui/src/components/`
+- Sample data for every component: `apps/docs/sample-data.js`
+- Token reference: `packages/ui/THEMING.md`
+- Live preview: `bun run preview` then open `http://localhost:3001`
+- Money endpoints reference: see the RoxyAPI methodology page at `roxyapi.com/methodology`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roxy Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+<p align="center">
+	<a href="https://roxyapi.com/ui">
+		<img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/banner.png" alt="Roxy UI. Beautiful spiritual components in 30 minutes." width="100%">
+	</a>
+</p>
+
+# @roxyapi/ui
+
+[![npm](https://img.shields.io/npm/v/@roxyapi/ui)](https://www.npmjs.com/package/@roxyapi/ui)
+[![Docs](https://img.shields.io/badge/docs-roxyapi.com-blue)](https://roxyapi.com/ui)
+[![API Reference](https://img.shields.io/badge/api%20reference-roxyapi.com-blue)](https://roxyapi.com/api-reference)
+[![Pricing](https://img.shields.io/badge/pricing-roxyapi.com-blue)](https://roxyapi.com/pricing)
+
+Web components for the RoxyAPI catalog. Drop astrology, tarot, numerology, and every other RoxyAPI domain into any framework with one script tag or one npm install. Stateless components, typed responses, beautiful defaults in 30 minutes.
+
+## Why developers use Roxy UI
+
+- One API key. Charts, tables, cards, forms for every domain in the catalog.
+- Works in React, Vue, Svelte, Angular, Solid, vanilla HTML, WordPress.
+- Stateless. Caller fetches via `@roxyapi/sdk`, passes the response as `data`.
+- Theming via CSS custom properties. No Tailwind required, no class-name overrides.
+- A11y zero violations under axe-core. Keyboard navigation. Reduced-motion honored.
+- Tree-shake friendly. Tight bundle budget enforced in CI.
+
+## Start with one component
+
+Vanilla HTML. Three lines. No build step.
+
+```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@1/dist/factory.js';
+	const roxy = createRoxy(import.meta.env?.ROXY_API_KEY);
+	const { data } = await roxy.astrology.generateNatalChart({
+		body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+	});
+	document.getElementById('chart').data = data;
+</script>
+```
+
+Then add the kundli, the panchang, the dasha timeline, the tarot spread.
+
+## Install
+
+```bash
+npm install @roxyapi/ui
+# or
+bun add @roxyapi/ui
+```
+
+```ts
+import '@roxyapi/ui';
+// or per component
+import '@roxyapi/ui/components/natal-chart';
+```
+
+React users get a typed package with the same components.
+
+```bash
+npm install @roxyapi/ui-react
+```
+
+```tsx
+import { RoxyNatalChart } from '@roxyapi/ui-react';
+
+export function Chart({ data }: { data: NatalChart }) {
+	return <RoxyNatalChart data={data} />;
+}
+```
+
+## Quick start
+
+```ts
+import { createRoxy } from '@roxyapi/sdk';
+import '@roxyapi/ui';
+
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
+
+const { data: cities } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
+const { latitude, longitude, timezone } = cities.cities[0];
+
+const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
+	body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
+});
+
+document.querySelector('roxy-vedic-kundli')!.data = kundli;
+```
+
+Always call `/location/search` first. Every chart endpoint expects latitude, longitude, and timezone.
+
+## Distribution
+
+| Surface | URL |
+|---|---|
+| npm `@roxyapi/ui` | `npmjs.com/package/@roxyapi/ui` |
+| npm `@roxyapi/ui-react` | `npmjs.com/package/@roxyapi/ui-react` |
+| jsdelivr full UMD | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js` |
+| jsdelivr per-component UMD | `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` |
+| shadcn registry | `bunx shadcn add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@main/registry/{name}.json` |
+
+## Phase 1 components
+
+<!-- BEGIN:COMPONENTS -->
+| Element | Domain | Endpoint(s) | What it renders |
+|---|---|---|---|
+| `<roxy-natal-chart>` | Western | POST /astrology/natal-chart | Natal chart wheel with planet glyphs and aspect lines |
+| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly} | Daily, weekly, or monthly horoscope card |
+| `<roxy-synastry-chart>` | Western | POST /astrology/synastry | Dual-wheel synastry with inter-aspects table |
+| `<roxy-compatibility-card>` | Cross | POST /astrology/compatibility-score, /numerology/compatibility, /biorhythm/compatibility | Score card with category breakdown |
+| `<roxy-moon-phase>` | Western | GET /astrology/moon-phase/{current,upcoming,calendar/...} | Moon phase card and calendar |
+| `<roxy-vedic-kundli>` | Vedic | POST /vedic-astrology/birth-chart | South or North Indian kundli |
+| `<roxy-panchang-table>` | Vedic | POST /vedic-astrology/panchang/{basic,detailed} | 15+ muhurtas in detailed mode |
+| `<roxy-dasha-timeline>` | Vedic | POST /vedic-astrology/dasha/{current,major,sub/...} | Vimshottari mahadasha + antardasha + pratyantardasha |
+| `<roxy-dosha-card>` | Vedic | POST /vedic-astrology/dosha/{manglik,kalsarpa,sadhesati} | Presence, severity, remedies, scoped effects |
+| `<roxy-guna-milan>` | Vedic | POST /vedic-astrology/compatibility | 36-point Ashtakoota with eight sub-scores |
+| `<roxy-kp-planets-table>` | Vedic (KP) | POST /vedic-astrology/kp/planets | Sub-lord and sub-sub-lord columns |
+| `<roxy-numerology-card>` | Numerology | POST /numerology/{life-path,expression,personal-year,chart} | Life path, expression, personal year, full chart |
+| `<roxy-tarot-card>` | Tarot | GET /tarot/cards/{id}, POST /tarot/daily | Single card with upright and reversed flip |
+| `<roxy-tarot-spread>` | Tarot | POST /tarot/spreads/{three-card,celtic-cross,love}, /tarot/yes-no, /tarot/draw | Spreads with positions and reading |
+| `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
+| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram with trigrams, judgment, image, changing lines |
+| `<roxy-endpoint-form>` | Helper | Any endpoint via x-roxy-ui hints | Schema-driven form, emits roxy-submit |
+| `<roxy-location-search>` | Helper | GET /location/search | Debounced city search input, emits roxy-location-select |
+| `<roxy-data>` | Helper | Any response shape | Generic fallback renderer for unknown shapes |
+<!-- END:COMPONENTS -->
+
+## What you can build
+
+- Astrology dating apps with synastry charts and compatibility scores.
+- Kundli matching platforms with Guna Milan and Mangal Dosha checks.
+- Daily horoscope embeds for wellness, news, and lifestyle apps.
+- Tarot reading apps with daily pulls, three-card spreads, and Celtic Cross.
+- Numerology calculators with full-chart breakdowns and personal year forecasts.
+- Biorhythm dashboards with critical-day alerts.
+- I Ching apps with hexagram lookup and three-coin casting.
+- Founder hosted-app surfaces consuming the same components under brand themes.
+
+## 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](packages/ui/THEMING.md) for the full token reference.
+
+```css
+:root {
+	--roxy-accent: #6d28d9;
+	--roxy-radius-md: 12px;
+}
+
+roxy-natal-chart {
+	--roxy-accent: #ec4899;
+}
+```
+
+## Reliability
+
+- Verified astronomical calculations from Roxy Ephemeris, verified against NASA JPL Horizons.
+- Stable, versioned API. New endpoints regenerate component types automatically.
+- Consistent response formats across every domain in the catalog.
+- A11y zero violations enforced in CI.
+- Tight per-component bundle budget enforced in CI.
+- Coverage of the highest-demand endpoints across Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, plus helpers for location search and schema-driven forms.
+
+## Built for AI agents
+
+- Works with Claude Code, Cursor, Copilot, Codex, Gemini CLI.
+- Ships with `AGENTS.md` so agents know which component to render for which response.
+- Combines with the `@roxyapi/sdk` for typed prop shapes that match the OpenAPI spec.
+- Remote MCP servers per domain at `roxyapi.com/mcp/{domain}`. No local setup, runs in seconds.
+
+## Build anything, fast
+
+```bash
+git clone https://github.com/RoxyAPI/ui.git
+cd ui
+bun install
+bun run build
+bun run preview
+# http://localhost:3001
+```
+
+Three steps. Thirty minutes. See [examples](examples/) for a full vanilla HTML, React, Vue, and WordPress integration.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- [Documentation](https://roxyapi.com/ui)
+- [API reference](https://roxyapi.com/api-reference)
+- [Methodology](https://roxyapi.com/methodology)
+- [Pricing](https://roxyapi.com/pricing)
+- [Support](https://roxyapi.com/contact)

package/THEMING.md

@@ -0,0 +1,129 @@
+# 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.
+
+## Token reference
+
+### Color
+
+| Variable | Light default | Dark default | Used by |
+|---|---|---|---|
+| `--roxy-primary` | `#0f172a` | `#f8fafc` | Headings, primary text |
+| `--roxy-secondary` | `#475569` | `#94a3b8` | Subheadings, muted accents |
+| `--roxy-accent` | `#f59e0b` | `#fbbf24` | Planet glyphs, hexagram lines, focused state |
+| `--roxy-success` | `#16a34a` | `#22c55e` | Positive doshas, biorhythm peaks |
+| `--roxy-warning` | `#ea580c` | `#fb923c` | Caution states, mid severity |
+| `--roxy-danger` | `#dc2626` | `#ef4444` | Manglik present, critical days |
+| `--roxy-info` | `#0284c7` | `#38bdf8` | Informational badges |
+| `--roxy-bg` | `#ffffff` | `#0a0a0a` | Card and chart backgrounds |
+| `--roxy-fg` | `#0a0a0a` | `#fafafa` | Body text |
+| `--roxy-muted` | `#71717a` | `#a1a1aa` | Secondary text |
+| `--roxy-border` | `#e4e4e7` | `#27272a` | Wheel lines, table borders |
+| `--roxy-ring` | `rgba(245, 158, 11, 0.4)` | `rgba(251, 191, 36, 0.45)` | Focus outlines |
+
+### Typography
+
+| Variable | Default | Notes |
+|---|---|---|
+| `--roxy-font-sans` | `Geist, system-ui, ...` | Body and headings |
+| `--roxy-font-mono` | `Geist Mono, ui-monospace, ...` | Numeric tables, code |
+| `--roxy-text-xs` | `0.75rem` | Captions |
+| `--roxy-text-sm` | `0.875rem` | Body small |
+| `--roxy-text-base` | `1rem` | Body |
+| `--roxy-text-lg` | `1.125rem` | Subheading |
+| `--roxy-text-xl` | `1.5rem` | Heading |
+| `--roxy-weight-normal` | `400` | Body |
+| `--roxy-weight-bold` | `600` | Heading |
+| `--roxy-leading-tight` | `1.2` | Heading |
+| `--roxy-leading-normal` | `1.5` | Body |
+| `--roxy-tracking-tight` | `-0.02em` | Heading |
+| `--roxy-tracking-normal` | `0em` | Body |
+
+### Spacing
+
+| Variable | Default |
+|---|---|
+| `--roxy-space-xs` | `0.25rem` |
+| `--roxy-space-sm` | `0.5rem` |
+| `--roxy-space-md` | `1rem` |
+| `--roxy-space-lg` | `1.5rem` |
+| `--roxy-space-xl` | `2.5rem` |
+
+### Radius
+
+| Variable | Default |
+|---|---|
+| `--roxy-radius-sm` | `4px` |
+| `--roxy-radius-md` | `8px` |
+| `--roxy-radius-lg` | `12px` |
+| `--roxy-radius-full` | `9999px` |
+
+### Shadow
+
+| Variable | Default |
+|---|---|
+| `--roxy-shadow-sm` | `0 1px 2px rgba(0, 0, 0, 0.06)` |
+| `--roxy-shadow-md` | `0 4px 6px -1px rgba(0, 0, 0, 0.08), ...` |
+| `--roxy-shadow-lg` | `0 12px 24px -8px rgba(0, 0, 0, 0.14)` |
+
+### Motion
+
+| Variable | Default | Notes |
+|---|---|---|
+| `--roxy-motion-duration` | `200ms` | Set to `0ms` to disable transitions and entry animations |
+| `--roxy-motion-easing` | `cubic-bezier(0.4, 0, 0.2, 1)` | Standard ease |
+
+`prefers-reduced-motion: reduce` always pins duration to `0ms`. Honor this by default.
+
+## Patterns
+
+### Brand the whole library
+
+```css
+:root {
+	--roxy-accent: #6d28d9;
+	--roxy-radius-md: 12px;
+	--roxy-font-sans: 'Inter', system-ui;
+}
+```
+
+### Brand one component
+
+```css
+roxy-natal-chart {
+	--roxy-accent: #d946ef;
+	--roxy-border: #f0abfc;
+}
+```
+
+### Dark mode
+
+Three opt-in mechanisms work out of the box.
+
+```css
+/* System preference: nothing to do */
+
+/* data-theme on the document */
+:root[data-theme='dark'] { /* automatic */ }
+
+/* Tailwind dark class on an ancestor */
+.dark roxy-natal-chart { /* automatic */ }
+```
+
+### Map Tailwind tokens
+
+Tailwind users can map our tokens to theirs in five lines of `globals.css`:
+
+```css
+:root {
+	--roxy-bg: theme(colors.background);
+	--roxy-fg: theme(colors.foreground);
+	--roxy-accent: theme(colors.primary.DEFAULT);
+	--roxy-border: theme(colors.border);
+	--roxy-radius-md: theme(borderRadius.md);
+}
+```
+
+## A11y
+
+Color contrast must stay at 4.5:1 minimum against `--roxy-bg` for body text and 3:1 for large text. The defaults pass WCAG AA. Verify any custom palette with the axe Chrome extension or any contrast checker before shipping.