Projection UI

Yes. Another UI library. React components, shared themes, and a thing for light. You still have to build the app.

Documentation · Component explorer · Give feedback

0.2.0-next.2 is an unpublished candidate. The current documentation is one evolving 0.2.0 edition, marked Alpha. An alpha is a preview that can change before stable release. The screenshots show real components from the packed library. The preview adds glass, edge light, underglow, gradients, and a shared chart palette. The component examples below describe 0.2, while the preserved documentation covers the published 0.1.5 package.

Install from npm

For the published 0.1.x line, install the stable package:

npm install @hannasage/[email protected]

The current stable release is 0.1.5. Use its root imports and preserved documentation for feature dependency requirements. The 0.2 examples below require a 0.2 alpha package.

npm currently has only 0.1.x releases and no next tag. The alpha commands below are post-publication steps and do not work today. After an alpha is published under next, opt in with:

npm install --save-exact @hannasage/projection-ui@next

--save-exact keeps later alpha and stable updates manual. It saves the resolved version instead of a version range.

After 0.2.0-next.2 appears on npm, pin that exact version with:

npm install --save-exact @hannasage/[email protected]

In an existing React 19 application, install one 0.2 Projection UI package. The library manages its chart, drag, and toast dependencies. npm downloads them automatically with the package. React 19 and React DOM 19 stay shared with your application. They are peer dependencies: packages that your application supplies. The alpha does not promise 1.0 API stability. Read the maintenance guide for the separate 0.1 patch path.

Review the candidate locally

Before publication, build and pack the candidate from this repository:

npm ci
npm run build
npm pack

In your application, install the generated tarball with its actual file path:

npm install /path/to/packed-candidate.tgz

Quick start

Import scoped styles once in your application entry. A CSS variable is a named value that styles share. The provider sets those values inside its wrapper.

import '@hannasage/projection-ui/styles'
import { Badge, Button, Card, DEFAULT_THEME, ThemeProvider } from '@hannasage/projection-ui/core'

export default function App() {
  return (
    <ThemeProvider theme={DEFAULT_THEME} style={{ background: 'var(--ui-bg)', color: 'var(--ui-text)', padding: 24 }}>
      <Card border="accent">
        <Badge dot={false}>Example project</Badge>
        <h1>Build with shared components.</h1>
        <Button type="button" variant="primary">Explore example</Button>
      </Card>
    </ThemeProvider>
  )
}

The package selects a font family but does not bundle or download font files. Existing UITheme objects remain compatible. Optional body and display font roles fall back to the existing font field.

Give it your theme

Projection is the default dark theme, with a subtle lime gradient. Coastal Day uses a soft blue shift on pale surfaces. Fernwood keeps the green light palette. PROJECTION_LIGHT_THEME remains an alias for Coastal Day. Your application supplies colors, fonts, and radius through ThemeProvider.

import { Card, COASTAL_DAY_THEME, ThemeProvider } from '@hannasage/projection-ui/core'

export function LightExample() {
  return (
    <ThemeProvider theme={COASTAL_DAY_THEME}>
      <Card material="glass" edgeLight underglow>
        <h2>Keep the light.</h2>
        <p>Content stays clear. The background gets the blur.</p>
      </Card>
    </ThemeProvider>
  )
}

Use PROJECTION_FLAT_THEME or COASTAL_DAY_FLAT_THEME for the main pair with solid surfaces. Coastal Day Flat keeps blue accents. FERNWOOD_FLAT_THEME retains the original green light palette. The theme guide covers custom values and all presets.

Choose an entry

Import	Contents	Package-managed runtime
/core	Theme, foundations, surfaces, actions, forms, modal, skeleton, table, content primitives	None
/charts	AreaChart, BarChart, LineChart, DonutChart	Recharts and react-is
/sortable	SortableList, SortableItem, arrayMove	dnd-kit
/toast	ToastContainer, useToastStore	Zustand
Root	Combined compatibility entry	All feature dependencies

All entries share the application's React 19 and React DOM 19. Feature imports keep their JavaScript isolated; installing the package still downloads its runtime dependencies. You do not install feature packages separately. Read the compatibility guide for tested consumers.

Add a chart

Import the feature you need. The package manages Recharts and its other feature dependencies.

import { BarChart } from '@hannasage/projection-ui/charts'
import { PROJECTION_THEME, ThemeProvider } from '@hannasage/projection-ui/core'

const data = [
  { day: 'Mon', reviews: 4 },
  { day: 'Tue', reviews: 6 },
  { day: 'Wed', reviews: 3 },
]

export function ReviewChart() {
  return (
    <ThemeProvider theme={PROJECTION_THEME}>
      <BarChart
        data={data}
        xKey="day"
        series={[{ key: 'reviews', label: 'Reviews', color: 'var(--ui-primary)' }]}
        title="Example review activity"
        height={220}
      />
    </ThemeProvider>
  )
}

These values are example data. Pair charts with a text summary or table for readers who cannot use the visual. Read the accessibility guide.

Select styles

/styles scopes shared component rules to theme wrappers. /reset supplies explicit page-wide rules. /tokens retains the legacy global rules for existing consumers. Read the migration guide before changing an existing stylesheet import.

Components

Group	Exports
Foundations	ThemeProvider, DEFAULT_THEME, UI_FOUNDATIONS, RADIUS_SCALE, THEME_PRESETS, Projection, Coastal Day, and Fernwood presets
Surfaces and actions	Card, Badge, Button, ButtonGroup, LinkButton, ProjectionGlow
Content	Container, Stack, Prose, Separator, VisuallyHidden
Forms	Input, Select, Textarea, Toggle, Slider
Feedback	Modal, Skeleton, ToastContainer, useToastStore
Data	DataTable
Sorting	SortableList, SortableItem, arrayMove
Charts	AreaChart, BarChart, LineChart, DonutChart
Materials	Surface, GradientBackground, GradientText
Basics	Avatar, Checkbox, RadioGroup, Tabs, Accordion, Alert, Notification, Progress, Spinner, Tooltip, Carousel

The package exports component prop types and UITheme. Toast is a data type, not a React component. Application routes, business data, and 3D scenes belong in consuming applications. ProjectionGlow adds decorative light behind sibling content. It inherits the theme accent and stays still by default. Read the token guide for its optional reveal and reduced-motion behavior.

Read and try the guides

npm run build:docs

The command builds the Fumadocs reader and component explorer from the same installed packed candidate. The static site appears in docs-site/out. The guides cover installation, themes, tokens, accessibility, migration, releases, and community. Every public component has a preview. Read the documentation and use the component explorer for interactive examples. Each reader page has a plain Markdown link. The version selector retains the v0.1.5 documentation and its original source examples. Live examples follow the selected light or dark theme. The explorer includes prop controls, action logs, accessibility scans, keyboard interaction steps, and viewport tools. The paired gallery covers the 49 approved categories in both core themes. It marks application examples as compositions, not separate package exports. The gallery includes a flat appearance selector. The text index links all guides and component contracts.

Read the component reference, theme guide, and development guide. Read the release contract before publication.

Download the matching Figma design kit for editable mockups. Its local importer creates native components, text, variables, and Modern/Flat theme variants. The kit includes its source inventory and the React contracts without a matching design category.

Contribute and give feedback

Use Issues for defects and bounded requests. Use Discussions for questions, examples, and design feedback. Share example needs in the examples discussion. Share upgrade constraints in the preservation discussion. Read CONTRIBUTING.md, FEEDBACK.md, and SECURITY.md for each report path. No response deadline is promised.

License

MIT.