Release v2.0.0

.claude/skills

@@ -0,0 +1 @@
+../.opencode/skills

.github/copilot-instructions.md

@@ -0,0 +1,270 @@
+# OUDS Flutter - GitHub Copilot Instructions
+
+This file provides guidance to GitHub Copilot when working on this repository.
+It covers contributor and maintainer guidelines: code formatting, architecture, build process, best practices, accessibility, development requirements, build commands and review guidelines.
+
+## Skills
+
+Load the appropriate skill before acting on the related task:
+
+| Task | Skill to load |
+|------|---------------|
+| Ask about or explain OUDS-specific terms (Tokenator, token, raw token, semantic token, component token, theme, …) | `ouds-flutter-vocabulary` |
+| Write or review Dart / Flutter code that uses OUDS components, themes or tokens | `ouds-flutter-framework-usage` |
+| Translate a Figma token name or token family into its Dart equivalent | `ouds-flutter-figma-to-dart` |
+| Migrate code between OUDS Flutter versions, adopt OUDS from native or custom Flutter components, or remove deprecated APIs | `ouds-flutter-migration-guide` |
+| Implement or review accessibility (Semantics, screen readers, text scale, high-contrast, orientation) | `ouds-flutter-accessibility` |
+
+Skills are located in `skills/<name>/SKILL.md` (treat this folder as the source of truth; keep the copies under `.claude/skills/` and `.opencode/skills/` in sync).
+## 1. Code formatting
+
+The source code is written in Dart and formatted with `dart format`. Linting is configured via `analysis_options.yaml` in each package using `package:flutter_lints/flutter.yaml`.
+
+Before any commit, run:
+```bash
+dart format .
+flutter analyze --no-pub
+```
+
+No `// ignore:` suppression is allowed unless strictly justified with an explanatory comment on the same line.
+
+## 2. Architecture details
+
+The repository is a multi-package Flutter workspace managed with `pub` (native Dart workspace, `pubspec.yaml` at root).
+
+### 2.1 Packages
+
+#### `ouds_core`
+
+Contains all reusable UI components (widgets) provided by OUDS Flutter: buttons, switches, checkboxes, chips, tags, links, badges, navigation bars, top bars, form inputs, etc.
+
+- Components are located in `ouds_core/lib/components/<name>/`
+- Each component class is prefixed with `Ouds` (e.g. `OudsButton`, `OudsTag`)
+- Every component reads visual values exclusively through the active theme tokens
+- Current component areas also include `alert/`, `bottom_sheet/`, `country_selector/`, `divider/`, `link/`, `navigation/`, `pin_code_input/`, `top_bar/`, and form inputs such as `ouds_phone_number_input.dart` and `password_input/ouds_password_input.dart`
+- `ouds_core` also contains reusable module screens under `ouds_core/lib/modules/` (currently `module-about/` and `module-more/`)
+
+#### `ouds_theme_contract`
+
+Defines the `OudsThemeContract` abstract interface, the `OudsTheme` `InheritedModel` widget, semantic token abstractions and component token interfaces.
+
+> ⚠️ Token interface files in this package are **generated by Tokenator** (Figma → Dart). Do not edit them manually.
+
+#### `ouds_theme_orange`
+
+Implements `OudsThemeContract` for all Orange brand products. Provides `OrangeTheme`.
+
+#### `ouds_theme_orange_compact`
+
+Implements `OudsThemeContract` for Orange products with tighter space and size constraints. Provides `OrangeCompactTheme`.
+
+#### `ouds_theme_sosh`
+
+Implements `OudsThemeContract` for all Sosh brand products. Provides `SoshTheme`.
+
+#### `ouds_theme_wireframe`
+
+Implements `OudsThemeContract` for prototyping and mockups. Provides `WireframeTheme`.
+
+#### `ouds_global_raw_tokens`
+
+Contains raw design token values (colors as hex, spacing as floats, typography sizes, etc.).
+
+> ⚠️ All files in this package are **generated by Tokenator** (Figma → Dart). Never edit them manually.
+
+#### `ouds_accessibility_plugin`
+
+Native plugin (Android + iOS) providing platform-level accessibility features: high-contrast detection, system font scale. Used internally by `OudsCheckbox`, `OudsSwitch`, `OudsRadioButton`.
+
+#### `app`
+
+Demo application "Design System Toolbox" showcasing all components and tokens interactively. Every component must have a corresponding demo screen registered in `app/lib/ui/components/components.dart`.
+
+### 2.2 Architecture guidelines
+
+- Flutter / Material 3 is the default UI paradigm — embrace its declarative and reactive nature
+- When creating a new component, try to match the equivalent Material 3 widget API as closely as possible
+- Avoid unnecessary abstractions and over-engineering
+- Focus on simplicity, clarity, and idiomatic Dart
+- Organize by component — keep related code together
+- Use extensions to organise large files
+- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart) naming conventions consistently
+- Use `sealed class` for exhaustive type modelling (e.g. `OudsIconStatus`)
+- Prefer `StatelessWidget` unless state is strictly necessary
+- Use `const` constructors wherever possible
+
+## 3. Build verification process ⚠️ CRITICAL
+
+**IMPORTANT**: When editing code, you MUST:
+1. Format the sources: `dart format .`
+2. Run static analysis: `flutter analyze --no-pub`
+3. Fix **all** errors and warnings before proceeding
+4. Run tests in every modified package: `flutter test`
+5. Check for dead code and remove unused imports, variables and methods
+
+## 4. Best practices
+
+### 4.1 DO
+
+- Write documentation in dartdoc format (`///`) for all public APIs, with at least one minimal code example
+- Use Dart's type system for safety — prefer strong types, avoid `dynamic`
+- Use `public` only when truly needed — prefer private (`_`) visibility
+- Apply **Clean Code, DRY, SOLID** and **TDD** principles
+- Use `const` constructors everywhere possible
+- Use `StatelessWidget` when state is not needed
+- Use `sealed class` / `enum` for exhaustive type modelling
+- Split large widgets into smaller private sub-widgets or methods
+- Use `final` fields in all widget classes
+- Use `static` for utility methods that do not need instance context
+- If a third-party dependency is added or updated, document it in `THIRD_PARTY.md`
+- Use `OudsTheme.of(context)` to read all colors, spacing, typography and component tokens
+- Use `OudsLocalizations.of(context)` or app localizations for user-facing strings
+  - When introducing breaking changes or API modifications, update `MIGRATION.md` at the root of the repository and `skills/ouds-flutter-migration-guide/SKILL.md` accordingly
+
+### 4.2 DON'T
+
+- Add abstraction layers without clear benefit
+- Use `dynamic` or `Object` unless strictly necessary
+- Perform heavy computation inside `build()` — move it to `initState`, a provider, or `compute()`
+- Call `setState` from `initState` — use `addPostFrameCallback` if needed
+- Mix business logic with UI code
+- Use `print()` — use `debugPrint` or a proper logging package
+- Hardcode colors, dimensions, or strings — always use tokens and localizations
+- Edit or create token files in `ouds_global_raw_tokens`, `ouds_theme_contract`, `ouds_theme_orange`, `ouds_theme_orange_compact`, `ouds_theme_sosh`, or `ouds_theme_wireframe`
+- Create a root barrel file for `ouds_core` — this repository imports components directly from `package:ouds_core/components/...`
+
+## 5. Accessibility basics 🔴 MANDATORY
+
+Everything is available on [Orange accessibility guidelines](https://a11y-guidelines.orange.com/fr/mobile/).
+
+> Load the **`ouds-flutter-accessibility`** skill for the full reference with code examples, Semantics patterns, high-contrast, TalkBack/VoiceOver and the complete testing checklist.
+
+### 5.1 Components
+
+- Wrap the root interactive element in a `Semantics` widget with appropriate flags (`button`, `checked`, `toggled`, `label`, `hint`, `value`)
+- Use `ExcludeSemantics` on purely decorative children
+- Use `MergeSemantics` to group related elements into a single focusable node when needed
+- Always provide a `semanticsLabel` parameter on components whose meaning is conveyed by color alone (e.g. `OudsBadge`)
+- Use `OudsLocalizations.of(context)` for all default accessibility strings — never hardcode them
+
+### 5.2 Display
+
+- Never lock text size — use OUDS typography tokens; never override `MediaQuery.textScalerOf`
+- Do not lock the app in portrait mode — support landscape orientation
+- Support high-contrast mode via `ouds_accessibility_plugin`
+- Test with TalkBack (Android) and VoiceOver (iOS)
+
+## 6. Development requirements
+
+- **Flutter**: `>= 3.35.0`
+- **Dart**: `>= 3.9.0`
+- **Minimum Android SDK**: API 21 (Android 5.0)
+- **Minimum iOS**: 13.0
+- **Android Studio** or **Xcode** for platform builds
+- A physical device or simulator/emulator for full accessibility testing (TalkBack on Android, VoiceOver on iOS)
+
+## 7. Building commands
+
+### 7.1 Install dependencies
+
+```bash
+flutter pub get
+(cd ouds_core && dart pub get)
+(cd app && flutter pub get)
+```
+
+If you modify ARB files in `app/lib/l10n/` or `ouds_core/lib/l10n/`, regenerate the generated localization files in the corresponding package:
+
+```bash
+(cd app && flutter gen-l10n)
+(cd ouds_core && flutter gen-l10n)
+```
+
+### 7.2 Run tests
+
+Run tests in each modified package that currently has a `test/` directory:
+
+```bash
+(cd app && flutter test)
+(cd ouds_core && flutter test)
+(cd ouds_global_raw_tokens && flutter test)
+(cd ouds_theme_contract && flutter test)
+(cd ouds_theme_orange && flutter test)
+(cd ouds_theme_sosh && flutter test)
+(cd ouds_theme_wireframe && flutter test)
+```
+
+At the time of writing, `ouds_theme_orange_compact` and `ouds_accessibility_plugin` do not contain a `test/` directory.
+
+### 7.3 Run static analysis
+
+```bash
+flutter analyze --no-pub
+```
+
+### 7.4 Format the sources
+
+```bash
+dart format .
+```
+
+### 7.5 Build documentation
+
+```bash
+cd ouds_core && dart doc
+```
+
+## 8. Review guidelines
+
+- [ ] Sources are formatted — `dart format .` produces no diff
+- [ ] `flutter analyze --no-pub` passes with zero errors and warnings
+- [ ] All tests pass — `flutter test` in every modified package
+- [ ] No dead code — leave a comment identifying any element that seems unused
+- [ ] Documentation builds without error — `dart doc` in `ouds_core` produces no error
+- [ ] No secrets or credentials committed (Gitleaks scan via `.github/workflows/gitleaks.yml`)
+- [ ] No function is too long or too complex — keep cyclomatic complexity low, split if needed
+- [ ] All commits are signed-off (DCO applied) by their authors
+- [ ] All new public APIs have dartdoc comments (`///`) with at least one code example
+- [ ] All new interactive widgets use `Semantics` with appropriate flags
+- [ ] No hardcoded colors, dimensions, or strings — tokens and localizations are used
+- [ ] Component tested visually with all 4 themes (Orange, Orange Compact, Sosh, Wireframe)
+- [ ] Component tested in light **and** dark mode
+- [ ] Demo screen added or updated in `app/lib/ui/components/<name>/`
+- [ ] Demo screen registered in `app/lib/ui/components/components.dart`
+- [ ] Commit message follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `doc:`, `chore:`, `test:`)
+- [ ] `MIGRATION.md` updated if any public API has changed or been deprecated
+- [ ] `skills/ouds-flutter-migration-guide/SKILL.md` updated to reflect any new migration steps
+
+## 9. Agent response optimization 🚀
+
+When using GitHub Copilot for code reviews, refactoring, or documentation updates, minimize token consumption:
+
+### Key principles
+
+- **Batch operations**: Combine multiple file edits into single calls; parallelize `grep_search` and `file_search`
+- **Skip verbose narrative**: Avoid acknowledgments and filler ("Sounds good!", "Let me now..."); use single-line summaries
+- **Compress output**: Use tables/checklists instead of prose; reference line numbers instead of repeating content
+- **Front-load context**: Gather all research upfront before proposing changes; use `run_subagent` for large searches
+- **Minimize reads**: Read files once with adequate ranges; use search filters to avoid irrelevant files
+
+### Response template (optimized)
+
+```
+**[Action summary — 1 line]**
+
+### Changes
+[Table or checklist of modifications]
+
+### Verification
+[Brief grep/status check results]
+```
+
+**Target**: 150–300 tokens per response (50–60% reduction vs. standard approach).
+
+### When to delegate to subagent
+
+Use `run_subagent` when:
+- Search scope involves 50+ files
+- Result set would exceed 500 tokens
+- Task requires multiple sequential searches
+

