> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Customization

> Customize TapRails branded UI with your own colors and integrate reusable components.

The TapRails SDK ships with a complete, production-ready UI layer. You can use it as-is, theme it to match your brand, or use its primitives alongside your own custom screens.

***

## TapRailsThemeProvider

Wrap your app root with `TapRailsThemeProvider` to enable theming across all TapRails components:

```tsx theme={null}
import { TapRailsThemeProvider } from '@taprails/tap-to-pay';

<TapRailsThemeProvider
  colorOverrides={{
    primary: '#6366F1',      // Brand color (default: TapRails purple #8B5CF6)
    success: '#22C55E',      // Confirmation green
    error: '#EF4444',        // Error red
    background: '#FFFFFF',   // Screen background
    text: '#1F2937',         // Primary text
  }}
>
  <YourApp />
</TapRailsThemeProvider>
```

### colorOverrides

All fields are optional — any value you omit falls back to the TapRails default:

| Field        | Default   | Description                                |
| ------------ | --------- | ------------------------------------------ |
| `primary`    | `#8B5CF6` | Main brand color (buttons, icons, accents) |
| `success`    | `#10B981` | Success states and confirmations           |
| `error`      | `#EF4444` | Error states                               |
| `background` | `#0D0D0D` | Screen background                          |
| `surface`    | `#1A1A1A` | Card / elevated surface background         |
| `text`       | `#FFFFFF` | Primary body text                          |
| `textMuted`  | `#9CA3AF` | Muted / secondary text                     |
| `border`     | `#2D2D2D` | Dividers and borders                       |

***

## useTheme

Access the active theme anywhere in your component tree:

```tsx theme={null}
import { useTheme } from '@taprails/tap-to-pay';

function CustomComponent() {
  const theme = useTheme();

  return (
    <View style={{ backgroundColor: theme.colors.surface }}>
      <Text style={{ color: theme.colors.primary, ...theme.typography.styles.h2 }}>
        Hello
      </Text>
      <Text style={{ color: theme.colors.textMuted }}>
        Subtext
      </Text>
    </View>
  );
}
```

### theme.colors

All colors from `colorOverrides` merged with TapRails defaults, accessible as `theme.colors.<key>`.

### theme.typography.styles

Pre-built text style objects:

| Key         | Usage                            |
| ----------- | -------------------------------- |
| `h1`        | Large screen heading             |
| `h2`        | Section heading                  |
| `h3`        | Card heading                     |
| `body`      | Regular body text                |
| `bodySmall` | Small secondary text             |
| `label`     | Input labels                     |
| `button`    | Button label text                |
| `mono`      | Monospace (tx hashes, addresses) |

***

## Button Component

A themed, accessible button with variants and sizes:

```tsx theme={null}
import { Button } from '@taprails/tap-to-pay';

// Primary CTA
<Button
  title="Pay $25.00"
  onPress={handlePay}
  variant="primary"   // 'primary' | 'secondary' | 'ghost' | 'danger'
  size="lg"           // 'sm' | 'md' | 'lg'
  loading={isProcessing}
  disabled={!isReady}
/>

// Ghost / outlined
<Button
  title="Cancel"
  onPress={onCancel}
  variant="ghost"
  size="md"
/>

// Danger (e.g. revoke session key)
<Button
  title="Revoke Access"
  onPress={handleRevoke}
  variant="danger"
/>
```

### ButtonProps

| Prop       | Type                   | Default     | Description                          |
| ---------- | ---------------------- | ----------- | ------------------------------------ |
| `title`    | `string`               | —           | Button label                         |
| `onPress`  | `() => void`           | —           | Press handler                        |
| `variant`  | `ButtonVariant`        | `'primary'` | Visual style                         |
| `size`     | `ButtonSize`           | `'md'`      | Height and font size                 |
| `loading`  | `boolean`              | `false`     | Shows spinner, disables press        |
| `disabled` | `boolean`              | `false`     | Disables interaction and dims button |
| `icon`     | `ReactNode`            | —           | Optional icon to the left of label   |
| `style`    | `StyleProp<ViewStyle>` | —           | Additional container styles          |

***

## Icon Component

Access TapRails's icon set directly:

```tsx theme={null}
import { Icon } from '@taprails/tap-to-pay';

<Icon name="nfc" size={32} color="#8B5CF6" />
<Icon name="check-circle" size={24} />
<Icon name="x" size={20} color="red" />
```

Icons use the `lucide-react-native` library under the hood. The `name` prop accepts any Lucide icon name.

### IconProps

| Prop          | Type     | Default             | Description                     |
| ------------- | -------- | ------------------- | ------------------------------- |
| `name`        | `string` | —                   | Lucide icon name (snake\_case)  |
| `size`        | `number` | `24`                | Icon width and height in points |
| `color`       | `string` | `theme.colors.text` | Icon color                      |
| `strokeWidth` | `number` | `2`                 | Stroke weight                   |

***

## Accessibility

TapRails UI components are built WCAG AA compliant:

* All interactive elements have `accessibilityLabel` and `accessibilityRole`
* Minimum touch targets of **44×44pt**
* Color contrast ratios meet WCAG AA (≥ 4.5:1 for text)
* Loading states announce to screen readers via `accessibilityLiveRegion`
* Full keyboard navigation support