@hennge/ui-react

A collection of highly accessible React components implementing the HENNGE One Design System

Features

• Fully accessible components following WAI-ARIA patterns
• Comprehensive theming support for HENNGE One products
• Responsive design and mobile-friendly components
• Built on top of React Aria Components for solid accessibility foundations
• Tailwind CSS integration (optional)

Accessibility Foundation

HENNGE UI React is strategically built on industry-leading accessibility foundations:

• React Aria Components by Adobe: Provides comprehensive ARIA patterns, keyboard navigation, and screen reader support
• Headless UI by Tailwind Labs: Offers accessible primitives with robust interaction patterns

This approach allows our library to deliver a polished visual layer atop these battle-tested accessibility implementations. By leveraging these foundations, HENNGE applications can more easily achieve WCAG 2.1 Level AA compliance.

Benefits of this architecture include:

• Simplified development: Core accessibility patterns have been thoroughly tested by the wider community
• Reduced accessibility barriers: Common accessibility issues are solved at the component level
• Consistent behavior: Interactions work predictably across different browsers and assistive technologies
• Faster compliance: Projects using this library inherit accessibility best practices automatically

Installation

pnpm add @hennge/ui-react

Usage

Basic Setup

Import the CSS in your application entry point:

import "@hennge/ui-react/css";

Although this stylesheet is produced using Tailwind CSS, you DO NOT need Tailwind CSS in your project to use this library.

Using Components

import { Button } from "@hennge/ui-react";

function MyComponent() {
  return (
    <Button intent="primary" size="medium">
      Click Me
    </Button>
  );
}

Tailwind CSS Integration

Project Setup with Tailwind CSS V4

For projects using Tailwind CSS V4, you can integrate HENNGE UI React's styles:

pnpm add -D tailwindcss-react-aria-components

@import "tailwindcss";
@import "@hennge/ui-react/tailwindcss";
@source "../node_modules/@hennge/ui-react";

@source directive compiles HENNGE UI React with your project's Tailwind CSS for optimal bundle size.

Modular Setup with Tailwind CSS V4

For more granular control, you can selectively import specific theme components:

@import "tailwindcss";

/* Removes most colors shipped by Tailwind CSS */
@import "@hennge/ui-react/tailwindcss/unset-colors.css";

/* Imports the default HENNGE One Design System color theme, including fonts */
@import "@hennge/ui-react/tailwindcss/theme-hennge-default.css";

/* Imports the HENNGE One Identity Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-identity.css";

/* Imports the HENNGE One DLP Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-dlp.css";

/* Imports the HENNGE One Cybersecurity Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-cybersecurity.css";

/* Add utility classes used in HENNGE UI React */
@import "@hennge/ui-react/tailwindcss/utilities.css";

/* Add Tailwind CSS support for React Aria Components */
@plugin "tailwindcss-react-aria-components";

/* Compile Tailwind CSS classes used in HENNGE UI React */
@source "../node_modules/@hennge/ui-react";

Font Setup

HENNGE UI React requires the following font packages for proper display:

pnpm add @fontsource-variable/noto-sans-jp @fontsource-variable/noto-sans-mono

Import the fonts in your application entry point:

import "@fontsource-variable/noto-sans-jp";
import "@fontsource-variable/noto-sans-mono";

Optional Chinese Language Support

For applications requiring Chinese language support:

# Traditional Chinese (zh-Hant-TW)
pnpm add @fontsource-variable/noto-sans-tc

# Simplified Chinese (zh-Hans-CN)
pnpm add @fontsource-variable/noto-sans-sc

And import in your application:

import "@fontsource-variable/noto-sans-tc";
import "@fontsource-variable/noto-sans-sc";

Documentation

Complete documentation of all components is available in Storybook:

• Online Storybook (requires HENNGE organization account)
• Local development Storybook (see Development section)

Development

Prerequisites

• Node.js - Install the correct version using fnm:

  fnm install

  This uses the .nvmrc file in the project root.
• pnpm (used by the team for package management)

Available Scripts

pnpm build

Builds the package for production, including JavaScript, CSS, and themes.

pnpm build

pnpm dev

Starts the development mode with file watching enabled.

pnpm dev

pnpm typecheck

Runs TypeScript's type checking to ensure there are no type errors.

