🚧 WORK in PROGRESS 🚧

Inclusive design system written using @adeira/sx. Core value of this project are (in this order):

• ⚛️ exclusively using atomic CSS via @adeira/sx
• 🏳️‍🌈 fully supported localization (🇺🇸🇲🇽🇨🇿🇳🇴🇺🇦🇷🇺🇦🇪)
• ☯️ light and dark theme out of the box
• 🆘 accessible components for people with visual impairment
• حلال support for RTL layouts (🇦🇪)
• 📲 mobile first

Installation and Usage

Using SX Design is as simple as installing the package via NPM or Yarn and importing the right component from @adeira/sx-design.

yarn add @adeira/sx @adeira/sx-design

SX Design is fully localized and requires information about the current application locale. This typically changes with every user, so it's necessary to provide it via SxDesignProvider React component (before the first SX Design component in the React tree):

import { SxDesignProvider } from '@adeira/sx-design';

// Note: SX Design automatically enables styled error boundary 👍
export default function MyRootApp() {
  return (
    <SxDesignProvider
      locale="en-US" // affects translations as well as dates, monetary values and similar
      theme="light" // or "dark" or "system"
      onErrorBoundaryCatch={(error, errorInfo) => {
        // call your error reporting service, for example:
        Sentry.captureException(error, { extra: { errorInfo } });
      }}
    >
      {/* … */}
    </SxDesignProvider>
  );
}

It is recommended to have some global CSS in your application where you configure fonts for your application, for example:

/* https://github.com/rsms/inter */
@import url('https://rsms.me/inter/inter.css');
html {
  font-family: 'Inter', sans-serif;
  font-feature-settings: 'ss01', 'zero';
}
@supports (font-variation-settings: normal) {
  html {
    font-family: 'Inter var', sans-serif;
  }
}

SX Design doesn't currently take care of this to give you freedom of choice.

Available components

🚧 WORK in PROGRESS 🚧

Legend:

✅  yes! (or not relevant)
🧐  needs some more work (or not evaluated yet)

Component	Localized?¹	Dark mode?²	Has stories?³	Tested?⁴	RTL?⁵
<Badge />	✅	✅	✅	✅	✅
<Breadcrumb />	✅	✅	✅	✅	✅
<Button />	✅	✅	✅	✅	🧐
<ButtonLink />	✅	✅	✅	✅	🧐
<DateTime />	✅	✅	✅	✅	✅
<Entity />	✅	✅	✅	✅	✅
<EntityField />	✅	✅	✅	✅	✅
<ErrorBoundary />	✅	✅	✅	✅	✅
<FlashMessage />	🧐	🧐	🧐	🧐	🧐
<FilterChips />	✅	✅	✅	✅	🧐
<Image />	✅	✅	✅	✅	✅
<Kbd />	✅	✅	✅	✅	✅
<Link />	✅	✅	✅	✅	🧐
<LinkButton />	✅	✅	✅	✅	🧐
<Loader />	✅	✅	✅	✅	✅
<Menu />	✅	✅	✅	✅	🧐
<Meter />	🧐	🧐	✅	✅	🧐
<MissingData />	✅	✅	✅	✅	✅
<Modal />	✅	✅	✅	✅	🧐
<Money />	✅	✅	✅	✅	🧐
<Note />	✅	✅	✅	✅	✅
<Placeholder />	✅	✅	✅	✅	✅
<ProductCard />	✅	✅	✅	✅	🧐
<Skeleton />	✅	✅	✅	✅	✅
<SkipLink />	✅	🧐	🧐	🧐	🧐
<Table />	✅	✅	✅	✅	✅
<Tabs />	✅	✅	✅	✅	✅
<Text />	✅	✅	✅	✅	✅
<Tooltip />	✅	✅	✅	✅	🧐

There is an additional set of so-called "Layout" components that are responsible for rendering the components above in a correct order, with correct spacing and so on:

• <LayoutBlock /> - typically⁶ vertical stacking
• <LayoutGrid /> - children in a CSS grid
• <LayoutInline /> - typically⁶ horizontal stacking
• … 🚧

Did you find a mistake in this table? Please, report is as an issue.

_{¹ Localized means that it's either translated by us or the component inputs are (Flow) typed in a way that encourages passing translated strings instead of plain strings.
² Component should look fine in both light and dark mode.
³ There are stories in the Storybook (https://sx-design.vercel.app/) and these stories are somehow useful and explanatory.
⁴ There are tests available to make sure that the component works as expected and we won't break it by accident.
⁵ Component correctly supports right-to-left (RTL) as well as traditional left-to-right (LTR) layouts
⁶ https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties#block_vs._inline}

Styles customization

SX Design leverages full power of CSS variables as a main way of style customization. You can optionally overwrite the values from your application. Most of the CSS variable values are available in src/SxDesignProviderCSSVariables.js or in a documentation of each component (when they relate only to that component).

There is also an useSxDesignContext hook which allows you to access system theme and other global SX Design properties:

export default function MyComponent() {
  // `theme` can be "light", "dark" or "system"
  const { theme } = useSxDesignContext();
}

Development

The easiest way how to develop these components is to run a Storybook:

yarn workspace @adeira/sx-design storybook

Please, make sure that any changes still follow the core values of this project and the matrix of available components was updated accordingly.

Changing language and dark mode in Storybook

Storybook is configured to ease switching between different languages and light/dark modes. You can change these settings in the top panel:

There is no way how to manually switch between LTR and RTL layouts. RTL layout is applied automatically once you select some language that should be rendered in RTL context (for example Arabic).

Working with SX Design colors

It's recommended to use pastel when working with the SX Design colors:

brew install pastel

SX Design commonly uses colors written as triplets of values from 0 to 255. Here is how you can convert these triplets back and forth:

pastel color "28, 30, 33"
pastel format hex "28, 30, 33"

To generate colors gradient run:

pastel gradient -n 9 '255, 255, 255' '28, 30, 33'
pastel gradient -s rgb -n 9 '255, 255, 255' '28, 30, 33' | pastel format rgb

Another interesting command for checking colors with simulated colorblindness:

pastel colorblind deuter "247,212,214" "255,26,26" "238,0,0" "197,0,0"

For more info run:

pastel --help

Prior art

sorted alphabetically

• https://github.com/vercel/commerce
• https://material.io/components?platform=web
• https://seek-oss.github.io/braid-design-system/
• https://vercel.com/design
• https://www.radix-ui.com/