hfn-core-components

The official React design system of Heartfulness Institute — a global meditation movement that has reached millions of practitioners across 160+ countries.

Built on React 18/19, Radix UI, Tailwind CSS v4, and TypeScript. Documented with Storybook 8.

Why this exists

Heartfulness teams ship dozens of properties — donation portals, registration flows, retreat sites, mobile apps — across many languages and brand variants. This library gives every team:

• Accessible defaults — Radix-grounded components that pass keyboard, screen-reader, and contrast checks out of the box.
• Themable tokens — six built-in brand themes (primary, teal, secondary, burgundy, warm, black) plus CSS-custom-property hooks for one-off variants.
• Composable building blocks — from low-level primitives (HFNButton, HFNInputText) up to feature blocks (HFNDynamicForm, HFNContactForm, HFNDataTable).
• A meditation-friendly content model — HFNAudio and HFNVideo accept transcripts and caption tracks because guided meditations must be reachable to Deaf and hard-of-hearing meditators.

Install

The package is published to AWS CodeArtifact. Authenticate once per machine:

aws codeartifact login --tool npm \
  --repository HFN_npm_packages \
  --domain hfnnpm \
  --domain-owner 502390415551 \
  --region ap-south-1

Then install:

npm install hfn-core-components

Peer dependencies. This library lists React and the Radix primitives as peer dependencies. On npm 7+ they are auto-installed; on older npm you must install them yourself.

Requires Node 20+.

Quick start

// 1. Import the bundled stylesheet once, near your app entry.
import 'hfn-core-components/css';

// 2. Import components by name.
import {
  HFNButton,
  HFNToaster,
  useToast,
  ThemeProvider,
} from 'hfn-core-components';

export function App() {
  const toast = useToast();

  return (
    <ThemeProvider>
      <HFNButton onClick={() => toast.success('Welcome 🙏')}>
        Begin meditation
      </HFNButton>
      <HFNToaster />
    </ThemeProvider>
  );
}

Components

Storybook is the source of truth — run npm run storybook (or visit the team-hosted preview, link in #design-system Slack).

Core HFNButton, HFNInputText, HFNTextarea, HFNSelect, HFNAutocomplete, HFNCityAutocomplete, HFNCheckbox, HFNRadioGroup, HFNToggle, HFNSlider, HFNInputOtp, HFNPhoneInput, HFNInputCalendar, HFNModal, HFNDrawer, HFNAlertModal, HFNConfirmDialog, HFNTooltip, HFNToaster, HFNAccordion, HFNTab, HFNStepper, HFNBreadcrumb, HFNBadge, HFNAvatar, HFNCard, HFNCarousel, HFNDataTable, HFNHeader, HFNFooter, HFNSidebar, HFNSkeleton, HFNHeading, HFNSubHeading, HFNContent, HFNImage, HFNImageGallery, HFNAudio, HFNVideo, HFNIcon, HFNFAQ.

Blocks (composed patterns) HFNContactForm, HFNDynamicForm, HFNDonationCard, HFNNewsCard, HFNProfileCard, HFNProductCard, HFNEventCard, HFNPressRelease, HFNPrinciplesGrid.

Hooks & utilities useToast, useFetchOptions, useDebounce, useIsMobile, useTheme, cn, fetchData.

Theming

Theme tokens are CSS custom properties defined in dist/hfncore.css. Switch themes by setting [data-theme] on a parent element, or by using <ThemeProvider> for runtime swaps:

<ThemeProvider>
  <App />
</ThemeProvider>

Built-in themes: theme-primary (blue), theme-teal, theme-secondary (purple), theme-burugundy, theme-warm, theme-black.

To override individual tokens for a deployment, set them on :root after importing the stylesheet:

:root {
  --hfn-sidebar-item-bg-active: #fce7f3;
  --theme-color-primary: #db2777;
}

Accessibility

This library targets WCAG 2.2 AA as a baseline.

• All interactive components forward keyboard focus and expose accessible names.
• HFNAudio and HFNVideo accept captions (WebVTT tracks) and transcript (text alternative) so guided meditations can be consumed by Deaf and hard-of-hearing users.
• HFNButton defaults to type="button" to avoid accidental form submissions.
• HFNInputText wires aria-invalid and aria-describedby to error messages.
• HFNToaster's viewport is a polite live region — toasts are announced.
• HFNDataTable exposes aria-sort, aria-selected, and live-region selection counts.

If you find an a11y regression, please open an issue.

Contributing

git clone <repo-url>
cd hfn-design-system
npm install
npm run storybook       # http://localhost:6006
npm run build:lib       # build the package
npm run lint

We use Husky + lint-staged on pre-commit. Conventional commit messages are appreciated.

License

Proprietary — © Heartfulness Institute. Internal use only.