In preparation for Global Accessibility Awareness Day, the Pulsar team has been on an accessibility kick recently, doing various things to improve the accessibility of the Pulsar design system and the software it serves.

I took some time to experiment with a handful of popular accessibility testing extensions and tools which we use to validate the accessibility of our user interfaces. These tools will give you a good foundation of accessibility before you move onto user-centric testing with real people and/or full blown accessibility audits. You should consider using these tools to test accessibility much the same way as you test your markup using the W3C validators which has always been one of the most basic tests we all perform before go-live.

Browser extensions (I’m using Chrome for the purposes of this post)

• WAVE Web Accessibility Evaluation Tool
• Lighthouse
• aXe browser extension
• WCAG Accessibility Audit Developer UI
• SiteImprove Accessibility Checker

Other tools

• Tenon.io (free and paid plans available)

Starting our test

I needed a real user interface to test, something fairly small with a handful of form elements and interactions, so I started where all our Continuum users start, our sign-in screen. There’s a small amount of interaction design here, users will move between a few different forms in-place but there’s not an awful lot of markup involved, so for the purposes of this post it’s a good example of how we can work through the various issues flagged by the tools.

First, let’s see what each tool tells us before we make any changes. If the tool gives me the option to filter results I will be setting it to show me anything related to the Web Content Accessibility Guidelines 2.0 at AA compliance level, although in our real-world testing we’re also interested in looking at Section 508 compliance for the US market.

WAVE Web Accessibility Evaluation Tool

This is usually the first browser extension developers think of when accessibility testing comes up, but as I’ll show in the post, it’s probably not the first one you should reach for.

Hitting the WAVE button in Chrome’s extensions toolbar displays the WAVE toolbar as a column inside your window, here it shows me 1 error and 9 alerts. Previously we’ve only focused on resolving ‘errors’ in our internal testing but we’re now increasing our scope to ‘alerts’ also.

WAVE overlays an icon for each issue on the UI but it gets confused by absolute positioning and doesn’t show any other information about the related element, such as markup or ID/class attributes. This is somewhat problematic if you have issues on UI partials that are not yet visible, such as hidden forms. It takes some hunting around using dev tools to pinpoint the element causing the error. Alternatively, as suggested by Charles Hall in the comments below (Lead developer of WAVE) you can toggle the ‘no styles’ mode which will give you the plain old HTML view of your UI but still show WAVE icons next to the related elements. This also has the handy effect of displaying any UI partials that are visually hidden with CSS.

Lighthouse

If you’re running an up-to date version of Chrome, you probably already have Lighthouse because it’s built right in! Open devtools and go to the ‘Audits’ tab, hit the ‘Perform an Audit’ button and you’re given a list of the audits that Lighthouse can perform, we’re only going to run the accessibility audit to save time.

Lighthouse is a bit more lenient than WAVE for this sample UI, only complaining about the alt and tabindex issues. It does show affected markup but doesn’t do any highlighting or jumping to the affected elements in devtools. It’s also the slowest test covered here.

Interestingly, Lighthouse uses axe-core (which we talk about next) for its accessibility audit, but I suspect doesn’t run the full set of ~70 tests that the aXe extension does, I need to look into this a bit more…

aXe Browser Extension

I’m a big, big fan of aXe, the extension adds a new tab to Chrome’s Dev Tools with a big blue ‘analyze’ button, once you hit that you’re shown a very nice list of issues (I’ve filtered to just show violations here, but there’s also a list of other things to review) with really useful related information.

Each issue show the related markup clearly, hitting ‘inspect node’ jumps right back into the elements tab of DevTools highlighting the element.

aXe rates the impact of a11y issues differently to WAVE, in this example the alt-text issue is critical, the tabindex issue is serious and the others are moderate. It’s worth noting that this presentation compells me to resolve all of the violations because it tells me there’s nine of them, rather than WAVE telling me there’s one error and nine alerts.

aXe also lists things for review, which don’t specifically cause a violation of accessibility guidance but may need to be considered based on the actual context of the element within the UI. The galaxy image behind our sign-in UI is actually a video which doesn’t particularly need captions or an audio-description track, but perhaps it needs marking as purely presentational only. I can’t do this yet because we use a third-party library to inject the <video> element, but it’s something for me to review in the future.

Interestingly, aXe is smart enough to know that the blue box containing our form has opacity (0.9) with an image behind it. The colour contrast issues are flagged because the tool can’t guarantee the background colour would allow the required contrast level of the foreground text to be met (it does, but it’s useful to be reminded to check).

