Framework
Components
The catalog of all components provided by OUDS. It contains also View extensions and ViewModifiers to apply tokens and styles on components and higher-level views.
Overview
Components are grouped in several categories, the same as the ones defined in the Figma design kit: Actions component are for example buttons. Navigations group contains links, inputs group has checkboxes, radio buttons and switches, layouts group is dedicated to things like dividers. You can get more details about them in the categories below:
Customize components
Apply a specific shadow effect (elevation tokens)
The unified design system implemented by OUDS iOS library allows to apply elevation effets on a View, i.e. a shadow under the component. Because the design tool in use is Figma which defines such shadow with a blur and a spread radiuses, and because SwiftUI uses only its own radius definition, an extension of View has been implemented to let users apply some effect using an ElevationCompositeSemanticToken from the OUDSTokensSemantic library thanks to the method shadow(elevation: ElevationCompositeSemanticToken).
// For example, apply the elevation effect "drag" from your theme:
myView.shadow(theme.elevations.drag)
In details how it works:
// In the theme this "drag" has been defined for example like:
@objc open var drag: ElevationCompositeSemanticToken { ElevationCompositeSemanticToken(ElevationRawTokens.bottom_3_500) }
// And if you look deeper, the raw token "bottom_3_500" can be like:
public static let bottom_3_500 = ElevationCompositeRawToken(x: x0, y: y300, blur: blur400, color: ColorRawTokens.opacityBlack320)
// Blur will be used to compute the radius value
Apply a specific typography (font tokens)
Your application identity can be strongly based on the typography you use, i.e. the font family you choose and other configuration details like the font size or the font weight.
With OUDS, typography depends to the class size, i.e. whether or not the application is in compact mode or in regular mode, and is defined with a MultipleFontCompositeSemanticToken defined in the FontSemanticTokens.
The theme contains lots of MultipleFontCompositeSemanticToken listing all the combinations of typography you can apply, and these composite semantic tokens use composite raw tokens. For example:
However the theme must know which font family to apply, and this font family can be a custom one or the system one. Thus, we let the users define the font family they want by overriding the family property. This value will be used to compute the typography, if not defined the default system font will be used.
Thus, if you want to apply a specific typography to a View (supposing the semantic tokens are defined in the theme), just call the method you want and gives as parameter the theme (to get the custom font if defined):
// Apply typography "body default small"
myView.bodyDefaultSmall(theme)
// Apply typography "label strong X large"
myView.labelStrongXLarge(theme)
// Etc.
In details how it works:
// Here is a definition of a semantic token inside the theme for typography "displayMedium":
@objc open var displayMedium: MultipleFontCompositeSemanticToken {
MultipleFontCompositeSemanticToken(compact: bold750, regular: bold1050)
}
// And here are the raw tokens definitions:
let bold750 = FontCompositeSemanticToken(size: size750, lineHeight: lineHeight850, weight: weightBold)
let bold1050 = FontCompositeSemanticToken(size: size1050, lineHeight: lineHeight1150, weight: weightBold)
These view modifiers are available for any View object, you can get the curated list in the documentation.
Apply a specific border (border tokens)
This module exposes the helper border(style:width:radius:color:) so as to apply border semantic tokens on a view in order to define a border effect. The helper is available through View, and tokens through the provider of the theme.
@Environment(\.theme) private var theme
var body: some View {
SomeView()
.border(
style: theme.borders.styleDefault,
width: theme.borders.widthThin,
radius: theme.borders.radiusNone,
color: theme.colors.borderDefault)
}
Apply specific colors
Colors can be applied on view for background and foreground colors, foreground style, accent color or tint color. Some helpers are available in the OUDS API to avoid to use the color(for:) method.
// Given a color at theme.colors.bgPrimary
// This token can have light and dark declinations
@Environment(\.theme) private var theme
// Apply a foreground style
someView.foregroundStyle(theme.colors.bgPrimary)
// Apply a foreground color
someView.foregroundColor(theme.colors.bgPrimary)
// Apply a background
someView.background(theme.colors.bgPrimary)
// Apply an accent color
someView.accentColor(theme.colors.bgPrimary)
// Apply a tint color
someView.tint(theme.colors.bgPrimary)
Flip images according to layouts
Images bring meanings, and are used in components. But sometimes, depending to your layouts (right to left (RTL) or left to right (LTR)), if the whole layout of your app changes, the images in use can loose meanings or have another one (except if they are asymetric). Even if some assets can be defined in a project with specific RTL/LTR variants, images can be loaded outside and in some case, in the end, must not be mirrored.
If your application manages several languages with RTL and LTR, here is a simple trick to flip the icons depending to the layout for the cases you want. The flipIcon flag available in components can be used.
// Get the layout direction in your View
@Environment(\.layoutDirection) private var layoutDirection
// Because by default icons are not flipped, i.e. more LTR flavoured, use a simple comparison
// (layoutDirection == .rightToLeft)
// For example in a checkbox item
OUDSCheckboxItem(...,
flipIcon: (layoutDirection == .rightToLeft),
)
Change font family according to locale or preferred language
If you use for example one of the Orange themes, you may for sure use the Helvetica Neue font family. However, this font family manages latin alphabet and not arabic alphabet. Nevertheless a trick can be done to use the suitable Helvetica Neue font family according to the language.
/// Returns the Helvetica Neue font family to use depending to the preferred language or locale
func localizedHelveticaFont() -> String {
return (OUDSUtils.isArabicLanguageInUse() ? "Helvetica Neue Arabic" : "Helvetica Neue")
}
/// Instanciate your Orange theme using the font family.
/// Thus when the user will change the app language the app will be restarted, repainted and the theme updated
let localizedOrangeTheme: OUDSTheme = OrangeTheme(fontFamily: localizedHelveticaFont())
Caution
For legal reasons OUDS does not provide the Helvetica Neue Arabic nore Helvetica Neue assets. You will have to get them and register the fonts files in your app
Note
For cyrillic alphabet the Orange Brand does not provide Helvetica Neue variant, you can use Arial instead
Registering font assets
If you need to use some fonts like Helvetica Neue Arabic, you will need to add the TTF files in your project and somewhere somehow register them.
private static var fontsAlreadyRegistered = false
// Fonts are defined in Resources/Fonts in TTF files.
private func registerFonts() {
if !Self.fontsAlreadyRegistered {
let fonts = Bundle.main.urls(forResourcesWithExtension: "ttf", subdirectory: nil)
fonts?.forEach { CTFontManagerRegisterFontsForURL($0 as CFURL, .process, nil) }
Self.fontsAlreadyRegistered = true
}
}
Topics
Structures
struct OUDSAlertMessageAlert message is a UI element that displays system feedback, status changes or required action; throughout detailed, prominent, persistent and actionable communication. Alert message includes functional icon and semantic colour, and may include as well a close button and/or action link. Alert Message does not disappear automatically and remains visible until dismissed or resolved by the user.
struct OUDSBadgeBadge is a UI element that emphasizes system notifications, status, or the categorization of an information, throughout colour only. Badge is rendered as a coloured shape, without icon, text or number; and its chosen size remains unchanged regardless of the changes of the interface size.
struct OUDSBulletListBullet list is a UI element that helps to view in related individual text items grouped together; items usually starting with a number or a bullet. Bullet list is also known as Unordered list or Ordered list and is not an interactive element by default.
struct OUDSButtonButton is a UI element that triggers an action or event, and is used to initiate tasks or confirming an action. Button appears in different layouts, styles and states to indicate hierarchy or emphasis.
struct OUDSCheckboxCheckbox is a UI element that allows to select multiple options from a set of mutually non exclusive choices. Checkbox that does not show icon or text, provides greater flexibility when creating other components that require a checkbox to be displayed.
struct OUDSCheckboxIndeterminateCheckbox is a UI element that allows to select multiple options from a set of mutually non exclusive choices. Checkbox that does not show icon or text, provides greater flexibility when creating other components that require a checkbox to be displayed.
struct OUDSCheckboxItemCheckbox is a UI element that allows to select multiple options from a set of mutually non exclusive choices. Checkbox item covers a wider range of contexts by allowing to toggle the visibility of additional text labels and icon assets.
struct OUDSCheckboxItemIndeterminateCheckbox is a UI element that allows to select multiple options from a set of mutually non exclusive choices. Checkbox item covers a wider range of contexts by allowing to toggle the visibility of additional text labels and icon assets.
struct OUDSCheckboxPickerA picker allowing to expose several checkboxes and select some of them within the others. Each checkbox contains a “tag”, i.e. a supposed to be unique value. The picker will expose the choosen values using this “tag”. It has also some configuration elements which will override the one applied to nested OUDSCheckboxItem (divider, read only and error mode, layout and outlined)
struct OUDSCheckboxPickerDataThe data to use to populate the picker of OUDSCheckboxItem objects. Each property in this OUDSCheckboxPickerData is used to define the suitable OUDSCheckboxItem.
struct OUDSChipPickerA picker allowing to expose several filter chips and proposing single or multiple selections.
struct OUDSChipPickerDataThe data to use to populate the picker of OUDSFilterChip objects. Each property in this OUDSChipPickerData is used to define the suitable OUDSFilterChip.
struct OUDSColoredSurfaceUsed to define if a content is used on a colored surface.
struct OUDSColoredSurfaceModifierViewModifier which helps to apply a predefined color mode on a view. This mode is based on OUDSColoredSurface.SurfaceColor and defines which tyê of color scheme and monochrome must be considered.
struct OUDSFilterChipFilter chip is a UI element that allows to select or deselect an option within a series, and is commonly used to capture filtering decisions. Filter chip allows to filter content by being selected or deselected. It can be toggled “On” or “Off” to refine displayed results, and selected Filter Chips remain visually distinct to indicate active filters.
struct OUDSHStackCreates an HStack with spacing scaled according to horizontalSizeClass base on OUDS MultipleSpaceSemanticToken.
struct OUDSHorizontalDividerDivider is a UI element that allows to structure the content by visually separating the content zones. Divider improves readability and content organization without introducing a stronger visual hierarchy like a heading or a container would. A horizontal Divider is used to separate content laid out one under the other (VStack). The divider can be colored using dedicated OUDSDividerColor colors. The thickness (height) is fixed by dedicated token from OUDSTheme.
struct OUDSIconUse to provide an asset to ouds in order to be added in some components. The icon can be flipped for RTL consideration and an associated acessibilityLabelmust be provided if the icon is not decorative.
struct OUDSInlineAlertInline alert is a lightweight UI element, placed in the content flow, that displays information, system feedback, status changes throughout short, prominent, persistent and non actionable communication. Inline alert includes functional icon and semantic colour, and does not include a close button and/or action link. Inline alert does not disappear and remains visible.
struct OUDSInputTagInput tag is a UI element that allows to enter multiple values, each represented as a tag. As users type and submit values (usually by pressing enter, comma, or tab), each value is transformed into a tag. Input tag is often used for adding labels, categories, or participants.
struct OUDSLinkLink is a UI element that allows to navigate from one location to another, either within the same page or across different pages in the same resource, or to an external resource. Link’s primary function is navigation and it communicates its interactive nature visually and semantically.
struct OUDSNavigationStackUse a navigation stack to present a stack of views over a root view. and let system applies theme colors on navigation bar appearance.
struct OUDSPasswordInputPassword input is a UI element that allows to securely and confidentially capture a user’s password. As it is based on the OUDSTextInput, it offers same layout and the same elements of configuration.
struct OUDSPinCodeInputPIN code input is a UI element that allows to capture short, fixed-length numeric codes, typically for authentication or confirmation purposes, such as a four, six or eight-digit personal identification number (PIN). PIN code input is presented as a series of individual input fields or boxes, each representing a single digit, to enhance readability and encourage accurate input, while supporting smooth keyboard navigation and secured input masking if needed.
struct OUDSRadioRadio button is a UI element that allows to select a single option from a set of mutually exclusive choices. Radio button that does not show icon or text, provides greater flexibility when creating other components that require a Radio button to be displayed.
struct OUDSRadioItemRadio button item is a UI element that allows to select a single option from a set of mutually exclusive choices. Radio button item covers a wider range of contexts by allowing to toggle the visibility of additional text labels and icon assets.
struct OUDSRadioPickerA picker allowing to expose several radio buttons and choose only one within the others. Each radio button contains a “tag”, i.e. a supposed to be unique value. The picker will expose the choosen value through this “tag”. It has also some configuration elements which will override the one applied to nested OUDSRadioItem (divider, read only and error mode, layout and outlined)
struct OUDSRadioPickerDataThe data to use to populate the picker of OUDSRadioItem objects. Each property in this OUDSRadioPickerData is used to define the suitable OUDSRadioItem.
struct OUDSSuggestionChipSuggestion chip is a UI element that allows to present recommended or predictive options based on user’s input or context, and is commonly used to capture filtering decisions. Suggestion chip is typically non-selected by default and can be tapped or clicked to apply the suggestion, streamlining input and enhancing usability. Chips can show multiple interactive elements together in the same area, such as a list of selectable movie times, or a serie of email contacts. Best suited for category-based filters that do not require additional visual elements.
struct OUDSSwitchSwitch is a UI element that allows to toggle between two states, typically “On” and “Off”, and used to enable or disable features, options or settings. Switch that does not show icon or text, provides greater flexibility when creating other components that require a Switch to be displayed.
struct OUDSSwitchItemSwitch item is a UI element that allows to toggle between two states, typically “On” and “Off”, and used to enable or disable features, options or settings. Switch Item covers a wider range of contexts by allowing to toggle the visibility of additional text labels and icon assets.
struct OUDSTabBarThe Tab bar is a system navigation component with a position which can vary depending to the OS. The tab bar can be found at the bottom of the screen for iOS. It can vary for iPadOS. It allows users to switch between the sections of an app. Each tab can be represented by a label, optionally paired with an icon, and maintains persistent visibility across top-level destinations.
struct OUDSTagTag is a UI element that allows to display short info like a label, keyword, or category. Tag helps users quickly find, group, or understand content.
struct OUDSTextAreaText area is a UI element that allows to type, edit, or select longer blocks of textual data, such as comments, messages or descriptions; by expanding vertically and offering more space to input text. It provides a visual and interactive affordance for multiline text entry while supporting labels, placeholders, descriptions, and validation feedback.
struct OUDSTextInputText input is a UI element that allows to enter, edit, or select single-line textual data. Text input is one of the most fundamental form elements used to capture user input such as names, emails, passwords, or search queries. It provides a visual and interactive affordance for text entry while supporting labels, placeholders, icons, descriptions, and validation feedback.
struct OUDSToolBarBottomThe bottom toolbar is a kind of navigation bar component used to display leading and trailing actions at the bottom of the screen when supported.
struct OUDSToolBarItemA strongly typed toolbar item container used inside:
struct OUDSToolBarTopThe top toolbar (aka navigation bar on iOS and iPadOS 18 and lower) sits at the top of the screen and provides contextual information and controls related to the current view. It typically displays the page title, and may include navigation actions such as “Back” or “Close” as well as supplementary actions. It can contains leading and trailing actions.
struct OUDSVStackCreates a VStack with spacing scaled according to verticalSizeClass base on OUDS MultipleSpaceSemanticToken.
struct OUDSVerticalDividerDivider is a UI element that allows to structure the content by visually separating the content zones. Divider improves readability and content organization without introducing a stronger visual hierarchy like a heading or a container would. A vertical Divider is used to separate content laid out side by side (HStack). The divider can be colored using dedicated OUDSDividerColor colors. The thickness (width) is fixed by dedicated token from OUDSTheme.
Enumerations
Extended Modules