Introduction
Welcome to our Custom CSS Guidelines! We’re here to help you create beautiful and functional custom styles in Gainsight Customer Communities. These guidelines introduce structured conventions to mitigate the risks associated with broken CSS. Following these guidelines ensures your custom CSS is robust, reliable, and compatible with our platform.
Our approach involves introducing new anchor points strategically designed to facilitate the creation of cleaner CSS code. These anchor points serve as reference markers, enabling you to adopt a more organized and systematic approach to styling. By incorporating these anchor points into your CSS structure, you can effectively address challenges posed by global CSS inconsistencies. This approach not only enhances the overall stability of your custom styles but also empowers you to develop confidently knowing that your CSS will be less prone to issues stemming from conflicting styles or unintended overrides.
Begin with overriding CSS Variables
Using CSS variables is a resilient method for applying custom styles because it allows you to change properties like colors, borders, and border-radiuses without directly targeting HTML elements. This approach reduces the risk of your styles breaking when there are changes to the underlying HTML markup.
We use CSS variables as a foundation for Theme Customization functionality. You have more granular control and more options by changing CSS variable value compared to available customization using UI of Theme Customisation.
Examples
Links
Always Start Your Styles with Specific Identifiers
TL DR: Make sure your CSS Specificity is more than 200
To ensure that your custom CSS does not interfere with our existing styles and to prevent CSS specificity issues, always use the following identifiers at the beginning of your styles:
#customcss #root .your-css-selector {
/* Your custom styles here */
}
Using these two identifiers (#customcss #root) will ensure that your code is required and has sufficient specificity. It also allows you to avoid adding extra class names to the CSS selector and gives us more flexibility in terms of HTML markup changes.
If you encounter any crucial rules or CSS specificity issues caused by our code, please report them to our support team via an assistance ticket.
Examples:
Links:
Use 2data-css-anchor] Attributes in Your CSS Selectors as Anchors
TL DR; Scope your styles using #customcss #root sdata-css-anchor="%name%"] to prevent global CSS errors.
We are introducing the use of data-css-anchor attributes to represent actual modules in the codebase or product features. This change provides a more reliable and stable way to target elements in your custom CSS. Here's how you can effectively use data-css-anchor attributes for styling:
Links
Avoid Using ~, >, and + Operators; Prefer the Descendant Combinator (Space Selector)
To keep your CSS simple and avoid specificity issues, avoid using sibling (~), child (>), and adjacent sibling (+) combinators. Instead, prefer using the descendant combinator (space selector).
It gives us more flexibility in terms of HTML markup changes without breaking Custom CSS styles.
Examples:
Links:
- General sibling combinator ~
- Child combinator>
- Adjacent sibling combinator+
- Descendant combinator (space)
Avoid Manipulating DOM for Styling
Gainsight's strict recommendation is that your CSS or scripts should not change the DOM.
Manipulating the DOM, such as adding or removing classes or attributes from HTML elements, can lead to inconsistencies and conflicts outside of our control. This makes it harder for us to support and update the UI elements without impacting highly customized communities.
Do’s and Don’ts:
- Do: Use existing classes and data attributes as selectors in your CSS to ensure a cohesive and consistent user interface.
- Don’t: Add or remove classes or any other attributes from HTML elements.
If you have any questions or need help, our onboarding and support team is here to help! We encourage you to reach out for any assistance you may need during your CSS customization process.
Examples:
More examples of good practices.
If you’re using preprocessors, you can simply nest it in the following way:
