Production guidelines
For anyone interested in contributing to the Carbon Design System website, we follow a set of guidelines to ensure consistency across site content.
- Read these production guidelines for best practices.
- Look over our markdown cheatsheet for how to properly style content.
- Create your content, images, etc.
- 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.
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 switcherandData table.
Pro-tip: Remember to use quotation marks (“ ”) instead of inch marks (" ")
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
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.
The Carbon website supports and hosts PNG, SVG and GIF image formats.
- 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 (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.
- GIFs are the preferred animation image format used on Carbon to show motion and interactions examples.
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
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.
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
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:
Each component page is divided into three tabs, Code, Usage, and Style, and differs in content given the section:
Define the component and include any documentation for SCSS and Javascript.
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.
Order applicable content by:
- Color
- Typography
- Layer
- 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 (
#ffffffinstead of#FFFFFF).
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 |
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.
| 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. | - |
