ouds-ios-guide-migration

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill: ouds-ios-guide-migration

Migration guide from **v1.0.0** to **v3.2.0** (current). Covers all breaking changes and deprecated symbols.
For full before/after examples, refer to `MIGRATION.md` in the project root.

---

## Quick-reference: what changed, when

| From → To | Impact | Key changes |
|---|---|---|
| v1.0.0 → v1.1.0 | High | `Multiple*Tokens` → `Multiple*Token`; button border tokens shortened |
| v1.1.0 → v1.2.0 | High | Theme renamed: `OrangeBusinessTools` → `OrangeCompact` |
| v1.2.0 → v1.3.0 | Low | `oudsVerticalSizeClass` removed; `UnorderedIcon` → `UnorderedAsset` |
| v1.3.0 → v1.4.0 | Low | `ouds`-prefixed `View` methods removed; `OUDSTabBar(selected:)` → `(selectedTab:)` |
| v1.4.0 → v2.0.0 | High | Token renames (colors, elevations, sizes, badge, bar); charts provider renamed; toolbar action type enriched |
| v2.0.0 → v2.1.0 | Low | Component token `spacePaddingBlockDensityCompactTopAlignmentTopText_container` renamed |
| v2.0.0 → v2.2.0 | Medium | `OUDSBadge` split into `OUDSBadgeStandard`, `OUDSBadgeCount`, `OUDSBadgeIcon` |
| v2.2.0 → v2.3.0 | Low | `OUDSIcon` → `OUDSImage`; all `icon: Image` + `flipIcon` + `renderingMode` params replaced by `OUDSImage` |
| v2.3.0 → v3.0.0 | High | Button/tag/link component token renames (add `Default` suffix); `icon.colorContentDefault` removed; `theme.controlItem` → `theme.listItem`; `OUDSLink.Indicator.back` → `.previous`; `OUDSChipPickerData.Layout.icon(icon:…)` → `.image(image:)`; `.textAndIcon` → `.textAndImage`; alert status `.neutral(icon:)`/`.accent(icon:)` → `(image:)`; `OUDSBadgeIcon` status `.neutral(icon:flipped:renderingMode:)`/`.accent(…)` → `(image: OUDSImage)`; `forceOUDSLegacyTabBar` → `forceOUDSLegacyLayout`; `OUDSLegacyTabBarModifier` → `OUDSLegacyLayoutModifier`; `OUDSButton.Style.loading` → `.loading()`; `OUDSTag` `hasLoader:` removed → use `loadingLabel:`/`loadingKey:` inits, now with optional `progress:` |
| v3.0.0 → v3.2.0 | Low | `OUDSListItemData` — all 6 String/`AttributedString` initializers deprecated; new unified initializers `init(label: Label, …)` / `init(label: some View, accessibilityLabel:, …)` taking `OUDSListItemData.Label` + `OUDSTextualContent` (`.raw` / `.localized` / `.rich`) for `description` / `overline` / `extraLabel` / `helperText`. `OUDSTextualContent` becomes `public @frozen`; both it and `Label` conform to `ExpressibleByStringLiteral`. `Label.text` deprecated in favor of new `Label.textual(OUDSTextualContent, isBold:)`. `OUDSBulletList.Item` — `String` / `AttributedString` / `LocalizedStringKey` initializers deprecated; new `init(_: OUDSTextualContent, …)`. `OUDSTextArea` — `HelperText.plain` / `.rich` deprecated in favor of `.textual(OUDSTextualContent)`; `Status.error(message:)` / `.richError(message:)` deprecated in favor of `.textualError(message: OUDSTextualContent)`. `OUDSPasswordInput` — 4 initializers (`helperText` `String?` / `AttributedString`) deprecated; 2 new initializers taking `helperText: OUDSTextualContent?`. `OUDSTextInput` — 4 initializers (`helperText` `String?` / `AttributedString`) deprecated; 2 new initializers taking `helperText: OUDSTextualContent?`; `Status.error(message:)` / `.richError(message:)` deprecated in favor of `.textualError(message:)` (also used by `OUDSPasswordInput`). `OUDSPinCodeInput` — 3 initializers (`helperText` `String?` / `AttributedString` / `helperText key: LocalizedStringKey`) deprecated; 1 new initializer taking `helperText: OUDSTextualContent?`; `Status.error(message:)` / `.richError(message:)` deprecated in favor of `.textualError(message: OUDSTextualContent)`. `OUDSCheckboxItemIndeterminate` — 2 initializers (`errorText: String?`) deprecated; 2 new initializers taking `errorText: OUDSTextualContent?`. `OUDSSwitchItem`, `OUDSCheckboxItem` and `OUDSRadioItem` — 4 initializers each (`errorText` `String?` / `AttributedString`) deprecated; 2 new initializers each taking `errorText: OUDSTextualContent?`. `OUDSAlertMessage` — 8 initializers (`String` / `AttributedString` `description`, `[String]` / `[AttributedString]` `bulletList`) deprecated; 2 new initializers (`label:` / `_ key:`) taking `description: OUDSTextualContent?` and `bulletList: [OUDSTextualContent]`. |

---

## Migration workflow

1. **Detect** — grep for deprecated symbols (commands below).
2. **Transform** — apply the rules for the relevant version.
3. **Build** — `swift build` must succeed with zero errors.
4. **Check warnings** — `swift build 2>&1 | grep -i deprecated` must return nothing OUDS-related.
5. **Test** — `swift test` must pass.

---

## Detection grep commands

