CSS

Overview

This guide explains the CSS/SCSS architecture, file organization, naming conventions, design tokens, and best practices for building maintainable and scalable UI components in the Raaghu Design System.

File Organization Structure

Component-Level Styles

Each RDS component follows a strict structure:

raaghu-elements/
├── rds-{component-name}/
│   ├── rds-{component-name}.tsx          # React component
│   ├── rds-{component-name}.stories.tsx  # Storybook stories
│   └── rds-{component-name}.scss         # Component-specific styles

Layout-Level Styles

raaghu-layouts/
├── rds-comp-{layout-name}/
│   ├── rds-comp-{layout-name}.tsx
│   ├── rds-comp-{layout-name}.stories.tsx
│   └── rds-comp-{layout-name}.css        # Layout-specific styles

Theme Styles

raaghu-react-themes/
├── src/
│   └── styles/
│       ├── index.scss                    # Main theme entry
│       ├── variables/
│       │   └── color-variables.scss      # Color tokens
│       └── themes/
│           ├── light.scss               # Light theme
│           ├── dark.scss                # Dark theme

Naming Conventions

BEM (Block Element Modifier) with RDS Prefix

.rds-{component-name} { }
.rds-{component-name}__element { }
.rds-{component-name}--modifier { }
.rds-{component-name}__element--modifier { }

Examples

.rds-button { }
.rds-button__icon { }
.rds-button--primary { }
.rds-button--large { }
.rds-card { }
.rds-card__header { }
.rds-card--elevation-2 { }

SCSS Structure Standards

Component SCSS Template

.rds-{component-name} {
  // Base styles
  display: block;

  // Elements
  &__element {
    // Element styles
  }

  // Modifiers
  &--variant {
    // Variant styles
  }

  // States
  &:hover { }
  &:focus { }
  &:disabled { }
}

Design Tokens Usage

Use CSS custom properties for colors, spacing, typography, and elevation:

background-color: var(--rds-color-primary);
padding: var(--rds-spacing-md);
border-radius: var(--rds-border-radius);
box-shadow: var(--rds-elevation-2);

Implementation Checklist

• Component has corresponding .scss file
• SCSS uses BEM naming with rds- prefix
• Styles include all necessary variants and states
• Design tokens are used for colors and spacing
• Accessibility states are styled
• Component is exported in package index.ts

Accessibility & Performance

• Include focus states for interactive elements
• Ensure sufficient color contrast
• Support screen readers with .sr-only class
• Minimize CSS specificity conflicts
• Avoid deep nesting (max 3 levels)
• Use efficient selectors

Best Practices

1. Isolation: Keep styles self-contained per component
2. Consistency: Use established naming and spacing patterns
3. Maintainability: Document complex styles, use meaningful names
4. Performance: Purge unused CSS, use tree-shaking, minify for production
5. Accessibility: Test keyboard navigation, color contrast, and focus states

Development Tools

• SCSS IntelliSense
• Live Sass Compiler
• CSS Peek
• Prettier - Code formatter

Linting Configuration

{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "selector-class-pattern": "^rds-[a-z]([a-z0-9-]+)?(__([a-z0-9]+-?)+)?(--([a-z0-9]+-?)+)?$"
  }
}