xrpl-dev-portal/styles

XRPL Styles

This folder contains the source files for the XRP Ledger Dev Portal CSS. The optimized, minified version of these styles is /static/css/devportal2024-v1.css.

Build Pipeline

The CSS build uses a modern optimization pipeline:

1. Sass - Compiles SCSS to CSS
2. PostCSS - Processes CSS with plugins:
   • PurgeCSS - Removes unused CSS (production only)
   • Autoprefixer - Adds vendor prefixes for browser compatibility
   • cssnano - Minifies and optimizes CSS (production only)

Performance Improvements

The optimized build dramatically improves CSS delivery:

Metric	Before	After	Improvement
Uncompressed	486.64 KB	280.92 KB	42% smaller
Gzipped (network)	71.14 KB	43.32 KB	39% smaller

This improves page load times, developer experience (DevTools filter: 60s → <1s), and reduces bandwidth costs.

Prerequisites

All dependencies are automatically installed via NPM:

npm install

Key dependencies:

• sass - SCSS compiler
• postcss-cli - PostCSS command-line interface
• @fullhuman/postcss-purgecss - Removes unused CSS
• autoprefixer - Browser compatibility
• cssnano - CSS minification

Building

Production Build

For production deployments with full optimization:

npm run build-css

Includes: PurgeCSS, autoprefixer, minification (no source maps)

Development Build

For local development with debugging:

npm run build-css:dev

Includes: Autoprefixer, source maps (no PurgeCSS for faster builds)

Watch Mode

For continuous compilation during development:

npm run build-css:watch

Auto-rebuilds on file changes with source maps

Analysis

To analyze the CSS bundle composition:

npm run analyze-css

This shows:

• Bundle size and selector counts
• Bootstrap component usage
• Custom component patterns
• Optimization recommendations

Files Structure

Main Entry Point

• xrpl.scss - Master file that imports all other SCSS files, Bootstrap, and defines variables

Component Styles

Each _*.scss file contains styles for specific components:

• _colors.scss - Color palette and variables
• _font-face.scss - Font definitions
• _font.scss - Typography styles
• _layout.scss - Page layout and grid
• _buttons.scss - Button styles
• _forms.scss - Form controls
• _cards.scss - Card components
• _nav-*.scss - Navigation components (top-nav, side-nav)
• _content.scss - Content area styles
• _blog.scss - Blog-specific styles
• _dev-tools.scss - Developer tools styles
• _rpc-tool.scss - RPC tool interface
• _tables.scss - Table styles
• _footer.scss - Footer styles
• _callouts.scss - Callout/alert boxes
• _diagrams.scss - Diagram styles
• _print.scss - Print media styles
• light/_light-theme.scss - Light theme overrides

Configuration

PostCSS Configuration

The PostCSS pipeline is configured in postcss.config.cjs at the project root.

PurgeCSS Safelist:

• Scans all .tsx, .md, .yaml, and .html files for class names
• Preserves dynamically-added classes (Bootstrap JS components, CodeMirror, etc.)
• Keeps state classes (active, disabled, show, etc.)
• Only runs in production builds

Sass Configuration

Sass is configured via command-line flags in package.json:

• --load-path styles/scss - Additional import paths
• --source-map - Generate source maps (dev only)

Troubleshooting

"Classes are missing after build"

If you find missing styles after a production build:

1. Check if the class is dynamically added via JavaScript
2. Add the class pattern to the safelist in postcss.config.cjs
3. Rebuild: npm run build-css

Example safelist patterns:

deep: [
  /my-dynamic-class/, // Keeps .my-dynamic-class and children
]

"Build is too slow"

For development, use:

npm run build-css:watch  # Watch mode (no PurgeCSS)
# or
npm run build-css:dev    # One-time dev build (no PurgeCSS)

"Seeing Sass deprecation warnings"

The warnings about @import are from Bootstrap 5's use of legacy Sass syntax. They're harmless and will be resolved when Bootstrap updates to the new @use syntax.

Adding New Styles

When adding new component styles:

1. Create _component-name.scss in this directory
2. Add @import "_component-name.scss"; to xrpl.scss
3. If using dynamic classes, add them to the PurgeCSS safelist in postcss.config.cjs
4. Test: npm run build-css:dev (dev) and npm run build-css (prod)
5. Analyze: npm run analyze-css

Further Reading

See CSS-OPTIMIZATION.md in the project root for detailed information about the optimization implementation and migration process.