A hub for community extensions and an official homepage

[StarLederer]

This is an RFC so please comment whether you agree with the problem/solution and how you think the solution can be improved.

The problem

Despite the fact that UnoCSS is faster, more extendable and better designed than Tailwind it has so far not succeeded at communicating how much better it is to existing Tailwind users (Google trends; GitHub star counts). On top of that, the community does not have tools or a platform to showcase and explain their creations reserving to simple READMEs for both purposes.

Proposed solution

The proposed solution is a website that hosts a community collection of presets, transformers, and other UnoCSS extensions, as well as a coherent and visually attractive landing page that effectively informs developers of the benefits of UnoCSS over Tailwind and/or other tools & architectures.

The hub

While there already is a list of community creations on the README I think building a visual hub, similar to Nuxt modules page will significantly improve the discoverability and learnability of those creations.

A large part of the UnoCSS target audience (in my opinion) has a limited experience with web development (e.g. pierrbourne, 2023 or wpcarroll, 2023) and I believe a README is not an effective way to communicate to that audience. A visually attractive webpage that lists "products", on the other hand, is a concept that essentially everyone is comfortable with and would work much better for potential UnoCSS users.

On top of that, a visual hub creates an opportunity to build tooling for and encourage the writing of documentation of the community creations. Currently developers rely on themselves to architect a documentation strategy and build a frontend for it (e.g. Windblade, my own UnoCSS preset), which is a lot of work and is an unnecessary obstacle for the community. Since I have already gone through the process of documenting an UnoCSS preset I now have a starting point for how documentation can be written and I have a forntend that renders it nicely. This forntend can render documentation for any UnoCSS preset as long as it follows the same format and I think integrating it into the UnoCSS community hub can make the documentation process of other community presets significantly more approachable for their creators.

What is required

