@mahdava/ui

A React-friendly design system package for building consistent interfaces with shared components, semantic tokens, and themeable styles.

Status: under active development
@mahdava/ui is not production-ready yet. Expect API changes, styling changes, incomplete coverage, and occasional breaking changes while the package is still being shaped.

What this package is for

@mahdava/ui is meant to provide:

• reusable UI components
• semantic design tokens
• theme files for different visual directions
• framework-aware provider hooks for things like custom link renderers
• a package structure that can be consumed from external apps

The goal is to make it easier to build interfaces with a shared design language instead of restyling the same primitives over and over again.

What it currently includes

• atoms, molecules, and higher-level UI building blocks
• semantic CSS variable tokens
• built-in theme files
• package stylesheets for consumer apps
• MahdavaUIProvider for integration points like custom link renderers

Install

npm install @mahdava/ui
npm install -D tailwindcss @tailwindcss/postcss

@mahdava/ui expects the consumer app to process its CSS through a Tailwind 4 compatible pipeline. It does not ship fully precompiled standalone CSS.

Basic usage

Import Tailwind in your app, then import the base package styles, then import a theme explicitly.

import { MahdavaUIProvider } from "@mahdava/ui";
import "tailwindcss";
import "@mahdava/ui/styles.css";
import "@mahdava/ui/themes/default.css";

export function App() {
  return (
    <MahdavaUIProvider>
      {/* your app */}
    </MahdavaUIProvider>
  );
}

What styles.css includes

@mahdava/ui/styles.css is the base package entrypoint. It includes:

• the package token and component styles
• the generated Tailwind inline source helper used by published components

It does not include Tailwind itself, and it does not include a theme. Both are imported separately on purpose.

Why themes are separate

Themes are treated as explicit overlays, not hidden defaults. That keeps the contract clearer:

• @mahdava/ui/styles.css = base styles and package wiring
• @mahdava/ui/themes/*.css = theme choice

This makes it easier to swap themes or provide your own without fighting an implicit built-in default.

Required PostCSS config in consumer apps

Consumer apps using @mahdava/ui/styles.css should include a PostCSS config with the Tailwind v4 PostCSS plugin:

const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;

If your app is missing this, you may see warnings such as Unknown at rule: @theme, @source, or @tailwind, and package styling may render incorrectly even if the build succeeds.

Built-in themes

Themes can be imported separately when needed:

import "@mahdava/ui/themes/default.css";
import "@mahdava/ui/themes/forest.css";
import "@mahdava/ui/themes/pixel-galaxy.css";

In most apps, you should import exactly one theme at the app entrypoint.

Consumer setup summary

For most consumer apps, the intended setup is:

import "tailwindcss";
import "@mahdava/ui/styles.css";
import "@mahdava/ui/themes/default.css";

Integration notes

Use MahdavaUIProvider when your app needs custom framework-aware renderers, such as:

• Next.js Link / Image
• Remix Link
• other router or image abstractions

Development warning

This package is still being actively designed.

That means:

• component APIs may change
• token names and theme contracts may evolve
• examples and docs may move faster or slower than implementation
• versions may introduce breaking changes before the package stabilizes

If you use it today, treat it as best suited for:

• internal prototyping
• package integration work
• exploratory UI development
• design-system iteration

Repository docs

Repository-specific contributor and maintainer guidance lives in:

• CONTRIBUTING.md
• docs/component-text-customization.md