Custom Properties

Design tokens referenced internally and externally for custom styles

Demo

My background and text colors reference custom properties

API

Colors

All color values are in the perceptually uniform color space to provide visually appealing colors while still achieving a11y contrast guidelines.

Name Example Description
--m-color-red-[1|2|3]
Used to denote something has or will go wrong.
--m-color-orange-[1|2|3]
Used for bringing attention to something that may not be desirable.
--m-color-blue-[1|2|3]
Used to highlight primary actions.
--m-color-green-[1|2|3]
Used to communicate something desirable has or will happen.
--m-color-gray-[7|8|9]
Used for text and high-contrast backgrounds.
--m-color-gray-[1|2|3|4|5|6]
Grayscale used for backgrounds, borders, and disabled state.
--m-color-primary-action
Used for links and other primary action elements.
--m-color-disabled-[bg|fg]
Disabled background and foreground.
--m-color-border
Default border color.

Spacing

The spacing sizes are based on Divine Proportions to help provide a natural rhythm. Padding, margin, and gap use these values.

Name Value Description
--m-space-[xs|sm|md|lg|xl] 6px, 12px, 18px, 30px, 48px Used for developing a visual rhythm between elements. Loosely follows Divine Proportion. You should use the padding and margin utility classes whenever possible and reserve use of --m-space-* for other spacing needs like position.

Element styles

All elements use these values for their relevant styles.

Name Value Description
--m-border-radius-[sm|md|full] 2px, 4px, fully round Used for border radius.

Breakpoints

Although custom properties are unfortunately not usable in media queries, these breakpoint values are useful elsewhere.

The large breakpoint and above are considered desktop-sized

Name Value Description
--m-breakpoint-sm 576px The portrait width of an iPhone X.
--m-breakpoint-md 768px The portrait width of an iPad.
--m-breakpoint-lg 992px The landscape width of an iPad.

Other

Name Value Description
--m-font-family 'Helvetica Neue', Arial The typefaces in use.
--m-max-content-width 1536px The max width used by Container. Wrapping your content in a m-container is more likely what you need, but you can use this if necessary.
--m-min-input-height 34px The min height used for form elements. Reference this if you'd like your element to match the height of inputs.

Guidelines

Do not hard code values

Facebook famously had 548 unique colors hard-coded 6,498 times across all their stylesheets. Custom properties are a modern CSS feature that helps you avoid such a mess by defining reusable values. Use custom properties instead of hard coding their values. Like this:

/* Do */ @import "../node_modules/m-/dist/custom-properties.css"; #foo \{ background-color: var(--m-color-gray-2); } /* Don't */ #foo \{ background-color: #dedede; }

Go here to learn more about custom properties and how to use them.

Accessibility

The colors and spacing meet accessibility requirements.