Why Talla Hacked Our Own Onboarding Joyride Framework to Be LESS Precise (Then Gave it Up Entirely)

Posted by Hart Neray on Aug 7, 2017 11:01:18 AM

There's always been a tension between web design and web development, as designers want final HTML/CSS code to be pixel-perfect, but there's only so much justifiable effort you can put into fine-tuning a CSS layout. That's especially true when your design constantly changes. We proved this out when developing the onboarding guides for new Talla users.

Onboarding is an area where designers' demands for perfection are usually justified. If you're trying to explain to a new user what a specific button or control does in your application, it would help to point an arrow directly at the control you're explaining. We used the Joyride framework to make this simpler.

Old UI w- Pointer-Talla.png

Joyride can "hang" a call-out overlay and arrow off any CSS element -- so you get a text box that points at the exact element you're describing -- but you have to declare from which direction the overlay will appear. If the element you're describing is on the right side of the page, hang the callout to the left, so it stays on the screen and doesn't obscure something else relevant on the page.

Unfortunately, every time we moved or resized any design element in Talla, we had to tweak the associated Joyride tour component to re-declare from which element and direction the callout should hang. It was also not an ideal fit for CSS elements that don't have a stable size, like our task tickets, which can have a variable amount of text within them, so they may take up wildly different amounts of vertical space.

Given how much and how often we update the features of Talla, and how many dynamic design elements we have, constantly updating the tour guide callouts was a "design tax" we didn't want to keep paying. We'd rather use our development time and effort to get the actual features right.

Instead, we tweaked Joyride to create a generic modal that hangs off an invisible, dummy element in the center of the page. That leaves us the option to ramp up Joyride callouts when and if a design element "stabilizes" into a semi-permanent form, but lets us use a generic modal (that stays useful over time) for items that are still in flux.

Here's a sample code for the dummy anchor element we hang the modal off of:

<div className="tour" style=>
    {/* dummy element used for centering a tooltip on the page} */}
    <div className="tour-modal-centering"></div>
    {this.renderJoyride()}
    {childrenWithProps}
</div>

And …

// Nothing crazy here.
.tour-modal-centering {
        position: fixed;
        left: 0;
        top: 10%;
        right: 0;
        width: 100px;
        height: 100px;
        visibility: hidden;
        overflow: auto;
        margin: auto;
        background-color: rgba(11, 31, 61, 0.5);
}

While Joyride lets you remove the arrow from the callout (so it looks more like a modal), it also wants to put a shadow overlay on the page, with a "hole" over the element you're highlighting. We needed to remove that, too, because it would just be highlighting our dummy modal anchor.

Joyride not hiding hole-Talla.png

// But below..
/**
* Default styling for a tour step that should look like a modal.
* Hides the arrow and the "hole" for the selected element.
* @return - the style object for a React Joyride step.
*/
export function modalStepStyle(){
  let options = {
    arrow: {
      display: 'none',
    },
    hole: {
      // hide the hole by doing some overrides to Joyride's styling (yuck!). Without these 3 lines, Joyride would highlight our anchor element.
      backgroundColor: 'rgba(11, 31, 61, 0.8)',
      boxShadow: '0 0 0 9999px rgba(11, 31, 61, 0.8), 0 0 0px rgba(0, 0, 0, 0.5) ',
      borderRadius: '0px',
    },
    back: {
      display: 'none',
    }
  }
  return _.assign(defaultStepStyle(), options)
}

So, with the code above, we dumbed down Joyride callouts to make traditional modals. Then we tested how well the modals performed compared to the Joyride callouts that gave specific direction.

The modals were just as good. In fact, because we "only" needed modals, we realized we would likely never need to go back to the more-specific Joyride callouts, so we removed the framework entirely -- including all the special code above we needed to make modals work in Joyride -- and just used standard CSS modals for our onboarding tours.

We tried to make the perfect onboarding system, and decided that a "good enough" onboarding modal was, in fact, good enough.

Perfection is brittle is a philosophy I've come to embrace at Talla. This work lets us focus on designing Talla features, rather than constantly tweaking our tour guides to keep up with design changes. And at Talla, we're all about avoiding the mindless, repetitive work that doesn't make best use of your time.

If our mission (and philosophy) sounds interesting to you, check out the open roles on our engineering team.

Topics: Company Culture, Engineering