Prepping for V2 of Abyss

This is a prepping guide for ways teams can prepare for the upgrade from Abyss V1 to V2.

What is the difference between a prepping guide and a migration guide?

This prepping guide is different from the migration guide that will be released with Abyss V2. Understanding these differences will help you plan your approach:

Prepping Guide	Migration Guide
Focuses on gradual preparation	Provides comprehensive instructions for full migration to V2
Helps distribute workload across sprints	Will be a one-time migration effort
Identifies components to start replacing now
Allows teams to adopt V2 patterns incrementally
Reduces migration complexity later

By following this prepping guide now, you'll significantly reduce the effort required when the full migration guide is released with Abyss V2.

Dependencies

// from:
- "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"

// to:
+ "react": "^18.0.0 || ^19.0.0"

UHG theme

The uhg theme will be removed in Abyss V2.

To learn more about next steps please navigate to the UHG Theme documentation.

Components

With the migration to Abyss V2 we are making several changes to our components. This includes:

• Prop changes: Some props have been removed, modified, or renamed.
• Class changes: Some classes have been removed and renamed.
• Component deprecations: Some components will be deprecated and replaced with new ones.
• Component breaking changes: Some components will have breaking changes that may affect how they are used in your application.

Deprecations

Here is a list of tools/hooks/components that will no longer be available in Abyss V2:

Note: This list is not exhaustive and may change as we finalize the migration.

Mobile Deprecations

V1 Abyss	Reason for Deprecation	Migration Path
Name:ActionNavImport Path:@uhg-abyss/mobile/ui/ActionNav	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:ArrowImport Path:@uhg-abyss/mobile/ui/Arrow	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:BulletsImport Path:@uhg-abyss/mobile/ui/Bullets	Doesn't align with the Abyss Design system	Nested internally for Carousel.
Name:CellCreatorImport Path:@uhg-abyss/mobile/ui/CellGroup	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:ElevationImport Path:@uhg-abyss/mobile/ui/Elevation	elevation() function was created to be placed inside the style prop	Move to @uhg-abyss/mobile/tools/elevation as a replacement.
Name:IconMaterialImport Path:@uhg-abyss/mobile/ui/IconMaterial	Google has deprecated the Material Icons library and instead moved to a font based icon library.	Move to @uhg-abyss/mobile/ui/IconSymbol as a replacement.
Name:LagoonProviderImport Path:@uhg-abyss/mobile/ui/LagoonProvider	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:NibGroupImport Path:@uhg-abyss/mobile/ui/NibGroup	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:OverlayImport Path:@uhg-abyss/mobile/ui/Overlay	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:ScrollWheelImport Path:@uhg-abyss/mobile/ui/ScrollWheel	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:SearchBarImport Path:@uhg-abyss/mobile/ui/SearchBar	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:LagoonFormImport Path:@uhg-abyss/utility/ui/LagoonForm	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:LagoonProviderImport Path:@uhg-abyss/utility/ui/LagoonProvider	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:MaelstromProviderImport Path:@uhg-abyss/utility/ui/MaelstromProvider	Maelstrom has been moved out of Abyss	Use alternative authentication methods
Name:lagoonImport Path:@uhg-abyss/utility/tools/lagoon	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.

Teams should start replacing these components with their new counterparts or alternative solutions now, rather than waiting for the V2 release. By proactively doing this now, you can:

• Reduce the refactoring effort required when V2 is officially released
• Migrate in smaller, more manageable increments
• Identify and resolve integration issues earlier
• Ensure a smoother and quicker transition to V2

Component breaking changes

We've documented all component changes to help with migration planning. For details, see the Component Changes section.

Note: V2 is officially released, the "V2" prefix is removed and these components will replace their V1 counterparts. For example, V2Button is now Button.

AI-Powered Component Migration

Need help with component migration? Use our AI-Powered Migration Copilot to help convert V1 components to their V2 equivalents with proper prop mapping.

Why should I use the V2 components now?

• Familiarize yourself with the new APIs and features
• Identify any potential issues or changes in behavior early
• Ensure your codebase is ready for the V2 release without needing a complete overhaul
• Many of these components were completely rewritten to improve performance, accessibility, and usability
• These components have many added features and improvements that are not available in the V1 components (e.g., tokens, design improvements, etc.)

Note: These V2 components may change before the official V2 release. However, they are stable for production use and can be safely integrated into your application.

AI-Powered Migration Copilot

To help with component migration, we provide an AI context package that works with tools like GitHub Copilot, ChatGPT, or other AI code assistants. This context enables the AI to understand V1 to V2 changes and provide accurate migration assistance.

Using the Migration Copilot

• Download the this zip folder
• Extract the zip to your project root directory:

your-project-root/
├── abyss-migration-ai-context/
│   ├── ABYSS-MIGRATION-ASSISTANT.md
|   └── MigrationData.json
├── package.json
└── src/
    └── ... (your project files)

Add the context to your AI tool of choice (e.g., Copilot, ChatGPT, etc.) referencing the folder location.

Next you can prompt the AI tool with questions like:

Migrate this file from V1 to V2 of Abyss
Migrate the `Button` component from V1 to V2 of Abyss

Here is an example showcasing migrating a file from V1 to V2 of Abyss using the AI tool:

Migrate #file:Mobile.tsx from V1 to V2 of Abyss

Note: This is the result after using the one prompt above. No additional prompts were needed to get the correct result