@hannasage/projection-ui

Dark-first React component library with consumer-configurable theming. No hardcoded themes — you define your palette, the library renders it.

Installation

npm install @hannasage/projection-ui

Peer dependencies

npm install react react-dom recharts zustand @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

---

Quick start

1. Import the fallback tokens (optional but recommended)

In your entry file (main.tsx or index.tsx):

import '@hannasage/projection-ui/tokens'

This loads a set of CSS custom property defaults. If you wrap your app with ThemeProvider, these are overridden by your theme — but they act as a safe fallback.

2. Define your theme

import type { UITheme } from '@hannasage/projection-ui'

const myTheme: UITheme = {
  bg:        '#07090C',   // page background
  surface:   '#0D1117',   // card / panel
  border:    '#1B2535',   // borders
  text:      '#DDE3EE',   // primary text
  muted:     '#8396AB',   // secondary text / labels
  primary:   '#C9F53A',   // accent — buttons, focus rings
  primaryFg: '#07090C',   // text on top of primary (e.g. button label)
  danger:    '#FF5252',   // destructive actions
  font:      "'IBM Plex Mono', monospace",
  radius:    'soft',      // 'sharp' | 'soft' | 'rounded'
}

Radius presets:

preset	buttons/inputs	cards	pills/toggles
sharp	2px	4px	4px (no pill)
soft	6px	10px	9999px
rounded	16px	24px	9999px

3. Wrap your app

import { ThemeProvider, ToastContainer } from '@hannasage/projection-ui'

export default function App() {
  return (
    <ThemeProvider theme={myTheme}>
      <YourApp />
      <ToastContainer />
    </ThemeProvider>
  )
}

Switching themes is instant — pass a new theme object and all --ui-* CSS variables update automatically.

---

Component reference

Layout

Component	Description
ThemeProvider	Writes CSS vars from your theme. Wrap your app root.
Card	Surface container. Props: padding, border, as, className

Actions

Component	Description
Button	Variants: primary secondary ghost danger. Sizes: sm md lg.
ButtonGroup	Segmented control / tab bar. Mutually exclusive options with optional deselect.

Forms

Component	Description
Input	Text input with label, error, hint, prefix/suffix slots
Select	Styled native select with chevron
Textarea	Resizable textarea with label, error, hint
Toggle	On/off switch. Sizes: sm md
Slider	Range input with fill track, value display, and min/max labels

Feedback

Component	Description
Modal	Accessible dialog. Closes on Escape + backdrop click.
ToastContainer	Notification portal. Use useToastStore().push(message, variant) to trigger.
Skeleton	Shimmer placeholder. Configurable width, height, borderRadius.

Data

Component	Description
DataTable	Sortable columns, loading skeletons, empty state slot, row click handler

Drag and drop

Component	Description
SortableList	Wraps @dnd-kit DndContext + SortableContext
SortableItem	Render-prop item exposing dragHandleProps and isDragging

Charts (Recharts wrappers)

Component	Description
AreaChart	Gradient fill area chart
BarChart	Grouped or stacked bar chart
LineChart	Multi-series line chart
DonutChart	Pie/donut with optional center label slot

All charts accept data, series (array of { key, color, label }), xKey, height, title, xFormatter, yFormatter.

---

Toast usage

import { useToastStore } from '@hannasage/projection-ui'

function MyComponent() {
  const toast = useToastStore(s => s.push)

  return (
    <button onClick={() => toast('Saved!', 'success')}>
      Save
    </button>
  )
}

Variants: info | success | warning | danger

---

Dynamic theming

ThemeProvider is just a div that writes CSS vars — swapping themes is a single state update:

const [theme, setTheme] = useState<UITheme>(darkTheme)

<ThemeProvider theme={theme}>
  <button onClick={() => setTheme(lightTheme)}>Toggle theme</button>
</ThemeProvider>

---

Used in

• financial-projections — personal financial scenario planner (the app this library was extracted from)
• sageadvice-crm — production CRM for a financial advisory practice

---

License

MIT