@nova-design-system/nova-webcomponents

v3.37.0

Published

5 days ago

Nova is a design system created by Elia Group to empower creators to efficiently build solutions that people love to use.

0High
0Medium
0Low

Nova Web Components (Vanilla)

Use Nova’s native Web Components directly in plain HTML/TypeScript without a framework. This package exposes the same UI components used across all Nova wrappers, ready to drop into any site or app.

Nova Web Components (Vanilla)

Key Points

Tailwind CSS is required. Nova’s CSS-only Tailwind plugin binds Nova design tokens to Tailwind’s utilities for consistent, token-driven styling.
Do not import nova-utils.css when using Tailwind. The Tailwind pipeline produces a smaller, optimized bundle and richer utilities.
Import exactly one token CSS file (spark.css or ocean.css) so the underlying CSS variables exist at runtime.

Installation

Install the required packages:

npm install @nova-design-system/nova-webcomponents @nova-design-system/nova-base

yarn add @nova-design-system/nova-webcomponents @nova-design-system/nova-base

In some cases, you might experience SSL certificate issues when working on Developers' VM. As documented in the Developers' setup guide, you need to turn off the SSL certificate verification:
npm config set strict-ssl false

Setting up Tailwind

Nova Web Components rely on Tailwind for all of the utility classes. The Nova CSS plugin maps Nova’s tokens into Tailwind’s system and generates utilities that resolve to token-backed CSS variables at runtime.

Tailwind version This guide targets Tailwind v4.

About Tailwind and the Nova Plugin

What is Tailwind? A utility‑first CSS framework with low‑level, composable classes (flex, grid, spacing, color, typography) to quickly build UIs.
Nova Tokens: Nova ships design tokens as CSS variables (Spark/Ocean themes) for colors, spacing, typography, radii, shadows, etc.
Integration: @nova-design-system/nova-base/theme/plugin.css wires Nova tokens into Tailwind’s theme scales and emits utilities and variants that read those variables at runtime.
Why import tokens CSS? Import one of spark.css or ocean.css so the CSS variables exist. Tailwind utilities produced by the Nova plugin reference these variables.

1. Install Tailwind CSS

This example uses Vite, but there are multiple ways to set up Tailwind with your project. See the Tailwind documentation for more information.

npm install -D tailwindcss @tailwindcss/vite

Tip: Install the Tailwind CSS IntelliSense VS Code extension for autocomplete on Tailwind and Nova tokens.

2. Configure Vite

vite.config.ts:

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

3. Configure Tailwind and Nova in your CSS

Create a global CSS file (for example, src/index.css) and import Tailwind, the CSS-only Nova plugin, and exactly one token theme:

@import 'tailwindcss';
@import '@nova-design-system/nova-base/theme/plugin.css';
@import '@nova-design-system/nova-base/dist/css/spark.css';
/* Or import ocean.css instead of spark.css. */

No tailwind.config file, @config, @plugin, or separate JavaScript theme import is required. Do not combine theme/plugin.css with nova-utils.css.

4. Register components

Create src/setup.ts (or main.ts):

import './index.css'

// Register Nova Web Components
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader'
defineCustomElements()

5. Use components in HTML with Tailwind utilities

index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Nova Web Components</title>
    <script type="module" src="/src/setup.ts"></script>
  </head>
  <body class="min-h-screen flex items-center justify-center bg-background text-foreground">
    <!-- Layout with Tailwind utilities; styling flows into nv-* hosts (no shadow) -->
    <div class="flex flex-col items-center gap-4 p-6 rounded-md shadow-sm">
      <h1 class="text-2xl font-semibold">Nova Button</h1>
      <nv-button id="counter" danger>Click me</nv-button>
    </div>

    <script type="module">
      const button = document.getElementById('counter');
      let count = 0;
      button.addEventListener('click', () => {
        count += 1;
        button.textContent = `Count is ${count}`;
      });
    </script>
  </body>
</html>

Use Tailwind utilities to create layouts (e.g., flex, grid, gap-*, p-*, m-*).
Apply utilities directly to nv-* elements and surrounding/ slotted content to customize spacing and appearance.
Consolidate repeated class patterns with Tailwind’s @apply in your own CSS utilities when useful.

Dark mode

Enable dark mode by adding the dark class on the body (or a root container):

<body class="dark">
  <!-- content -->
</body>

Deprecated JavaScript configuration

The JavaScript theme and plugin remain available for backward compatibility. Do not combine this setup with theme/plugin.css.

tailwind.config.ts:

import type { Config } from 'tailwindcss'
import { novaTailwindTheme } from '@nova-design-system/nova-base/theme'

export default {
  theme: novaTailwindTheme,
} satisfies Config

src/index.css:

@import 'tailwindcss';
@import '@nova-design-system/nova-base/dist/css/spark.css';

@config '../tailwind.config.ts';
@plugin '@nova-design-system/nova-base/theme/plugin';
@custom-variant dark (&:where(.dark, .dark *));

Nova Font Pro Integration

[!WARNING] Nova Fonts is a protected asset and is not included in the Nova Base package. You need to include the Nova Fonts CSS file in your project. To get the Nova Fonts URL, please contact us via Teams or get the URL in the Nova Design System internal wiki.

Once you have the URL, integrate it using one of the following:

Import in global CSS (recommended):

/* e.g., in src/index.css */
@import url('contact-us-for-URL/nova-fonts-pro.css');

Link in HTML:

<link rel="stylesheet" href="contact-us-for-URL/nova-fonts-pro.css" />

The nova-fonts-pro.css file includes font-face definitions and a body { font-family: ... } rule to apply fonts across your application.