# Why a shared design system for Rahhal mini-apps?

Rahhal is a family of small, focused web apps that each live on their own subdomain. Without a shared foundation, each new mini-app would re-invent the same buttons, the same theme, the same login screen — and slowly drift away from feeling like one product.

## The problem

Independent deploys are great for teams; they're terrible for brand cohesion if each app picks its own colors, type scale, and locale handling. The design system makes the right thing the easy thing: a mini-app that uses `@rahhal/ui`, `@rahhal/themes`, `@rahhal/i18n`, and `@rahhal/auth` automatically inherits the platform's look, RTL behavior, and authentication contract.

## Use cases

| use case | what it gives you |
| --- | --- |
| One product family | Every mini-app on rahhal.app feels like a chapter of the same product. |
| Bilingual by default | EN + AR (with full RTL) ship together — no retrofit, no per-app translation pipeline. |
| Phone-OTP, once | `@rahhal/auth` implements the iOS → web handover and standalone OTP flow exactly once. |
| Built for AI agents | Every catalog page is also served as Markdown — same source of truth humans browse here. |
| Cross-platform tokens | Color / typography / radius defined in TypeScript, emitted as CSS vars + JSON for iOS / Android / Figma. |
| Ship fast | Scaffolding a new mini-app is mostly composing what's already here. |

## Principles

- Compose first — reach for `@rahhal/ui` before writing your own button.
- Tokens are the contract — never hardcode brand colors in an app.
- RTL is not optional — use logical utilities and the i18n adapters everywhere.
- Document deliberately — shared packages get TSDoc, file headers, and a README; the catalog is the public contract.