@astralui/core

v0.1.10

Published

9 days ago

AstralUI - a self-contained, dependency-free React design system: theme engine (light/dark + per-brand theming), design tokens, and components (Modal, Drawer, Select, Menu, Toast, DateInput, PinInput, Spinner).

Downloads

1,727

0High
0Medium
0Low

unboundedtechnologiesinc

react design-system ui components theme dark-mode astralui

AstralUI

A self-contained React design system - theme engine, design tokens, and a set of dependency-free UI components. No CSS-in-JS runtime: just CSS variables + light-dark() and small, focused components.

🎨 Theme tokens - a full color palette + semantic tokens as --astral-* CSS variables, light & dark.
🌗 Color scheme - ColorSchemeProvider / useColorScheme (persisted, data-astral-scheme on <html>).
🖌️ Per-brand theming - AstralThemeProvider generates a brand palette from a single hex and injects per-scheme overrides at runtime (with live preview).
🧩 Components - AstralModal, AstralDrawer, AstralSelect, AstralMenu, AstralPinInput, AstralToaster + notifications, DateInput, Spinner, Collapsible.
🌌 Backgrounds - SpaceBackground (animated starfield) and GridBackground (masked technical grid) for auth screens, heroes, and splash pages.
📊 Charts - dependency-free, prop-driven Sparkline, Delta, Donut, FunnelBars, StackedBars (pure SVG + CSS, theme-aware).
🔐 Auth surface - AuthShell / AuthCard + au-auth-* classes for sign-in / sign-up / verify / onboarding screens.
❓ ConfirmModal - a confirmation/alert dialog (with a danger variant) built on AstralModal.

▶ Live playground · Documentation · npm

Install

pnpm add @astralui/core
# peer deps (you almost certainly already have these):
pnpm add react react-dom @tabler/icons-react

Setup

Import the stylesheet once (e.g. in your entry file), then wrap your app:

import '@astralui/core/styles.css';
import { ColorSchemeProvider, AstralThemeProvider, AstralToaster } from '@astralui/core';

function Root() {
  return (
    <ColorSchemeProvider defaultScheme="dark">
      <AstralThemeProvider colors={orgBrandColors /* optional */}>
        <AstralToaster />
        <App />
      </AstralThemeProvider>
    </ColorSchemeProvider>
  );
}

Color scheme

import { useColorScheme } from '@astralui/core';

function ThemeToggle() {
  const { colorScheme, toggle } = useColorScheme();
  return <button onClick={toggle}>{colorScheme === 'dark' ? '🌙' : '☀️'}</button>;
}

Per-brand theming

Pass any subset of brand colors; AstralUI builds a 10-shade palette (via generateColors) and overrides the tokens per scheme. Omit colors for the default look.

<AstralThemeProvider colors={{
  primary_color: '#7950f2',
  background_color: '#141417', card_color: '#1c1c20', navbar_color: '#0e0e11', font_color: '#f4f4f5',
  light_primary_color: '#0f766e', light_background_color: '#f5f7fa', /* ...light_* */
}}>

For a live editor, useThemePreview().setPreview(partialColors) applies instantly without persisting.

Notifications

import { notifications } from '@astralui/core';

const id = notifications.show({ message: 'Saved', color: 'green' });
notifications.show({ id: 'x', message: 'Working…', loading: true, autoClose: false });
notifications.update({ id: 'x', message: 'Done', color: 'green', loading: false, autoClose: 2000 });

Components (quick reference)

| Export | What | |---|---| | AstralModal / AstralDrawer | Portalled, centered modal / right drawer (escape + click-outside). | | AstralSelect | Single-select combobox (searchable / clearable / creatable). | | AstralMenu | Anchored dropdown menu (items array). | | AstralPinInput | Code/OTP input. | | DateInput | Freeze-proof native date / datetime-local input. | | Spinner | Theme-aware loading spinner. | | notifications + AstralToaster | Toast system. | | SpaceBackground | Animated cosmic backdrop with a twinkling starfield (wrap your content as children). | | GridBackground | Subtle technical grid with a brand-tinted glow, edge-masked. | | Sparkline / Delta | Inline KPI sparkline; period-over-period delta badge. | | Donut / FunnelBars / StackedBars | Interactive, linked-hover charts (pure SVG + CSS). | | AuthShell / AuthCard | Centered auth/onboarding layout on a cosmic or wash backdrop. | | ConfirmModal | Confirmation dialog (supports a danger variant). | | Avatar | Image avatar with an initials fallback (brand gradient). | | StatusBadge | Status pill (dot + label), prop-driven color + filled. | | SearchInput | Clearable search field (leading icon + clear button). | | Collapsible | Folding panel that animates open AND closed (measured max-height + chevron). | | generateColors(hex) | 10-shade palette from one color. |

Token reference

All colors resolve through --astral-color-*, --astral-primary-color-*, --astral-font-family, and the app surface vars --astral-app-bg/-nav/-card. Use them directly in your own CSS, e.g.:

.thing { background: var(--astral-color-body); color: var(--astral-color-text);
         border: 1px solid var(--astral-color-default-border); }

Local development

pnpm install
pnpm build       # → dist/ (ESM + CJS + types + styles.css)
pnpm typecheck

To use a local build in another project without publishing: pnpm link --global here, then pnpm link --global @astralui/core in the consumer (or a file: dependency).

Releasing

Versioned on npm as @astralui/core. CI builds + type-checks every push; publishing a GitHub Release (v*) publishes to npm via the publish workflow using npm Trusted Publishing (OIDC) - no token or secret. One-time setup on npmjs.com: the package's Settings -> Trusted Publisher -> GitHub Actions, repo UnboundedTechnologies/AstralUI, workflow publish.yml. The very first publish is done manually (npm publish --access public) since the trusted publisher is configured on an existing package.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme