Skip to content

MIGRATION.md

Latest commit

 

History

History
937 lines (675 loc) · 30.2 KB

MIGRATION.md

File metadata and controls

937 lines (675 loc) · 30.2 KB
Raw

Migration Guide

v2.1.0 → v3.0.0

Overview

This release adds the List item component and a typography tokens component, updates the icon library to v2.3.0, updates the Button component to v3.3.0 with tinted/untinted icon support, updates the Link component to v2.4.0, adds a size parameter to OudsCircularProgressIndicator for button integration, and fixes a crash in OudsTabBar. It also introduces a typed prefix/suffix icon configuration with tinting support for OudsTextInput.

It also introduces a new shared OudsIcon class (package:ouds_core/components/common/ouds_icon.dart) that unifies icon configuration (asset path, tinted state, backgroundColor and semanticsLabel) across OudsButton, OudsLink, OudsFilterChip, OudsSuggestionChip, OudsTextInput, OudsPhoneNumberInput, OudsCheckboxItem, OudsRadioButtonItem and OudsSwitchButtonItem. It replaces the component-specific OudsTextInputPrefixIcon and OudsControlItemIcon classes and String type. All these components now support tinted/untinted icon display through OudsIcon.tinted (defaults to true).

Before You Begin

Prerequisites

  • Use version 2.1.0 or older

Breaking Changes

1. New shared OudsIcon class replacing a String icon and OudsTextInputPrefixIcon

Icon configuration (asset path, tinted, backgroundColor, semanticsLabel) is now expressed with a single shared OudsIcon class used by OudsButton, OudsLink, OudsFilterChip, OudsSuggestionChip, OudsTextInput, OudsPhoneNumberInput, OudsCheckboxItem, OudsRadioButtonItem and OudsSwitchButtonItem. All these classes now support tinting the icon: set OudsIcon(tinted: false) to keep the icon's original (multi-color) colors instead of the theme color.

Impact: Medium (breaking — import and use OudsIcon instead of the removed class and type String)

Before:

// ...
 icon: 'assets/ic_heart.svg'

After:

import 'package:ouds_core/components/common/ouds_icon.dart';
// ...
 icon: OudsIcon('assets/ic_heart.svg', tinted: true)

Required Action:

  • Since v2.1.0, the icon parameter of OudsLink and OudsButton, the prefixIcon of OudsTextInput/OudsPhoneNumberInput, and the icon parameter of OudsCheckboxItem/OudsRadioButtonItem/OudsSwitchButtonItem, is now typed OudsIcon instead of a plain String (or the removed OudsControlItemIcon class for control items)
  • The deprecated avatar parameter of OudsFilterChip/OudsSuggestionChip is replaced by the icon parameter, typed OudsIcon, via the .icon named constructors
  • Import package:ouds_core/components/common/ouds_icon.dart and wrap your icon asset paths in OudsIcon(...)

Reason for Change: Avoid duplicating the same icon configuration (asset, tinting, background color, accessibility label) across multiple components and provide one consistent API for icon-bearing components

2. OudsTextInput / OudsPhoneNumberInput — Typed prefix/suffix icon configuration with tinting support

OudsFormInputDecoration.prefixIcon and suffixIcon are no longer plain String/asset paths. prefixIcon now takes an OudsIcon directly, and suffixIcon takes an OudsTextInputSuffixIconButton whose icon field is also an OudsIcon. Both let you control whether the icon is tinted with the theme color or displayed with its original (multi-color) asset colors via OudsIcon's tinted parameter (defaults to true). The onSuffixPressed parameter on the decoration has been removed; the press callback now lives on OudsTextInputSuffixIconButton.onPressed.

Impact: Medium (breaking — any code setting prefixIcon, suffixIcon, or onSuffixPressed on OudsInputDecoration/OudsFormInputDecoration must be updated)

Before:

OudsInputDecoration(
  prefixIcon: 'assets/ic_heart.svg',
  suffixIcon: 'assets/ic_heart.svg',
  onSuffixPressed: () {},
)

After:

