UTA DevHub

AI Collaboration Guide for UI Development

Standardized AI prompts, patterns, and quality validation for consistent UI component development across all projects.

AI Collaboration Guide for UI Development

Overview

This guide provides standardized AI prompts, patterns, and quality validation techniques to help create consistent UI components across projects. It aims to enhance collaboration between developers and AI assistants while maintaining architectural standards and code quality.

Why AI Collaboration Patterns Matter

We've found that AI tools can significantly accelerate UI development, but consistency requires thoughtful prompting. These patterns have evolved through extensive experimentation to solve common challenges:

  • Consistency: Ensuring all AI-generated components follow the same standards
  • Quality: Maintaining high-quality code regardless of who (or what) wrote it
  • Learning curve: Reducing the time needed to effectively collaborate with AI
  • Maintainability: Creating components that integrate seamlessly with existing code

Purpose & Scope

This guide will help you:

  • Craft effective, consistent AI prompts for predictable results
  • Ensure AI-generated components align with our architectural standards
  • Validate and improve AI-generated code quality
  • Create components that seamlessly integrate with existing codebase
  • Develop a workflow that combines human expertise with AI capabilities

Core AI Collaboration Principles

Our approach to AI collaboration is built on four key principles that help maintain quality and consistency:

1. Predictable Structure

We help AI understand our three-layer architecture by being explicit about component categories and their characteristics:

By consistently using these structural concepts in our prompts, AI can better understand which type of component we're creating and what standards should apply.

2. Consistent Prompting

Standardized prompts provide a common language between developers and AI systems, leading to more predictable results and reducing miscommunication.

(Consider 🤔) Using the template prompts provided in this guide

These templates were developed through iterative testing to produce high-quality, compliant components consistently.

3. Quality Validation

All AI-generated components benefit from validation against our quality standards, covering areas like accessibility, performance, and testing.

(Do ✅) Review AI-generated code against our quality checklist

This helps catch common issues before integration and ensures all code meets our standards, regardless of its origin.

4. Architectural Compliance

Our prompts explicitly guide AI to follow established architecture patterns, ensuring generated code fits seamlessly into our codebase.

Standard AI Prompts for UI Components

Foundation Component Creation

Basic Foundation Component