WCAG Accessibility Audit Developer UI

It only checked four things, and passed them all. In the bin with you.

SiteImprove Accessibility Checker

SiteImprove is very popular in the waters in which we sail (local & central government, higher education, not-for-profit etc…) so it’s very useful to have a SiteImprove tool to verify the accessibility of our UIs.

This tool gives a lot of relevant information about issues, though I find the way it’s listed to be a bit more difficult to scan and you need to click into an issue to get the detail specific to that issue, then back out to the main list to see your issues. I do prefer aXe’s master/detail view but SiteImprove does the best it can with the single column constraint.

Tenon.io

Tenon is different as it’s a web service you can use much like the W3C HTML Validator we all know and love, but for accessibility. Simply give it a link or paste in the markup of your UI and it’ll generate a report for you. There‘s multiple (paid) ways to integrate Tenon with your build tooling or CI servers, but that’s meat for another blog post.

It’s slower than the in-browser tests, but the main caveat when passing the URL to the browser version is that it needs your site/UI to be publicly available to Tenon. For now I’m just going to use ngrok to create a temporary public URL to my localhost, and give that link to Tenon.

The scores on the accessible doors?

Barring one shambolic effort, all of the tools gave fairly consistent results for this—admittedly limited—UI test. For me to give them some form of ranking it came down to how the information is presented and what tools it gives me to resolve the issues it raises. Realistically there’s no silver bullet and we’ll likely use most if not all of these tools to sanity check each UI, but the first tool I use in nearly all cases is the aXe browser extension in Chrome. The information is clear, well organised and the highlighting and dev tools integration make it the best tool out of the ones I’ve tested so far. I’m also very interested in integrating aXe core or Tenon.io into our CI process in the near future, for more automated on-going testing.

So in terms of results, my personal order of usefulness is:

1. aXe
2. SiteImprove
3. Tenon
4. WAVE
5. Lighthouse*

*I wouldn’t write-off Lighthouse as irrelevant, as long as Google keep updating the number of audits it will continue to improve.

The fixes

So I know I have things to fix, and to be honest I’m not going to bore you with those, I’m only going to use aXe during my initial pass and then see what the other tools tell me.

The fixes, in brief, involved:

• Adding alt-text to the ‘Continuum’ brandmark image
• Add <main> wrapper around the content to act as an aria-landmark region
• Change the ‘Pulsar’ text into a h1 heading (with CSS fixes to maintain size)
• Remove a bit of javascript which added incrementing tabindex values (1, 2, 3 etc) in favour of simply 0 or -1
• Added id attributes to the ‘forgot password’ and ‘sign in’ forms to act as the target for the related skip-links

After those fixes, let’s take them for another spin in the testing tools.

aXe = No violations 🎉

WAVE = no errors, no alerts 🎉

Lighthouse = no errors 🎉

SiteImprove 💥

OK, so SiteImprove still isn’t happy…

First, let’s drill into the issue with contrast, earlier using aXe we saw how it couldn’t figure out the colour of our background because of the opacity of the container, but that’s not what SiteImprove is complaining about…

SiteImprove thinks that the background of all these elements is white, in all honesty I’m not sure why but my first thought was that perhaps it’s ignoring the video and the fallback image isn’t loading, but the background colour on the underlying body element is, of course, white. So setting an explicit colour for the container underneath the video keeps SiteImprove happy in this instance, and catches any situations where both the video and fallback image fail to load while keeping the white text visible. A worthwhile fix.

Next up, bypass blocks.

SiteImprove wants me to put a top-level skip-to-content link in which we could do with across our entire UI, so that’s an easy one to check off.

Lastly, that aria-atomic thing, we use a aria-live region using role="alert" (the ‘Pulsar’ text) to change to display warnings or errors as the user is attempting to sign in, any change to the content here is announced by screenreaders.

Adding aria-atomic="true" makes sure the screenreader announces the whole region if part of it changes, we don’t actually need it in this case but SiteImprove doesn’t know we’ll always update the whole region, so it’s good to reassure the tool that it’s going to happen and to guarantee the behaviour in screenreaders.

So a few more quick tweaks and we’re done! SiteImprove is happy!

Tenon.io 💥

Lastly, a few more nitpicky bits from Tenon…

