Review application A.2.7

Colours and styles

Every colour in the web app, the maps and the documentation diagrams comes from one small palette. Each colour has a fixed meaning: navy is ATLAS, green is OSM, orange is GTFS, red is an unmatched ATLAS platform. This page lists the palette, what each colour means, where the tokens are defined and how the rules are enforced.

Canonical palette

Primary Navy
#174092 --color-primary
Brand primary color, used for ATLAS markers and UI accents.
OSM Matched Green
#4CAF50 --color-success
Success color, used for matched OSM markers.
ATLAS Unmatched Red
#DC3545 --color-danger
Danger color, used for unmatched ATLAS markers.
Priority P2 Orange
#F0AD4E --color-warning
Warning color, used for significant problems.
OSM Unmatched Gray
#6C757D --color-secondary
Muted color, used for unmatched OSM markers.
Text
#111111 --color-fg
Body text and headings.
Muted Text
#6C757D --color-fg-muted
Secondary text and low-priority elements.
System Border
#E5E7EB --color-border
Standard card and container borders.
Subtle Surface
#F8F9FA --color-bg-subtle
Subtle background for list headers and sections.
Primary Subtle
#eef3fb --color-primary-subtle
Subtle background for info banners.

The palette is defined once as CSS tokens and once as JavaScript constants. Authored CSS references the tokens and never writes a colour value itself, not even an alpha variant of a palette colour.

What the colours mean

Map markers

Marker Colour
Matched ATLAS Navy #174092
Matched OSM Green #4CAF50
Matched GTFS stop_id (GTFS stop_id ↔ SLOID map) Orange #F0AD4E
Unmatched ATLAS Red #DC3545
Unmatched OSM Grey #6C757D
Disused OSM Hollow ring: grey #6C757D stroke and U letter, white fill
Unmatched GTFS stop_id Grey #6C757D

Map lines

Line Colour and style
ATLAS–OSM match Navy #174092, solid
OSM pair partners Green #4CAF50, dashed 6,4
OSM two-sided stop members Green #4CAF50, dashed 6,4

Route family cards

Route family cards use the status family of each marker colour, with a full semantic border and a flat, subtle background: matched ATLAS is primary navy, matched OSM is success green, unmatched ATLAS is danger red, and unmatched OSM is secondary grey. The same families colour the source headings in map popups. The --color-map-* tokens colour what mirrors the map itself, such as legend dots, because they do not change with the theme. Their colours reflect saved family matches; exploring a candidate inside an unmatched variant does not change the family card's status.

Stop links in variant comparisons use the navy of the ATLAS–OSM match line.

Operator tag status

The Operators page lists the operator and operator:wikidata values on each ATLAS operator's matched OSM stops as plain rows with counts, without colour: green stays reserved for OSM and matches, and the counts say more than bar lengths would. Not tagged rows are muted grey italic.

The status pill reuses the status tokens: success for a single consistent value; warning for several values, partial tagging or no tag; muted grey when no stop is matched. Each pill also carries an icon and a label, so colour is never the only signal.

Information banners

Banners carry the global statistics summary and the problem details.

Part Colour
Background Primary subtle #eef3fb
Border Primary border --color-primary-border, navy at 30 % opacity
Text Primary navy #174092

Analytics

The analytics page (/data/analytics) colours only two things: where a number comes from and how severe a problem is.

Part Colour
Bars and charts about ATLAS Navy; a second share of the same total is a lighter navy
Bars and charts about OSM Green; a second share is a lighter green
The rest of a total (unmatched, neither) Grey
Key figures, tables and label/value lists No colour
Problem priorities The priority colours below

Lighter shares use the same token at lower opacity rather than a new colour.

Code quality map

The code map on /quality colours modules from a 10-slot categorical palette (--color-quality-module-1 to --color-quality-module-10) by default and reuses the semantic tokens for alternative encodings and edge types. Its values live in static/css/src/01-settings/tokens.css and are mirrored in static/js/quality/rendering.js because the HTML5 canvas cannot read CSS variables directly:

