npm package: @rsl-org/rsl-ui-kit
Description: Radiiant Software Labs UI Kit – shared React Native components and theme for Cend and future apps.
Author: Radiiant Software Labs
Latest version: 1.0.4

# Radiiant Software Labs UI Kit

Shared React Native layout and theming primitives used across Cend and future RSL apps. The library is intentionally lightweight and focuses on structural components and design tokens that keep screens feeling native on iOS and Android.

## Core primitives

- **ThemeProvider** – wraps your app to provide `colors`, expanded `spacing`, and `typography` tokens.
- **ScreenContainer** – a universal screen wrapper with safe-area support, keyboard avoidance, and consistent horizontal rhythm.
- **EmptyState** – a centered, friendly layout for zero-content moments, tuned to Material-level spacing.
- **Spacer** – a utility view that enforces the shared spacing scale across layouts.

## Spacing rhythm

All spacing is derived from a 4 pt grid inspired by Apple HIG and Material Design. Use the semantic keys below instead of hard-coded numbers:

| Token | Value (dp) | Typical use |
| --- | --- | --- |
| `xxs` | 2 | Hairline separation |
| `xs` | 4 | Tight control between micro elements |
| `sm` | 8 | Label-to-input spacing |
| `md` | 12 | Stack of text blocks |
| `lg` | 16 | Default horizontal padding |
| `lgPlus` | 20 | Primary card gutters, button stacks |
| `xl` | 24 | Section spacing, EmptyState breathing room |
| `xxl` | 32 | Screen padding, large modals |
| `xxxl` | 40 | Hero spacing |

`gutters.screen` defaults to `lgPlus` (20 dp) and `gutters.section` to `xxl` (32 dp). Access them through `useTheme()` or the `Spacer` component (`<Spacer size="xl" />`).

## Typography map

`AppText` reads variant styles from the theme so copy decks stay on rhythm:

- Micro: `labelSmall`, `caption`, `footnote`
- Body: `body`, `bodySmall`, `bodyLarge`, with `bodyBold` and `bodyMedium` for emphasis
- Titles: `titleSmall`, `title`, `titleLarge`
- Display: `headline`, `displaySmall`, `displayMedium`, `displayLarge`

Pass `align`, `weight`, and native `Text` props as needed. When you need an alternative font family, merge it via `ThemeProvider`.

## ScreenContainer usage

```jsx
import ScreenContainer from 'rsl-ui-kit/components/layout/ScreenContainer';

const Example = () => (
	<ScreenContainer
		scrollable
		contentInsetAdjustmentBehavior="always"
		keyboardDismissMode="on-drag"
		horizontalPadding={24}
	>
		{/* screen content */}
	</ScreenContainer>
);
```

Props worth noting:

- `horizontalPadding`, `topPadding`, `bottomPadding` – override the defaults if a screen needs tighter or looser breathing room.
- `contentInsetAdjustmentBehavior` and `keyboardDismissMode` – forwarded directly to `ScrollView` for native feel.
- `safeAreaStyle` – tweak the `SafeAreaView` wrapper without losing the consistent outer behavior.

## EmptyState tips

```jsx
import EmptyState from 'rsl-ui-kit/components/layout/EmptyState';

<EmptyState
	title="No rides yet"
	subtitle="Once you request a driver, your trip details will appear here."
	message="We’ll send a push notification and email confirmation as soon as things get rolling."
	actionButton={<PrimaryButton label="Plan a ride" />}
/>;
```

- Use `subtitle` for mild supporting copy and `message` for optional extended context.
- Provide an `imageSource` for a light-touch illustration; it will scale responsively.
- Swap in custom `contentStyle` or `maxWidth` to match the host screen.

## Development

This package ships without build tooling. Use the components directly in your React Native app and run the host app’s Metro bundler to see changes. The repository currently exposes a placeholder `npm test`; hook this into your app’s test runner if you need automated checks.

---

Questions or improvements? Open an issue or PR so we can keep the kit evolving alongside our product surfaces.