Component Guidelines

This section outlines the standards for building consistent, accessible, and maintainable components within the UI Kit — covering structure, styling, testing, and documentation best practices.

Structure

Each component should follow the structure below:


HvComp/
├── index.ts            # Entry file with public exports
├── HvComp.tsx          # Component implementation and types
└── HvComp.test.tsx     # Unit tests

Components and their types must be exported in index.ts.
Use PascalCase for component names and prefix with Hv (e.g., HvButton, HvAccordion).
Boolean props should be opt-in — default value should be false.
Name event handler props using the on<Action> convention (e.g., onClick, onChange).
Optionally move styles (HvComp.styles.ts), types (types.ts), or utils (utils.ts) into separate files when they grow too complex or are reused across components.

Styles

Use the createClasses utility to define component classes.
Leverage the design theme variables (e.g., colors, spacing), avoiding hard-coded values when possible.
Class names generated by createClasses are exposed to users, so choose names thoughtfully:
- Always apply classes.root to the root element.
- When targeting non-root elements, make the purpose clear (e.g., classes.label, classes.iconContainer).
- For conditional styles, use descriptive names that reflect the condition (e.g. classes.containerOpen).

Documentation

Create a corresponding comp.mdx file under the apps/docs/src directory.
Leverage the Playground component for the most common & relevant properties
Include only meaningful and distinct stories, avoiding redundant examples.

Other Conventions

Write unit tests using @testing-library/react.
Use semantic HTML elements whenever possible for better accessibility and performance.
Ensure components meet WCAG requirements and follow ARIA guidelines .

Following these guidelines helps maintain a coherent developer experience across the library and ensures consistency, accessibility, and long-term maintainability.

Example

Here’s an example anatomy of a HvComp component:


// HvComp.styles.ts
import { createClasses } from "@hitachivantara/uikit-react-utils";
import { theme } from "@hitachivantara/uikit-styles";
 
export const { staticClasses, useClasses } = createClasses("HvComp", {
  /** Applied to the root element */
  root: {
    padding: theme.spacing("xs"), // 👈 leverage the `theme.` object
    backgroundColor: theme.colors.backgroundColor,
  },
  /** Applied to the root element when selected */
  selected: {},
  /** Applied to the root element when disabled */
  disabled: {
    // 👇 leverage global `disabled` instead of adding a `buttonDisabled`
    "& $button": {
      cursor: "not-allowed",
    },
  },
  /** Applied to the button element */
  button: {},
});


// HvComp.tsx
import {
  useDefaultProps,
  type ExtractNames,
} from "@hitachivantara/uikit-react-utils";
 
import { HvBaseProps } from "../types/generic";
import { staticClasses, useClasses } from "./MyComp.styles";
 
// export `staticClasses` 👇 as `compClasses` (camelCase without `Hv` prefix)
export { staticClasses as compClasses };
 
// export the classes 👇 inferred from `useClasses`
export type HvCompClasses = ExtractNames<typeof useClasses>;
 
// extend the types to where `...others` 👇 is being passed
export interface HvCompProps extends HvBaseProps<HTMLDivElement> {
  selected?: boolean; // 👈 name boolean props so its obvious they're boolean
  /** Disables the component visually and its controls */
  disabled?: boolean; // 👆 add JSDoc to the props, especially if they're complex
  children?: React.ReactNode;
  buttonContent?: React.ReactNode; // 👈 use `ReactNode` for props that are rendered as-is
  onClick?: HvButtonProps["onClick"]; // 👈 re-use types when possible
  onButtonClick?: HvButtonProps["onClick"]; // 👈 call handlers `on[<Element>]<Action>`
  id?: string; // 👈 ❌ don't add redundant types (included in the parent interface)
}
 
// 👇 Add a JSDoc block to the component explaining its purpose
/** HvComp does some amazing stuff */
export const HvComp = forwardRef<
  // no-indent
  React.ComponentRef<"div">,
  HvCompProps
>(function HvComp(props, ref) {
  const {
    children,
    classes: classesProp, // 👈 fix collisions by renaming to `<x>Prop`
    className,
    selected, // 👈 make booleans be opt-in (default is false/undefined)
    disabled, // 👈 don't  set defaults (ie `false`) unnecessarily
    buttonContent,
    onClick,
    onButtonClick,
    ...others // 👈 call remaining props `others`
  } = useDefaultProps("HvComp", props); // 👈 use the useDefaultProps utility
  const { classes, css, cx } = useClasses(classesProp);
 
  // reserve `useMemo` for expensive 👇 computations
  const hasInput = useMemo(() => expensiveSearch(children), [children]);
 
  // rename handlers 👇 `handle<Action>` and 👇 type them accordingly, or ideally inline them
  const handleButtonClick: HvButtonProps["onClick"] = (evt) => {
    evt.preventDefault();
    onButtonClick?.(evt);
  };
 
  // keep `render<Stuff>` as a `ReactNode` if possible
  // if you 👇 need `(props) => ReactNode`, it should likely be a separate component
  const renderContent = (
    <div>
      <span />
    </div>
  );
 
  return (
    <div
      ref={ref} // 👈 always forwarding the ref
      // 👇 merge class names with `cx` provided by `useClasses`
      className={cx(
        css(), // 👈 AVOID inline classes, but pass them styles first when necessary
        classes.root, // 👈 ensure `classes.root` is on the root element
        {
          [classes.selected]: selected, // 👈 names are based on their *condition*
          [classes.disabled]: disabled, // 👈 higher priority classes come after
        },
        className, // 👈 pass user-defined `className` last
      )}
      onClick={disabled ? undefined : onClick}
      {...others} // 👈 forward others according to the types
    >
      <HvButton className={classes.button} onClick={handleButtonClick}>
        {buttonContent}
      </HvButton>
      {selected && renderContent}
      {children}
    </div>
  );
});