Encoding or element Token / colour
Module by module (default) Categorical slots --color-quality-module-1 to -10: #2A78D6, #EB6834, #17A173, #99631F, #D6558A, #C98500, #6250D6, #008300, #0E93A8, #E34948 (each ≥ 3:1 on white, ordered to stay distinguishable under protanopia and deuteranopia)
Module by repository Engine green #4CAF50, application navy #174092
Module by criticality Navy #174092 at 100 %, 68 %, 42 % and 20 % over white
Module, file or function by branch coverage Navy #174092 from 14 % (0 % coverage) to 100 % in 10 % steps; unmeasured files use #E9ECEF
Cross-repository contract Shared-owner purple #6B21A8, dotted
Module dependencies Declared: #6C757D solid; undeclared: #E08E0B dashed; declared without static reference: #ADB5BD dotted
File and function links Unselected: #ADB5BD; selected intra-module: #CED4DA; selected declared cross-module: #174092; copied code: #111111 dashed
Node markers Unused function: hollow ring; file > 1,000 lines: #111111 outer ring

Priorities

The same three colours mark priorities in reports, on the Problems page and on the analytics page:

Priority Colour
P1 Red #DC3545 (danger, critical)
P2 Orange #F0AD4E (warning, significant)
P3 Grey #6C757D (secondary, minor)

Documentation diagrams

The SVG diagrams in this documentation use the same tokens. Domain diagrams use the map colours (ATLAS navy, OSM green, GTFS orange, unmatched red); system diagrams use green for the engine, navy for the application and the shared-owner purple #6B21A8 (--color-docs-shared) for the result bundle. The documentation portal marks which project owns a page with the same three colours (A2.8).

Token sources

CSS tokens

Defined in static/css/src/01-settings/tokens.css. Each token names a role, not a colour, so that a second theme can give the same role a different value.

Group Tokens Use
Surfaces --color-bg, --color-bg-subtle, --color-bg-muted Page, card and section backgrounds, from lightest to darkest
--color-surface-glass Translucent panel over the map or a tinted page
--color-surface-veil Lightens what lies beneath it: hover and open states
--color-surface-dark Hints, banners and toggles over a map: dark in both themes
--color-surface-banner, --color-on-banner The translucent zoom banner over a map and its white text: the same in both themes
--color-overlay Backdrop behind modals, drawers and loading screens: dark in both themes
--color-on-dark, --color-on-dark-muted Text, and borders or key caps, on the dark surface and the backdrop
Text --color-fg, --color-fg-muted, --color-fg-subtle Body text and headings, secondary text, placeholders and faint icons
--color-on-accent, --color-on-accent-subtle, --color-on-accent-muted Text and icons on a filled colour; translucent controls on a filled chip
--color-on-warning Text on the warning fill, where --color-on-accent is too light in the light theme
Lines --color-border, --color-border-emphasis Standard and stronger borders
--color-focus-ring Keyboard focus ring
Status --color-{family}, -hover, -subtle, -border Base, hover, tinted background and tinted border of primary, secondary, success, warning and danger
--color-success-fg, --color-warning-fg, --color-danger-fg Text on the family's subtle background or on the page
Map --color-map-* Markers and lines, the same values as the JavaScript constants below, in both themes
Code quality --color-quality-* Lines of the code quality map, and --color-quality-module-1 to -10 for its modules (values)
Documentation --color-docs-shared, --color-docs-shared-subtle Shared ownership in the documentation portal

Primary navy also carries information: there is no separate info family. Secondary grey marks neutral and minor states.

The documentation portal marks engine-owned pages with the success palette and application-owned pages with the primary palette.

The same file defines the shadows: --shadow-xs to --shadow-xl for elevation, --shadow-inset for recessed controls, --shadow-primary for navy-tinted emphasis and --shadow-text for text on a filled colour.

Tints are literal rgba() values in the token file rather than color-mix() expressions, because WeasyPrint renders the token file into the PDF reports and does not support color-mix(). Outside the token file, a color-mix() of tokens is allowed where a page derives a shade.

JavaScript constants

Defined in static/js/shared/constants.js:

Constants Use
AppConstants.COLORS.ATLAS_MATCHED, OSM_MATCHED, GTFS_MATCHED Matched markers
AppConstants.COLORS.ATLAS_UNMATCHED, OSM_UNMATCHED, GTFS_UNMATCHED Unmatched markers; GTFS_UNMATCHED reuses the unmatched grey
AppConstants.COLORS.OSM_DISUSED Stroke and letter of the hollow disused OSM marker
AppConstants.COLORS.LINE_ATLAS_OSM, LINE_OSM_GROUP Map lines
AppConstants.COLORS.LINE_OSM_GROUP_DASH Dash pattern of group lines

Dark theme

The app has a light and a dark theme. The navbar's theme menu offers System, Light and Dark; System, the default, follows the operating system and changes with it. The choice is kept in the browser's local storage under theme.

