File organization structure

File Organization Structure

The organizational structure of CSS files directly impacts code maintainability and readability. A reasonable file division allows for quick location of style rules and reduces team collaboration costs. Common organizational approaches include categorization by functional modules, page hierarchy, or CSS features.

Basic Structure Standards

A typical project should include the following core files:

styles/
├── base/            # Base styles
│   ├── _reset.scss     # Reset styles
│   ├── _typography.scss # Typography
│   └── _variables.scss  # Variable definitions
├── components/      # Component styles
│   ├── _buttons.scss
│   └── _cards.scss
├── layouts/         # Layout styles
│   ├── _header.scss
│   └── _grid.scss
└── main.scss        # Main entry file

The main entry file aggregates other parts via @import:

// main.scss
@import 'base/variables';
@import 'base/reset';
@import 'base/typography';

@import 'layouts/grid';
@import 'layouts/header';

@import 'components/buttons';
@import 'components/cards';

Modular Organization Solutions

Combined with BEM Naming Convention

// components/_navbar.scss
.nav {
  &__item {
    &--active {
      color: var(--primary-color);
    }
  }
}

// layouts/_sidebar.scss
.sidebar {
  &__section {
    @media (min-width: 768px) {
      padding: 1.5rem;
    }
  }
}

Atomic CSS Approach

/* utilities/_spacing.css */
.mt-4 { margin-top: 1rem; }
.px-8 { padding-left: 2rem; padding-right: 2rem; }

/* utilities/_display.css */
.flex { display: flex; }
.grid { display: grid; }

Variable Management Strategy

Create an independent variable management file:

// base/_variables.scss
:root {
  --color-primary: #3498db;
  --color-danger: #e74c3c;
  --spacing-unit: 8px;
  
  --font-heading: 'Georgia', serif;
  --font-body: 'Helvetica', sans-serif;
}

// Usage example
.button {
  background-color: var(--color-primary);
  padding: calc(var(--spacing-unit) * 2);
}

Responsive Code Organization

Two recommended organizational approaches:

1. Centralized Management (suitable for small projects)

// responsive/_breakpoints.scss
@mixin mobile {
  @media (max-width: 599px) { @content; }
}

.card {
  width: 100%;
  
  @include mobile {
    flex-direction: column;
  }
}

2. Decentralized Management (suitable for large projects)

// components/_gallery.scss
.gallery {
  &__item {
    @media (min-width: 1200px) {
      grid-template-columns: repeat(4, 1fr);
    }
  }
}

Third-Party Style Handling

Store third-party library styles in a separate directory:

styles/
├── vendor/
│   ├── _bootstrap.scss
│   └── _swiper.scss
└── ...

Maintain priority when importing:

// main.scss
@import 'vendor/bootstrap';
@import 'vendor/swiper';

@import 'base/variables';
// Other custom styles...

Style Override Strategy

Establish a clear override hierarchy:

// utilities/_overrides.scss
// Highest priority override
[data-override] {
  .ant-btn {
    border-radius: 0 !important;
  }
}

// Component-level override
.enhanced-table {
  .ant-table-cell {
    background-color: #f9f9f9;
  }
}

Code Splitting Practice

Split CSS by route (with build tools):

// React example
import(/* webpackChunkName: "dashboard" */ './styles/dashboard.scss');

Corresponding file structure:

styles/
├── routes/
│   ├── _dashboard.scss
│   ├── _profile.scss
│   └── _settings.scss

Style Documentation

Add usage instructions:

// components/_tooltip.scss
/**
 * Tooltip component
 * @example
 * <div class="tooltip" data-tooltip="Tooltip content">
 *   Hover element
 * </div>
 */
.tooltip {
  position: relative;
  
  &::after {
    content: attr(data-tooltip);
    position: absolute;
    /* Other styles */
  }
}

Build Output Control

Configure output for different environments:

// webpack.config.js
{
  test: /\.scss$/,
  use: [
    {
      loader: MiniCssExtractPlugin.loader,
      options: {
        publicPath: isProd ? '/dist/css/' : '/'
      }
    },
    'css-loader',
    'sass-loader'
  ]
}

Style Linting Configuration

.stylelintrc configuration example:

{
  "extends": "stylelint-config-standard",
  "rules": {
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$",
    "no-descending-specificity": null
  },
  "ignoreFiles": [
    "**/vendor/**",
    "**/node_modules/**"
  ]
}

Performance Optimization Structure

Critical CSS extraction solution:

// critical/_above-the-fold.scss
.hero-banner,
.primary-nav {
  // Above-the-fold necessary styles
}

// Build script
postcss([
  require('critical-split')({
    output: 'critical',
    block: 'critical'
  })
])

Theme Switching Implementation

Multi-theme file structure:

styles/
├── themes/
│   ├── _light.scss
│   ├── _dark.scss
│   └── _high-contrast.scss
└── ...

Theme switching logic:

// main.scss
@import 'themes/light';

[data-theme="dark"] {
  @import 'themes/dark';
}

[data-theme="high-contrast"] {
  @import 'themes/high-contrast';
}

Style Debugging Techniques

Add environment markers:

// utilities/_debug.scss
.debug * {
  outline: 1px solid rgba(255, 0, 0, 0.2);
  
  @at-root body:before {
    content: 'Breakpoint: default';
    position: fixed;
    /* Other positioning styles */
  }

  @media (min-width: 768px) {
    @at-root body:before {
      content: 'Breakpoint: tablet';
    }
  }
}