Update AGENTS.md

Author: florentmaitre

AGENTS.md

@@ -4,7 +4,7 @@ This document provides context and guidelines for AI agents assisting with the *
 
 ## 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.
+**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](https://unified-design-system.orange.com/).
 
 - **Language**: Kotlin
 - **UI Framework**: Jetpack Compose
@@ -19,24 +19,23 @@ This document provides context and guidelines for AI agents assisting with the *
 
 The project is organized into the following modules:
 
-### Core Modules
+### Essential Modules
 
 - **`:core`** - Core library containing reusable UI components (e.g., `OudsTag`, buttons, etc.)
-- **`:foundation`** - Foundation layer with basic design primitives
+- **`: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., `OudsDrawableResources`, `OudsAlertTokens`)
+- **`: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-orange-business-tools`** - Orange Business Tools theme variant
 - **`:theme-sosh`** - Sosh brand theme implementation
 - **`:theme-wireframe`** - Wireframe theme for development/prototyping
 
 ### Application & Testing
 
-- **`:app`** - Demo application "Design Toolbox" showcasing components (e.g., `AlertMessageDemoState`, `InlineAlertDemoState`, `ComponentCode`)
+- **`:app`** - Demo application "Design Toolbox" showcasing components and design tokens
 - **`:core-test`** - Shared testing utilities
 - **`:dokka-plugin`** - Custom Dokka plugin for documentation generation
 
@@ -70,8 +69,9 @@ OudsTheme(
 ### 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 values for each brand
+- **Theme Implementations** - Concrete semantic and component token values for each brand, as well as brand-specific raw tokens
 
 ### 3. Component Structure
 
@@ -80,41 +80,46 @@ Components follow a consistent pattern:
 - 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. **Kotlin Conventions**: Follow official Kotlin coding conventions
 2. **Compose Best Practices**: Use modern Jetpack Compose patterns
+1. **Coding Conventions**: Follow [Style guidelines for Jetpack Compose APIs](https://developer.android.com/develop/ui/compose/api-guidelines) which basically includes:
+   - The [API Guidelines for Jetpack Compose](https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/docs/compose-api-guidelines.md) (based on [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html))
+   - The [API Guidelines for @Composable components in Jetpack Compose](https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/docs/compose-component-api-guidelines.md)
 3. **Naming**: 
    - Prefix components with `Ouds` (e.g., `OudsTag`, `OudsButton`)
    - Token classes end with `Tokens` (e.g., `OudsAlertTokens`)
-   - Theme-related resources use `Ouds` prefix (e.g., `OudsDrawableResources`)
 
 ### 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/preview code in `:app/src/main/java/com/orange/ouds/app/ui/components/`
+- Demo app code in `:app/src/main/java/com/orange/ouds/app`
 
 ### Adding New Components
 
 When adding new components:
 
-1. Create the composable in `:core` module
-2. Define component tokens in `:theme-contract`
-3. Implement token values in theme modules (`:theme-orange`, etc.)
-4. Add demo screens in `:app` module
+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 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. Ensure accessibility semantics are properly implemented
+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
 
 ### 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
 
@@ -124,9 +129,8 @@ Demo screens use state classes (e.g., `AlertMessageDemoState`, `InlineAlertDemoS
 
 ## Testing
 
-- Unit tests for logic and state management
+- Snapshot tests for visual regression
 - Compose UI tests for component behavior
-- Visual regression testing (where applicable)
 - Accessibility testing should be considered
 
 ## Documentation
@@ -138,33 +142,27 @@ Demo screens use state classes (e.g., `AlertMessageDemoState`, `InlineAlertDemoS
 
 ## Common Tasks
 
-### Adding a New Theme Variant
+### Adding a New Theme
 
 1. Create new module (e.g., `:theme-newbrand`)
 2. Implement `OudsTheme` interface from `:theme-contract`
-3. Define all required token values
+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. Verify changes across all theme modules
+3. Update reference snapshots in all theme modules
 4. Update demo screens if needed
-5. Test in light and dark modes
-
-### Working with Tokens
-
-1. Raw tokens → `:global-raw-tokens`
-2. Component contracts → `:theme-contract/tokens/components/`
-3. Theme implementations → specific theme modules
 
 ## Build & Deploy
 
 - **Build**: `./gradlew build`
-- **Run app**: `./gradlew :app:installDebug`
-- **Tests**: `./gradlew test`
+- **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
@@ -173,6 +171,7 @@ Demo screens use state classes (e.g., `AlertMessageDemoState`, `InlineAlertDemoS
 
 Always consider that changes affect multiple brands. Test components with:
 - Orange theme
+- Orange Compact theme
 - Sosh theme
 - Wireframe theme
 - Light and dark modes
@@ -196,15 +195,6 @@ Always consider that changes affect multiple brands. Test components with:
 - Avoid unnecessary recompositions
 - Optimize preview rendering
 
-## Files to Watch
-
-Based on recent edits, key areas of active development:
-
-- **Alert Components**: `OudsAlertTokens`, demo states
-- **Tag Component**: `OudsTag.kt`
-- **Theme Resources**: `OudsDrawableResources.kt`
-- **Demo Infrastructure**: `ComponentCode.kt`, demo state classes
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
@@ -215,6 +205,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 - **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
 
@@ -224,5 +215,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 
 ---
 
-**Last Updated**: 2025
 **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.