static/js/shared/theme.js loads in <head> before the stylesheets and sets data-bs-theme on <html>, so a page is painted in its theme from the start. Bootstrap reads the same attribute. When the theme changes, the script fires a themechange event on the document for code that draws its own colours.

The dark theme gives every role in the token file a dark value; outside the token file, only c-leaflet.css refers to a theme, to dim the map tiles and invert the layer control's dark icon. Its rules:

  • Surfaces get lighter as they rise: the page (--color-bg-subtle) is darkest, cards (--color-bg) are lighter and --color-bg-muted lighter still. Borders separate them, since shadows barely show on dark surfaces.
  • Status colours are lighter than in the light theme so that they read on dark surfaces, and text on a filled colour (--color-on-accent) turns dark.
  • Hints and banners over a map (--color-surface-dark, --color-surface-banner) and the backdrop stay dark in both themes, with light text (--color-on-dark, --color-on-banner): over the map tiles, a light banner would stand out less than a dark one.
  • Every text and fill pair meets WCAG AA: at least 4.5:1 for text.
  • The map markers and lines and the code quality colours keep their values; their meaning does not depend on the theme. Map tiles are dimmed. The code quality map, which draws its own light palette on a canvas, keeps the light theme with data-bs-theme="light" on its container: any element can opt out this way.
  • Bootstrap's body, border, link and tertiary variables point at the tokens, so its components, forms and tables follow the theme. Use theme-aware Bootstrap utilities such as bg-body and text-body, not bg-white, text-dark or btn-light.
  • Bootstrap colours a disabled button from its own palette, so buttons.css points each button variant's --bs-btn-disabled-* variables at the tokens: a disabled button keeps its colour, faded.
  • The PDF reports never set the attribute and are always light.

Style rules

Semantic colours

  • Use the tokens. Hex, rgb(), hsl() and named colours appear only in the token file; transparent and currentColor are allowed everywhere.
  • Do not add a fallback to a colour token (var(--color-bg, #fff)): every token is defined, and a fallback is a second, stale copy of its value.
  • Do not introduce a second grey, blue, green, warning or danger palette for an individual page.
  • A genuinely new visual meaning may receive a narrowly named token in tokens.css (the Stylelint configuration does not keep a separate hidden colour allowlist). A one-off shade is mapped to an existing background, foreground, border or status token.

Alpha, shadows and overlays

Opacity creates a new colour value, so it is a token like any other. Each family has one subtle background and one border tint; a translucent surface is either --color-surface-glass (a panel) or --color-surface-veil (a hover or open state), and a dark one is --color-overlay, --color-surface-dark or --color-surface-banner. A component does not pick its own opacity.

Use the --shadow-* tokens for elevation, insets and text shadows.

Borders

Do not use a coloured left border or left accent border. Use a neutral full border, a semantic full border, spacing or a background colour to show grouping and status. Transparent left borders used only for CSS geometry, such as a tooltip arrow, are allowed.

Gradients

A gradient is not acceptable merely because its colours belong to the palette. Use one only for a clear visual purpose, and review it separately from colour-token compliance. Flat semantic surfaces are the default.

Enforcement

Stylelint checks authored CSS:

npm run lint:css

The policy:

  • rejects every colour literal outside static/css/src/01-settings/tokens.css, including those in var() fallbacks and inside color-mix();
  • rejects var(--color-*) references to tokens the token file does not define;
  • rejects coloured or accented left borders while permitting transparent geometry;
  • rejects Bootstrap border-start utility classes in templates;
  • checks empty blocks, duplicate declarations and unknown CSS properties;
  • excludes the import-only static/css/main.css entry point and vendor assets.

Code

File Role
static/css/src/01-settings/tokens.css The colour and shadow tokens of both themes
static/js/shared/constants.js AppConstants.COLORS: the map colours for JavaScript
static/js/shared/theme.js Sets the theme before the stylesheets load and fires themechange
static/css/src/06-components/c-leaflet.css Dims the map tiles and adjusts the layer control in the dark theme
backend/services/docs_stats.py get_canonical_palette_html(): the palette at the top of this page
stylelint.config.mjs The Stylelint policy for authored CSS
scripts/stylelint/no-undocumented-colors.mjs, scripts/stylelint/no-left-accent-border.mjs The rules against colour literals, undefined tokens and left accent borders
scripts/stylelint/check-template-left-borders.mjs Rejects border-start utility classes in templates