Skip to content

AGENTS.md

Latest commit

 

History

History
225 lines (159 loc) · 8.31 KB

AGENTS.md

File metadata and controls

225 lines (159 loc) · 8.31 KB

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.

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:
  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

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.

Resources

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.