Contribution Guidelines for gluestack-ui Components

Welcome to the gluestack-ui component library! This guide outlines the structure, best practices, and expectations when contributing new components, specifically using the example of a Button component.

General Guidelines

1. Component Structure:

   • Each component should be built using React and React Native.
   • Use NativeWind for styling and ensure Tailwind class names are used for consistency.
   • Ensure that components are flexible, maintainable, and can handle platform-specific variations (web, mobile, etc.).

2. Component Scope:

   • Define a unique SCOPE for each component. This helps manage context, and ensures proper theming/scoping of styles.
   • Example: const SCOPE = 'BUTTON';

3. Primitive Components:

   • Use native primitives like Pressable, Text, View, etc., and wrap them with utilities like withStyleContext to manage shared props and context properly.

     • Component Context:

       • Use useStyleContext to inherit parent styles and states in child components like ButtonText, ButtonIcon, and ButtonGroup.

       • Example:

         const { variant: parentVariant } = useStyleContext(SCOPE);
         
         

     • Example:

       withStyleContext(Pressable, SCOPE)
       

   Not need if there is no creator API Just use simple context api with scope.

4. Reusability & Variants:

   • Components should be highly configurable. Use the tva (Tailwind Variants API) to define base styles, variants, and compound variants for different sizes, actions, and states.

   • Use Tokens only color token defined by us like:- primary, secondary, avoid using hard coded color tokens like bg-red-500

     If you don’t know how to design don’t worry create basic component design we will improve design according to our design guidelines.

   • Example:

     const buttonStyle = tva({
       base: 'base-styles',
       variants: {
         size: {
           sm: 'small',
           lg: 'large',
         },
         action: {
           primary: 'bg-primary',
           secondary: 'bg-secondary',
         },
       },
     });
     
     

5. Composability:

   • Your component should be built in a modular way. Each visual aspect (icon, text, group, spinner) should have its own logic and styling, and the main component should assemble them.
   • Use proper props forwarding and memoization to ensure efficient rendering.

6. CSS Interoperability:

   • Use cssInterop to ensure styles are handled across React Native and web.
     • This is not needed if you are not using third party headless components. read more about it here

Best Practices

1. Styling:

   • Always use Tailwind classes for styling, with tva to manage variants and responsive behaviours. read more here
   • Ensure platform-specific styles are handled using web: ,ios: , android: read more here.

2. Accessibility:

   • Components should be accessible. Add focus states, ARIA labels, and other accessibility attributes to ensure compatibility with screen readers and assistive devices.

3. Testing:

   • Include tests for each new component. Write tests for different variants, sizes, and states, ensuring that both styles and behavior are correctly applied across platforms.

4. Performance:

   • Use useMemo, React.forwardRef, and React.memo to optimize component rendering and prevent unnecessary re-renders.

5. Type Safety:

   • Use TypeScript for strong type checking. Ensure that prop types are defined using VariantProps and appropriate interfaces.

6. Display Names:

   • Ensure all components and sub-components are given a displayName for better debugging and readability in React Developer Tools.

   Example:

   Button.displayName = 'Button';
   ButtonText.displayName = 'ButtonText';
   
   

Pull Request Requirements

• Ensure the component matches the design guidelines and the above standards.
• Include appropriate documentation for each new component. Document props, default values, and examples.
• Ensure the component is fully tested, including edge cases for size, variant, and interaction states.