The first two are in relation to field labels not being unique. Both our sign-in and forgotten password forms ask for a username and Tenon gives us the correct advice about wrapping them in a fieldset, however after doing so it still flags this as an error at the time of writing. I believe this is a bug and have fed this back to Tenon support.

*Update* Since publishing, Tenon have confirmed this is a bug and will fix it in an upcoming release.

The other last one is complaining about a href="#" in some example code for this UI, Tenon complains loudly about absolutely every instance of using a hash symbol as a href so if you’re wanting to test prototype, sample or demo code you’ll find yourself mopping these up all over the place.If you’re using <a href="#">something like this</a> as a trigger for javascript behaviour you should consider using a <button> instead, or if it absolutely has to be a link then maybe you need an actual link as a fallback for when js doesn’t load instead of an empty hash. There’s normally never an actual time for you to use href="#" in production code, so it’s good that Tenon catches this.

Findings

After experimenting with this range of browser based accessibility testing tools, the most important thing to take away is that no one tool gave me a complete list of issues found by the others, you really do have to test in multiple tools.

I’ve pretty much adopted the aXe browser extension as my primary testing tool, once I’ve resolved any issues there I move onto SiteImprove, Tenon.io and then WAVE. This allows me to clear up a great deal of accessibility issues in our user interfaces and clears the decks for us to perform device testing with assistive technologies such as screen readers. More on that soon.

And once more, for those skimming to the end of the article to find the answer sheet, my personal order of usefulness is:

1. aXe
2. SiteImprove
3. Tenon
4. WAVE
5. Lighthouse

If there’s any other tools or methods you use to good effect, please do let me know!

Which accessibility testing tool should you use? was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

I recently did a chunk of work on the Pulsar design system to improve how we align form elements against a common 12 column grid, and all sorts of fun little things crept out of the woodwork that we’re still tweaking.Normally, when you’re styling up your forms you’d add padding to both the left and right sides, right? It’s pretty much standard practice everywhere.

Previously, we used specific pixel values to set the widths of our inputs which—while great from a consistency point of view—was awful in terms of responsiveness. We worked out a responsive 12 column grid, three of which would be our main form labels, and the remaining 9 made available to form inputs, with the default being set to 4 columns wide.

When we used pixel widths, our inputs were designed with internal padding on both the left and right edges, which was fine when we could rely on a developer choosing the most appropriate width class, like .form__group--small to suit their expected input widths.

However, that padding caused us a problem when we allowed form inputs to be completely responsive, growing and shrinking based on the widths of the responsive columns, depending on the width of the value there’s a chance that when the text overflows, the right hand padding hides the fact that the value is overflowing.

Luckily, we’re able to fix this easily by removing the right hand padding, allowing the value to extend right to the edge of the input. If, at some point, we add RTL language support to our software then we’ll need to remove the left instead.

It’s not as visually pleasing, but it makes it much more obvious that the value extends beyond the visual container and does as much as we can to remove ambiguity and the opportunity for error.

Making form inputs more obvious by removing padding was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

In part 1 I explained how we use unit tests to validate that the markup generated by our design system components matches our expectations from one release to the next. In this part, I’ll show how we check the visual presentation of those same components.

We start again, with a button.

Our humble button has 8 possible main colour variations, things like btn--primary, btn--success, btn--danger, etc. It can also have a number of other modifiers, like btn--outline, btn--small, btn--naked or is-disabled and it could have one, multiple or all of them at any one time. Oh, and don’t forget active, hover and focus, yeah?

You want a small, primary, disabled, outline button? We got you.

Certain classes need to take priority over others, regardless of the order in which they’re applied by the developer coding the UI. That’s a lot of variations to check, and a bit of a cascade jigsaw puzzle to code up; we’re pretty protective of the colour combinations for the default states because they all meet the WCAG 2.0 AA standard for colour contrast, Something which we aim for in all our user interfaces.

So if you use…

btn btn--primary btn--outline btn--small btn--disabled

…it should result in the same visual styling as…

btn btn--disabled btn--outline btn--small btn--primary

To test this I’ve set up grids of buttons, mapping out the various combinations of classes so we can visually scan through them while also checking their interactive states.

I have a page full of button combinations, 384 of them in fact. So many, that it’s unrealistic to expect anyone to visually check these for each release to make sure nothing has changed. So it’s time to employ one of my guilty pleasures—Visual Regression Testing 🙌