Create a foundation [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/foundation/[ComponentName]/
- Use design tokens from core/shared/styles/theme
- Include TypeScript props interface with JSDoc comments
- Add accessibility support with proper roles and states
- Include unit tests with rendering, interaction, and accessibility coverage
- Create barrel export in index.ts
- Follow our established naming conventions

Component should:
- Accept variant, size, and disabled props as minimum
- Use theme colors, spacing, and typography tokens exclusively
- Handle loading and error states appropriately
- Include proper accessibility labels and hints
- Be memoized for performance if props are complex

Example structure:
- variant?: 'primary' | 'secondary' | 'ghost'
- size?: 'small' | 'medium' | 'large'
- disabled?: boolean
- loading?: boolean
- children: React.ReactNode

Interactive Foundation Component

Create a foundation [ComponentName] component for user interaction:

Props interface should include:
- variant: Visual style variants (primary, secondary, ghost, danger)
- size: Component sizing options (small, medium, large)
- disabled: Disabled state handling
- loading: Loading state with spinner/indicator
- onPress/onChange: Event handlers
- children/value: Content props

Implementation requirements:
- Use TouchableOpacity/TextInput/Pressable as base
- Integrate theme tokens for all colors, spacing, and typography
- Add accessibility role and state communication
- Handle disabled/loading states visually and functionally
- Include proper TypeScript types with JSDoc
- Add comprehensive test coverage (render, interaction, accessibility)
- Use React.memo for performance optimization

Pattern Component Creation

Composed Pattern Component

Create a pattern [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/patterns/[ComponentName]/
- Compose using foundation components from ui/foundation/
- Use design tokens for any additional styling
- Include complex UI behavior but remain domain-agnostic
- Add proper TypeScript interfaces with comprehensive JSDoc
- Include unit tests covering all interactions and states
- Create barrel exports

Component should:
- Be composed from 2+ foundation components
- Handle complex user interactions (multi-step, validation, etc.)
- Remain reusable across different features
- Include loading, error, and success states
- Have comprehensive prop interfaces
- Be optimized for performance with proper memoization

Example: Modal component using Card, Button, Text from foundation
Example: Form component using Input, Button, Text from foundation

Data Display Pattern

Create a pattern [ComponentName] component for data display:

Props interface should include:
- data: Array or object of data to display
- loading: Loading state handling
- error: Error state handling
- onAction: Callback for user actions
- variant: Display style options
- pagination: Pagination controls if applicable

Implementation requirements:
- Use foundation components for all UI elements
- Handle empty states gracefully
- Include sorting/filtering if applicable
- Add accessibility support for data tables/lists
- Implement virtualization for large datasets
- Include comprehensive loading and error states
- Add proper TypeScript interfaces for data structures

Business Component Creation

Domain-Aware Business Component

Create a business [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/business/[ComponentName]/
- Accept [Domain] objects as props (e.g., Product, User, Order)
- Use foundation/pattern components for all UI rendering
- Integrate with domain hooks from core/domains/[domain]/hooks
- Include domain-specific logic and calculations
- Add proper TypeScript interfaces for domain objects
- Include comprehensive tests including domain integration

Component should:
- Accept domain entities as primary props
- Use domain hooks for data fetching (useProduct, useUser, etc.)
- Contain business logic specific to the domain
- Render using foundation/pattern components only
- Handle domain-specific states (out of stock, expired, etc.)
- Include domain-specific actions (add to cart, save profile, etc.)
- Be reusable across multiple features

Example: ProductCard accepting Product object and using useProduct hook
Example: UserAvatar accepting User object and using useUser hook

Entity Management Component

Create a business [ComponentName] component for [Domain] entity management:

Domain integration:
- Import hooks from core/domains/[domain]/hooks
- Import types from core/domains/[domain]/types
- Use domain API methods through hooks
- Handle domain-specific validation
- Include domain-specific error handling

Props interface should include:
- [entity]Id: Identifier for the entity
- on[Action]: Callback functions for entity actions
- variant: Display/behavior variants
- permissions: User permission handling
- editable: Edit mode support

Implementation requirements:
- Use domain hooks for data fetching and mutations
- Implement optimistic updates where appropriate
- Handle domain-specific loading and error states
- Include proper form validation for entity editing
- Add accessibility support for all interactions
- Include comprehensive tests with domain mock data

AI Quality Validation Prompts

Pre-Implementation Validation

Review this component requirement and provide feedback:

Component: [ComponentName]
Category: [foundation/patterns/business]
Purpose: [Brief description]

Please validate:
1. Is the component category correct based on the requirements?
2. Are there any missing requirements for this component type?
3. What accessibility considerations should be included?
4. What testing scenarios should be covered?
5. Are there any performance considerations?
6. Does this fit well with our three-layer architecture?

Provide specific recommendations for any issues found.

Post-Implementation Review

Review this [ComponentName] component for compliance with our UI architecture standards:

Please check:
1. **Architecture Compliance**: 
   - Component placed in correct folder (foundation/patterns/business)
   - Follows proper import/export patterns
   - No architecture rule violations

2. **Design Token Usage**:
   - All colors use theme.colors.* tokens
   - Typography uses typography.* tokens  
   - Spacing uses theme.spacing.* tokens
   - No hardcoded values anywhere

3. **TypeScript Quality**:
   - Proper interfaces with JSDoc comments
   - Correct prop typing and defaults
   - Proper component typing

4. **Accessibility Implementation**:
   - Appropriate accessibilityRole set
   - Proper accessibilityLabel and accessibilityHint
   - Correct accessibilityState usage
   - Screen reader compatibility

5. **Performance Optimization**:
   - Appropriate use of React.memo
   - Proper memoization of expensive calculations
   - Efficient re-rendering patterns

6. **Testing Coverage**:
   - Unit tests for all functionality
   - Accessibility tests included
   - Integration tests if applicable

Provide specific feedback on any issues found with code examples for fixes.

Code Migration Validation

Help me migrate this existing component to follow our UI architecture standards:

Current component: [Paste component code]

Please:
1. Analyze the current component and determine correct category (foundation/patterns/business)
2. Identify what needs to be updated to meet our standards
3. Check for hardcoded values that should use design tokens
4. Identify missing accessibility features
5. Suggest performance optimizations
6. Recommend additional tests needed
7. Provide the updated component code following our patterns

Focus on maintaining existing functionality while improving architecture compliance.

AI-Assisted Development Workflows

New Component Development Flow

Step 1: Requirements Analysis

Help me design a [ComponentName] component:

Context:
- Purpose: [Describe what the component does]
- Usage: [Describe where it will be used]
- User interactions: [Describe how users interact with it]
- Data requirements: [Describe what data it needs]

Please help me:
1. Determine the correct component category (foundation/patterns/business)
2. Define the props interface with proper TypeScript types
3. Identify required accessibility features
4. Suggest design token usage patterns
5. Outline testing requirements
6. Identify potential performance considerations

Provide a complete component specification ready for implementation.

Step 2: Implementation

Implement the [ComponentName] component based on this specification:

[Paste specification from Step 1]

Requirements:
- Follow our UI architecture standards exactly
- Use design tokens from core/shared/styles/ for all styling
- Include comprehensive TypeScript interfaces
- Add full accessibility support
- Handle all specified states and interactions
- Include proper error handling
- Optimize for performance
- Follow our established patterns and conventions

Create:
1. Component implementation file
2. TypeScript interfaces file
3. Barrel export file
4. Comprehensive unit tests

Step 3: Quality Assurance

Perform a quality review of this implemented component:

[Paste implementation]

Check against our standards:
- Architecture rule compliance
- Design token usage (no hardcoded values)
- TypeScript interface completeness
- Accessibility feature implementation
- Performance optimization
- Testing coverage
- Documentation quality

Provide a detailed quality report with any issues found and specific fixes needed.

Maintenance and Enhancement Flow

Bug Fix Assistance

Help me fix this issue in [ComponentName]:

Issue description: [Describe the bug]
Current behavior: [What's happening now]
Expected behavior: [What should happen]
Component code: [Paste relevant code]

Please:
1. Identify the root cause of the issue
2. Provide a fix that maintains our architecture standards
3. Ensure the fix doesn't break existing functionality
4. Suggest additional tests to prevent regression
5. Check if similar issues might exist in related components

Provide the corrected code with explanation of changes.

Feature Enhancement

Help me add [feature] to the existing [ComponentName] component:

Current component: [Paste component code]
New feature requirements: [Describe what needs to be added]

Requirements:
- Maintain backward compatibility with existing props
- Follow our architecture standards
- Use design tokens for any new styling
- Add proper TypeScript types for new features
- Include accessibility support for new functionality
- Add comprehensive tests for new features
- Update documentation as needed

Provide the enhanced component with all changes clearly marked.

AI Prompt Templates by Use Case

Component Creation Templates

Quick Foundation Component

Create a foundation [ComponentName] that:
- Uses design tokens from core/shared/styles/
- Has variant and size props
- Includes accessibility support
- Has comprehensive TypeScript types
- Includes unit tests

Complex Pattern Component

Create a pattern [ComponentName] that:
- Composes [list foundation components]
- Handles [specific interactions]
- Manages [specific states]
- Remains domain-agnostic
- Includes comprehensive props interface

Business Domain Component

Create a business [ComponentName] that:
- Works with [Domain] entities
- Uses [specific domain hooks]
- Contains [specific business logic]
- Integrates with our domain architecture
- Handles [domain-specific scenarios]

Testing Templates

Comprehensive Test Generation

Generate comprehensive tests for [ComponentName]:

Component behavior:
- Props: [list all props and expected behaviors]
- Interactions: [list all user interactions]
- States: [list all visual/logical states]
- Accessibility: [list all a11y features]

Test requirements:
- Unit tests with @testing-library/react-native
- Accessibility tests for all a11y features
- Visual regression tests for all states
- Integration tests for complex behavior
- Mock any external dependencies properly

Accessibility Test Focus

Generate accessibility-focused tests for [ComponentName]:

Please test:
- Proper accessibility roles and labels
- Screen reader announcements
- Keyboard navigation support
- State change announcements
- Focus management
- High contrast mode compatibility
- Large text scaling support

Use @testing-library/react-native patterns and include both automated and manual testing guidance.

Refactoring Templates

Architecture Compliance Update

Refactor this component to follow our UI architecture standards:

Current code: [paste code]

Updates needed:
- Move to correct folder structure
- Update to use design tokens
- Add missing accessibility features
- Improve TypeScript interfaces
- Add comprehensive tests
- Optimize performance
- Update documentation

Maintain all existing functionality while improving compliance.

Performance Optimization

Optimize this component for performance:

Component code: [paste code]

Focus on:
- Proper memoization strategies
- Efficient re-rendering patterns
- Bundle size optimization
- Runtime performance improvements
- Memory usage optimization

Provide optimized code with explanations of improvements made.

Quality Assurance Integration

Pre-Merge Checklist for AI-Generated Code

Use this prompt to validate any AI-generated component:

Validate this component against our UI architecture standards:

Component: [paste component code]

Checklist:
- [ ] Correct folder placement (foundation/patterns/business)
- [ ] Uses design tokens exclusively (no hardcoded values)
- [ ] Proper TypeScript interfaces with JSDoc
- [ ] Comprehensive accessibility support
- [ ] Includes unit tests (render, interaction, accessibility)
- [ ] Performance optimized (memoization where needed)
- [ ] Follows naming conventions
- [ ] Proper barrel exports
- [ ] Documentation complete
- [ ] Integration with existing architecture

Provide pass/fail status for each item with specific fixes for any failures.

Continuous Quality Monitoring

Review our recent AI-generated components for consistency:

Components to review: [list recent components]

Check for:
1. Pattern consistency across components
2. Design token usage compliance
3. Accessibility implementation consistency
4. TypeScript interface patterns
5. Testing pattern adherence
6. Performance optimization consistency

Identify any inconsistencies and provide standardization recommendations.

Integration with Development Workflow

Workflow Integration Points

Our AI collaboration patterns integrate seamlessly with the existing development workflow:

Planning Phase Integration

Combine with existing planning processes:
- Requirements gathering (existing workflow)
- AI-assisted component specification (this guide)
- Design review (existing workflow)  
- Implementation planning (this guide + existing workflow)

Development Phase Integration

Enhanced development process:
- Component structure creation (existing standards)
- AI-assisted implementation (this guide)
- Design token integration (existing architecture)
- Code review process (existing workflow + AI validation)

Quality Assurance Integration

Comprehensive QA process:
- Automated testing (existing standards)
- AI-assisted test generation (this guide)
- Manual review process (existing workflow)
- Performance validation (existing standards)

For complete development workflow details, see Component Development Workflow.

Troubleshooting Common AI Issues

Issue: AI Not Using Design Tokens

Problem: AI generates hardcoded values instead of theme tokens Solution: Use this corrective prompt:

The component you generated uses hardcoded values. Please update it to use design tokens:

Replace all hardcoded values with:
- Colors: theme.colors.[semantic-name][shade]
- Spacing: theme.spacing.[size]
- Typography: typography.sizes.[size], typography.weights.[weight]
- Border radius: theme.radii.[size]

Show the corrected component with all hardcoded values replaced.

Issue: AI Missing Accessibility Features

Problem: AI generates components without proper accessibility Solution: Use this enhancement prompt:

Add comprehensive accessibility support to this component:

Component: [paste code]

Add:
- Appropriate accessibilityRole
- Descriptive accessibilityLabel
- Helpful accessibilityHint
- Proper accessibilityState for all states
- accessibilityLiveRegion for dynamic content
- Keyboard navigation support

Provide the updated component with full accessibility implementation.

Issue: AI Creating Wrong Component Category

Problem: AI places components in wrong folders or mixes concerns Solution: Use this correction prompt:

This component is in the wrong category. Please recategorize and fix:

Current: [describe current implementation]
Issue: [explain why it's wrong category]

Correct approach:
- Category: [foundation/patterns/business]
- Location: ui/[category]/[ComponentName]/
- Concerns: [what it should and shouldn't do]

Provide the corrected component in the right category with proper separation of concerns.

This guide ensures consistent, high-quality AI collaboration for UI component development across all projects.

On this page