Stylesheet configuration

This document explains how stylesheets are organized and managed in the SignalWire documentation platform.

Types of Stylesheets

Our documentation uses three types of stylesheets with different purposes:

1. Core Stylesheets - Foundation styles that define the site's visual identity and base variables
2. Customization Stylesheets - Feature and component-specific styles that control how content is presented
3. Plugin Stylesheets - Specialized styles for third-party and custom plugins

These stylesheets are using the SCSS file format. SCSS is a preprocessor that allows us to write more efficient and maintainable CSS. SCSS is enabled by utilizing the Docusaurus Sass plugin.

---

Core Stylesheets

These files establish the fundamental visual framework of the site.

Core Structure

Core stylesheets are organized in the root /src/css/ directory:

src/css/
├── common.scss
├── signalwire.scss
└── neue-einstellung.scss

Purpose of Each Core File

Common Styles (_common.scss)

The central configuration file that establishes the site's visual foundation. Any global variables or base styles that need to be accessed throughout the platform & plugins should be defined here.

Brand Styles (_signalwire.scss)

Manages SignalWire's visual identity throughout the platform. This file ensures brand consistency across all components and features of the documentation. This file makes it easy to change the brand colors, fonts, etc.

Font Configuration (_neue-einstellung.scss)

Handles all aspects of the custom font implementation to ensure consistent typography across the platform.

---

Customization Stylesheets

These files handle specific features and components of the documentation platform. This is where you can change the colors, fonts, etc. for specific components & JSX elements.

Customization Structure

Located in /src/css/customizations/:

customizations/
├── articles.scss
├── markdown.scss
├── site.scss
└── index.scss

Purpose of Each Customization File

Article Styles (_articles.scss)

Manages the visual presentation of all documentation content, ensuring consistent and readable article layouts throughout the platform.

Markdown Utilities (_markdown.scss)

Provides a collection of utility classes that content authors can use directly in markdown files to maintain consistent styling patterns.

Site Structure (_site.scss)

Controls the overall layout and navigation structure of the documentation platform, handling how users interact with and move through the documentation.

---

Plugin Stylesheets

Specialized styles for plugin integration and customization. Each plugin that requires custom styling should have its own stylesheet file to maintain separation of concerns and ensure styles don't conflict with the core platform.

Plugin Structure

Located in /src/css/customizations/plugins/:

plugins/
├── index.scss # Main entry point for all plugin styles
└── plugin_name.scss # Individual plugin styles

Purpose of Plugin Styles

Plugin stylesheets allow for custom styling of third-party and custom plugins while maintaining consistency with the platform's design language. These styles ensure that plugin components integrate seamlessly with the rest of the documentation platform.

Adding New Plugin Styles

When a plugin needs custom styling:

1. Create a new file in the plugins directory following the naming convention:

   _plugin_name.scss
   

2. Import it in the plugins index file:

   // plugins/index.scss
   @import "./_plugin_name";

This modular approach allows for:

• Easy addition and removal of plugin styles
• Clear separation of plugin-specific styling
• Maintainable and scalable plugin customization

---

Stylesheet Processing Pipeline

Styles are processed in this order to ensure proper cascade and specificity:

1. Core Processing

   • Global variables and foundations
   • Brand identity elements
   • Typography system

2. Customization Processing

   • Component-specific styles
   • Layout structures
   • Utility classes

3. Plugin Processing

   • Plugin-specific customizations
   • Component overrides
   • Special features

Best Practices

1. File Organization

   • Group related styles together
   • Follow the established file structure
   • Maintain clear dependencies

2. Style Management

   • Use variables for consistency
   • Follow naming conventions
   • Keep styles modular

3. Documentation

   • Document style purposes
   • Explain complex patterns
   • Note dependencies

---

Troubleshooting

When debugging style issues:

1. Core Style Issues

   • Check variable definitions
   • Verify import order
   • Review cascade order

2. Customization Issues

   • Verify style scope
   • Check class specificity
   • Review media queries

3. Plugin Style Issues

   • Check plugin version compatibility
   • Verify style overrides
   • Review plugin documentation