nova-design-system/README.md

Nova Design System (NDS)

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.

---

Table of Contents

1. Overview
2. Project Status
3. Core Principles
4. Available Components
5. Design Tokens
6. Installation
7. Usage
8. Development
9. 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.2.1. 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.