```bash
# Breaking changes (v3.0.0)
grep -rn \
  "theme\.controlItem\|icon\.colorContentDefault\|spaceInsetLoader\|\.sizeMaxHeightIconOnly\b\|\.sizeMinHeight\b\|\.sizeMinWidth\b\|\.sizeIcon\b\|\.sizeIconOnly\b\|\.sizeProgressIndicator\b\|\.spaceColumnGapIconChevron\b\|\.spaceColumnGapChevron\b\|\.spaceInsetIconOnly\b\|\.spacePaddingBlock\b\|\.spacePaddingInlineChevronEnd\b\|\.spacePaddingInlineChevronStart\b\|\.spacePaddingInlineEndIconStart\b\|\.spacePaddingInlineIconNone\b\|\.spacePaddingInlineStartIconEnd\b\|indicator: \.back\b\|forceOUDSLegacyTabBar\|OUDSLegacyTabBarModifier\|hasLoader:" \
  --include="*.swift" .

# Active deprecations (v2.x)
grep -rn \
  "OUDSBadge\b\|OUDSIcon\b\|icon: Image\|flipIcon\|renderingMode:\|spacePaddingBlockDensityCompactTopAlignmentTopText_container" \
  --include="*.swift" .

# Removed symbols (v1.x era)
grep -rn \
  "oudsVerticalSizeClass\|UnorderedIcon\|\.free(\|OUDSTabBar(selected:\|\.ouds[A-Z]\|Multiple.*Tokens\b\|OrangeBusinessTools\|buttonBorderRadius\|buttonBorderWidth" \
  --include="*.swift" .
```

---

## v1.0.0 → v1.1.0

| Old | New |
|---|---|
| `MultipleElevationCompositeRawTokens` | `MultipleElevationCompositeRawToken` |
| `MultipleColorSemanticTokens` | `MultipleColorSemanticToken` |
| `MultipleFontCompositeSemanticTokens` | `MultipleFontCompositeSemanticToken` |
| `MultipleFontLetterSpacingSemanticTokens` | `MultipleFontLetterSpacingSemanticToken` |
| `MultipleFontLineHeightSemanticTokens` | `MultipleFontLineHeightSemanticToken` |
| `MultipleFontSizeSemanticTokens` | `MultipleFontSizeSemanticToken` |
| `MultipleSizeSemanticTokens` | `MultipleSizeSemanticToken` |
| `MultipleSpaceSemanticTokens` | `MultipleSpaceSemanticToken` |
| `theme.button.buttonBorderRadiusDefault` | `theme.button.borderRadiusDefault` |
| `theme.button.buttonBorderRadiusRounded` | `theme.button.borderRadiusRounded` |
| `theme.button.buttonBorderRadiusSocial` | `theme.button.borderRadiusSocial` |
| `theme.button.buttonBorderWidthDefault` | `theme.button.borderWidthDefault` |
| `theme.button.buttonBorderWidthDefaultInteraction` | `theme.button.borderWidthDefaultInteraction` |
| `theme.button.buttonBorderWidthDefaultInteractionMono` | `theme.button.borderWidthDefaultInteractionMono` |

---

## v1.1.0 → v1.2.0

Replace everywhere: `OUDSThemeOrangeBusinessTools` → `OUDSThemeOrangeCompact`, `OrangeBusinessToolsTheme` → `OrangeCompactTheme`, `OrangeBusinessTools` → `OrangeCompact`.

---

## v1.2.0 → v1.3.0

- Remove all uses of `@Environment(\.oudsVerticalSizeClass)`.
- Rename `OUDSBulletList.UnorderedIcon` → `OUDSBulletList.UnorderedAsset`; case `.free(…)` → `.icon(…)`.

---

## v1.3.0 → v1.4.0

| Removed | Replacement |
|---|---|
| `.oudsForegroundStyle(_:)` | `.foregroundStyle(_:)` |
| `.oudsForegroundColor(_:)` | `.foregroundColor(_:)` |
| `.oudsBackground(_:)` | `.background(_:)` |
| `.oudsAccentColor(_:)` | `.accentColor(_:)` |
| `.oudsShadow(_:)` | `.shadow(_:)` |
| `.oudsBorder(style:width:radius:color:)` | `.border(style:width:radius:color:)` |
| `.oudsColoredSurface(_:)` | `.coloredSurface(_:)` |
| `.oudsGridMargin(_:)` | `.gridMargin(_:)` |
| `.oudsRequestAccessibleFocus(_:)` | `.requestAccessibleFocus(_:)` |
| `.oudsRequestAccessibleFocus(_:for:)` | `.requestAccessibleFocus(_:for:)` |
| `.oudsHorizontalDivider(dividerColor:)` | `.horizontal(color:)` |
| `.oudsVerticalDivider(color:)` | `.vertical(color:)` |
| `OUDSTabBar(selected: 0, count: 3) { … }` | `@State var selectedTab = 0; OUDSTabBar(selectedTab: $selectedTab, count: 3) { … }` |

---

## v1.4.0 → v2.0.0

### Renamed semantic tokens

| Old | New |
|---|---|
| `repositorySecondaryHigher` | `repositorySecondaryHigherHigh` |
| `overlayModalLight/Dark/` | `overlayModalSheetLight/Dark/` (drop `Modal`, add `Sheet`) |
| `xDefault`, `yDefault`, `blurDefault`, `spreadDefault` | `xElevated`, `yElevated`, `blurElevated`, `spreadElevated` |
| `colorDefaultLight/Dark` | `colorElevatedLight/Dark` |

From Orange-OpenSource/ouds-ios, MIT.

More from Orange-OpenSource/ouds-ios