Color tokens and responsive utility classes

The Alliance Research Indicators SPA uses a CSS custom property (CSS variable) system for all color and spacing decisions. Tokens are declared on :root in src/styles/colors.scss and are consumed either directly as var(--ac-*) in component SCSS or indirectly through the generated utility class system. Dark mode is implemented by overriding the same token names under a [data-theme='dark'] selector — no branching on a isDarkMode() flag in component logic is ever needed or allowed.

Color token system

All color tokens follow the naming pattern --ac-<family>-<shade>. Shades increase in darkness from 100 (lightest) to the highest number in each family. Singleton colors (like orange, white, background, and red) use a numeric suffix (-1, -2).

Never use hex color literals in component SCSS or inline styles. Always reference a token via var(--ac-*) or the corresponding utility class (.abc-* / .atc-*). Hard-coded hex values break dark mode and make global rebranding impossible.

Light blue

Used for informational accents and links.

Token	Light mode value
`--ac-light-blue-100`	`#79d9ff`
`--ac-light-blue-200`	`#00b6ff`
`--ac-light-blue-300`	`#1689ca`
`--ac-light-blue-400`	`#035ba9`
`--ac-light-blue-500`	`#074b86`

Primary blue

Used for brand elements, navbar, and primary CTAs.

Token	Light mode value
`--ac-primary-blue-100`	`#b0c4dd`
`--ac-primary-blue-200`	`#7c9cb9`
`--ac-primary-blue-300`	`#345b8f`
`--ac-primary-blue-400`	`#153c71`
`--ac-primary-blue-500`	`#173f6f`
`--ac-primary-blue-600`	`#112f5c`
`--ac-primary-blue-700`	`#0b1e3c`

Green

Used for indicator families 1–3 (capacity sharing, innovation development, policy change).

Token	Light mode value
`--ac-green-100`	`#d3e7d5`
`--ac-green-200`	`#a8ceab`
`--ac-green-300`	`#7cb580`
`--ac-green-400`	`#509c55`
`--ac-green-500`	`#358540`
`--ac-green-600`	`#235b2d`
`--ac-green-700`	`#1f4e24`

Grey

Used for neutrals, borders, and body text.

Token	Light mode value
`--ac-grey-100`	`#f4f7f9`
`--ac-grey-200`	`#e8ebed`
`--ac-grey-300`	`#d1d6da`
`--ac-grey-400`	`#b9c0c5`
`--ac-grey-500`	`#a2a9af`
`--ac-grey-600`	`#8d9299`
`--ac-grey-700`	`#777c83`
`--ac-grey-800`	`#4c5158`
`--ac-grey-900`	`#191919`

Singleton tokens

Token	Light mode value	Use
`--ac-orange-1`	`#f58220`	Indicator families 4–5
`--ac-white-1`	`#fff`	Surface — primary white
`--ac-white-2`	`#fcfcfc`	Surface — off-white
`--ac-background`	`#f5f5f5`	Page background
`--ac-red-1`	`#cf0808`	Errors and destructive actions

Dark mode

Dark mode is activated by setting data-theme="dark" on the <body> element. The DarkModeService writes this attribute and persists the choice in localStorage via the cache service. When data-theme="dark" is present, every --ac-* token is overridden with a darker equivalent in src/styles/colors.scss:

src/styles/colors.scss (dark mode overrides, excerpt)

[data-theme='dark'] {
  --ac-background:          #191919;
  --ac-light-blue-100:      #4a708b;
  --ac-light-blue-200:      #369;
  --ac-light-blue-300:      #2b5986;
  --ac-light-blue-400:      #23466b;
  --ac-light-blue-500:      #1b3450;
  --ac-primary-blue-100:    #3d5167;
  --ac-primary-blue-200:    #2e3e51;
  /* ... all families follow the same pattern */
  --ac-orange-1:            #ff9d56;
  --ac-white-1:             #e5e5e5;
  --ac-white-2:             #dcdcdc;
  --ac-red-1:               #ff4d4d;
}