• Community creations will have to provide documentation that follows the expected format (can be as simple as an object of Documentation type, similar or the same as Windblade's).
• I advise official presets are also documented in this way to serve as an example and improve their own discoverability.

Example

The Nuxt modules page is my inspiration and a great example of what I am describing. As for the documentation, this proposal is based on my learning from Windblade's docs which demonstrate what the documentation pages could look like.

The landing page

I believe there is no need for me to explain why the README does not serve the function of a landing page well but please let me know if you would like me to fill this section, just consider that I have limited time for this.

What is required

• A very well designed landing page
• Concise and convincing story that explains why UnoCSS helps developers when Tailwind/other technologies can't

Example

Any product landing page is an example of this, but I would like to highlight Tailwind's own landing page which does a great job as explaining why it is better than other CSS architectures and Windblade's landing page where I attempt to explain how Windblade can help developers better than Tailwind

[antfu]

Thanks for writing these up, and I agree we should probably have a better landing page and introduction. However, currently I don't have enough time to work on it (it can be a big task, as if I do, I want to make it great). I am not sure if I can give a timeline for it. Before that, it would be great if anyone wants to try a 3rd party site :)

[StarLederer]

I understand the time problem so much... 😅

I am glad to hear that a landing page is within the vision, but could you please let me know what you think of having an official documentation format so that developers can reuse the same frontend for their docs?

I'd shelf the landing page for now because I don't have the resources to make a great one at the moment either, however, I am up for building a prototype of the unified docs format and a fornend for it. Please let me know if you are interested in that as a 3rd party project too and whether this can be eventually picked up by the UnoCSS community because I won't be able to maintain it in the long term.

[antfu]

If there should be a template/style for the doc site, I would recommend https://vitepress.vuejs.org/, which comes out with a very nice default design, and has been used by a lot of libraries like:

• https://vitest.dev/
• https://vitejs.dev/
• https://rollupjs.org/
• https://vueuse.org/
• https://pinia.vuejs.org/

[SnowingFox]

Can i work for this project?

[StarLederer]

Do you mean that we want to introduce playground into the document

In my opinion, we can ditch the interaction on a documentation site, some representative examples can be given since we already have interactive documentation.

I realize I didn't make this clear at all. Code editors are not what I meant by interactive documentation, in fact, maybe we can indeed ditch the "interactive" part but we still need essentially the same code to generate previews of what utilities look like inside shadow DOM so that any community preset can just reuse the theme and be guaranteed that they have a clean isolated environment to write examples. I have already implemented this in Windblade's docs, its really not that hard. Here is what it looks like (try selecting different items and inspecting the preview), and this, and this, is all it took me to make this.

[SnowingFox]

I realize I didn't make this clear at all. Code editors are not what I meant by interactive documentation, in fact, maybe we can indeed ditch the "interactive" part but we still need essentially the same code to generate previews of what utilities look like inside shadow DOM so that any community preset can just reuse the theme and be guaranteed that they have a clean isolated environment to write examples. I have already implemented this in Windblade's docs, its really not that hard. Here is what it looks like (try selecting different items and inspecting the preview), and this, and this, is all it took me to make this.

I see your examples, that's interesting, we can select items to choose style and we can see generated css code, this is a good idea.

but the generated css sometimes may be too long, especially in the case of many examples, more css code will be generated, which will affect the user's experience of reading documents, so i think we give a button for users to choose whether to display the css code

[StarLederer]

Agreed, but showing CSS is not the important part, the important part is that there is a live unocss instance generating this CSS that is actually used inside shadow DOM without anything else interfering with it. The developers of the presets can essentially write HTML for their examples as if they are on CodePen and be sure nothing outside of what they write affects it.

[antfu]

Just FYI, we built a lot of interactive examples (mini playground) back in Windi's documentation:
https://windicss.org/utilities/general/svg.html

They are built with VitePress + Vue. If we need, we could actually copy them over.

But honestly - for me, I explicitly don't want to document every utility's rules, as most of them are just an alias for CSS props. That's also why we built the interactive documentation (it can take custom configs, meaning 3rd party presets should work).

[StarLederer]

Oh wow, yeah, that is really good to know because it looks exactly like what I had in mind. I hope that Tailwind will eventually just use UnoCSS instead of PostCSS anyway so porting that documentation might in fact be a misguided effort.

I still want to address the community documentation problem so might still look into how Windi's theme can be reused, however, I tried VitePress out earlier today and found that there is no way to easily inherit documentation. I'll reach out to the VitePress community about this but so far I am still open to other options, including just using plain JavaScript with a client-side markdown renderer. VitePress looks amazing for projects that need documentation to be purely utilitarian but I am not sure it solves more problems than it creates if you want customize the theme, I'll make sure to also ask their community what they think about this.

[StarLederer]

Update

It sounds like there is some interest, agreement, and ideas so we should proceed. I created a new repo for this project so that we can build a quick prototype and see if we are onto something. This project at the moment is not affiliated with UnoCSS and I would like everyone to recognize that it might fail or never become an official part of UnoCSS. Nontheless, this project aims to quickly confirm our ideas and has @antfu's approval (to some extent) so the prototype will be valuable at least in the form of research.

Goal at the moment

• A test preset with one documented rule.
• Another test preset that has one rule, inherits the other preset and exports documentation for both rules.
• A simple VitePress theme that has a sort of <UnoCSSDocument innerHtml="..." /> for writing examples.
• A VitePress documentation for both test presets.

How to participate

Feel free to fork the repo and make pull requests to master. I'd want to avoid adding collaborators to prevent sabotage, however please let me know in the replies if you want to have it.

[StarLederer]

The repo is empty at the moment, please wait for me to add a quick CONTRIBUTING.md before making forks

[StarLederer]

@SnowingFox let me know if you need collaborator access

[SnowingFox]

can we dicuss in Discord? My id snowingfox#7856

[StarLederer]

Half a year later update

As one might imagine, a lot has happened during the past 6 months in the world and this includes my personal circumstances, this RFC and UnoCSS itself. UnoCSS has made significant progress on the issue this proposal intended to address and has launched web documentation that improved on the previous README-based experience a lot. I've also made some developments documenting Windblade and creating a (paper) framework for UnoCSS preset documentation. Finally, I have learned more about atomic CSS and traditional approaches to styling and admittedly cannot find motivation to work on atomic CSS anymore (I might explain this in more detail in the future, will 404 until that happens).

In this update I intend to sum up the developments on my side and document the mistakes I made along the way to help future readers avoid making them again, as well as conclude this RFC and leave it behind.

What I learned

Documenting built-in presets

I still believe that each UnoCSS presets should be independently documented similar to the old Windi docs or the big daddy Tailwind itself. I think UnoCSS is an improvement over Tailwind in every possible way but having no independent documentation and expecting that the users either already know Tailwind or are willing to cross-reference their docs might be sending the wrong message. I keep seeing it that UnoCSS is being rejected by Tailwind fans and is perceived like a knock-off rather than an improvement, and asking them to read Tailwind docs because the default preset/preset-wind doesn't have their own positions it more like the latter.

I don't think the Interactive docs are a suitable substitute, it is a clever solution that kind of documents all the possible UnoCSS presets, even ones that don't exist yet, however, Tailwind docs not only demonstrate what the utilities do but also cover two more touch-points that I'm sure helps them increase adoption. First, they simply list all the utilities and topics in a linear way allowing users to go through it all one by one and in the end feel like they have completed their education and learned everything he creators believe they needed to know. Second, they not only make connections to CSS properties and give examples but they also explain the CSS properties themselves so even the users that don't know CSS can start using Tailwind. I believe these two points will continue to, in my opinion, trick a lot of people into using Tailwind, when a massively better alternative exists.

Inheritable documentation

As I mentioned in the past, I really like that you can not only overlay UnoCSS presets but also fork, slim down, extend and generally just modify first-party UnoCSS presets (or any other presets that are built well) with ease, and I was hoping to find a way to carry that aspect over to the documentation.

I tried VitePress, however I did not come up with any way to achieve this with it directly because it was impossible to import pages from the docs of a different project reliably.

In the end I self rolled a solution that used a tree of plain-text strings to build documentation and relied on third parties to render this content. This could be done on server side or on the client using any framework or language because it is just data. In my experience so far this solution worked well and I managed to break Windblade down into multiple smaller presets and make them share documentation pages between each other when this was needed.

Admittedly, I cannot confirm if this works as well when extending and, especially, modifying a big existing preset. I worry that this approach might completely fall apart if you want to modify something very small that applies to all rules/all documentation pages because there is no framework for how to modify the docs, only reuse and inherit them.

Overall, I think a tree of strings is a promising structure that I would recommend anyone that might be interested to try to explore further and see if it is possible to painlessly and reliably modify inherited documentation pages as well.

Documentation format

When it comes to the format there were several obvious choices: vue-enhanced markdown components in/like in VitePress, plain markdown, and, of course, JSDoc. Admittedly, the JSDoc idea came much later and I did not explore it at all but the other two did not work well for the text-based approach that I took. Obviously, you can't use Vue components if your target is text, executing third party js, especially on the client side, was out of the question. Markdown didn't work either because it was too simple and did not allow for interactive components and advanced examples without turning into absolute mess.

After a failed Markdown experiment I turned to Markdown's bigger brother, markup, in this case XML specifically, and found out that it covered all the features that were required and was already familiar to the the target audience making it easy for them to contribute back to. You can see an example of how I put XML to use in the documentation here, the example covers titles, text, and some special UnoCSS doc elements like <html> for rendering example input code, <renderer> for defining input code templates, and <viewport> & <css> for rendering examples using a live UnoCSS instance based on a util selected with <utils>, but other markdown features and more UnoCSS-specific elements are possible.

This approach worked very well for me but it also has downsides, the biggest of which being that it has to be written as a JavaScript string which leaves you without IDE support. This can be solved with JSX or simple render functions but I did not go down that rabbit hole.

All things considered, I think markup is the best way to go, but perhaps it should not be written by hand like I did.

Next steps

Personally I have been already trying to take Windblade to a point where I feel like I can call it done and am currently intending to offer it up for adoption if anyone is interested. Unfortunately I cannot make further developments on this topic at the moment and I will not be requiring potential future Windblade maintainers to continue this exploration, it will be up to them to decide.

As for this RFC, I think significant developments are unlikely in the near future so I will be closing it with this post. I would like to thank everyone for their interest and participation and I hope you took something useful out of the progress and discoveries we made together.