Imported from Orange-OpenSource/ouds-android (AGENTS.md). Install upstream with npx skills add Orange-OpenSource/ouds-android. Copyright stays with the author.

AGENTS.md - AI Agent Guidelines for OUDS Android

This document provides context and guidelines for AI agents assisting with the OUDS Android (Orange Unified Design System for Android) project.

Project Overview

OUDS Android is an Android design system library that provides Orange-branded UI components and tokens for building consistent, accessible Android applications across all Orange brands and affiliates. This library is the Android implementation of the Orange Unified Design System.

• Language: Kotlin
• UI Framework: Jetpack Compose
• Minimum SDK: API 23 (Android 6.0)
• Build System: Gradle (Kotlin DSL)
• License: MIT
• Repository: https://github.com/Orange-OpenSource/ouds-android
• Documentation: https://android.unified-design-system.orange.com/
• Distribution: Maven Central

Project Structure

The project is organized into the following modules:

Essential Modules

• :core - Core library containing reusable UI components (e.g., OudsTag, buttons, etc.)
• :foundation - Foundation layer containing code used in all modules (extension methods, annotations, etc.)
• :global-raw-tokens - Raw design tokens (colors, typography, spacing, etc.)
• :theme-contract - Theme abstraction layer and token interfaces (e.g., OudsThemeContract, OudsAlertTokens)

Theme Modules

• :theme-orange - Orange brand theme implementation
• :theme-orange-compact - Compact variant of Orange theme
• :theme-sosh - Sosh brand theme implementation
• :theme-wireframe - Wireframe theme for development/prototyping

Application & Testing

• :app - Demo application "Design Toolbox" showcasing components and design tokens
• :core-test - Shared testing utilities
• :dokka-plugin - Custom Dokka plugin for documentation generation

Build Configuration

• :buildSrc - Build configuration and shared Gradle logic
• Root project - Overall project configuration

Key Architecture Concepts

1. Theming System

OUDS Android uses a multi-brand theming system:

OudsTheme(
    theme = OrangeTheme(
        orangeFontFamily = OrangeFontFamily(
            latin = OrangeHelveticaNeueLatin.Bundled(...)
        )
    )
) {
    // UI components here
}

• Themes are interchangeable (Orange, Sosh, Wireframe, etc.)
• Each theme implements the theme-contract interfaces
• Tokens drive all visual properties (colors, typography, spacing, etc.)

2. Token-Based Design

• Raw Tokens (global-raw-tokens) - Base design values
• Semantic Tokens (theme-contract) - Semantic token definitions (e.g., OudsColorActionSemanticTokens)
• Component Tokens (theme-contract) - Component-specific token definitions (e.g., OudsAlertTokens)
• Theme Implementations - Concrete semantic and component token values for each brand, as well as brand-specific raw tokens

The files containing the tokens are generated by an external tool called Tokenator. This tool takes Figma tokens as an input and convert them to Kotlin code.

3. Component Structure

Components follow a consistent pattern:

• Composable functions in :core
• Token-driven styling via theme
• Preview functions for development
• Accessibility support built-in
• KDoc-based documentation for public methods that includes simple code samples

Development Guidelines

Code Style

1. Compose Best Practices: Use modern Jetpack Compose patterns
2. Coding Conventions: Follow Style guidelines for Jetpack Compose APIs which basically includes:
   • The API Guidelines for Jetpack Compose (based on Kotlin Coding Conventions)
   • The API Guidelines for @Composable components in Jetpack Compose
3. Naming:
   • Prefix components with Ouds (e.g., OudsTag, OudsButton)
   • Token classes end with Tokens (e.g., OudsAlertTokens)

File Organization

• Component files in :core/src/main/java/com/orange/ouds/core/component/
• Token definitions in :theme-contract/src/main/java/com/orange/ouds/theme/tokens/
• Demo app code in :app/src/main/java/com/orange/ouds/app

Adding New Components

When adding new components:

1. Verify that component tokens generated by Tokenator are defined in :theme-contract and implemented in theme modules (:theme-orange, etc.)
2. Create one or more composables in :core module, trying to match the equivalent Material 3 APIs as much as possible
3. Ensure accessibility semantics are properly implemented
4. Add a sample code for each component composable
5. Include @Preview annotations for IDE preview
6. Add snapshot tests in :core-test module and generate snapshots for each theme
7. Add instrumented Compose UI tests for user interactions such as clicks
8. Add demo screen in :app module
9. Update Component.kt in :buildSrc as well as the component KDoc so that it references the design guidelines link and version

State Management

Demo screens use state classes (e.g., AlertMessageDemoState, InlineAlertDemoState) to:

• Manage component configuration
• Provide interactive controls in demo app
• Showcase different component variants Customization parameters in demo screens match the parameters of the component APIs

Resource Handling

• Drawable resources defined via OudsDrawableResources interface
• Each theme provides concrete drawable implementations
• Use token system for colors, dimensions, and other values

Testing

• Snapshot tests for visual regression
• Compose UI tests for component behavior
• Accessibility testing should be considered

Documentation

• Public APIs must have KDoc comments
• Documentation generated with Dokka
• Published to https://android.unified-design-system.orange.com/
• README examples should be clear and concise

Common Tasks

Adding a New Theme

1. Create new module (e.g., :theme-newbrand)
2. Implement OudsTheme interface from :theme-contract
3. Use concrete token values generated by Tokenator
4. Add to :app for testing
5. Update documentation

Modifying Existing Components

1. Check token definitions in :theme-contract
2. Update component implementation in :core
3. Update reference snapshots in all theme modules
4. Update demo screens if needed

Build & Deploy

• Build: ./gradlew build
• Run demo app: ./gradlew :app:installProdDebug
• Snapshot tests: ./gradlew verifyPaparazziDebug
• Instrumented tests: ./gradlew :core:connectedCheck
• Distribution: Maven Central via com.orange.ouds.android group

Important Considerations

1. Multi-Brand Support

Always consider that changes affect multiple brands. Test components with:

• Orange theme
• Orange Compact theme
• Sosh theme
• Wireframe theme
• Light and dark modes

2. Accessibility

• Provide content descriptions
• Ensure proper semantic roles
• Support TalkBack and other accessibility services
• Maintain sufficient color contrast

3. Backward Compatibility

• Minimum SDK 23 (Android 6.0)
• Be mindful of deprecated APIs
• Maintain stable public API surface

4. Performance

• Compose best practices (remember, derivedStateOf, etc.)
• Avoid unnecessary recompositions
• Optimize preview rendering

5. Miscellaneous

• Any hardcoded string must be avoided; use stringResource.

Contributing

See CONTRIBUTING.md for detailed contribution guidelines.

AI Skills

Agent skills are located in the skills/ directory at the repository root. The .agents/, .claude/, and .opencode/ directories contain skills symlinks pointing to the root skills/ directory, ensuring compatibility across all major AI agent tools.

Available skills

Maintaining Skills

The skills must be kept synchronized with code changes to ensure AI agents have accurate, up-to-date information.

When to update skills:

• Before each release

How to update:

1. Navigate to skills/maintenance/update-skills-prompt.md
2. Copy the prompt and execute it with your AI agent
3. Review the generated report and proposed changes
4. Commit the updated skills

The update prompt automatically detects changes in components, tokens, themes, integration setup, patterns, and deprecations by analyzing the codebase source code, KDoc documentation, and demo app.

Resources

• Documentation: https://android.unified-design-system.orange.com/
• Repository: https://github.com/Orange-OpenSource/ouds-android
• Demo App: http://oran.ge/designtoolbox
• Issues: https://github.com/Orange-OpenSource/ouds-android/issues
• Orange Unified Design System: https://unified-design-system.orange.com/

Data Privacy & Permissions

• This SDK does not handle personal data
• No device permissions required
• Complies with Orange data privacy standards

For AI Agents: This document is specifically designed to provide context for AI assistants. When making changes, consider the multi-module, multi-brand nature of this design system.