Skip to content

SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.

12.2 KB
Raw Blame

CSS Modules Guide

Checklist Before Committing

  • All class names use camelCase in CSS
  • State classes use is-/has- prefix (e.g., isActive, hasError)
  • No bracket access (styles['...']) in JS unless verified
  • No dynamic class lookup - use explicit variant maps instead
  • No deep class nesting (max 3 class levels; pseudo-classes/elements and parent-reference selectors like &.active, &#bar are not counted)
  • No hardcoded colors - use --l1/l2/l3-* semantic tokens (not --bg-* primitives)
  • No magic numbers - use --spacing-* tokens
  • Typography uses --periscope-font-size-* or --font-size-* tokens
  • @signozhq/ui overrides use CSS variables, not direct class overrides
  • Global escapes only for third-party overrides
  • No ID selectors
  • No bare element selectors
  • Keyframes use :local(@keyframes name) to avoid global collisions

Config (vite.config.ts)

css: {
  modules: {
    localsConvention: 'camelCaseOnly',
  },
}

Critical: camelCaseOnly exports ONLY camelCase keys. Original kebab-case NOT accessible.

Quick Reference

CSS Class JS Access Works? Preferred?
.alertHistory styles.alertHistory Yes Yes
.alert-history styles.alertHistory Yes No, use .alertHistory
.alert-history styles['alert-history'] NO - undefined Never, use .alertHistory

Bad Patterns

Class Naming

// BAD: Bracket access won't work
.my-class { }
// Then in JS: styles['my-class'] -> undefined

// BAD: Collision - both become same key
.alertHistory { }
.alert-history { }  // -> styles.alertHistory (conflicts)

// BAD: Underscore inconsistency
.my_class { }  // -> styles.myClass (confusing)

// GOOD: Direct camelCase
.alertHistory { }
.statsCard { }

// GOOD: State classes with is-/has- prefix
.isDisabled { }
.isActive { }
.hasError { }
.isLoading { }

Nesting

// BAD: Deep nesting - specificity wars, hard to override
.container {
  .wrapper {
    .inner {
      .content { }
    }
  }
}

// BAD: Nesting creates separate classes you might not expect
.button {
  .icon { }  // -> styles.icon (separate class, not scoped under .button)
}

// GOOD: Flat structure
.container { }
.containerWrapper { }
.containerContent { }

// GOOD: Nesting only for pseudo/states
.button {
  &:hover { }
  &:disabled { }
  &::before { }
}

Global Escapes

// BAD: Overusing global
:global {
  .everything { }
  .in-here { }
  .is-global { }
}

// BAD: Global without necessity
:global(.myComponent) { }  // defeats purpose of modules

// GOOD: Targeted global for third-party overrides
.container {
  :global(.ant-modal-content) {
    padding: 0;
  }
}

Selectors

// BAD: ID selectors - not reusable
#myComponent { }

// BAD: Element selectors without scope
div { }  // affects ALL divs in component

// BAD: Complex selectors
.container > div + span ~ p { }

// GOOD: Class-only selectors
.container { }
.title { }

Variables & Values

// BAD: Hardcoded colors
.button {
  background: #1890ff;
  color: white;
}

// BAD: Magic numbers
.container {
  padding: 17px;
  margin-left: 43px;
}

// GOOD: Semantic tokens (theme-aware)
.button {
  background: var(--primary-background);
  color: var(--primary-foreground);
}

.card {
  background: var(--l2-background);
  color: var(--l2-foreground);
}

// GOOD: Spacing system
.container {
  padding: var(--spacing-4);
  margin-left: var(--spacing-5);
}

Design Tokens (@signozhq/design-tokens)

Prefer semantic tokens over hardcoded values.

You can read the ./node_modules/@signozhq/design-tokens/dist/style.css to find complete list of available tokens.

Spacing

// Spacing scale (index -> px):
// --spacing-0=0    --spacing-1=2    --spacing-2=4    --spacing-3=6    --spacing-4=8
// --spacing-5=10   --spacing-6=12   --spacing-7=14   --spacing-8=16   --spacing-10=20
// --spacing-12=24  --spacing-16=32  --spacing-20=40  --spacing-24=48  --spacing-32=64
// --spacing-40=80  --spacing-48=96  --spacing-56=112 --spacing-64=128
// (index != px; --spacing-2 is 4px, not 2px)
.container {
  padding: var(--spacing-4);      // 8px
  gap: var(--spacing-6);          // 12px
  margin-bottom: var(--spacing-8); // 16px
}

// Also available: --padding-* and --margin-* (rem-based)
// --padding-1 = 0.25rem, --padding-4 = 1rem, etc.

Typography

// Font sizes (preferred)
.title {
  font-size: var(--periscope-font-size-large);   // 18px
  font-size: var(--periscope-font-size-medium);  // 16px
  font-size: var(--periscope-font-size-base);    // 13px
  font-size: var(--periscope-font-size-small);   // 11px
}

// Alternative scale (rem-based)
.heading {
  font-size: var(--font-size-xl);  // 1.25rem
  font-size: var(--font-size-lg);  // 1.125rem
  font-size: var(--font-size-base); // 1rem
  font-size: var(--font-size-sm);  // 0.875rem
}

// Font weights
.bold {
  font-weight: var(--font-weight-semibold); // 600
  font-weight: var(--font-weight-medium);   // 500
  font-weight: var(--font-weight-normal);   // 400
}

// Line heights
.text {
  line-height: var(--line-height-20); // 20px
  line-height: var(--line-height-24); // 24px
}

Colors (Prefer Semantic Tokens)

Use L1/L2/L3 semantic tokens - they handle light/dark theme automatically.

// BAD: Primitive tokens (fixed value across themes, won't swap on theme change)
.card {
  background: var(--bg-ink-400);
  color: var(--text-vanilla-100);
}

// GOOD: L1/L2/L3 tokens (theme-aware - swap automatically light/dark)
.card {
  background: var(--l1-background);  // base layer
  color: var(--l1-foreground);       // primary text
}

.panel {
  background: var(--l2-background);  // elevated surface
  color: var(--l2-foreground);       // secondary text
  border-color: var(--l2-border);
}

.nested {
  background: var(--l3-background);  // nested/inset
  color: var(--l3-foreground);       // tertiary text
}

// Hover states
.card:hover {
  background: var(--l1-background-hover);
  color: var(--l1-foreground-hover);
}

// Semantic action colors (also theme-aware)
.primary {
  background: var(--primary-background);
  color: var(--primary-foreground);
}

.danger {
  background: var(--danger-background);
  color: var(--danger-foreground);
}

.success {
  background: var(--success-background);
  color: var(--success-foreground);
}

.warning {
  background: var(--warning-background);
  color: var(--warning-foreground);
}

// Accent colors (for highlights, badges, etc.)
.accent {
  background: var(--accent-primary);        // robin blue
  background: var(--accent-forest);         // green
  background: var(--accent-cherry);         // red
  background: var(--accent-amber);          // yellow
}

Token hierarchy:

  • Primitive tokens (--bg-*, --text-*, etc.) have fixed values across themes.
  • Semantic tokens (L1/L2/L3, --primary-*, --danger-*, etc.) automatically swap based on theme.
  • L1 = base/root layer
  • L2 = elevated surfaces (cards, panels)
  • L3 = nested/inset elements

Overriding @signozhq/ui Components

Components expose CSS variables for customization.

You can ensure they exist by looking at ./node_modules/@signozhq/ui/dist. Never write a override without confirm it exists.

Override via:

Method 1: CSS Variables (Preferred)

Each component exposes --<component>-<property> variables:

// Override Button
.customButton {
  --button-background: var(--success-background);
  --button-border-radius: var(--radius-2);
  --button-padding: var(--spacing-4) var(--spacing-8);
  --button-font-size: var(--periscope-font-size-base);
}

// Override Input
.customInput {
  --input-height: 2.5rem;
  --input-border-color: var(--l2-border);
  --input-padding: var(--spacing-2) var(--spacing-6);
  --input-placeholder-color: var(--l3-foreground);
}

// Override nested parts
.customInput {
  --input-prefix-padding: 0 var(--spacing-4) 0 var(--spacing-6);
  --input-suffix-color: var(--accent-primary);
}

Method 2: Data Attributes

Components use data attributes for variants/states. Target them for state-specific overrides:

// Target variant
.wrapper :global([data-variant="outlined"]) {
  --button-border-color: var(--accent-primary);
}

// Target size
.wrapper :global([data-size="sm"]) {
  --button-font-size: var(--periscope-font-size-small);
}

// Target color
.wrapper :global([data-color="destructive"]) {
  --button-background: var(--danger-background);
}

// Target state (Radix patterns)
.popover :global([data-state="open"]) {
  opacity: 1;
}

.tooltip :global([data-side="top"]) {
  margin-bottom: var(--spacing-2);
}

Common Component CSS Variables

Button:

  • --button-background, --button-border-radius, --button-padding
  • --button-font-size, --button-height, --button-gap
  • --button-hover-background, --button-disabled-opacity

Input:

  • --input-height, --input-border-color, --input-background
  • --input-padding, --input-font-size, --input-placeholder-color
  • --input-focus-outline-color, --input-hover-border-color
  • --input-prefix-*, --input-suffix-* for adornments

General pattern: --<component>-<property> or --<component>-<state>-<property>

Good Patterns

Structure

// Flat, descriptive, component-scoped
.alertHistory { }
.alertHistoryHeader { }
.alertHistoryContent { }
.alertHistoryFooter { }

// State modifiers as separate classes
.alertHistory { }
.alertHistoryLoading { }
.alertHistoryEmpty { }
.alertHistoryError { }

Composition

// GOOD: Composing styles
.baseButton {
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-2);
}