Because every color decision goes through var(--ac-*), components automatically adapt to both modes with zero branching. PrimeNG Aura preset overrides are handled separately in src/app/theme/roartheme.ts.

Never branch on isDarkMode() for color decisions. A component that uses var(--ac-primary-blue-500) or .abc-primary-blue-500 just works in both modes without any conditional logic.

Utility class system

The generate-color-classes SCSS mixin in src/styles/colors.scss automatically generates two classes for every token in the color map:

.abc-<color-name> — applies background-color: var(--ac-<color-name>) with a 0.3s transition
.atc-<color-name> — applies color: var(--ac-<color-name>) with a 0.3s transition
.abc-<color-name>-i — same as .abc-* with !important
.atc-<color-name>-i — same as .atc-* with !important

Usage in templates

<!-- Background + text from different families -->
<div class="abc-light-blue-100 atc-primary-blue-500">
  Light blue background, deep blue text
</div>

<!-- Status badge using green family -->
<span class="abc-green-100 atc-green-700 rs-p-[8]">
  Submitted
</span>

<!-- Error state using red token -->
<p class="atc-red-1">This field is required.</p>

Usage in component SCSS (when utility classes are not enough)

.custom-element {
  background-color: var(--ac-light-blue-300);
  color: var(--ac-primary-blue-700);
  border: 1px solid var(--ac-grey-300);
}

Correct vs incorrect patterns

.result-card {
  background-color: var(--ac-grey-100);
  border-color: var(--ac-grey-300);
  color: var(--ac-grey-900);
}

Responsive size utilities

Responsive utility classes are defined in src/styles/responsive-size.scss. They cover font size, dimensions, gaps, margins, and padding. All classes accept an integer value n in square brackets. Most utilities range from 1 to 30; size (rs-size-*, rs-w-*, rs-h-*) ranges from 0 to 500. Every utility has a .md: prefixed variant that applies only on landscape orientation with height ≤ 768 px. The .md: variants use !important to guarantee they override base rules.

Class	Effect
`.fs-[n]`	`font-size: npx` (n = 1–30)
`.md:fs-[n]`	Same, scoped to the `md:` breakpoint

Width and height

<!-- Square icon container: 40×40px normally, 32×32px on compact screens -->
<span class="rs-size-[40] md:rs-size-[32]"></span>

<!-- Fixed-width sidebar item -->
<div class="rs-w-[200] rs-h-[48]">...</div>

Class	Effect
`.rs-size-[n]`	Sets both `width` and `height` to `npx` (n = 0–500)
`.rs-w-[n]`	`width: npx`
`.rs-h-[n]`	`height: npx`
`.md:rs-size-[n]` / `.md:rs-w-[n]` / `.md:rs-h-[n]`	Breakpoint variants

Gap utilities

<!-- Flex row: 16px gap normally, 8px on compact screens -->
<div class="d-flex rs-gap-[16] md:rs-gap-[8]">...</div>

<!-- Different horizontal and vertical gaps -->
<div class="rs-gap-x-[12] rs-gap-y-[8]">...</div>

Class	Effect
`.rs-gap-[n]`	`gap: npx` (all directions)
`.rs-gap-x-[n]`	`column-gap: npx`
`.rs-gap-y-[n]`	`row-gap: npx`
`.md:rs-gap-[n]` / `.md:rs-gap-x-[n]` / `.md:rs-gap-y-[n]`	Breakpoint variants

Margin utilities

<div class="rs-m-[20]">20px margin all sides</div>
<div class="rs-mx-[10] rs-my-[15]">horizontal 10px, vertical 15px</div>
<div class="rs-mt-[10] rs-mb-[20] rs-ml-[15] rs-mr-[15]">individual sides</div>

Class	Effect
`.rs-m-[n]`	`margin: npx`
`.rs-my-[n]`	`margin-top` and `margin-bottom`
`.rs-mx-[n]`	`margin-left` and `margin-right`
`.rs-mt-[n]` / `.rs-mb-[n]` / `.rs-ml-[n]` / `.rs-mr-[n]`	Individual sides
`.md:rs-m-[n]` / `.md:rs-my-[n]` / etc.	Breakpoint variants

