Nova Design System (NDS) is a lightweight, responsive UI component library built with Astro. It is developed primarily for internal and personal projects, and is publicly available for reference and contributions.

Overview
Project Status
Core Principles
Available Components
Design Tokens
Installation
Usage
Development
License

Overview

NDS provides a focused set of reusable Astro components with centralized design tokens, light/dark theming, and a strong focus on consistency and maintainability. The component documentation and showcase are also built with Astro.

Project Status

ALPHA — The library is under active development. Current version: 1.01.0. Component APIs, token naming, and internal architecture may change before a stable release.

Core Principles

Responsive Architecture: Components are built mobile-first and work correctly across modern screen sizes.
Security-Centric: Unsafe patterns (injection, untrusted rendering) are avoided by design.
Native Theming: All styling relies on centralized design tokens and supports Light and Dark modes.
Type Safety: Written in TypeScript for stronger reliability and a better developer experience.
Consistency First: Shared tokens, naming conventions, and reusable patterns take priority over one-off styles.

Available Components

These are the components currently exported from the package (src/components/index.ts):

Component	Category
`Button`	Actions
`Toggle`	Actions
`NumericStepper`	Actions
`Select` / `SelectOption`	Actions
`TextField`	Forms
`Checkbox`	Forms
`Radio`	Forms
`Tab` / `TabItem` / `TabContent`	Navigation
`Link`	Navigation
`Breadcrumb` / `BreadcrumbItem`	Navigation
`Pagination` / `PaginationNumber`	Navigation
`Navbar`	Navigation
`Sidebar` / `SidebarItem`	Navigation
`Avatar`	Data Display
`Badge`	Data Display
`Card`	Data Display
`ListItem` / `ListItemTitle` / `ListItemSubtitle`	Data Display
`Notification`	Feedback
`LoadingBar`	Feedback
`Tooltip`	Feedback
`Modal`	Overlay

Icons are no longer shipped as standalone NDS components. As of 1.00.3, all icons used internally (e.g. in Select, Avatar, Notification, numericStepper) come directly from the @lucide/astro package. See ATTRIBUTION.md for details.

Design Tokens

All styling is controlled via CSS custom properties prefixed with --nds-, defined in src/styles/tokens/:

File	Contents
`_colors.scss`	Color palette and semantic colors (`success`, `warning`, `error`, `info`)
`_spacing.scss`	Base spacing scale, border radius, and border width
`_typography.scss`	Font families, sizes, and weights

Rules:

Never hardcode colors, spacing, or radii in component styles when a token exists.
Never override tokens locally in component scope unless explicitly supported.
All global token changes must go through the core styling system.

Installation

Requires Node.js >= 22.12.0.

npm install @unkn0wndo3s/nova-design-system

No extra Vite de-optimization configuration is required.

Usage

Import components directly from the package:

---
import { Button } from '@unkn0wndo3s/nova-design-system';
---

<Button>Click me</Button>

---
import { Notification } from '@unkn0wndo3s/nova-design-system';
---

<Notification type="warning">
  This is a warning message.
</Notification>

---
import { Modal } from '@unkn0wndo3s/nova-design-system';
---

<Modal>
  This is a modal dialog.
</Modal>

---
import { Breadcrumb, BreadcrumbItem } from '@unkn0wndo3s/nova-design-system';
---

<Breadcrumb>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/docs">Docs</BreadcrumbItem>
</Breadcrumb>

Development

Clone the repository

git clone https://git.novaprojects.dev/unkn0wn/nova-design-system.git

Install dependencies

npm install

Start the dev server

npm run dev

Useful scripts

npm run build    # Build the project
npm run preview  # Preview the production build

Project Structure

src/
├── components/            # Astro components
│   ├── Avatar/
│   ├── Badge/
│   ├── Breadcrumb/
│   ├── Button/
│   ├── Card/
│   ├── Checkbox/
│   ├── Link/
│   ├── ListItem/
│   ├── LoadingBar/
│   ├── Modal/
│   ├── Navbar/
│   ├── Notifications/
│   ├── numericStepper/
│   ├── pagination/
│   ├── Radio/
│   ├── Select/
│   ├── Sidebar/
│   ├── Tabs/
│   ├── textField/
│   ├── Toggle/
│   ├── Tooltip/
│   └── index.ts
├── layouts/                # Astro layouts
├── pages/                  # Documentation pages
├── styles/
│   ├── tokens/
│   │   ├── _colors.scss
│   │   ├── _spacing.scss
│   │   └── _typography.scss
│   └── index.scss
└── index.ts

Contributing

Contributions are welcome. To report a bug, suggest a feature, or open a Pull Request, follow the repository contribution rules and templates.

NDS no longer maintains a custom set of icon components — icons are sourced from the Lucide icon set via @lucide/astro. If a needed icon isn't in Lucide, open an issue to discuss it before adding any new icon dependency.

License

This project is not distributed under a standard open-source license. Usage, redistribution, commercial use, and derivative work rules are defined in LICENSE.md. Read that file carefully before using the library in a product or service.

README.md

Nova Design System (NDS)

Table of Contents