.github/workflows/dartdoc-gh-pages.yml

@@ -100,6 +100,7 @@ jobs:
         uses: ./.github/actions/setup
 
       - name: Setup Pages
+        if: github.event_name != 'pull_request'
         uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
 
       - name: Setup Ruby

.opencode/skills

@@ -0,0 +1 @@
+../skills

AGENTS.md

@@ -0,0 +1,52 @@
+| Property       | Value                      |
+|----------------|----------------------------|
+| type           | ai-agent-guide             |
+| framework      | OUDS-Flutter               |
+| language       | Dart                       |
+| ui-framework   | Flutter / Material 3       |
+| platforms      | Android, iOS               |
+| min-sdk        | Android API 21 / iOS 13    |
+
+# OUDS Flutter - AI Agent Guide
+
+OUDS (Orange Unified Design System) is a multi-package Flutter workspace providing design tokens, themes and Material 3 components for Orange Group products.
+The demo application is called "Design System Toolbox".
+The project is open source (MIT) at https://github.com/Orange-OpenSource/ouds-flutter.
+Target platforms: Android API 21+, iOS 13+. Language: Dart 3.9+ / Flutter 3.35+.
+
+## Skills
+
+Load skills on demand for detailed guidance:
+
+- **`ouds-flutter-vocabulary`** — glossary of OUDS Flutter-specific terms (Tokenator, token types, theme, …)
+- **`ouds-flutter-framework-usage`** — full OUDS Flutter usage reference: imports, themes, tokens, localizations, all components with code examples
+- **`ouds-flutter-figma-to-dart`** — how to derive Dart naming and token layer from Figma token families for the OUDS Flutter project (raw, semantic and component tokens)
+- **`ouds-flutter-migration-guide`** — adopt OUDS Flutter from native Flutter or custom components, migrate between OUDS Flutter versions, before/after mappings
+- **`ouds-flutter-accessibility`** — OUDS Flutter Semantics patterns, text scale, high-contrast, TalkBack / VoiceOver, orientation and full testing checklist
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Architecture, build commands, best practices, accessibility, review checklist |
+| `pubspec.yaml` | Workspace manifest — lists all packages |
+| `ouds_core/lib/components/` | All OUDS widgets (`OudsButton`, `OudsTag`, …) |
+| `ouds_theme_contract/lib/` | Abstract token interfaces — generated by Tokenator, never edit manually |
+| `app/lib/ui/components/components.dart` | Demo screen registry — register every new component here |
+| `MIGRATION.md` | Public API change log — update for every breaking change or deprecation |
+
+## Critical rules
+
+- Always load the **`ouds-flutter-vocabulary`** skill before discussing tokens or themes.
+- Always load the **`ouds-flutter-framework-usage`** skill before writing or reviewing code that uses OUDS components or tokens.
+- Always load the **`ouds-flutter-figma-to-dart`** skill when asked to find or map a Figma token name to its Dart equivalent.
+- Always load the **`ouds-flutter-migration-guide`** skill when asked to migrate code, adopt OUDS in an existing app, replace native/custom Flutter components with OUDS equivalents, or remove deprecated APIs.
+- Always load the **`ouds-flutter-accessibility`** skill when asked about Semantics, screen readers, TalkBack, VoiceOver, text scale, high-contrast or orientation.
+- Before committing: `dart format .` → `flutter analyze --no-pub` → fix all errors → `flutter test` in every modified package (see `.github/copilot-instructions.md §7`).
+- **Never** create or edit token files in `ouds_global_raw_tokens`, `ouds_theme_contract`, `ouds_theme_orange`, `ouds_theme_orange_compact`, `ouds_theme_sosh`, or `ouds_theme_wireframe` — all content is generated by Tokenator.
+- **Never** create a root barrel file for `ouds_core` — import components directly (e.g. `package:ouds_core/components/button/ouds_button.dart`).
+- When introducing a breaking change or deprecation: update **both** `MIGRATION.md` **and** `skills/ouds-flutter-migration-guide/SKILL.md`.
+- Use `OudsTheme.of(context)` for all colors, spacing, typography and component tokens — never hardcode values.
+- Use `OudsLocalizations.of(context)` for all user-facing and accessibility strings — never hardcode them.
+- Prefix all OUDS widgets with `Ouds` (e.g. `OudsButton`, `OudsTag`).
+- Every new interactive widget must wrap its root element in a `Semantics` widget with appropriate flags (`button`, `checked`, `toggled`, `label`, `hint`, `value`).