Sass Reference
Here is a collection of references for our sass files, custom tools, and non-ui specific items.
Coding Guidelines
Sass Styleguide
Just as important as a visual styleguide is a coding styleguide. We follow many common conventions outlined in Sass Guidelines (the tldr; is a good overview). The general good-coding practices applies to all Sass, but commenting format is specific to the nature of the file; for example, component classes follow a different commenting setup than most other pages.
Annotations
For annotations to generate this automated reference page, we use SassDoc. Their full list of annotations can be read here.
Sass Organization Structure
This is an overview of the CSS architecture employed on safe.com. As is apparent, we use the preprocessor Sass; for organization, we follow an ITCSS structuring; and for class naming, we use BEM with some additional namespacing rules.
ITCSS
We have organized our Sass files to roughly follow the Inverted Triangle CSS structure by Harry Roberts. The CSS architecture emphasizes hierarchical layering of specificity, to reduce code redundancy and inadvertent leaking styles.
As our UI and layout specific components are layed out in the pattern library, this reference is for the CSS-specific architecture and maintenance of our code-base. In particular, this document focuses on the Settings and Tools levels of the ITCSS hierarchy.
BEM
"Block Element Modifier" (BEM) is a naming convention for classes that makes hierarchy and style-application immediately apparent. To summarize, the block is the standalone entity, with elements being children of the block, and modifiers act to change the UI in specific ways.
For more detailed explanations, read the official introduction (don't worry, it's very straightforward and not boring at all).
Namespacing
Prefixing classes based on their functionality and how they fit into the CSS architecture provides transparency for developers. This makes clear the use of each class and how best to update the styles.
Namespacing is currently implemented for internal tools and utility classes only. Read this article on CSS Wizardry for more on the benefits and specifics of namespacing.
Current Architecture Summary
| Level | CSS output | Prefix | Detail |
|---|---|---|---|
| Settings | no | - | Contains global classes only, such as font and color definitions, that need to be accessible from everywhere in the code. Settings relating to each partial should be in the same file as that partial. |
| Tools | no | sc- | Globally used mixins and functions. As with partial-specific settings, partial-specific mixins and functions should belong in the related file. All custom mixins are functions start with sc-, for safecom. |
| Generic | yes | - | High-level, far-reaching styles that affect a lot of the DOM. For instance, resets/normalize styles, box-sizing definitions, etc. |
| Elements | yes | - | Bare HTML elements, like the heading levels and <a> tags. |
| Objects | yes | - | Undecorated design patterns, such as the media-object from OOCSS (Object Oriented CSS). Our object classes are documented in our pattern library. |
| Components | yes | - | Specific UI components and where a majority of our work is. In our code-base, we also follow BEM naming conventions, and all components are also made into Blade templates, which are documented in the pattern library. |
| Utilities | yes | u- | Helper classes have the ability to override anything and everything declared before it in the triangle. |
Border
mixin
sc-border
Not a very useful mixin, so is deprecated since version 2.0.
Outputs default border settings. Do we even need this default border???
Todo:
- Make this simpler, too many mixins repeating the same thing.
Border-radius
mixin
sc-border-radius
Get a named border-radius sizing.
@include sc-border-radius($type)
border-radius: {size}| parameter | type | default | description |
|---|---|---|---|
| $type | string | - | none, soft, softer, pill |
See also: border-radii
variable
$border-radii
Border-radii map with standard values.
$border-radii
none: 0,
soft: 2px,
softer: 5px,
pill: 20px,
circle: 50%,Colour
function
sc-get-color()
Get a colour from our colour palette.
sc-get-color($name)
| parameter | type | default | description |
|---|---|---|---|
| $name | string | - | The colour name from our colour palettes. |
variable
$semantic-color-palette
The semantic names for our common colours.
$semantic-color-palette
'primary': map-get($core-palette, 'orange'),
'primary-light': map-get($color-palette, 'orange-60'),
'accent': map-get($core-palette, 'orange'),
'secondary': map-get($color-palette, 'orange-60'),
'success': map-get($semantic-palette, 'green'),
'warning': map-get($color-palette, 'yellow'),
'alert': map-get($semantic-palette, 'red'),
'error': map-get($semantic-palette, 'red'),
'info': map-get($core-palette, 'blue'),Todo:
- Convert the palette maps to use nested mapping for scales.
variable
$gradients
$gradients
'grape': linear-gradient(135deg, #3023AE 0%, #C86DD7 100%),
'blue': linear-gradient(90deg, map-get($core-palette, 'blue-dark-20') 0%, map-get($core-palette, 'blue-light-10') 100%),
'dark-blue': linear-gradient(135deg, map-get($core-palette, 'blue') 0%, map-get($core-palette, 'blue') 100%),
'dark-blue-reversed': linear-gradient(135deg, map-get($core-palette, 'blue') 0%, map-get($core-palette, 'blue-40') 100%),
'navy': linear-gradient(135deg, map-get($core-palette, 'blue') 0%, #000959 100%),
'navy-vertical': linear-gradient(0, #000959 0%, map-get($core-palette, 'blue') 100%),
'navy-reversed': linear-gradient(135deg, #000959 0%, map-get($core-palette, 'blue') 100%),
'orange': linear-gradient(90deg, map-get($core-palette, 'orange-light-10') 0%, map-get($core-palette, 'orange-dark-10') 100%),
'red': linear-gradient(135deg, map-get($semantic-palette, 'red') 0%, map-get($semantic-palette, 'red') 100%),
'green': linear-gradient(135deg, map-get($semantic-palette, 'green') 0%, map-get($semantic-palette, 'green') 100%),
'papaya': linear-gradient(135deg, map-get($core-palette, 'orange') 0%, rgba(233,132,0,1) 24%, map-get($semantic-palette, 'red') 100%),
'cantaloup': linear-gradient(135deg, rgba(map-get($semantic-palette, 'green'), .6) 0%, map-get($core-palette, 'blue') 88%),
'maya-blue': linear-gradient(92deg, map-get($semantic-palette, 'maya-blue-dark-60') 0%, map-get($semantic-palette, 'maya-blue-dark-50') 0.01%, map-get($semantic-palette, 'maya-blue-dark-30') 100%),
'blue-grey': linear-gradient(90deg, map-get($secondary-palette, 'blue-grey-light-40') 0%, map-get($secondary-palette, 'blue-grey') 100%),
'brown': linear-gradient(90deg, map-get($secondary-palette, 'brown') 0%, map-get($secondary-palette, 'brown-dark-30') 100%),
'infra-red': linear-gradient(135deg, map-get($secondary-palette, 'infra-red-dark-10') 0%, map-get($secondary-palette, 'infra-red-dark-40') 100%),
'purple': linear-gradient(90deg, map-get($secondary-palette, 'purple-light-10') 0%, map-get($secondary-palette, 'purple-dark-20') 100%),
'grey': linear-gradient(90deg, map-get($neutral-palette, 'grey-light-40') 0%, map-get($neutral-palette, 'grey') 100%),
'white-fade': linear-gradient(135deg, #fff 0%, rgba(#fff, .6) 100%),Todo:
- Make example blocks to show gradients.
- Clean up the actual values.
function
sc-gradient()
Gets the linear-gradient() code for the named gradient.
sc-gradient($type)
| parameter | type | default | description |
|---|---|---|---|
| $type | string | - | name of the gradient |
mixin
sc-gradient
Sets the background-image to a specified gradient.
@include sc-gradient($type, $opacity)
| parameter | type | default | description |
|---|---|---|---|
| $type | string | - | name of the gradient |
| $opacity | num | - | opacity of the gradient, value between 0 - 1 |
Dropshadow
function
sc-dropshadow()
Get a named dropshadow value.
sc-dropshadow($type)
| parameter | type | default | description |
|---|---|---|---|
| $type | string | - | A dropshadow type. |
mixin
sc-dropshadow
Return the box-shadow property with the named values.
@include sc-dropshadow($type)
| parameter | type | default | description |
|---|---|---|---|
| $type | string | - | A dropshadow type. |
variable
$dropshadows
Box-shadow values for the related property type name.
$dropshadows
none: 0 0 0 0 rgba($dropshadow-color, $dropshadow-transparency),
soft: -4px 6px 16px 1px rgba($dropshadow-color, $dropshadow-transparency),
hard: 0 3px 4px 1px rgba($dropshadow-color, $dropshadow-transparency),
glow: 0 3px 16px 1px rgba($dropshadow-color, $dropshadow-transparency),
faint-glow: 0 1px 4px 2px rgba($dropshadow-color, $dropshadow-transparency),
hard-dark: 0 3px 4px 1px rgba($dropshadow-dark-color, $dropshadow-transparency),
glow-dark: 0 3px 16px 1px rgba($dropshadow-dark-color, $dropshadow-transparency),
hard-darkest: 0 3px 4px 1px rgba($dropshadow-darkest-color, $dropshadow-transparency),
glow-darkest: 0 3px 16px 1px rgba($dropshadow-darkest-color, $dropshadow-transparency),Todo:
- Make example blocks for documentation.
Icons
variable
$icon-sizes
Sizes for icons; same for both tokens and pictos.
$icon-sizes
mini: 1rem,
tiny: 1.5rem,
xxsmall: 2rem,
xsmall: 3rem,
small: 4rem,
medium: 5rem,
large: 6rem,
xlarge: 7rem,
xxlarge: 8rem,
jumbo: 9rem,function
sc-icon-size()
Function to get a named icon size from a map.
sc-icon-size($size)
| parameter | type | default | description |
|---|---|---|---|
| $size | string | - | Named icon size from $icons-sizes map. |
Todo:
- Add size detection for headers?
See also: icon-sizes
function
sc-icon-path()
Function to get the image path of the named icon, either Token or Picto.
sc-icon-path($name)
| parameter | type | default | description |
|---|---|---|---|
| $name | string | - | Name of icon. |
mixin
sc-icon-bg-image
Return the icon image as the background image property.
@include sc-icon-bg-image($name)
| parameter | type | default | description |
|---|---|---|---|
| $name | string | - | Name of the icon. |
mixin
sc-icon-sizes
Return the icon sizes for width and height.
@include sc-icon-sizes($size)
| parameter | type | default | description |
|---|---|---|---|
| $size | string | - | Name for size. |
Internal-tool
function
-sc-match-list-with-map()
Match the values of a list with a map and return a list of the matched values
-sc-match-list-with-map($list, $map)
| parameter | type | default | description |
|---|---|---|---|
| $list | list | - | List to be matched against. |
| $map | map | - | Map whose values will be matched against list. |
Rhythm
variable
$spacing-names
Semantic names for spacing values. Index numbers are for a loop that creates a new variable with scaled rem values.
$spacing-names
0: none,
1: xxsmall,
2: xsmall,
3: small,
4: medium,
5: large,
6: xlarge,
7: xxlarge,
8: xxxlarge,
9: jumbo,function
sc-spacing()
Get a rem value based on the named spacing name.
sc-spacing($space)
| parameter | type | default | description |
|---|---|---|---|
| $space | string | - | Named spacing name. |
function
sc-rhythm()
Returns rem value as a multiple of the rhythm ratio.
sc-rhythm($lines)
| parameter | type | default | description |
|---|---|---|---|
| $lines | int | - | Multiples of the $base-rhythm size |
function
-sc-rhythm()
Determine the correct rem spacing to upkeep the rhythm of the design, while accounting for offets that are not automatically included in the default spacing calcaulations, like borders.
-sc-rhythm($lines, $offset)
| parameter | type | default | description |
|---|---|---|---|
| $lines | int | - | Multiples of the $base-rhythm size |
| $offset | pixel | - | How much to decrease the rhythm, in pixels |
mixin
sc-rhythm-border
Returns a border of specified style with the correct padding to uphold the vertical rhythm of the design.
@include sc-rhythm-border($border-position,
$rhythm-spacing,
$border-width,
$border-style,
$border-color)
| parameter | type | default | description |
|---|---|---|---|
| $border-position | string | - | Top, right, bottom, left, all |
| $rhythm-spacing | int | - | How many rhythm-spaces to include |
| $border-width | pixel | rem | - | Border-width |
| $border-style | string | - | Border-style |
| $border-color | color | - | Border color |
Undefined
mixin
caret
Styles for an inverted triangle caret.
variable
$z-indexes
Z-indexes for various components and parts of the website, consolidated into one map to reduce conflicts.
$z-indexes
reveal: 1007,
gecko: 1006,
header: 1005,
header-dropdown: 11,
overlap-containers: 2,
general: 1,
banner: 1,
overlay: -1,
bg-img: -2,Utilities
css
.u-bulletless-list, .bulletless-list
Bulletless lists.
Todo:
- Replace all prefix-less occurrences
Xy-grid
mixin
xy-grid-layout
Sizes child elements so that `$n` number of items appear on each row.
| parameter | type | default | description |
|---|---|---|---|
| $n | Number | - | Number of elements to display per row. |
| $selector | String | - | Selector(s) to use for child elements. |
| $gutter-output | Boolean | - | Whether or not to output gutters |
| $gutters | Number|Map | - | Map or single value for gutters. |
| $gutter-type | Keyword | - | Type of gutter to output. Accepts `margin` or `padding`. |
| $gutter-position | List | - | The position to apply gutters to. Accepts `top`, `bottom`, `left`, `right` in any combination. |
| $vertical | Boolean | - | Set to true to output vertical (height) styles rather than widths. |
To do
sc-border
- Make this simpler, too many mixins repeating the same thing.
semantic-color-palette
- Convert the palette maps to use nested mapping for scales.
gradients
- Make example blocks to show gradients.
- Clean up the actual values.
dropshadows
- Make example blocks for documentation.
sc-icon-size
- Add size detection for headers?
.u-bulletless-list, .bulletless-list
- Replace all prefix-less occurrences