Getting designers to play nicely with SharePoint, keeping clients happy on a short deadline, herding CSS
!importants – what could possibly go wrong?
We were recently approached by a large client to work on a new generation of its Microsoft SharePoint-based product: a project management solution it had put together in house using a mix of off-the-shelf and custom-built components.
In the brief, the client asked us to identify and solve key usability issues with the existing solution and to develop a new look and feel layer for it while maintaining a single visual identity and coherent user experience across the two main solution components – Microsoft SharePoint and Microsoft Project, both web apps on the SharePoint platform. In the research we conducted, users repeatedly brought up navigation within the existing system as a major pain point, and we felt we could solve this as well.
Challenge one: the look and feel
With input from our design team, we first put together a SharePoint theme to use in both SharePoint and Project. This would apply the same colours and fonts throughout the solution.
It quickly became clear that we had to go beyond the SharePoint theme engine to satisfy our designers: the two products still had their separate logos displayed prominently in the page headers; we still wanted to improve layouts, spacing and form elements as well as add subtle touches like shadows and hover effects; and we found the theme engine itself limiting.
For example, setting a background colour in the header would also affect text colour in a separate side panel. Therefore, we turned to CSS. (If you come from a SharePoint background, you might ask why we didn’t just change the master page… we’ll let Vesa Juvonen, a Senior Program Manager at Microsoft, explain)
Writing custom CSS for SharePoint is something of an art. It is, in essence, retrofitting style rules onto existing markup developed over the years by several teams at Microsoft, all of which is internal to the SharePoint platform (so no official documentation) and some of which was not written with styling in mind. Needless to say, we spent a lot of time inspecting code in Chrome’s Developer Tools and working back towards reliable patterns.
Challenge two: navigation
The disjointed out-of-the-box navigation systems of Project and SharePoint created significant user pain and reduced acceptance of the overall solution.
These components combine data from the SharePoint and Project APIs to create a unified navigation UI that looks and behaves exactly the same on both SharePoint and Project. It might have been easier to hard-code the new menu and be done with it, but we served the client better with a configurable and scalable solution, which could be easily adapted to different site structures, international markets and the like.
Customising SharePoint has grown over the years into a noble tradition that comes with a lot of conventional wisdom attached to it. In this case, we deliberately chose to apply a modern web toolset to the problem. We wrote our code in ECMAScript 2017+ (with async/await and other goodies), compiled using Babel, bundled using Webpack, type checked using Flow, and unit tested using Jest. We used React for UI rendering, we wrote stylesheets as CSS Modules with SASS and PostCSS, and we regularly released semantically versioned packages (using Lerna) to our client via a private npm repository.
Doing all of the above in a ‘brownfield’ project was not without its challenges. We still had to closely integrate with the client’s tech team who had their own process in place. Therefore we emphasised open communication, established a joint release cycle we were all comfortable with and provided clear and up-to-date documentation, which we wrote concurrently with the code.