Proposal to Adopt Tailwind CSS for Improved Styling

[Abhijay007]

Discussed in https://github.com/uptane/uptane.github.io/discussions/177

^{Originally posted by **Abhijay007** January 22, 2024} Hi, Uptane Community 👋 , I'd like to bring up a suggestion regarding the current styling practices on our site. we currently employ vanilla CSS styles, with each component having its own separate CSS file. This approach necessitates a considerable amount of CSS for each component, and we've encountered challenges with certain components not exhibiting the desired responsiveness. Considering these issues, I propose a transition to [Tailwind CSS](https://tailwindcss.com/) to overhaul our site styles. Tailwind offers several advantages over vanilla CSS, including rapid development, consistency, a mobile-first approach, increased customization capabilities, the need for minimal CSS, enhanced flexibility, and support for responsive design. Switching to Tailwind would not only enhance the site's visual appeal but also streamline the development process. Tailwind has gained widespread adoption in open-source projects, fostering a robust community. This community support can potentially attract volunteers to contribute and expand our existing set of components. I encourage everyone to consider this proposal and share your thoughts on adopting Tailwind for our site. Your feedback and contributions are vital to making this transition successful. Let's leverage the benefits of Tailwind CSS to improve our site's design, responsiveness, and overall user experience. Here are a few resources below to see how we can leverage Tailwind in our documents project and how some sites are already doing the same. 1. [A Guide to Seamless Integration with Tailwind CSS in Docusaurus](https://medium.com/@bargadyahmed/docusaurus-a-guide-to-seamless-integration-with-tailwind-css-dd202211caac) 2. [Using Tailwind CSS v3 in Docusaurus in 5 Steps](https://dev.to/shannonajclarke/using-tailwindcss-v3-in-docusaurus-in-5-steps-5c26) 3. [Example from Medusa.js, an open-source project utilizing Tailwind in Docusaurus](https://github.com/medusajs/medusa/blob/4792c552269c147d3c07da49a175e9038f9260a8/www/apps/docs/src/css/_docusaurus.css#L4) 4. [Supabase, another popular OSS project using SCSS + Tailwind + Docusaurus](https://github.com/supabase/supabase/blob/616a6981baea55fc6a48d58327ba130a8e804920/apps/docs/styles/main.scss#L96) If you have any suggestions or alternative approaches for this transition, please feel free to share them in the discussion below. I am looking forward to your valuable input and support in making our site more efficient and responsive. Thank you!

[ravikr126]

Hi @Abhijay007 I like to contribute to this issue. I have good knowledge of tailwind css and I can help you move from vanilla css to tailwind css with mobile responsive.

[Abhijay007]

Hi @Abhijay007 I like to contribute to this issue. I have good knowledge of tailwind css and I can help you move from vanilla css to tailwind css with mobile responsive.

Hi @ravikr126, Thanks for showing your interest in the same. It's a lengthy issue which can be further divided into sub-issues. Specifically for this issue we are targeting to migrate the main CSS file and an existing component (preferably a Header component ) to the tailwind CSS and want to know which approach would be better for the same. I have shared a few resources above; you can take references from those resources and come up with an approach to use Tailwind in Docusaurus effectively.

After that, we will migrate all the components one by one to Tailwind. Additionally, we are looking to add many new components to the site. So, please come up with an approach in which you can address this issue and use Tailwind with Docusaurus effectively.

You can further find the discussion related to this here: Discussion Link

Also, there is a contributor, @Nishu0, who also wants to work on these issues. Once we are done with the basic setup, I will keep assigning issues to both of you around the same. You both can come up with different but best approaches to using Tailwind in Docusaurus, and we can move forward with the best one. We will then add migrate components one by one.

Let me know if you have any further questions around the same.

[ravikr126]

Hi @Abhijay007 I checked out the repository and documentation, and I found all the files are in component form. My approach is to start with the top component, and in a sequential manner, I will change the Vanilla CSS to the Tailwind CSS and make the component responsive so that it can be accessed on different devices and comes to down till footer , but i need 1 help that many times some version issue come up, how i tackle the version issue. and I will create the pull request in every component migration from vanilla to tailwind CSS so that you can track the whole thing in a better manner. I will create branches that help to not disturb the main branch.

[Abhijay007]

Hi @Abhijay007 I checked out the repository and documentation, and I found all the files are in component form. My approach is to start with the top component, and in a sequential manner, I will change the Vanilla CSS to the Tailwind CSS and make the component responsive so that it can be accessed on different devices and comes to down till footer , but i need 1 help that many times some version issue come up, how i tackle the version issue. and I will create the pull request in every component migration from vanilla to tailwind CSS so that you can track the whole thing in a better manner. I will create branches that help to not disturb the main branch.

Your approach to converting components from top to bottom in a sequential manner is fine, but the approach that I am asking about is not related to how we convert components from vanilla CSS to Tailwind, It's a straightforward task and might not need that much of hustle around it. Also, it might make more sense only if we can figure out how we're going to utilize Tailwind with Docusaurus.

So, the main thing for now is how we're going to use Tailwind in Docusaurus, like how we are using it as an entry point. That's why I shared those resources above, as those projects used some customization around the same. We might need to create different files around custom CSS or maybe need to convert that.

For this issue, we are mainly looking for that only, like what can be the entry point and how Tailwind can be structured in our existing Docusaurus site and replace the main vanilla CSS file that we are using.

Also, talking about versions, so I am not quite getting it, are you talking about Tailwind versions or Docusaurus versioning?

[Abhijay007]

Hi @Abhijay007 I checked out the repository and documentation, and I found all the files are in component form. My approach is to start with the top component, and in a sequential manner, I will change the Vanilla CSS to the Tailwind CSS and make the component responsive so that it can be accessed on different devices and comes to down till footer , but i need 1 help that many times some version issue come up, how i tackle the version issue. and I will create the pull request in every component migration from vanilla to tailwind CSS so that you can track the whole thing in a better manner. I will create branches that help to not disturb the main branch.

Your approach to converting components from top to bottom in a sequential manner is fine, but the approach that I am asking about is not related to how we convert components from vanilla CSS to Tailwind, It's a straightforward task and might not need that much of hustle around it. Also, it might make more sense only if we can figure out how we're going to utilize Tailwind with Docusaurus.

So, the main thing for now is how we're going to use Tailwind in Docusaurus, like how we are using it as an entry point. That's why I shared those resources above, as those projects used some customization around the same. We might need to create different files around custom CSS or maybe need to convert that.

For this issue, we are mainly looking for that only, like what can be the entry point and how Tailwind can be structured in our existing Docusaurus site and replace the main vanilla CSS file that we are using.

Also, talking about versions, so I am not quite getting it, are you talking about Tailwind versions or Docusaurus versioning?

our main entry point for site styles is this : https://github.com/uptane/uptane.github.io/blob/main/src/css/custom.css , we are getting most of our styles rendered in different component CSS files from here only, like color schema, headings, fonts, etc.

so if you look into the resources I shared above you will be redirected to the main entry point Taliwind file of the site that is utilizing Tailwind in Docusaurus, see their approach and we need to Iterate our site something like that or better

[ravikr126]

Hi @Abhijay007 I checked out the repository and documentation, and I found all the files are in component form. My approach is to start with the top component, and in a sequential manner, I will change the Vanilla CSS to the Tailwind CSS and make the component responsive so that it can be accessed on different devices and comes to down till footer , but i need 1 help that many times some version issue come up, how i tackle the version issue. and I will create the pull request in every component migration from vanilla to tailwind CSS so that you can track the whole thing in a better manner. I will create branches that help to not disturb the main branch.

Your approach to converting components from top to bottom in a sequential manner is fine, but the approach that I am asking about is not related to how we convert components from vanilla CSS to Tailwind, It's a straightforward task and might not need that much of hustle around it. Also, it might make more sense only if we can figure out how we're going to utilize Tailwind with Docusaurus.

So, the main thing for now is how we're going to use Tailwind in Docusaurus, like how we are using it as an entry point. That's why I shared those resources above, as those projects used some customization around the same. We might need to create different files around custom CSS or maybe need to convert that.

For this issue, we are mainly looking for that only, like what can be the entry point and how Tailwind can be structured in our existing Docusaurus site and replace the main vanilla CSS file that we are using.

Also, talking about versions, so I am not quite getting it, are you talking about Tailwind versions or Docusaurus versioning?

I am talking about react version and some extra dependencies that are not working now, i use npm force and 1 more thing i use npm instead of yarn so which one you like to prefered

[Abhijay007]

Hi @Abhijay007 I checked out the repository and documentation, and I found all the files are in component form. My approach is to start with the top component, and in a sequential manner, I will change the Vanilla CSS to the Tailwind CSS and make the component responsive so that it can be accessed on different devices and comes to down till footer , but i need 1 help that many times some version issue come up, how i tackle the version issue. and I will create the pull request in every component migration from vanilla to tailwind CSS so that you can track the whole thing in a better manner. I will create branches that help to not disturb the main branch.

Your approach to converting components from top to bottom in a sequential manner is fine, but the approach that I am asking about is not related to how we convert components from vanilla CSS to Tailwind, It's a straightforward task and might not need that much of hustle around it. Also, it might make more sense only if we can figure out how we're going to utilize Tailwind with Docusaurus. So, the main thing for now is how we're going to use Tailwind in Docusaurus, like how we are using it as an entry point. That's why I shared those resources above, as those projects used some customization around the same. We might need to create different files around custom CSS or maybe need to convert that. For this issue, we are mainly looking for that only, like what can be the entry point and how Tailwind can be structured in our existing Docusaurus site and replace the main vanilla CSS file that we are using. Also, talking about versions, so I am not quite getting it, are you talking about Tailwind versions or Docusaurus versioning?

I am talking about react version and some extra dependencies that are not working now, i use npm force and 1 more thing i use npm instead of yarn so which one you like to prefered

have you tried updating the node version on your local machine?

[devilkiller-ag]

@ravikr126 you won't face the version issue if you use yarn install as our project is using yarn instead of npm.

[devilkiller-ag]

@Abhijay007 I think the resource 1 that you provided is enough to understand how to set up the tailwind css with docusaurus. But these tutorials (resource 1 and 2) use inline tailwind css. The open source projects you shared were using tailwind css through an external css file.

To decide which mode (inline or external) we should use we have to focus on what's our second aim besides making our website style consistent and streamlining the development process:

1) Remove the requirements of using different css files for separate components?(In this case we can consider inline css)

