CM3: Styling

[matheusps]

Shoreline styling API

The styling API is built using data-attributes. Make sure you understand this topic before continuing.

Every component has its unique data-attribute for styling. It follows the pattern data-sl-{component-name}, where sl stands for Shoreline.

import { Button } from '@vtex/shoreline-components'
import './styles.css'

export default function App() {
  return (
    <Button>Accessible button</Button> 
  )
}

Adding styles to the component is simple as referencing its data-attribute.

[data-sl-button] {
  cursor: pointer;
  margin: 1rem 2rem;
  /* ... */
}

Also, you can use classNames.

<Button className="custom-button">Custom</Button>

.custom-button {
  border: 1px solid red;
}

For library authors, it's recommended to use the components layer.

@layer sl-components {
  [data-sl-button] {
    cursor: pointer;
    margin: 1rem 2rem;
    /* ... */
  }
}

When using csx, you can reference components inside of the components layer using the $ symbol:

import { csx } from '@vtex/shoreline-vanilla-extract'

export const button = csx({
  '@layer': {
    components: {
      '$button': {
        cursor: 'pointer',
        margin: '$space-2 $space-4'
      }
    }
  }
})

Variants

Components often have variants. They are also represented using data-attributes. The possible values for variants are string, number, and boolean. For example,

<Button variant="primary" /> 

To style this example. Reference the attribute on the CSS:

@layer sl-components {
  [data-sl-button] {
    cursor: pointer;
    /* ... */
    & [data-variant="primary"] {
      background: var(--sl-color-blue-400);
    }
  }
}

Usage

// application root
import "@vtex/shoreline-styles"

//... rest of the code

import { Checkbox } from '@vtex/shoreline-components'
// ... 

or (modular)

import { Checkbox } from 'components'
import '@vtex/shoreline-styles/checkbox' // css

References

• Ariakit
• React Spectrum
• Radix

[lucasaarcoverde]

Just out of curiosity, using $button is the same as [data-sl-button]?

[matheusps]

Yes! But when used on the namespace: @layer -> components

[matheusps]

I think is positive to create shorthands on the recommended route, it reinforces the correct API.

[marcelovicentegc]

What are the benefits/downsides/tradeoffs of this approach?

I trust you! Just want to learn more about why we are moving into this direction. For instance, I have rarely see cascade layers in use, so it occurs to me that it might be a little intimidating (at the same time it is so so so so simple) for folks that want to contribute, adding a little bit of friction to third-party contributions, but I don't know the advantages/disadvantages of this approach and would love to learn more

[matheusps]

The main downside would be compatibility, but It is well covered. Cascade layers are getting traction in newer CSS frameworks, like panda-css. I don't say we have a downside since it is easy to use, and solves precedence problems. Real world solution: Take a look at this thread.

I agree that it can be little intimidating, but it pays off - don't you think?

[marcelovicentegc]