Skip to content

Commit b04d0f9

Browse files
AhmedAmineZrAhmedAmineZr
authored
feat(ai): Add agent.md to project (#668)(#669)
* feat(ai): Add agent.md to project * chore: update agent and add skills * review: apply Copilot review suggestions * chore: rename skills and add optimisation of agent
1 parent 748eeb3 commit b04d0f9

9 files changed

Lines changed: 2882 additions & 0 deletions

File tree

‎.claude/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.opencode/skills

‎.github/copilot-instructions.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# OUDS Flutter - GitHub Copilot Instructions
2+
3+
This file provides guidance to GitHub Copilot when working on this repository.
4+
It covers contributor and maintainer guidelines: code formatting, architecture, build process, best practices, accessibility, development requirements, build commands and review guidelines.
5+
6+
## Skills
7+
8+
Load the appropriate skill before acting on the related task:
9+
10+
| Task | Skill to load |
11+
|------|---------------|
12+
| Ask about or explain OUDS-specific terms (Tokenator, token, raw token, semantic token, component token, theme, …) | `ouds-flutter-vocabulary` |
13+
| Write or review Dart / Flutter code that uses OUDS components, themes or tokens | `ouds-flutter-framework-usage` |
14+
| Translate a Figma token name or token family into its Dart equivalent | `ouds-flutter-figma-to-dart` |
15+
| Migrate code between OUDS Flutter versions, adopt OUDS from native or custom Flutter components, or remove deprecated APIs | `ouds-flutter-migration-guide` |
16+
| Implement or review accessibility (Semantics, screen readers, text scale, high-contrast, orientation) | `ouds-flutter-accessibility` |
17+
18+
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).
19+
## 1. Code formatting
20+
21+
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`.
22+
23+
Before any commit, run:
24+
```bash
25+
dart format .
26+
flutter analyze --no-pub
27+
```
28+
29+
No `// ignore:` suppression is allowed unless strictly justified with an explanatory comment on the same line.
30+
31+
## 2. Architecture details
32+
33+
The repository is a multi-package Flutter workspace managed with `pub` (native Dart workspace, `pubspec.yaml` at root).
34+
35+
### 2.1 Packages
36+
37+
#### `ouds_core`
38+
39+
Contains all reusable UI components (widgets) provided by OUDS Flutter: buttons, switches, checkboxes, chips, tags, links, badges, navigation bars, top bars, form inputs, etc.
40+
41+
- Components are located in `ouds_core/lib/components/<name>/`
42+
- Each component class is prefixed with `Ouds` (e.g. `OudsButton`, `OudsTag`)
43+
- Every component reads visual values exclusively through the active theme tokens
44+
- 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`
45+
- `ouds_core` also contains reusable module screens under `ouds_core/lib/modules/` (currently `module-about/` and `module-more/`)
46+
47+
#### `ouds_theme_contract`
48+
49+
Defines the `OudsThemeContract` abstract interface, the `OudsTheme` `InheritedModel` widget, semantic token abstractions and component token interfaces.
50+
51+
> ⚠️ Token interface files in this package are **generated by Tokenator** (Figma → Dart). Do not edit them manually.
52+
53+
#### `ouds_theme_orange`
54+
55+
Implements `OudsThemeContract` for all Orange brand products. Provides `OrangeTheme`.
56+
57+
#### `ouds_theme_orange_compact`
58+
59+
Implements `OudsThemeContract` for Orange products with tighter space and size constraints. Provides `OrangeCompactTheme`.
60+
61+
#### `ouds_theme_sosh`
62+
63+
Implements `OudsThemeContract` for all Sosh brand products. Provides `SoshTheme`.
64+
65+
#### `ouds_theme_wireframe`
66+
67+
Implements `OudsThemeContract` for prototyping and mockups. Provides `WireframeTheme`.
68+
69+
#### `ouds_global_raw_tokens`
70+
71+
Contains raw design token values (colors as hex, spacing as floats, typography sizes, etc.).
72+
73+
> ⚠️ All files in this package are **generated by Tokenator** (Figma → Dart). Never edit them manually.
74+
75+
#### `ouds_accessibility_plugin`
76+
77+
Native plugin (Android + iOS) providing platform-level accessibility features: high-contrast detection, system font scale. Used internally by `OudsCheckbox`, `OudsSwitch`, `OudsRadioButton`.
78+
79+
#### `app`
80+
81+
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`.
82+
83+
### 2.2 Architecture guidelines
84+
85+
- Flutter / Material 3 is the default UI paradigm — embrace its declarative and reactive nature
86+
- When creating a new component, try to match the equivalent Material 3 widget API as closely as possible
87+
- Avoid unnecessary abstractions and over-engineering
88+
- Focus on simplicity, clarity, and idiomatic Dart
89+
- Organize by component — keep related code together
90+
- Use extensions to organise large files
91+
- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart) naming conventions consistently
92+
- Use `sealed class` for exhaustive type modelling (e.g. `OudsIconStatus`)
93+
- Prefer `StatelessWidget` unless state is strictly necessary
94+
- Use `const` constructors wherever possible
95+
96+
## 3. Build verification process ⚠️ CRITICAL
97+
98+
**IMPORTANT**: When editing code, you MUST:
99+
1. Format the sources: `dart format .`
100+
2. Run static analysis: `flutter analyze --no-pub`
101+
3. Fix **all** errors and warnings before proceeding
102+
4. Run tests in every modified package: `flutter test`
103+
5. Check for dead code and remove unused imports, variables and methods
104+
105+
## 4. Best practices
106+
107+
### 4.1 DO
108+
109+
- Write documentation in dartdoc format (`///`) for all public APIs, with at least one minimal code example
110+
- Use Dart's type system for safety — prefer strong types, avoid `dynamic`
111+
- Use `public` only when truly needed — prefer private (`_`) visibility
112+
- Apply **Clean Code, DRY, SOLID** and **TDD** principles
113+
- Use `const` constructors everywhere possible
114+
- Use `StatelessWidget` when state is not needed
115+
- Use `sealed class` / `enum` for exhaustive type modelling
116+
- Split large widgets into smaller private sub-widgets or methods
117+
- Use `final` fields in all widget classes
118+
- Use `static` for utility methods that do not need instance context
119+
- If a third-party dependency is added or updated, document it in `THIRD_PARTY.md`
120+
- Use `OudsTheme.of(context)` to read all colors, spacing, typography and component tokens
121+
- Use `OudsLocalizations.of(context)` or app localizations for user-facing strings
122+
- 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
123+
124+
### 4.2 DON'T
125+
126+
- Add abstraction layers without clear benefit
127+
- Use `dynamic` or `Object` unless strictly necessary
128+
- Perform heavy computation inside `build()` — move it to `initState`, a provider, or `compute()`
129+
- Call `setState` from `initState` — use `addPostFrameCallback` if needed
130+
- Mix business logic with UI code
131+
- Use `print()` — use `debugPrint` or a proper logging package
132+
- Hardcode colors, dimensions, or strings — always use tokens and localizations
133+
- 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`
134+
- Create a root barrel file for `ouds_core` — this repository imports components directly from `package:ouds_core/components/...`
135+
136+
## 5. Accessibility basics 🔴 MANDATORY
137+
138+
Everything is available on [Orange accessibility guidelines](https://a11y-guidelines.orange.com/fr/mobile/).
139+
140+
> Load the **`ouds-flutter-accessibility`** skill for the full reference with code examples, Semantics patterns, high-contrast, TalkBack/VoiceOver and the complete testing checklist.
141+
142+
### 5.1 Components
143+
144+
- Wrap the root interactive element in a `Semantics` widget with appropriate flags (`button`, `checked`, `toggled`, `label`, `hint`, `value`)
145+
- Use `ExcludeSemantics` on purely decorative children
146+
- Use `MergeSemantics` to group related elements into a single focusable node when needed
147+
- Always provide a `semanticsLabel` parameter on components whose meaning is conveyed by color alone (e.g. `OudsBadge`)
148+
- Use `OudsLocalizations.of(context)` for all default accessibility strings — never hardcode them
149+
150+
### 5.2 Display
151+
152+
- Never lock text size — use OUDS typography tokens; never override `MediaQuery.textScalerOf`
153+
- Do not lock the app in portrait mode — support landscape orientation
154+
- Support high-contrast mode via `ouds_accessibility_plugin`
155+
- Test with TalkBack (Android) and VoiceOver (iOS)
156+
157+
## 6. Development requirements
158+
159+
- **Flutter**: `>= 3.35.0`
160+
- **Dart**: `>= 3.9.0`
161+
- **Minimum Android SDK**: API 21 (Android 5.0)
162+
- **Minimum iOS**: 13.0
163+
- **Android Studio** or **Xcode** for platform builds
164+
- A physical device or simulator/emulator for full accessibility testing (TalkBack on Android, VoiceOver on iOS)
165+
166+
## 7. Building commands
167+
168+
### 7.1 Install dependencies
169+
170+
```bash
171+
flutter pub get
172+
(cd ouds_core && dart pub get)
173+
(cd app && flutter pub get)
174+
```
175+
176+
If you modify ARB files in `app/lib/l10n/` or `ouds_core/lib/l10n/`, regenerate the generated localization files in the corresponding package:
177+
178+
```bash
179+
(cd app && flutter gen-l10n)
180+
(cd ouds_core && flutter gen-l10n)
181+
```
182+
183+
### 7.2 Run tests
184+
185+
Run tests in each modified package that currently has a `test/` directory:
186+
187+
```bash
188+
(cd app && flutter test)
189+
(cd ouds_core && flutter test)
190+
(cd ouds_global_raw_tokens && flutter test)
191+
(cd ouds_theme_contract && flutter test)
192+
(cd ouds_theme_orange && flutter test)
193+
(cd ouds_theme_sosh && flutter test)
194+
(cd ouds_theme_wireframe && flutter test)
195+
```
196+
197+
At the time of writing, `ouds_theme_orange_compact` and `ouds_accessibility_plugin` do not contain a `test/` directory.
198+
199+
### 7.3 Run static analysis
200+
201+
```bash
202+
flutter analyze --no-pub
203+
```
204+
205+
### 7.4 Format the sources
206+
207+
```bash
208+
dart format .
209+
```
210+
211+
### 7.5 Build documentation
212+
213+
```bash
214+
cd ouds_core && dart doc
215+
```
216+
217+
## 8. Review guidelines
218+
219+
- [ ] Sources are formatted — `dart format .` produces no diff
220+
- [ ] `flutter analyze --no-pub` passes with zero errors and warnings
221+
- [ ] All tests pass — `flutter test` in every modified package
222+
- [ ] No dead code — leave a comment identifying any element that seems unused
223+
- [ ] Documentation builds without error — `dart doc` in `ouds_core` produces no error
224+
- [ ] No secrets or credentials committed (Gitleaks scan via `.github/workflows/gitleaks.yml`)
225+
- [ ] No function is too long or too complex — keep cyclomatic complexity low, split if needed
226+
- [ ] All commits are signed-off (DCO applied) by their authors
227+
- [ ] All new public APIs have dartdoc comments (`///`) with at least one code example
228+
- [ ] All new interactive widgets use `Semantics` with appropriate flags
229+
- [ ] No hardcoded colors, dimensions, or strings — tokens and localizations are used
230+
- [ ] Component tested visually with all 4 themes (Orange, Orange Compact, Sosh, Wireframe)
231+
- [ ] Component tested in light **and** dark mode
232+
- [ ] Demo screen added or updated in `app/lib/ui/components/<name>/`
233+
- [ ] Demo screen registered in `app/lib/ui/components/components.dart`
234+
- [ ] Commit message follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `doc:`, `chore:`, `test:`)
235+
- [ ] `MIGRATION.md` updated if any public API has changed or been deprecated
236+
- [ ] `skills/ouds-flutter-migration-guide/SKILL.md` updated to reflect any new migration steps
237+
238+
## 9. Agent response optimization 🚀
239+
240+
When using GitHub Copilot for code reviews, refactoring, or documentation updates, minimize token consumption:
241+
242+
### Key principles
243+
244+
- **Batch operations**: Combine multiple file edits into single calls; parallelize `grep_search` and `file_search`
245+
- **Skip verbose narrative**: Avoid acknowledgments and filler ("Sounds good!", "Let me now..."); use single-line summaries
246+
- **Compress output**: Use tables/checklists instead of prose; reference line numbers instead of repeating content
247+
- **Front-load context**: Gather all research upfront before proposing changes; use `run_subagent` for large searches
248+
- **Minimize reads**: Read files once with adequate ranges; use search filters to avoid irrelevant files
249+
250+
### Response template (optimized)
251+
252+
```
253+
**[Action summary — 1 line]**
254+
255+
### Changes
256+
[Table or checklist of modifications]
257+
258+
### Verification
259+
[Brief grep/status check results]
260+
```
261+
262+
**Target**: 150–300 tokens per response (50–60% reduction vs. standard approach).
263+
264+
### When to delegate to subagent
265+
266+
Use `run_subagent` when:
267+
- Search scope involves 50+ files
268+
- Result set would exceed 500 tokens
269+
- Task requires multiple sequential searches
270+

