design-system component-creation.instructions.md

V6 Component Creation Guidelines

These guidelines ensure consistency and quality when creating new components in the design system.

File Structure Requirements

Each component must include exactly these files:

ComponentName/
├── index.ts                          # Exports
├── ComponentName.tsx                 # Main component
├── ComponentName.styles.ts           # Styling (CVA recipe)
├── ComponentName.stories.tsx         # Storybook stories
├── ComponentName.test.tsx            # Tests
└── ComponentName.docs.mdx            # Documentation
└── mocks/                            # (optional) Mock use cases for this component that cannot be represented in stories

Component Implementation (*.tsx)

Required Structure

import { propagateTestid } from '@helpers/utility/propagateTestid';
import { componentName } from './ComponentName.styles';
import { cx } from '@/styled-system/css';
import { styled } from '@/styled-system/jsx';
import { ReactNode, useMemo } from 'react';
import { IressStyledProps } from '@/types';
import { GlobalCSSClass } from '@/enums';

export interface IressComponentNameProps extends IressStyledProps {
  /**
   * Content of this component.
   */
  children?: ReactNode;

  /**
   * Additional props with detailed JSDoc comments.
   * Include default values, examples, and relationships to other props.
   */
  variant?: 'primary' | 'secondary';

  /**
   * Status of the component.
   * @default 'info'
   */
  status?: 'info' | 'success' | 'warning' | 'danger';
}

export const IressComponentName = ({
  children,
  className,
  variant,
  status = 'info',
  ...restProps
}: IressComponentNameProps) => {
  const classes = componentName({ variant, status });

  return (
    <styled.div
      className={cx(className, classes.root, GlobalCSSClass.ComponentName)}
      {...restProps}
    >
      {children}
    </styled.div>
  );
};

Key Requirements

• Always use Iress prefix for component names (e.g., IressAlert, IressButton)
• Extend existing props when appropriate (e.g., IressStyledProps, IressUnstyledProps, IressTextProps)
• Include comprehensive JSDoc comments with defaults, examples, and relationships
• Use cx() for className composition to merge custom and component classes
• Add GlobalCSSClass enum for consistent global CSS class naming
• Use propagateTestid() helper for nested testids when needed
• Implement controlled/uncontrolled patterns with useControlledState hook when applicable
• Do not import from @/main within the component file itself to ensure tree-shaking. Import from @/components/ComponentName instead.