Tips

Naming tips and ideas for SpiraCSS projects.

Layout

Rule	Notes
Use only top margins (margin-top) for vertical spacing; do not use bottom margins.	Simplifies spacing calculations and prevents duplicates

From a design perspective, treating elements as having their own space above them is more natural, so use top margins.
See property-placement for Stylelint settings.

Class naming

Rule	Notes
Use *-box for layout classes within a Block and, as a rule, do not use relative names such as wrapper / inner / outer.	Example: .content-box, .media-box

wrapper / inner / outer imply relative structure and can become misleading when the structure changes. *-box does not constrain meaning, so it is easier to swap or split.

Naming idea

• If you standardize the root Block class (defined in each component’s root SCSS file) as <name>-container, the root Block becomes easier to identify and component boundaries are easier to track.

Recommended Stylelint config (optional)

Recommended setup: stylelint-config-standard-scss + stylelint-config-recess-order.
The config below focuses on reducing SCSS + SpiraCSS false positives and includes optional formatting/CSS Modules tweaks.

// stylelint.config.js (ESM example)
import spiracssPlugin, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'

export default {
  extends: ['stylelint-config-standard-scss', 'stylelint-config-recess-order'],
  plugins: [spiracssPlugin, 'stylelint-scss'],
  customSyntax: 'postcss-scss',
  // Exclude shared partials; keep shared keyframes linted.
  ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
  rules: {
    ...createRules(spiracssConfig),
    'at-rule-no-unknown': null,
    'function-no-unknown': null,
    'length-zero-no-unit': true,
    'no-descending-specificity': null,
    'no-invalid-position-at-import-rule': null,
    'rule-empty-line-before': [
      'always-multi-line',
      {
        ignore: ['after-comment', 'first-nested']
      }
    ],
    'selector-class-pattern': null,
    'selector-pseudo-class-no-unknown': [
      true,
      {
        ignorePseudoClasses: ['global', 'local']
      }
    ],
    'selector-pseudo-element-colon-notation': 'double',
    'declaration-property-value-no-unknown': null,
    'scss/comment-no-empty': null
  }
}

Notes:

• selector-pseudo-class-no-unknown is only needed if you use CSS Modules (:global/:local).
• rule-empty-line-before and similar are formatting preferences; remove if you prefer stricter defaults.