Skill: IDS Version Migration

When to Use

• Migrating from IDS v5 (or v4) to IDS v6

• Migrating from OUI (@iress/oui ) to IDS v6

• Updating imports from @iress/components-react to @iress-oss/ids-components

• Converting Formik forms to React Hook Form via IressForm /IressFormField

• Updating test files that use IDS v4 test utilities

• Reviewing migration PRs for correctness

Decision Table: Which Migration Path?

Current stack Migration path Complexity Reference

OUI only OUI→v6 guide High (form architecture change) prop-renames.md

IDS v4 only v4→v6 guide Medium (form architecture change) prop-renames.md

IDS v5 only v5→v6 guide Low–Medium v5-to-v6-migration.md

OUI + IDS v4 Both OUI→v6 and v4→v6 guides High (form architecture change) prop-renames.md

OUI + IDS v5 OUI→v6 guide + v5→v6 for IDS changes High (form architecture change) v5-to-v6-migration.md

Full interactive guides with diff viewers are available in Storybook:

• v4→v5 guide

• v5→v6 guide

• OUI→v6 guide

Pre-Migration Assessment

Before starting migration, run these scripts (or perform checks manually):

• Identify current version: scripts/detect-version.sh — detects IDS/OUI version and recommends migration path

• Audit component usage: scripts/audit-components.sh — generates component usage report

• Check for deprecated props: scripts/find-deprecated-props.sh — finds props that will break

• Check form architecture: scripts/find-formik.sh — identifies Formik forms needing migration

• Check test patterns: scripts/find-test-utils.sh — finds old test utilities

• Review custom CSS: Search for .oui- , .ids- , or iress- class selectors that may break

• Setup VRT (recommended): scripts/setup-playwright-vrt.sh — generates Playwright visual regression tests

• Capture baseline screenshots: Run VRT suite before migration to capture current state

• Create migration branch: Ensure you can rollback if needed

Quick Reference: Package Changes

Import path

// ❌ Old (IDS v4) import { IressButton } from '@iress/components-react';

// ❌ Old (OUI) import { Button, Input } from '@iress/oui';

// ✅ IDS v6 (install with @alpha tag: npm install @iress-oss/ids-components@alpha) import { IressButton, IressInput } from '@iress-oss/ids-components';

Important: IDS v6 is currently in alpha. Install with the @alpha tag:

npm install @iress-oss/ids-components@alpha npm install @iress-oss/ids-tokens@alpha # if using tokens directly

CSS entry point

// ✅ Required in your app entry point import '@iress-oss/ids-components/dist/style.css';

Token package

// ✅ Required for design tokens import '@iress-oss/ids-tokens/build/css-vars.css'; import { cssVars } from '@iress-oss/ids-tokens';

Key Migration Areas

v5 → v6 Migration

For migrations specifically from IDS v5 to v6, see references/v5-to-v6-migration.md for:

• Package and CSS import changes

• Component renames (IressBadge → IressPill , IressFilter → IressDropdownMenu , etc.)

• Prop changes by component (Button, Alert, Toggle, Field, Modal, Select)

• Icon migration (FontAwesome → Material Symbols)

• Form migration patterns

Component renames

Components that changed names between versions (IDS and OUI → v6), plus removed and new components. See references/component-renames.md for the full map.

Key renames: IressBadge → IressPill , IressRichSelect → IressSelect , IressField → IressFormField , IressFilter → IressDropdownMenu .

Prop renames (CRITICAL — verified against source code)

Using old prop names will silently fail. See references/prop-renames.md for the complete table.

Most common renames:

Component Old prop (OUI) New prop (v6)

Alert

context

status

Modal

onHide

onShowChange

Fieldset /RadioGroup

legend

label

Label

optional

required

Component (IDS v4/v5) Old prop New prop (v6)

IressButton

variant

mode

IressAlert

variant

status

IressModal

isOpen

show

IressModal

onClose

onShowChange

IressModal

title

heading

IressPanel

background

bg

IressStack /IressInline

gutter

gap

Form migration (Formik → React Hook Form)

The most significant architectural change. Forms use IressForm

• IressFormField with render prop, replacing Formik's <Field as={...}> pattern. Yup schemas become per-field rules props.

See references/form-migration.md for validation mapping, before/after examples, and common patterns.

Quick example:

<IressForm defaultValues={{ email: '' }} onSubmit={handle}> <IressFormField name="email" label="Email" render={(props) => <IressInput {...props} type="email" />} rules={{ required: 'Required' }} /> <IressButton type="submit" mode="primary"> Submit </IressButton> </IressForm>

Testing migration

IDS v6 uses standard React Testing Library — no special test utilities. Replace idsFireEvent with fireEvent /userEvent , remove mockLazyLoadedComponents , prefer getByRole /getByLabelText over getByTestId .

See references/testing-migration.md for import changes, pattern mapping, config updates, and form test examples.

Styling migration

OUI CSS classes and IDS v4 Stencil classes are removed. Use styling props (p , m , bg , gap , scrollable ) or design tokens (var(--iress-*) ). Declare @layer order if custom CSS is overridden.

See references/styling-migration.md for examples and AG Grid migration.

Post-Migration Validation

After completing migration, run scripts/validate-migration.sh or verify manually:

• Automated checks: Run validation script to check for common issues

• Visual regression: Run VRT suite and review all visual diffs (see references/visual-regression-testing.md)

• Visual check: All components render without console errors or warnings

• Form functionality: Submit forms and verify validation rules work correctly

• Test suite: All tests pass with new testing patterns (no idsFireEvent , etc.)

• Accessibility: Keyboard navigation and screen reader functionality intact

• Styling: No missing styles, check responsive breakpoints

• Interactive states: Hover, focus, disabled, loading states work as expected

• Build: Production build completes without errors, check bundle size

The validation script checks for:

• Old imports (@iress/oui , @iress/components-react )

• Old test utils (idsFireEvent , mockLazyLoadedComponents )

• Deprecated props (variant= , isOpen= , gutter= , etc.)

• Required CSS import

• Remaining Formik usage

Common Gotchas

See references/common-gotchas.md for a comprehensive troubleshooting guide covering:

• Critical breaking changes (missing CSS, validation, renamed props)

• IDS v4 React → v6 React gotchas (test utils, slots, helpers, icons)

• OUI-specific gotchas (prop renames, removed components)

• Component API changes (form fields, styling, composition patterns)

• Form architecture changes (Formik → React Hook Form)

Cross-References

Generated migration guides (read these for full details)

• v4→v5 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v5.md

• v5→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v6.md

• OUI→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-oui.md

Component and pattern docs

• Component docs — node_modules/@iress-oss/ids-components/.ai/components/

• Pattern docs — node_modules/@iress-oss/ids-components/.ai/patterns/

• Index — node_modules/@iress-oss/ids-components/.ai/index.json

Related skills

• token-usage — Design token usage patterns

• ui-translation — Building new IDS v6 UIs from scratch

• ui-doctor — Auditing IDS compliance

Reference

• Storybook and Guidelines: https://main--691abcc79dfa560a36d0a74f.chromatic.com