@qumra/fanar
v0.0.14
Published
Qumra's Arabic-first component library and design tokens. Tailwind 4, RSC-safe.
Readme
@qumra/fanar
Qumra's component library and design tokens — Arabic-first, Tailwind 4, RSC-safe.
Every component works in both dir="rtl" and dir="ltr" with no
direction-specific code: logical properties only, and the library reads its
own language from <html lang>.
pnpm add @qumra/fanarEntry points
The package is one install with seven entry points. Importing
@qumra/fanar pulls in neither TipTap, nor three, nor the notification
system — each heavy group is behind its own path.
| Import | What it gives you | Notes |
| --- | --- | --- |
| @qumra/fanar | Components | client |
| @qumra/fanar/lib | Pure helpers (cn, toLatinDigits) | server-safe |
| @qumra/fanar/tokens | Token values (TOKENS, scales) | server-safe |
| @qumra/fanar/notifications | Notification system | client |
| @qumra/fanar/ai | Assistant surfaces | needs @qumra/jawab-ai |
| @qumra/fanar/orb | Animated voice orb | needs three, @react-three/fiber, @react-three/drei |
| @qumra/fanar/editor | Rich-text editor | bundles TipTap |
Plus two stylesheets: @qumra/fanar/tokens.css and
@qumra/fanar/editor.css.
Setup
/* styles.css */
@import 'tailwindcss';
@import '@qumra/fanar/tokens.css';import { Button, Money } from '@qumra/fanar'
import { cn } from '@qumra/fanar/lib' // usable from a server component
import { TOKENS } from '@qumra/fanar/tokens'
;<Button variant="primary">
Pay <Money value={1250} currency="EGP" />
</Button>The six rules
Every component in this library follows them, and two are enforced by lint:
- No hand-written colors. Every color comes from a token.
- Surfaces use semantic tokens —
bg-surface,text-ink,border-line. These flip themselves in dark mode. - Logical properties only —
ps-4notpl-4,start-0notleft-0. - Real elements. Anything clickable is a
<button>or an<a>; every field is a<label htmlFor>plusaria-describedbyfor its error. - Numbers carry
data-numeric— pins LTR direction and turns ontabular-nums. - Sizes come from the scale —
text-ui,rounded-card,shadow-modal.
Peer dependencies
react and react-dom are required. tailwindcss, three,
@react-three/fiber, @react-three/drei, @google/model-viewer, and
@qumra/jawab-ai are optional — you only install the ones whose entry
point you actually import.
This is not a formality. @react-three/drei pulls in camera-controls,
which requires Node 22; as a hard dependency it broke yarn install on a
Node 20 server for a consumer that never imported the orb. Heavy groups
belong to their entry point, and the manifest has to say so.
Documentation
Source, decision log, and a live catalogue with a page per component live in the repository. Comments and internal docs there are written in Egyptian Arabic: they are the record of why each decision was made, kept in the language the team argued them in.
License
UNLICENSED — see package.json.