OudsInputDecoration(
  prefixIcon: OudsIcon(
    'assets/ic_heart.svg',
    tinted: true, // optional, defaults to true
  ),
  suffixIcon: OudsTextInputSuffixIconButton(
    icon: OudsIcon(
      'assets/ic_heart.svg',
      tinted: true, // optional, defaults to true
    ),
    onPressed: () {},
  ),
)

Required Action:

  • Wrap existing prefixIcon asset paths in OudsIcon(...) (no more intermediate OudsTextInputPrefixIcon)
  • Wrap existing suffixIcon asset paths in OudsTextInputSuffixIconButton(icon: OudsIcon(...), onPressed: ...), moving the onSuffixPressed callback into onPressed and the tinted value inside the nested OudsIcon
  • Set tinted: false on OudsIcon if the icon asset is multi-color and should keep its original colors instead of being tinted with the theme color

Reason for Change: Support untinted (multi-color) leading and trailing icons in text and phone number inputs, consistent with the tinted behavior available in OudsButton, OudsLink and chips, and reuse the shared OudsIcon configuration

3. OudsButton — icon now takes an OudsIcon

OudsButton.icon (and OudsButton.small) no longer accept a plain String asset path for icon. The parameter now takes an OudsIcon, which also carries the tinted and backgroundColor configuration.

Impact: Medium (breaking — any code passing a String to icon directly on OudsButton/OudsButton.small, must be updated)

Before:

OudsButton(
  icon: 'assets/ic_heart.svg',
  onPressed: () {},
)

After:

OudsButton(
  icon: OudsIcon(
    'assets/ic_heart.svg',
    tinted: false,
    backgroundColor: myBrandColor, // used only when tinted is false
  ),
  onPressed: () {},
)

Required Action:

  • Wrap the icon asset path in OudsIcon(...)
  • When tinted is false, provide a backgroundColor on OudsIcon if the icon needs a colored background to remain visible

Reason for Change: Reuse the shared OudsIcon configuration across all icon-bearing components instead of a component-specific tinted parameter

4. OudsLink — icon now takes an OudsIcon instead of String

OudsLink.icon (and the deprecated icon parameter of the default OudsLink() constructor) now take an OudsIcon instead of the String type.

Impact: Low (the constructor arguments are unchanged)

Before:

OudsLink.icon(
  label: 'Label',
  icon: 'assets/ic_heart.svg',
  onPressed: () {},
)

After:

OudsLink.icon(
  label: 'Label',
  icon: OudsIcon('assets/ic_heart.svg', tinted: true),
  onPressed: () {},
)

Required Action:

  • Replace the String parameter icon with OudsIcon(...)

Reason for Change: Reuse the shared OudsIcon configuration instead of a link-specific icon class

5. OudsFilterChip / OudsSuggestionChip — icon now takes an OudsIcon instead of String

OudsFilterChip.icon and OudsSuggestionChip.icon now take an OudsIcon instead of the String type.

Impact: Low (the constructor arguments are unchanged)

Before:

OudsFilterChip.icon(
  label: 'Label',
  icon: 'assets/ic_chip_heart.svg',
  selected: true,
  onSelected: (bool selected) {},
)

OudsSuggestionChip.icon(
  label: 'Label',
  icon: 'assets/ic_chip_heart.svg',
  onPressed: () {},
)

After:

OudsFilterChip.icon(
  label: 'Label',
  icon: OudsIcon('assets/ic_chip_heart.svg', tinted: true),
  selected: true,
  onSelected: (bool selected) {},
)

OudsSuggestionChip.icon(
  label: 'Label',
  icon: OudsIcon('assets/ic_chip_heart.svg', tinted: true),
  onPressed: () {},
)

Required Action:

  • Replace the String parameter icon with OudsIcon(...)

Reason for Change: Reuse the shared OudsIcon configuration instead of a chip-specific icon class

6. OudsCheckboxItem / OudsRadioButtonItem / OudsSwitchButtonItem — icon now takes an OudsIcon instead of OudsControlItemIcon

OudsCheckboxItem.icon, OudsRadioButtonItem.icon and OudsSwitchButtonItem.icon now take an OudsIcon instead of the removed OudsControlItemIcon class. OudsIcon still supports tinting the icon with the theme color (or keeping its original multi-color asset via tinted: false), exactly like OudsControlItemIcon did.

