[OUDS] feat(docs): Add the bi-mode page#3216
Conversation
84e6ae9 to
1cc9704
Compare
MaxLardenois
left a comment
There was a problem hiding this comment.
First pass with some suggestions
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Preamble | ||
|
|
||
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. |
There was a problem hiding this comment.
just a suggestion
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. | |
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It also works as a tutorial to implement OUDS Web gradually inside your website. Be careful, we will support this in a "best-effort" way; this feature is supposed to be mainly used by selected projects. If you’re not, please contact us so we can help you. |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Example of integration | ||
|
|
||
| If you want to see the kind of changes and the amount of changes it might require on your side by watching it in action in the [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files). Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. |
There was a problem hiding this comment.
| If you want to see the kind of changes and the amount of changes it might require on your side by watching it in action in the [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files). Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. | |
| You can check this [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files) update to see what it would entail on your side in terms of changes. Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. |
site/src/content/docs/bi-mode.mdx
Outdated
| Here is a non exhaustive list of disadvantages of using this bi-mode: | ||
| - There might be some unwanted side and edge effects that we didn’t anticipate. | ||
| - It implies a change of design, so be in touch with your designer(s). | ||
| - It implies a mix of two brands that doesn’t coexist well. |
There was a problem hiding this comment.
| - It implies a mix of two brands that doesn’t coexist well. | |
| - It implies a mix of two brands that might sometimes clash. |
site/src/content/docs/bi-mode.mdx
Outdated
| - You gain time for the future since you are migrating to OUDS Web little by little. | ||
| - You will be in advance compared to others projects in terms of design system. | ||
| - You will more likely have only few changes to do to integrate components one by one. | ||
| - No more issues about dark mode. |
There was a problem hiding this comment.
| - No more issues about dark mode. | |
| - No more issues with dark mode. |
site/src/content/docs/bi-mode.mdx
Outdated
| - You will be in advance compared to others projects in terms of design system. | ||
| - You will more likely have only few changes to do to integrate components one by one. | ||
| - No more issues about dark mode. | ||
| - Easier releases, so you won’t have to wait long until something’s corrected. |
There was a problem hiding this comment.
| - Easier releases, so you won’t have to wait long until something’s corrected. | |
| - Easier releases, so you won’t have to wait as long until something’s corrected. |
site/src/content/docs/bi-mode.mdx
Outdated
| **This is the recommended scenario.** | ||
| </Callout> | ||
|
|
||
| In this scenario, you will have access, use all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the blanks using Boosted and custom CSS. |
There was a problem hiding this comment.
| In this scenario, you will have access, use all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the blanks using Boosted and custom CSS. | |
| In this scenario, you will have access to all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the missing parts using Boosted and custom CSS. |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| In this scenario, you will have access, use all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the blanks using Boosted and custom CSS. | ||
|
|
||
| 1. Make sure to install `sass`, and `boosted`. You’ll also need a theme, and this tutorial assumes it will be the Orange theme. |
There was a problem hiding this comment.
| 1. Make sure to install `sass`, and `boosted`. You’ll also need a theme, and this tutorial assumes it will be the Orange theme. | |
| 1. Make sure to install `sass`, and `boosted`. You’ll also need a theme, in this tutorial we assume it will be the Orange theme. |
site/src/content/docs/bi-mode.mdx
Outdated
| @import "boosted/scss/offcanvas"; | ||
| @import "boosted/scss/placeholders"; | ||
|
|
||
| // Boosted |
There was a problem hiding this comment.
This is Boosted specific whereas before it's from bootstrap? We should be more clear if so
There was a problem hiding this comment.
Tried something.
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| 3. Once your all set, you can begin to follow [our migration guide from Boosted]([[docsref:/migrations/migration-from-boosted]]). | ||
|
|
||
| 4. Sometimes, we provide only a partial support of what was done before. Since the goal of OUDS is to support all the previous components or at least give an alternative. For example, the [Boosted social buttons](https://boosted.orange.com/docs/5.3/components/buttons/#social-buttons) aren’t yet developed, so you need to copy paste the code if you use it in your code. |
There was a problem hiding this comment.
I'm not sure I get the point of this paragraph
| 4. Sometimes, we provide only a partial support of what was done before. Since the goal of OUDS is to support all the previous components or at least give an alternative. For example, the [Boosted social buttons](https://boosted.orange.com/docs/5.3/components/buttons/#social-buttons) aren’t yet developed, so you need to copy paste the code if you use it in your code. | |
| 4. Sometimes, we provide only a partial support of what was done before. But rest assured the goal of OUDS is to support all the previous components or at least give an alternative. For example, the [Boosted social buttons](https://boosted.orange.com/docs/5.3/components/buttons/#social-buttons) aren’t yet developed, so you need to copy paste the code if you use it in your code. |
There was a problem hiding this comment.
The main goal of this paragraph is to explain how and when to introduce Boosted components
site/src/content/docs/bi-mode.mdx
Outdated
| ## Preamble | ||
|
|
||
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. | ||
| This page is not to be used alone, but is complementary to [OUDS Web documenation](https://web.unified-design-system.orange.com/) and [Boosted documentation](https://boosted.orange.com/). |
There was a problem hiding this comment.
| This page is not to be used alone, but is complementary to [OUDS Web documenation](https://web.unified-design-system.orange.com/) and [Boosted documentation](https://boosted.orange.com/). | |
| This page is not to be used alone, but is complementary to [OUDS Web documentation](https://web.unified-design-system.orange.com/) and [Boosted documentation](https://boosted.orange.com/). |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Preamble | ||
|
|
||
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. |
There was a problem hiding this comment.
I would have presented the bi-mode as a way to gradually and early migrate to OUDS for a Boosted project.
What about OB1? Did we test it?
There was a problem hiding this comment.
We didn't test ob1 I guess, but it should behave the same, apart from the custom import.
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Preamble | ||
|
|
||
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. |
There was a problem hiding this comment.
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It’s also a tutorial to implement OUDS Web gradually inside your website. Be careful, we don’t support it too much and this feature is supposed to be used only by the selected projects. If you’re not, please contact us so we can maybe help you. | |
| Bi-mode is a way to early and gradually migrate a Boosted project to OUDS. | |
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It also works as a tutorial to implement OUDS Web gradually inside your website. Be careful, we will support this in a "best-effort" way; this feature is supposed to be used only by pre-selected projects. If you would like assistance, please contact us. |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Example of integration | ||
|
|
||
| If you want to see the kind of changes and the amount of changes it might require on your side by watching it in action in the [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files). Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. |
There was a problem hiding this comment.
| If you want to see the kind of changes and the amount of changes it might require on your side by watching it in action in the [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files). Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. | |
| You can check the [example of bi-mode on ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files) to see what kind of changes, and how much work it would be required on your side. Be aware that the ODS Charts project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. |
|
|
||
| If you want to see the kind of changes and the amount of changes it might require on your side by watching it in action in the [ODS Charts project](https://github.com/Orange-OpenSource/ods-charts/pull/673/files). Be aware that this project remains very simple due to the used technology, and that only few pages were done in this example just to test different configurations. | ||
|
|
||
| ## Cons |
There was a problem hiding this comment.
Is the idea to start with the disadvantages to discourage the projects?
There was a problem hiding this comment.
I just wanted them to be aware of the nightmare they are entering in 😄
site/src/content/docs/bi-mode.mdx
Outdated
| Here is a small list of what to do once, you’re all set, you should check once a week if there isn’t a new OUDS Web release. | ||
| - If not, you can stop here and enjoy a week without release. | ||
| - If yes, follow [our migration guide]([[docsref:/migration]]). The main changes can be: | ||
| - Already existing components to update in your code. | ||
| - New components, so update your code with the new ones, remove the newly useless import(s) from Boosted custom import stack or from the custom Boosted backports. |
There was a problem hiding this comment.
| Here is a small list of what to do once, you’re all set, you should check once a week if there isn’t a new OUDS Web release. | |
| - If not, you can stop here and enjoy a week without release. | |
| - If yes, follow [our migration guide]([[docsref:/migration]]). The main changes can be: | |
| - Already existing components to update in your code. | |
| - New components, so update your code with the new ones, remove the newly useless import(s) from Boosted custom import stack or from the custom Boosted backports. | |
| Once you’re all set, you should check once a month if there isn’t a new OUDS Web release. | |
| - If not, you can stop here and enjoy a month without release. | |
| - If yes, follow [our migration guide]([[docsref:/migration]]). The main changes can be: | |
| - Already existing components to update in your code. | |
| - New components, so update your code with the new ones, remove the newly useless import(s) from Boosted custom import stack or from the custom Boosted backports. |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| ## Good practices | ||
|
|
||
| Here is a non-exhaustive list for the good practices once you’re all set: |
There was a problem hiding this comment.
| Here is a non-exhaustive list for the good practices once you’re all set: | |
| Here is a non-exhaustive list of best practices to adopt once you’re all set: |
site/src/content/docs/bi-mode.mdx
Outdated
| - Have two separate custom stylesheets, one with the style that will be included in OUDS Web, and one that is very specific to your project. | ||
| - Keep up to date with the latest OUDS Web version, add the newly added components, remove dead code from your stylesheets. | ||
| - `data-bs-theme` must be set alongside with `.boosted` class. | ||
| - Don’t hesitate if there is any question. If you have any question, any review, it will probably to others after you, and we can complete a faq with yours to helps others. |
There was a problem hiding this comment.
| - Don’t hesitate if there is any question. If you have any question, any review, it will probably to others after you, and we can complete a faq with yours to helps others. | |
| - If you have any questions, don't hesitate to ask. Any question or feedback will probably be useful to others after you, and we will add your contributions to our FAQs to help them. |
site/src/content/docs/bi-mode.mdx
Outdated
| In this scenario, you will have access, use all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the blanks using Boosted and custom CSS. | ||
|
|
||
| 1. Make sure to install `sass`, and `boosted`. You’ll also need a theme, and this tutorial assumes it will be the Orange theme. | ||
| <Code lang="sh" code="npm i sass @ouds/web-orange boosted" /> |
There was a problem hiding this comment.
What about @ouds/web-common for the js part? I think we should mention it.
There was a problem hiding this comment.
Yes, definitely, I tried something
There was a problem hiding this comment.
I would still add the @ouds/web-common in the install command (even if you talked about that package before in the JS part)
Co-authored-by: Hannah Issermann <hannah.issermann@orange.com> Co-authored-by: Maxime Lardenois <maxime.lardenois@proton.me>
087b33e to
bd75502
Compare
✅ Deploy Preview for boosted ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
site/src/content/docs/bi-mode.mdx
Outdated
|
|
||
| Bi-mode is a way to early and gradually migrate a Boosted project to OUDS. | ||
|
|
||
| This page is for people that want to try the bi-mode combining sBoosted and OUDS Web. It also works as a tutorial to implement OUDS Web gradually inside your website. Be careful, we will support this in a “best-effort” way ; this feature is supposed to be mainly used by pre-selected projects. If you need any assistance, please [contact us]([[docsref:/about/team]]). |
There was a problem hiding this comment.
| This page is for people that want to try the bi-mode combining sBoosted and OUDS Web. It also works as a tutorial to implement OUDS Web gradually inside your website. Be careful, we will support this in a “best-effort” way ; this feature is supposed to be mainly used by pre-selected projects. If you need any assistance, please [contact us]([[docsref:/about/team]]). | |
| This page is for people that want to try the bi-mode combining Boosted and OUDS Web. It also works as a tutorial to implement OUDS Web gradually inside your website. Be careful, we will support this in a “best-effort” way ; this feature is supposed to be mainly used by pre-selected projects. If you need any assistance, please [contact us]([[docsref:/about/team]]). |
site/src/content/docs/bi-mode.mdx
Outdated
| - It implies a change of design, and a mix of two brands that might sometimes visually clash, so be in touch with your designer(s). | ||
| - It implies a big load of work to start the journey. | ||
| - You will need to adapt to the new naming of utilities, helpers, components, etc. | ||
| - Since the library isn’t released, it won’t be as stable as Boosted. |
There was a problem hiding this comment.
I think we can remove this sentence now, the foundations are stable I think, we will probably "just" add new components. (I hope so)
site/src/content/docs/bi-mode.mdx
Outdated
| In this scenario, you will have access, use all the components available in OUDS Web, the grid, the utilities, the helpers, and fill the blanks using Boosted and custom CSS. | ||
|
|
||
| 1. Make sure to install `sass`, and `boosted`. You’ll also need a theme, and this tutorial assumes it will be the Orange theme. | ||
| <Code lang="sh" code="npm i sass @ouds/web-orange boosted" /> |
There was a problem hiding this comment.
I would still add the @ouds/web-common in the install command (even if you talked about that package before in the JS part)
| @import "boosted/scss/mixins"; | ||
| // Don’t import Boosted utilities since they are all defined by OUDS Web already | ||
|
|
||
| // Declare a custom _root.scss, inspired from Boosted, but linked to OUDS Web evolutions |
There was a problem hiding this comment.
is it still needed, even with the custom root selector ? Is it to remove what's already defined in OUDS and should not be overwritten ?
There was a problem hiding this comment.
Yeah, for example we need to remove the link-color or things like that
Co-authored-by: Vincent Prothais <vincent.prothais@orange.com>
Related issues
Closes #3202.
Description
Add an hidden page for the bi-mode
Checklists
Progression (for Core Team only)
ouds/mainfollowing conventional commitLive previews