pnpm typecheck

pnpm lint

Lints the codebase using Biome.

pnpm lint

pnpm test

Runs the test suite using Vitest.

pnpm test

pnpm icons

Compiles SVG files from the /svg folder into React components. This script automates the SVG-to-React conversion process, ensuring consistent and optimized icon components.

pnpm icons

Icon Workflow

The SVG icon workflow follows these steps:

1. SVG files are organized in the /svg directory with specific naming conventions:

   • Files should be placed in subdirectories that indicate their category (e.g., /icon, /fileIcon)
   • The subdirectory name becomes part of the component name
   • For example:
     • /fileIcon/csv.svg will be compiled to /src/FileIconCsv.tsx
     • /icon/account.svg will be compiled to /src/IconAccount.tsx

2. The compiler:

   • Transforms SVG files into React components
   • Applies proper naming conventions using PascalCase
   • Sets default props like size, color, and accessibility attributes
   • Optimizes the SVG code for React

3. Importing generated icons:

   import { IconAccount } from "@hennge/ui-react";
   
   function App() {
     return <IconAccount />;
   }

Adding New Icons

New icons should be sourced from the HENNGE Design System Figma file:

1. Go to the Design System Figma file
2. Navigate to the Icons section
3. Select the icons you need (be careful not to select text labels)
4. Export as SVG format from the Export panel
5. Place the exported files in the appropriate subdirectory under /svg
6. Run pnpm icons to generate the React components

pnpm themes

Converts color themes from hexadecimal format to P3 color space using OKLCH syntax. This script enhances color rendering on modern displays while maintaining backward compatibility.

pnpm themes

Theme Workflow

The theme workflow involves:

1. Theme source files are stored in /src/themes-hex/ directory in standard hexadecimal format:

   • theme-hennge-default.css
   • theme-hennge-identity.css
   • theme-hennge-dlp.css
   • theme-hennge-cybersecurity.css

2. The compiler:

   • Reads these source files
   • Converts the hexadecimal colors to OKLCH color space with high precision (5 significant digits)
   • Outputs the processed files to /src/themes/ directory
   • Preserves color fidelity while enabling better rendering on wide-gamut displays

3. Finally, during the build process:

   • Theme files are copied to the distribution package
   • Made available through various import paths for consumer applications

This process is typically only needed when updating the design system colors or adding new themes. Most developers won't need to run this script regularly.

Development Workflow

A typical development workflow for this package might look like this:

1. Start the development mode with file watching enabled:

   pnpm dev

2. Make changes to the source code in the /src directory

3. Verify type correctness:

   pnpm typecheck

4. Run tests to ensure functionality:

   pnpm test

5. Lint your code to ensure consistency:

   pnpm lint

6. Build the package for production:

   pnpm build

7. Create a tarball for testing with:

   pnpm pack

   This generates a .tgz file that can be installed in other projects to verify the package works correctly.

Testing the Package in Other Projects

When testing in a monorepo setup, there are additional considerations for handling internal dependencies like @hennge/ui-core. Yalc provides an excellent solution for this scenario.

Using Yalc for Local Package Testing

Yalc acts as a local package repository, making it easy to share local packages across projects without publishing to a registry. It's especially useful for testing packages with internal dependencies like our monorepo structure.

1. Installation:

   # Install yalc globally
   pnpm add -g yalc

2. Publishing and using packages:

   # In ui-core directory
   pnpm build
   yalc publish  # Makes ui-core available in the local yalc store
   
   # In ui-react directory
   yalc add @hennge/ui-core  # Adds the local ui-core as a dependency
   pnpm install
   pnpm build
   yalc publish  # Makes ui-react available in the local yalc store
   
   # In your test project
   yalc add @hennge/ui-react  # Adds the local ui-react as a dependency
   pnpm install

3. Updating packages during development:

   # After making changes to ui-core
   pnpm build
   yalc push  # Updates all projects using this package
   
   # After making changes to ui-react
   pnpm build
   yalc push  # Updates all projects using this package

4. Removing yalc dependencies when done:

   # In your test project
   yalc remove --all
   pnpm install  # Restore regular dependencies

This workflow allows you to test your changes in a real application context without publishing to npm or dealing with complex manual extractions.

License

Apache-2.0 - see LICENSE for details.