ouds-ios-guide-create-theme

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill: ouds-ios-guide-create-theme

Step-by-step guide to create a **custom OUDS theme** for an iOS/iPadOS app.

---

## 0. Prerequisites — ask the user first

Before writing any code, ask the user these two questions:

**Question 1 — Which strategy?**

| Strategy | When to choose |
|---|---|
| **A — Subclass `OrangeTheme`** *(recommended)* | Orange brand assets are needed; only some tokens differ from Orange defaults |
| **B — From scratch on `OUDSTheme`** | Fully independent brand (no Orange assets); all tokens are custom |
| **C — Mix existing providers** | Compose providers from existing themes without creating a new subclass |

**Question 2 — Custom fonts?**

Does the theme need to embed `.ttf` font files? If yes, collect:
- Font family name (as shown in Font Book)
- PostScript name for each weight used

---

## 📚 Reference documentation

To get the full list of properties / tokens by protocols:

- **General OUDS documentation** : https://ios.unified-design-system.orange.com

- **Semantic tokens** : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/
  - `ColorSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/ColorSemanticTokens
  - `BorderSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/BorderSemanticTokens
  - `DimensionSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/DimensionSemanticTokens
  - `SizeSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/SizeSemanticTokens
  - `SpaceSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/SpaceSemanticTokens
  - `FontSemanticTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensSemantic/FontSemanticTokens
  - etc.

- **Component tokens** : https://ios.unified-design-system.orange.com/documentation/oudsTokensComponent/
  - `ButtonComponentTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensComponent/ButtonComponentTokens
  - `TextInputComponentTokens` : https://ios.unified-design-system.orange.com/documentation/oudsTokensComponent/TextInputComponentTokens
  - etc.

> **Tip** : To see all properties / tokens of a provider, look in files `Values/SemanticTokens/` or `Values/ComponentTokens/` in Orange theme from OUDS iOS repository.

---

## 1. Inheritance hierarchy

```
OUDSTheme                    ← base "abstract" class (open)
    │
    └── OrangeTheme          ← open, the ONLY publicly subclassable theme
            │
            └── YourTheme    ← your app's custom theme (Strategy A)

OUDSTheme
    └── YourTheme            ← from-scratch theme (Strategy B)
```

> **Rule:** Only `OrangeTheme` can be subclassed by external code.
> `SoshTheme`, `OrangeCompactTheme`, and `WireframeTheme` are all `final`
> but their tokens providers can be reused.

---

## 2. Strategy A — Subclass `OrangeTheme` *(recommended)*

### 2.1 Import

```swift
import OUDSThemesOrange
// or the umbrella product that includes it:
import OUDSSwiftUIOrange
```

### 2.2 Override only the providers you need

Each provider inherits from an `OrangeThemeXxxProvider` class. Override `@objc open` properties.

**Semantic token providers available to override** (Layer 2 — generic tokens):

| What to override | Orange base class to inherit |
|---|---|
| Borders (style / width / radius) | `OrangeThemeBorderSemanticTokensProvider` |
| Colors (light + dark via `MultipleColorSemanticToken`) | `OrangeThemeColorSemanticTokensProvider` |
| Color modes (for `OUDSColoredSurface`) | `OrangeThemeColorModeSemanticTokensProvider` |
| Color charts | `OrangeThemeColorChartSemanticTokensProvider` |
| Color decorative | `OrangeThemeColorDecorativeSemanticTokensProvider` |
| Effects | `OrangeThemeEffectSemanticTokensProvider` |
| Elevations / shadows | `OrangeThemeElevationSemanticTokensProvider` |
| Typography / fonts | `OrangeThemeFontSemanticTokensProvider` |
| Grids | `OrangeThemeGridSemanticTokensProvider` |
| Opacities | `OrangeThemeOpacitySemanticTokensProvider` |
| Dimensions (base scale) | `OrangeThemeDimensionSemanticTokensProvider` |
| Sizes (icon, component) | `OrangeThemeSizeSemanticTokensProvider` |
| Spaces (fixed, scaled) | `OrangeThemeSpaceSemanticTokensProvider` |

**Component token providers available to override** (Layer 3 — component-specific tokens):

| Component | Orange base class |
|---|---|
| Alert messages | `OrangeThemeAlertComponentTokensProvider` |
| Badge | `OrangeThemeBadgeComponentTokensProvider` |
| Bar (tab bar / toolbar) | `OrangeThemeBarComponentTokensProvider` |
| Bullet list | `OrangeThemeBulletListComponentTokensProvider` |
| Button | `OrangeThemeButtonComponentTokensProvider` |
| Checkbox | `OrangeThemeCheckboxComponentTokensProvider` |
| Chip | `OrangeThemeChipComponentTokensProvider` |
| Divider | `OrangeThemeDividerComponentTokensProvider` |
| Icon | `OrangeThemeIconComponentTokensProvider` |
| Link | `OrangeThemeLinkComponentTokensProvider` |
| List item | `OrangeThemeListItemComponentTokensProvider` |
| Pin code input | `OrangeThemePinCodeInputComponentTokensProvider` |
| Quantity input | `OrangeThemeQuantityInputComponentTokensProvider` |
| Radio button | `OrangeThemeRadioButtonComponentTokensProvider` |

From Orange-OpenSource/ouds-ios, MIT.

More from Orange-OpenSource/ouds-ios