1. Publish components, not styles. This has been rehashed in other HN threads, but the idea is to provide Lego blocks to help engineers build UIs more quickly. This might be out of fashion with Tailwind adherents but we found success by treating the framework's primary interface as React/Vue/JS, not CSS.
2. Be transparent and receptive. Share your goals with consuming teams and ask how you can help them. They might ask for specific components or might ask you to help them convert a UI to use the library. By demonstrating that you and the library are there to serve (as opposed to dictate) you'll earn goodwill and your work will have more impact.
3. Have high-quality components. This applies to the UI design (both how the components look and how they behave) and software design. Are the props intuitive? Do the components compose well? We were fortunate enough to have a strong design and engineering team that did well on this points.
4. Seed the consuming codebase. Patterns in codebases propagate because engineers like to copy/paste. For example, start by migrating all buttons in the consuming codebase over. Then migrate over all forms, modals, and so on. It also helps to take a vertical approach, by migrating a single view entirely over to the library, or building one from scratch. This can get people excited about the library because they can see and experience the end result.
5. Ensure compatibility with the existing codebase. Make sure styles don't collide, make sure the underlying JS libraries are compatible. I chose React for EUI, but the consuming codebase (Kibana) was Angular. We made the decision to convert Kibana to React too, but there was a temporary period where we mounted React components inside of Angular. We needed simple guidelines to support the engineers who were doing that.
I appreciate your points. Can you share more about how you interacted with other teams? Did you have resources to help implement the components into products? Did you use any tools or meeting formats to gather feedback and listen to needs?
Unfortunately most of that lesson isn't generalizable. No matter how much Salesforce wanted Lightning to be the next Bootstrap, it was never going to be the next Bootstrap. That's a tiny niche.
That said, as a developer who has gone through several cycles of designers trying to force me to buy into whatever their latest "company wide" component library will be, there are still lessons from Bootstrap to take away starting with the big one: treat it like a product and a service. Treat the rest of the company like your customers and prepare for dealing with complaints, needs, and desires as customer service.
Some related bullet points:
- You are only as good as your documentation says you are. Documentation should be a priority. Documentation should be accurate and up-to-date.
- Have a compatibility plan. Internal branding changes on a whim, don't take that out on your customers. Find ways to support easier transitions from whatever old styles exist. Find ways to make sure that no matter what changes updates are clean and easy with as little rework as possible. Especially that last part, don't hose your early adopters by making them redo everything for "the real production version". Just like with any product launch, your early adopters can be one of your best marketing tools and you can't point to how much they like using your library if you put them through a ringer of rapid changes and constant update struggles.
- Treat as much of the communication as possible as product marketing. Don't tell developers why they "need" or "must" adopt your central styles, sell them on why they should "want" to. Sell an experience of working with it. Sell the features that they can't get from off the shelf tools or the things they might already be using. Mandates from managers and product staff can sometimes get things done faster than marketing and salesmanship can (assuming managers and product staff have the time and money budgets for it and an "all hands do this"), but it doesn't create lasting buy in (especially if it creates resentment) and it doesn't build lasting trust in your project or team (it can generate the feeling that because managers/product did it this time, they'll do it again when the next branding fad or corporate whim comes to mind and they have an excess of budget).
- An internal branding product is only as good as its reach: Can you support the widest variety of technology stacks inside your company? How far back into legacy apps can you reach?
- Can you support the widest variety of technology stacks inside your company? Too many times I've seen these branding products die in the meetings of trying to crown a "best framework" or "chosen tech stack". As a design team, that should never be your role to tell developers what technology to work with, you need to meet them where they are. (In terms of modern technical suggests, CSS is universal and HTML snippet copy and paste can be easily adapted everywhere; if you need to include interactivity in your comments try for as Vanilla JS as possible. Web Components and micro-frameworks for Web Components such as Lit and FAST can be great tools here with wide reach now.)
- How far back into legacy apps can you reach? There's great reason to not want to support IE11, but if your company's internal users are still spending most of their day in IE Mode in Edge to get "real work done" that's what you need to support. Sometimes it is terrible to build for the true lowest common denominator, but the unfortunate corporate reality is that your lowest common denominator will always reflect your overall success in something like component sharing or internal rebranding. On the other side "even 'Legacy App X', that developers hate working on and try to only touch with a ten foot pole, had an easy time adopting some of the new components" can be a great part of a marketing pitch to other teams.
- Maybe try to start with the lowest common denominator and the hard problems: your early adopters should be complex and legacy and excited to spread the message if you did a great job solving their hard problems in their ugly lowest common denominator parts of the company's tech stack. The easy stuff will follow by peer pressure in those cases. (The reverse is far less likely, the hard apps will scoff at the all the easy ones switching to the new stuff as just fad followers and trend sheep. They've seen it before, they'll see it again, their own apps will still be chugging along with same classically bad styles then too.)
- Document everything like a product for external vendors and cheap consultants and pet open source projects. Treat questions/complaints/concerns/desires/needs like product customer service. (Have customer support tools ready on Day 1.) These two I think are important and bear repeating.
I’m very much on board with the “thinking it as a product” and I think we’re actually going to be in good position to sell it to other teams since they’re being forced to adhere to common designs - there’s just no help or implementations to get them there. So even if we don’t build something they find as good as their favorite library, we’ll have the upside of being the one that adheres to the design.
I also like your thoughts on “customer support” and I’m considering whether doing hands on help for the teams migrating would also be worth it.
I’m still pondering whether starting with something really hard or doing some of the easy stuff is the right way. Starting with easier stuff would allow us to build a foundation, get to the point where the library is actually installed across products, which could help establish some feedback loops. That said, I really like your point about targeting the most legacy apps. As you say, that might create of following of people that appreciate the work and would spread the word.