@alsaeedfayed/ui-lib

Design System & Shared UI Component Library built with React, Tailwind CSS, shadcn/ui, and SCSS.

Prerequisites

• Node.js >= 18
• pnpm (recommended) — install with npm i -g pnpm

Getting Started (Local Development)

1. Clone the repository

git clone https://github.com/alsaeedfayed/sa-ui-lib.git
cd sa-ui-lib

2. Install dependencies

pnpm install

3. Run the playground (dev server)

pnpm playground

This starts a Vite dev server with the playground app where you can test components locally with hot-reload.

4. Build in watch mode (optional)

If you want the library to rebuild automatically on every change:

pnpm dev

Building for Production

1. Clean previous build artifacts

pnpm clean

2. Run the build

pnpm build

This uses tsup to compile the library and outputs the following to the dist/ folder:

| Output | Description | | ----------------- | ------------------------------------ | | dist/index.js | CommonJS bundle | | dist/index.mjs | ESM bundle | | dist/index.d.ts | TypeScript declarations | | dist/index.css | Compiled styles (SCSS + CSS Modules) |

3. Verify the build

ls dist/

Available Scripts

| Script | Command | Description | | ----------------------- | ----------------------------------------------- | ------------------------------- | | pnpm playground | vite --config playground/vite.config.ts | Start the playground dev server | | pnpm dev | tsup --watch | Build the library in watch mode | | pnpm build | tsup | Production build | | pnpm clean | rm -rf dist | Remove build artifacts | | pnpm lint | eslint src/ | Lint source files | | pnpm playground:build | vite build --config playground/vite.config.ts | Build the playground |

Project Structure

src/
├── components/       # UI components (Button, etc.)
├── design-system/
│   ├── scss/         # SCSS variables, mixins, global styles
│   └── tokens/       # Design tokens (colors, spacing, typography)
├── lib/              # Utilities (cn, twMerge)
├── styles/           # Global style entry point
└── types/            # TypeScript type declarations

playground/           # Vite app for testing components locally

Installation (for consumers)

npm i @alsaeedfayed/sa-ui-lib

Usage in Next.js Apps

1. Import styles in your layout

// app/layout.tsx
import "@alsaeedfayed/ui-lib/styles";

2. Extend your Tailwind config

// tailwind.config.ts
import uiLibConfig from "@alsaeedfayed/ui-lib/tailwind.config";

const config = {
  presets: [uiLibConfig],
  content: [
    "./app/**/*.{ts,tsx}",
    "./node_modules/@alsaeedfayed/ui-lib/dist/**/*.{js,mjs}",
  ],
};

export default config;

---------------------------------------------------------

usage in next15

1-global.css

@import "tailwindcss" prefix(wm);

/_ Load theme (colors, fonts, spacing) from the UI lib's tailwind preset _/
@config "../../tailwind.config.ts";

/_ Scan the UI lib's compiled JS so Tailwind picks up classes like wm:bg-primary _/
@source "../../node_modules/@alsaeedfayed/sa-ui-lib/dist";

2-app.tsx

import "@/styles/globals.css";
import "@alsaeedfayed/sa-ui-lib/styles";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

3-tailwind.config.ts

import type { Config } from "tailwindcss";
import uiLibConfig from "@alsaeedfayed/sa-ui-lib/tailwind.config";

const config: Config = {
  presets: [uiLibConfig],
  content: [
    "./src/pages/**/*.{ts,tsx}",
    "./src/components/**/*.{ts,tsx}",
    "./node_modules/@alsaeedfayed/sa-ui-lib/dist/**/*.{js,mjs}",
  ],
};

export default config;

4- start using components and classes

import { Button } from "@alsaeedfayed/sa-ui-lib";

export default function Home() {
  return (
    <div>
      Home
      <Button variant="primary" size="lg">
        Click Me
      </Button>
      <Button className="wm:w-full" variant="destructive" size="md">
        Delete Me
      </Button>
      <button className="wm:bg-primary wm:text-shadow-add-blue wm:p-2.5 wm:rounded-lg wm:shadow-md wm:shadow-blue-500/50 wm:hover:bg-primary/80 wm:active:bg-primary/90">
        Default
      </button>
    </div>
  );
}

--------------------------------------------------------

3. Use components

import { Button } from "@alsaeedfayed/ui-lib";

export default function Page() {
  return (
    <Button variant="primary" size="lg">
      Save to Cart
    </Button>
  );
}

4. Use design tokens directly

import { colors, spacing } from "@alsaeedfayed/ui-lib/design-system";

const style = { color: colors.primary.DEFAULT, padding: spacing[4] };

5. Use SCSS variables in your app

@use "@alsaeedfayed/ui-lib/src/design-system/scss/variables" as wm;
@use "@alsaeedfayed/ui-lib/src/design-system/scss/mixins" as wm-mix;

.my-component {
  color: wm.$color-primary;
  @include wm-mix.focus-ring(wm.$color-primary);
}