@alsaeedfayed/ui-test-lib

Design System package — design tokens (colors, spacing, radii, shadows), SCSS mixins, Tailwind CSS configuration, and React components (Button, Card, Input).

Built to be installed across microfrontend apps so every app shares the same visual language.

Architecture

The design system has 3 layers that chain together:

SCSS Tokens (_colors.scss, _sizes.scss)
    ↓  raw values ($color-primary: #6366f1)
CSS Custom Properties (global.css)
    ↓  runtime bridge (--ebs-primary: #6366f1)
Tailwind Config (tailwind.config.js)
    ↓  class names (bg-primary → var(--ebs-primary) → #6366f1)
React Components (Button, Card, Input)

• SCSS tokens — source of truth, usable via @use in .scss files
• CSS custom properties — bridge tokens to the browser, enable runtime theming
• Tailwind config — maps CSS vars to utility classes like bg-primary, text-muted-foreground, rounded-lg
• React components — pre-built UI components using the above tokens via Tailwind

Project Structure

src/
├── components/
│   ├── Button/          # CVA-based button (6 variants, 4 sizes)
│   ├── Card/            # Card + CardHeader, CardTitle, CardDescription, CardContent, CardFooter
│   └── Input/           # Input with label and error support
├── lib/
│   └── utils.ts         # cn() helper (clsx + tailwind-merge)
├── tokens/
│   ├── _colors.scss     # Color tokens (brand, neutral, semantic, surface)
│   └── _sizes.scss      # Spacing, radii, font sizes, weights, shadows, transitions
├── mixins/
│   └── _index.scss      # SCSS mixins (flex-center, card, focus-ring, button-base, etc.)
├── styles/
│   └── global.css       # CSS custom properties (:root vars)
└── index.ts             # Package entry point

playground/               # Local dev playground (not published)
tailwind.config.js        # Shared Tailwind theme config (published)
tsup.config.ts            # Build config

Scripts

# Install dependencies
pnpm install

# Build the package (CJS + ESM + types + CSS)
pnpm build

# Build in watch mode during development
pnpm dev

# Run the playground (live demo at http://localhost:3100)
pnpm playground

# Build the playground for static hosting
pnpm playground:build

# Type-check without emitting
pnpm lint

# Remove dist folder
pnpm clean

Publishing

The package is published publicly to npmjs.com under the @alsaeedfayed org.

# Make sure you're logged in
npm whoami

# Build first
pnpm build

# Publish (access: public is configured in package.json)
npm publish --access public

# To publish a new version, bump the version first
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0
npm publish --access public

Usage in Microfrontend Apps

1. Install

npm install @alsaeedfayed/ui-test-lib

2. Import the global CSS (required)

This loads the CSS custom properties that power all the tokens:

// In your app's entry file (main.tsx or App.tsx)
import "@alsaeedfayed/ui-test-lib/styles";

3. Extend your Tailwind config

// tailwind.config.js
const libConfig = require("@alsaeedfayed/ui-test-lib/tailwind");

module.exports = {
  content: [
    "./src/**/*.{ts,tsx}",
    // Scan the library's components so Tailwind generates their classes
    "./node_modules/@alsaeedfayed/ui-test-lib/dist/**/*.{js,mjs}",
  ],
  theme: {
    extend: {
      ...libConfig.theme.extend,
    },
  },
};

4. Use the components

import { Button, Card, CardHeader, CardTitle, CardContent, Input } from "@alsaeedfayed/ui-test-lib";

function MyPage() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Sign In</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input label="Email" type="email" placeholder="[email protected]" />
        <Input label="Password" type="password" />
        <Button className="w-full">Sign In</Button>
        <Button variant="outline" className="w-full">Cancel</Button>
      </CardContent>
    </Card>
  );
}

5. Use SCSS tokens & mixins (optional)

If your app uses SCSS, you can import tokens and mixins directly:

@use "@alsaeedfayed/ui-test-lib/src/tokens" as t;
@use "@alsaeedfayed/ui-test-lib/src/mixins" as m;

.my-component {
  color: t.$color-primary;
  @include m.flex-center;
  @include m.focus-ring;
}

Available Components

Button

<Button>Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon"><Icon /></Button>

<Button disabled>Disabled</Button>

Card

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description text</CardDescription>
  </CardHeader>
  <CardContent>Body content</CardContent>
  <CardFooter>Footer actions</CardFooter>
</Card>

Input

<Input label="Email" type="email" placeholder="[email protected]" />
<Input label="Username" error="Must be at least 3 characters" />
<Input disabled placeholder="Disabled input" />

Design Tokens

Colors

| Token | CSS Variable | Tailwind Class | Value | |-------|-------------|----------------|-------| | $color-primary | --ebs-primary | bg-primary, text-primary | #6366f1 | | $color-secondary | --ebs-secondary | bg-secondary, text-secondary | #0ea5e9 | | $color-destructive | --ebs-destructive | bg-destructive, text-destructive | #ef4444 | | $color-success | --ebs-success | bg-success, text-success | #22c55e | | $color-warning | --ebs-warning | bg-warning, text-warning | #f59e0b | | $color-info | --ebs-info | bg-info, text-info | #3b82f6 | | $color-background | --ebs-background | bg-background | #ffffff | | $color-foreground | --ebs-foreground | text-foreground | #0f172a | | $color-muted | --ebs-muted | bg-muted, text-muted-foreground | #f1f5f9 | | $color-border | --ebs-border | border-border | #e2e8f0 |

Border Radius

| Tailwind Class | CSS Variable | Default Value | |---------------|-------------|---------------| | rounded-lg | --ebs-radius | 0.5rem | | rounded-md | calc(--ebs-radius - 2px) | 0.375rem | | rounded-sm | calc(--ebs-radius - 4px) | 0.25rem |

Peer Dependencies

These must be installed in the consuming app:

• react ^18.2.0
• react-dom ^18.2.0
• tailwindcss ^3.3.0