Padding utilities

<div class="rs-p-[20]">20px padding all sides</div>
<div class="rs-px-[10] rs-py-[15]">horizontal 10px, vertical 15px</div>
<div class="rs-pt-[10] rs-pb-[20] rs-pl-[15] rs-pr-[15]">individual sides</div>

Class	Effect
`.rs-p-[n]`	`padding: npx`
`.rs-py-[n]`	`padding-top` and `padding-bottom`
`.rs-px-[n]`	`padding-left` and `padding-right`
`.rs-pt-[n]` / `.rs-pb-[n]` / `.rs-pl-[n]` / `.rs-pr-[n]`	Individual sides
`.md:rs-p-[n]` / `.md:rs-py-[n]` / etc.	Breakpoint variants

Visibility utilities

Class	Effect
`.rs-hide`	`display: none` on all screen sizes
`.md-rs-hide`	`display: none` only on the `md:` breakpoint

PrimeNG theme preset

The custom PrimeNG Aura preset is defined in src/app/theme/roartheme.ts. It overrides the Aura defaults with the Alliance brand’s primary color scale, border radii, form field sizing, and both light and dark color schemes. The primary semantic scale in the preset is derived from the Alliance primary blue palette:

src/app/theme/roartheme.ts (primary scale)

semantic: {
  primary: {
 '#f2f7fb',
'#c3d8ea',
'#93b8da',
'#6399ca',
'#337ab9',
'#035ba9',   // --ac-light-blue-400
'#034d90',
'#024076',
'#02325d',
'#012444',
'#01172a'
  }
}

The PrimeNG preset controls the interactive state colors (hover, focus, active, highlight) for all PrimeNG components. Do not override individual PrimeNG component styles with hex values — extend the preset or use the custom-prime-force-styles.scss override file.

Quick reference

Goal	Tool
Set background color	`.abc-<token-name>` utility class
Set text color	`.atc-<token-name>` utility class
Use a color in SCSS	`var(--ac-<token-name>)`
Set font size	`.fs-[n]` / `.md:fs-[n]`
Set element dimensions	`.rs-size-[n]`, `.rs-w-[n]`, `.rs-h-[n]`
Set gaps in flex/grid	`.rs-gap-[n]`, `.rs-gap-x-[n]`, `.rs-gap-y-[n]`
Set margin	`.rs-m-[n]`, `.rs-mx-[n]`, `.rs-my-[n]`, individual side variants
Set padding	`.rs-p-[n]`, `.rs-px-[n]`, `.rs-py-[n]`, individual side variants
Compact layout override	Prefix any of the above with `.md:`
Hide on compact screens	`.md-rs-hide`

Setup & Development

Architecture

Contributing

Color token system

Light blue

Primary blue

Green

Grey

Singleton tokens

Dark mode

Utility class system

Usage in templates

Usage in component SCSS (when utility classes are not enough)

Correct vs incorrect patterns

Responsive size utilities

Font size

Width and height

Gap utilities

Margin utilities

Padding utilities

Visibility utilities

PrimeNG theme preset

Quick reference

Build docs developers (and LLMs) love

Setup & Development

Architecture

Contributing

Documentation Index

​Color token system

​Light blue

​Primary blue

​Green

​Grey

​Singleton tokens

​Dark mode

​Utility class system

​Usage in templates

​Usage in component SCSS (when utility classes are not enough)

​Correct vs incorrect patterns

​Responsive size utilities

​Font size

​Width and height

​Gap utilities

​Margin utilities

​Padding utilities

​Visibility utilities

​PrimeNG theme preset

​Quick reference

Build docs developers (and LLMs) love

Color token system

Light blue

Primary blue

Green

Grey

Singleton tokens

Dark mode

Utility class system

Usage in templates

Usage in component SCSS (when utility classes are not enough)

Correct vs incorrect patterns

Responsive size utilities

Font size

Width and height

Gap utilities

Margin utilities

Padding utilities

Visibility utilities

PrimeNG theme preset

Quick reference