mada-design-system
v1.7.4
Published
A React + TypeScript component library (Radix UI primitives, Tailwind CSS, `class-variance-authority`) with built-in light/dark themes, Arabic/English localization and RTL support.
Readme
mada-design-system
A React + TypeScript component library (Radix UI primitives, Tailwind CSS, class-variance-authority) with built-in light/dark themes, Arabic/English localization and RTL support.
Using an AI coding agent? Point it at
docs/agents.mdin this package (also shipped asAGENTS.mdat the package root). It has the conventions and common mistakes in a form built for agents.
Install
pnpm add mada-design-systemPeer dependencies: react and react-dom (v19). Radix UI, recharts, @tanstack/react-query, react-localization and framer-motion are external, so your app must be able to resolve them (the package declares them as dependencies).
Setup
1. Import the stylesheet once (app entry)
import 'mada-design-system/style.css'2. Use the Tailwind config
The design tokens (colors, spacing such as p-space-04, typography such as text-body-02) live in the shared Tailwind config. Reuse its theme and plugins, and let Tailwind scan the library so any class you use in your own code that depends on those tokens is generated:
// tailwind.config.js
import madaConfig from 'mada-design-system/tailwind'
export default {
darkMode: ['class'],
content: ['./src/**/*.{ts,tsx}', './node_modules/mada-design-system/**/*.js'],
theme: madaConfig.theme,
plugins: madaConfig.plugins,
}Dark mode is class-based: the dark class is toggled on document.body. The config also sets html { font-size: 10px }, so 1rem is 10px. Size things with the spacing tokens instead of assuming a 16px root.
Font. IBM Plex Sans Arabic (weights 400-700, Arabic and Latin subsets, woff2, SIL OFL 1.1) is bundled with style.css and served from your own origin. The package makes no request to Google Fonts. Your bundler resolves the url() references in style.css. To avoid a late font swap, you can preload the files your bundler emits, for example <link rel="preload" as="font" type="font/woff2" href="..." crossorigin>. The crossorigin attribute is required, even on the same origin.
3. Optional shared config
mada-design-system/prettier, /eslint and /tsconfig export the lint and format configs used by the library.
Providers and global state
| Concern | How |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Theme | useThemeStore().setTheme(THEME.LIGHT \| THEME.DARK \| THEME.SYSTEM). Toggles the dark class on body and persists to localStorage. |
| Icons | Wrap the app in <IconConfigProvider isHugeIcons> to switch components from Material icons to HugeIcons. Read it with useIconConfig(). |
| Language / RTL | useLanguage() holds lang ('ar' or 'en') and dir. changeLang() persists the choice and reloads the page. Translated strings come from strings and setLanguage in Locales. |
| Toasts | Render <Toaster /> once, then call toast({ title, description }) from anywhere. |
import { IconConfigProvider, Toaster, Button, toast } from 'mada-design-system'
export function App() {
return (
<IconConfigProvider isHugeIcons>
<Button colors="primary" onClick={() => toast({ title: 'Saved' })}>
Save
</Button>
<Toaster />
</IconConfigProvider>
)
}Components
Everything is exported from the package root.
- Primitives (shadcn/ui style, wrapping Radix):
Accordion,Alert,AlertDialog,Avatar,Badge,Breadcrumb,Button,Calendar,Card,Carousel,Checkbox,Collapsible,Command,Dialog,DropdownMenu,HoverCard,Input,InputOTP,Label,NavigationMenu,Popover,Progress,RadioGroup,ScrollArea,Select,Separator,Sheet,Sidebar,Skeleton,Slider,Switch,Table,Tabs,Textarea,Toast,Toggle,ToggleGroup,Tooltip. - Layout:
Grid/GridItem,SimpleGrid,Stack. - Typography:
Heading(h1–h6viaas),Text(span,labelorpviaas). - Forms:
Form,FormField,FormItem,FormLabel,FormControl,FormDescription,FormMessage(built onreact-hook-form, which is also re-exported:useForm,Controller, and so on), plusCombobox/ComboboxControl,Autocomplete,MultiSelect,DatePicker,TimePicker,FileUpload,DigitalSignature,Rating. - Data display:
DataTable(TanStack Table),List,Stepper,RadialStepper,Widget, charts,VirtualScroller,DraggableGrid,EmptySection. - Surfaces / navigation:
SheetForm*,SecondNavHeader,Footer,FloatingButton,FilterGroup,FilterSelect,Pagination,SliderPagination. - Helpers:
ShouldRender,ActionLoader,PageLoader,ResponsiveScroll.
Props, defaults and allowed variant values are documented with JSDoc on each component, so they show in your editor and in the .d.ts files.
Common props
Most visual components share the same variant props from class-variance-authority:
variant: for exampledefault | outline | ghost | link | text(Button),default | outline | lighter(Input)colors: for exampleprimary | error | neutral | secondary | tertiary | warning | success | info | gray | oncolor(Button)size:default | sm | xs, plusicon | icon-sm | icon-xsonButtonrounded:default | full
RTL
Components use logical Tailwind utilities (ms-*, me-*, start-*) and rtl: / ltr: variants. Set dir="rtl" on your root element for Arabic. See docs/agents.md for how to write RTL-safe code with the library.
Next.js
The library entry points are marked with 'use client' where needed, so components can be imported from Next.js client components.
