@blocklet/payment-react 1.20.5 → 1.20.6

package/docs/components.md

@@ -1,95 +1,122 @@
 # Components
 
-The `@blocklet/payment-react` library provides a comprehensive suite of pre-built React components designed to accelerate the development of payment, subscription, and donation features. These components are organized into logical categories to help you find the right tool for your specific use case, from high-level, all-in-one solutions to granular UI building blocks.
+The `@blocklet/payment-react` library offers a comprehensive suite of pre-built React components designed to accelerate the development of payment, subscription, and donation features. These components are categorized to help you find the right tool for the job, whether you need a complete drop-in solution or fine-grained UI elements to build a custom experience.
 
-All components are designed to be composable and customizable, ensuring they can fit seamlessly into your application's design and logic.
+All components are designed to work seamlessly within the `PaymentProvider` context, which handles state management and API communication.
 
-### Component Architecture
+## Component Architecture
 
-The components are structured into distinct categories based on their functionality. This modular approach allows you to import only what you need and gives you a clear path for building your payment interfaces.
+The following diagram illustrates how the high-level components typically interact. User-facing components like `CheckoutTable` or `CheckoutDonate` act as entry points, which then utilize the core `CheckoutForm` to handle the final payment processing.
 
 ```d2
 direction: down
 
-"@blocklet/payment-react": {
-  shape: package
-  
-  "Checkout Components": {
-    tooltip: "High-level components for complete payment flows"
-    "CheckoutForm": {}
-    "CheckoutTable": {}
-    "CheckoutDonate": {}
-  }
+User: {
+  shape: c4-person
+}
 
-  "UI Components": {
-    tooltip: "Granular building blocks for custom UIs"
-    "PricingTable": {}
-    "AddressForm": {}
-    "PaymentSummary": {}
+PaymentProvider-Context: {
+  label: "PaymentProvider Context"
+  shape: rectangle
+  style: {
+    stroke: "#888"
+    stroke-width: 2
+    stroke-dash: 4
   }
 
-  "Business Logic Components": {
-    tooltip: "Components for specific business scenarios"
-    "ResumeSubscription": {}
-    "OverdueInvoicePayment": {}
-    "AutoTopup": {}
+  Entry-Points: {
+    label: "High-Level Components"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
   }
 
-  "History Components": {
-    tooltip: "Components for displaying historical data"
-    "CustomerInvoiceList": {}
-    "CustomerPaymentList": {}
-    "CreditGrantsList": {}
+  Core-Processor: {
+    label: "Core Payment Processor"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
   }
 }
+
+User -> PaymentProvider-Context.Entry-Points.CheckoutTable: "Selects a plan"
+User -> PaymentProvider-Context.Entry-Points.CheckoutDonate: "Makes a donation"
+PaymentProvider-Context.Entry-Points.CheckoutTable -> PaymentProvider-Context.Core-Processor.CheckoutForm: "Initiates checkout"
+PaymentProvider-Context.Entry-Points.CheckoutDonate -> PaymentProvider-Context.Core-Processor.CheckoutForm: "Initiates checkout"
 ```
 
-### Provider Requirements
+## Component Categories
 
-A critical concept to understand is that almost all components in this library must be wrapped within a `PaymentProvider` to function correctly. This provider supplies the necessary context, such as the user session and API connection details. Specific components, like `CheckoutDonate`, require an additional `DonateProvider`.
+Explore our component categories to find the building blocks you need.
 
-Before using any components, ensure your application is set up with the required context providers.
+### Checkout Components
 
-```tsx
-import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
-// This is your application's custom hook for session management
-import { useSessionContext } from '../hooks/session'; 
+These are high-level components that provide complete, out-of-the-box payment experiences. Use them as the primary entry points for your payment flows.
 
-function App() {
-  // Fetch session and connectApi from your application's context.
-  const { session, connectApi } = useSessionContext();
+<x-cards>
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    The primary component for handling payment links and checkout sessions.
+  </x-card>
+  <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
+    Renders a complete pricing table and handles the checkout flow.
+  </x-card>
+  <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
+    Implement donation functionality with this flexible component.
+  </x-card>
+</x-cards>
 
-  return (
-    // The PaymentProvider wraps all components that need payment context
-    <PaymentProvider session={session} connect={connectApi}>
-      {/* Now, components like CheckoutForm can be used */}
-      <CheckoutForm id="plink_xxx" mode="inline" />
-    </PaymentProvider>
-  );
-}
-```
+### UI Components
 
-In the examples throughout this documentation, `useSessionContext` is a placeholder for your application's own hook for managing user sessions. For a complete guide on how to set up the `PaymentProvider` and create a session context, please refer to the [PaymentProvider](./providers-payment-provider.md) documentation.
+A collection of granular components for building custom payment forms and displays. Combine these blocks to create a user interface that perfectly matches your application's design.
 
-## Component Categories
+<x-cards>
+  <x-card data-title="PricingTable" data-icon="lucide:layout-list" data-href="/components/ui/pricing-table">
+    Display subscription plans and pricing options in a structured table.
+  </x-card>
+  <x-card data-title="PaymentSummary" data-icon="lucide:receipt" data-href="/components/ui/payment-summary">
+    Show a detailed summary of an order, including line items and totals.
+  </x-card>
+  <x-card data-title="Form Elements" data-icon="lucide:pencil-ruler" data-href="/components/ui/form-elements">
+    A collection of inputs for building custom payment and contact forms.
+  </x-card>
+</x-cards>
 
-Dive into the component categories to find the tools you need for your project. Each section provides detailed documentation and usage examples.
+### Business Logic Components
 
-<x-cards data-columns="2">
-  <x-card data-title="Checkout Components" data-icon="lucide:shopping-cart" data-href="/components/checkout">
-    High-level components that encapsulate entire payment flows. The fastest way to integrate standard checkouts, pricing plan selections, and donation widgets.
-  </x-card>
-  <x-card data-title="UI Components" data-icon="lucide:layout-template" data-href="/components/ui">
-    Granular building blocks for creating custom interfaces, including forms, selectors, and display elements like `PricingTable` and `PaymentSummary`.
+Specialized components designed to handle complex business workflows, such as managing overdue invoices, resuming subscriptions, and configuring automatic credit top-ups.
+
+<x-cards>
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    Handle the payment of overdue invoices for a customer or subscription.
   </x-card>
-  <x-card data-title="Business Logic Components" data-icon="lucide:briefcase" data-href="/components/business">
-    Handle specific, complex business scenarios like resuming subscriptions, paying overdue invoices, or configuring automatic credit top-ups.
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    Allow users to resume a canceled subscription with ease.
   </x-card>
-  <x-card data-title="History Components" data-icon="lucide:history" data-href="/components/history">
-    Display historical user data such as past invoices, payment lists, and credit grant histories for account management pages.
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:battery-charging" data-href="/components/business/auto-topup">
+    Manage and configure automatic credit top-up functionality.
   </x-card>
 </x-cards>
 
-## Next Steps
+### History Components
+
+Display historical payment and credit data to your users. These components make it easy to render lists of invoices, payments, and credit transactions.
 
-Now that you have an overview of the component categories, you can explore the specific documentation for the components that fit your needs. If you're looking for the fastest integration path, we recommend starting with the [Checkout Components](./components-checkout.md).
+<x-cards>
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:history" data-href="/components/history/invoice-list">
+    Render a list of a customer's invoices with details and status.
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:landmark" data-href="/components/history/payment-list">
+    Display a customer's payment history, including transaction details.
+  </x-card>
+  <x-card data-title="CreditGrantsList" data-icon="lucide:award" data-href="/components/history/credit-grants-list">
+    Show a list of credit grants, including status and remaining amounts.
+  </x-card>
+</x-cards>

package/docs/getting-started.md

@@ -1,111 +1,84 @@
 # Getting Started
 
-This guide provides a step-by-step walkthrough to get you up and running with `@blocklet/payment-react`. You will learn how to install the library, set up the essential `PaymentProvider`, and render your first payment form using the `CheckoutForm` component.
+This guide will walk you through the essential steps to install `@blocklet/payment-react` and integrate a basic, functional payment form into your application. In just a few minutes, you'll have a working checkout experience.
 
-## 1. Installation
+## Step 1: Installation
 
 First, add the library to your project using npm or your preferred package manager.
 
-```bash
+```bash Installation Command icon=lucide:terminal
 npm install @blocklet/payment-react
 ```
 
-## 2. Set up PaymentProvider
+## Step 2: Set Up the PaymentProvider
 
-Most components in `@blocklet/payment-react` require access to payment context, such as user session information and API configuration. The `PaymentProvider` component provides this context to all its children. You should wrap it around the root of your application or at least the section that handles payments.
+Most components in this library require access to a shared payment context. The `PaymentProvider` component provides this context and must be placed at the root of your application or component tree where payments will be handled.
 
-To supply the necessary `session` and `connectApi` props, you should create a local session context using `@arcblock/did-connect-react`. This allows you to access authentication state throughout your app.
+It requires a `session` object and a `connect` API function from your application's authentication context to work correctly.
 
-For a detailed guide on creating your `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
-
-Once your context is set up, you can use it like this:
-
-```tsx
+```tsx App.tsx icon=logos:react
 import { PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from '../path/to/your/session-context'; // Your local session context
+// This is a placeholder for your app's authentication context hook.
+// It should return the current user session and an API connector.
+import { useSessionContext } from './contexts/session'; 
 
-function App() {
+function App({ children }) {
   const { session, connectApi } = useSessionContext();
 
   return (
     <PaymentProvider session={session} connect={connectApi}>
       {/* Your payment components will go here */}
+      {children}
     </PaymentProvider>
   );
 }
 ```
 
-The relationship between the provider and the components it wraps can be visualized as follows:
-
-```d2
-direction: down
-
-"Your App": {
-  "PaymentProvider": {
-    style: { fill: "#dbeafe" }
-    "CheckoutForm": {
-      label: "Renders the payment UI"
-      style: { fill: "#ede9fe" }
-    }
-    "Other Components": {
-      label: "e.g., CustomerInvoiceList"
-      style: { fill: "#ede9fe" }
-    }
-  }
-}
+> For detailed information on setting up your session context and for advanced `PaymentProvider` configurations, please see the [PaymentProvider documentation](./providers-payment-provider.md).
 
-"Your App.PaymentProvider" -> "Your App.PaymentProvider.CheckoutForm": "Provides context (session, API)"
-"Your App.PaymentProvider" -> "Your App.PaymentProvider.Other Components": "Provides context (session, API)"
-```
+## Step 3: Add a CheckoutForm
 
-## 3. Add a Checkout Form
+The `CheckoutForm` is the primary component for rendering a payment flow. It can handle both one-time payments and subscriptions initiated from a Payment Link.
 
-The `CheckoutForm` is the primary component for building a payment flow. It renders a complete payment interface based on a `paymentLink` ID (prefixed with `plink_`) or a `checkoutSession` ID (prefixed with `cs_`) that you create in your payment service backend.
+To use it, simply place it inside the `PaymentProvider` and pass the required `id` of a Payment Link (`plink_...`) or a Checkout Session (`cs_...`).
 
-## 4. Complete Example
+## Complete Example
 
-This example combines the `PaymentProvider` and `CheckoutForm` to create a minimal, functional payment page. It uses the `useSessionContext` hook to provide the necessary authentication context.
+Here is a complete, minimal example that combines the steps above. You can use this code as a starting point for your integration.
 
-```tsx
-import React from 'react';
+```tsx PaymentPage.tsx icon=logos:react
 import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// This is a placeholder for your app's authentication context hook.
+import { useSessionContext } from './contexts/session'; 
 
-// This import points to your local session context implementation.
-// For setup details, see the PaymentProvider documentation.
-import { useSessionContext } from '../path/to/your/session-context';
-
-function MyPaymentPage() {
+function PaymentPage() {
   const { session, connectApi } = useSessionContext();
 
-  // It's good practice to ensure the session is loaded before rendering payment components.
-  if (!session || !session.user) {
-    return <div>Loading user session...</div>;
-  }
+  // A Payment Link ID is generated from your Payment Kit dashboard.
+  const paymentLinkId = 'plink_xxx'; 
 
   return (
     <PaymentProvider session={session} connect={connectApi}>
       <CheckoutForm 
-        id="plink_xxx" // IMPORTANT: Replace with your actual Payment Link ID
-        mode="inline"  // Embeds the form directly in your UI
+        id={paymentLinkId}
+        mode="inline" // Embeds the form directly into your page
         showCheckoutSummary={true}
-        onChange={(state) => console.log('Checkout State:', state)}
-        onPaid={() => alert('Payment Successful!')}
-        onError={(err) => alert(`Payment Failed: ${err.message}`)}
+        onChange={(state) => console.log('Checkout State Changed:', state)}
+        onPaid={(result) => console.log('Payment Successful:', result)}
       />
     </PaymentProvider>
   );
 }
 
-export default MyPaymentPage;
+export default PaymentPage;
 ```
 
-In this example:
-- We wrap `CheckoutForm` with `PaymentProvider` to provide the necessary context, obtained from our `useSessionContext` hook.
-- The `id` prop is set to a Payment Link ID. This is **required**.
-- `mode="inline"` renders the form within the current page flow.
-- `showCheckoutSummary={true}` displays a summary of what the user is paying for.
-- The `onChange`, `onPaid`, and `onError` callbacks allow you to monitor and react to the state of the checkout process.
+With this setup, the `CheckoutForm` will render a complete payment UI, handle user input, and process the transaction seamlessly.
+
+## Next Steps
 
-## 5. Next Steps
+Congratulations! You've successfully integrated your first payment form. Now you're ready to explore more advanced features and components.
 
-You have now successfully integrated a basic payment form. To learn more about configuring the context for your payment components, see the [Providers](./providers.md) section. To explore the full range of available UI and business logic components, head over to the [Components](./components.md) documentation.
+- **[CheckoutForm](./components-checkout-checkout-form.md)**: Dive deeper into the `CheckoutForm` props and customization options.
+- **[Providers](./providers.md)**: Learn more about the context providers that power the library.
+- **[Components](./components.md)**: Discover the full range of UI and business logic components available.

package/docs/guides-theming.md

@@ -1,80 +1,73 @@
 # Theming
 
-The `@blocklet/payment-react` library is built on Material-UI and includes a dedicated theme provider, `PaymentThemeProvider`, to ensure a consistent and polished look across all components. This guide explains how to customize the default theme to match your application's design system.
+Learn how to customize the appearance of payment components using the built-in theme provider and Material-UI theme options. The `@blocklet/payment-react` library is built on top of Material-UI, giving you extensive control over the look and feel of your payment flows.
 
-## `PaymentThemeProvider`
+## Overview of `PaymentThemeProvider`
 
-Most components in the library, such as `CheckoutForm`, are internally wrapped with `PaymentThemeProvider`. This provider establishes a cohesive visual foundation by extending ArcBlock's base theme with styles tailored for payment UIs. It defines a specific color palette, typography scale, and default styles for various MUI components.
+The library includes a dedicated `PaymentThemeProvider` that wraps all payment components. This provider establishes a default theme that inherits from the ArcBlock UX theme (`@arcblock/ux/lib/Theme`), ensuring visual consistency within the ArcBlock ecosystem. It also adds its own customizations, such as a special `chip` color palette and style overrides for various MUI components.
 
-The theme merging process follows a clear hierarchy to combine the base theme, default payment styles, and your custom overrides.
+Here is a simplified look at how `PaymentThemeProvider` is structured:
 
-```d2
-direction: down
+```tsx src/theme/index.tsx icon=logos:react
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';
 
-"Parent MUI Theme"
+export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
+  const parentTheme = useTheme();
 
-is_ab_theme: "Is it an ArcBlock Theme?" {
-  shape: diamond
-}
-
-"Parent MUI Theme" -> is_ab_theme
+  const mergeTheme = useMemo(() => {
+    // Start with the base blocklet theme
+    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();
 
-use_parent: "Use Parent Theme as Base"
-create_new: "Create New BlockletTheme as Base"
+    // Merge our custom payment theme options
+    let paymentThemeOptions = deepmerge(blockletTheme, {
+      // Custom palette extensions, e.g., for chips
+      palette: {
+        chip: { /* ... */ },
+      },
+      // Custom component style overrides
+      components: {
+        MuiButton: { /* ... */ },
+        MuiOutlinedInput: { /* ... */ },
+        // ... other components
+      },
+    });
 
-is_ab_theme -> use_parent: "Yes"
-is_ab_theme -> create_new: "No"
+    // Merge any user-provided custom theme
+    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);
 
-base_theme: "Base Theme"
-use_parent -> base_theme
-create_new -> base_theme
+    return createTheme(paymentThemeOptions);
+  }, [parentTheme, customTheme]);
 
-default_payment_styles: "Default Payment Component Styles"
-
-merge1: "Merge with Base Theme" {
-  shape: oval
+  return (
+    <ThemeProvider theme={mergeTheme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  );
 }
-
-base_theme -> merge1
-default_payment_styles -> merge1
-
-user_customizations: "User's Customizations (from 'theme' prop)"
-
-final_theme: "Final Merged Theme"
-
-merge1 -> final_theme
-user_customizations -> final_theme
 ```
 
-## Customization Methods
-
-You can customize the theme by passing a `theme` prop to payment components like `CheckoutForm`. This prop accepts a `PaymentThemeOptions` object, offering two primary methods for customization.
-
-In the following examples, `useSessionContext` is a hook from your local session management setup. For more details on setting up the required context, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+## Customizing Component Styles
 
-### 1. Overriding Component Styles
+Since version 1.14.22, you can easily customize the theme for individual payment components by passing a `theme` prop. This prop accepts a Material-UI `ThemeOptions` object, giving you two primary ways to apply custom styles.
 
-To modify the default styles of underlying Material-UI components, provide a `components` object in your theme configuration. This object follows the standard MUI `styleOverrides` structure and will be deeply merged with the default payment theme.
+### 1. Using `styleOverrides`
 
-This method is ideal for making consistent changes to components like buttons, inputs, and chips across the payment UI.
+For deep, structural changes, you can override the styles for specific Material-UI components within the payment component's scope. This is the standard MUI way of theming.
 
-**Example: Changing the Primary Button Color**
-
-```tsx
+```tsx Customizing the Primary Button icon=logos:react
 import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
-import { useSessionContext } from '/path/to/your/session/context'; // This path is specific to your project
+import { useSessionContext } from '@/hooks/session-context'; // Assuming session context is defined here
 
-function CustomStyledForm() {
+function CustomStyledCheckout() {
   const { session, connectApi } = useSessionContext();
 
-  if (!session) {
-    return <div>Loading session...</div>;
-  }
-
   return (
     <PaymentProvider session={session} connect={connectApi}>
       <CheckoutForm
         id="plink_xxx"
+        onChange={console.info}
         theme={{
           components: {
             MuiButton: {
@@ -96,34 +89,28 @@ function CustomStyledForm() {
 }
 ```
 
-### 2. Using the `sx` Prop for Targeted Overrides
+In this example, we target the primary contained button (`MuiButton.styleOverrides.containedPrimary`) and change its background and text color.
 
-For more specific, one-off style adjustments, you can use the `sx` property within the `theme` object. This applies CSS directly to the component's wrapper element, allowing you to use class selectors to target nested elements.
+### 2. Using the `sx` Prop
 
-This approach is useful when you need to style a specific element that doesn't have a direct `styleOverrides` entry or when you want to apply a quick fix without altering the global theme configuration.
+For quick, targeted CSS changes, you can pass an `sx` object within the `theme` prop. This allows you to use CSS selectors to target specific elements within the component.
 
-**Example: Customizing the Submit Button**
-
-```tsx
+```tsx Customizing with the sx Prop icon=logos:react
 import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
-import { useSessionContext } from '/path/to/your/session/context'; // This path is specific to your project
+import { useSessionContext } from '@/hooks/session-context';
 
-function TargetedStyleForm() {
+function SxStyledCheckout() {
   const { session, connectApi } = useSessionContext();
 
-  if (!session) {
-    return <div>Loading session...</div>;
-  }
-
   return (
     <PaymentProvider session={session} connect={connectApi}>
       <CheckoutForm
         id="plink_xxx"
         showCheckoutSummary={false}
+        onChange={console.info}
         theme={{
           sx: {
-            // Note: The specific class name may vary.
-            // Inspect the element in your browser to find the correct selector.
+            // Target the submit button by its specific class name
             '.cko-submit-button': {
               backgroundColor: '#1DC1C7',
               color: '#fff',
@@ -137,39 +124,90 @@ function TargetedStyleForm() {
     </PaymentProvider>
   );
 }
+
 ```
 
+This method is useful when you need to override a style that isn't easily accessible through the standard component style overrides.
+
 ## Understanding the Default Theme
 
-To customize effectively, it's helpful to know what the default theme provides. The `PaymentThemeProvider` includes several key customizations.
+The default theme is built upon a system of CSS variables (Design Tokens) for colors, spacing, and typography, allowing for consistent styling across light and dark modes.
+
+### Color Palette
 
-### Custom Palette Extensions
+The theme extends the standard Material-UI palette with a custom `chip` object to style status indicators. You can override these colors in your custom theme.
 
-The theme extends the standard MUI palette with additional colors for specific UI elements.
+```ts src/theme/types.ts icon=mdi:language-typescript
+declare module '@mui/material/styles' {
+  interface Palette {
+    chip: {
+      success: { text: string; background: string; border: string; };
+      default: { text: string; background: string; border: string; };
+      secondary: { text: string; background: string; border: string; };
+      error: { text: string; background: string; border: string; };
+      warning: { text: string; background: string; border: string; };
+      info: { text: string; background: string; border: string; };
+    };
+  }
+  // ... PaletteOptions definition
+}
+```
 
-| Palette Key            | Description                                                                                                                                      |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `palette.chip`         | An object containing `text`, `background`, and `border` colors for different chip statuses: `success`, `default`, `secondary`, `error`, `warning`, and `info`. |
-| `palette.text.lighter` | A lighter text color, typically mapped to `grey[400]`.                                                                                           |
-| `palette.text.link`    | The color for hyperlink text, mapped to `secondary.main`.                                                                                        |
+### Design Tokens (CSS Variables)
 
-### Global CSS Classes
+For advanced, global customization, you can override the CSS variables that define the theme. These variables are defined for both light (`:root`) and dark (`[data-theme='dark']`) modes.
 
-The theme injects several global utility classes via `MuiCssBaseline` that you can use for styling consistency.
+Here are some of the key variables you can target:
 
-- **`.base-card`**: Applies standard padding, border-radius, background, border, and shadow for card-like containers.
-- **`.base-label`**: A standard style for form labels and other descriptive text.
+```css src/theme/index.css icon=logos:css-3
+:root {
+  /* Light Theme */
+  --backgrounds-bg-base: #ffffff;
+  --backgrounds-bg-interactive: #3b82f6;
+  --foregrounds-fg-base: #030712;
+  --foregrounds-fg-interactive: #3b82f6;
+  --stroke-border-base: #eff1f5;
+  --radius-m: 0.5rem; /* 8px */
+}
 
-### CSS Variables for Light & Dark Modes
+[data-theme='dark'] {
+  /* Dark Theme */
+  --backgrounds-bg-base: #1b1b1f;
+  --backgrounds-bg-interactive: #60a5fa;
+  --foregrounds-fg-base: #edeef0;
+  --foregrounds-fg-interactive: #60a5fa;
+  --stroke-border-base: #2e3035;
+  --radius-m: 0.5rem;
+}
+```
 
-The entire color system is built upon a set of CSS variables that automatically adapt to light and dark modes. While you can override component styles directly, understanding this foundation helps explain the theme's adaptability.
+Overriding these variables in your global stylesheet will apply changes across all `@blocklet/payment-react` components.
+
+### Typography
+
+The default typography settings can be found in `src/theme/typography.ts`. You can override any of these settings in your custom theme to match your application's typography.
+
+```ts src/theme/typography.ts icon=mdi:language-typescript
+export const typography = {
+  h1: {
+    fontSize: '1.5rem',
+    lineHeight: 1.2,
+    fontWeight: 800,
+  },
+  body1: {
+    fontSize: '0.875rem',
+    lineHeight: 1.75,
+  },
+  // ... other typography settings
+};
+```
 
-| Variable                 | Light Mode Value | Dark Mode Value |
-| ------------------------ | ---------------- | --------------- |
-| `--backgrounds-bg-base`  | `#ffffff`        | `#1b1b1f`       |
-| `--foregrounds-fg-base`  | `#030712`        | `#edeef0`       |
-| `--stroke-border-base`   | `#eff1f5`        | `#2e3035`       |
+By understanding these layers of customization, you can seamlessly integrate the payment components into your application with a consistent and polished design.
 
 ---
 
-Now that you understand how to customize the visual appearance of components, you may want to explore the utility functions that can help with data formatting and API requests. For more information, see the [Utilities](./guides-utilities.md) guide.
+Next, explore the various utility functions that can help you with tasks like data caching and date formatting.
+
+<x-card data-title="Next: Utilities" data-icon="lucide:wrench" data-href="/guides/utilities" data-cta="Read More">
+  A reference for utility functions provided by the library, including cached requests, and date formatting.
+</x-card>