HTML design

Owned by Bart Koopman (Unlicensed)
Last updated: Oct 07, 2016

Initial goals of a front-end module

A well working module should:

  • provide a visual for clients and users
  • be professional level quality
  • separate concerns

Strengths, weaknesses and opportunities of DXA whitelabel HTML design

Strengths

  • good continuous integration
  • uses modern tools
  • enforces a workflow
  • is open source
  • and uses open source tools

Weaknesses

  • doesn't communicate it's purpose well
  • not self documenting
  • TBBs aren't flexible for changes
  • doesn't appear to separate concerns

Result:

Seems to encourage ditching entire module and starting from scratch.

Opportunities

  • documentation
    • merge READMEs of current Git repository
    • provide "skinning" instructions
    • provide "for back-end / for front-end" info
    • communicate the back-end / build flow
    • visual aid for the workflow
  • presentation
    • make the whitelabel itself the documentation, the appeal, and the instruction
  • update the TBB
  • workflow improvement
    • two options: sources, front-end zip
    • Gulp build, Gulp package / npm package
    • remove requirement that Tridion executes any Node.js
    • positioning:
      • source build is for more discrete control (it's individual CSS/JS/... no HTML)
      • zip build is for quick deployment (contains CSS/JS in single file)
  • communicate workflow for adding modules

Highlights

Documentation

The current DXA whitelabel HTML design contains quite a lot of documentation, but it seems to miss the most important part, which is how it is intended to be used. There is information on how it can be built and updated, but we missed describing what we expected front-end developers to do with it exactly, which is style it by adjusting only CSS and JavaScript, without modifying the HTML.

Workflow improvement

Currently the DXA whitelabel HTML design is build at publish time using Node.js and Grunt. This results in a rather complex package structure, because we didn't want the Bower components and required npm packages to be downloaded each time when the design was published. This type of magic is what confuses the seasoned developers, and makes them decide to ditch it, while the current workflow for a front-end designer was actually quite good. So if we can clarify the workflow, start using Gulp instead of Grunt (since that seems to be more widely accepted these days) and remove the magic around the HTML design build process, we hope it will be more widely accepted.

Going forward

We have noticed that the basic styling of the existing whitelabel HTML design seems to not resonate with the community. The idea behind the current (lack of) styling was that the implementer would see the need for restyling, instead it seems to have encouraged ditching it completely. So going forward, it makes sense to deliver two or three versions of the whitelabel HTML design, each with the exact same HTML, but styled differently. This allows for nicer demos and shows the viability of (re)styling.

It will be a good idea to have the whitelabel HTML design available as an npm package, seeing as it is common practice to use Node.js and its package manager to build HTML designs. https://www.npmjs.com/package/dxa can serve as a container for the main design, and each module can be a separate package.