SmoothCSS
  • Introduction
  • Design tokens
  • Global styles
  • Layouts
  • Styling skins
  • Utility classes
  • Customisation

SmoothCSS is in active development

As a result, this documentation and the underlying code will change before a stable release.

Global styles

Global styles provide you with good design defaults for a wide selection of HTML elements – all based on your design tokens.

Using global styles is as simple as writing semantic HTML. No class names. No components.

Below are tables of all the elements included in the SmoothCSS global styles. The descriptions explain the intention of the styles rather than the implementation details. This gives us the flexibility to change the implementation details as the browser, HTML and CSS evolve and improve.

There are some common HTML elements that are not covered by the global styles. This is generally for one of two reasons:

  1. The styling depends on the context. For example, an <aside> might be used for a callout or a sidebar.
  2. The visual styling is not specific to a single HTML element. Like how a visual button could be a <button>, <a>, or <input type="submit">.

In SmoothCSS these types of styles are covered by styling skins.

To make it easier to find the element your looking for, the elements are grouped into the following tables:

  • General elements
  • Typography
  • Lists
  • Media
  • Tables
  • Interactive elements
  • Forms

To see all of the global styles in context, please see this example page.


General elements

Element Styling
All HTML elements
  • Box sizing is set to border-box, which includes the element's padding and border in the width and height.
html
  • Prevent font size inflation
  • Make MacOS render text slightly thinner and crisper
  • Prevent long text from pusing a container wider than its parent would naturally be
  • Add smooth scrolling
body
  • Apply color, background color, font, font-size and line height from design tokens
  • Make elements like <code> proportional to base font
  • Stop the body from collapsing when less content fills the viewpport
  • Remove margin
hr
  • Add a single border from design tokens
  • Add spacing before and after from design tokens, or the variable --stack-space if it is set
:target
  • Prevent anchor tags from hitting the top of the viewport
::selection
  • Add color and background color from design tokens
[hidden]
  • Make sure elements with the hidden attribute are hidden (note, this element uses !important)

Typography

Element Styling
h1
  • Apply heading font, font-size, maximum inline size, font-weight, line-height and letter spacing from design tokens
  • Balance heading when it wraps
  • Remove margin
h2
  • Apply heading font, font-size, maximum inline size, font-weight, line-height and letter spacing from design tokens
  • Balance heading when it wraps
  • Remove margin
h3
  • Apply heading font, font-size, maximum inline size, font-weight, line-height and letter spacing from design tokens
  • Balance heading when it wraps
  • Remove margin
h4
  • Apply heading font, font-size, maximum inline size, font-weight and letter spacing from design tokens
  • Prevent orphans when heading wraps
  • Remove margin
h5
  • Apply heading font, font-size, maximum inline size, font-weight and letter spacing from design tokens
  • Prevent orphans when heading wraps
  • Remove margin
h6
  • Apply heading font, font-size, maximum inline size, font-weight and letter spacing from design tokens
  • Prevent orphans when heading wraps
  • Remove margin
p
  • Apply maximum inline size from design tokens
  • Prevent orphans when text wraps
  • Remove margin
ins
  • Remove text decoration
  • Apply coloring based on design tokens
  • Add padding
strong
  • Apply font weight from design tokens
b
  • Apply font weight from design tokens
q
  • Apply italic font style
sub
  • Remove default line height
sup
  • Remove default line height
var
  • Apply font weight from design tokens
math
  • Make numbers aligned and consistent width so they are easier to read
  • Use a slashed zero when the font supports it
time
  • Make numbers aligned and consistent width so they are easier to read
  • Use a slashed zero when the font supports it
code
  • Apply a mono font and border-radius from design tokens
  • Add padding and style text so it stands out from body text
  • Use a slashed zero when the font supports it
kbd
  • Apply a mono font, border and border-radius from design tokens
  • Add padding and style text so it stands out from body text
samp
  • Apply a mono font and border-radius from design tokens
  • Add padding and style text so it stands out from body text
pre
  • Apply a backgournd-color and border-radius from design tokens
  • Prevent long text from pushing a container wider than its parent would naturally be
  • Prevent code blocks from wrapping and allow the content to scroll
  • Remove padding from <code> when in a code block
  • Remove margin
abbr
  • Only use a text decoration when there is a title attribute
  • Use the help cursor when there is a title attribute
blockquote
  • When there is no class on the blockquote apply basic styling with padding and border from design tokens
  • Apply font-size and marging from design tokens to <footer> elements used in a blockquote without a class
  • Remove italic styling from <q> element when it's used in a blockquote
  • Remove margin

Lists

