# Styling

Historical information around decisions and opinions on our approach to styling React applications

# Mantras

Keep specificity low and predictable
Box Model spacing should exist in containers, not in the reusable component
Prefer rem over px
Keep your styles close to the module they are styling

# Why do we need a consistent CSS approach?

Managing styles for an application as the application grows in size and complexity can be difficult. It is important to establish a convention early so that everyone is on the same page. If some parts of the application use SCSS, others use CSS Modules, and another use Utility classes (á la Tailwind), this provides ambiguity to developers when authoring code as well as unnecessary configuration and build complexity.

# Decision to use CSS Modules

A team decision was made to use CSS Modules as our styling method of choice. A few of the guiding factors that helped us land there include:

Provides configurable component scoping out of the box, removing any issues with conflicting cascade.
Provides an easy to understand organization of files, i.e. your style module file lives next to your component definition.
Does not require knowledge of a new syntax, but is extensible if we opt to add functionality via PostCSS.
With significant advancements coming in the base CSS spec itself, tools such as SASS or SCSS have become unnecessary overhead. Many of the problems they were solving can no be achieved with bare CSS.

# Module Placement

Your style modules should live next to the module they are styling. While conventional CSS would tell you that you might have many components share a single CSS file and even share selectors, this is an anti-pattern in a CSS Modules world. If you find yourself wanting to reuse a certain selector/style, this is typically a flag that you may have an abstractable display component that needs to be created.

Example folder/file structure
✅ Good, style module next to component
src
  components
    MyComponent
      index.tsx
      style.module.css
    AnotherComponent
      index.tsx
      style.module.css

❌ Bad, style module outside of component
src
  components
    style.module.css
    MyComponent
      index.tsx
    AnotherComponent
      index.tsx

# Units

It is one of our mantras to Prefer rem over px. An additional part that goes along with this is keeping our base units consistent. The ideal scenario will set us up to have consistent unit of scale, with a font-size: 16 on the body, we get end up with 1rem = 16px. Since our spacing scale has a base unit of 4px or 0.25rem, we'll easily align with specs from Design.

# Interaction with Vinyl

Some of our applications are going to have an integration with Vinyl for the design system layer. Vinyl is an implementation of the Digital Banking Smarthub design system, but is also serving as a catalog of components and visual patterns that we can use to quickly build new applications.

The primary integration with Vinyl from a styling perspective will be through CSS Custom Properties. Vinyl supplies myriad options for things such as typography, color, and spacing.

Do not be tempted to override styles internal to Vinyl.

You may find yourself in a scenario where the Vinyl component is not doing exactly what you want it to do. You may also find yourself attempting to write a CSS selector to override or change the default behavior of the component.

This should be regarded as a cardinal sin, and handled with extreme caution. Your overrides will be both flimsy (potentially breaking if anything internal to Vinyl changes), and regarded as a direct violation of the principals reasoning for a Design System (to main consistency in a world of entropy.)

# Typography

Vinyl provides CSS Custom Properties for use when assign styles to type in an application. The property names follow a consistent convention to help you remember how to form them when authoring new code.

The full list of available typography styles can be found in Storybook or directly in the code.

# Colors

Vinyl provides CSS Custom Properties for referencing the color palette of the design system. The property names follow a consistent convention to help you remember how to form them when authoring new code.

// Property Name Pattern
--vinyl-color-[color_variant]-[scale_position]

// Example
--vinyl-color-primary-400: #83a4ae;

// Usage
p {
  color: var(--vinyl-color-primary-400);
}

A full list of all available colors can be found in Vinyl here.

# Spacing

Vinyl provides CSS Custom properties for referencing spacing in the design system spacing scale. The design system dictates that our spacing scale has a base unit of 4px, but when implemented in the browser, we use rem for our spacing units. With the browser default font size of 16px, this translates to a base spacing unit of 0.25rem. The CSS Custom Property names follow a consistent patter for ease of authoring.

// Property Name Pattern
--vinyl-spacing-[scale_position]

// Usage
p {
  margin-bottom: var(--vinyl-spacing-2); // ✅ good, use for box-model spacing
  font-size: var(
    --vinyl-spacing-4
  ); // ❌ bad, do not use for non spacing properties
}