# Nebula Design System
> Nebula is Kaluza's React component library and design system.
> It provides accessible, themeable UI components for building energy retail products.
> Built with TypeScript, React, and styled-components.
Full documentation: https://nebula.kaluza.com
Installation: https://nebula.kaluza.com/get-started/setup
---
## Quick Reference
All components are imported from `@kaluza-platform/nebula`:
```tsx
import { Page, Card, PrimaryCTAButton } from '@kaluza-platform/nebula';
```
Nebula requires a styled-components ThemeProvider at the app root:
```tsx
import { ThemeProvider } from 'styled-components';
import { theme } from '@kaluza-platform/nebula';
;
```
### Page structure
Every app page should use `Page` as the root layout:
```tsx
Page title
{/* Page content here */}
```
### Form structure
Forms use `Form`, `FormFields`, and `FormActions`:
```tsx
```
Fields inside `FormFields`. Buttons inside `FormActions`. Error handling is built in — pass an `errors` array to `Form` and field errors are set automatically via context using each field's `name` prop.
### When to use CTAButton vs CTALink
- `CTAButton` (Primary/Secondary/Destructive) — Performs an action on the current page: submitting a form, opening a modal, deleting an item.
- `CTALink` — Navigates the user to a different page. Renders as an anchor element. Use this even if the link is styled to look like a button.
### When to use DateField vs DatepickerField
- `DateField` — For entering an exact known date by typing (e.g. date of birth). No calendar popup.
- `DatepickerField` — For selecting a date from a calendar popup or by typing (e.g. appointment booking).
### Rules
Rules use this vocabulary: **Always** (required), **Never** (prohibited), **Avoid** (strongly discouraged), **Ensure** (verify before shipping). Full rationale in the linked guides.
#### Forms — https://nebula.kaluza.com/guides/forms
- **Always** ask for only the information you definitely need.
- **Always** give every field a label — never use placeholder text as a label or hint.
- **Always** validate on form submit, not as the user types.
- **Always** display a list of errors at the top of the form using `ErrorSummaryNotification`.
- **Always** use plain, concise language for error messages — avoid pleasantries like "please".
- **Avoid** multi-column form layouts — error-prone and cause abandonment.
- **Avoid** disabling buttons (except while submitting) — creates poor UX and excludes users with disabilities.
- **Never** use HTML default validation — add `novalidate` to the `