Element Styling
ol
  • Indent the text to handle double figure list numbers
  • De-emphasise the list numbers by making them smaller than the text
  • Add spacing between nested <li> elements
  • Maintain consistent spacing between <li> elements for nested lists
  • When the attribute [role="list"] is present, remove all list styles
  • Remove margin
ul
  • Indent the text to leave space for the list bullet
  • Add spacing between nested <li> elements
  • Maintain consistent spacing between <li> elements for nested lists
  • When the attribute [role="list"] is present, remove all list styles
  • Remove margin
dt
  • Apply heading font-weight from design tokens
  • Add space between it and the preceeding <dd> element
  • Remove margin
dd
  • Indent the text
  • Add space between it and the preceeding <dt> element
  • Remove margin

Media

Element Styling
img
  • Set display to block
  • Prevent it from overflowing its container
  • Preserve the aspect ratio
  • Set font-size for alt text when image not shown
picture
  • Set display to block
  • Prevent it from overflowing its container
  • Preserve the aspect ratio
canvas
  • Set display to block
  • Prevent it from overflowing its container
  • Preserve the aspect ratio
video
  • Set display to block
  • Prevent it from overflowing its container
  • Set the aspect ratio to 16/9
iframe
  • Set display to block
  • Prevent it from overflowing its container
  • Set the aspect ratio to 16/9 for YouTube and Vimeo embeds
figure
  • Base the inline size on the content
  • Remove margin
figcaption
  • Apply smaller font size from design tokens
  • Stop the figcaption from being wider than the figure
svg
  • Prevent it from shrinking when used in a flex container
  • Use the currentColor when no fill value is given
  • When the svg is more of an image, use the provided width and height (requires [role="img"] attribute)

Tables

Element Styling
table
  • Apply a border from design tokens
  • Fill the container
  • Collapse the borders so there is a single line
tr
  • Apply border from design tokens
th
  • Apply color, background color, font weight, line height, padding and border from design tokens
  • Align text to the start of the cell
td
  • Apply padding and border from design tokens
caption
  • Place the caption below the table
  • Add spacing between the table and the caption from design tokens

Interactive elements

Element Styling
a
  • Color using the currentColor
  • Keep the underline thickness consistent across browsers
  • Remove the underline when the link is in a heading – but apply it on hover
  • Change the underline color on hover from design tokens
  • Add spacing before and after from design tokens, or the variable --stack-space if it is set
summary
  • Add font weight from design tokens
  • Add space below when the <details> element is open
  • Use the pointer cursor to be consistent with other interactive elements
:focus
  • Remove outline so taps and clicks don't get the focus styling
:focus-visible
  • Add an outline with an offset
  • The --focus-color and --focus-offset variables can be used to alter these properties

Forms

Element Styling
form
  • Add default space between form elements (excluding hidden inputs), or use --stack-space if it is set
  • The --focus-color and --focus-offset variables can be used to alter these properties
button
  • Inherit font family and size so they are the same as the rest of the page
input
  • Inherit font family and size so they are the same as the rest of the page
  • Apply accent color from design tokens
  • Adjust background color (from design tokens) and opacity and cursor not-allowed when disabled
input (not "checkbox", "radio" or "color")
  • Apply border, border radius, color and background color from design tokens
  • Scale padding with text size
  • Fill the container
  • Add color (from design token) and opacity to placeholder text
  • Set the --focus-color (from design token) and --focus-offset
textarea
  • Inherit font family and size so they are the same as the rest of the page
  • Apply border, border radius, color, background color and accent color from design tokens
  • Scale padding with text size
  • Fill the container
  • Add color (from design token) and opacity to placeholder text
  • Set the --focus-color (from design token) and --focus-offset
  • Make sure it is not too small when there is no rows attribute
select
  • Inherit font family and size so they are the same as the rest of the page
  • Apply border, border radius, color, background color and accent color from design tokens
  • Scale padding with text size
  • Fill the container
  • Add color (from design token) and opacity to placeholder text
  • Set the --focus-color (from design token) and --focus-offset
  • Use progressive enhancement to style selects for browsers with customizable selects
label
  • Display as block element
  • Apply font weight from design tokens
  • Add opacity and cursor not-allowed when the label's input is disabled
label wrapping input
  • Usually a label wraps checkboxes and radio buttons
  • Display as a flex element
  • Align items
  • Add gap between checkbox or radio button and text, and adjust font weight of text from design tokens
  • Add spacing between checkboxes and radio buttons
fieldset
  • Remove border and padding
legend
  • Add font weight from design tokens
  • Remove padding
  • Add space after the element