Impact: Low (breaking only for code referencing the OudsControlItemIcon type directly — the constructor arguments are unchanged)

Before:

OudsCheckboxItem(
  title: 'Label',
  icon: OudsControlItemIcon('assets/ic_heart.svg', tinted: true),
  value: true,
  onChanged: (value) {},
)

After:

OudsCheckboxItem(
  title: 'Label',
  icon: OudsIcon('assets/ic_heart.svg', tinted: true),
  value: true,
  onChanged: (value) {},
)

Required Action:

  • Replace OudsControlItemIcon(...) with OudsIcon(...) on OudsCheckboxItem, OudsRadioButtonItem and OudsSwitchButtonItem

Reason for Change: Reuse the shared OudsIcon configuration instead of a control-item-specific icon class

Icon Library Update — v2.3.0

The OUDS icon library has been updated to version 2.3.0. Some icon names or asset paths may have changed.

Impact: Medium (if using icon constants from the library)

Required Action:

  • Review any icon constants or asset paths you reference directly
  • Update to the new icon names from v2.3.0 if you receive compilation errors or missing asset warnings

New Components Added

Component Description
OudsListItem Standard list item component with leading/trailing content support

Component Updates (Non-breaking)

Component Change
Button Updated to v3.3.0 — icon now configured via the shared OudsIcon type, with tinted/untinted support
Link Updated to v2.4.0
Alert / Badge / Tag / List items OudsIconStatus.Neutral and OudsIconStatus.Accent gained tinted, backgroundColor and semanticsLabel parameters to control custom icon tinting, background and accessibility label
Progress Indicator Added size parameter to OudsCircularProgressIndicator for button integration
Tab Bar Fixed Invalid value: Not in inclusive range 0..2: 3 crash
Typography Added typography tokens component

Compatibility

  • Backward Compatibility: No (breaking changes in the icon API shared by OudsButton, OudsLink, OudsFilterChip, OudsSuggestionChip, OudsCheckboxItem, OudsRadioButtonItem, OudsSwitchButtonItem, and in the form input decoration API)
  • v2.1.0 Support: Ended with this release

v2.0.0 → v2.1.0

Overview

This release adds the Navigation Button, Circular Progress Indicator, and Linear Progress Indicator components, and updates design tokens to v2.6.0.

Before You Begin

Prerequisites

  • Use version 2.0.0 or older

Breaking Changes

None.

New Components Added

Component Description
OudsNavigationButton Navigation button component
OudsCircularProgressIndicator Circular (indeterminate/determinate) progress indicator
OudsLinearProgressIndicator Linear (indeterminate/determinate) progress indicator

Token Updates — v2.6.0

Design tokens have been updated to version 2.6.0.

Impact: Low (only if overriding tokens directly in a custom theme)

Required Action:

  • If you override tokens in a custom theme, audit your overrides against the new token names

Compatibility

  • Backward Compatibility: Yes
  • v2.0.0 Support: Ended with this release

v1.3.1 → v2.0.0

Overview

This is a major release introducing rich text support across multiple components, significant design version updates, major token updates (v2.4.0 and v2.5.0), and an updated icon library (v1.6). It also brings improvements to the Tab Bar, Toolbar Top, Badge, Tag, Input Tag, Text Input, Password Input, Phone Number Input, Filter Chip, and Suggestion Chip components.

Before You Begin

Prerequisites

  • Use version 1.3.1 or older

Breaking Changes

1. Rich text (Markdown) support in multiple components

Several components have been updated to support Markdown formatting in their label/content parameters. The label (or equivalent text parameter) still accepts a plain String, but now also renders Markdown syntax (bold, italic, links, etc.).

Affected components: OudsAlertMessage, OudsSwitch, OudsRadioButton, OudsCheckbox, OudsTextInput, OudsPinCodeInput, OudsPhoneNumberInput

Impact: Low (additive — existing plain strings continue to work as before)

Required Action:

  • No action required (backward compatible)
  • Optionally use Markdown syntax in labels to add bold, italic, or link formatting

