## Designing User Interfaces and Interactions for Stripe Apps

This section provides guidance on designing effective user interfaces and interactions within Stripe Apps, ensuring a consistent and intuitive experience for users. It covers various aspects of UI development, from fundamental design principles to specific component usage and interaction patterns.

### Core UI Design Principles and Components

*   **Design Your App (`/stripe-apps/design`):** This foundational page introduces the overall design philosophy for Stripe Apps, emphasizing platform consistency, accessibility, and branding. It highlights the available tools and guidelines for creating a cohesive user experience.
*   **Style Your App (`/stripe-apps/style`):** Learn how to apply styling to your Stripe App using provided design tokens. This ensures visual consistency with the Stripe Dashboard and maintains a high-quality user interface.
*   **UI Components (`/stripe-apps/components`):** This is a comprehensive reference to all available UI components within the Stripe Apps UI toolkit. It serves as a catalog for building your app's interface, detailing each component's purpose, props, and usage.
    *   **Layout and Structure:**
        *   `Box` (`/stripe-apps/components/box`): A fundamental component for wrapping other elements, applying custom styles, and managing layouts, similar to an HTML `div`.
        *   `Inline` (`/stripe-apps/components/inline`): For styling inline content like text, analogous to an HTML `span`.
        *   `Divider` (`/stripe-apps/components/divider`): Renders a simple horizontal rule for visual separation.
        *   `FullPageView` (`/stripe-apps/components/fullpageview`): Implements the full-page viewport for Stripe Apps, allowing for expansive layouts.
    *   **Navigation and Structure:**
        *   `Tabs` (`/stripe-apps/components/tabs`): Organizes content into distinct sections, allowing users to switch between them.
        *   `FullPageTabs` (`/stripe-apps/components/fullpagetabs`): A private developer preview component for displaying sections of content within a full-page layout.
        *   `Link` (`/stripe-apps/components/link`): Enables navigation between pages or for subtle actions, offering primary and secondary styles.
        *   `Route Descriptors` (`/stripe-apps/route-descriptors`): Facilitates soft, context-preserving navigation within the Dashboard, avoiding full page reloads.
    *   **Input and Controls:**
        *   `Button` (`/stripe-apps/components/button`): Allows users to take actions, direct attention, or warn of outcomes, with primary, secondary, and destructive types.
        *   `ButtonGroup` (`/stripe-apps/components/buttongroup`): Manages the layout of multiple buttons, collapsing them into an overflow menu when space is limited.
        *   `Checkbox` (`/stripe-apps/components/checkbox`): Indicates or controls boolean values.
        *   `Radio` (`/stripe-apps/components/radio`): Enables selection from a set of mutually exclusive options.
        *   `Switch` (`/stripe-apps/components/switch`): Similar to checkboxes, used to indicate or control boolean values, often for immediate settings changes.
        *   `TextField` (`/stripe-apps/components/textfield`): Provides a single-line text input field.
        *   `TextArea` (`/stripe-apps/components/textarea`): Creates an input field for multiple lines of text.
        *   `DateField` (`/stripe-apps/components/datefield`): Collects date information from users.
        *   `Select` (`/stripe-apps/components/select`): Allows users to pick from a set of options in a dropdown.
        *   `SearchField` (`/stripe-apps/components/searchfield`): Enables users to search and filter content within your app.
    *   **Information Display and Feedback:**
        *   `Badge` (`/stripe-apps/components/badge`): Indicates the state of an item or object with distinct types (neutral, info, positive, negative, warning, urgent).
        *   `Banner` (`/stripe-apps/components/banner`): Displays alerts or messages that require user attention, with default, caution, and critical types.
        *   `Toast` (`/stripe-apps/components/toast`): Informs users of temporary status updates, typically appearing at the bottom of the view.
        *   `Tooltip` (`/stripe-apps/components/tooltip`): Provides additional contextual information about an element or subject.
        *   `Sparkline` (`/stripe-apps/components/sparkline`): A concise line chart for displaying data succinctly.
        *   `LineChart` (`/stripe-apps/components/linechart`): Visualizes data points connected by a line.
        *   `BarChart` (`/stripe-apps/components/barchart`): Displays data using bars.
        *   `List` (`/stripe-apps/components/list`): Presents collections of information in various preconfigured formats.
        *   `Table` (`/stripe-apps/components/table`): Displays tabular data.
        *   `DataTable` (`/stripe-apps/components/datatable`): Another component for displaying tabular data.
        *   `DetailPageTable`, `DetailPagePropertyList`, `DetailPageModule` (`/stripe-apps/components/detailpagetable`, `/stripe-apps/components/detailpagepropertylist`, `/stripe-apps/components/detailpagemodule`): Components for rendering app content within Stripe dashboard detail pages.
        *   `PropertyList` (`/stripe-apps/components/propertylist`): Displays data as key-value pairs.
        *   `Chip` (`/stripe-apps/components/chip`): Displays and allows manipulation of values, often used for filtering.
        *   `Icon` (`/stripe-apps/components/icon`): Displays an icon graphic.
        *   `Img` (`/stripe-apps/components/img`): Displays images.
        *   `Spinner` (`/stripe-apps/components/spinner`): Indicates that content is loading.
        *   `Menu` (`/stripe-apps/components/menu`): Presents a group of actions for user selection.
        *   `Accordion` (`/stripe-apps/components/accordion`): Splits content into collapsible chunks.
    *   **Views and Context:**
        *   `ContextView` (`/stripe-apps/components/contextview`): The root view for your app, allowing side-by-side viewing with Stripe content in a drawer.
        *   `FocusView` (`/stripe-apps/components/focusview`): Opens a dedicated space for users to complete specific tasks.
        *   `OnboardingView` (`/stripe-apps/components/onboardingview`): Implements an onboarding flow for your Stripe App.
        *   `SignInView` (`/stripe-apps/components/signinview`): Displays a sign-in screen for your app.
        *   `SettingsView` (`/stripe-apps/components/settingsview`): Allows users to change app settings.
    *   **Developer Tools:**
        *   `UI extension developer tools` (`/stripe-apps/ui-extension-developer-tools`): Details tools for type checking, linting, and testing your app's UI.
        *   `UI testing` (`/stripe-apps/ui-testing`): Provides utilities and helpers for testing your app's UI.
        *   `Component hierarchy constraints` (`/stripe-apps/component-hierarchy-constraints`): Explains rules governing component composition to ensure predictable UI rendering.
        *   `Next generation UI components` (`/stripe-apps/next-ui-components`): Offers early access to updated UI components.

