Merge "Add comments to the font-stacks, reference documentation"

variables.less

@@ -3,12 +3,38 @@
 @font-size-root: 100%;
 @font-size-browser: 16; // Assumed browser default of `16px`
 
-@font-family-serif: 'Linux Libertine', 'Georgia', 'Times', serif;
+//
+// == Typography ==
+//
+// Detailed documentation of the font choices:
+// https://www.mediawiki.org/wiki/Wikimedia_User_Interface/Use_cases/Font_family_stack
+// Source of this font stack definition in WikimediaUI Base:
+// https://phabricator.wikimedia.org/source/wikimedia-ui-base/browse/master/wikimedia-ui-base.less$202
+// See T73240 for a related discussion concerning the serif font stack.
+// Note: Numbers in Georgia font are non-lining, the font-feature to change this is documented at:
+// https://www.mediawiki.org/wiki/Talk:Typography_refresh/Archive_2#Numbers_looks_weird_in_article_title
+
+@font-family-serif:
+	'Linux Libertine', // GNU+Linux, alternative to Times New Roman.
+	'Georgia',         // Windows, intended as a serif typeface that would appear elegant but
+	                   // legible printed small or on low-resolution screens.
+	'Times',           // Windows, very similar to Times New Roman with subtle differences.
+	serif;             // Platform default: 'Times New Roman' on Windows.
+
+//
+// Body content uses the user setting in browser / the system default sans-serif font:
+// Arial on Windows, Roboto on Android.
 // FIXME: Use WikimediaUI Base's OS specific default sans-serif fonts.
+
 @font-family-sans: sans-serif;
+
+// Fallback for headings, language: ja,he,ko. See T73240,T65817,T65843,T65844,T65827.
 @font-family-sans--fallback: sans-serif;
 
-// Page content
+//
+// == Page content ==
+//
+
 @background-color-base: #fff;
 @color-base: #222;
 @color-base--emphasized: #000;