Reason for Change: Provide richer content support across input and control components

2. Token breaking changes — v2.4.0 and v2.5.0

Design tokens have been updated to versions 2.4.0 and 2.5.0. These major token updates may rename or restructure token keys.

Impact: Medium (only if overriding tokens directly in a custom theme)

Required Action:

  • If you override tokens in a custom theme, audit your overrides against the new token names
  • Rebuild and check for compilation errors related to missing or renamed token properties

Reason for Change: Align with latest design system token specification

3. Icon library update — v1.6

The OUDS icon library has been updated to version 1.6. Some icon names or asset paths may have changed.

Impact: Medium (if using icon constants from the library)

Required Action:

  • Review any icon constants or asset paths you reference directly
  • Update to the new icon names from v1.6 if you receive compilation errors or missing asset warnings

4. OudsLink — Dedicated named constructors for icon and navigation variants

OudsLink now provides dedicated named constructors for every non text-only variant. The generic OudsLink() constructor's layout parameter is now deprecated in favor of these constructors.

Impact: Low (additive — the default constructor keeps working for text-only and legacy usages)

Before:

OudsLink(
  label: 'Label',
  icon: 'assets/ic_heart.svg',
)

OudsLink(
  label: 'Label',
  layout: OudsLinkLayout.back,
)

OudsLink(
  label: 'Label',
  layout: OudsLinkLayout.next,
)

After:

OudsLink.icon(
  label: 'Label',
  icon: 'assets/ic_heart.svg',
  tinted: true,
)

OudsLink.previous(label: 'Label')

OudsLink.next(label: 'Label')

OudsLink.external(label: 'Label')

Required Action:

  • Replace OudsLink(icon: ...) with OudsLink.icon(icon: ..., tinted: ...)
  • Replace OudsLink(layout: OudsLinkLayout.back) with OudsLink.previous(...)
  • Replace OudsLink(layout: OudsLinkLayout.next) with OudsLink.next(...)
  • Use OudsLink.external(...) for links navigating outside the current product, service or application
  • Text-only links keep using the default OudsLink(...) constructor unchanged

Reason for Change: Improve type safety and API clarity by making each link variant explicit through its own constructor, consistent with OudsTag and OudsBadge

5. OudsFilterChip — avatar parameter deprecated in favor of OudsFilterChip.icon

The avatar parameter of the default OudsFilterChip() constructor is now deprecated. Use the OudsFilterChip.icon named constructor with its icon parameter instead, for consistency with the rest of the API.

Impact: Low (additive — avatar still works but should be migrated)

Before:

OudsFilterChip(
  label: 'Label',
  avatar: 'assets/ic_chip_heart.svg',
  selected: true,
  onSelected: (bool selected) {},
)

After:

OudsFilterChip.icon(
  label: 'Label',
  icon: 'assets/ic_chip_heart.svg',
  selected: true,
  onSelected: (bool selected) {},
)

Required Action:

  • Replace OudsFilterChip(avatar: ...) with OudsFilterChip.icon(icon: ...)
  • Text-only filter chips keep using the default OudsFilterChip(...) constructor unchanged

Reason for Change: Align OudsFilterChip's icon parameter naming with its own .icon named constructor, avoiding two different parameter names (avatar vs icon) for the same purpose

6. OudsSuggestionChip — avatar parameter deprecated in favor of OudsSuggestionChip.icon

The avatar parameter of the default OudsSuggestionChip() constructor is now deprecated. Use the new OudsSuggestionChip.icon named constructor with its icon parameter instead, for consistency with OudsFilterChip. This named constructor also introduces a tinted parameter to control whether the icon is tinted with the theme color, and a contentDescription parameter for accessibility on icon-only chips.

Impact: Low (additive — avatar still works but should be migrated)

Before:

OudsSuggestionChip(
  label: 'Label',
  avatar: 'assets/ic_chip_heart.svg',
  onPressed: () {},
)

After:

OudsSuggestionChip.icon(
  label: 'Label',
  icon: 'assets/ic_chip_heart.svg',
  tinted: true,
  onPressed: () {},
)

