design-system: Instructions file for GitHub Copilot

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.