Lessons Learned from Enterprise Grade UX Customization

When I joined the IBM Connections project, it took me little to realize that few or none of our end users were seeing our product as we developed it, i.e. with the default styles and UX. Connections is IBM’s flagship enterprise social collaboration offering, comprising of a suite of web applications, native mobile clients, and a range of plugins and extensions for other IBM offerings like WebSphere Portal.

Connections was born as a Lotus product that could be installed on-premises in the customers’ own IT infrastructure and used in the intranet, but later became the backbone of IBM’s social offering, offered as a solution in a number of flavors and variants, standalone or integrated with other capabilities, e.g. WebSphere Portal, Kenexa Talent Suite, also made available as a SaaS cloud offering.

Our development team was tasked with the unique mission of having to develop and maintain a performant, accessible and globalized product that delivered a compelling experience out of the box, but were also extensible and customizable to meet the customers’ unique requirements for integration, wording, visual design, and extension.

We wouldn’t have been able to deliver on the mission hadn’t we had the support of a few elements:

  • An amazingly powerful and flexible style toolkit that provided us with a full range of visual patterns
  • Support for resource customization, that let admins override any of the resources used by the applications
  • A style guide that provided developers with a live catalog of patterns and widgets

The OneUI Toolkit

The public documentation of the OneUI Toolkit v3.0.3

The OneUI style guide had some dynamic behavior, in that it loaded patterns in <iframe>’s thus allowing the container page to load different content based on URL parameters, enabling prototypers to use it as a test bench while coding the very styles. The dropdown menus for language, directionality, and base text size are absent from the public style guide, but you can still request them manually.

Runtime aggregator

At the peak of its heyday our resource aggregator was able to crawl and aggregate JS files via AMD require() or the Dojo Toolkit’s dojo.require(), and CSS files via @import. It could also customize file by file JS and CSS resources, as well as HTML templates, Java .properties files for localized strings, and plain text files.

A living style guide

We got as far as reaching a point where we were doing true Style Guide Driven Development as popularized by Nicole Sullivan, in fact we mostly used this approach to publish a catalog of existing patterns to aid our refactor from legacy Dojo module system to AMD, and used the pages of the live style guide as test rig to execute end to end tests with WebDriver.

The reality

I had a sudden flashback while I was reading the brilliant article Building an Enterprise CSS Framework by Salesforce.com’s Stephanie Rewis who states:

Salesforce partners wanted their apps to have a Salesforce look, but many didn’t have the resources or developers needed to make it happen, and those that did were inspecting in the browser to reverse engineer our code. A version of Bootstrap with a Salesforce look was created, though not by us, and it quickly fell out of step with our changing designs.

We had an even worse problem. Since we committed to let our customers create visual themes that matched their corporate identity by overriding our styles, it meant that we couldn’t alter the structure of pages without breaking all of our customers’ custom themes. This had a negative impact on our own internal development as well, as visual theme updates like the gen4 theme had to be markup-compatible with the existing UX.

Lessons Learned

Namespace your class names

This reduced the likelihood of interferences between the product’s own CSS selectors and third party styles’ selectors to a minimum.

In detail, the OneUI Toolkit used the lotus* prefix for all classes, e.g. lotusMain, lotusBanner, while Connections’ own styles had a prefix of lconn*, later superseded by ic-* or ics-* (acronyms of IBM Connections, or IBM Collaboration Solutions respectively[1]).

Style guide driven development is awesome

In our experience, developing a catalog of UX patterns proved invaluable to quickly iterate over designs, prototype new widgets or entire pages, and try them out with all supported themes.

While our style guide was never published or shared with customers, it served well as a development tool, also exercised by automated end to end tests in CI, as well as a communication tool to browse and review patterns.

Document and test extension points

When your code is shipped to customers, it’s out. You can’t control it anymore. It took us a couple of releases to figure out we’d better document extension points and cover them with automated unit tests, than let customers be creative and choose where to attach their extensions.

As a result, the number of problems reported on the field went down dramatically, as most of the regressions and problems were caught during development sprints.

Let them build it

If you don’t have such a use case, you’d better build your resources into layers via Webpack, Gulp, or Grunt, and publish static files to an HTTP server like Apache or Nginx. If you have a requirement to let customers override your resources, share them as open source (your front-end code is most often not your secret sauce, after all) or via shared source agreements, and give them instructions to build them themselves.

Open source your style toolkit

Open sourcing your style toolkit allows customers to clone, modify and rebuild the stylesheets of the product, as well as lets them make use of the style guide and tests, thus taking advantage not just of the code, but also the development methodology to ensure continuous quality.

[1] These are actually acronyms of acronyms.

Full stack web developer with a keen interest for the open web platform, privacy, security, and IoT. Former Amazonian, former IBMer. All views my own.

Full stack web developer with a keen interest for the open web platform, privacy, security, and IoT. Former Amazonian, former IBMer. All views my own.