Skip to main content

Methodology

At Croma Design System, we follow a structured and scalable approach to ensure consistency, maintainability, and clarity throughout our design and development process. Our methodology incorporates three key frameworks:

  • BEM for naming.
  • Atomic Design for components.
  • ITCSS combined with Atomic Design for organizing file structure.

Here's how each methodology integrates into our workflow:

The CDS prefix​

We use the cds- prefix in all class names to ensure compatibility with other frameworks and prevent class name collisions. This approach allows us to avoid conflicts when integrating our design system with external libraries or third-party tools, ensuring that our styles remain isolated and don't interfere with other global styles. By using this consistent naming convention, we maintain a clear and predictable structure across our entire codebase.

BEM (Block, Element, Modifier)​

We use the BEM naming convention to create clear and predictable CSS class names. This methodology helps maintain consistency and scalability as our codebase grows.

  • Block: The standalone component or reusable part of the UI. cds-button, cds-toast.
  • Element: A part of the block with a specific function. cds-button__text, cds-toast__title.
  • Modifier: A variation or state of the block or element. cds-button--primary, cds-toast--success.
HTML Example
<button class="cds-button cds-button--primary">
  <span class="cds-button__text">Click me!</span>
  <span class="cds-button__icon cds-ph-arrow-right"></span>
</button>

BEM ensures CSS class names are human-readable and self-explanatory while minimizing the risk of style collisions.

Check the official BEM documentation.

Atomic Design​

We employ Atomic Design principles to build our components systematically, ensuring reusability and modularity. Atomic Design breaks down components into five distinct levels:

  • Atoms: Basic building blocks, such as buttons, input fields, or icons.
  • Molecules: Combinations of atoms that form slightly more complex UI elements, like input fields with labels.
  • Organisms: Groups of molecules working together, such as a navigation bar or form section.
  • Templates: Page-level wireframes showcasing the layout of organisms.
  • Pages: Fully realized interfaces populated with real data and content.

ITCSS​

Our file structure combines ITCSS (Inverted Triangle CSS) and Atomic Design to create a scalable and organized system for managing SCSS files.

ITCSS categorizes styles into seven layers based on specificity and inheritance, ensuring a clear hierarchy and preventing style conflicts.

  • Settings: Global variables and design tokens.
  • Tools: Mixins, functions, and utilities.
  • Generic: Resets and standardizations.
  • Elements: Base styles for HTML elements.
  • Objects: Reusable design patterns.
  • Components: Modular UI components.
  • Utilities: Helper classes for overrides and one-off styling.

ITCSS + Atomic Design​

We divide the Components layer of ITCSS into the Atomic Design hierarchy, creating a more organized and modular structure. Each Atomic Design level corresponds to a folder within the Components layer, which includes:

  • Atoms: Basic building blocks like buttons, icons, and input fields.
  • Molecules: Combinations of atoms, such as form elements or button groups.
  • Organisms: Groups of molecules working together, like a navigation bar or header.
  • Templates: Layout structures that combine organisms to form page-level wireframes.

This approach helps us maintain a clear, logical structure that enhances the scalability and reusability of our components while following ITCSS principles. Each level in Atomic Design has its own specific folder within the Components directory to ensure that our SCSS files are organized and easy to maintain.

Integration of Atomic Design with ITCSS
/scss/
  ├── 01-settings/
  ├── 02-tools/
  ├── 03-generic/
  ├── 04-elements/
  └── 05-objects/
  ├── 06-atoms/
  ├── 07-molecules/
  ├── 08-organisms/
  └─ 09-templates/
  └── 10-utilities/