Required Action:

  • Replace OudsSuggestionChip(avatar: ...) with OudsSuggestionChip.icon(icon: ...)
  • Text-only suggestion chips keep using the default OudsSuggestionChip(...) constructor unchanged

Reason for Change: Align OudsSuggestionChip's icon parameter naming with OudsFilterChip's .icon named constructor, avoiding two different parameter names (avatar vs icon) for the same purpose

Component Design Version Updates

Several components have been updated to align with new design specification versions. These changes are primarily visual and do not require code changes unless you override component tokens in a custom theme.

Impact: Low–Medium (visual changes; verify rendering after upgrading)

Required Action:

  • Verify the visual appearance and accessibility behaviour of each updated component after upgrading
  • If you override component tokens in a custom theme, check that your overrides are still valid
Component New Design Version
OudsTextInput v1.4
OudsPasswordInput v1.3
OudsFilterChip / OudsSuggestionChip v1.4
OudsBadge (icon variant) v1.3.0
OudsPhoneNumberInput v1.3
OudsTag v1.5
OudsInputTag v1.2

Component Updates (Non-breaking)

Component Change
Tab Bar Updated selected tab indicator animation
Toolbar Top Badge support added in trailing actions
Bottom Bar Fixed inconsistent accessible order and zoom overlap
Password Input Fixed label truncation when zoom is applied
Filter Chip Fixed keyboard/Switch Access focus issue
Phone Number Input Added interaction hint for accessibility
Input Tag Fixed button role for accessibility

Compatibility

  • Backward Compatibility: No (breaking changes in token API, icon API, and component label parameters)
  • v1.3.1 Support: Ended with this release

Note: v1.3.1 is a maintenance release with bug fixes and improvements. No migration is required.

v1.3.0 → v1.3.1

Overview

This is a maintenance and patch release focusing on bug fixes and accessibility improvements.

Compatibility

  • Backward Compatibility: Full (no breaking changes)
  • Migration Required: No

v1.2.0 → v1.3.0

Overview

This release adds new components (Bottom sheet, Alert message, Inline alert), updates the Pin code input with optional keyboard type, and introduces new named constructors for OudsTag and OudsBadge components with deprecated old APIs.

Before You Begin

Prerequisites

  • Use version 1.2.0 or older

Breaking Changes

1. OudsTag — Migration to named constructors

The generic OudsTag() constructor is now deprecated. Use the new named constructors based on your tag type.

Impact: High

Before (v1.2.x):

// Text only tag
OudsTag(
  label: 'My Tag',
  status: OudsTagStatus.positive,
  size: OudsTagSize.small,
)

// Tag with icon
OudsTag(
  label: 'Custom',
  layout: OudsTagLayout.textAndIcon,
  status: OudsTagStatus.neutral,
  icon: 'assets/custom_icon.svg',
)

// Tag with bullet
OudsTag(
  label: 'Info',
  layout: OudsTagLayout.textAndBullet,
  status: OudsTagStatus.info,
)

After (v1.3.0):

// Text only tag
OudsTag.text(
  label: 'My Tag',
  status: Positive(),
  size: OudsTagSize.small,
)

// Tag with icon
OudsTag.icon(
  label: 'Custom',
  status: Neutral(icon: 'assets/custom_icon.svg'),
)

// Tag with bullet
OudsTag.bullet(
  label: 'Info',
  status: Info(),
)

Required Action:

  • Replace OudsTag(...) with OudsTag.text(), OudsTag.icon(), or OudsTag.bullet()
  • Replace OudsTagStatus enum values with OudsIconStatus classes:
Old (OudsTagStatus) New (OudsIconStatus)
OudsTagStatus.positive Positive()
OudsTagStatus.negative Negative()
OudsTagStatus.info Info()
OudsTagStatus.warning Warning()
OudsTagStatus.accent Accent()
OudsTagStatus.neutral Neutral()
  • Remove icon parameter; pass icon via status: Accent(icon: 'path') or Neutral(icon: 'path')
  • Remove layout parameter; the layout is now determined by the named constructor

