Skip to content
This repository has been archived by the owner on Feb 5, 2024. It is now read-only.

Production guidelines

Anna Gonzales edited this page Dec 17, 2018 · 23 revisions

!! Note: guidelines are being updated to reflect new Carbon X criteria

For anyone interested in contributing to the Carbon Design System website, we follow a set of standardized guidelines to ensure consistency across the site.

  1. Read these production guidelines for best practices.
  2. Look over our markdown cheatsheet for how to properly style content.
  3. Create your content, images, etc.
  4. Submit a PR to the carbon-website. Checkout our how-to guide for help.

Index


Writing content

The website is written in markdown, which makes it easy for anyone to contribute content in a systematic way. If you are not familiar with markdown, check out Carbon's handy markdown styling cheatsheet.

  • Use sentence case except when referencing components.
  • Components are proper nouns and therefore written in Title Case.
  • Convey a friendly tone as you are writing content and avoid sounding too harsh or directive.

Pro-tip: Remember to use quotation marks (“ ”) instead of inch marks (" ")


Creating images

Sizes

We support three image sizes based on type:

SIZE (PX) TYPE
290 Half width image, small components (Ex. Buttons), and cropped images
604 Full width image
894 Wide format images and larger components (Ex. Data Tables)

The artwork in an image does not have to fill the full image size. White space is ok but the artwork should always be centered aligned on the image. If there is excessive or limited white space consider using a different size.

Pro-tip: Two half width images (290px) can be arranged side by side to give the appearance of a full image. This allows images to stack a responsive breakpoints without having to generate two sets of images.

File type

The Carbon website supports and hosts PNG, SVG and GIF image formats.

PNG

  • PNG is preferred for raster-graphics, like static images and photographs (to show redlined components, for example).
  • PNG is used for graphs, diagrams, and anywhere you want to display flat colors and lines that won’t need to scale up. They are a lossless image format, which means when they are compressed, they don’t lose any data. They also allow for alpha transparency. When you need to overlay an image on a different colored background, PNG files work well.
  • Note: Text inside of a png is not accessible and therefore a PNG should never contain important information that cannot be accessed elsewhere on the page.

SVG

  • SVG (Scalable Vector Graphic) is preferred for vector-graphics.
  • Use an SVG file format when you have a flat, relatively simple asset such as logos, icons, basic shapes, and line art. Accessible text inside SVGs is possible but long strands of copy should be avoided.

GIF

  • GIFs are the preferred animation image format used on Carbon to show motion and interactions examples.

Exporting PNG and SVG

For images to render properly, export them from Sketch or Illustrator by:

  • Aligning all elements to the pixel grid
  • Using one of the three image sizes: 290px, 604px, 894px
  • Export at 2x for PNG
  • Background should be transparent

Creating GIFs

We recommend using the image sizes above and a tool called GIF Brewery for creating animated GIFs by recording from your desktop or open browser window.

Naming conventions

Images are named using the format: page-name-tabname-#.png

Examples:

Components > Data Table > Usage tab

  • data-table-usage-1.png

  • data-table-usage-2.png

Style > Layer > Overview

  • layer-overview-1.png

  • layer-overview-2.png

Accessibility

Alt text describes an image and is used for a variety of reasons. Include alt text so on hover the browser tooltip displays the text. In cases when an image doesn't render, the alt text will show in lieu of the image. Additionally, alt text enables users who rely on assistive technology to know what the image represents. In the HTML, make sure the alt text is in brackets before the image URL:

![alt text goes here](image URL goes here)


Creating content for component pages

Each component page is divided into three tabs, Code, Usage, and Style, and differs in content given the section:

Code tab

Define the component and include any documentation for SCSS and Javascript.

Usage tab

Explain how to use the component, which may include best practices and frequently asked questions. Use static images to support your content and GIFs when explaining interactive elements.

If a component has multiple variations, include a comparison table to show the differences between them and when to use which variation. This table can be styled using markdown. Check out this handy table generator.

Style tab

Order applicable content by:

  1. Color
  2. Typography
  3. Layer
  4. Structure

Structure may include states, pacing, and any other component-specific variations. Add supporting images to this section, with at least one image showing how color is applied within the component and another showing structure and spacing measurements. Images are accompanied by a descriptive caption below the image and used in conjunction with the spec charts.

Pro-tip: Use lowercase when referencing HEX values (#ffffff instead of #FFFFFF).

Spec guidelines

All style image specs are set in IBM Plex Mono. Numerical measurements include both pixels and rems and follow the naming convention #px/#rem (please note the lack of spaces between the forward slash). We recommend using this site for converting pixels to rems. The increment unit ##px/##rem only needs to for one measurement per image; the remaining measurements can simply read ##/##. Measurements are presented horizontally for readability and never flipped vertically to fit smaller spaces. Specs can be broken up into two lines if necessary.

Keep as many spec lines and measurements outside the component as possible for easy readability.

PROPERTY SPACING (PX)
Spec line & component 6
Measurement & spec line 4

spec-example-1

Spec lines have a 1px thickness and flat ends. To add endings to an open path in Sketch, go to the Borders section in the right-side panel, click the gear icon and select the flat end option for both the start and end arrow dropdown menus.

Adding flat ends to a line in Sketch

Spec color usage

ITEM COLOR PURPOSE PX/REM
Pink lines #ff00ff Height and width measurements for a component as well as key elements within a component such as row height -
Pink text #ff00ff - 10/0.625
Green blocks #00ff80 @ 40% opacity Internal edge padding/margin, and internal spacing between component elements -
Green text & lines #007d7d - 10/0.625
Blue blocks #00ffff @ 40% opacity External padding/margin, and can also be used internally if there are too many overlapping green blocks -
Blue text & lines #007d7d - 10/0.625

spec-example-2