.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/lib/rules/font-family-name-quotes/README.md

   1 # font-family-name-quotes
   2
   3 Specify whether or not quotation marks should be used around font family names.
   4
   5 ```css
   6 a { font-family: "Times New Roman", 'Ancient Runes', serif; }
   7 /**              ↑               ↑  ↑             ↑
   8  *               These quotation marks and this one */
   9 ```
  10
  11 This rule checks the `font` and `font-family` properties.
  12
  13 This rule ignores `$sass`, `@less`, and `var(--custom-property)` variable syntaxes.
  14
  15 ## Options
  16
  17 `string`: `"always-where-required"|"always-where-recommended"|"always-unless-keyword"`
  18
  19 *Please read the following to understand these options*:
  20
  21 -   The `font` and `font-family` properties accept a short list of special **keywords**: `inherit`, `serif`, `sans-serif`, `cursive`, `fantasy`, and `monospace`. If you wrap these words in quotes, the browser will not interpret them as keywords, but will instead look for a font by that name (e.g. will look for a `"sans-serif"` font) -- which is almost *never* what you want. Instead, you use these keywords to point to the built-in, generic fallbacks (right?). Therefore, *all of the options below enforce no quotes around these keywords*. (If you actually want to use a font named `"sans-serif"`, turn this rule off.)
  22 -   Quotes are **recommended** [in the spec](https://www.w3.org/TR/CSS2/fonts.html#font-family-prop) with "font family names that contain white space, digits, or punctuation characters other than hyphens".
  23 -   Quotes are **required** around font-family names when they are not [valid CSS identifiers](https://www.w3.org/TR/CSS2/syndata.html#value-def-identifier). For example, a font family name requires quotes around it if it contains `$`, `!`, or `/`, but does not require quotes just because it contains spaces or a (non-initial) number or underscore. *You can probably bet that almost every font family name you use **will** be a valid CSS identifier*.
  24 -   Quotes should **never** be used around vendor prefixed system fonts such as `-apple-system` and `BlinkMacSystemFont`.
  25
  26 For more on these subtleties, read ["Unquoted font family names in CSS"](https://mathiasbynens.be/notes/unquoted-font-family), by Mathias Bynens.
  27
  28 **Caveat:** This rule does not currently understand escape sequences such as those described by Mathias. If you want to use the font family name "Hawaii 5-0" you will need to wrap it in quotes, instead of escaping it as `Hawaii \35 -0` or `Hawaii\ 5-0`.
  29
  30 ### `"always-unless-keyword"`
  31
  32 Expect quotes around every font family name that is not a keyword.
  33
  34 The following patterns are considered violations:
  35
  36 ```css
  37 a { font-family: Arial, sans-serif; }
  38 ```
  39
  40 ```css
  41 a { font-family: Times New Roman, Times, serif; }
  42 ```
  43
  44 ```css
  45 a { font: 1em Arial, sans-serif; }
  46 ```
  47
  48 The following patterns are *not* considered violations:
  49
  50 ```css
  51 a { font-family: 'Arial', sans-serif; }
  52 ```
  53
  54 ```css
  55 a { font-family: "Times New Roman", "Times", serif; }
  56 ```
  57
  58 ```css
  59 a { font: 1em 'Arial', sans-serif; }
  60 ```
  61
  62 ### `"always-where-required"`
  63
  64 Expect quotes only when quotes are *required* according to the criteria above, and disallow quotes in all other cases.
  65
  66 The following patterns are considered violations:
  67
  68 ```css
  69 a { font-family: "Arial", sans-serif; }
  70 ```
  71
  72 ```css
  73 a { font-family: 'Times New Roman', Times, serif; }
  74 ```
  75
  76 ```css
  77 a { font: 1em "Arial", sans-serif; }
  78 ```
  79
  80 The following patterns are *not* considered violations:
  81
  82 ```css
  83 a { font-family: Arial, sans-serif; }
  84 ```
  85
  86 ```css
  87 a { font-family: Arial, sans-serif; }
  88 ```
  89
  90 ```css
  91 a { font-family: Times New Roman, Times, serif; }
  92 ```
  93
  94 ```css
  95 a { font-family: "Hawaii 5-0"; }
  96 ```
  97
  98 ```css
  99 a { font: 1em Arial, sans-serif; }
 100 ```
 101
 102 ### `"always-where-recommended"`
 103
 104 Expect quotes only when quotes are *recommended* according to the criteria above, and disallow quotes in all other cases. (This includes all cases where quotes are *required*, as well.)
 105
 106 The following patterns are considered violations:
 107
 108 ```css
 109 a { font-family: Times New Roman, Times, serif; }
 110 ```
 111
 112 ```css
 113 a { font-family: MyFontVersion6, sake_case_font; }
 114 ```
 115
 116 ```css
 117 a { font-family: 'Arial', sans-serif; }
 118 ```
 119
 120 ```css
 121 a { font: 1em Times New Roman, Times, serif; }
 122 ```
 123
 124 The following patterns are *not* considered violations:
 125
 126 ```css
 127 a { font-family: 'Times New Roman', Times, serif; }
 128 ```
 129
 130 ```css
 131 a { font-family: "MyFontVersion6", "sake_case_font"; }
 132 ```
 133
 134 ```css
 135 a { font-family: Arial, sans-serif; }
 136 ```
 137
 138 ```css
 139 a { font: 1em 'Times New Roman', Times, serif; }
 140 ```