[Layout] Primitive layout components

[sarahill]

As part of the Layout foundations work, the team is working on prototyping several primitive layout components based on the Braid design system.

The goal of this discussion is to have a place to talk about the various layout primitives, how we want to approach them, and their job/purpose for building various layouts in the admin.

Primitive layout components for discussion:

• Box
• Card
• Stack
• Inline
• Columns
• Tiles
• ContentBlock
• Bleed

Related links:

• Card discussion
• Modal flexibility

[sarahill]

Tiles or Grid

In our sync the other day the discussion of Tile came up. It wasn't clear what the purpose of the Tile component was and/or if another layout primitive could do the same job.

Here's my general understanding of what Tile does:

• The elements would wrap within the container to create a grid of elements
• The elements wrapped in Tile equal height and width
• Tile would be responsive -> you could opt to make the layout single column or it would be single column be default on mobile size screens

Here are some examples from the admin that I think fit that description (although not sure about the second example since that spans a couple rows)

Please challenge any of that and bring up any additional thoughts and questions.

cc: @chazdean

[aveline]

I agree with Sara, Tile looks like it works well for these examples. I wonder what an example of a layout where Grid would be the better choice looks like? Would it be something with uneven row heights? I think that's one of the limitations of Tile right?

[sarahill]

Thoughts from @kyledurand

Some of my concerns here:

1. Let's align on naming in both Figma and in code. What are designers most commonly referring to? IMO I don't like the name tiles, when I think of wall tiles or floor tiles they can come in all shapes and sizes like mosaics etc... we're all familiar with a grid, we had grid paper in school, designers use grid overlays, developers use css grid. It's familiar and represents both sides.

2. Grid is currently only used in 3 places in web but in some complex ways. Here's an example of a configuration of props: https://github.com/Shopify/web/blob/main/app/sections/Companies/CompanyDetails/components/CompanyLocationListItem/utilities/constants.ts

Let's make sure we can achieve the same things with Tiles if we deprecate Grid.

3. Why are we calling it Tile when the component represents a groups of Tiles? Braid calls it Tiles, let's call it Tiles if that's what we go with

[heyjoethomas]

From a designer pov I think Tile is just fine. I would have no issue with that name. Something like Grid has way trouble I think as designers will think mainly of a 12 column grid.

[sarahill]

When I think of Tiles I think of something pretty specific. When I think of Grid I tend to think about larger complex layouts or a traditional 12 column grid (as Joe mentioned).

If we had Grid and Columns that feels confusing as to know when I would use one over the other. Whereas with Tiles I do think of something different.

It might feel a little new to designers as a term but I think with guidance and visuals it should be fine. I think designers have a mental image of what a tile is and the component generally matches that model (for me at least).

[kyledurand]

If we had Grid and Columns that feels confusing

Love that thinking. They both do basically the same thing but Grid allows for a bit more control over its layout which adds complexity and I don't think that's necessarily what we want. Let's roll with Tiles and remove Grid.

[sarahill]

Utility styles

There's been some convos cropping up around shared utility styles and naming conventions. Kicking a thread to have some convo around that.

Some conversation points:

• What utility styles do we need?
• What naming convections do we want to use for these styles?

Spacing utilities:

• space
• top, bottom, left, right, vertical, horizontal
  • When would I reach for these over a padding or margin?
• padding, paddingX, paddingY, paddingTop, paddingBottom, paddingLeft, paddingRight
  • Our current approach is to generally only use padding to keep everything contained and composed: Components shouldn't concern themselves with spacing outside their bounds. This also avoids issues with collapsing margins.
    • Is this true for both vertical and horizontal spacing?
• I think we need margin for Bleed though as it applies negative margin
• How do we want to handle negative values?

Position

• top, bottom, left, right

Widths:

• minWidth, maxWidth, ?

Display:

• block, flex, inline, inlineBlock, none

Border-radius

• These change in some cases on desktop vs. mobile

Flex

• justifyContent, alignItems, flexDirection, flexWrap, flexShrink, flexGrow, ?

These are just to start the convo to strengthen our decisions and opinions. Please challenge any of these. These are largely based off of Braid's utility classes and Style system

Related links:

• Alpha Bleed component PR

[sarahill]

