Development

Adding the sds-core package to a project.

It is recommended to use sds-core via the published NPM package.

Start by adding sds-core as a dependency to a project using the following command.

NPM

npm install @sipster/core

Yarn

yarn add @sipster/core 

Once added, there are two important files in the main directory of the sds-core package: reset.scss and tools.scss . Both of these files need to be added to your project on a root file to have the styles implemented globally.

---

reset.scss

This file is a basic style reset that also includes some standardization sprinkled in. The main objective of this reset is to offer a consistent starting point for every project regardless of environment (device, browser, operating system). To achieve this, certain user agent styles need to be overridden, standardized, or even potentially removed.

This file outputs actual css, and is strongly recommended to add only once—in the root entry file of a project.

Some key targets included in this reset are:

• Reset font sizes so that using semantic markup does not impact hierarchy or style (important for building dynamic and modular components)

• Reset block margins so that the spacing is only applied where/when needed

• Reset tables so that tabular data only takes the space it needs

• Preserve inline padding so that buttons and inputs keep their default layout while still allowing for full customization

• Set border-box sizing so that properties like borders and padding don't impact an item's dimensions

• Set responsive media elements so that images and videos scale with the browser/parent container width

• Set default font-family so that all the projects start with the approved typeface of SDS

---

sds-tools.scss

This file contains all foundational styles (color, typography, shadows, etc) as well as a comprehensive layout system (spacing, flex, css grid). This file can be thought of as the developer's counterpart to the SDS Core Figma Design Library.

Tools is comprised of various partials including custom Sass(SCSS) maps, mixins, and functions, but should not output any actual css on its own. To access these styles and features, import this sds-tools.scss file at the beginning of every SCSS file you plan on using them in.

@use "node_modules/@sipster/core/tools" as *;

.myCustomClass {
  color: sds-color(blue);
  margin-bottom: sds-spc(16);
  @include sds-typeset(title-1, bold);
}

To help organize the various concepts and partials, the tools file is divided in two sections: Styles and Layout System. You can learn more about each topic on their respective pages of this documentation.

sds-tools.scss
|
|– Styles
|  |– Colors
|  |– Typography
|  |– Shadows
|
|– Layout System
|  |– Spacing
|  |– Z-index & Layering
|  |– Flexbox
|  |– CSS Grid
|  |– Breakpoints
|

---

Example

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "@sipster/core/reset.scss";
import "@sipster/themes/themes.scss";

const rootElement = document.getElementById("root")!;
const root = ReactDOM.createRoot(rootElement);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

---

Sass Functions

In Sass(SCSS), functions are special actions that can receive parameters and will return a specific value based on those parameters. This makes functions very useful for various CSS properties that we want to make sure remain consistent both in developer implementation as well as compiled outcome.

Since functions return a specific value, it's critical that the function being used returns a value that is valid syntax for the CSS property being targeted.

Example: The sds-color function, which returns a specific hex color code, should not be used for properties that require a number value like margin, padding, width etc.

Here are a few examples of sds-core functions:

Spacing: sds-spc()

button {
  padding: sds-spc(8) sds-spc(12);
}


//--------------
// Compiled CSS 
//--------------

button {
  padding: 0.5rem 0.75rem;
}

Color: sds-color()

button {
  color: sds-color(blue, 10);
  background-color: sds-color(blue, 60);
}


//--------------
// Compiled CSS 
//--------------

h1 {
  color: #CDDEFD;
  background-color: #0C5BEC;
}

---

Sass Mixins

Mixins, like functions, are special actions that can receive parameters and return expected results. However, there are a few important distinctions between the two tools.

• Mixins don't return a specific value. Instead, they return a property (or group of properties) whose values are already defined. Because of this, mixins are a powerful tool that can help reduce code and ensure consistency

• Mixins can have a 'content area,' where developers can write their own style declarations to include within the mixin itself. This can be seen in action here in the breakpoints partial of sds-core.

• While functions are assigned to specific CSS properties (returning a specific value for that property), mixins are declared at the same level as other CSS properties (since they return style declarations). And while functions are called just by writing their custom name, mixins are called using @include .

Here are a few examples of sds-core mixins:

Flexbox: sds-flex()

div {
  width: 100px;
  @include sds-flex(center, center, column);
}


//--------------
// Compiled CSS 
//--------------

div {
  width: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
}

CSS Grid: sds-grid()

div {
  width: 100px;
  @include sds-grid(4);
}


//--------------
// Compiled CSS 
//--------------

div {
  width: 100px;
  display: grid;
  grid-template-columns: repeat(4, 1fr);
}