2025-10-30 17:22:03 +01:00
|
|
|
# styling Specification
|
2025-10-27 22:04:52 +01:00
|
|
|
|
2025-10-30 17:22:03 +01:00
|
|
|
## Purpose
|
|
|
|
|
TBD - created by archiving change add-custom-bootstrap-styling. Update Purpose after archive.
|
|
|
|
|
## Requirements
|
2025-10-27 22:04:52 +01:00
|
|
|
### Requirement: SCSS Processing Pipeline
|
|
|
|
|
The system SHALL process SCSS files using Hugo Pipes to generate custom CSS that supplements Bootstrap's CDN-provided styles.
|
|
|
|
|
|
|
|
|
|
#### Scenario: SCSS compilation on build
|
|
|
|
|
- **WHEN** Hugo builds the site
|
|
|
|
|
- **THEN** SCSS files in `assets/scss/` are compiled to CSS
|
|
|
|
|
- **AND** the compiled CSS is fingerprinted for cache busting
|
|
|
|
|
- **AND** the resulting CSS file is included in the HTML output
|
|
|
|
|
|
|
|
|
|
#### Scenario: Development mode with live reload
|
|
|
|
|
- **WHEN** running Hugo in development mode (hugo server)
|
|
|
|
|
- **THEN** SCSS changes trigger automatic recompilation
|
|
|
|
|
- **AND** the browser live-reloads with updated styles
|
|
|
|
|
|
|
|
|
|
### Requirement: Bootstrap Variable Customization
|
|
|
|
|
The system SHALL allow customization of Bootstrap design tokens through SCSS variables without modifying the CDN-provided Bootstrap CSS.
|
|
|
|
|
|
|
|
|
|
#### Scenario: Override heading font sizes
|
|
|
|
|
- **WHEN** custom heading sizes are defined in SCSS variables
|
|
|
|
|
- **THEN** the compiled CSS applies these sizes to heading elements
|
|
|
|
|
- **AND** the Bootstrap CDN CSS is loaded first (base styles)
|
|
|
|
|
- **AND** custom CSS is loaded after (overrides)
|
|
|
|
|
|
|
|
|
|
#### Scenario: Override link colors
|
|
|
|
|
- **WHEN** custom link colors are defined in SCSS variables
|
|
|
|
|
- **THEN** links across the site use the custom colors
|
|
|
|
|
- **AND** link hover states use appropriate custom colors
|
|
|
|
|
|
|
|
|
|
#### Scenario: Override spacing scale
|
|
|
|
|
- **WHEN** custom spacing values are defined
|
|
|
|
|
- **THEN** elements using those spacing classes reflect the custom values
|
|
|
|
|
|
|
|
|
|
### Requirement: Custom Style Organization
|
|
|
|
|
The system SHALL organize custom styles in a maintainable SCSS file structure following Hugo and SASS best practices.
|
|
|
|
|
|
|
|
|
|
#### Scenario: Main SCSS entry point
|
|
|
|
|
- **WHEN** Hugo processes SCSS
|
|
|
|
|
- **THEN** a single main SCSS file serves as the entry point
|
|
|
|
|
- **AND** this file imports Bootstrap variable overrides
|
|
|
|
|
- **AND** this file imports custom component styles
|
|
|
|
|
- **AND** this file imports custom utility styles
|
|
|
|
|
|
|
|
|
|
#### Scenario: Modular SCSS files
|
|
|
|
|
- **WHEN** developers add new custom styles
|
|
|
|
|
- **THEN** styles can be organized into separate partial files
|
|
|
|
|
- **AND** partial files are imported into the main SCSS file
|
|
|
|
|
- **AND** file naming follows SCSS conventions (e.g., `_variables.scss`, `_custom.scss`)
|
|
|
|
|
|
|
|
|
|
### Requirement: CSS Output Integration
|
|
|
|
|
The system SHALL integrate compiled custom CSS into the base layout template alongside Bootstrap CDN CSS.
|
|
|
|
|
|
|
|
|
|
#### Scenario: CSS load order
|
|
|
|
|
- **WHEN** a page is rendered
|
|
|
|
|
- **THEN** Bootstrap CDN CSS loads first
|
|
|
|
|
- **AND** custom compiled CSS loads second
|
|
|
|
|
- **AND** CSS files include integrity hashes where applicable
|
|
|
|
|
- **AND** the custom CSS file path includes a fingerprint for cache busting
|
|
|
|
|
|
|
|
|
|
#### Scenario: Production build optimization
|
|
|
|
|
- **WHEN** building for production
|
|
|
|
|
- **THEN** SCSS is compiled with minification
|
|
|
|
|
- **AND** the output CSS is optimized for file size
|
|
|
|
|
- **AND** source maps are not included in production builds
|
2025-10-30 17:22:03 +01:00
|
|
|
|