OR

2) Reduce the repeating and non-consistent css code? (In this case we should consider creating a general style components using tailwind css which is stored in a external css file and be used with any component throughout our codebase).

Do let me know your pointview on this and If I am thinking in the correct direction.

[Abhijay007]

@Abhijay007 I think the resource 1 that you provided is enough to understand how to set up the tailwind css with docusaurus. But these tutorials (resource 1 and 2) use inline tailwind css. The open source projects you shared were using tailwind css through an external css file.

To decide which mode (inline or external) we should use we have to focus on what's our second aim besides making our website style consistent and streamlining the development process:

1. Remove the requirements of using different css files for separate components?(In this case we can consider inline css)

OR

2. Reduce the repeating and non-consistent css code? (In this case we should consider creating a general style components using tailwind css which is stored in a external css file and be used with any component throughout our codebase).

Do let me know your pointview on this and If I am thinking in the correct direction.

@devilkiller-ag, they are not using any external CSS for the components, but for global styles for utilizing Talwind, The thing is that they've created a separate file to support the main custom CSS file (global one) here : https://github.com/uptane/uptane.github.io/blob/main/src/css/custom.css, to render Tailwind. And yes, we need to remove the external CSS file from the components and utilize inline CSS instead. For example, take a look at this component here: Navigation/Footer.tsx. They've used inline Tailwind in this but still have global styles. It's pretty straightforward.