Remember those Twig fixture files we previously used with PHPUnit? I use the BBC’s Wraith tool to take screenshots of each and every one. Wraith uses a headless version of WebKit and stores those images as a visual baseline—a defined and verified standard that we want future screenshots to match; Unless we’re making explicit changes, of course.

Every time we make changes to a stylesheet we can re-run Wraith which will take a second set of snapshots, then automatically compare them against each other and report any differences, no matter how small.

This means that if one of our 384 buttons suddenly got a different label colour than we were expecting, Wraith will tell us. If one of the buttons suddenly became wider by 1 pixel, Wraith will tell us.

Wraith is that annoying colleague who hovers over your shoulder and points out the tiniest difference, but only when you ask it to, which is nice.

Shall we play a game?

Here’s two screenshots of that button grid but I’ve made a change, can you see it? Try not to scroll down too much until you’ve had a good look…

Figured it out yet?

I can’t tell, but Wraith can.

I lightened the label colour for the naked buttons by 1%, too small a difference to be detected by my eyes, but more than enough for a computer to notice. Admittedly, I had to dial Wraith’s tolerance all the way down to zero to get it to pick up this small of a difference (you can tell it to work with a certain percentage ‘fuzz’ factor) but I wanted to make a point ;)

At the end of the process we’re informed about any failures, although failures is a strong word as they’re just “differences”, it’s down to us to decide whether those differences are intended or not. We’re even given a handy HTML gallery of all the screenshots to easily work through and visually check whatever it’s found.

Spend time setting up a safety net

If you work on a design system, however large, spending time learning and setting up a tool like Wraith will reduce the amount of time you spend manually checking your components every time you make a change, and it’ll let you release with more confidence that unintended changes haven’t leaked out to other components.

No-one likes leaky styles

We don’t use visual regression testing to fail builds, but it’s becoming an extremely valuable safety net to run before committing changes or performing a release of our design system. We’ve all had issues where a change with CSS is one place affects other components in ways we weren’t expecting, and Wraith helps us catch those.

There’s an investment to be made in setting up the tests. We were lucky enough to be able to tap into the hundreds of helper tests we already had and make them work in Wraith too, and we’re now adding tests cases (like the button grids) purely for the visual regression testing.

Finally, the biggest benefit I’ve found is during refactoring. I’m much more confident in making larger-scale changes because I can run my visual tests and have Wraith check all of my components for me.

Testing for unforseen visual change was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

We have lots of components in our Pulsar design system, but for this post I’m going to focus on just one. The button.

Buttons are prolific in our software, they do lots of different things and they need to be consistent, recognisable and predictable. Our buttons can have a handful of classes applied which define the colour (primary, success, danger etc), visual variations (small, outlined, naked) and the state (disabled, active) as well as the normal set of interactive states that a button needs to support (hover, active, focus).

We test lots of things about our humble little button, like:

• Is the markup generated by the button helper correct?
• Does the CSS render the button variations correctly?
• Do all of the colour combinations match what we expect?
• Has anything else changed that we weren’t expecting?

Part 1: Testing the markup

We use the Twig templating language which gives us a lot of features to play with but the main one we take advantage of are macros, although we call them ‘helpers’ within Pulsar.

Helpers let us provide, for want of a better description, an API for the UI. Instead of using the raw HTML markup for a button in a view, we can call the button helper with a set of options, and the relevant markup will be created for us when the page is viewed in-browser.

This helper:

{{
    html.button({
        'label': 'Foo',
        'class': 'btn--primary'
    })
}}

will spit out the following HTML:

<button class="btn btn--primary">Foo</button>

I know you’re probably wondering “why is this any better than normal markup” and admittedly, a button is probably the least impressive example I can give (form elements have a good amount of wrapper markup), but we’ll keep it simple with buttons for now.

There’s a few documented options that a button may have. Supply 'type': 'link' and you’ll get <a href="#" class="btn btn--primary">Foo</a> instead of <button>, as well as different markup for input and submit types too. We need to test all of those to make sure the markup created by our helper is correct, valid and that any other supported options like disabled are added as correctly formatted attributes.

We have a suite of fixtures, which consist of a .twig file (the input) and a matching .html file containing the expected output. The Twig fixtures all run through PHPUnit and their output is matched against the ‘expected’ HTML file. The Pulsar repository has hundreds of fixtures being tested in this way, everything from buttons to more complex components like the primary navigation module.