Reason for Change: Improve type safety, simplify API, and align Tag with the unified OudsIconStatus model shared with Badge

2. OudsBadge — Migration to named constructors

The generic OudsBadge() constructor is now deprecated. Use the new named constructors.

Impact: High

Before (v1.2.x):

// Standard badge (dot)
OudsBadge(
  status: OudsBadgeStatus.positive,
  size: OudsBadgeSize.medium,
)

// Badge with count
OudsBadge(
  status: OudsBadgeStatus.negative,
  size: OudsBadgeSize.large,
  label: '5',
)

// Badge with icon
OudsBadge(
  status: OudsBadgeStatus.info,
  size: OudsBadgeSize.large,
  icon: Icons.check,
)

After (v1.3.0):

// Standard badge (dot)
OudsBadge.standard(
  status: Positive(),
  size: OudsBadgeSize.medium,
)

// Badge with count
OudsBadge.count(
  status: Negative(),
  size: OudsBadgeSize.large,
  label: '5',
)

// Badge with icon
OudsBadge.icon(
  status: Info(),
  size: OudsBadgeSize.large,
)

Required Action:

  • Replace OudsBadge(...) with OudsBadge.standard(), OudsBadge.count(), or OudsBadge.icon()
  • Replace OudsBadgeStatus enum values with OudsIconStatus classes (same mapping as Tag above)
  • Remove icon parameter; icon is now driven by the status parameter

Reason for Change: Align Badge API with the unified OudsIconStatus model

3. OudsPinCodeInput — new keyboardType parameter

A new optional keyboardType parameter has been added to OudsPinCodeInput. The default remains numeric.

Impact: Low (non-breaking, additive)

Before (v1.2.x):

OudsPinCodeInput(
  length: 6,
  onCompleted: (code) => print(code),
)

After (v1.3.0):

OudsPinCodeInput(
  length: 6,
  keyboardType: OudsPinCodeKeyboardType.alphanumeric, // optional, default is numeric
  onCompleted: (code) => print(code),
)

Required Action:

  • No action required (backward compatible)
  • Optionally use keyboardType: OudsPinCodeKeyboardType.alphanumeric if needed

4. Tokens update — Bullet List and Alert component tokens

Component tokens for Bullet List and Alert have been updated to align with design tokens v1.9.0.

Impact: Low (only if using raw token values directly)

Required Action:

  • If you override bullet list or alert tokens in a custom theme, verify your overrides still apply

New Components Added

Component Class Description
Bottom Sheet OudsBottomSheetScaffold, OudsModalBottomSheet Standard and modal bottom sheets
Alert Message OudsAlertMessage Contextual alert messages with status
Inline Alert OudsInlineAlert Inline alert banners within content

Compatibility

  • Backward Compatibility: Partial (deprecated constructors still work with warnings)
  • v1.2.0 Support: Until release of next major version

v1.1.x → v1.2.0

Overview

This release introduces the Toolbar Top and Top App Bar components, adds French language support, and includes breaking changes to the Tag component configuration API.

Before You Begin

Prerequisites

  • Use version 1.1.x or older

Breaking Changes

1. Removal of OudsTagConfig from theme configuration

OudsTagConfig usage in OudsThemeConfigModel is now deprecated. Rounded corners are now built directly into the OudsTag component via the roundedCorners parameter.

Impact: High

Before (v1.1.x):

OudsThemeConfigModel(
  tag: OudsTagConfig(roundedCorners: true),
  child: MyApp(),
)

OudsTag(
  label: 'My Tag',
  // corner style came from theme config
)

After (v1.2.0):

OudsThemeConfigModel(
  // tag config deprecated, remove it
  child: MyApp(),
)

OudsTag(
  label: 'My Tag',
  roundedCorners: true, // now a direct parameter on the component
)

Required Action:

  • Remove tag: OudsTagConfig(...) from OudsThemeConfigModel
  • Use roundedCorners parameter directly on OudsTag widget