### Design Patterns and Best Practices

*   **Design patterns for Stripe Apps (`/stripe-apps/patterns`):** This section introduces recommended design patterns to streamline the app review process and ensure a consistent user experience.
    *   **Onboarding and Authentication:**
        *   `Onboarding flow` (`/stripe-apps/patterns/onboarding-experience`): Guides users through an effortless, customizable, and relevant setup process.
        *   `Sign in template` (`/stripe-apps/patterns/sign-in`): Provides guidance on using the `SignInView` component for secure user authentication.
        *   `Settings sign in` (`/stripe-apps/patterns/settings-signin`): Details how to onboard users directly on a settings page, especially for backend-only apps.
        *   `Additional context` (`/stripe-apps/patterns/additional-context`): Explains how to provide supplementary information during onboarding.
        *   `Demo content` (`/stripe-apps/patterns/demo`): Offers tips for displaying concise and functional app demonstrations.
    *   **Navigation and Flow:**
        *   `Action buttons` (`/stripe-apps/patterns/action-buttons`): Recommends consistent placement for action buttons to enhance usability.
        *   `Back link` (`/stripe-apps/patterns/back-link`): Provides guidance on implementing clear navigation back to previous pages.
        *   `Redirects` (`/stripe-apps/patterns/redirects`): Ensures clear and user-friendly redirects within the onboarding flow.
        *   `Progress stepping` (`/stripe-apps/patterns/progress-stepping`): Helps users manage multi-step tasks without abandonment.
        *   `Waiting screens` (`/stripe-apps/patterns/waiting-screens`): Informs users about wait times and next steps during the onboarding process.
    *   **Information and State Management:**
        *   `Communicating state` (`/stripe-apps/patterns/communicating-state`): Guides on how to inform users about actions and system-level requirements using Toasts and Banners.
        *   `Empty state` (`/stripe-apps/patterns/empty-state`): Provides clear messaging when no data is available to load.
        *   `Loading` (`/stripe-apps/patterns/loading`): Details how to use the Spinner component to indicate data loading.
    *   **Filtering and Lists:**
        *   `Filter controls` (`/stripe-apps/patterns/filter-controls`): Explains how to use Chip components for filtering table rows.
        *   `Lists` (`/stripe-apps/patterns/lists`): Covers the use of List components for displaying collections of information.
    *   **Page Layouts:**
        *   `Full page apps` (`/stripe-apps/patterns/full-page-apps`): Guides on building custom, multi-view pages within the Stripe Dashboard.
    *   **Sign Out:**
        *   `Sign out` (`/stripe-apps/patterns/sign-out`): Ensures users can easily sign out of your app.

### Building and Integrating Stripe Apps

