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 we're solving
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.
What it's for
One product family
Every mini-app on rahhal.app feels like a chapter of the same product, not a museum of mismatched stacks.
Bilingual by default
EN and AR (with full RTL) ship together. No retrofit, no per-app translation pipeline, no "v2 will add Arabic".
Phone-OTP, once
@rahhal/auth implements the iOS → web session handover and the standalone phone-OTP flow exactly once. Apps just install it.
Built for AI agents
Every catalog page is also served as Markdown. Agents fetch /skill.md (or any /components/<slug>.md) and get the same source of truth humans browse here.
Cross-platform tokens
Color, typography, and radius are defined in TypeScript and emitted as CSS variables AND a JSON snapshot for iOS / Android / Figma — one source of truth.
Ship in days, not weeks
Scaffolding a new mini-app is mostly composing what's already here. The interesting product work starts on day one.
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.