As an example, if I intentionally add a newClass class to the helper and run PHPUnit again it will fail any fixtures that weren’t expecting a button with newClass. If the change is expected, I can verify which components are depending on the button helper and may be affected by the change or, if the change to the helper wasn’t expected, I can fix that instead!

Taking the time to write unit tests for our helper markup helps massively when it comes to refactoring and bug fixing, we can quickly run the test suite to confirm that our changes within Twig have not affected the markup in ways we weren’t expecting.

But wait, there’s more!

Twig is a PHP templating language but there’s also the Twig.js javascript implementation. We want Pulsar to be usable in Node projects so we run the exact same set of PHPUnit fixtures through Twig.js to make sure the markup is still fine (when we first did this, the markup was wildly different, but thanks to a couple of PRs being accepted into the twig.js project, it’s fine now).

What next?

So we have this comprehensive fixture suite pulling double-duty, testing our generated markup is correct in both the PHP and JS implementations of Twig. In my next post I’ll show how we use the same fixtures again to test the visual output and let us know if anything changed, right down to the pixel.

Header image from Black Mesa, used under fair use.

Testing our design system components was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

“Don’t break the build.”

The mantra you’ll hear often if you work with a continuously integrated product. Design systems, frameworks, pattern libraries or whatever we’re calling them this week usually live outside of the product(s) in which they’re used. They’re products in and of themselves, with their own team, their own backlog and their own release cycles. Updating to the latest version of your design system should rarely, if ever, intentionally break something which you previously supported.

Hell hath no fury like a developer who’s build breaks with a minor patch release of a dependency. Similarly, you’ll suffer scorn if you’re constantly releasing major versions because of the amount of breaking changes you’re publishing. The Pulsar design system got to version 6.x.x pretty quickly when we first started integrating it with our existing software products, but has stayed stable there for quite a while now because we’re increasingly focused on not breaking things. Which is generally a good thing for everyone.

Now, that’s not to say we don’t refactor things, or even remove things altogether, we do it all the time! We just take a few steps to make sure that the changes we make are as minimally disruptive as possible. The following process we use for retiring components may come in handy for you.

Retiring components

If you’re like us, you’ll have a lot of components with their related Sass files, every now and then we’ll go through ours and check they’re all still being used. After all, software features get retired and things get rewritten into newer and better alternatives so sometimes we need to just get rid of older components from the system.

Pulsar has a main Sass file pulsar.scss which imports all of the individual components but this is a reference file and not used in production. Each Continuum product has its own version of this file only importing the specific components they require, as well as adding any product-specific code they may need which aren’t appropriate to keep in Pulsar.

Say we want to remove a component no-one wants anymore, let’s call it _component.millhouse.scss, simply removing this file from the Pulsar repository would break the build of Continuum products attempting to import it.

!optional imports still aren’t a thing in Sass, unfortunately, so we take a few steps to gradually phase Millhouse out over a few releases.

1. Move the contents of _component.millhouse.scss into _deprecated.styles.scss

All Continuum products include this deprecated styles file, we include docblock-style comments to explain where they came from, why they’re being deprecated and the date which they were moved. This is useful for the later step of cleaning out the unwanted styles when we’re confident they’re no longer referenced in production.

/* -------------------------------------------------------------- *\

04/07/2016 - Paul Stanton

_component.millhouse.scss

Millhouse component replaced by Nelson component.

\* -------------------------------------------------------------- */

.millhouse { ... }

At this point we’ve not broken the build, but our final CSS output still contains the .millhouse classes, we need to warn people that they’re being phased out.

2. Communicate the change

We publish release notes with each Pulsar version listing new features, bug fixes etc, and if we’re planning on removing something we mention it here too. But not everyone reads your meticulously crafted release notes so you can never guarantee someone will notice your warning.

Remember that empty _component.millhouse.scss file? Time to put it to use.

Sass has a handy @warn feature that lets you throw warning messages during compilation, we add a warning message inside this file informing product teams that the component is being phased out, and that this Sass file should be removed from their imports.

@warn '_component.millhouse.scss has been deprecated and needs to be removed from your main pulsar.scss file. UAT teams should not treat this as a build failure. (Stanton, 04/07/2016)'

If you’re lucky enough to have dedicated test engineers, you’ll know that their finely tuned spidey-sense tingles whenever they sense a disturbance in the build, even though @warn will not trigger a build failure, it’s enough of an error to make them rightfully err on the side of caution and possibly fail a ticket. We include a message asking for it to not be treated as a build failure, but something that should still be followed up. Again, we put our name and date on the warning which helps the teams know who’s responsible for the warning and give them the chance to ping them on Slack, for example.

