Grupalia Design System

Overview

This design system provides a scalable, maintainable, and consistent approach to building user interfaces across Grupalia products. It is inspired by best practices and the documentation in our Figma files:

Installation

npm install @grupalia/rn-ui-kit
# or
yarn add @grupalia/rn-ui-kit

Font Setup

This design system uses Inter fonts. To configure them in your project:

1. Install the required dependencies:

npx expo install @expo-google-fonts/inter expo-font

2. Add the expo-font plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "node_modules/@expo-google-fonts/inter/100Thin/Inter_100Thin.ttf",
            "node_modules/@expo-google-fonts/inter/200ExtraLight/Inter_200ExtraLight.ttf",
            "node_modules/@expo-google-fonts/inter/300Light/Inter_300Light.ttf",
            "node_modules/@expo-google-fonts/inter/400Regular/Inter_400Regular.ttf",
            "node_modules/@expo-google-fonts/inter/500Medium/Inter_500Medium.ttf",
            "node_modules/@expo-google-fonts/inter/600SemiBold/Inter_600SemiBold.ttf",
            "node_modules/@expo-google-fonts/inter/700Bold/Inter_700Bold.ttf",
            "node_modules/@expo-google-fonts/inter/800ExtraBold/Inter_800ExtraBold.ttf",
            "node_modules/@expo-google-fonts/inter/900Black/Inter_900Black.ttf",
            "node_modules/@expo-google-fonts/inter/100Thin_Italic/Inter_100Thin_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/200ExtraLight_Italic/Inter_200ExtraLight_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/300Light_Italic/Inter_300Light_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/400Regular_Italic/Inter_400Regular_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/500Medium_Italic/Inter_500Medium_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/600SemiBold_Italic/Inter_600SemiBold_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/700Bold_Italic/Inter_700Bold_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/800ExtraBold_Italic/Inter_800ExtraBold_Italic.ttf",
            "node_modules/@expo-google-fonts/inter/900Black_Italic/Inter_900Black_Italic.ttf"
          ]
        }
      ]
    ]
  }
}

3. Run prebuild to apply the font configuration:

npx expo prebuild --clean

This will copy all Inter font weights (100-900) and styles (regular and italic) to your native projects.

Color System & Variables

1. Palette Variables

• All base colors (brand, gray, error, etc.) are defined in styles/colors.js.
• Each color and shade is available as a palette variable (e.g., brand[500], gray_light[100]).
• Palette variables are mapped to semantic variables and should not be used in UI code or components.

2. Semantic Variables

• Semantic color files (background-colors.js, text-colors.js, border-colors.js) map UI roles (e.g., bg-primary, text-secondary) to palette colors.
• Each semantic variable has a light (and optionally dark) value, referencing the palette.
• Always use semantic utility classes in your UI code with NativeWind.

Example (NativeWind):

// BAD: using StyleSheet or inline styles
// <View style={{ backgroundColor: colors.brand[500] }} />

// GOOD: using semantic utility classes with NativeWind
<View className="bg-primary text-secondary">
  <Text className="text-primary">Hello</Text>
</View>

3. Tailwind/NativeWind Integration

• The Tailwind config (src/preset.ts) is extended to generate utility classes only for semantic colors.
• Classes like bg-primary, text-secondary, border-brand are available for use with NativeWind.
• Only use the semantic utility classes generated by the config in your components.

When to Use Each Variable

• Palette variables: Only in semantic mapping files.
• Semantic variables: Always in UI code, components, and styles via NativeWind utility classes.
• Tailwind/NativeWind classes: Only use the semantic classes generated by the config.

Why This Approach?

• Consistency: Ensures all UI uses the same color roles, making updates and theming easy.
• Scalability: Adding/changing a palette color or semantic mapping updates the whole system.
• Theming: (Future) Enables light/dark mode and custom themes by changing semantic mappings.

Development

Local Development with yalc

To test changes locally in another project before publishing:

1. In this repository, publish the package locally:

yarn publish-local

2. In the target project (e.g., promoters-mobile), add the local package:

npx yalc add @grupalia/rn-ui-kit

This creates a reference in your package.json:

"@grupalia/rn-ui-kit": "file:.yalc/@grupalia/rn-ui-kit"

3. To update after making changes, run yarn publish-local in this repo, then in the target project:

npx yalc update

Running Tests

This project uses Vitest for testing. The following commands are available:

# Run tests in watch mode
yarn test

# Run tests once
yarn test:run

Continuous Integration

Tests are automatically run on GitHub Actions for:

• Pull requests to main and develop branches
• Pushes to main and develop branches
• Multiple Node.js versions (18.x, 20.x)

The CI pipeline includes:

• Type checking with TypeScript
• Running the full test suite
• Building the project
• Coverage reporting

For more details, see the Figma documentation and the code in the styles/ directory.