UI Standards

Last modified by Vincent Massol on 2024/02/26 17:54




I think we all agree that we need to have standards to write a nice and consistent UI. We already have some, and also some undocumented ones. Now, we have introduced Bootstrap in the Flamingo Skin to use all their great components and CSS styling.

Now, it is time to define what we want to be as standard.


A UI standard is made of:

  • CSS classes.
  • HTML snippets (to use in conjunction of CSS classes).
  • Theme variables to customize the framework.

But it could also contain:

  • Wiki macros to generate the appropriate HTML code.
  • Javascript components that dynamically generate the appropriate HTML code.

The standards will be the new recommended way of writing applications. For old applications that we cannot re-write, we can provide a compatibility layer. This compatibility layer should not be used by new apps and should not be considered as part of our standards.

Idea 1: marry to Bootstrap (+ our own add-ons built on top of Bootstrap)

The first idea was to say we drop our own standard and Bootstrap (BS) is our new standard now. 


  • BS is quite popular.
  • we do not waste time designing our standards and we avoid the "Not Invented Here" issue.
  • much richer than our own standards.


  • BS may not maintain retro-compatibility in the future: all applications would be broken.
  • What if we want to switch to the next popular framework in the future?
  • BS have very generic class names like ".label". They could collide with existing the CSS classes of user applications. It would have been better to have something like ".bs-label".
  • In the future, if we move to an other framework, this generic class names can collide with the future framework too.

We can marry to bootstrap on the CSS aspects but still having our own color theme variables.

Idea 2: Create our own standard (and bind it to whatever framework you want)

We design our standards, but it could be a copy/paste of bootstrap if we want. Then we have to guarantee that these standards will remain stables so we have the retro-compatibility.


  • We can create exactly what we want (ex: prefix all CSS classes by xwiki-*).
  • We can switch to any CSS framework, we just need to bind our CSS classes to the framework ones.


  • Switching to an other CSS framework is not as simple as "we just bind our CSS classes to the new CSS classes", because the CSS classes apply on HTML code written in a specific way. In the reality, HTML and CSS are not so separate as it should be in a perfect world. We will still need to rewrite HTML code.
    • But it is not an issue anymore if we only use wiki macros that generate correct HTML code depending on the current CSS framework.
  • Bootstrap has probably broken their retro-compatibility for good reasons. I am not sure we can do better concerning this aspect with our own standards.
  • It takes time to write such a standard and it needs a good & complete documentation.
    • But not that much if we just copy/paste the BS doc.
  • New developers will have to discover our own standards, instead of using the popular framework they may already known.
    • Same, if it is only a wrapper on top of BS, it is not a hard learning curve!
  • Maintaining a mapping between our classes and bootstrap classes is not that easy (see: https://github.com/xwiki-contrib/bootstrap-wrapper/blob/master/style.less where I just try to add a namespace). It needs to be done on every bootstrap upgrades.
    • (the namespacing can be done via a maven plugin able to rename every classes defined in the LESS files).

About creating macros

If we create wiki macros in order to avoid using HTML in wiki page, we need to have something similar for JavaScript, especially if we expend the use of AngularJS.

Idea 3: Mix Standard: XWiki specific classes + a selection of Bootstrap classes

The reason is that Caty and Guillaume both prefer our XForm layout convention to the bootstrap form, because it looks better even without CSS enabled.

And we probably don't want to marry to all bootstrap points of view.

So the idea is to select which components we like in Bootstrap + which existing work we have and we like in XWiki.


  • We use Bootstrap without marrying to all of their conventions
  • We do not have to rewrite every existing applications that use the current XForm layout convention (and any existing components that we would decide to keep).
  • Minimal documentation to maintain: only our own components + links to Bootstrap components.


  • It still does not fix the retro-compatibility issue. If Bootstrap 4 breaks a lot of things and if we are not able to provide fix for them,
    applications would be broken.
    • But we can still create macros
  • It's a bit messy because part of the documentation is on xwiki.org and part of it is on getbootstrap.com.
  • Bootstrap does not have a namespace.


Get Connected