Reason for Change: Simplify the Tag API and align with design specifications (#598)

2. Updated status icons in Badge and Tag

The icon assets used for status indicators in OudsBadge and OudsTag have been updated to use OUDS icon status system.

Impact: Medium

Required Action:

  • If you referenced specific icon assets for badge/tag status, update to the new icon set
  • Verify your custom status icons still render correctly

Reason for Change: Align with updated design specifications (#597)

New Components Added

Component Class Description
Toolbar Top OudsToolbarTop iOS-style toolbar with leading/trailing actions
Top App Bar OudsTopAppBar Material-style top app bar with title and actions

Configuration uses OudsTopBarActionConfig factory constructors:

OudsTopBarActionConfig.icon(icon: 'assets/icon.svg', onActionPressed: () {})
OudsTopBarActionConfig.text(actionLabel: 'Done', onActionPressed: () {})
OudsTopBarActionConfig.back(onActionPressed: () => Navigator.pop(context))
OudsTopBarActionConfig.close(onActionPressed: () => Navigator.pop(context))
OudsTopBarActionConfig.none() // No action

Compatibility

  • Backward Compatibility: No (due to OudsTagConfig deprecation)
  • v1.1.x Support: Until release of next minor version

v1.0.0 → v1.1.1

Overview

This release introduces the Orange Compact theme, adds Navigation bar and Bottom Navigation components, deprecates OrangeTheme, updates OudsButton to full width, and updates tokens to v1.9.0.

Before You Begin

Prerequisites

  • Use version 1.0.0

Breaking Changes

1. Deprecated OrangeTheme — Use OudsOrangeTheme instead

OrangeTheme has been marked as @deprecated. Use OudsOrangeTheme instead.

Impact: Medium

Before (v1.0.0):

import 'package:ouds_theme_orange/ouds_theme_orange.dart';

OrangeTheme(
  child: MyApp(),
)

After (v1.1.x):

import 'package:ouds_theme_orange/ouds_theme_orange.dart';

OudsOrangeTheme(
  child: MyApp(),
)

Required Action:

  • Replace all OrangeTheme usages with OudsOrangeTheme

Reason for Change: Consistent naming convention with Ouds prefix (#610)

2. OudsButton — Full width by default

OudsButton now takes the full available width by default.

Impact: Medium

Before (v1.0.0):

// Button sized to its content
OudsButton(
  label: 'Click me',
  onPressed: () {},
)

After (v1.1.x):

// Button now takes full width by default
// To restore old behavior, constrain it:
SizedBox(
  width: 200, // or use IntrinsicWidth
  child: OudsButton(
    label: 'Click me',
    onPressed: () {},
  ),
)

Required Action:

  • If you relied on the button being sized to its content, wrap it in a SizedBox or IntrinsicWidth

Reason for Change: Align with design specifications (#577)

3. New Orange Compact theme package

A new theme ouds_theme_orange_compact is available for compact layouts.

Impact: Low (additive)

// Add to pubspec.yaml
dependencies:
  ouds_theme_orange_compact: ^1.1.1

import 'package:ouds_theme_orange_compact/ouds_theme_orange_compact.dart';

OudsOrangeCompactTheme(
  child: MyApp(),
)

Required Action:

  • No action required unless you want to use the compact theme

4. Token updates — v1.9.0

Input tag tokens and Orange Compact theme tokens have been updated.

Impact: Low

Required Action:

  • If you override input tag tokens in a custom theme, verify your overrides still apply

New Components Added

Component Class Description
Navigation Bar OudsNavigationBar Material navigation bar with items
Bottom Navigation OudsBottomBar Bottom navigation bar
Navigation Bar Item OudsNavigationBarItem Individual navigation item 
OudsNavigationBar(
  selectedIndex: _currentIndex,
  onDestinationSelected: (index) => setState(() => _currentIndex = index),
  items: [
    OudsNavigationBarItem(icon: 'assets/home.svg', label: 'Home'),
    OudsNavigationBarItem(icon: 'assets/search.svg', label: 'Search'),
    OudsNavigationBarItem(icon: 'assets/profile.svg', label: 'Profile'),
  ],
)

Compatibility

  • Backward Compatibility: Partial (deprecated APIs still work with warnings)
  • v1.0.0 Support: Until release of next minor version

Support

If you encounter issues during migration: