@blocklet/payment-react 1.19.22 → 1.20.0

package/docs/components-ui-pricing-table.md

@@ -0,0 +1,227 @@
+# PricingTable
+
+The `PricingTable` component is a flexible UI element designed to display subscription plans and pricing options in a structured, user-friendly table. It allows users to browse different plans, switch between billing cycles (e.g., monthly, yearly), select a currency, and proceed to checkout by selecting a plan.
+
+This component must be used within the context of a `PaymentProvider`, as it relies on the provider for payment settings and currency information. For detailed instructions on setting up the provider, refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+For a more integrated solution that bundles the pricing table with the complete checkout flow, consider using the higher-level [`CheckoutTable`](./components-checkout-checkout-table.md) component.
+
+```d2
+direction: down
+
+"PaymentProvider": {
+  shape: class
+  "Provides Context (Settings, Currency, etc.)"
+}
+
+"Your Application": {
+  shape: class
+  "Provides `table` data"
+  "Implements `onSelect` handler"
+}
+
+"PricingTable": {
+  shape: package
+  "Renders UI"
+  " - Billing Cycle Toggles"
+  " - Currency Selector"
+  " - Plan Cards"
+}
+
+"User": {
+  shape: person
+}
+
+"PaymentProvider" -> "PricingTable": "Provides context"
+"Your Application" -> "PricingTable": "Passes props (`table`, `onSelect`)"
+"User" -> "PricingTable": "Interacts (selects plan)"
+"PricingTable" -> "Your Application": "Triggers `onSelect(priceId, currencyId)`"
+
+```
+
+## Props
+
+The `PricingTable` component accepts the following props to customize its behavior and appearance:
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `table` | `TPricingTableExpanded` | Yes | - | An object containing the pricing table data, including a list of items (plans) to display. |
+| `onSelect` | `(priceId: string, currencyId: string) => void` | Yes | - | A callback function that is invoked when a user clicks the action button for a plan. |
+| `alignItems` | `'center' \| 'left'` | No | `'center'` | Controls the horizontal alignment of the pricing plans and controls. |
+| `mode` | `'checkout' \| 'select'` | No | `'checkout'` | Determines the behavior and text of the action button. `'checkout'` is for direct payment, while `'select'` is for plan selection. |
+| `interval` | `string` | No | `''` | The initially selected billing interval (e.g., 'month-1', 'year-1'). If empty, the first available interval is used. |
+| `hideCurrency` | `boolean` | No | `false` | If `true`, the currency selection dropdown will be hidden from the user. |
+
+## Usage Scenarios
+
+### Basic Checkout Table
+
+This is the default mode. The component displays plans with a subscription button. When a user clicks the button, the `onSelect` callback is triggered, which you can use to initiate a checkout session.
+
+```jsx
+import React from 'react';
+import PricingTable from '@blocklet/payment-react/lib/components/pricing-table';
+import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
+import { useSessionContext } from '../hooks/session'; // Your local session context hook
+
+// Assume 'myPricingTableData' is fetched from your backend and conforms to TPricingTableExpanded
+
+function MyPricingPage({ myPricingTableData }) {
+  const handleSubscription = async (priceId, currencyId) => {
+    console.log(`Starting subscription for price: ${priceId} with currency: ${currencyId}`);
+    // Add your logic to create a checkout session and redirect the user
+  };
+
+  return (
+    <PricingTable 
+      table={myPricingTableData} 
+      onSelect={handleSubscription} 
+    />
+  );
+}
+
+// Your component must be wrapped in PaymentProvider
+function AppWithPayment() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session.user) {
+    return <button onClick={connectApi}>Connect Wallet</button>;
+  }
+
+  // Assume 'myPricingTableData' is available here
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <MyPricingPage myPricingTableData={myPricingTableData} />
+    </PaymentProvider>
+  );
+}
+```
+
+**Note:** The `useSessionContext` hook should be set up in your application to provide session information. For a detailed guide on how to configure this and the `PaymentProvider`, please see the [PaymentProvider documentation](./providers-payment-provider.md).
+
+### Plan Selection Mode
+
+By setting `mode='select'`, the component can be used as part of a larger form where the user selects a plan before proceeding. The action button text changes to "Select" or "Selected", and selected items are highlighted with a border.
+
+In this mode, you need to manage the selected plan in your parent component's state and pass the `is_selected` property down to the `table` items.
+
+```jsx
+import React, { useState, useMemo } from 'react';
+import PricingTable from '@blocklet/payment-react/lib/components/pricing-table';
+import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
+import { useSessionContext } from '../hooks/session'; // Your local session context hook
+
+function PlanSelectionForm({ myPricingTableData }) {
+  const [selectedPriceId, setSelectedPriceId] = useState(null);
+
+  const handlePlanSelect = (priceId, currencyId) => {
+    setSelectedPriceId(priceId);
+    console.log(`User selected price: ${priceId} in currency: ${currencyId}`);
+  };
+
+  // Add is_selected property to the items based on the current state
+  const tableDataWithSelection = useMemo(() => ({
+    ...myPricingTableData,
+    items: myPricingTableData.items.map(item => ({
+      ...item,
+      is_selected: item.price_id === selectedPriceId,
+    })),
+  }), [myPricingTableData, selectedPriceId]);
+
+  return (
+    <div>
+      <h2>Choose Your Plan</h2>
+      <PricingTable 
+        table={tableDataWithSelection} 
+        onSelect={handlePlanSelect} 
+        mode="select"
+        alignItems="left"
+      />
+      <button disabled={!selectedPriceId}>Continue to Checkout</button>
+    </div>
+  );
+}
+
+// Your component must be wrapped in PaymentProvider
+function AppWithPaymentSelection() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session.user) {
+    return <button onClick={connectApi}>Connect Wallet</button>;
+  }
+  
+  // Assume 'myPricingTableData' is available here
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <PlanSelectionForm myPricingTableData={myPricingTableData} />
+    </PaymentProvider>
+  );
+}
+```
+
+## Data Structure for `table` prop
+
+The `table` prop expects an object with a specific structure, `TPricingTableExpanded`. Here's a simplified overview of what it contains:
+
+- **`id`**: A unique identifier for the pricing table.
+- **`livemode`**: A boolean indicating if the table is in live or test mode.
+- **`currency`**: A default currency object.
+- **`items`**: An array of `TPricingTableItem` objects. Each item represents a single plan and contains:
+  - **`price_id`**: The unique ID for the price.
+  - **`product`**: An object with product details like `name`, `description`, and an array of `features`.
+  - **`price`**: An object with pricing details, including `unit_amount`, `currency_options`, and a `recurring` object that specifies the billing `interval` (e.g., 'month', 'year') and `interval_count`.
+  - **`is_highlight`** (optional): A boolean to highlight a specific plan.
+  - **`highlight_text`** (optional): Text to display in the highlight chip (e.g., "Most Popular").
+
+### Example `table` Object
+
+```json
+{
+  "id": "pt_12345",
+  "livemode": true,
+  "currency": { "id": "usd", "symbol": "$" },
+  "items": [
+    {
+      "price_id": "price_basic_monthly",
+      "product": {
+        "name": "Basic Plan",
+        "description": "For individuals and small teams.",
+        "features": [
+          { "name": "5 Projects" },
+          { "name": "Basic Analytics" },
+          { "name": "24/7 Support" }
+        ],
+        "unit_label": "user"
+      },
+      "price": {
+        "unit_amount": "1000",
+        "currency_options": [{ "currency_id": "usd", "unit_amount": "1000" }],
+        "recurring": { "interval": "month", "interval_count": 1 }
+      },
+      "is_highlight": false
+    },
+    {
+      "price_id": "price_pro_yearly",
+      "product": {
+        "name": "Pro Plan",
+        "description": "For growing businesses.",
+        "features": [
+          { "name": "Unlimited Projects" },
+          { "name": "Advanced Analytics" },
+          { "name": "Priority Support" }
+        ],
+        "unit_label": "user"
+      },
+      "price": {
+        "unit_amount": "25000",
+        "currency_options": [{ "currency_id": "usd", "unit_amount": "25000" }],
+        "recurring": { "interval": "year", "interval_count": 1 }
+      },
+      "is_highlight": true,
+      "highlight_text": "Popular"
+    }
+  ]
+}
+```
+
+This component streamlines the creation of dynamic and interactive pricing pages. Once the user selects a plan, you can use the `onSelect` callback to guide them to the next step, which is often displaying a [PaymentSummary](./components-ui-payment-summary.md).

package/docs/components-ui.md

@@ -0,0 +1,44 @@
+# UI Components
+
+The UI Components are a collection of granular, self-contained React components designed for building custom payment and checkout experiences. Unlike the high-level [Checkout Components](./components-checkout.md), which manage an entire payment flow, UI Components give you full control over the layout and user experience by providing the essential building blocks for your interface.
+
+This approach allows you to integrate payment functionality seamlessly into your existing application design. You can combine these components to construct a checkout process that is tailored to your specific requirements, as illustrated in the workflow below.
+
+```d2
+direction: down
+
+A: "Display PricingTable Component"
+B: "User Selects a Subscription Plan"
+C: "Application State is Updated via onSelect Callback"
+D: "Render PaymentSummary with Order Details"
+E: "Render Form Elements (e.g., AddressForm)"
+F: "User Clicks Custom 'Pay' Button"
+G: "Application Logic Submits Payment to Backend"
+
+A -> B: "User Action"
+B -> C: "Triggers Callback"
+C -> D: "Re-renders UI"
+D -> E
+E -> F: "User provides info"
+F -> G: "Initiates Submission"
+```
+
+Below is an overview of the core UI components available. Each component has its own detailed documentation page.
+
+<x-cards data-columns="3">
+  <x-card data-title="PricingTable" data-href="/components/ui/pricing-table" data-icon="lucide:table">
+    Renders a structured, responsive table of your subscription plans. It handles logic for switching between billing intervals and currencies, allowing users to make a selection.
+  </x-card>
+  <x-card data-title="PaymentSummary" data-href="/components/ui/payment-summary" data-icon="lucide:receipt">
+    Displays a detailed breakdown of an order, including line items, quantities, pricing, trial information, and the total amount due. Essential for transparency during checkout.
+  </x-card>
+  <x-card data-title="Form Elements" data-href="/components/ui/form-elements" data-icon="lucide:pencil-ruler">
+    A suite of individual inputs for collecting user data like billing addresses and phone numbers. They include built-in validation and are designed to be composed into any form.
+  </x-card>
+</x-cards>
+
+By combining these components, you can build a robust and user-friendly payment interface that fits perfectly within your application's design. To get started, explore the documentation for the component that best fits your immediate needs.
+
+---
+
+Next, learn how to display your products and plans with the [PricingTable component](./components-ui-pricing-table.md).

package/docs/components.md

@@ -0,0 +1,95 @@
+# 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.
+
+All components are designed to be composable and customizable, ensuring they can fit seamlessly into your application's design and logic.
+
+### 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.
+
+```d2
+direction: down
+
+"@blocklet/payment-react": {
+  shape: package
+  
+  "Checkout Components": {
+    tooltip: "High-level components for complete payment flows"
+    "CheckoutForm": {}
+    "CheckoutTable": {}
+    "CheckoutDonate": {}
+  }
+
+  "UI Components": {
+    tooltip: "Granular building blocks for custom UIs"
+    "PricingTable": {}
+    "AddressForm": {}
+    "PaymentSummary": {}
+  }
+
+  "Business Logic Components": {
+    tooltip: "Components for specific business scenarios"
+    "ResumeSubscription": {}
+    "OverdueInvoicePayment": {}
+    "AutoTopup": {}
+  }
+
+  "History Components": {
+    tooltip: "Components for displaying historical data"
+    "CustomerInvoiceList": {}
+    "CustomerPaymentList": {}
+    "CreditGrantsList": {}
+  }
+}
+```
+
+### Provider Requirements
+
+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`.
+
+Before using any components, ensure your application is set up with the required context providers.
+
+```tsx
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// This is your application's custom hook for session management
+import { useSessionContext } from '../hooks/session'; 
+
+function App() {
+  // Fetch session and connectApi from your application's context.
+  const { session, connectApi } = useSessionContext();
+
+  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>
+  );
+}
+```
+
+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.
+
+## Component Categories
+
+Dive into the component categories to find the tools you need for your project. Each section provides detailed documentation and usage examples.
+
+<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`.
+  </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>
+  <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>
+</x-cards>
+
+## Next Steps
+
+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).

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# 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.
+
+## 1. Installation
+
+First, add the library to your project using npm or your preferred package manager.
+
+```bash
+npm install @blocklet/payment-react
+```
+
+## 2. Set up 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.
+
+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.
+
+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
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../path/to/your/session-context'; // Your local session context
+
+function App() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      {/* Your payment components will go here */}
+    </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" }
+    }
+  }
+}
+
+"Your App.PaymentProvider" -> "Your App.PaymentProvider.CheckoutForm": "Provides context (session, API)"
+"Your App.PaymentProvider" -> "Your App.PaymentProvider.Other Components": "Provides context (session, API)"
+```
+
+## 3. Add a Checkout Form
+
+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.
+
+## 4. 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.
+
+```tsx
+import React from 'react';
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+
+// 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() {
+  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>;
+  }
+
+  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
+        showCheckoutSummary={true}
+        onChange={(state) => console.log('Checkout State:', state)}
+        onPaid={() => alert('Payment Successful!')}
+        onError={(err) => alert(`Payment Failed: ${err.message}`)}
+      />
+    </PaymentProvider>
+  );
+}
+
+export default MyPaymentPage;
+```
+
+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.
+
+## 5. Next Steps
+
+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.

package/docs/guides-theming.md

@@ -0,0 +1,175 @@
+# 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.
+
+## `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 theme merging process follows a clear hierarchy to combine the base theme, default payment styles, and your custom overrides.
+
+```d2
+direction: down
+
+"Parent MUI Theme"
+
+is_ab_theme: "Is it an ArcBlock Theme?" {
+  shape: diamond
+}
+
+"Parent MUI Theme" -> is_ab_theme
+
+use_parent: "Use Parent Theme as Base"
+create_new: "Create New BlockletTheme as Base"
+
+is_ab_theme -> use_parent: "Yes"
+is_ab_theme -> create_new: "No"
+
+base_theme: "Base Theme"
+use_parent -> base_theme
+create_new -> base_theme
+
+default_payment_styles: "Default Payment Component Styles"
+
+merge1: "Merge with Base Theme" {
+  shape: oval
+}
+
+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).
+
+### 1. Overriding Component 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.
+
+This method is ideal for making consistent changes to components like buttons, inputs, and chips across the payment UI.
+
+**Example: Changing the Primary Button Color**
+
+```tsx
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // This path is specific to your project
+
+function CustomStyledForm() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        theme={{
+          components: {
+            MuiButton: {
+              styleOverrides: {
+                containedPrimary: {
+                  backgroundColor: '#1DC1C7',
+                  color: '#fff',
+                  '&:hover': {
+                    backgroundColor: 'rgb(20, 135, 139)',
+                  },
+                },
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### 2. Using the `sx` Prop for Targeted Overrides
+
+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.
+
+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.
+
+**Example: Customizing the Submit Button**
+
+```tsx
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // This path is specific to your project
+
+function TargetedStyleForm() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        showCheckoutSummary={false}
+        theme={{
+          sx: {
+            // Note: The specific class name may vary.
+            // Inspect the element in your browser to find the correct selector.
+            '.cko-submit-button': {
+              backgroundColor: '#1DC1C7',
+              color: '#fff',
+              '&:hover': {
+                backgroundColor: 'rgb(20, 135, 139)',
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+## Understanding the Default Theme
+
+To customize effectively, it's helpful to know what the default theme provides. The `PaymentThemeProvider` includes several key customizations.
+
+### Custom Palette Extensions
+
+The theme extends the standard MUI palette with additional colors for specific UI elements.
+
+| 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`.                                                                                        |
+
+### Global CSS Classes
+
+The theme injects several global utility classes via `MuiCssBaseline` that you can use for styling consistency.
+
+- **`.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 Variables for Light & Dark Modes
+
+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.
+
+| Variable                 | Light Mode Value | Dark Mode Value |
+| ------------------------ | ---------------- | --------------- |
+| `--backgrounds-bg-base`  | `#ffffff`        | `#1b1b1f`       |
+| `--foregrounds-fg-base`  | `#030712`        | `#edeef0`       |
+| `--stroke-border-base`   | `#eff1f5`        | `#2e3035`       |
+
+---
+
+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.