@kerne/react 1.1.0 → 1.3.0

package/README.md

@@ -81,6 +81,68 @@ const { openCheckout } = useCheckout();
 const { openPortal } = usePortal();
 ```
 
+## Prebuilt UI
+
+`@kerne/react/ui` ships full screens - sign-in/up, account management, pricing table, usage meters, checkout result - accessible and themeable out of the box, for when you don't want to build auth/billing UI by hand.
+
+```tsx
+import { LoginForm, UserButton, PricingTable } from '@kerne/react/ui';
+
+<LoginForm appearance={{ surface: 'card' }} />
+<UserButton items={[{ label: 'Settings', href: '/settings' }]} />
+<PricingTable product="pro">
+  <PricingTable.Header headline="Pricing that grows with you" />
+  <PricingTable.LabelSwitch />
+  <PricingTable.Plans featuredSlug="scale" featuredBadge="Recommended" />
+</PricingTable>
+```
+
+Every component takes an `appearance` prop - `primaryColor` alone derives a matched hover state, label color, and focus ring (WCAG-checked), or set `fontFamily`/`radius`/`controlHeight`/`theme` individually:
+
+```tsx
+<LoginForm
+  appearance={{
+    primaryColor: '#6d5ef5',
+    fontFamily: '"Plus Jakarta Sans", -apple-system, sans-serif',
+    radius: '12px',
+  }}
+/>
+```
+
+The unstyled default (system font, neutral gray) is deliberate - these components land inside someone else's product, so a saturated default would clash with every host they meet. The theming above is the mechanism to get a distinctive look for a single tenant, or your own hosted portal.
+
+There is no `styles.css` to import or override - theming is exclusively `appearance` (per component) or the global `--kerne-*` CSS custom properties above; the stylesheet itself is injected at runtime rather than shipped as a file, which is what keeps drop-in install possible. Known limitation: under a strict CSP `style-src` (no `'unsafe-inline'`), that runtime injection is blocked and the components render unstyled - there's no fix for this today, only the `--kerne-*` variables to compensate.
+
+If your own app needs the default palette's raw values (to match it in your own stylesheet, say) rather than reading them off the rendered page, import `defaultTokens` instead of hand-copying hex codes - it's the same values the injected stylesheet uses, so it can't drift from what actually renders:
+
+```tsx
+import { defaultTokens } from '@kerne/react/ui';
+
+defaultTokens.light['primary']; // '#16171a'
+defaultTokens.dark['primary']; // '#f0f1f3'
+```
+
+Every string these components render - labels, placeholders, error messages - comes from `localization`. A French pack ships as `fr`:
+
+```tsx
+import { fr } from '@kerne/react/ui';
+
+<KerneProvider appId="..." localization={fr}>
+  <AuthFlow />
+</KerneProvider>;
+```
+
+Override just a few strings on top of a pack with `mergeLocalization`:
+
+```tsx
+import { fr, mergeLocalization } from '@kerne/react/ui';
+
+<KerneProvider
+  appId="..."
+  localization={mergeLocalization({ common: { email: 'Adresse professionnelle' } }, fr)}
+/>;
+```
+
 ## Core Hooks
 
 - `useAuth`: login, signup, logout, password reset, email verification, cross-origin session handoff (`redirectWithSession` - for an app hosting login on a different origin, e.g. a portal).