3. Remove the @import from the product

Each product team at Jadu has a Pulsar team member working within it, it’s usually us that will create a ticket and pull request to remove the reference to _component.millhouse.scss from the product’s mainpulsar.scss file. This then goes through the usual process of peer review and testing.

4. Remove the .millhouse code from _deprecated.styles.scss

After a while it should be safe to remove the .millhouse styles, normally we’d search the codebase for any remaining references of it in the products before we do, again, trying not to break the build, and typically we’d do this at the start of a sprint so that any unforseen regressions would hopefully surface during the course of regular work and testing.

We do visual regression testing on changes like this too, which helps to identify any unexpected consequences.

5. 🎉

Job done!

We’ve done this a few times in Pulsar to allow us to gradually and safely remove older code that may still be referenced in production, without the need to resort to releasing a new major version each time. If you have any better suggestions, we’d love to hear them!

Retiring pieces of a design system was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

Pulsar is the open-source design system powering the user experience of the Jadu Continuum platform. Sounds fancy, but what does it really mean?

Jadu software is used in large organisations, it powers hundreds of local government/council sites as well as some in central government, higher education and commercial sectors. There are thousands of people who use our software every day to deliver sites and services used by millions.

The Jadu Continuum Platform currently consists of the following main products:

• CMS — Content Management System
• CXM — SAAS based Customer Experience Management
• XForms Professional — Secure Forms

Customers may have one, two or all the Continuum products, and some of their users may access one or more of them as part of their job. It’s important to us that each product maintains a consistent, familiar experience even though their main features may differ. Simply put, you should be able to jump into a different product and know your way around.

Each product has a dedicated team of developers and testers, and each team has a Pulsar team member responsible for designing the user interfaces for new features as well as looking after the design and experience of their team’s product as a whole.

We developed the Pulsar design system to provide a single framework that all products use to deliver consistent, stable and well designed experiences. Jadu engineers have well documented methods to create everything from a single button up to more complex components all coming together to make full user interfaces.

We design in the open as much as possible, publishing screenshots and wireframes on a Trello board with a rough idea of their progress from conception to delivery, we have public documentation and of course, all our code is on GitHub under the MIT license.

All of this is to engage more with our customers as a design team, giving them the opportunity to get involved in the early stages so that we can learn any particular requirements that we may not have thought of.

Pulsar — The design system for Jadu was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.

It happens every year, almost always at the same time. Autumn kicks in, the weather starts getting cooler, and my mood swings upwards so much that I never fail to notice how much happier I’ve suddenly become and start commenting on how Autumn is my favourite time of year.

It’s only recently that I’ve realised this upswing for what it really is: Recovering from burnout.

I don’t know if its a seasonal affective thing each summer or just coincidence but I definitely feel the change when its over, I just don’t really realise it at the time.

When I think about the effect that burnout has on me it always seems to be my right brain that’s affected more, my desire to create, design and make awesome things takes a back seat for a while. Its not that my creative output entirely vanishes, I still need to function as part of a creative team, but I do feel less of a desire to do certain things, especially outside of work.

Fortunately enough, I still have my left-brain pick up the slack and keep me productive (and employed). I instinctively swing into the more of the technical side of my job for a while; writing more code, tests, documentation or looking at things like our build process with a renewed intensity. Over the past few weeks I had a whale of a time implementing visual regression testing on our design system, something that I wouldn’t have had much interest in looking at if my creative brain was taking the lead.

I’ve been thinking about what I could do to plan around this for the next time. Perhaps while my internal pendulum is over in my right-brain I need to stockpile my creative output ready for the swing into my left-brain, when I’ll have the technical mindset to develop and implement the backlog of things I’ve got ready to build out.

Hopefully I can figure out a way to prevent creative burnout from affecting me for so long, whether that’s making time each week for purely creative ventures when I’m in left-brain mode, and vice-versa, by forcing myself to do technical tasks when I’m in right-brain mode. The first step is understanding, now it’s time to find some form of healthy balance.

