Review application A.2.7
Colours and styles
On this page
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
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-mutedlighter 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-bodyandtext-body, notbg-white,text-darkorbtn-light. - Bootstrap colours a disabled button from its own palette, so
buttons.csspoints 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;transparentandcurrentColorare 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 invar()fallbacks and insidecolor-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-startutility classes in templates; - checks empty blocks, duplicate declarations and unknown CSS properties;
- excludes the import-only
static/css/main.cssentry 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 |
Related pages
- A2.1 Map data loading and rendering: the markers and lines these colours draw
- A2.8 Documentation portal: how the documentation diagrams are rendered
- A3.4 Frontend asset management: Bootstrap and the other stylesheets served with the tokens
- A4.2 JavaScript tests: where
npm run lint:cssruns with the other checks