Migrating

Here's a comparison between Admin UI and Styleguide to give you an overview of the main differences.

info

This comparison strives to be as accurate and unbiased as possible. If you feel this information could be improved, feel free to suggest changes (with notes or evidence of claims) creating an issue on admin-ui.

Overview

Styleguide

Current Design System, the home for all our reusable patterns, components, and assets related to product design in VTEX. It is a common language of tools and processes to facilitate how we collaborate and share knowledge across teams and projects.

Admin UI

A library of React components with a focus on accessibility and developer experience.

We also have other packages that are responsible for providing the entire structure used by our library.

About CSS styles

Styleguide

Functional CSS using VTEX Tachyons.

Admin UI

We use Stitches to implement a CSS-like, and prop-based model of styling components.

Overriding Styles

In most applications, it is a common challenge to override styles for a specific context to match design requirements.

Styleguide

Given that Styleguide uses VTEX Tachyons as a CSS utility framework, you may need to rewrite the tachyons config to override specific classNames. In Styleguide, there is no easy way to do this.

Admin UI

Given that Admin UI styles are prop-based, overrides are as easy as passing a property.

<Card csx={{ padding: '$s' }}>Card content</Card>

<Button csx={{ border: 'default' }}>Label</Button>

Responsive Design

Styleguide

Authoring responsive styles in Styleguide requires a combination of pseudo-classes.

<div className="w-10 w-30-m w-40-l">{content}</div>

Admin UI

Every StyleObject property can receive a responsive value, for example:

<div className={csx({ width: ['10%', '30%', '40%'] })} />

Accessibility

Styleguide

Many components do not support accessibility requirements, some of which are very difficult to provide.

Admin UI

We always build our components thinking about accessibility first and use two libraries for that: Reakit Library and Downshift.

Typography

It is important to define different typography styles for an app by setting a combination of different typography attributes: Typeface, weight, size, capitalization and letter spacing.

Styleguide

Comes with a set of classNames to apply the typography attributes.

<p className="t-body lh-copy">This is a paragraph!</p>

Admin UI

Provides the VTEX Trust font and comes with a set of components and CSS properties that turns the application of the typography attributes easier.

<Paragraph>This is a paragraph!</Paragraph>

<Heading>This is a Heading!</Heading>

<Text variant="subtitle">Text with subtitle style!</Heading>

<h1 className={cn({ text: 'headline' })}>This is a Heading!</h1>

Iconography

Styleguide

Exports a set of icons, most of them are not well documented.

Admin UI

Exports a set of Icons divided into categories according to their usage. It also has some features that our library provides. For example:

• Icons with direction: Some icons have a state that allows the developer to control their direction (left, right, down, up).

• Custom Icon: We export an Icon component that allows the developer to create a custom icon using our structure.

Charts

Styleguide

Comes with a set of chart components ready to be used.

Admin UI

Not yet available. Will be implemented in the future.

State

Styleguide

Most of the components have their states self-contained.

function Example() {
  const [state, setState] = useState('Item 1')

  const options = [
    { value: 'Item 1', label: '1' },
    { value: 'Item 2', label: '2' },
    { value: 'Item 3', label: '3' },
  ]

  return (
    <Dropdown
      label="dropdown"
      options={options}
      value={state}
      onChange={(_, v) => setState(v)}
    />
  )
}

Admin UI

We export the entire state control using react hooks.

function Example() {
  const items = ['Item 1', 'Item 2', 'Item 3']
  const state = useDropdownState({ items, initialSelectedItem: 'Item 1' })
  return <Dropdown items={items} state={state} label="dropdown" />
}

Reuse Design Behavior

Styleguide

The component's styles are made combining Tachyons classNames, so to reuse the design behavior we need to combine the same tokens.

Admin UI

Style reuse is done with Design Tokens, which are based on semantic context and make the styling consistent throughout different apps. Admin UI also provides layout components for common layout styling cases like Bleed, Stack and Inline, using them reduces the constant repetition of positioning css or classNames. Since these components accept the csx prop for aditional styling they also allow for merging other styles into the layout.

Utilities

Styleguide

Style patterns are not mapped.

Admin UI

We map styles that are repeated in the admin applications and create patterns from that. There are two ways of using those utilities:

Components

Flex: You don't have to repeat the display: 'flex' every time and it comes with shorthands properties to apply Flexbox CSS behavior.

Grid & GridItem: You don't have to repeat the display: 'grid' every time and it comes with shorthands properties to apply Grid CSS behavior.

Stack: Handles all the CSS logic to apply spacing between its children, flex-direction, and all of that as easy as using two properties.

Custom CSS Properties

Border:

// without token
<div
  className={cn({
    borderBottom: 'solid',
    borderBottomWidth: '1px',
    borderBottomColor: 'mid.secondary',
  })}
/>

// with token
<div className={cn({ border: 'divider-bottom' })} />

Size:

// without token
<div className={cn({ width: 100, height: 100 })} />

// with token
<div className={cn({ size: 100 })} />

Text:

// without token
<div
  className={cn({
    fontFamily: 'sans',
    lineHeight: 'headline',
    fontSettings: 'regular',
    fontSize: 4,
  })}
/>

// with token
<div className={cn({ text: 'headline' })} />