Naqa UI

Naqa UI is a lightweight, themeable, and modular component library built with React, TypeScript, and CSS Modules. Designed for performance and full tree-shaking support.

Playground

Explore the components and their variations in our interactive Storybook.

✨ Features

• 🌈 Themeable with CSS Variables via Vanilla Extract
• ⚡ Optimized for tree shaking and modular imports
• 🧩 Independent, co-located components
• 🎨 Customizable themes (colors, fonts, etc.) via ThemeProvider
• 🧪 Tested with Jest and Playwright
• 📚 Storybook support

📦 Installation

yarn add @alifsabrani/naqa-ui

🧑‍💻 Usage

Required Global Styles

To ensure your UI kit's components and utility classes render correctly, you must import the core stylesheet into your application's entry point (e.g., main.tsx or App.tsx). This is especially important for frameworks that use Server-Side Rendering (SSR), such as Next.js.

Due to the nature of SSR, CSS styles generated via JavaScript are not available when the initial HTML is rendered on the server. By directly importing the style.css file, you ensure that all the necessary base styles, theme variables, and utility classes are available from the start, preventing layout shifts (FOUC - Flash of Unstyled Content) and ensuring a consistent user experience.

// src/main.tsx or src/_app.tsx
import '@alifsabrani/naqa-ui/style.css';

// ... rest of your code

Basic Usage

import { Button } from '@alifsabrani/naqa-ui/Button';

export default function App() {
  return (
    <Button variant="fill" color="primary">
      Click Me
    </Button>
  );
}

Apply Theme

import { ThemeProvider } from '@alifsabrani/naqa-ui/ThemeProvider';
import { defaultTheme } from '@alifsabrani/naqa-ui/styles/theme.css';

export default function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  );
}

Custom Theme

import { ThemeProvider } from '@alifsabrani/naqa-ui/ThemeProvider';

const customTheme = {
  color: {
    primary: '#5b7cfa',
    primaryHover: '#3f62e2',
    secondary: '#ffd275',
    secondaryHover: '#fcbf49',

    background: '#f9f9fb',
    surface: '#ffffff',
    elevation: '#f1f3f8',

    text: {
      primary: '#1f1f1f',
      secondary: '#555c66',
      muted: '#848b98',
    },

    border: '#e2e4ea',
    shadow: 'rgba(0, 0, 0, 0.05)',

    warning: '#f5a623',
    warningHover: '#e0931e',
    error: '#e74c3c',
    errorHover: '#c0392b',
    info: '#3498db',
    infoHover: '#2980b9',
    success: '#2ecc71',
    successHover: '#27ae60',
    dark: '#2c3e50',
    darkHover: '#1e2b3a',
    light: '#ecf0f1',
    lightHover: '#d5d9dc',
  },
  font: {
    sans: `'Inter', 'Helvetica Neue', Arial, sans-serif`,
    mono: `'Fira Code', monospace`,
    serif: `'Lora', Georgia, serif`,
    display: `'Poppins', 'Inter', sans-serif`,
    size: {
      xs: '0.75rem',
      sm: '0.875rem',
      md: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
      h2: '1.5rem',
      h1: '1.875rem',
      h0: '2.5rem',
      display: '3.5rem',
      icon: {
        sm: '1.25rem',
        md: '1.5rem',
        lg: '1.875rem',
        xl: '2.5rem',
      },
    },
    lineHeight: {
      tight: '1.2',
      normal: '1.5',
      relaxed: '1.75',
    },
    weight: {
      regular: '400',
      medium: '500',
      semibold: '600',
      bold: '700',
    },
  },
  radius: {
    sm: '4px',
    md: '8px',
    lg: '16px',
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    lg: '24px',
    xl: '32px',
  },
  zIndex: {
    dropdown: 1000,
    sticky: 1020,
    fixed: 1030,
    backdrop: 1040,
    modal: 1050,
    popover: 1060,
    tooltip: 1070,
  },
};

export default function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

🎨 Utility Classes

Your UI kit also provides a set of lightweight, global utility classes to help you quickly apply common styles like spacing, flexbox layouts, and colors without writing custom CSS.

How to Use

Simply include the naqa-ui-utilities.css file in your project, and ensure that your theme.css variables are available. These classes are prefixed with nq- to prevent naming conflicts with other libraries or your own styles.

Example HTML:

<div class="nq-d-flex nq-flex-col nq-gap-sm nq-p-md nq-bg-surface nq-rounded-md nq-shadow">
  <p class="nq-text-primary nq-m-0">Card Title</p>
  <p class="nq-text-secondary nq-m-0">This is a card built with utility classes.</p>
</div>

| Category | Prefix | Example Class | Description | | :---------- | :------------------ | :-------------- | :------------------------------------------------------------------------- | | Spacing | nq-p-, nq-m- | nq-p-md | Applies padding or margin based on the spacing scale. | | Flexbox | nq-d-flex, nq-flex- | nq-d-flex | Sets display: flex;. Other classes control direction, alignment, and gaps. | | Text | nq-text- | nq-text-center | Controls text alignment. | | Colors | nq-text-, nq-bg- | nq-text-primary | Applies text or background colors from the theme. | | Borders | nq-rounded- | nq-rounded-md | Applies border-radius from the theme. | | Shadows | nq-shadow | nq-shadow | Applies a standard box shadow. |

📚 Storybook

Run Storybook locally to explore and test components:

yarn storybook

🧪 Testing

Run tests using:

yarn test

📜 License

MIT © Alif Sabrani