Skip to content

Production guidelines

Connor edited this page Sep 5, 2019 · 2 revisions

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

  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. Check out our how-to guide for help.

For Pattern contributions, you can use our Markdown template for guidance when documenting your pattern.

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.

  • Aim for a friendly and encouraging tone.
  • Speak directly to the user. You can use the second person pronoun ("you").
  • Keep sentences and paragraphs short and focused.
  • Be clear and concise by removing unnecessary words. The more concise the text, the easier it is for all users to understand.
  • Use sentence case for everything, including component names, e.g. Content switcher and Data table.

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


Creating images

Sizes

We support four image sizes based on type:

SIZE (PX) TYPE
352 Half width image, ex-small components. Usually a 2 up do/don't pair.
448 Half width image, small components (Ex. Buttons), and cropped images
736 Full width image
1120 Wide format images and larger components (Ex. Data Tables)

**Final decision: export images at largest size an image would ever appear. We have 4 different image sizes: lg, md, sm, xs

lg: 1120px

md: 736px

sm: 448px

xs: 352px

Images should have white background. When presenting components on Gray 10 theme, use a 16px white border on the image so it doesn't blend into webpage background.

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 4
Measurement & spec line 2

button spec lines.png

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
Magenta text #d12765 - Mono, 12/0.75
Magenta lines #d12765 Height and width measurements for a component as well as key elements within a component such as row height and icons. 1px stroke
Teal text #007d79 - Mono, 12/0.75
Teal lines #009e9a - 1px stroke
Teal overlay #87eded @ 50% opacity External padding/margin as well as internal spacing between component elements. -
Purple blocks and lines #8a3ffc Spacing of units in components. -

spec-example-2.png