Neptune Design System

Design tokens, components, and styles for Neptune DXP Cockpit 2.0.

Published as @inversestudio/neptune-components on npm.

Live Links

| App | Link | |-----|------| | Component Showcase | neptune-design-system.vercel.app | | Health Dashboard | invstd.github.io/neptune-design-system |

Installation

npm install @inversestudio/neptune-components

Import components

import { Button, Panel, Badge, TabBar } from "@inversestudio/neptune-components";

Import styles

Add once in your app entry CSS:

@import "@inversestudio/neptune-components/css";

This brings in all design tokens and component styles.

For incremental adoption, import the tokens plus only the categories you use:

@import "@inversestudio/neptune-components/tokens";   /* required */
@import "@inversestudio/neptune-components/css/base";  /* shared primitives */
@import "@inversestudio/neptune-components/css/inputs";
@import "@inversestudio/neptune-components/css/feedback";

Categories: base, inputs, navigation, layout, feedback, data-display, overlays.

TypeScript

The package ships generated .d.ts declarations — no @types install and no hand-written shims needed. Components expose typed props and refs:

import { Button } from "@inversestudio/neptune-components";
const ref = useRef<HTMLButtonElement>(null);
<Button ref={ref} variant="primary" onClick={() => {}}>Save</Button>;

Toasts

import { ToastProvider, useToast } from "@inversestudio/neptune-components";

// Wrap once:
<ToastProvider position="bottom-right"><App /></ToastProvider>;

// Then anywhere:
const toast = useToast();
toast.success("Saved");
toast.error("Could not save", { duration: 6000 });

What's Included

33 Components

| Category | Components | |----------|------------| | Inputs (12) | Button, IconButton, IconToggle, Toggle, Checkbox, TextInput, SuggestionPill, PillSelect, NaiaChatInput, NaiaSendButton, FilterBar, PropertyField | | Navigation (5) | TabBar, SidebarNav, SidebarTabs, Dropdown, Breadcrumb | | Layout (5) | AppHeader, Toolbar, BottomBar, Panel, Card | | Feedback (5) | Badge, StatusIndicator, StatusDot, ChatMessage, Avatar | | Data Display (5) | DataTable, FileTree, KpiCard, VersionRow, AppPreview | | Overlays (1) | Modal |

Design Tokens

All tokens use the --npt- prefix:

• 9 color palettes x 19 steps (50-950): plum, orange, purple, lavender, green, red, coral, neutral, aubergine
• 4 themes: base-light, base-dark, naia-light, naia-dark
• Spacing, typography, radius, shadows, motion

4-Theme System

| Theme | Selector | Accent | |-------|----------|--------| | Base light | :root | Orange | | Base dark | .dark | Orange | | Naia light | [data-theme="naia"] | Purple | | Naia dark | .dark [data-theme="naia"] | Purple |

Naia is a theme, not a component variant. Apply data-theme="naia" on a container and all components inside adopt purple accents automatically.

Package Exports

import { Button, ToastProvider, useToast } from "@inversestudio/neptune-components"; // components + hooks (typed)
import { t } from "@inversestudio/neptune-components/shared";       // Utilities
import "@inversestudio/neptune-components/css";                     // Tokens + all component styles
import "@inversestudio/neptune-components/tokens";                  // Tokens only (migration path)
import "@inversestudio/neptune-components/styles";                  // All component styles only
import "@inversestudio/neptune-components/css/inputs";              // One category's styles

TypeScript declarations ship with the package; see CHANGELOG.md for release notes.

Per-component prop types are exported, too:

import type { ButtonProps, TextInputProps } from "@inversestudio/neptune-components";

Tree-shaking

Components are side-effect-free ("sideEffects": ["**/*.css"]), so unused components are eliminated by modern bundlers. You can also import a single component by subpath to keep dependency graphs tight:

import Button from "@inversestudio/neptune-components/components/inputs/Button.jsx";

CSS is opt-in and orthogonal — pull in only the categories you use (see Import styles).

Icons

Components that take an icon accept any ReactNode, so you can pass your own icon set:

import { Button } from "@inversestudio/neptune-components";
import { MyIcon } from "./icons";
<Button icon={<MyIcon />}>Save</Button>;