Card component

As I'm working on adding AlphaCard to the UI Kit I'm starting to think it needs to be more opinionated.

Here are my thoughts / observations:
The first value in the "Values" column represents the default value with the other value options below. For things like backgroundColor, borderRadius, and elevation I think those should actually be pretty opinionated at this level. Each of those have 2 options.

Anything that needs to go outside of these styles would use the Box component.

If I'm interpreting it correctly, it looks like there's more flexibility in AlphaCard styling right now for backgroundColor and borderRadius correct me if I'm wrong though. I know we were still figuring out some of these opinions.

Thoughts?

Props	Values
children	React.ReactNode;
backgroundColor	surface
	surface-subdued
borderRadius	border-radius-2
	none
elevation	shadow-card
	shadow-transparent
padding	space-5
	space tokens scale
roundedAbove	breakpoint tokens

[heyjoethomas]

Totally agree. This feels very odd to me and doesn't seem like a design pattern we want to replicate.

[aveline]

In the example that you posted @heyjoethomas the nested content would be very easy to create with our existing AlphaCard. I'm not sure why a dev shouldn't use AlphaCard for that since it will provide the border, background color and flat elevation that already exists in AlphaCard and we enable the flexibility to create sections within.

[heyjoethomas]

I think a Card is a specific recipe of styles and is a larger wrapper than that sub-section. From a language perspective it also doesn't look or feel like a Card. It feels like a container or section of content. I think that mental model is important to keep. By making the subsection a Card we have made it pretty difficult to define what a Card is and what it isn't. I think keeping things clearly defined is important for long term health and scalability.

[sarahill]

☝️ I agree with that. If we're going to make AlphaCard really flexible then I would start to question why we have both Card and Box. It starts to get a little fuzzy as to when I should reach for one vs. the other.

[zecarlostorre]

@sarahill - apologies for the delay, just managed to catch up with this.

Re:elevation - I think this approach makes sense right now, we'll figure out what we need when we land on a definite direction and then we see what things we may need to add, if anything.

Just to share what on my mind: I'm thinking beyond a shadow, we may also want to have a way to represent how bright or dim an object should be. But again, for now this is speculation, we don't need to get into that until we know exactly what we want to do.

[sarahill]

ContentBlock

Let's clarify the intent of ContentBlock. There have been a few discussion in different places about the use case for this component in the admin so I wanted to consolidate those and align here.

My understanding is ContentBlock would set the max-width of the content within the current breakpoint. My thought was Page would be refactored to use ContentBlock to set the width of the main page content. For example:

So this would be a more opinionated layout component that specifically sets max-widths for the contents container.

Some questions to start the conversation:

• Other use cases for ContentBlock?
• Why not use Box for this instead of creating a separate component?

[aveline]

I think we should ship ContentBlock as is for the alpha version and try using it with Page. I'm hoping there will be some good learnings there that could answer some of those questions.

[sarahill]

I'm all for shipping it as is. My goal is for us to be able to be confident in why we need ContentBlock and what job it's doing. It sounds like we can learn and form stronger opinions as we start applying it to components 👍

[SeanyB]

So, in the context of Page, would that component continue to have props for narrowWidth, normalWidth, and fullWidth, but use ContentBlock to achieve them in the underlying implementation? Or would the user need to wrap their components in the ContentBlock and then put the ContentBlock inside the Page?

[aveline]

Should Box have support for passing in an id?

Currently we do not have an id prop on Box to support passing in an id as an HTML attribute.

Are we concerned about the misuse of the id attribute and therefore not including it in our layout primitives? Should we be removing the use of id in our components?

[kyledurand]

It seems to me like it’s going to come down to preference. In theory we shouldn’t need to pass any ids if our library is perfectly composable.

Braid allows ID on box

A couple of others don’t:
https://nulogy.design/components/box/
https://paste.twilio.design/primitives/box/

I’m leaning towards not including id to keep our APIs simple and clean but again that’s just preference

[aveline]

After further discussion we've decided to allow id on Box and Text. While we don't want to encourage misuse of the attribute, we recognize there are valid instances where using id is necessary and we don't want to force users to have to use workarounds like a wrapper div with id. Having it as a prop will make it easier to track and evaluate usage.