‎.opencode/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../skills

‎AGENTS.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
| Property | Value |
2+
|----------------|----------------------------|
3+
| type | ai-agent-guide |
4+
| framework | OUDS-Flutter |
5+
| language | Dart |
6+
| ui-framework | Flutter / Material 3 |
7+
| platforms | Android, iOS |
8+
| min-sdk | Android API 21 / iOS 13 |
9+
10+
# OUDS Flutter - AI Agent Guide
11+
12+
OUDS (Orange Unified Design System) is a multi-package Flutter workspace providing design tokens, themes and Material 3 components for Orange Group products.
13+
The demo application is called "Design System Toolbox".
14+
The project is open source (MIT) at https://github.com/Orange-OpenSource/ouds-flutter.
15+
Target platforms: Android API 21+, iOS 13+. Language: Dart 3.9+ / Flutter 3.35+.
16+
17+
## Skills
18+
19+
Load skills on demand for detailed guidance:
20+
21+
- **`ouds-flutter-vocabulary`** — glossary of OUDS Flutter-specific terms (Tokenator, token types, theme, …)
22+
- **`ouds-flutter-framework-usage`** — full OUDS Flutter usage reference: imports, themes, tokens, localizations, all components with code examples
23+
- **`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)
24+
- **`ouds-flutter-migration-guide`** — adopt OUDS Flutter from native Flutter or custom components, migrate between OUDS Flutter versions, before/after mappings
25+
- **`ouds-flutter-accessibility`** — OUDS Flutter Semantics patterns, text scale, high-contrast, TalkBack / VoiceOver, orientation and full testing checklist
26+
27+
## Key files
28+
29+
| File | Purpose |
30+
|------|---------|
31+
| `.github/copilot-instructions.md` | Architecture, build commands, best practices, accessibility, review checklist |
32+
| `pubspec.yaml` | Workspace manifest — lists all packages |
33+
| `ouds_core/lib/components/` | All OUDS widgets (`OudsButton`, `OudsTag`, …) |
34+
| `ouds_theme_contract/lib/` | Abstract token interfaces — generated by Tokenator, never edit manually |
35+
| `app/lib/ui/components/components.dart` | Demo screen registry — register every new component here |
36+
| `MIGRATION.md` | Public API change log — update for every breaking change or deprecation |
37+
38+
## Critical rules
39+
40+
- Always load the **`ouds-flutter-vocabulary`** skill before discussing tokens or themes.
41+
- Always load the **`ouds-flutter-framework-usage`** skill before writing or reviewing code that uses OUDS components or tokens.
42+
- Always load the **`ouds-flutter-figma-to-dart`** skill when asked to find or map a Figma token name to its Dart equivalent.
43+
- 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.
44+
- Always load the **`ouds-flutter-accessibility`** skill when asked about Semantics, screen readers, TalkBack, VoiceOver, text scale, high-contrast or orientation.
45+
- Before committing: `dart format .` → `flutter analyze --no-pub` → fix all errors → `flutter test` in every modified package (see `.github/copilot-instructions.md §7`).
46+
- **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.
47+
- **Never** create a root barrel file for `ouds_core` — import components directly (e.g. `package:ouds_core/components/button/ouds_button.dart`).
48+
- When introducing a breaking change or deprecation: update **both** `MIGRATION.md` **and** `skills/ouds-flutter-migration-guide/SKILL.md`.
49+
- Use `OudsTheme.of(context)` for all colors, spacing, typography and component tokens — never hardcode values.
50+
- Use `OudsLocalizations.of(context)` for all user-facing and accessibility strings — never hardcode them.
51+
- Prefix all OUDS widgets with `Ouds` (e.g. `OudsButton`, `OudsTag`).
52+
- Every new interactive widget must wrap its root element in a `Semantics` widget with appropriate flags (`button`, `checked`, `toggled`, `label`, `hint`, `value`).

0 commit comments

Comments
 (0)