Arch Lunch with Julie, Hubspot Design System lead - 2019-01-09

Questions for Julie and her team

  • Journey
    • What was their Journey? from where they started to where they are now
    • How much effort/what was the timeline for the creation of Canvas?
    • Remaining rough edges?
    • False starts?
  • People
    • What has been the reaction/adoption?
    • How many people?
    • What % of code is using Canvas?
    • How do they work with UX, product, a11y?
    • Who did they build this for - developers, customers?
    • Adoption
  • Component management
    • How are the components deployed to production?
    • How are they managed in GitHub repos? 1 repo per component or 1 mega-repo?
    • Is Canvas versioned in some way?
    • Are there any issues / innovations around being able to consume the components in multiple dependent repositories?  ( comes to mind)
    • How do you handle the need for custom functionality and styling and ensure that the integrity of the design system is protected?
    • Related, as you continue to live with Canvas, how do you decide what constitutes functionality/UX affordances that should be built into the design system, vs. work that should remain a one-off?
    • Ongoing maintenance
      • How do new components get added? dedicated team vs feature dev teams
      • Maintenance & updates to components - sustainment team
  • Drawing boundaries
    • Small number of primitives or large number of variations?
    • Include compound components?
    • How configurable do you make components
    • Microfrontends - how do they split their frontends?
    • How to do they decide the size of their components?
  • Technical concerns
    • How do they handle styles? Inline JS?
    • How do they measure performance, if at all, at the component level?
    • How is localization handled, if at all, at the component level?
    • This is diving a bit, but have you established any best practices around how to structure form data state with UIForm and its inputs?  Controlled components with state stored in the form?  How does that get extracted from the design system's components for submission?
    • Responsive design / mobile considerations?  Media queries?  UISelect, for instance, says to use a native select where appropriate.  How often does this sort of thing become a problem in your experience?
  • A11y
    • To what extent does theming support or enforce contrast requirements?
    • Any consideration for Windows and Chrome High Contrast Mode?
    • Focus management -- how can you make it work with dynamic documents?
    • What are the preferred architectures for plugins when the Canvas isn’t providing everything needed?
    • Are they doing any browser/screen reader compatibility testing?

Meeting Notes

Our Guests:

  • Julie - Tech Lead of design system - Canvas
  • Chris - 
  • Joe - 


Started in beginning of 2016. Started with the design team. Putting together two large pieces together into one, wanted to create a consistent design language and consistent component infrastructure.

Did an audit to put together everything that was necessary. Created the components.

Once the apps were on react, they helped product teams move to the new components they'd developed. In that process they found they needed to create new components or add to existing ones.

There's constant maintenance.

No new features while they worked with specific teams.

Took from mid 2016 - mid 2017.

There's about 200 front end developers and 50 designers

Remaining rough edges? False starts?

Decide what you want to start with knowing you'll have to change it later. After the initial adoption there's the continuing process of smoothing things out.

There were no false starts. There was company buy in from the start.

Before the effort there was a developer who produced some reusable components. It was small scale - not company wide, it informed the design system effort.

Flexibility vs. consistency is a constant balance. Autonomy is valued at HubSpot. Thinks it may be good to start more prescriptive, forces people to think, "Do I need to make this different?"

How to square autonomy with requirement of using the system. There's no "requirement" but people are highly incentivized – never really had to argue about it. There were likely conversations at the beginning asking the question of "Why is this important?" For developers it meant ease of use. For design it meant, decisions will scale across the product quickly. For PMs excitement about a quicker development process.

Most convincing was needed to get PMs to hold off on feature development to switch over to the new library/system

When creating the system, there weren't many designers. This helped because everyone had a voice in it – without too many people working on it.

One thing that helps keep everyone on board is that people come to spend a 3 month stint in the US office.

How long did it take to convert the front end to the system?

Depends on product size. Cruft. How much help from the teams themselves. How many new components were needed.

On average maybe 3 weeks to a month. It got faster over time. 

Each product was already on React when they got around to converting to the new system.

Process of switching: a beta process allowing people to opt in. They were okay with parts of the app being redesigned and other parts not. 

They don't have to worry about things getting out of date.

Avoid versions. Libraries auto-deploy. The next time each product deploys it gets the new library. 

Some systems allow you to version different components differently. Julie doesn't like that. Everyone will have different components. A huge number of permutations.

They avoid breaking changes. If they need to change a prop, they'll create a migration path. Will update documentation with a deprecated status.

A big philosophy of her team, instead of making product teams adapt to them, they'll help them adjust to breaking changes. They don't want to disrupt those teams.

Other teams will contribute back to Canvas. Some will make pull requests. For the most part it's her team's responsibility. For the design team it's a little different because there's a rotating team working on the design language.

Which parts of the company needed to be part of the discussion about start the effort?

The product management team (+design). To a lesser degree brand and marketing but not as critical.


I see a style guide and a pattern library similar. Mostly recommendations on what and how.

Reusable component library ...

Design language is the same a style guide to me. That was more on the ux team to determine.

If people want to request a new component there's template. People should frame them as a proposal. "I have this problem, I think it could be solved this way."

Have a weekly meeting with her team and the designers to make sure the components are ready enough


Deploy to Prod

Versioning everything together instead of auto-deploy?  Convincing the numerous teams they have to continue to upgrade is cumbersome/annoying/hurts productivity.

Size? 200 FEE, 50 teams, 5 repos each.

May be reasonable to do versioning with a smaller team. But you should make sure you're on top of it.

They have the ability to version, but avoid doing it at all costs.

Does everyone have a package lock to get non major versions? HubSpot has a special system, but effectively that.

How do you handle visual regression testing?

This is the hardest problem.

There is no QA at HubSpot. They'll do testing.

They make there components in a declarative way. To help them see every state of the component. This helps test for writing visual regression tests. Takes screenshots of components in browsers and view diffs of the screenshots.

styled-components instead of sass is helpful for avoiding problems when making variants.


I think that's the most important part of a design system.

Their documentation is an app that looks at prop-types etc. Write example specs in the components themselves and the documentation site consumes them. One nice thing about their site is that it's interactive code. They can write all the components right there and see how they'll work. Basically CodePen for their components. Super useful for debugging (can send links around).

Design guidelines are part of the proposal (group effort)

  • when do you use this, etc.
  • ux writing guidelines

Her team is the one actually typing it.


Visual states of the components. We don't mess with APIs. All are controlled components.

For teams using their components and adding business logic. teams can share them as add-ons. Our components: They're "dumb" could be used anywhere

When you include a 3rd party dependency it's better to separate it into another repo. That way not everyone needs to require it. 

Example: UI Modal Component > You can insert a button or a string and it will make one for you. This adds flexibility. In the beginning it wasn't necessary.

How to you handle styles?

Started with the standard Sass bundle. BEM naming convention. All components should be self contained. Would have created a stronger css name space if he were to do it again.