# Frequently asked questions

Quick answers to the questions newcomers ask first. For long-form references, the `rahhal-miniapps` skill at `.claude/skills/` is the canonical how-to.

### How do I start using the Rahhal design system?

Clone the monorepo, run `pnpm install`, then `pnpm --filter @rahhal/themes build` to generate the token CSS. Browse the components in the catalog to find what you need, and import from `@rahhal/ui`. The repo's `CLAUDE.md` is the always-on summary; the `rahhal-miniapps` skill has the deep how-tos.

### How do I scaffold a new mini-app?

Create a folder under `apps/<name>`, choose Next.js or Vite based on whether you need SSR/SEO, then follow `scaffold-next.md` or `scaffold-vite.md` in the `rahhal-miniapps` skill. Both flows wire `@rahhal/ui`, `@rahhal/themes`, `@rahhal/i18n`, and (optionally) `@rahhal/auth`.

### How do I import components from @rahhal/ui?

Either from the bundle root (`import { Button } from "@rahhal/ui"`) or per-component subpaths (`import { Button } from "@rahhal/ui/button"`). Both work; subpaths keep your bundle tighter when you only need one or two.

### How do I add Arabic (or another locale) to my app?

Both EN and AR are wired by default through `@rahhal/i18n`. Add app-specific messages on top of the shared catalog. RTL flips automatically as long as you use Tailwind logical utilities (`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`).

### How do I wire phone-OTP login?

Install `@rahhal/auth`, wrap your root in `<AuthProvider>`, gate authed routes with `<RequireSession>`, set the `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars. Use `requestPhoneOtp` + `verifyPhoneOtp` for the standalone flow; the iOS → web handover is automatic. Never import `@supabase/supabase-js` directly.

### How do I add or change a design token?

Edit `packages/themes/src/themes/{light,dark}.ts` (TypeScript is the source of truth — both themes must satisfy `ThemeTokens`), then run `pnpm --filter @rahhal/themes build` to regenerate `dist/tokens.css` and `dist/tokens.json`. Never edit the generated files by hand.

### When should I promote an app-local component into @rahhal/ui?

When the same wrapper recurs across two or more apps. Move source into `packages/ui/src/<component>.tsx`, add an `index.ts` export and a subpath in `package.json`, then add a catalog entry under `apps/design-system/src/catalog/entries/` and a meta row in `spec/components-meta.ts`.

### How do AI agents consume this design system?

Every catalog page has a Markdown counterpart at `/components/<slug>.md`, plus the umbrella `/skill.md`, plus `/why.md` and `/faq.md`. Agents fetch those URLs to read the same source of truth humans browse here.

### Where do mini-apps deploy?

Independently — each mini-app owns its own deploy config (`vercel.json`, `Dockerfile`, Cloudflare Pages, …). There is no centralized deploy. Subdomains roll up under `*.rahhal.app` so the platform reads as one product family even though deploys are independent.

### What if a component I need isn't in the catalog?

Build it locally first inside your app. If it stays self-contained you're done. If it starts being copied across apps, that's the signal to promote it into `@rahhal/ui` — see the promotion question above.