Contributing Overview

This guide covers how to extend the UI Kit with new components.

Two Types of Components

1. UI Primitives (shadcn-vue)

Accessible, unstyled components from the shadcn-vue registry. These are added using the CLI and provide the foundation for common UI patterns.

Examples: Button, Input, Dialog, Select, Tabs, Toast

Guide: Adding Components

2. Domain Components (Custom)

Platform-specific components that implement GXP business logic. These are either ported from z-plugin-components or built custom.

Examples: VideoPlayer, BarcodeScanner, Leaderboard, FileUploader

Guide: Porting Components

Development Setup

Prerequisites

# Clone the repository
git clone <repo-url>
cd gx-uikit

# Install dependencies
npm install

# Start development
npm run dev

Available Commands

Command	Description
npm run dev	Start Vite dev server
npm run build	Build the library
npm run test	Run tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage
npm run storybook	Start Storybook
npm run storybook:build	Build Storybook

Component Structure

Every component follows this structure:

src/components/ui/component-name/
├── ComponentName.vue       # Main component
├── index.ts                # Exports
├── ComponentName.test.ts   # Unit tests
└── ComponentName.stories.ts # Storybook stories

Required Files

1. Component.vue - The Vue component
2. index.ts - Clean exports
3. Component.test.ts - Unit tests (minimum 80% coverage)
4. Component.stories.ts - Storybook documentation

Workflow

Adding a New Component

1. Decide the type:

   • shadcn primitive? Use the CLI
   • Domain component? Create manually

2. Create the component:

   • Follow the file structure
   • Use TypeScript
   • Follow existing patterns

3. Write tests:

   • Cover all props and states
   • Test accessibility
   • Test edge cases

4. Write stories:

   • Show all variants
   • Document props
   • Include examples

5. Export from index:

   • Add to src/index.ts
   • Export types if applicable

6. Verify:

   • Run tests: npm test
   • Build: npm run build
   • Check Storybook: npm run storybook

Code Standards

TypeScript

• All components must be TypeScript
• Define prop interfaces
• Export types when useful

interface Props {
  variant?: 'default' | 'secondary'
  size?: 'sm' | 'md' | 'lg'
}

Vue Components

• Use <script setup> syntax
• Use Composition API
• Keep templates clean

<script setup lang="ts">
import { computed } from 'vue'

const props = defineProps<Props>()
</script>

<template>
  <!-- Clean, readable template -->
</template>

Styling

• Use Tailwind CSS classes
• Use CSS variables for theming
• Use the cn() utility for class merging

<template>
  <div :class="cn('base-classes', props.class)">
    <!-- content -->
  </div>
</template>

Testing

• Use Vitest
• Test behavior, not implementation
• Cover edge cases

describe('Component', () => {
  it('renders with default props', () => {
    // Test default state
  })

  it('applies variant classes', () => {
    // Test each variant
  })

  it('handles disabled state', () => {
    // Test disabled behavior
  })
})

Quality Checklist

Before submitting a component:

• Component follows file structure
• TypeScript types are defined
• All props have defaults or are required
• Tests cover 80%+ of code
• Stories document all variants
• Exported from src/index.ts
• Build passes: npm run build
• Tests pass: npm test
• Storybook renders: npm run storybook

Next Steps

• Adding Components - Add shadcn-vue primitives
• Porting Components - Port from z-plugin-components
• Testing Guide - Writing effective tests