*   **Stripe Apps (`/stripe-apps`):** An overview of Stripe Apps, their capabilities, and how to get started.
*   **How Stripe Apps work (`/stripe-apps/how-stripe-apps-work`):** Explains the fundamental concepts and architecture of Stripe Apps.
*   **Getting started with Stripe Apps (`/stripe-apps/create-app`):** A step-by-step guide to building your first Stripe App.
*   **Common use cases (`/stripe-apps/common-use-cases`):** Illustrates various scenarios for building Stripe Apps.
*   **Sample apps (`/stripe-apps/sample-apps`):** Provides working examples of Stripe Apps to use as a starting point.
*   **Build a UI (`/stripe-apps/build-ui`):** Details how to create custom user interfaces within the Stripe Dashboard using React and the UI Extensions SDK.
*   **How UI extensions work (`/stripe-apps/how-ui-extensions-work`):** Explains the system for rendering custom UIs within Stripe.
*   **Add server-side logic (`/stripe-apps/build-backend`):** Covers integrating backend code for processing user actions and data.
*   **API authentication methods (`/stripe-apps/api-authentication`):** Describes different methods for authenticating API requests.
    *   `OAuth 2.0` (`/stripe-apps/api-authentication/oauth`): Details the OAuth 2.0 authentication flow.
    *   `Restricted API key authentication` (`/stripe-apps/api-authentication/rak`): Explains how to use restricted API keys for secure authentication.
*   **Authorization flows (`/stripe-apps/pkce-oauth-flow`):** Implements PKCE OAuth workflows for enhanced security.
*   **Store secret credentials and tokens in your app (`/stripe-apps/store-secrets`):** Guides on securely persisting sensitive data using the Secret Store API.
*   **App settings page (`/stripe-apps/app-settings`):** How to create a page for users to configure app settings.
*   **Enable local network access (`/stripe-apps/enable-local-network-access`):** Necessary for app previewing with local development servers.
*   **Enable sandbox support for your public app (`/stripe-apps/enable-sandbox-support`):** How to allow users to test your app in a sandbox environment.
*   **Handle different modes (`/stripe-apps/handling-modes`):** Adapt your app to function correctly in both live and sandbox environments.

### Migration and Legacy Extensions

*   **Migrate an extension to Stripe Apps (`/stripe-apps/migrate-extension`):** Explains why and how to migrate legacy extensions to the modern Stripe Apps platform.
*   **Migrate a plugin to Stripe Apps or Stripe Connect (`/stripe-apps/plugins/decide-migration`):** Helps you choose the best migration path for your existing integrations.
    *   `Migrate a plugin to an OAuth 2.0 app` (`/stripe-apps/plugins/oauth`): Guides migration to OAuth 2.0 authentication.
    *   `Migrate a plugin to a RAK app` (`/stripe-apps/plugins/rak`): Guides migration to Restricted API Key (RAK) authentication.
*   **Legacy extensions (`/building-extensions`):** Information on the deprecated extensions integration pattern for historical reference.

### Distribution, Testing, and Publishing

*   **Distribution options (`/stripe-apps/distribution-options`):** Learn about making your Stripe Apps publicly available or sharing them privately.
*   **Upload and install your Stripe App (`/stripe-apps/upload-install-app`):** Steps to make your app available to team members.
*   **Test your app externally (`/stripe-apps/test-app`):** Set up and distribute test versions of your app before publication.
*   **Manage your app's versions and releases (`/stripe-apps/versions-and-releases`):** Learn about app versioning and managing changes over time.
*   **How to publish an app to the Stripe App Marketplace (`/stripe-apps/publish-app`):** A guide to getting your app approved for the Stripe App Marketplace.
*   **Stripe Apps quality requirements (`/stripe-apps/review-requirements`):** Details the qualitative requirements for apps on the App Marketplace.
*   **Promote your app (`/stripe-apps/promote-app`):** Information on partnering with Stripe to grow your app's reach.
*   **Add deep links (`/stripe-apps/deep-links`):** Create URLs that navigate users directly to your Stripe App within the Dashboard.
*   **Using install links (`/stripe-apps/install-links`):** Allow users to install your app outside of the Stripe App Marketplace.
*   **Using roles in UI extensions (`/stripe-apps/using-roles-in-ui-extensions`):** Tailor app functionality based on user roles within the Dashboard.

### Reference and SDKs

*   **App manifest reference (`/stripe-apps/reference/app-manifest`):** Documentation for the app manifest file, defining app integration with Stripe.
*   **Stripe Apps CLI reference (`/stripe-apps/reference/cli`):** Instructions for using the command-line interface to manage your Stripe App.
*   **Permissions reference (`/stripe-apps/reference/permissions`):** A list of available events and their required permissions for your app.
*   **Extension SDK API reference (`/stripe-apps/reference/extensions-sdk-api`):** Documentation for the Extension SDK API, including context props and utility functions.
*   **Upgrade Stripe's UI extension SDK (`/stripe-apps/upgrade-stripes-ui-extension-sdk`):** Guidance on upgrading your app to the latest version of the UI extension SDK.
*   **Viewports reference (`/stripe-apps/reference/viewports`):** A list of available viewports where your app's UI can appear within the Dashboard.
*   **App analytics (`/stripe-apps/analytics`):** Access analytics to understand your app's performance and usage.
*   **Embedded Stripe Apps integration guide (`/stripe-apps/embedded-apps`):** Information on embedding Stripe Apps into third-party applications.
    *   **Marketing software integrations (`/stripe-apps/embedded-apps/marketing-integrations`):** Specific guidance on integrating marketing software.