# Topper Client SCSS Architecture

This folder contains the SCSS source for Topper presentation classes (`.o-topper*`).

## High-level compile flow

Entry point: `main.scss`

Import order in `main.scss`:

1. `./variables`
2. `./mixins`
3. `./grid`
4. `./elements`
5. `./layout`
6. `./themes/*`
7. `./colors/colors`

After imports, `main.scss` defines `@mixin oTopper(...)`, which is the orchestrator:

- Reads options from `$opts`:
  - `themes` (defaults to `$_o-topper-themes`)
  - `elements` (defaults to `$_o-topper-elements`)
  - `colors` (defaults to `$_o-topper-colors`)
- Optionally outputs base shell styles via `_oTopperBase`
- Calls:
  - `_oTopperElements($elements)` to emit element selectors
  - `_oTopperThemes($themes, $colors)` to emit theme selectors

By default this repo auto-emits once:

- If `$o-topper-is-silent == false`, `@include oTopper()` runs immediately.
- Then `$o-topper-is-silent` is set to `true !global` to prevent duplicate output.

`main.scss` also includes local cp-pipeline-only modifiers:

- `.o-topper--full-grid`
- `.o-topper--in-line`

## File responsibilities

### `_variables.scss`

Defines the controlling lists and flags:

- `$_o-topper-elements`: which element selectors may be generated
- `$_o-topper-themes`: which theme selectors may be generated
- `$_o-topper-colors`: supported color variants
- `$o-topper-is-silent`: auto-output toggle
- `$_o-topper-defined`: registry used by `_oTopperDefineOnce(...)`

Important: comments in this file already note that README should be updated when adding elements/themes/colors.

### `_mixins.scss`

Contains:

- utility typography mixins (`_oTypographyList`, `_oTypographyLink`)
- composition gates:
  - `_oTopperElements($elements)`
  - `_oTopperThemes($themes, $colors)`
- helper mixins used across themes/elements (`_oTopperAlignText`, `_oTopperDefineOnce`, etc)

This is the key "switchboard": each `@if index($elements, '...')` or `@if index($themes, '...')` block decides whether a selector is emitted.

### `_elements.scss`

Defines low-level styling mixins for individual pieces, for example:

- `_oTopperStandfirst`
- `_oTopperSummary`
- `_oTopperSummaryBody`
- `_oTopperImage`, `_oTopperImageCredit`, `_oTopperImageCaption`
- tag mixins (`_oTopperBrand`, `_oTopperTopic`)

These do not choose what to output; they provide the style bodies used by `_oTopperElements(...)`.

### `_grid.scss`

Defines reusable grid skeleton mixins:

- `_oTopperArticleGrid`
- `_oTopperArticleGridCentered`

These are consumed by base/layout/theme mixins.

### `_layout.scss`

Defines structural/base layout mixins:

- `_oTopperBase` (base shell for `.o-topper`)
- `_oTopperBasic`
- `_oTopperCentered`
- core region mixins (`_oTopperContent`, `_oTopperBackground`, `_oTopperVisual`, `_oTopperReadNext`)

### `themes/*.scss`

Each file contributes one or more theme-specific mixins, e.g.:

- `_oTopperThemeBranded`, `_oTopperThemeOpinion`, `_oTopperHasHeadshot`
- `_oTopperThemeFullBleedOffset`
- `_oTopperThemeSplitText`
- `_oTopperThemeFullBleedImage`
- `_oTopperThemePackage*`
- `_oTopperGridRightRail`, `_oTopperFullBleedGridRightRail`
- `_oTopperCentered`
- `_oTopperThemeSplitTextPortraitLeft`, `_oTopperThemeDeepLandscape`

`_oTopperThemes(...)` in `_mixins.scss` wires these mixins to public classes like `.o-topper--branded`, `.o-topper--split-text-center`, etc.

### `colors/*.scss`

Color files output modifier classes of the form:

- `.o-topper--color-<name>`

Each class sets background/text/link/hover rules for that palette and may include theme-specific tweaks (for example deep-landscape/deep-portrait adjustments).

`colors/_colors.scss` is only an import barrel for all color partials.

## How selectors are generated

At compile time, output is determined by the three lists passed to `@include oTopper(...)`:

- elements list controls `.o-topper__*` selector emission
- themes list controls `.o-topper--*` theme selector emission
- colors list is currently accepted as an option and passed through theme plumbing; color class definitions are imported from `colors/*.scss`

Example usage pattern:

```scss
@include oTopper(
  (
    'elements': ('content', 'headline', 'standfirst'),
    'themes': ('basic', 'right-rail'),
    'colors': ('white', 'black')
  ),
  $include-base-styles: true
);
```

## Practical change guide

When adding new styling capabilities:

1. Add low-level style mixin in `_elements.scss`, `_layout.scss`, `_grid.scss`, or a theme/color partial.
2. Register the new key in `_variables.scss` (elements/themes/colors list).
3. Add conditional emission in `_oTopperElements(...)` or `_oTopperThemes(...)` (usually `_mixins.scss`).
4. If needed, import new partial from `main.scss` (or `colors/_colors.scss` for colors).
5. Update this README list so available options stay accurate.