DOCSEARCHbyAlgolia
Submit Docs

Primer CSS

repository·main·Indexed 11 days ago

https://github.com/primer/css

The CSS implementation of GitHub's Primer Design System, version 22.3.0. It provides utility classes and modular SCSS files for building interfaces, including bundles for autocomplete, avatars, base, box, branch-name, buttons, core, forms, header, labels, layout, loaders, markdown, marketing, navigation, pagination, product, and select-menu.

Tokens
22.4K
Snippets
98
Records
163
Agent score
96%

What's inside Primer CSS

  1. Style and layout form controls

    main

    Primer CSS provides styles for individual form controls and common layouts.

    Key behaviors:

    • Resets: Default styles for <fieldset>s, WebKit validation bubbles, and textual <input>s are reset for cross-browser consistency.
    • Automatic Styling: Specific types of textual <input>s are styled automatically. Use the .form-control class if you need to apply these styles manually.
    • Buttons: Always declare a type attribute on your <button> elements.
    • Layouts: Form layouts rely on the use of form groups. Note that form controls do not have a default layout (like vertical stacking) built-in; you must use <fieldset>s, <div>s, or other elements with custom styles to arrange them.

  2. Understand the Primer CSS module structure

    main

    Primer CSS is published as the @primer/css npm package. The styles are organized into three primary themes, which are located in subfolders under src/ and can be accessed via their respective index.scss files:

    • Core (core/): Common dependencies including support variables, native element styles, typography, buttons, navigation, and tooltips.
    • Product (product/): Components specific to github.com, such as avatars, labels, markdown styles, popovers, and progress indicators.
    • Marketing (marketing/): Styles for GitHub marketing efforts and design-heavy feature pages. These extend the core typography and whitespace scales and include specialized colors and button styles.

  3. Follow BEM-style naming and structure for components

    main

    Primer CSS uses a modified BEM (Block Element Modifier) syntax to ensure components are predictable and reusable.

    Naming Conventions:

    • Block: Use PascalCase for the block name. Blocks contain base styles and should have minimal thematic styling. (e.g., .ProgressBar)
    • Element: Use hyphen-lowercase for elements. Elements are parts of a component and should not override block styles. Use camelCase if the element name requires two words (e.g., .ProgressBar-closeButton).
    • Modifier: Use --double-hyphen-lowercase for modifiers. Modifiers add to existing styles rather than overriding them. Use camelCase if the modifier name requires two words (e.g., .ProgressBar--extraLarge).

    Core Principles:

    • Separate structure and skin: Define repeating visual features (like backgrounds/borders) as separate "skins" that can be mixed into components.
    • Separate container and content: Avoid location-dependent styles so components look the same regardless of where they are placed.
    /* block */
.Box {
  ...
}

/* elements */
.Box-header {
  ...
}
.Box-closeButton {
  ...
}

/* modifiers */
.Box--blue {
  ...
}
.Box--extraLarge {
  ...
}

  5. Understand Color Modes and Functional Variables (v16+)

    main

    Starting with Primer v16.0.0, the color system shifted from presentational colors (e.g., blue, gray) to color modes and functional variables.

    Color Modes

    Primer supports multiple color modes, currently including light mode and dark mode. A color mode defines a specific set of colors that change based on the active mode.

    Functional Variables

    Instead of applying a specific color to an element, you should apply colors based on the element's function. This is achieved using functional CSS variables. These variables automatically update their values when the color mode changes, ensuring proper contrast and visibility in both light and dark themes.

    Key Change: Sass color variables from versions prior to v16.0.0 have been replaced by these functional CSS variables.

  7. Understand the Color Scale and Auto Colors

    main

    Primer v16 provides two types of color variables beyond functional variables:

    1. Color Scale Variables: These represent specific color values in the scale (e.g., var(--color-scale-black), var(--color-scale-gray-1), var(--color-scale-pink-9)). Use these when you need a specific shade regardless of the color mode.

    2. Auto Colors: These variables automatically invert their shade based on the active color mode. For example, var(--color-auto-gray-0) is light gray in light mode and dark gray in dark mode.

    Note: While auto colors are convenient, you should use functional variables (like var(--color-text-primary)) as much as possible for more predictable results.

  11. Use utility classes for layout and common overrides

    main

    Utilities are immutable, single-purpose classes used for layout or to handle common use cases (like margin or padding) without writing new custom selectors. They are an acceptable way to override component styles when necessary. Utility class names should be transparent and clearly describe their function.

    Note: Utility classes in Primer CSS typically use !important to ensure they behave as immutable building blocks.

    .text-white { color: #fff !important; }
.bg-gray-light { background-color: #ddd !important; }
.mr-1 { margin-right: $spacer !important; }
.d-inline-block { display: inline-block !important; }
.rounded { border-radius: 3px !important; }

  12. Enforce SCSS file naming conventions

    main

    Primer enforces specific naming conventions for .scss files to align with modern CSS web standards:

    • Use lowercase letters.
    • Use hyphens (-) as separators.
    • Do not use leading underscores (_). While underscores are common in Sass for partials, Primer is proactively moving away from this pattern to match standard CSS practices.