lucide-react is the peer dependency the showcase uses, but it is not required for consuming components — bring your own icons where an icon prop is exposed.

Licensed Customer

This is proprietary software (see LICENSE.md); publication to npm does not grant a right to use it. Under the commercial grant, Neptune Software GmbH product teams are licensed to use and integrate it in their products (the "Neptune Products"), including in production, and may modify the source for integration. For procurement and legal, a plain-language summary is in docs/license-faq.md. Licensing inquiries: [email protected].

Repository Structure

neptune-design-system/
├── tokens/                     # CSS + JSON design tokens
├── components/                 # 33 components across 6 categories
├── neptune-components.css      # All component styles (BEM)
├── registry.json               # Component metadata & drift tracking
├── inbox/                      # Designer contribution inbox
├── scripts/                    # Drift check, build, DESIGN.md generation
├── preview/                    # Vite app for Vercel showcase deployment
├── dashboard/                  # Health dashboard (GitHub Pages)
├── CLAUDE.md                   # Agent conventions
└── DESIGN.md                   # Auto-generated portable reference (see below)

Contributing Components

Via the Inbox Workflow

1. Create a branch: inbox/add-datepicker
2. Copy inbox/TEMPLATE.md to inbox/DatePicker/brief.md and fill it out
3. Drop a rough inbox/DatePicker/DatePicker.jsx next to it
4. Open a PR targeting main

The inbox processor agent formalizes the component automatically (proper BEM CSS, token usage, registry entry, showcase integration). The DS maintainer reviews and merges.

Conventions

• Token-only styling — never hardcode colors; use --npt-* tokens
• CSS-first states — :hover, :focus-visible, :disabled in CSS, not React state
• BEM naming — .neptune-button, .neptune-button--primary
• All 4 themes — components must work across all theme modes
• WCAG AA — minimum 4.5:1 contrast for text, 3:1 for interactive elements

See CLAUDE.md for the full guide.

DESIGN.md

DESIGN.md is an auto-generated portable reference file containing all tokens, component metadata, and theme documentation in markdown tables. It is generated from registry.json and tokens/neptune-design-tokens.css by scripts/generate-design-md.js.

• Do not edit manually — changes will be overwritten
• CI enforces freshness — the design-system-check workflow fails if DESIGN.md drifts from source
• Lives only in this repo — the prototype repo does not keep a copy (its Claude Code skills read registry.json directly for live data)

To regenerate: npm run generate:design-md

AI Rules

This repo ships rules for AI coding assistants. Both sets cover the same conventions — pick the one matching your tool.

| Tool | Location | Format | |------|----------|--------| | Claude Code | CLAUDE.md | Single file, auto-loaded | | Cursor | .cursor/rules/*.mdc | Glob-scoped rule files |

If you update conventions in one, update the other to keep them in sync.

CI/CD

| Workflow | Trigger | Purpose | |----------|---------|---------| | Drift Check | PR | Validates token usage, registry sync, state compliance | | Reconciliation | Merge to main | Auto-fixes drift via Claude agent | | Weekly Audit | Sunday 2am UTC | Full audit, creates issue if drift found | | Inbox Processor | PR touching inbox/ | Formalizes rough components | | Publish | Git tag v* | Publishes to npm | | Dashboard | Merge to main | Deploys health dashboard to GitHub Pages |

Versioning

| Change | Version bump | |--------|-------------| | New component | Minor | | Bug fix / token drift fix | Patch | | Breaking change (removed prop, renamed component) | Major | | Token-only update | Minor |

The package version (package.json, npm, Git tags) is the source of truth for releases — see CHANGELOG.md. The version field inside registry.json is a separate registry-schema version and is not expected to track the package version. CI enforces that each package version has a matching CHANGELOG entry (npm run check:changelog).

Tag a release to publish: git tag v1.1.0 && git push origin v1.1.0

Scripts

npm run dev                  # Preview app dev server
npm run build                # Build preview for deployment
npm run check:drift          # Run drift check (JSON)
npm run check:drift:md       # Run drift check (Markdown)
npm run generate:design-md   # Regenerate DESIGN.md
npm run check:design-md      # Verify DESIGN.md is current (CI)