Button usage updates

[jeanservaas]

Button usage updates. I created a new PR because so much was changed.

Related PR:
#971

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/carbon-design-system/carbon-website/fevb327c4
✅ Preview: https://carbon-website-git-fork-jeanservaas-update-component-doc-205a6c.carbon-design-system.vercel.app

[jillianhowarth]

This looks awesome @jeanservaas. Just a few minor copy and formatting tweaks but overall it looks really great 👏

[joshblack]

Sorry for the delay on this! Catching up today 👀

Something that feels like it's showing up is a misalignment between design and dev on some of these topics, along with a difference in perspective on shipping guidance without code. Hearing that this stuff is in production can be a surprise to the development team, particularly if there isn't existing guidance around it on the site. This feels similar to the inline theming questions that come up.

For this PR, it seems like pretty much all of it is spot-on. The only hesitation from development comes from shipping guidance without code. I wrote out below why this can be concerning and what kinds of challenges our team, and teams who end up doing overrides, run into as a result.

The preference from development would be to take some of these topics and work on them together (design/dev) over the next release (1-2 weeks) and ship this guidance together with code. I feel like we could really nail the end-to-end experience for someone using buttons, button groups, etc. if we did this (guidance, kit, code, docs)

Without this alignment, it would be helpful to have the banner indicate that this is not ready for production use. One idea was:

Note: Some of the examples we discuss here include fluid (full-span) and hanging buttons which are not available for production use. This guidance reflects our current understanding of these topics and we are working towards releasing this work in a future version of Carbon.

Let me know what you think!

---

Guidance without code has several downstream impacts that we've experienced, namely that it creates maintenance issues for teams that attempt to implement the guidance. To quote one of the groups that we're working with:

Pervasive custom styling that overrides Carbon defaults creates maintainability issues.

If a team chooses to override a component, this impacts:

• Any code that we ship that could break their overrides
  • We experienced this issue recently with teams who overrode the height of our dropdowns
• Any updates that we make to guidance won't be picked up by their overrides or custom implementation
• Any work that we ship to tackle the problem is likely to not be used because they have something that works already and is in production
  • This topic was brought up by Phil today when it comes to adopting the replacement of tree view

[jeanservaas]

@joshblack

Happy to change the Note to this:

Note: Some of the examples we discuss here include fluid (full-span) and hanging buttons which are not available for production use. This guidance reflects our current understanding of these topics and we are working towards releasing this work in a future version of Carbon.

As for this, it sounds great, but would this really be doable in the next 1-2 weeks? Would this just address issues with button or with the Narrow grid mode in general. One of the questions/points of confusion for @aagonzales and I is whether this is really a component issue or a grid issue.

The preference from development would be to take some of these topics and work on them together (design/dev) over the next release (1-2 weeks) and ship this guidance together with code. I feel like we could really nail the end-to-end experience for someone using buttons, button groups, etc. if we did this (guidance, kit, code, docs)

And for this part, would you like this to be worked into the copy somewhere... or incorporate the consequence of proceeding without code into the note somehow?

Guidance without code has several downstream impacts that we've experienced, namely that it creates maintenance issues for teams that attempt to implement the guidance...

[shinytoyrobots]

Just to clarify, is;

Note: Some of the examples we discuss here include fluid (full-span) and hanging buttons which are not available for production use. This guidance reflects our current understanding of these topics and we are working towards releasing this work in a future version of Carbon.

the specific text you'd like to see in the disclaimer? And would you also want to call out the risk of maintenance issues from custom coded implementations?

It sounds like the minimum needed here is agreement on a specific disclaimer paragraph that covers our development concerns but allows the PR to move forward (...and then an issue or plan to address the underlying problems that cause the disclaimer to be required).

[aagonzales]

Hearing that this stuff is in production can be a surprise to the development team, particularly if there isn't existing guidance around it on the site.

It is on our site we talk about it on the grid page. We also imply it throughout the website in images. We also frequently mention it when giving advice to designers in Slack and in crits. We also present and talk about it in our Pattern courses that we give to the new hires and also to the industry hires (at least 4 times in the last year).

This is airing some dirty laundry here but its a little concerning to me that dev doesn't seem to be aware of major design concepts we've been preaching for a year+ now. It's in products because we have gotten the word out. Ask any designer not on Carbon and they most likely know about the grid hang behavior. If you don't know about it then you haven't been paying attention.

If all it will take is two weeks to get functioning code up for this behavior then let's do it! Let's not waste any more time talking about dev/design misalignment and let's just get the alignment. @joshblack what are the actionable items you need from design to start working on this asap? What's the next step to taking this forward?

Not shipping button docs, doesn't put this issue back in the bottle. This concept is out there. Blocking these docs won't stop teams from doing overrides to achieve this behavior. We can only help our community by getting this work done asap.

[joshblack]

@aagonzales it hurts as a team member to see stuff said like this:

If you don't know about it then you haven't been paying attention.

I'm trying to share the experience of myself, and the development team where I can. I'm not putting blame on anyone. I only want to make the experience for using this work as simple and easy as possible for teams at IBM, and it hurt to see this in response from a team member.

I'd be happy to work together and see how to fit this into the roadmap for the next cycle to evaluate and ship based on that.

---

@jeanservaas thanks so much for taking a look at the note, glad it works 🙏 To your question around the overrides concern, I don't think that's anything we need to detail to share externally. I just wanted to share what the cost can be for this kind of stuff so our team is on the same page.

As for this, it sounds great, but would this really be doable in the next 1-2 weeks?

I think we could definitely prioritize it and at the very least get a better estimate for the scope and timeline.

For things like fluid, as we talked about last week I think it's something that is definitely feasible to do and could be built into helpful components like button groups too.

For things like hanging, this is definitely less certain as we need to take the time to evaluate this stuff (over in carbon-design-system/carbon#5892) The hope is to use our grid to build out all the awesome examples that you all shared to see what the experience is like. As it stands, it seems like very few teams are using the grid even for pages like IBM Cloud's dashboard that look like they are hitting the alignment guidance specified in the narrow grid section.

[aagonzales]

@joshblack I didn't mean "you" as in directly target at you. I'm sorry for that I meant it in a more abstract saying sense. But I stand by it. Hanging grid components has been a very known and discussed item in the last year or 2. It should not have been a surprise to anyone on our team when we documented it.

Saying we don't have implementation for it yet is fair but saying it was unknown and design essentially surprised dev with this in these docs for the first time is not fair.

[shinytoyrobots]

Let's take the post-mortem about some of the deeper foundational issues outside of the PR.

Within the scope of the PR, can we confirm the desired wording of the disclaimer that we could add that would allow us to close it?

[jeanservaas]

@joshblack

This is the disclaimer I included:

Note: Some of the examples we discuss here include fluid (full-span) and hanging buttons which are not available for production use. This guidance reflects our current understanding of these topics and we are working towards releasing this work in a future version of Carbon.

Is that correct? thanks!

[joshblack]

@aagonzales I don't think the surprise is coming from the topics themselves, e.g. fluid was discussed back during Duo. The surprise comes from learning that they are being shared and applied in production without alignment from dev.

---

@jeanservaas looks great 👍 thanks 🙏