chore(doc): update readme & contributing doc

CONTRIBUTING.md

@@ -1,29 +1,205 @@
 # Contributing to ODS project
 
-This project accepts contributions. In order to contribute, you should
-pay attention to a few things:
+OVHcloud Design System is an evolving project, and we welcome contributions from the community.
+By keeping our repository open source, we aim to make it easier for anyone to suggest improvements, fix issues, or share ideas.
 
-1. your code must follow the coding style rules
-2. your code must be unit-tested
-3. your code must be documented
-4. your work must be signed (see below)
-5. you may contribute through GitHub Pull Requests
+Whether it’s a small fix or a new feature, every contribution helps improve the quality and usability of the system.
+We appreciate the time and effort of anyone who chooses to take part.
 
-# Coding and documentation Style
-* Code must pass `yarn test`, and therefore the `build` and `step` step in CI to be considered as a valid contribution.
+Please note that while we welcome contributions, we encourage you to discuss major changes with our team to ensure alignment with the project's goals and overall quality.
+Additionally, if you're interested in proposing a new feature, please reach us out first to avoid duplicating effort, as we may already be working on a similar development.
 
-# Submitting Modifications
-The contributions should be submitted through Github Pull Requests
-and follow the DCO which is defined below.
+## Project installation
+
+### Pre-requisites
+
+- [Node.js](https://nodejs.org/) >= 22
+- [Yarn](https://yarnpkg.com/) >= 2.4.0
+- [Chrome browser](https://www.google.com/intl/fr_fr/chrome/) locally installed (if you need to run the [lighthouse](https://github.com/GoogleChrome/lighthouse#readme) tests)
+
+### Building the project
+
+1. Fork the ODS repository.
+2. Clone your new repository.
+3. At the root of the repository, run the following commands:
+
+```shell
+# Install the dependencies and link the monorepo.
+yarn
+
+# Build the different packages.
+yarn build:prod
+```
+
+### Running the documentation locally
+
+At the root of the repository, run the following commands:
+
+```shell
+# Generate all the needed documentation files.
+yarn doc
+
+# Start the storybook local server.
+yarn storybook
+```
+
+## Project architecture
+
+ODS is a monorepo project split into multiple sub-projects under the `/packages` directory:
+- `examples` regroups example projects to test some specific behavior (a11y, SSR, bundlers, ...).
+- `ods-react` contains the React implementation of the component library.
+- `storybook` is the public documentation.
+- `themes` regroups all the existing ODS themes and the design assets (fonts, design tokens, ...).
+
+## Creating a new component
+
+To create a new component, run the following command at the root of the repository and follow the prompt:
+
+```shell
+yarn new:component
+```
+
+This will generate all the component resources and the documentation files in the storybook package.
+
+## Working on an existing component
+
+Each component can be run as an autonomous project, so you don't have to build the whole package each time.
+
+All the following implies that you're under the `/packages/ods-react/src/components/<component-name>` directory.
+
+### Component directory overview
+
+All files/directories not detailed underneath should **NOT** be updated and can be ignored.
+
+```text
+src/
+  components/
+    <component-name>/
+      <componentName>.scss (only if the component need specific style)
+      <ComponentName>.tsx
+  contexts/ (if needed)
+    use<...>.tsx
+  controller/ (if needed)
+    <...>.tsx
+tests/
+  behavior/ (if needed)
+    <component-name>.e2e.ts
+    <component>.stories.tsx
+  controller/ (if needed)
+    <...>.spec.ts
+  rendering/
+    <component-name>.e2e.ts
+    <component>.stories.tsx
+```
+
+### Dev server
+
+To test how the component renders and behaves, we run a dedicated minimal Storybook that executes all the stories
+defined in the src/dev.stories.tsx file.
+
+To start the server, run:
+```shell
+yarn start
+```
+
+You can add as many stories as needed to help you handle all the use cases of the component.
+
+Please keep in mind that those stories are for dev purposes only; they do not replace actual unit or E2E tests.
+
+### Linters
+
+When you're done, ensure that your codebase follows the linter rules by running:
+
+```shell
+yarn lint:ts
+yarn lint:scss
+```
+
+Fix the potential errors, warnings until all commands passes.
+
+### Unit tests
+
+Ensure all functions you add (usually grouped in the controller files) are covered by unit tests.
+
+When you're done, ensure that your tests still pass by running:
+```shell
+yarn test:spec
+```
+
+### E2e tests
+
+Ensure all rendering/behaviour changes added to the component are covered by e2e tests.
+
+When you're done, ensure that your tests still pass by running:
+```shell
+yarn test:e2e
+```
+
+### Updating the style
+
+ODS uses [Sass](https://sass-lang.com/) and follows the [BEM](https://getbem.com/) convention.
+
+When adding/updating style, please ensure that:
+- a component only refers to style defined in its matching scss file.
+- the BEM convention is followed.
+
+If you need to reuse generic style or style from other components (like focus, disabled state, ...),
+you can include common mixins defined in the `style` directory.
+
+## Updating documentation
+
+When you're done with the component and all the above pre-requisites, you may have to
+update the documentation accordingly, depending on the changes.
+
+### Storybook directory overview
+
+All files/directory not detailed underneath should **NOT** be updated and can be ignored.
+
+```text
+src/
+  <contains custom React components used internally by our storybook>
+stories/
+  components/
+    <component-name>/
+      <component-name>.stories.tsx
+      documentation.mdx
+      technical-information.mdx
+  ovhcloud-design-system/
+    <contains more generic information about the whole library>
+```
+
+If some of your changes impacts how the component behave (in a functional way), please update its `documentation.mdx` file accordingly.
+
+If some of your changes impacts the technical side of the component:
+- check that the generated interfaces/definitions are correct (run `yarn doc` at the root to get the latest data).
+- if relevant, add some stories in the `<component-name>.stories.tsx` file, then reference them in the `technical-information.mdx` file.
+
+If you've updated the attributes list of a component, check that the `Demo` page controls are still relevant.
+
+# Code submission
+
+The contributions should be submitted through Github Pull Requests and follow the DCO defined below.
+
+Before submitting your Pull Request:
+
+- make sure all commit messages follows the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) rules
+- make sure all commits are [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
+- ensure all the following commands succeed (run at the root of the project):
+
+```shell
+yarn lint
+yarn test:spec:ci
+yarn test:e2e:ci
+```
 
 # Licensing for new files
+
 ODS is licensed under a Apache 2 license. Anything
 contributed to ODS must be released under this license.
 
-When introducing a new file into the project, please make sure it has a
-copyright header making clear under which license it's being released.
-
 # Developer Certificate of Origin (DCO)
+
+```
 To improve tracking of contributions to this project we will use a
 process modeled on the modified DCO 1.1 and use a "sign-off" procedure
 on patches that are being emailed around or contributed in any other
@@ -64,6 +240,4 @@ then you just add a line saying
     Signed-off-by: Random J Developer <random@example.org>
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
-
-Please find all the documentation about contributions in the directory `packages/contributing`.
-You can start with the Getting Started in `packages/contributing/contributing-getting-started.mdx`.
+```

README.md

@@ -8,15 +8,15 @@
 ### A collection of assets and guidelines for building consistent user experiences across OVHCloud products.
 
 [![NPM version][npm-image]][npm-url] [![License](https://img.shields.io/badge/Licence-Apache%202.0-blue.svg)](./LICENSE.md) [![Last commit][last-commit-image]][last-commit-url]\
-[![StencilJS][stenciljs-image]][stenciljs-url] [![TypeScript][typescript-image]][typescript-url] [![Sass][sass-image]][sass-url]\
+[![React][react-image]][react-url] [![TypeScript][typescript-image]][typescript-url] [![Sass][sass-image]][sass-url]\
 [![Storybook][storybook-image]][storybook-url] [![Jest][jest-image]][jest-url] [![Puppeteer][puppeteer-image]][puppeteer-url]
 
 [npm-image]: https://img.shields.io/badge/-NPM-A00709?logo=npm&logoColor=white
-[npm-url]: https://www.npmjs.com/package/@ovhcloud/ods-components
+[npm-url]: https://www.npmjs.com/package/@ovhcloud/ods-react
 [last-commit-image]: https://img.shields.io/github/last-commit/ovh/design-system
 [last-commit-url]: https://github.com/ovh/design-system/commits
-[stenciljs-image]: https://img.shields.io/badge/-StencilJS-000?logo=webcomponents.org&logoColor=white
-[stenciljs-url]: https://stenciljs.com/
+[react-image]: https://img.shields.io/badge/React-%2320232a.svg?logo=react&logoColor=%2361DAFB
+[react-url]: https://fr.react.dev/
 [typescript-image]: https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white
 [typescript-url]: https://www.typescriptlang.org/
 [sass-image]: https://img.shields.io/badge/-Sass-CC6699?logo=sass&logoColor=white
@@ -32,21 +32,16 @@
 
 ## Quick links
 
-* [**Storybook**](https://ovh.github.io/design-system/latest/)
+* [**Documentation**](https://ovh.github.io/design-system/latest/)
 * [**What's new**](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-what-s-new--docs)
 * [**Changelog**](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-changelog--docs)
+* [**FAQ**](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-f-a-q--docs)
 
 ## Installation & Usage
 Feel free to check out the [Get Started](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-get-started--docs) guide which describes everything you need to use ODS in your project.
 
 ## Migration
-Please read [Migration pages](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-migration-guide-17-x-to-18-x--docs) to help you to manage the migration guides between each version of ODS.
-
-# Related links
-* Migrate from one version to another: [https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-migration-guide-17-x-to-18-x--docs](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-migration-guide-17-x-to-18-x--docs)
-* Troubleshoot dev issues: [https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-f-a-q--docs](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-f-a-q--docs)
-* Report bugs: [https://github.com/ovh/design-system/issues](https://github.com/ovh/design-system/issues)
-* Get latest version: [https://github.com/ovh/design-system](https://github.com/ovh/design-system)
+Please read [Migration pages](https://ovh.github.io/design-system/latest/?path=/docs/ovhcloud-design-system-what-s-new-migration-guide-to-19-x--docs) to help you to manage the migration guides between each version of ODS.
 
 # License
 Copyright 2024 OVH SAS

packages/storybook/stories/ovhcloud-design-system/faq.mdx

@@ -12,6 +12,19 @@ import { HOME_TITLE } from '../../src/constants/meta';
 
 *Here, we aim to address common questions and provide helpful guidance for developers.*
 
+<Heading label="How can I contribute?" level={ 2 } />
+
+OVHcloud Design System is an evolving project, and we welcome contributions from the community.
+By keeping our repository open source, we aim to make it easier for anyone to suggest improvements, fix issues, or share ideas.
+
+Whether it’s a small fix or a new feature, every contribution helps improve the quality and usability of the system.
+We appreciate the time and effort of anyone who chooses to take part.
+
+Please note that while we welcome contributions, we encourage you to discuss major changes with our team to ensure alignment with the project's goals and overall quality.
+Additionally, if you're interested in proposing a new feature, please reach us out first to avoid duplicating effort, as we may already be working on a similar development.
+
+Refer to our project <ExternalLink href="https://github.com/ovh/design-system?tab=contributing-ov-file#contributing-to-ods-project">README</ExternalLink> to learn more about installation and pre-requisites.
+
 <Heading label="I can't find a component I need" level={ 2 } />
 
 ODS provides base components that you can build on top of and implement in various contexts.