.primaryButton {
  composes: baseButton;
  background: var(--primary-background);
}

Pseudo Elements

.button {
  // States
  &:hover { opacity: 0.9; }
  &:focus { outline: 2px solid var(--ring); outline-offset: 2px; }
  &:disabled { opacity: 0.5; cursor: not-allowed; }

  // Pseudo elements
  &::before { content: ''; }
  &::after { content: ''; }
}

Media Queries

.container {
  display: flex;
  flex-direction: column;
  
  @media (min-width: 768px) {
    flex-direction: row;
  }
}

Keyframes (Local Scoping)

Without :local(), keyframe names are global and can clash across modules:

// BAD: Global keyframe - can conflict with other modules
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

// GOOD: Locally scoped keyframe
:local(@keyframes fadeIn) {
  from { opacity: 0; }
  to { opacity: 1; }
}

.modal {
  animation: fadeIn 200ms ease;
}

JS Import Patterns

// GOOD
import styles from './Component.module.scss';

<div className={styles.container}>
  <span className={styles.title}>Title</span>
</div>

// GOOD: Conditional classes
<div className={`${styles.button} ${isActive ? styles.buttonActive : ''}`}>

// GOOD: With clsx/classnames
<div className={clsx(styles.button, { [styles.buttonActive]: isActive })}>

// BAD: Bracket access (may be undefined)
<div className={styles['button-active']}>  // undefined if CSS has .button-active

// BAD: String interpolation for class names
<div className={`${styles.button}-active`}>  // won't work

// BAD: Dynamic class lookup - can't be statically analyzed
const cls = styles[`variant${props.type}`];  // Vite can't tree-shake or type-check

// GOOD: Explicit map for dynamic variants
const variantMap = {
  primary: styles.variantPrimary,
  secondary: styles.variantSecondary,
  ghost: styles.variantGhost,
};
const cls = variantMap[props.type];

Lint Rules

JS/TS (oxlint)

Rule Severity Catches
signoz/no-css-module-bracket-access warn styles['kebab-case'], dynamic access

CSS/SCSS (stylelint)

Rule Severity Catches
local/no-deep-nesting warning class nesting >3 levels (pseudo-classes/elements and parent-reference selectors &.foo, &#bar not counted; configurable via maxDepth secondary option)
local/no-id-selectors error #id selectors
local/no-bare-element-selectors error root-level div, span etc
local/prefer-css-variables warning hardcoded colors
local/class-name-pattern warning kebab-case, snake_case, PascalCase

Run: pnpm lint:styles to check CSS modules.