SCSS Guidelines

These guidelines help ensure that all SCSS in Cynosure components is reliable, readable, and maintainable.

Third-Party SCSS Libraries Used

Below is a list of third-party SCSS or SASS libraries that are imported in Cynosure components or tooling:

• Normalize.scss: Modern, HTML5-ready alternative to CSS resets (imported via npm or directly)
• Sass MQ: Media Query mixin framework for easier responsive design
• Modular Scale: Provides functions for modular scale typography
• Font Awesome SCSS: (if used) SCSS integration for icon fonts
• Bootstrap SCSS: (selectively imported parts only if needed, not full framework)
• Color Functions/Mixins: Utility libraries for color manipulation

Note: Some of these libraries are included globally; others may be imported only by specific components as needed.

If you’re authoring or updating component SCSS:

• Favor native SASS/SCSS functions over adding new dependencies.
• Check if a helper/mixin exists already before adding your own.
• Import only what you need to keep CSS bundles small and fast.

---

1. Use SCSS Syntax and Features

Prefer modern SCSS features and syntax for readability and maintainability.

• Use variables for colors, spacing, font sizes, etc.
• Prefer @use and @forward over @import for new code (Sass modules)
• Use nesting in moderation (avoid > 2 levels deep)
• Utilize SASS functions and mixins instead of duplicated code

1// Good
2$primary-color: #1473e6;
3.button {
4  color: $primary-color;
5  @include mq($from: tablet) {
6    font-size: 1.2rem;
7  }
8}
9
10// Bad
11.button {
12  color: #1473e6;
13  @media (min-width: 768px) {
14    font-size: 1.2rem;
15  }
16}
17

2. Namespace Component Styles

Component SCSS should use unique namespaces or BEM class names to avoid conflicts.

• Prefix classes by component/module
• Avoid global selectors or element selectors

1// Good
2.card-list__item { ... }
3

3. Use Variables & Maps for Tokens

• Store color, spacing, and other tokens in variables or maps
• Reference design tokens rather than hardcoded values

1// Good
2$spacing-map: (
3  sm: 0.5rem,
4  md: 1rem,
5  lg: 2rem,
6);
7
8.margin-lg {
9  margin: map-get($spacing-map, lg);
10}
11

4. Responsive Design With Mixins

• Use a standard mixin library (like sass-mq) for breakpoints
• Store breakpoints in a central place

1.element {
2  @include mq($until: tablet) {
3    display: none;
4  }
5}
6

5. Accessibility in Styles

• Respect user’s system settings (e.g. prefers-color-scheme & reduced-motion media queries)
• Use :focus and :hover states regularly for interactive elements

1.button:focus-visible {
2  outline: 2px solid $focus-outline;
3}
4

6. Keep Specificity Low

• Prefer class selectors over IDs, avoid !important where possible
• Keep selectors simple to allow easy overrides

---

7. Avoid Inline Styles

• Use SCSS for styling, avoid inline style="" attributes in HTML

---

8. Document Complex Mixins/Functions

• Add comments to describe tricky or non-obvious mixins/functions

1/// Calculates a nice box-shadow for cards.
2/// @param {Color} $color - Base shadow color
3@mixin card-shadow($color) {
4  box-shadow: 0 1px 4px rgba($color, 0.16);
5}
6

---

9. Optimize Output

• Remove unused CSS (purge/clean as part of build)
• Avoid heavy selector chains and complex combinators

---

10. Linting & Formatting

• Follow Prettier or Stylelint rules for consistency
• Run a SCSS linter (like stylelint) before committing
• Follow project naming and ordering conventions

---

Apply these principles to all Cynosure component SCSS, and keep code clear, modular, tokenized, and maintainable.