For everyone's convenience, I'll summarize it here:

• We need to find the best and most effective way to use Tailwind with our documents.
• Then, we need to convert or create a dedicated global styles file using Tailwind, as shared in the above resource.
• Then, we need to remove the external CSS files from the components.

For this issue, you just need to figure out the first two things and convert any of the components to showcase that we can convert the existing component using Tailwind. If we can do this, we're going to change most of the components and add some new ones too.

[ravikr126]

hi @abhijay007 I found 1 resource regarding custom tailwind CSS that may be this approch help us https://medium.com/@arulpraba/using-tailwind-css-utilities-in-custom-css-files-acf811089055

[devilkiller-ag]

@devilkiller-ag, they are not using any external CSS for the components, but for global styles for utilizing Talwind, The thing is that they've created a separate file to support the main custom CSS file (global one) here: https://github.com/uptane/uptane.github.io/blob/main/src/css/custom.css, to render Tailwind. And yes, we need to remove the external CSS file from the components and utilize inline CSS instead. For example, take a look at this component here: Navigation/Footer.tsx. They've used inline Tailwind in this but still have global styles. It's pretty straightforward.

For everyone's convenience, I'll summarize it here:

• We need to find the best and most effective way to use Tailwind with our documents.
• Then, we need to convert or create a dedicated global styles file using Tailwind, as shared in the above resource.
• Then, we need to remove the external CSS files from the components.

For this issue, you just need to figure out the first two things and convert any of the components to showcase that we can convert the existing component using Tailwind. If we can do this, we're going to change most of the components and add some new ones too.

@Abhijay007 Got your points. For the first point, I think it will be better to have inline CSS for all the components and a separate file for global CSS using the @apply directive (which is useful when we find a common utility pattern in our HTML that we’d like to extract to a new component). This should be done for global styles because they are being used in many places. I found a nice discussion about when and why to use separate CSS files for tailwind CSS.

I think we should start with converting the global styles file into Tailwind CSS.

[Abhijay007]

hi @Abhijay007 I found 1 resource regarding custom tailwind CSS that may be this approch help us https://medium.com/@arulpraba/using-tailwind-css-utilities-in-custom-css-files-acf811089055

@ravikr126, this blog is informative, but it appears a bit dated as it pertains to 2021, both Tailwind and Docusaurus have had major version upgrades since 2021, I've shared a relatively new article around the same topic listed in the resources above that might help.

[Abhijay007]

@devilkiller-ag, they are not using any external CSS for the components, but for global styles for utilizing Talwind, The thing is that they've created a separate file to support the main custom CSS file (global one) here: https://github.com/uptane/uptane.github.io/blob/main/src/css/custom.css, to render Tailwind. And yes, we need to remove the external CSS file from the components and utilize inline CSS instead. For example, take a look at this component here: Navigation/Footer.tsx. They've used inline Tailwind in this but still have global styles. It's pretty straightforward. For everyone's convenience, I'll summarize it here:

• We need to find the best and most effective way to use Tailwind with our documents.
• Then, we need to convert or create a dedicated global styles file using Tailwind, as shared in the above resource.
• Then, we need to remove the external CSS files from the components.

For this issue, you just need to figure out the first two things and convert any of the components to showcase that we can convert the existing component using Tailwind. If we can do this, we're going to change most of the components and add some new ones too.

@Abhijay007 Got your points. For the first point, I think it will be better to have inline CSS for all the components and a separate file for global CSS using the @apply directive (which is useful when we find a common utility pattern in our HTML that we’d like to extract to a new component). This should be done for global styles because they are being used in many places. I found a nice discussion about when and why to use separate CSS files for tailwind CSS.

I think we should start with converting the global styles file into Tailwind CSS.

Ya, we need that only to begin with this migration, It would be great if you could open a pull request adding Tailwind to Docusaurus in the most recent and effective approach as suggested in the articles above. Also, please start converting the global styles. Begin by converting the "hero component" using Tailwind and if it works properly, then we can open new issues for other components.

[devilkiller-ag]

Ya, we need that only to begin with this migration, It would be great if you could open a pull request adding Tailwind to Docusaurus in the most recent and effective approach as suggested in the articles above. Also, please start converting the global styles. Begin by converting the "hero component" using Tailwind and if it works properly, then we can open new issues for other components.

Okay I will divide this into two PRs one for the integration setup of Tailwind with Docusaurus and then another for converting the "hero component" using Tailwind.

[devilkiller-ag]

Hey @Abhijay007, I made the changes to the headings. However, I think I will need to convert the whole custom.css into a tailwind, to fix the stylings. I am currently doing these changes in a different CSS file. I have changed the headings styling into tailwind in the above commit.

[Abhijay007]

Hey @Abhijay007, I made the changes to the headings. However, I think I will need to convert the whole custom.css into a tailwind, to fix the stylings. I am currently doing these changes in a different CSS file. I have changed the headings styling

Using a separate file for the specific changes would be more effective. We can follow the same approach outlined in the resources shared above. I have reviewed the code, and it looks good to me. For the initial step, let's create a separate file and submit a new pull request to convert one of the components using Tailwind. I recommend starting with the hero component."

[ravikr126]

@Abhijay007 can you assign me any component so that I can also work on this project I check out all the resources and tried some code related to global tailwind implementation and inline tailwind code

[Abhijay007]

@Abhijay007 can you assign me any component so that I can also work on this project I check out all the resources and tried some code related to global tailwind implementation and inline tailwind code

I will open new issues once we are done with the initial tailwind setup and having at least one component converted using Tawliind, once we are done with this, I will assign some issues to you.

[ravikr126]

thank you @Abhijay007

[shubhusion]

@Abhijay007 is this issue still relevant? if yes, can you let me know how much is done and what needs to be done?

[Abhijay007]

@Abhijay007 is this issue still relevant? if yes, can you let me know how much is done and what needs to be done?

yes it is, you can work on this, take reference from this PR here : https://github.com/uptane/uptane.github.io/pull/185