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.

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 } from "@inversestudio/neptune-components";        // All components
import { t } from "@inversestudio/neptune-components/shared";       // Utilities
import "@inversestudio/neptune-components/css";                     // Tokens + styles
import "@inversestudio/neptune-components/tokens";                  // Tokens only
import "@inversestudio/neptune-components/styles";                  // Component styles only

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 |

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)