Let me tell you something, pendejo, by the time you’re reading this Pulsar version 3.0.0 should’ve been tagged and released and it was very cathartic. After using Pulsar in anger on the MoJ and Q projects for the best part of two years we learnt a hell of a lot about what it takes to write a UI framework that needs to work across multiple products and now I’m taking the time to fix and polish up a lot of things before we start to FINALLY bring Pulsar into Jadu CMS.

Originally, this blog was only ever meant to be available internally at Jadu, so there’s a lot of inside baseball here and I apologise. In the future I hope to write more about our process, how we’re building our user interface platform and how we’re changing everything to make sure our software is beautiful to use, as well as great to look at.

Originally, the idea for the Pulsar UI framework was there would be a nicely compiled package that would be either hosted or distributed and that a Jadu product like CMS or Q would simply include this package, then add its own stuff on top. This turned out to be rather naive and fell apart as soon as we started thinking about theming Pulsar for the TPT Portal. If Pulsar was only distributed as a ‘built’ package, anything we’d have to do to theme the default styles would have to be overly specific to override the default selectors. Even something as simple as changing the font stack would have to be written as an override.

Now each product is responsible for compiling the Sass and has the opportunity to insert their own theme files into the build and override any base variables (all Pulsar vars now use !default) or to add completely custom Sass that doesn’t necessarily belong in Pulsar core, which is intended to be common across all Jadu products.

I plan on writing a bit more information about how Q extends Pulsar with its own custom components and how it all gets pulled in and built with the magic of Composer and Grunt, but that’s a post for another day. I also want to share more about what’s going on in Pulsar and the work we’re doing to improve the experience of our software for our users as well as improving how we communicate what’s changed for those of you already using Pulsar, so expect some nice changelogs coming your way soon.

So to catch up, some recent highlights (not just limited to 3.0.0) include:

• New html.panel component
• New html.label_group component
• Rewrote all helpers to remove the need for named arguments, now everyone gets along nicely
• Made all helpers compatible with Twig’s strict_variables mode
• Added an AttributesParser Twig extension to simplify how html element attributes are passed around inside macros
• Added new excludes() and only() array filters for Twig, now you can be a bit more bossy about what your arrays do
• Switched to the official twigphp/twig repository instead of jadu/twig which was a fork of fabpot/twig (did you follow all that?)
• Went through the 12 step programme and removed the Bourbon dependency from Sass
• Remixed the state colours (success, error etc) to meet WCAG 2.0 AA guidelines for contrast ratios, you can now read the text, which is nice
• Made buttons look pretty (buttons used to use Bourbon’s button styling, eww)
• Updated popover styling to make them a bit sharper and standouty (totally a word)
• Added Vagrant hawtness for running the Pulsar development environment in a VM like the cool kids
• Did a blog

Macro Madness

This is a biggy, and worth talking a little about. Since we first decided to use Twig as our templating language there was a known issue with using named arguments in inherited templates, I was able to ‘bodge’ a fix which, although it fixed our specific needs, didn’t address the underlying cause within Twig, the fix for this seems to have been pushed for the Twig 2.0 release so we couldn’t wait any longer, things had to change.

So over the past couple of weeks I’ve been rewriting all helper macros, which was a bit of a grind but absolutely necessary to remove that technical debt before we start plugging Pulsar into the CMS in the coming weeks. While I was in there I generally tidied, DRYed and polished things up, wrote a load of documentation and added the ability for almost every macro to support common options like Classes, IDs and data attributes which was only done on an as-required basis previously.

The macro syntax has changed too and arguments are now passed through a hash.

html.button({

    ‘class’: ‘btn—-primary’,

    ‘label’: ‘Click Me!’

})

Unfortunately this does mean some work will have to happen to update all views using the old macros, but to mitigate the impact of this, Pulsar’s macros (effectively, its API) will be versioned so that a product (like Q) can have some views running v1 while others are updated to use v2 and not have to lock their Pulsar dependency to ~2.* and miss out on any new features or bug fixes. Once the relevant teams sound the horn to say they’re no longer using v1 macros, they’ll be removed.

The new versions sit in a v2 directory, the actual path will depend on how you’re pulling Pulsar into your product, but for example:

Version 1

{% import ‘@pulsar/helpers/html.html.twig’ as html %}

Version 2

{% import ‘@pulsar/v2/helpers/html.html.twig’ as html %}

Think you have what it takes to work on a UI platform that will be used by a company full of engineers across many different products?

You should totally talk to us.

Polishing the pulsar was originally published in Pulsar on Medium, where people are continuing the conversation by highlighting and responding to this story.