diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a18f185de..5849253bc 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,23 +4,31 @@ Looking to contribute something to OUDS Android? **Here's how you can help.** Please take a moment to review this document in order to make the contribution process easy for everyone involved. -Following these guidelines helps to communicate that you respect the time of the developers managing and developing this Open Source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features. +Following these guidelines helps to communicate that you respect the time of the developers managing and developing this Open Source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches and features. ## Using the Issue Tracker -The [issue tracker](https://github.com/Orange-OpenSource/ouds-android/issues) is the preferred channel for [bug reports](#bug-reports), [feature requests](#feature-requests) and [submitting pull requests](#pull-requests), but please respect the following restrictions: +The [issue tracker](https://github.com/Orange-OpenSource/ouds-android/issues) is the preferred channel +for [bug reports](#bug-reports), [feature requests](#feature-requests) and [submitting pull requests](#pull-requests), but please respect the following +restrictions: -- Please **do not** use the issue tracker for personal support requests. [GitHub Discussions](https://github.com/Orange-OpenSource/ouds-android/discussions/categories/q-a) or our internal Orange communication tools are better places to get help. +- Please **do not** use the issue tracker for personal support + requests. [GitHub Discussions](https://github.com/Orange-OpenSource/ouds-android/discussions/categories/q-a) or our internal Orange communication tools are + better places to get help. - Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others. -- Please **do not** post comments consisting solely of "+1" or ":thumbsup:". Use [GitHub's "reactions" feature](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) instead. We reserve the right to delete comments which violate this rule. +- Please **do not** post comments consisting solely of "+1" or ":thumbsup:". + Use [GitHub's "reactions" feature](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) instead. We reserve the right to + delete comments which violate this rule. ## Issues and Labels Our bug tracker utilizes several labels to help organize and identify issues. Here's what they represent and how we use them: -- `feature` - Issues asking for a new feature to be added, or an existing one to be extended or modified. New features require a minor version bump (e.g., `v1.0.0` to `v1.1.0`). +- `feature` - Issues asking for a new feature to be added, or an existing one to be extended or modified. New features require a minor version bump (e.g., + `v1.0.0` to `v1.1.0`). - `help wanted` - Issues we need or would love help from the community to resolve. For a complete look at our labels, see the [project labels page](https://github.com/Orange-OpenSource/ouds-android/labels). @@ -37,7 +45,9 @@ Guidelines for bug reports: 3. **Isolate the problem** — ideally create a reduced reproducible test case. -A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What device(s) and OS experience the problem? Do other devices show the bug differently? What would you expect to be the outcome? All these details will help people to fix any potential bugs. +A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your +environment? What steps will reproduce the issue? What device(s) and OS experience the problem? Do other devices show the bug differently? What would you expect +to be the outcome? All these details will help people to fix any potential bugs. Example: @@ -59,15 +69,19 @@ Example: ## Feature Requests -Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to _you_ to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible. +Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible. ## Pull requests Good pull requests—patches, improvements, new features—are a fantastic help. They should remain focused in scope and avoid containing unrelated commits. -**Please ask first** before embarking on any **significant** pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project. For trivial things, or things that don't require a lot of your time, you can go ahead and make a PR. +**Please ask first** before embarking on any **significant** pull request (e.g., implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project. For trivial things, or +things that don't require a lot of your time, you can go ahead and make a PR. -Please adhere to the [coding guidelines](#code-guidelines) used throughout the project (indentation, accurate comments, etc.) and any other requirements (such as test coverage). +Please adhere to the [coding guidelines](#code-guidelines) used throughout the project (indentation, accurate comments, etc.) and any other requirements (such +as test coverage). Adhering to the following process is the best way to get your work included in the project: @@ -95,7 +109,8 @@ Adhering to the following process is the best way to get your work included in t git checkout -b ``` -4. Commit your changes in logical chunks. Use Git's [interactive rebase](https://help.github.com/articles/about-git-rebase/) feature to tidy up your commits before making them public. +4. Commit your changes in logical chunks. Use Git's [interactive rebase](https://help.github.com/articles/about-git-rebase/) feature to tidy up your commits + before making them public. 5. Locally merge (or rebase) the upstream development branch into your topic branch: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d914e7752..26d57fd23 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -56,7 +56,7 @@ _Note: Please transform `- [ ]` into `- (NA)` in the description when things are ### Checklist (for Core Team only) -- [ ] Manually test (dark mode, RTL, landscape display, tablet) +- [ ] Manually test (Dark mode, RTL, landscape display, tablet) - [ ] Documentation has been updated if relevant - [ ] Design review - [ ] A11y review diff --git a/README.md b/README.md index 8fe7ae6b4..06d0d2c2a 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,12 @@ Scan the following QR code with your device to download the latest version of th Or, follow this link: [http://oran.ge/designtoolbox](http://oran.ge/designtoolbox) -The Design Toolbox app allows you to test OUDS components in several themes in light or dark mode. +The Design Toolbox app allows you to test OUDS components in several themes in Light or Dark mode. - +
Design Toolbox sample using Orange themeDesign Toolbox sample using Sosh theme in dark modeDesign Toolbox sample using Sosh theme in Dark mode
diff --git a/build.gradle.kts b/build.gradle.kts index b55ff7429..e2685a39b 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -35,6 +35,7 @@ dependencies { dokka(project(":theme-contract")) dokka(project(":theme-orange")) dokka(project(":theme-sosh")) + dokka(project(":theme-wireframe")) } checkNotice { diff --git a/core/Module.mustache b/core/Module.mustache index fb953de1b..32764b511 100644 --- a/core/Module.mustache +++ b/core/Module.mustache @@ -1,20 +1,258 @@ # Module core -Contains the main elements of the OUDS Android library. +The **OUDS Core** module provides the essential implementation of OUDS Android library. It acts as a semantic wrapper around Material Design 3, ensuring that all UI +elements strictly adhere to the brand's visual guidelines without requiring manual configuration from the developer. -#### Component versions +This module is divided into two main pillars: + +1. The **OUDS Theme**: Foundation of colors, typography, sizes, etc. +2. The **OUDS Components**: Ready-to-use UI elements (Buttons, Chips, Navigation Bar, etc.). + +## OUDS Theme + +**Package:** `com.orange.ouds.core.theme` + +The `OudsTheme` composable is the entry point of OUDS Android. It automatically applies the correct color palette (Light or Dark) to the +entire application hierarchy and provides OUDS tokens values. + +### Applying the theme + +Wrap your application's root composable or any specific screen with OudsTheme. It internally handles the switch between Light and Dark modes based on the system +settings. + +```kotlin +import com.orange.ouds.core.theme.OudsTheme + +setContent { + OudsTheme { + // Your app content goes here + } +} +``` + +### Accessing theme attributes + +The module exposes a singleton object `OudsTheme` (similar to `MaterialTheme`) to access design tokens within your composables. This object provides direct +access to all semantic design tokens (colors, typography, borders, etc.) defined in the system, allowing you to build custom UIs that remain consistent with +the global brand style. + +**IMPORTANT: You should always use these semantic values instead of hardcoded values.** + +#### Borders + +Access border width, radius and style tokens via `OudsTheme.borders`. + +```kotlin +Box( + modifier = Modifier.border( + width = OudsTheme.borders.width.medium, + color = OudsTheme.colorScheme.border.default + ) +) +``` + +#### Colors + +Access the semantic color palette via `OudsTheme.colorScheme`. This ensures your UI adapts automatically to Light or Dark mode. + +```kotlin +Text( + text = "Hello World", + color = OudsTheme.colorScheme.content.default, // Semantic color + style = OudsTheme.typography.body.strong.large +) +``` + +#### Elevations + +Access elevation tokens via `OudsTheme.elevations`. These values represent the depth of an element on the z-axis (shadows) and follow Material Design elevation principles. + +```kotlin +Surface( + shadowElevation = OudsTheme.elevations.default +) { + // Content +} +``` + +#### Grids + +Access layout grid definitions (column gaps, margins, min and max widths) based on the window size via `OudsTheme.grids`. + +```kotlin +Column( + modifier = Modifier.padding(horizontal = OudsTheme.grids.margin), +) { + // Content +} +``` + +#### Opacities + +Access alpha transparency levels via `OudsTheme.opacities`. + +```kotlin +Box( + modifier = Modifier.alpha(OudsTheme.opacities.weak) +) +``` + +#### Sizes + +Access standardized fixed dimensions (e.g., for icons, avatars, or touch targets) via `OudsTheme.sizes`. + +```kotlin +Icon( + painter = painterResource(id = R.drawable.ic_heart), + contentDescription = null, + modifier = Modifier.size(OudsTheme.sizes.icon.medium) +) +``` + +#### Spaces + +Access spacing and padding values via `OudsTheme.spaces`. This is essential for maintaining consistent white space between elements. + +```kotlin +Column( + verticalArrangement = Arrangement.spacedBy(OudsTheme.spaces.fixed.medium) +) { + // Content +} +``` + +#### Typography + +Access the brand's typography styles via `OudsTheme.typography`. + +```kotlin +Text( + text = "Headline", + style = OudsTheme.typography.heading.large +) +``` + +### Overriding theme modes + +Sometimes you may need to display a specific part of your screen in a different mode than the rest of the application (e.g., a dark section inside a light +screen). The module provides the `OudsThemeTweak` composable for this purpose. + +It allows you to **invert the current mode** or **force a specific mode** (Light or Dark) for its content. + +```kotlin +// Example: Force a specific section to be in Dark Mode +OudsThemeTweak(tweak = OudsTheme.Tweak.ForceDark) { + Surface { + Text("This text is always in Dark Mode") + } +} + +// Example: Invert the current mode (Light -> Dark, Dark -> Light) +OudsThemeTweak(tweak = OudsTheme.Tweak.Invert) { + // Content with inverted theme +} +``` + +## OUDS Components + +**Package:** `com.orange.ouds.core.component` + +The Core module exposes a set of Jetpack Compose components prefixed with `Ouds` (e.g., `OudsButton`, `OudsNavigationBar`). These components serve as the +building blocks for your application's UI. + +### Implementation strategy + +The library adopts an hybrid approach to component implementation to best serve the design system: + +1. **Direct Wrappers:** When the Material Design 3 specification aligns with OUDS, we wrap the standard Material 3 composables and configure them with +OUDS-specific +default values (tokens for colors, shapes, typography) to ensure brand consistency without reinventing the wheel. +2. **Custom Implementations:** When a specific OUDS component diverges significantly from the standard Material 3 behavior or layout, we provide a full custom +implementation. This ensures that unique design requirements are met pixel-perfectly, rather than forcing a standard component to behave in a way it wasn't +designed for. + +Regardless of the implementation strategy, the API remains consistent and easy to use for the developer. + +### Philosophy + +- **Zero Configuration:** You do not need to pass design parameters like color or shape for standard states. The component knows how to render itself in +Enabled, Disabled, Selected, Hovered or Focused states. +- **Controlled Flexibility:** Components use structured parameters (specific classes or data objects) instead of open composable slots. This ensures that +while you can customize content like text or icons, the structural integrity and visual consistency of the Orange Unified Design System are always preserved. +- **Modifier Support:** Following Jetpack Compose best practices, every OUDS component exposes a modifier parameter. This allows you to easily customize layout +behavior (padding, positioning, semantics) externally without modifying the component's internal logic. + +### Example: Navigation Bar + +The `OudsNavigationBar` manages the bottom navigation. It works in tandem with `OudsNavigationBarItem`. + +```kotlin +import com.orange.ouds.core.component.OudsNavigationBar +import com.orange.ouds.core.component.OudsNavigationBarItem + +@Composable +internal fun OudsNavigationBarSample() { + data class Item(val label: String, val imageVector: ImageVector) + val items = listOf( + Item("Call", Icons.Default.Call), + Item("Email", Icons.Default.Email), + Item("Settings", Icons.Default.Settings) + ) + var selectedItemIndex: Int by rememberSaveable { mutableIntStateOf(0) } + + OudsNavigationBar( + items = items.mapIndexed { index, item -> + OudsNavigationBarItem( + selected = index == selectedItemIndex, + onClick = { selectedItemIndex = index }, + icon = OudsNavigationBarItemIcon(imageVector = item.imageVector), + label = item.label, + // Optional: Add a badge + badge = if (index == 1) OudsNavigationBarItemBadge(contentDescription = "Unread emails", count = "2") else null + ) + } + ) +} +``` + +### Available components and versions -{{#versions}} - -{{/versions}} + {{#versions}} + + + + + {{/versions}}
{{name}}{{value}}
{{name}}{{value}}
+## Best Practices + +1. **Do not mix Material 3 components directly with OUDS components** if an OUDS equivalent exists. Using the native components might result in incorrect colors +or spacing that violates the brand guidelines. +2. **Use `OudsTheme` tokens** for custom layouts. If you need to build a custom card or row, use OudsTheme.colorScheme instead of Color.Black or Color.White to +ensure Dark mode compatibility. +3. **Window Insets:** The library is designed to work edge-to-edge. Components like OudsNavigationBar can be transparent to allow content to blur behind them (if supported), +but they require proper handling of WindowInsets in your layouts. + # Package com.orange.ouds.core.component -Contains all OUDS basic components: OudsButton, OudsLink,... +This package contains the catalog of ready-to-use UI components (like OudsButton, OudsNavigationBar) that implement the design system specifications using +Jetpack Compose. + +# Package com.orange.ouds.core.component.common + +This package holds shared elements that are reused across multiple higher-level OUDS components to ensure consistent behavior and reduce code duplication. + +# Package com.orange.ouds.core.extensions + +This package contains Kotlin extension functions, providing shorthand utilities to streamline development within the OUDS ecosystem. # Package com.orange.ouds.core.theme -Contains the `OudsTheme` composable that can be used in your app to apply a chosen theme. The other files are used to build the theme and don't have to be used -directly but only through the `OudsTheme`. \ No newline at end of file +This package contains the logic for the OudsTheme composable, including the OudsThemeTweak mechanism and the implementation of the theme contract that injects +visual data into the application. + +# Package com.orange.ouds.core.utilities + +This package provides internal helper classes and extensions used across the core module to support component logic and layout management. \ No newline at end of file diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt b/core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt index d7880fe4b..9b5da1ec7 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt @@ -60,7 +60,6 @@ import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider import com.orange.ouds.theme.OudsThemeContract import kotlin.enums.enumEntries - /** * The badge is a small UI element used to highlight status, notifications, or categorization within an interface. * It is often displayed as a label or indicator with a distinct background color and text. @@ -68,7 +67,7 @@ import kotlin.enums.enumEntries * Badges have five statuses depending on the context of the information they represent. * Each status is designed to convey a specific meaning and ensure clarity in communication. * - * This version of the badge renders as a static label without a number. + * This version of the badge renders a static label without a number. * It is used for status indicators (e.g., "New", "Pending", "Success"). * The size remains unchanged despite the increase in the interface size. * @@ -220,7 +219,7 @@ private fun OudsBadge( modifier = modifier.semantics(mergeDescendants = true) { if (text != null) { // The content description for a count badge is applied here instead of the Text composable - // That way it can be overridden by the caller through the semantics method on the modifier + // That way it can be overridden by the caller through the semantics method on the modifier contentDescription = text } }, @@ -353,7 +352,7 @@ const val OudsBadgeMaxCount = 99 /** * An icon in an [OudsBadge]. - * This icon is non-clickable. + * This icon is not clickable. */ open class OudsBadgeIcon internal constructor( graphicsObjectProvider: @Composable (OudsBadgeIcon) -> Any, diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsButton.kt b/core/src/main/java/com/orange/ouds/core/component/OudsButton.kt index 7e44f4d28..7b8a94123 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsButton.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsButton.kt @@ -81,25 +81,25 @@ import com.orange.ouds.theme.tokens.components.OudsButtonMonoTokens /** * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user. * - * This version of the button uses the *text only* layout which is the most used layout. + * This version of the button uses the *text only* layout, which is the most common layout. * Other layouts are available for this component: *text + icon* and *icon only*. * - * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. + * Note that if it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens]. * - * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property of an [OudsThemeSettings] when calling - * the [com.orange.ouds.core.theme.OudsTheme] method. + * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property in the settings of the theme provided + * when calling the [com.orange.ouds.core.theme.OudsTheme] method. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button) * * > Design version: 3.2.0 * - * @param label Label displayed in the button which describes the button action. Use action verbs or phrases to tell the user what will happen next. + * @param label Label displayed in the button describing the button action. Use action verbs or phrases to tell the user what will happen next. * @param onClick Callback invoked when the button is clicked. * @param modifier [Modifier] applied to the button. * @param enabled Controls the enabled state of the button when there is no [loader]. * When `false`, this button will not be clickable. - * Has no effect when [loader] is not null. + * Has no effect if [loader] is provided. * @param loader An optional loading progress indicator displayed in the button to indicate an ongoing operation. * @param appearance Appearance of the button among [OudsButtonAppearance] values. * A button with [OudsButtonAppearance.Negative] is not allowed as a direct or indirect child of an [OudsColoredBox] and will throw an [IllegalStateException]. @@ -135,14 +135,14 @@ fun OudsButton( /** * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user. * - * This version of the button uses the *icon only* layout which is typically used in business or back-office interfaces, it is rarely used alone (usually part of a group of elements). + * This version of the button uses the *icon only* layout, which is typically used in business or back-office interfaces. It is rarely used alone (usually part of a group of elements). * Other layouts are available for this component: *text only* and *text + icon*. * - * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. + * Note that if it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens]. * - * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property of an [OudsThemeSettings] when calling - * the [com.orange.ouds.core.theme.OudsTheme] method. + * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property in the settings of the theme provided + * when calling the [com.orange.ouds.core.theme.OudsTheme] method. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button) * @@ -153,7 +153,7 @@ fun OudsButton( * @param modifier [Modifier] applied to the button. * @param enabled Controls the enabled state of the button when there is no [loader]. * When `false`, this button will not be clickable. - * Has no effect when [loader] is not null. + * Has no effect if [loader] is provided. * @param loader An optional loading progress indicator displayed in the button to indicate an ongoing operation. * @param appearance Appearance of the button among [OudsButtonAppearance] values. * A button with [OudsButtonAppearance.Negative] is not allowed as a direct or indirect child of an [OudsColoredBox] and will throw an [IllegalStateException]. @@ -189,27 +189,27 @@ fun OudsButton( /** * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user. * - * This version of the button uses the *text + icon* layout which should remain specific to some clearly identified contexts (e.g. the use of an icon with a + * This version of the button uses the *text + icon* layout, which should remain specific to clearly identified contexts (e.g., the use of an icon with a * "Play" button is standard in the context of TV or video streaming). * Other layouts are available for this component: *text only* and *icon only*. * - * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. + * Note that if it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens]. * - * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property of an [OudsThemeSettings] when calling - * the [com.orange.ouds.core.theme.OudsTheme] method. + * Rounded corners can be enabled or disabled using the [OudsThemeSettings.roundedCornerButtons] property in the settings of the theme provided + * when calling the [com.orange.ouds.core.theme.OudsTheme] method. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button) * * > Design version: 3.2.0 * * @param icon Icon displayed in the button. Use an icon to add additional affordance where the icon has a clear and well-established meaning. - * @param label Label displayed in the button which describes the button action. Use action verbs or phrases to tell the user what will happen next. + * @param label Label displayed in the button describing the button action. Use action verbs or phrases to tell the user what will happen next. * @param onClick Callback invoked when the button is clicked. * @param modifier [Modifier] applied to the button. * @param enabled Controls the enabled state of the button when there is no [loader]. * When `false`, this button will not be clickable. - * Has no effect when [loader] is not null. + * Has no effect if [loader] is provided. * @param loader An optional loading progress indicator displayed in the button to indicate an ongoing operation. * @param appearance Appearance of the button among [OudsButtonAppearance] values. * A button with [OudsButtonAppearance.Negative] is not allowed as a direct or indirect child of an [OudsColoredBox] and will throw an [IllegalStateException]. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsCheckbox.kt b/core/src/main/java/com/orange/ouds/core/component/OudsCheckbox.kt index 4c3c75796..def7e76ed 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsCheckbox.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsCheckbox.kt @@ -73,16 +73,16 @@ import com.orange.ouds.theme.OudsThemeContract * @see [OudsTriStateCheckbox] If you require support for an indeterminate state. * @see [OudsCheckboxItem] If you want to use a checkbox with an associated label and other optional elements. * - * @param checked Controls checked state of the checkbox. + * @param checked Controls the checked state of the checkbox. * @param onCheckedChange Callback invoked on checkbox click. If `null`, then this is passive and relies entirely on a higher-level component to control - * the checked state. + * the checked state. * @param modifier [Modifier] applied to the layout of the checkbox. * @param enabled Controls the enabled state of the checkbox. When `false`, this checkbox will not be clickable. - * @param readOnly Controls the read only state of the checkbox. When `true`, this checkbox is displayed in a specific state (checked or unchecked) - * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the checkbox should appear in error state, `null` otherwise. + * @param readOnly Controls the read-only state of the checkbox. When `true`, this checkbox is displayed in a specific state (checked or unchecked) + * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the checkbox should appear in an error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this checkbox. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsCheckboxSample */ @@ -116,7 +116,7 @@ fun OudsCheckbox( * all child checkboxes are checked. If a parent checkbox is unchecked, all child checkboxes are unchecked. If some, but not all, child checkboxes are checked, * the parent checkbox becomes an indeterminate checkbox. * - * The **indeterminate standalone checkbox variant** allows to manage a checkbox with an indeterminate state that can be used when the checkbox input is nested + * The **indeterminate standalone checkbox variant** allows managing a checkbox with an indeterminate state that can be used when the checkbox input is nested * within another component and an alternative label is provided. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox) @@ -126,16 +126,16 @@ fun OudsCheckbox( * @see [OudsCheckbox] If you need a simple component that represents [Boolean] state. * @see [OudsTriStateCheckboxItem] If you want to use an indeterminate checkbox with an associated label and other optional elements. * - * @param state Controls whether TriStateCheckbox is checked, unchecked or in indeterminate state. - * @param onClick Callback invoked when checkbox is being clicked, therefore the change of [ToggleableState] state is requested. If null, then this is passive - * and relies entirely on a higher-level component to control the state. + * @param state Controls whether the TriStateCheckbox is checked, unchecked or in an indeterminate state. + * @param onClick Callback invoked when the checkbox is clicked, therefore the change of [ToggleableState] state is requested. If `null`, then this is passive + * and relies entirely on a higher-level component to control the state. * @param modifier [Modifier] applied to the layout of the checkbox. * @param enabled Controls the enabled state of the checkbox. When `false`, this checkbox will not be clickable. - * @param readOnly Controls the read only state of the checkbox. When `true`, this checkbox is displayed in a specific state (checked, unchecked or indeterminate) - * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the checkbox should appear in error state, `null` otherwise. + * @param readOnly Controls the read-only state of the checkbox. When `true`, this checkbox is displayed in a specific state (checked, unchecked or indeterminate) + * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the checkbox should appear in an error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this checkbox. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsTriStateCheckboxSample */ @@ -369,4 +369,4 @@ private val previewParameterValues: List } internal class OudsCheckboxHighContrastModePreviewParameterProvider : - BasicPreviewParameterProvider(ToggleableState.On, ToggleableState.Indeterminate) \ No newline at end of file + BasicPreviewParameterProvider(ToggleableState.On, ToggleableState.Indeterminate) diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsCheckboxItem.kt b/core/src/main/java/com/orange/ouds/core/component/OudsCheckboxItem.kt index 9cd229281..4dcb82b9b 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsCheckboxItem.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsCheckboxItem.kt @@ -15,12 +15,10 @@ package com.orange.ouds.core.component import androidx.compose.foundation.interaction.Interaction import androidx.compose.foundation.interaction.MutableInteractionSource import androidx.compose.foundation.isSystemInDarkTheme -import androidx.compose.foundation.layout.padding import androidx.compose.foundation.selection.triStateToggleable import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Call import androidx.compose.runtime.Composable -import androidx.compose.runtime.CompositionLocalProvider import androidx.compose.runtime.getValue import androidx.compose.runtime.remember import androidx.compose.ui.Modifier @@ -32,7 +30,6 @@ import androidx.compose.ui.tooling.preview.PreviewLightDark import androidx.compose.ui.tooling.preview.PreviewParameter import com.orange.ouds.core.component.common.OudsError import com.orange.ouds.core.extensions.collectInteractionStateAsState -import com.orange.ouds.core.theme.OudsTheme import com.orange.ouds.core.utilities.LoremIpsumText import com.orange.ouds.core.utilities.OudsPreview import com.orange.ouds.core.utilities.PreviewEnumEntries @@ -54,23 +51,24 @@ import com.orange.ouds.theme.OudsThemeContract * @see [OudsTriStateCheckboxItem] If you need an indeterminate state for the item's checkbox. * @see [OudsCheckbox] If you want to use a standalone checkbox without any other element. * - * @param checked Controls checked state of the item's checkbox. + * @param checked Controls the checked state of the item's checkbox. * @param label The main label of the checkbox item. * @param onCheckedChange Callback invoked on checkbox item click. If `null`, then this is passive and relies entirely on a higher-level component to control - * the checked state. + * the checked state. * @param modifier [Modifier] applied to the layout of the checkbox item. * @param description Optional text displayed below the label. * @param icon Optional icon displayed in the item. By default, it has a trailing position. If [reversed] is set to `true`, it is displayed as a leading element. * @param edgeToEdge Controls the horizontal layout of the item. When `true`, the item is designed to span the full width of the screen or container. When `false`, - * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. * @param divider Controls the display of a divider at the bottom of the checkbox item. + * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. + * @param divider Controls the display of a divider at the bottom of the checkbox item. * @param reversed When `false`, the checkbox has a leading position and the optional [icon] has a trailing position. Otherwise, it is reversed. * @param enabled Controls the enabled state of the checkbox item. When `false`, the checkbox, the texts and the optional icon are disabled, and the item - * will not be clickable. - * @param readOnly Controls the read only state of the checkbox item. When `true` the item's checkbox is disabled but the texts and the icon remain in - * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox item will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the checkbox item should appear in error state, `null` otherwise. + * will not be clickable. + * @param readOnly Controls the read-only state of the checkbox item. When `true` the item's checkbox is disabled but the texts and the icon remain in + * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox item will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the checkbox item should appear in error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for the item's checkbox. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsCheckboxItemSample */ @@ -131,22 +129,22 @@ fun OudsCheckboxItem( * * @param state Controls whether item's TriStateCheckbox is checked, unchecked or in indeterminate state. * @param label The main label of the checkbox item. - * @param onClick Callback invoked when checkbox item is being clicked, therefore the change of checkbox [ToggleableState] state is requested. If null, then - * this is passive and relies entirely on a higher-level component to control the state. + * @param onClick Callback invoked when checkbox item is being clicked, therefore the change of checkbox [ToggleableState] state is requested. If `null`, then + * this is passive and relies entirely on a higher-level component to control the state. * @param modifier [Modifier] applied to the layout of the checkbox item. * @param description Optional text displayed below the label. * @param icon Optional icon displayed in the item. By default, it has a trailing position. If [reversed] is set to `true`, it is displayed as a leading element. * @param edgeToEdge Controls the horizontal layout of the item. When `true`, the item is designed to span the full width of the screen or container. When `false`, - * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. + * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. * @param divider Controls the display of a divider at the bottom of the checkbox item. * @param reversed When `false`, the checkbox has a leading position and the optional [icon] has a trailing position. Otherwise, it is reversed. * @param enabled Controls the enabled state of the checkbox item. When `false`, the checkbox, the texts and the optional icon are disabled, and the item - * will not be clickable. - * @param readOnly Controls the read only state of the checkbox item. When `true` the item's checkbox is disabled but the texts and the icon remain in - * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox item will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the checkbox item should appear in error state, `null` otherwise. + * will not be clickable. + * @param readOnly Controls the read-only state of the checkbox item. When `true` the item's checkbox is disabled but the texts and the icon remain in + * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the checkbox item will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the checkbox item should appear in error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for the item's checkbox. Note that - * if `null` is provided, interactions will still happen internally. + * if `null` is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsTriStateCheckboxItemSample */ diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsChip.kt b/core/src/main/java/com/orange/ouds/core/component/OudsChip.kt index a948a57b3..e425cef40 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsChip.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsChip.kt @@ -294,7 +294,7 @@ private fun contentPadding(label: String?, icon: OudsChipIcon?, iconPosition: Ou /** * An icon in an [OudsFilterChip] or an [OudsSuggestionChip]. - * This icon is non-clickable. + * This icon is not clickable. */ class OudsChipIcon private constructor( graphicsObject: Any, @@ -310,7 +310,7 @@ class OudsChipIcon private constructor( * Creates an instance of [OudsChipIcon]. * * @param painter Painter of the icon. - * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains label. + * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains a label. */ constructor(painter: Painter, contentDescription: String) : this(painter as Any, contentDescription) @@ -318,7 +318,7 @@ class OudsChipIcon private constructor( * Creates an instance of [OudsChipIcon]. * * @param imageVector Image vector of the icon. - * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains label. + * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains a label. */ constructor(imageVector: ImageVector, contentDescription: String) : this(imageVector as Any, contentDescription) @@ -326,7 +326,7 @@ class OudsChipIcon private constructor( * Creates an instance of [OudsChipIcon]. * * @param bitmap Image bitmap of the icon. - * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains label. + * @param contentDescription The content description associated with this [OudsChipIcon]. This value is ignored if the chip also contains a label. */ constructor(bitmap: ImageBitmap, contentDescription: String) : this(bitmap as Any, contentDescription) diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsCircularProgressIndicator.kt b/core/src/main/java/com/orange/ouds/core/component/OudsCircularProgressIndicator.kt index 44225887c..6b4d50d82 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsCircularProgressIndicator.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsCircularProgressIndicator.kt @@ -25,7 +25,7 @@ import com.orange.ouds.core.theme.OudsTheme import com.orange.ouds.core.theme.value /** - * Temporary circular progress indicator component used in several public components. + * A temporary circular progress indicator component used internally by several public components. */ @Composable internal fun OudsCircularProgressIndicator(color: Color, progress: Float?, modifier: Modifier = Modifier, scale: Float = 1.0f) { diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsColoredBox.kt b/core/src/main/java/com/orange/ouds/core/component/OudsColoredBox.kt index c2e9068d5..dd7dfea10 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsColoredBox.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsColoredBox.kt @@ -42,13 +42,13 @@ import com.orange.ouds.theme.OudsThemeContract import com.orange.ouds.theme.tokens.OudsColorKeyToken /** - * A colored box is a [Box] where content color is automatically adjusted to maximize the contrast with the chosen background [color]. + * A colored box is a [Box] where the content color is automatically adjusted to maximize the contrast with the chosen background [color]. * - * Moreover, the colors of several OUDS Android components (for instance [OudsButton] or [OudsLink]) are also automatically adjusted. - * Some tokens associated with these specific colors can be customized and are grouped into `Mono` tokens classes (for instance [com.orange.ouds.theme.tokens.components.OudsButtonMonoTokens]). + * Additionally, the colors of several OUDS Android components (such as [OudsButton] or [OudsLink]) are also automatically adjusted. + * Some tokens associated with these specific colors can be customized and are grouped into `Mono` token classes (e.g., [com.orange.ouds.theme.tokens.components.OudsButtonMonoTokens]). * * @param color The background color of the colored box. - * @param modifier [Modifier] to be applied to the layout corresponding to the colored box. + * @param modifier [Modifier] to be applied to the colored box. * @param contentAlignment The default [Alignment] inside the colored box. * @param propagateMinConstraints Whether the incoming min constraints should be passed to content. * @param content The content of this colored box. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsControlItem.kt b/core/src/main/java/com/orange/ouds/core/component/OudsControlItem.kt index dde30a816..64695da50 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsControlItem.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsControlItem.kt @@ -53,7 +53,7 @@ import com.orange.ouds.core.utilities.getPreviewEnumEntry import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider /** - * Control item composable helps to factorize common layout elements between [OudsCheckboxItem], [OudsTriStateCheckboxItem], [OudsRadioButtonItem] + * The control item composable helps factorize common layout elements shared by [OudsCheckboxItem], [OudsTriStateCheckboxItem], [OudsRadioButtonItem], * and [OudsSwitchItem]. */ @Composable @@ -183,7 +183,7 @@ internal enum class OudsControlItemIndicatorPosition { /** * An icon in a control item like [OudsCheckboxItem] or [OudsRadioButtonItem]. - * It is non-clickable and no content description is needed because a control item label is always present. + * It is not clickable and requires no content description because a control item label is always present. */ class OudsControlItemIcon private constructor( graphicsObject: Any, diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsDivider.kt b/core/src/main/java/com/orange/ouds/core/component/OudsDivider.kt index 605868642..ec1d16ac1 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsDivider.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsDivider.kt @@ -32,10 +32,10 @@ import com.orange.ouds.foundation.utilities.EnumPreviewParameterProvider import com.orange.ouds.theme.OudsThemeContract /** - * Dividers are used to visually structure an interface by clearly separating content sections. It helps to improve readability and content organization + * Dividers are used to visually structure an interface by clearly separating content sections. They help to improve readability and content organization * without introducing a strong hierarchy like a heading or a container would. * - * The **horizontal divider** renders an horizontal line to separate stacked vertical sections. + * The **horizontal divider** renders a horizontal line to separate stacked vertical sections. * * The color of the divider can be specified using the [OudsDividerColor] enum, and the thickness is defined by the current theme's divider border width. * Note that a divider border width token set to 0 dp will produce a single pixel divider regardless of screen density. @@ -58,10 +58,10 @@ fun OudsHorizontalDivider( } /** - * Dividers are used to visually structure an interface by clearly separating content sections. It helps to improve readability and content organization + * Dividers are used to visually structure an interface by clearly separating content sections. They help to improve readability and content organization * without introducing a strong hierarchy like a heading or a container would. * - * The **vertical divider** renders an vertical line to separate horizontally aligned elements. + * The **vertical divider** renders a vertical line to separate horizontally aligned elements. * * The color of the divider can be specified using the [OudsDividerColor] enum, and the thickness is defined by the current theme's divider border width. * Note that a divider border width token set to 0 dp will produce a single pixel divider regardless of screen density. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsFilterChip.kt b/core/src/main/java/com/orange/ouds/core/component/OudsFilterChip.kt index 4e6760c8c..d050e9829 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsFilterChip.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsFilterChip.kt @@ -45,12 +45,12 @@ import com.orange.ouds.theme.OudsThemeContract * * @param selected Whether this chip is selected or not. * @param onClick Called when this chip is clicked. - * @param label Text label for this chip. + * @param label Text label displayed in the chip. * @param modifier The [Modifier] to be applied to this chip. * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. @@ -100,7 +100,7 @@ fun OudsFilterChip( * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. @@ -145,13 +145,13 @@ fun OudsFilterChip( * * @param selected Whether this chip is selected or not. * @param onClick Called when this chip is clicked. - * @param label Text label for this chip. + * @param label Text label displayed in the chip. * @param icon Icon displayed in the chip. Use an icon to add additional affordance where the icon has a clear and well-established meaning. * @param modifier The [Modifier] to be applied to this chip. * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsInputTag.kt b/core/src/main/java/com/orange/ouds/core/component/OudsInputTag.kt index c62e9e29d..6066e84af 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsInputTag.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsInputTag.kt @@ -56,20 +56,20 @@ import com.orange.ouds.theme.OudsThemeContract /** * An input tag is a component that allows users 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. + * enter, comma, or tab), each value is transformed into a tag. * Input tags are often used for adding labels, categories, or participants. They typically support editing, removing, and validating individual tags. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/7565ce-tag/t/697817ca4d) * * > Design version: 1.4.0 * - * @param label The label displayed in the input tag. + * @param label The text label displayed inside the input tag. * @param onClick Called when the input tag is clicked. * @param modifier [Modifier] applied to the input tag. * @param enabled Controls the enabled state of this input tag. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this input tag. You can use this to change the input tag's appearance or * preview the input tag in different states. Note that if `null` is provided, interactions will still * happen internally. @@ -167,20 +167,20 @@ fun OudsInputTag( /** * An input tag is a component that allows users 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. + * enter, comma, or tab), each value is transformed into a tag. * Input tags are often used for adding labels, categories, or participants. They typically support editing, removing, and validating individual tags. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com) * * > Design version: 1.4.0 * - * @param label The label displayed in the input tag. + * @param label The text label displayed inside the input tag. * @param onClick Called when the input tag is clicked. * @param modifier [Modifier] applied to the input tag. * @param enabled Controls the enabled state of this input tag. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this input tag. You can use this to change the input tag's appearance or * preview the input tag in different states. Note that if `null` is provided, interactions will still * happen internally. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsLink.kt b/core/src/main/java/com/orange/ouds/core/component/OudsLink.kt index 84a2e718b..8812c7805 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsLink.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsLink.kt @@ -68,7 +68,7 @@ import com.orange.ouds.theme.tokens.components.OudsLinkMonoTokens /** * Links are interactive elements that allow users to navigate to a new screen, website, or a specific section within the current screen. * - * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. + * Note that if it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with this variant can be customized by overriding [OudsLinkMonoTokens]. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/31c33b-link) @@ -105,7 +105,7 @@ fun OudsLink( /** * Links are interactive elements that allow users to navigate to a new screen, website, or a specific section within the current screen. * - * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. + * Note that if it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with this variant can be customized by overriding [OudsLinkMonoTokens]. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/31c33b-link) @@ -144,7 +144,7 @@ fun OudsLink( /** * An OUDS link which displays an [arrow] before ([OudsLinkArrow.Back]) or after ([OudsLinkArrow.Next]) a label. * - * In the case it is used in an [OudsColoredBox], its monochrome variant is automatically displayed. + * If it is used in an [OudsColoredBox], its monochrome variant is automatically displayed. * The tokens associated with this variant can be customized by overriding [OudsLinkMonoTokens]. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/31c33b-link) @@ -375,7 +375,7 @@ enum class OudsLinkSize { /** * A small size for a link, particularly useful in an information-dense interface or in a component requiring the use - * of small elements ("In-line alert" component, for example). + * of small elements ("Inline alert" component, for example). */ Small } @@ -385,12 +385,12 @@ enum class OudsLinkSize { */ enum class OudsLinkArrow { /** - * Used for "backward" navigation. This arrow is positioned before the label, it features a "chevron left" icon, which is not customizable. + * Used for "backward" navigation. This arrow is positioned before the label and features a "chevron left" icon, which is not customizable. */ Back, /** - * Used in a standard navigation context. This arrow is positioned after the label, it features a "chevron right" icon, which is not customizable. + * Used in a standard navigation context. This arrow is positioned after the label and features a "chevron right" icon, which is not customizable. */ Next } diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsRadioButton.kt b/core/src/main/java/com/orange/ouds/core/component/OudsRadioButton.kt index c870cc44c..93fde7142 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsRadioButton.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsRadioButton.kt @@ -72,14 +72,14 @@ import com.orange.ouds.theme.OudsThemeContract * * @param selected Controls the selected state of the radio button. * @param onClick Callback invoked on radio button click. If `null`, then this radio button will not be interactable, unless something else handles its - * input events and updates its state. + * input events and updates its state. * @param modifier [Modifier] applied to the layout of the radio button. * @param enabled Controls the enabled state of the radio button. When `false`, this radio button will not be clickable. - * @param readOnly Controls the read only state of the radio button. When `true`, this radio button is displayed in a specific state (selected or unselected) - * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the radio button will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the radio button should appear in error state, `null` otherwise. + * @param readOnly Controls the read-only state of the radio button. When `true`, this radio button is displayed in a specific state (selected or unselected) + * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the radio button will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the radio button should appear in an error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this radio button. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsRadioButtonSample */ diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsRadioButtonItem.kt b/core/src/main/java/com/orange/ouds/core/component/OudsRadioButtonItem.kt index 2703b9913..2f2aa0fd6 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsRadioButtonItem.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsRadioButtonItem.kt @@ -53,26 +53,26 @@ import com.orange.ouds.theme.OudsThemeContract * * @see [OudsRadioButton] If you want to use a standalone radio button. * - * @param selected Controls selected state of the radio button. + * @param selected Controls the selected state of the radio button. * @param label The main label of the radio button item. * @param onClick Callback invoked on radio button click. If `null`, then this radio button will not be interactable, unless something else handles its - * input events and updates its state. + * input events and updates its state. * @param modifier [Modifier] applied to the layout of the radio button item. * @param extraLabel Optional strong accompanying label for the main label. It is displayed between the [label] and the [description]. * @param description Optional text displayed below the [label] and the [extraLabel]. * @param icon Optional icon displayed in the item. By default, it has a trailing position. If [reversed] is set to `true`, it is displayed as a leading element. * @param edgeToEdge Controls the horizontal layout of the item. When `true`, the item is designed to span the full width of the screen or container. When `false`, - * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. + * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. * @param divider Controls the display of a divider at the bottom of the radio button item. * @param outlined When set to `true`, the radio button item, if selected, is outlined to stand out and draw the user's attention. * @param reversed When `false`, the radio button has a leading position and the optional [icon] has a trailing position. Otherwise, it is reversed. * @param enabled Controls the enabled state of the radio button item. When `false`, the radio button, the texts and the optional icon are disabled, and the item - * will not be clickable. - * @param readOnly Controls the read only state of the radio button item. When `true` the item's radio button is disabled but the texts and the icon remain in - * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the radio button item will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the radio button item should appear in error state, `null` otherwise. + * will not be clickable. + * @param readOnly Controls the read-only state of the radio button item. When `true` the item's radio button is disabled but the texts and the icon remain in + * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the radio button item will be displayed in disabled state. + * @param error Optional [OudsError] to indicate that the radio button item should appear in error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for the item's radio button. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsRadioButtonItemSample */ @@ -291,4 +291,3 @@ internal typealias OudsRadioButtonItemHighContrastModePreviewParameter = OudsCon internal class OudsRadioButtonItemHighContrastModePreviewParameterProvider : OudsControlItemHighContrastModePreviewParameterProvider(listOf(false, true)) - diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsSuggestionChip.kt b/core/src/main/java/com/orange/ouds/core/component/OudsSuggestionChip.kt index 1c57e191c..44e95dec4 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsSuggestionChip.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsSuggestionChip.kt @@ -45,12 +45,12 @@ import com.orange.ouds.theme.OudsThemeContract * > Design version: 1.3.0 * * @param onClick Called when this chip is clicked. - * @param label Text label for this chip. + * @param label Text label displayed in the chip. * @param modifier The [Modifier] to be applied to this chip. * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. @@ -98,7 +98,7 @@ fun OudsSuggestionChip( * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. @@ -141,13 +141,13 @@ fun OudsSuggestionChip( * > Design version: 1.3.0 * * @param onClick Called when this chip is clicked. - * @param label Text label for this chip. + * @param label Text label displayed in the chip. * @param icon Icon displayed in the chip. Use an icon to add additional affordance where the icon has a clear and well-established meaning. * @param modifier The [Modifier] to be applied to this chip. * @param enabled Controls the enabled state of this chip. When `false`, this component will not * respond to user input, and it will appear visually disabled and disabled to accessibility * services. - * @param interactionSource an optional hoisted [MutableInteractionSource] for observing and + * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and * emitting [Interaction]s for this chip. You can use this to change the chip's appearance or * preview the chip in different states. Note that if `null` is provided, interactions will still * happen internally. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsSwitch.kt b/core/src/main/java/com/orange/ouds/core/component/OudsSwitch.kt index 8f40e0ee5..6b069bd08 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsSwitch.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsSwitch.kt @@ -61,7 +61,7 @@ import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider import com.orange.ouds.theme.OudsThemeContract /** - * Switches allow the user to toggle between two states, typically "on" and "off". It is represented as a slider that changes its position or color to indicate + * Switches allow the user to toggle between two states, typically "on" and "off". They are represented as sliders that change their position or color to indicate * the current state. Switches are used to enable or disable features, options, or settings in an intuitive and visual manner. * * The **standalone switch variant** can be used when the switch selector control is nested within another component and an alternative label is provided. @@ -72,12 +72,12 @@ import com.orange.ouds.theme.OudsThemeContract * * @see [OudsSwitchItem] If you want to use a switch with an associated label and other optional elements. * - * @param checked Controls checked state of the switch. + * @param checked Controls the checked state of the switch. * @param onCheckedChange Callback invoked on switch click. If `null`, then this is passive and relies entirely on a higher-level component to control * the checked state. * @param modifier [Modifier] applied to the layout of the switch. * @param enabled Controls the enabled state of the switch. When `false`, this switch will not be clickable. - * @param readOnly Controls the read only state of the switch. When `true`, this switch is displayed in a specific state (checked or unchecked) + * @param readOnly Controls the read-only state of the switch. When `true`, this switch is displayed in a specific state (checked or unchecked) * but the user cannot modify it. Note that if it is set to `true` and [enabled] is set to `false`, the switch will be displayed in disabled state. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this switch. Note that if `null` * is provided, interactions will still happen internally. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsSwitchItem.kt b/core/src/main/java/com/orange/ouds/core/component/OudsSwitchItem.kt index 6ee586237..f6f82c026 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsSwitchItem.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsSwitchItem.kt @@ -15,7 +15,6 @@ package com.orange.ouds.core.component import androidx.compose.foundation.interaction.Interaction import androidx.compose.foundation.interaction.MutableInteractionSource import androidx.compose.foundation.isSystemInDarkTheme -import androidx.compose.foundation.layout.padding import androidx.compose.foundation.selection.toggleable import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Call @@ -30,7 +29,6 @@ import androidx.compose.ui.tooling.preview.PreviewLightDark import androidx.compose.ui.tooling.preview.PreviewParameter import com.orange.ouds.core.component.common.OudsError import com.orange.ouds.core.extensions.collectInteractionStateAsState -import com.orange.ouds.core.theme.OudsTheme import com.orange.ouds.core.utilities.LoremIpsumText import com.orange.ouds.core.utilities.OudsPreview import com.orange.ouds.core.utilities.PreviewEnumEntries @@ -38,14 +36,14 @@ import com.orange.ouds.core.utilities.getPreviewTheme import com.orange.ouds.theme.OudsThemeContract /** - * Switches allow the user to toggle between two states, typically "on" and "off". It is represented as a slider that changes its position or color to indicate + * Switches allow the user to toggle between two states, typically "on" and "off". They are represented as sliders that change their position or color to indicate * the current state. Switches are used to enable or disable features, options, or settings in an intuitive and visual manner. * * The **switch item variant** can function as a simple input with a label, or it can be combined with optional elements such as description, a divider, * or an icon, allowing it to suit various use cases. - * It can be used in a list as a list item or as a single element to validate general conditions for example. + * It can be used in a list as a list item or as a single element to validate general conditions, for example. * - * The OUDS switch item layout contains an [OudsSwitch]. By clicking on the switch item, the user changes the selected state of its switch. + * The OUDS switch item layout contains an [OudsSwitch]. By clicking the switch item, the user changes the checked state of its switch. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/18acc0-switch) * @@ -53,24 +51,24 @@ import com.orange.ouds.theme.OudsThemeContract * * @see [OudsSwitch] If you want to use a standalone switch. * - * @param checked Controls checked state of the item's switch. + * @param checked Controls the checked state of the item's switch. * @param label The main label of the switch item. * @param onCheckedChange Callback invoked on switch item click. If `null`, then this is passive and relies entirely on a higher-level component to control - * the checked state. + * the checked state. * @param modifier [Modifier] applied to the layout of the switch item. * @param description Optional text displayed below the label. * @param icon Optional icon displayed in the item. By default, it has a leading position. If [reversed] is set to `true`, it is displayed as a trailing element. * @param edgeToEdge Controls the horizontal layout of the item. When `true`, the item is designed to span the full width of the screen or container. When `false`, - * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. + * it is adapted for use within constrained layouts or containers with their own padding. Defaults to `true`. * @param divider Controls the display of a divider at the bottom of the switch item. * @param reversed When `false`, the switch has a trailing position and the optional [icon] has a leading position. Otherwise, it is reversed. * @param enabled Controls the enabled state of the switch item. When `false`, the switch, the texts and the optional icon are disabled, and the item - * will not be clickable. - * @param readOnly Controls the read only state of the switch item. When `true` the item's switch is disabled but the texts and the icon remain in - * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the switch item will be displayed in disabled state. - * @param error Optional [OudsError] to provide in the case of the switch item should appear in error state, `null` otherwise. + * will not be clickable. + * @param readOnly Controls the read-only state of the switch item. When `true`, the item's switch is disabled but the texts and the icon remain in the + * enabled color. Note that if it is set to `true` and [enabled] is set to `false`, the switch item will be displayed in the disabled state. + * @param error Optional [OudsError] to provide if the switch item should appear in an error state, `null` otherwise. * @param interactionSource Optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for the item's switch. Note that if `null` - * is provided, interactions will still happen internally. + * is provided, interactions will still happen internally. * * @sample com.orange.ouds.core.component.samples.OudsSwitchItemSample */ diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsTag.kt b/core/src/main/java/com/orange/ouds/core/component/OudsTag.kt index 2156b1a0c..6af0146d5 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsTag.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsTag.kt @@ -66,7 +66,7 @@ import kotlin.enums.enumEntries * A tag is a small element that shows short info like a label, keyword, or category. * It helps users quickly find, group, or understand content. * - * Tags have seven status depending on the context of the information they represent. Each state is designed + * Tags have six statuses depending on the context of the information they represent. Each status is designed * to convey a specific meaning and ensure clarity in communication. * * Four different layouts are supported: @@ -76,7 +76,7 @@ import kotlin.enums.enumEntries * Used to show status, presence, or activity next to the label. * - Text and icon: when [status] icon is not `null`, the tag includes an icon before the text. * Used to visually reinforce the meaning of the tag, such as status, type, or action. - * - Text and loader: when [loader] is `true`, the tag combines a loading spinner (or progress indicator) with text. + * - Text and loader: when [loader] is not `null`, the tag combines a loading spinner (or progress indicator) with text. * Used to indicate that a process or action related to the tag is in progress. * * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/7565ce-tag) @@ -86,11 +86,11 @@ import kotlin.enums.enumEntries * @param label The label displayed in the tag. * @param modifier [Modifier] applied to the tag. * @param enabled Controls the enabled appearance of the tag. - * A tag with loading spinner cannot be disabled. This will throw an [IllegalStateException]. - * @param appearance Appearance of the tag among [OudsTagAppearance] values. Combined with the [status] of the tag, the appearance determines tag's background + * A tag with a loading spinner cannot be disabled. This will throw an [IllegalStateException]. + * @param appearance Appearance of the tag among [OudsTagAppearance] values. Combined with the [status] of the tag, the appearance determines the tag's background * and content colors. * @param status The status of the tag. Its background color and its content color are based on this status combined with the [appearance] of the tag. - * There are two types of status: + * There are two types of statuses: * - Non-functional statuses ([OudsTagStatus.Neutral] or [OudsTagStatus.Accent]) used to display categories, default states, or to draw attention without * carrying a specific functional meaning (unlike functional tags such as success, info, etc.). * Using a non-functional status, you can provide a custom icon related to the tag’s context to enhance recognition by providing an [OudsTagIcon.Custom] @@ -98,10 +98,10 @@ import kotlin.enums.enumEntries * - Functional statuses communicate specific information or system feedback: [OudsTagStatus.Positive], [OudsTagStatus.Warning], [OudsTagStatus.Negative], * [OudsTagStatus.Info]. * Each functional status has its dedicated functional icon that matches the meaning of the tag. This icon will appear by providing [OudsTagIcon.Default] - * as icon value of the status. + * as the icon of the status. * @param roundedCorners Controls the shape of the tag. * When `true`, the tag has rounded corners, providing a softer and more approachable look, suitable for most modern interfaces. - * When `false`, the tag has sharp, square corners, providing a more formal, structured, or technical feel. Often used in business context to label + * When `false`, the tag has sharp, square corners, providing a more formal, structured, or technical feel. Often used in a business context to label * promotions, offers or important notices. * @param size The size of the tag. * @param loader An optional loading spinner (or progress indicator) displayed before the [label]. Used to indicate that a process or action related to the @@ -496,7 +496,7 @@ open class OudsTagIcon protected constructor( } /** - * A circular progress indicator displayed in the input or tag area to indicate that tags are being loaded or processed. + * A circular progress indicator displayed in the tag area to indicate that tags are being loaded or processed. * * @param progress The loading progress, where 0.0 represents no progress and 1.0 represents full progress. * Values outside of this range are coerced into the range. diff --git a/core/src/main/java/com/orange/ouds/core/component/OudsTextInput.kt b/core/src/main/java/com/orange/ouds/core/component/OudsTextInput.kt index f7ad4a3cc..30e5cd297 100644 --- a/core/src/main/java/com/orange/ouds/core/component/OudsTextInput.kt +++ b/core/src/main/java/com/orange/ouds/core/component/OudsTextInput.kt @@ -114,14 +114,14 @@ import com.orange.ouds.theme.OudsThemeSettings * * @param textFieldState The editable text state of the text input, including both the text itself and position of the cursor or selection. * @param modifier [Modifier] applied to the text input. - * @param label Label displayed above the text input. It describe the purpose of the input. + * @param label Label displayed above the text input. It describes the purpose of the input. * @param placeholder Text displayed when the text input is empty. It provides a hint or guidance inside the field to suggest expected input. * @param leadingIcon An optional leading icon displayed at the start of the text input. It helps indicate the purpose of the input (magnifying glass for search, * envelope for email, etc.). Only use a leading icon if it adds clear functional or contextual value. * @param trailingIconButton An optional trailing icon button displayed at the end of the text input. It is used to provide actions related to the field: * clear input, toggle password visibility, etc. It can also indicate status or feedback (error checkmark, loading spinner). - * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting like a country code, a unit... - * @param suffix Text placed after the user's input, often used to display a currency or a unit (kg, %, cm…). + * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting such as a country code or a unit. + * @param suffix Text placed after the user's input, often used to display a currency or a unit (e.g., kg, %, cm). * @param enabled Controls the enabled state of the text input. When `false`, this text input will not be focusable and will not react to input events. * True by default. * @param readOnly Controls the read-only state of the text input. When `true`, the text is visible but not editable. @@ -129,10 +129,9 @@ import com.orange.ouds.theme.OudsThemeSettings * @param loader An optional loading progress indicator displayed in the text input to indicate an ongoing operation. * @param outlined Controls the style of the text input. When `true`, it displays a minimalist text input with a transparent background and a visible * stroke outlining the field. - * @param error Optional [OudsError] to provide in the case of the text input item should appear in error state to indicate that the user input does not meet - * validation rules or expected formatting, `null` otherwise. + * @param error Optional [OudsError] to indicate that the user input does not meet validation rules or expected formatting. Pass `null` if there is no error. * @param helperText An optional helper text displayed below the text input. It conveys additional information about the input field, such as how it will be - * used. It should ideally only take up a single line, though may wrap to multiple lines if required. + * used. It should ideally only take up a single line, though it may wrap to multiple lines if required. * @param helperLink An optional helper link displayed below or in place of the helper text. * @param keyboardOptions Software keyboard options that contain configurations such as [KeyboardType] and [ImeAction]. * @param onKeyboardAction Called when the user presses the action button in the input method editor (IME), or by pressing the enter key on a hardware keyboard. @@ -146,7 +145,7 @@ import com.orange.ouds.theme.OudsThemeSettings * @param inputTransformation An optional [InputTransformation] that will be used to transform changes to the [TextFieldState] made by the user. The transformation * will be applied to changes made by hardware and software keyboard events, pasting or dropping text, accessibility services, and tests. The transformation * will _not_ be applied when changing the [textFieldState] programmatically, or when the transformation is changed. If the transformation is changed on an - * existing text field, it will be applied to the next user edit. the transformation will not immediately affect the current [textFieldState]. + * existing text field, it will be applied to the next user edit. The transformation will not immediately affect the current [textFieldState]. * @param outputTransformation An optional [OutputTransformation] that transforms how the contents of the text field are presented. * @param interactionSource An optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this text input. Note that if `null` * is provided, interactions will still happen internally. @@ -243,14 +242,14 @@ fun OudsTextInput( * @param value Input text to be shown in the text field. * @param onValueChange Callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback. * @param modifier [Modifier] applied to the text input. - * @param label Label displayed above the text input. It describe the purpose of the input. + * @param label Label displayed above the text input. It describes the purpose of the input. * @param placeholder Text displayed when the text input is empty. It provides a hint or guidance inside the field to suggest expected input. * @param leadingIcon An optional leading icon displayed at the start of the text input. It helps indicate the purpose of the input (magnifying glass for search, * envelope for email, etc.). Only use a leading icon if it adds clear functional or contextual value. * @param trailingIconButton An optional trailing icon button displayed at the end of the text input. It is used to provide actions related to the field: * clear input, toggle password visibility, etc. It can also indicate status or feedback (error checkmark, loading spinner). - * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting like a country code, a unit... - * @param suffix Text placed after the user's input, often used to display a currency or a unit (kg, %, cm…). + * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting such as a country code or a unit. + * @param suffix Text placed after the user's input, often used to display a currency or a unit (e.g., kg, %, cm). * @param enabled Controls the enabled state of the text input. When `false`, this text input will not be focusable and will not react to input events. * True by default. * @param readOnly Controls the read-only state of the text input. When `true`, the text is visible but not editable. @@ -258,13 +257,12 @@ fun OudsTextInput( * @param loader An optional loading progress indicator displayed in the text input to indicate an ongoing operation. * @param outlined Controls the style of the text input. When `true`, it displays a minimalist text input with a transparent background and a visible * stroke outlining the field. - * @param error Optional [OudsError] to provide in the case of the text input item should appear in error state to indicate that the user input does not meet - * validation rules or expected formatting, `null` otherwise. + * @param error Optional [OudsError] to indicate that the user input does not meet validation rules or expected formatting. Pass `null` if there is no error. * @param helperText An optional helper text displayed below the text input. It conveys additional information about the input field, such as how it will be - * used. It should ideally only take up a single line, though may wrap to multiple lines if required. + * used. It should ideally only take up a single line, though it may wrap to multiple lines if required. * @param helperLink An optional helper link displayed below or in place of the helper text. - * @param keyboardOptions software keyboard options that contains configuration such as [KeyboardType] and [ImeAction]. - * @param keyboardActions when the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what + * @param keyboardOptions Software keyboard options that contain configuration such as [KeyboardType] and [ImeAction]. + * @param keyboardActions When the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what * you specified in [KeyboardOptions.imeAction]. * @param onTextLayout Callback that is executed when a new text layout is calculated. A [TextLayoutResult] object that callback provides contains paragraph * information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. @@ -366,14 +364,14 @@ fun OudsTextInput( * @param value The [androidx.compose.ui.text.input.TextFieldValue] to be shown in the text input. * @param onValueChange Called when the input service updates the values in [TextFieldValue]. * @param modifier [Modifier] applied to the text input. - * @param label Label displayed above the text input. It describe the purpose of the input. + * @param label Label displayed above the text input. It describes the purpose of the input. * @param placeholder Text displayed when the text input is empty. It provides a hint or guidance inside the field to suggest expected input. * @param leadingIcon An optional leading icon displayed at the start of the text input. It helps indicate the purpose of the input (magnifying glass for search, * envelope for email, etc.). Only use a leading icon if it adds clear functional or contextual value. * @param trailingIconButton An optional trailing icon button displayed at the end of the text input. It is used to provide actions related to the field: * clear input, toggle password visibility, etc. It can also indicate status or feedback (error checkmark, loading spinner). - * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting like a country code, a unit... - * @param suffix Text placed after the user's input, often used to display a currency or a unit (kg, %, cm…). + * @param prefix Text placed before the user's input. Commonly used to indicate expected formatting such as a country code or a unit. + * @param suffix Text placed after the user's input, often used to display a currency or a unit (e.g., kg, %, cm). * @param enabled Controls the enabled state of the text input. When `false`, this text input will not be focusable and will not react to input events. * True by default. * @param readOnly Controls the read-only state of the text input. When `true`, the text is visible but not editable. @@ -381,13 +379,12 @@ fun OudsTextInput( * @param loader An optional loading progress indicator displayed in the text input to indicate an ongoing operation. * @param outlined Controls the style of the text input. When `true`, it displays a minimalist text input with a transparent background and a visible * stroke outlining the field. - * @param error Optional [OudsError] to provide in the case of the text input item should appear in error state to indicate that the user input does not meet - * validation rules or expected formatting, `null` otherwise. + * @param error Optional [OudsError] to indicate that the user input does not meet validation rules or expected formatting. Pass `null` if there is no error. * @param helperText An optional helper text displayed below the text input. It conveys additional information about the input field, such as how it will be - * used. It should ideally only take up a single line, though may wrap to multiple lines if required. + * used. It should ideally only take up a single line, though it may wrap to multiple lines if required. * @param helperLink An optional helper link displayed below or in place of the helper text. - * @param keyboardOptions software keyboard options that contains configuration such as [KeyboardType] and [ImeAction]. - * @param keyboardActions when the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what + * @param keyboardOptions Software keyboard options that contain configuration such as [KeyboardType] and [ImeAction]. + * @param keyboardActions When the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what * you specified in [KeyboardOptions.imeAction]. * @param onTextLayout Callback that is executed when a new text layout is calculated. A [TextLayoutResult] object that callback provides contains paragraph * information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. diff --git a/core/src/main/java/com/orange/ouds/core/component/common/OudsError.kt b/core/src/main/java/com/orange/ouds/core/component/common/OudsError.kt index 6a75a16d9..ffd83d91d 100644 --- a/core/src/main/java/com/orange/ouds/core/component/common/OudsError.kt +++ b/core/src/main/java/com/orange/ouds/core/component/common/OudsError.kt @@ -13,7 +13,7 @@ package com.orange.ouds.core.component.common /** - * An OUDS error that take into account accessibility. + * An OUDS error that takes accessibility into account. * * @param message A mandatory localized message explaining the error. */ diff --git a/core/src/main/java/com/orange/ouds/core/component/content/OudsComponentContent.kt b/core/src/main/java/com/orange/ouds/core/component/content/OudsComponentContent.kt index 691dedbd2..4d779b770 100644 --- a/core/src/main/java/com/orange/ouds/core/component/content/OudsComponentContent.kt +++ b/core/src/main/java/com/orange/ouds/core/component/content/OudsComponentContent.kt @@ -37,8 +37,8 @@ internal fun getLocalExtraParameters(clazz: Class): ProvidableComposition * * Subclasses of [OudsComponentContent] should be used instead of composable methods when passing parameters to components. * This prevents using generic composable methods that can encapsulate any kind of views and thus helps developers to follow UI guidelines more easily. - * This also allows to group parameters that are related to the same content inside a component. - * For instance it is possible to create an `Icon` subclass to replace both `icon: @Composable () -> Unit` and `onIconClick: () -> Unit` parameters with a single `icon: Icon` parameter. + * This also allows grouping parameters that are related to the same content inside a component. + * For instance, it is possible to create an `Icon` subclass to replace both `icon: @Composable () -> Unit` and `onIconClick: () -> Unit` parameters with a single `icon: Icon` parameter. * * @param extraParametersClass The extra parameters class. * @param T The type of extra parameters. diff --git a/core/src/main/java/com/orange/ouds/core/theme/OudsColorScheme.kt b/core/src/main/java/com/orange/ouds/core/theme/OudsColorScheme.kt index d232ff47d..611c7affd 100644 --- a/core/src/main/java/com/orange/ouds/core/theme/OudsColorScheme.kt +++ b/core/src/main/java/com/orange/ouds/core/theme/OudsColorScheme.kt @@ -978,7 +978,7 @@ internal val OudsColorSemanticTokens.darkColorScheme: OudsColorScheme } ) -// Always colors are the same in light & dark modes +// Always colors are the same in Light & Dark modes private val OudsColorSemanticTokens.alwaysColorScheme: OudsColorScheme.Always get() = with(alwaysColorTokens) { OudsColorScheme.Always( @@ -989,7 +989,7 @@ private val OudsColorSemanticTokens.alwaysColorScheme: OudsColorScheme.Always ) } -// Repository colors are the same in light & dark modes +// Repository colors are the same in Light & Dark modes private val OudsColorSemanticTokens.repositoryColorScheme: OudsColorScheme.Repository get() = with(repositoryColorTokens) { OudsColorScheme.Repository( diff --git a/core/src/main/java/com/orange/ouds/core/theme/OudsTheme.kt b/core/src/main/java/com/orange/ouds/core/theme/OudsTheme.kt index 2e2768085..bd7bf4d5e 100644 --- a/core/src/main/java/com/orange/ouds/core/theme/OudsTheme.kt +++ b/core/src/main/java/com/orange/ouds/core/theme/OudsTheme.kt @@ -136,7 +136,7 @@ object OudsTheme { * your application in replacement of the `MaterialTheme`. * Cause OUDS supports multi-theme, you should pass the OUDS supported [theme] used by your application. * - * @param theme Theme to apply to your application. It must implement [OudsThemeContract] (e.g. OrangeTheme, SoshTheme, ...) + * @param theme Theme to apply to your application. It must implement [OudsThemeContract] (e.g., OrangeTheme, SoshTheme, ...) * @param darkThemeEnabled Indicates whether the dark theme is enabled or not. * @param content Theme nested content. The provided [theme] will be applied to this content. */ diff --git a/core/src/main/java/com/orange/ouds/core/utilities/OudsPreview.kt b/core/src/main/java/com/orange/ouds/core/utilities/OudsPreview.kt index 398eaa417..2e241843b 100644 --- a/core/src/main/java/com/orange/ouds/core/utilities/OudsPreview.kt +++ b/core/src/main/java/com/orange/ouds/core/utilities/OudsPreview.kt @@ -44,10 +44,10 @@ internal val LocalPreviewEnumEntry = staticCompositionLocalOf { null } /** * Configures the Compose OUDS preview environment in Android Studio. * - * @param modifier The modifier for the preview content. + * @param modifier The modifier to be applied to the preview content. * @param theme The preview theme. * @param darkThemeEnabled Indicates whether the dark theme is enabled or not. - * @param highContrastModeEnabled Indicates whether the high contrast mode is enabled for the preview. + * @param highContrastModeEnabled Indicates whether high contrast mode is enabled for the preview. * @param content The content of the preview. * * @suppress diff --git a/docs/assets/orange-style.css b/docs/assets/orange-style.css index d2e0a2dd9..ff5706cce 100644 --- a/docs/assets/orange-style.css +++ b/docs/assets/orange-style.css @@ -12,6 +12,7 @@ --elements-border-color: rgba(0, 0, 0, 0.2); --color-action-hover: rgba(0, 0, 0, 0.68); --bs-color-surface-status-warning-muted: rgba(255, 208, 0, 0.16); + --bs-emphasis-color: #000; --default-font-family: "Helvetica Neue", helvetica, "Noto Sans", "Liberation Sans", arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", @@ -35,14 +36,18 @@ --font-size-heading-large: 1.5rem; --font-size-display-small: 2rem; - --font-line-height-heading-large: 0px; - --font-line-height-display-small: 40px; - --font-line-height-body-medium: 14px; + --font-line-height-heading-large: 1.3333333333; + --font-line-height-heading-medium: 1.4; + --font-line-height-heading-small: 1.3333333333; + --font-line-height-display-small: 1.25; + --font-line-height-body-large: 1.5; + --font-line-height-body-medium: 1.4285714286; - --font-letter-spacing-display-small: -0.32px; - --font-letter-spacing-heading-large: 0.12px; - --font-letter-spacing-heading-small: 0.18px; - --font-letter-spacing-body-large: 0.2px; + --font-letter-spacing-display-small: -0.02rem; + --font-letter-spacing-heading-large: -0.0075rem; + --font-letter-spacing-heading-medium: 0rem; + --font-letter-spacing-heading-small: 0.01125rem; + --font-letter-spacing-body-large: 0.0125rem; --default-font-size: var(--font-size-body-large); --horizontal-spacing-for-content: var(--grid-margin); @@ -57,18 +62,22 @@ --hero-image-height: 170px; - --font-size-body-large: 1.125rem; - --font-size-heading-small: 1.5rem; + --font-size-body-large: 1rem; + --font-size-heading-small: 1.25rem; --font-size-heading-medium: 1.5rem; - --font-size-heading-large: 2.25rem; + --font-size-heading-large: 1.75rem; --font-size-display-small: 2.5rem; - --font-line-height-heading-large: 36px; + --font-line-height-heading-large: 1.2857142857; + --font-line-height-heading-medium: 1.3333333333; + --font-line-height-heading-small: 1.4; + --font-line-height-body-large: 1.5; - --font-letter-spacing-display-small: -0.4px; - --font-letter-spacing-heading-large: 0.28px; - --font-letter-spacing-heading-small: 0px; - --font-letter-spacing-body-large: 0.18px; + --font-letter-spacing-display-small: -0.025rem; + --font-letter-spacing-heading-large: -0.0175rem; + --font-letter-spacing-heading-medium: -0.0075rem; + --font-letter-spacing-heading-small: 0rem; + --font-letter-spacing-body-large: 0.0125rem; } @media (min-width: 1024px) { @@ -185,6 +194,10 @@ font-weight: 700; } +.toc--icon { + line-height: 0px; +} + .toc--row { min-height: 34px; } @@ -245,11 +258,27 @@ /* Homepage introduction */ .main-content[pageIds~="OUDS"] > .cover > .cover > .paragraph:first-of-type { font-size: var(--font-size-heading-small); - font-weight: 700; + font-weight: 400; letter-spacing: var(--font-letter-spacing-heading-small); + line-height: var(--font-line-height-heading-small); margin-bottom: 1rem; } +.main-content p.paragraph{ + margin-top: 24px; +} + +.main-content ul p.paragraph, +.main-content blockquote p.paragraph, +.main-content .table p.paragraph, +.main-content ol li p.paragraph { + margin-top: 0px; +} + +.main-content blockquote { + margin-top: 18px; +} + /* section headings, using :is() to select like Dokka */ .main-content :is(h1, h2) { font-weight: 700; @@ -260,10 +289,27 @@ line-height: var(--font-line-height-display-small); letter-spacing: var(--font-letter-spacing-display-small); } -h2, h3 { - font-size: var(--font-size-heading-large); - line-height: var(--font-line-height-heading-large); - letter-spacing: var(--font-letter-spacing-heading-large); +h1 { + margin-top: 18px; +} +h2 { + font-size: var(--font-size-heading-medium); + line-height: var(--font-line-height-heading-medium); + letter-spacing: var(--font-letter-spacing-heading-medium); +} +h3 { + font-size: var(--font-size-heading-small); + line-height: var(--font-line-height-heading-small); + letter-spacing: var(--font-letter-spacing-heading-small); + margin-bottom: 1rem; + margin-top: 2rem; +} +h4 { + font-size: var(--font-size-body-large); + line-height: var(--font-line-height-body-large); + letter-spacing: var(--font-letter-spacing-body-large); + margin-bottom: 0rem; + margin-top: 1.75rem; } /* deprecation content */ @@ -302,7 +348,7 @@ h2, h3 { code:not(.block) { padding: 0 0.4em 0.175em; margin: 0; - font-size: 80%; + font-size: 95%; white-space: break-spaces; border-radius: 2px; } @@ -310,6 +356,12 @@ code:not(.block) { code.block { border: 1px solid var(--elements-border-color); border-radius: 0; + margin-top: 8px; +} + +/* sample code block */ +.sample-container, div.CodeMirror { + margin-top: 24px; } /* mainly fixes dark theme */ @@ -332,7 +384,6 @@ li { td:first-child { width: 25%; - padding-left: 0px; } .parameters { diff --git a/docs/index.md b/docs/index.md index dfb57bb48..1ff7aef63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,11 @@ # OUDS Android -The OUDS Android library is compatible with **Android 5.0 (API level 21) and higher**. It serves as the interface between applications and custom themes, +The OUDS Android library is compatible with **Android 6.0 (API level 23) and higher**. It serves as the interface between applications and custom themes, providing essential components for app development. ## Getting started -### Gradle +### Add OUDS Android to your project OUDS Android is available through [Maven Central Repository](https://central.sonatype.com/search?q=com.orange.ouds.android). To use it, add the OUDS Android library core and the theme you want to use in the `dependencies` section of your app build script:

@@ -38,7 +38,14 @@ dependencies { -### Themes +### Select and apply your theme + +OUDS Android provides several themes: + +- `OrangeTheme`, usable by Orange applications. This theme includes several customizable elements such as the possibility of having rounded corners on certain + components rather than rectangular ones. +- `SoshTheme`, usable by Sosh applications. +- `WireframeTheme`, a white label theme usable by mock-ups, prototypes and proofs of concepts without Orange-flavoured styles. The `OudsTheme` method is an extension of the `MaterialTheme` method which allows to use the Orange Unified Design System in Jetpack Compose applications. Because OUDS Android supports multi-theme, you must provide the theme to use in your application as a parameter. OUDS Android components such as `OudsButton` @@ -52,11 +59,15 @@ OudsTheme(theme = OrangeTheme()) { } ``` -### Design tokens +The code above will apply the default Orange theme to your application, but you can modify its settings to customize it to your needs. See `orange-theme` module +documentation. + +### Use design tokens -Design tokens are a set of platform-agnostic design values that provide a consistent way to manage and maintain the design system across design and development -for each platforms. You can find more information about design tokens in -the [Orange Unified Design System documentation](https://unified-design-system.orange.com/472794e18/p/903414-introduction). +Orange Unified Design System is a multi-brand design system built upon the use of **design tokens**, which are standardized, reusable variables that store +visual design attributes such as colors, typography, spacing, and more. These tokens enable consistency across different brands and facilitate easier updates +and maintenance. For a more detailed understanding of design tokens and their role within a design system, please refer +to [Orange Unified Design System documentation](https://unified-design-system.orange.com/472794e18/p/903414-introduction). Semantic tokens in OUDS Android can be accessed using the various properties of the `OudsTheme` singleton. As an example, the token for the small heading font can be retrieved as follows: @@ -72,9 +83,9 @@ Figma is equivalent to: OudsTheme.colorScheme.content.onStatus.neutral.emphasized ``` -Raw and component tokens are not directly available in the `OudsTheme` singleton and should only be used when customizing themes. +> Raw and component tokens are not directly available in the `OudsTheme` singleton and should only be used when customizing themes. -### Components +### Use OUDS components OUDS Android components are all prefixed with `Ouds`. For instance, `OudsButton` is the equivalent of the Material `Button` for Orange Unified Design System. diff --git a/global-raw-tokens/Module.mustache b/global-raw-tokens/Module.mustache index d6760448c..784bada81 100644 --- a/global-raw-tokens/Module.mustache +++ b/global-raw-tokens/Module.mustache @@ -1,14 +1,90 @@ # Module global-raw-tokens -Contains the raw tokens that can be used by any theme. +The **OUDS Global Raw Tokens** module serves as the single source of truth for all primitive design values of the Orange Unity Design System. It contains the +"atomic" definitions of the brand style (Hex codes, pixel values, font files) without any context or semantic meaning. -#### Tokens versions +These tokens act as the ingredients used to build the semantic `OudsTheme` defined in the **core** module. They are automatically generated by Tokenator. + +## Purpose + +This module is strictly a **dictionary of values**. + +- **Context-Agnostic:** A raw token like `Orange500` always refers to the exact same hex code `#FF7900`, regardless of whether the app is in Light or Dark mode. +- **Immutable:** These values represent the fixed brand guidelines and should not be altered at runtime. + +## Token Categories + +**Package:** `com.orange.ouds.tokens.global.raw` + +The raw tokens are organized into categories representing the fundamental properties of the design system. + +### 1. Raw Borders +Contains primitive values for corner radiuses and border widths. + +### 2. Raw Colors +Contains the complete definition of the OUDS color palette (e.g., Orange, Blue, Green, Grey scales). +- **Format:** `ColorName + Shade` (e.g., `ColorFunctionalAmethyst400`, `ColorFunctionalAmethyst600`, `ColorFunctionalGrayDark80`). +- **Value:** Hardcoded Hex values (`0xffa885d8`). + +### 3. Raw Dimensions +Contains primitive spacing and sizing units. +- **Format:** `Dimension + Scale` (e.g., `Dimension100`, `Dimension200`). +- **Value:** Density-independent pixels (`dp`). + +### 4. Raw Effects +Contains various visual effects applied to components, such as blurs. +- **Format:** `Effect + Scale` (e.g., `EffectBlur160`). +- **Value:** Parameters defining the visual distortion or filter applied. + +### 5. Raw Elevations +Contains the primitive definitions for depth and shadow effects. +- **Format:** `Elevation + Level` (e.g., `Elevation0`, `Elevation5`). +- **Value:** Combinations of shadow colors, offsets, and blur radiuses often mapped to standard dp elevations. + +### 6. Raw Grids +Contains the primitive layout grid definitions used to structure the UI. +- **Format:** `Grid element + Scale` (e.g., `GridMargin100`) or `Grid element + Window Size` (e.g., `GridMaxWidthCompact`). +- **Value:** Columns count, margin sizes, and gutter widths tailored for specific breakpoints. + +### 7. Raw Opacities +Contains primitive alpha transparency values. +- **Format:** `Opacity + Level` (e.g., `Opacity100`, `Opacity500`). +- **Value:** Float values ranging from 0.0 (transparent) to 1.0 (opaque). + +### 8. Raw Typography +Contains the definitions of basic text properties. +- **Format:** `Property + Scale` (e.g., `FontLineHeight100`, `FontSize200`). +- **Value:** Primitive values for font sizes, line heights, font weights, and letter spacing. + +## Usage Guidelines + +**⚠️ Important:** As an application developer, you should **rarely, if ever, use this module directly.** + +### Raw vs. Semantic +The core philosophy of OUDS is to separate the *Value* (Raw) from the *Usage* (Semantic). + +| Feature | Global Raw Tokens | OUDS Core Theme (Semantic) | +| :--- | :--- | :--- | +| **Example** | `Orange500` | `OudsTheme.colorScheme.brand.primary` | +| **Definition** | It is Orange `#FF7900`. | It is the main brand color used for primary actions. | +| **Context** | None. It is always orange. | Context-aware. It might be different in Dark and Light mode. | +| **Usage** | **Internal usage only.** | **Recommended for App UI.** | + +### When to use this module? + +You should only access `global-raw-tokens` in the following advanced scenarios: +1. **Defining Semantic Tokens:** When you are creating a custom theme implementation, you map these Raw tokens to Semantic slots (e.g., assigning `Orange500` to `brand.primary`). +2. **Creating Custom Components:** If you are building a highly specific component that cannot be achieved with standard semantic tokens (rare), you might need to reference a raw value to stay within brand guidelines. + +## Tokens versions + +This module is generated based on specific versions of the design system definitions. It ensures traceability between the design specifications and the implementation.
Android core{{AndroidCore}}
OUDS core{{OudsCore}}
-# Package com.orange.ouds.tokens.global.raw - -Contains the global raw tokens for borders, colors, dimensions, etc... These files are automatically generated by Tokenator. \ No newline at end of file +> 🤖 **Note:** Files in this module are **automatically generated by Tokenator** based on the design definitions. +> +> Any manual changes to these files will be lost during the next synchronization. \ No newline at end of file diff --git a/gradle.properties b/gradle.properties index 1765498d5..12b2b68d5 100644 --- a/gradle.properties +++ b/gradle.properties @@ -10,7 +10,7 @@ # Software description: Android library of reusable graphical components # # Project-wide Gradle settings. -# IDE (e.g. Android Studio) users: +# IDE (e.g., Android Studio) users: # Gradle settings configured through the IDE *will override* # any settings specified in this file. # For more details on how to configure your build environment visit diff --git a/theme-contract/Module.mustache b/theme-contract/Module.mustache index 080639311..de04fdf45 100644 --- a/theme-contract/Module.mustache +++ b/theme-contract/Module.mustache @@ -1,32 +1,104 @@ # Module theme-contract -This is the interface between the library and the custom themes. -#### Tokens versions +The **OUDS Theme Contract** module is the cornerstone of the design system's theming architecture. It defines the **abstract interfaces** that all concrete themes (Orange, Sosh, Wireframe, etc.) must implement. + +It enforces a strict separation of concerns: +- **The Contract** defines *what* can be styled (e.g., "Brand Primary Color"). +- **The Implementation** defines *how* it looks (e.g., "Orange #FF7900"). + +## Purpose + +This module guarantees consistency across applications. By coding against these interfaces rather than specific implementations, developers can switch themes dynamically without changing a single line of UI code. + +## Contract Structure + +**Package:** `com.orange.ouds.theme.contract` + +This module does not contain any values (hex codes, dp sizes). It only contains: +1. **Interfaces:** `OudsThemeContract`, `OudsColorSemanticTokens`, `OudsFontSemanticTokens`. +2. **Token Objects:** Abstract representations of semantic tokens. + +### Color Contract +Defines semantic color roles available in the system. +- **Interface:** `OudsColorSemanticTokens` +- **Purpose:** Ensures every theme provides colors for Brand, Surface, Content, Status, etc. +- **Example:** Defines that a `brand.primary` color *must* exist, but doesn't say it is `#FF7900`. + +### Material Color Contract +Defines the mapping required to bridge OUDS tokens to the standard Material Design 3 color slots. +- **Interface:** `OudsMaterialColorTokens` +- **Purpose:** Ensures that native Material Compose components (like `Button`, `TextField`, `Surface`) automatically pick up the correct OUDS colors without needing manual overrides. + +### Typography Contract +Defines the text styles. +- **Interface:** `OudsFontSemanticTokens` +- **Purpose:** Ensures existence of Display, Heading, Title, Body, and Label styles. +- **Example:** Defines that a `heading.large` style exists with properties for font, weight, and size. + +### Dimension Contracts +Defines abstract sizes, spaces, and borders. +- **Interfaces:** `OudsBorderSemanticTokens`, `OudsSizeSemanticTokens`, `OudsSpaceSemanticTokens`. +- **Example:** Defines that a `spaces.fixed.medium` token exists. + +### Component Tokens Contract +Defines tokens specifically scoped to OUDS custom components. +- **Interface:** `OudsComponentsTokens` +- **Purpose:** Allows overriding default values for specific components without altering the global semantic theme. +- **Example:** Defines specific tokens for an `OudsButton` (e.g., specific background color) independent of the generic theme. + +### Other Contracts +Includes interfaces for `OudsElevationSemanticTokens`, `OudsGridSemanticTokens`, and `OudsOpacitySemanticTokens`. + +## Usage + +### For Application Developers +**You typically do not interact with this module directly.** +You will use concrete implementations of this contract (like `OrangeTheme`, `SoshTheme`, etc.) via the `OudsTheme` composable provided by the `core` module. +However, understanding this contract helps you know which semantic tokens are guaranteed to exist regardless of the chosen theme. + +### For Theme Creators +If you are creating a custom theme implementation (e.g., for a specific sub-brand) while maintaining full compatibility with OUDS components, you must implement `OudsThemeContract`. + +## Relationship with other modules + +| Module | Role | Analogy | +| :--- | :--- | :--- | +| **global-raw-tokens** | The Ingredients | "Flour", "Eggs", "Milk" (The raw values like `#FF7900`, `16dp`) | +| **theme-contract** | **The Recipe Template** | **"A cake must have a base, a filling, and icing" (The rules defining what a theme is)** | +| **theme-orange** / **theme-sosh** / ... | The Concrete Cakes | "The Orange Cake" or "The Sosh Cake" (Specific implementations of the template) | +| **core** | The Bakery Window | The access point (`OudsTheme`) that serves the chosen cake to the customer | + +## Tokens versions
Android system{{AndroidSystem}}
Orange brand{{OrangeBrand}}
+> 🤖 **Note:** Files in `tokens` packages are **automatically generated by Tokenator** based on the design definitions. +> +> Any manual changes to these files will be lost during the next synchronization. + # Package com.orange.ouds.theme -Contains the `OudsThemeContract` interface that can be implemented to create a new theme by overriding semantic and components tokens. -Other files contains helpers to manage themes. +This is the root package of the contract module. It primarily defines the `OudsThemeContract` interface. +This interface is the central point of the design system's abstraction. It aggregates all the specific sub-contracts (colors, typography, borders, spaces, etc.) into a single object that represents a complete theme. Any class claiming to be an OUDS Theme (like `OrangeTheme`) must implement this contract. # Package com.orange.ouds.theme.tokens -Contains key token files which are tokens identifiers that should be used in your app to get a token value. -These files are automatically generated by Tokenator. +This package contains the **Key Token objects** that define the organization of semantic tokens. It establishes the **hierarchy** (tree structure) used to access token values. +Instead of a flat list, it groups tokens into logical categories (like `OudsBorderSemanticTokens`, `OudsSizeSemanticTokens`, or `OudsSpaceSemanticTokens`), enabling structured navigation through the theme properties. -# Package com.orange.ouds.theme.tokens.android +# Package com.orange.ouds.theme.tokens.components -Contains android tokens used for Material mapping, coming from Figma and automatically generated by Tokenator. +This package holds the contract for component-specific tokens (`OudsComponentTokens`). It defines the structure for overriding or specifying design values (like specific paddings or colors) for individual OUDS components, independent of the global theme values. -# Package com.orange.ouds.theme.tokens.components +# Package com.orange.ouds.theme.tokens.material -Contains specific components tokens coming from Figma and automatically generated by Tokenator. +This package defines the `OudsMaterialColorTokens` interface, which establishes the contract for mapping OUDS semantic colors to the standard Material Design 3 color roles, ensuring seamless integration with native Compose components. # Package com.orange.ouds.theme.tokens.semantic -Contains semantics tokens coming from Figma and automatically generated by Tokenator. \ No newline at end of file +This package contains the **interfaces** defining the semantic properties of the theme. It hosts the **contracts** for colors (`OudsColorSemanticTokens`), typography (`OudsFontSemanticTokens`), borders, elevations, grids, and opacities. +It dictates that every theme must implement these specific interfaces to provide the fundamental visual attributes. \ No newline at end of file diff --git a/theme-orange/Module.mustache b/theme-orange/Module.mustache index 6ba352391..883e2e68b 100644 --- a/theme-orange/Module.mustache +++ b/theme-orange/Module.mustache @@ -1,8 +1,79 @@ # Module theme-orange -Contains the Orange theme. +The **OUDS Theme Orange** module provides the concrete implementation of the Orange design system theme. It maps the abstract definitions from the **Theme Contract** to the specific **Raw Tokens** of the Orange brand. -#### Tokens versions +It serves as the "factory" that assembles the specific visual identity of Orange. + +## Purpose + +While the `core` module provides the mechanisms to *access* the theme, and `theme-contract` defines *what* a theme is, **theme-orange** defines **what the Orange theme looks like**. + +- **Implementation:** It implements the interfaces defined in `theme-contract` (`OudsColorSemanticTokens`, `OudsFontSemanticTokens`, etc.). +- **Mapping:** It assigns specific values from Orange raw tokens (e.g., `ColorOrange500`) or global raw tokens (e.g., `ColorFunctionalBlack`) to semantic slots (e.g., `contentBrandPrimaryDark`, `contentDefaultLight`). + +## Usage + +To use the Orange theme in your application, follow these steps: + +### 1. Add the dependency +Ensure the `theme-orange` module is included in your module's `build.gradle.kts` file in addition to the `core` module: + +
+ Kotlin DSL + +```kotlin +dependencies { + // ... + implementation("com.orange.ouds.android:ouds-core:0.4.0") + implementation("com.orange.ouds.android:ouds-theme-orange:0.4.0") + // ... +} +``` + +

+ +
+ Groovy DSL + +```shell +dependencies { + // ... + implementation 'com.orange.ouds.android:ouds-core:0.4.0' + implementation 'com.orange.ouds.android:ouds-theme-orange:0.4.0' + // ... +} +``` + +
+ +### 2. Initialize and Customize the Theme + +In your application, you must provide the `OrangeTheme` instance to the `OudsTheme` composable. This effectively "injects" the Orange visual style into the OUDS system. + +> Use `OudsTheme` as a replacement for the traditional `MaterialTheme`. + +```kotlin +OudsTheme(theme = OrangeTheme(roundedCornerButtons = true, roundedCornerTextInputs = true)) { + // Use OUDS Android or Material components here for an interface + // matching the Orange Unified Design System with the customized Orange theme +} +``` + +In the example above, you can see that Orange theme includes several customizable elements such as the possibility of having rounded corners on certain +components rather than rectangular ones. + +## Relationship with other modules + +| Module | Role | Analogy | +| :--- | :--- | :--- | +| **global-raw-tokens** | The Ingredients | "Flour", "Sugar", "Orange" | +| **theme-contract** | The Recipe Template | "A Cake Recipe" | +| **theme-orange** | **The Specific Recipe** | **"Orange Cake Recipe"** | +| **core** | The Baker | "Making the Orange Cake available to eat" | + +## Tokens versions + +This module implements the design specifications versioned below: @@ -10,14 +81,26 @@ Contains the Orange theme.
Android system{{AndroidSystem}}
Orange core{{OrangeCore}}
+> 🤖 **Note:** The majority of the files in this module (specifically within the `tokens` packages) are **automatically generated by Tokenator** based on the design definitions. +> +> Any manual changes to these files will be lost during the next synchronization. + # Package com.orange.ouds.theme.orange -Contains the `OrangeTheme` class that implements `OudsThemeContract` and represents the Orange theme. +This package contains the core `OrangeTheme` class, which acts as the bridge between the abstract contract and the concrete Orange visual implementation used to configure the `OudsTheme`. + +# Package com.orange.ouds.theme.orange.tokens.components + +This package provides specific token overrides for OUDS custom components (e.g., buttons, cards) within the Orange theme context, allowing fine-tuned styling adjustments that differ from the global semantic theme. + +# Package com.orange.ouds.theme.orange.tokens.material + +This package implements the `OudsMaterialColorTokens` contract, ensuring that standard Material Design 3 components (like native Buttons or Cards) automatically reflect the Orange brand colors without needing manual overrides. # Package com.orange.ouds.theme.orange.tokens.raw -Contains the raw tokens that are specific to the Orange theme. These files are automatically generated by Tokenator. +This package defines the fundamental, immutable values (such as specific hex codes and base dimensions) that constitute the raw ingredients of the Orange brand identity. # Package com.orange.ouds.theme.orange.tokens.semantic -Contains the semantic tokens for the Orange theme. These files are automatically generated by Tokenator. \ No newline at end of file +This package implements the mapping logic, assigning specific Orange raw values to the abstract semantic roles defined by the design system (e.g., linking `Orange500` to `borderBrandPrimaryDark`). diff --git a/theme-sosh/Module.mustache b/theme-sosh/Module.mustache index 26c5242af..828b9a22a 100644 --- a/theme-sosh/Module.mustache +++ b/theme-sosh/Module.mustache @@ -1,8 +1,76 @@ # Module theme-sosh -Contains the Sosh theme. +The **OUDS Theme Sosh** module provides the concrete implementation of the Sosh design system theme. It maps the abstract definitions from the **Theme Contract** to the specific **Raw Tokens** of the Sosh brand. -#### Tokens versions +It serves as the "factory" that assembles the specific visual identity of Sosh. + +## Purpose + +While the `core` module provides the mechanisms to *access* the theme, and `theme-contract` defines *what* a theme is, **theme-sosh** defines **what the Sosh theme looks like**. + +- **Implementation:** It implements the interfaces defined in `theme-contract` (`OudsColorSemanticTokens`, `OudsFontSemanticTokens`, etc.). +- **Mapping:** It assigns specific values from Sosh raw tokens (e.g., `ColorBlueDuckDark960`) or global raw tokens (e.g., `ColorFunctionalBlack`) to semantic slots (e.g., `bgPrimaryDark`, `contentDefaultLight`). + +## Usage + +To use the Sosh theme in your application, follow these steps: + +### 1. Add the dependency +Ensure the `theme-sosh` module is included in your module's `build.gradle.kts` file in addition to the `core` module: + +
+ Kotlin DSL + +```kotlin +dependencies { + // ... + implementation("com.orange.ouds.android:ouds-core:0.4.0") + implementation("com.orange.ouds.android:ouds-theme-sosh:0.4.0") + // ... +} +``` + +

+ +
+ Groovy DSL + +```shell +dependencies { + // ... + implementation 'com.orange.ouds.android:ouds-core:0.4.0' + implementation 'com.orange.ouds.android:ouds-theme-sosh:0.4.0' + // ... +} +``` + +
+ +### 2. Initialize the Theme + +In your application, you must provide the `SoshTheme` instance to the `OudsTheme` composable. This effectively "injects" the Sosh visual style into the OUDS system. + +> Use `OudsTheme` as a replacement for the traditional `MaterialTheme`. + +```kotlin +OudsTheme(theme = SoshTheme()) { + // Use OUDS Android or Material components here for an interface + // matching the Orange Unified Design System with the Sosh theme +} +``` + +## Relationship with other modules + +Module | Role | Analogy | +:--- | :--- | :--- | +**global-raw-tokens** | The Ingredients | "Flour", "Sugar", "Chocolate" | +**theme-contract** | The Recipe Template | "A Cake Recipe" | +**theme-sosh** | **The Specific Recipe** | **"Sosh Special Cake Recipe"** | +**core** | The Baker | "Making the Sosh Cake available to eat" | + +## Tokens versions + +This module implements the design specifications versioned below: @@ -10,14 +78,26 @@ Contains the Sosh theme.
Android system{{AndroidSystem}}
Sosh core{{SoshCore}}
+> 🤖 **Note:** The majority of the files in this module (specifically within the `tokens` packages) are **automatically generated by Tokenator** based on the design definitions. +> +> Any manual changes to these files will be lost during the next synchronization. + # Package com.orange.ouds.theme.sosh -Contains the `SoshTheme` class that implements `OudsThemeContract` and represents the Sosh theme. +This package contains the core `SoshTheme` class, which acts as the bridge between the abstract contract and the concrete Sosh visual implementation used to configure the `OudsTheme`. + +# Package com.orange.ouds.theme.sosh.tokens.components + +This package provides specific token overrides for OUDS custom components (e.g., buttons, cards) within the Sosh theme context, allowing fine-tuned styling adjustments that differ from the global semantic theme. + +# Package com.orange.ouds.theme.sosh.tokens.material + +This package implements the `OudsMaterialColorTokens` contract, ensuring that standard Material Design 3 components (like native Buttons or Cards) automatically reflect the Sosh brand colors without needing manual overrides. # Package com.orange.ouds.theme.sosh.tokens.raw -Contains the raw tokens that are specific to the Sosh theme. These files are automatically generated by Tokenator. +This package defines the fundamental, immutable values (such as specific hex codes and base dimensions) that constitute the raw ingredients of the Sosh brand identity. # Package com.orange.ouds.theme.sosh.tokens.semantic -Contains the semantic tokens for the Sosh theme. These files are automatically generated by Tokenator. \ No newline at end of file +This package implements the mapping logic, assigning specific Sosh raw values to the abstract semantic roles defined by the design system (e.g., linking `ColorMagenta300` to `borderBrandPrimaryDark`). \ No newline at end of file diff --git a/theme-wireframe/Module.mustache b/theme-wireframe/Module.mustache index 1157ef771..f733dbcb8 100644 --- a/theme-wireframe/Module.mustache +++ b/theme-wireframe/Module.mustache @@ -1,8 +1,75 @@ # Module theme-wireframe -Contains the Wireframe theme. +The **OUDS Theme Wireframe** module provides the concrete implementation of the Wireframe design system theme. It maps the abstract definitions from the **Theme Contract** to specific **Raw Tokens** intended for prototyping or white-label applications. -#### Tokens versions +## Purpose + +While the `core` module provides the mechanisms to *access* the theme, and `theme-contract` defines *what* a theme is, **theme-wireframe** defines **what the Wireframe theme looks like**. + +- **White Label Use:** Since it uses neutral colors and generic styles, **this theme is ideal for "White Label" applications** that require a clean, unbranded base before a specific visual identity is applied. +- **Implementation:** It implements the interfaces defined in `theme-contract` (`OudsColorSemanticTokens`, `OudsFontSemanticTokens`, etc.). +- **Mapping:** It assigns specific values from Wireframe raw tokens (e.g., `ColorFunctionalGrayDark880`) or global raw tokens (e.g., `ColorFunctionalSun750`) to semantic slots (e.g., `bgPrimaryDark`, `contentStatusWarningLight`). + +## Usage + +To use the Wireframe theme in your application (e.g., for internal testing, layout validation, or as a White Label base), follow these steps: + +### 1. Add the dependency +Ensure the `theme-wireframe` module is included in your module's `build.gradle.kts` file in addition to the `core` module: + +
+ Kotlin DSL + +```kotlin +dependencies { + // ... + implementation("com.orange.ouds.android:ouds-core:0.4.0") + implementation("com.orange.ouds.android:ouds-theme-wireframe:0.4.0") + // ... +} +``` + +

+ +
+ Groovy DSL + +```shell +dependencies { + // ... + implementation 'com.orange.ouds.android:ouds-core:0.4.0' + implementation 'com.orange.ouds.android:ouds-theme-wireframe:0.4.0' + // ... +} +``` + +
+ +### 2. Initialize the Theme + +In your application, you must provide the `WireframeTheme` instance to the `OudsTheme` composable. This effectively "injects" the Wireframe visual style into the OUDS system. + +> Use `OudsTheme` as a replacement for the traditional `MaterialTheme`. + +```kotlin +OudsTheme(theme = WireframeTheme()) { + // Use OUDS Android or Material components here for an interface + // matching the Orange Unified Design System with the Wireframe theme +} +``` + +## Relationship with other modules + +Module | Role | Analogy | +:--- | :--- | :--- | +**global-raw-tokens** | The Ingredients | "Flour", "Water", "Salt" | +**theme-contract** | The Recipe Template | "A Cake Recipe" | +**theme-wireframe** | **The Specific Recipe** | **"Basic Bread Recipe"** | +**core** | The Baker | "Making the Basic Bread available to eat" | + +## Tokens versions + +This module implements the design specifications versioned below: @@ -10,14 +77,26 @@ Contains the Wireframe theme.
Android system{{AndroidSystem}}
Wireframe core{{WireframeCore}}
+> 🤖 **Note:** The majority of the files in this module (specifically within the `tokens` packages) are **automatically generated by Tokenator** based on the design definitions. +> +> Any manual changes to these files will be lost during the next synchronization. + # Package com.orange.ouds.theme.wireframe -Contains the `WireframeTheme` class that implements `OudsThemeContract` and represents the Wireframe theme. +This package contains the core `WireframeTheme` class, which acts as the bridge between the abstract contract and the concrete Wireframe visual implementation used to configure the `OudsTheme`. + +# Package com.orange.ouds.theme.wireframe.tokens.components + +This package provides specific token overrides for OUDS custom components (e.g., buttons, cards) within the Wireframe theme context, allowing fine-tuned styling adjustments that differ from the global semantic theme. + +# Package com.orange.ouds.theme.wireframe.tokens.material + +This package implements the `OudsMaterialColorTokens` contract, ensuring that standard Material Design 3 components (like native Buttons or Cards) automatically reflect the Wireframe colors without needing manual overrides. # Package com.orange.ouds.theme.wireframe.tokens.raw -Contains the raw tokens that are specific to the Wireframe theme. These files are automatically generated by Tokenator. +Contains the raw tokens that are specific to the Wireframe theme. # Package com.orange.ouds.theme.wireframe.tokens.semantic -Contains the semantic tokens for the Wireframe theme. These files are automatically generated by Tokenator. \ No newline at end of file +This package implements the mapping logic, assigning specific Wireframe raw values to the abstract semantic roles defined by the design system (e.g., linking `ColorRoyalBlue300` to `borderBrandPrimaryDark`). \ No newline at end of file