npm package: @mahdava/ui
Description: Eons UI design system
Latest version: 0.3.8

# @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

```bash
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.

```tsx
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:

```js
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:

```tsx
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:

```tsx
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](./CONTRIBUTING.md)
- [docs/component-text-customization.md](./docs/component-text-customization.md)