From f70f2174ed2cbfc5ae4efc5d9548b768ed147431 Mon Sep 17 00:00:00 2001
From: wbamberg <will@bootbonnet.ca>
Date: Wed, 5 Jun 2024 15:18:39 -0700
Subject: [PATCH] Clarify family-name syntax

---
 files/en-us/web/css/font-family/index.md | 68 ++++++++++++------------
 1 file changed, 35 insertions(+), 33 deletions(-)

diff --git a/files/en-us/web/css/font-family/index.md b/files/en-us/web/css/font-family/index.md
index a00d8c1cbf945e0..2480fb448a6f08d 100644
--- a/files/en-us/web/css/font-family/index.md
+++ b/files/en-us/web/css/font-family/index.md
@@ -60,7 +60,13 @@ font-family: "Gill Sans Extrabold", sans-serif;
 ### Values
 
 - `<family-name>`
-  - : The name of a font family. For example, "Times" and "Helvetica" are font families. Font family names containing whitespace should be quoted. For example: "Comic Sans MS".
+
+  - : The name of a font family. This must be either a single {{cssxref("string")}} value or a space-separated sequence of {{cssxref("custom-ident")}} values. String values must be quoted but may contain any Unicode character. Custom identifiers are not quoted, but certain characters must be escaped.
+
+    It is good practice to quote font family names that contain white space, digits, or punctuation characters other than hyphens.
+
+    See also [Valid family names](#valid_family_names).
+
 - `<generic-name>`
 
   - : Generic font families are a fallback mechanism, a means of preserving some of the style sheet author's intent when none of the specified fonts are available. Generic family names are keywords and must not be quoted. A generic font family should be the last item in the list of font family names. The following keywords are defined:
@@ -112,38 +118,6 @@ font-family: "Gill Sans Extrabold", sans-serif;
     - `fangsong`
       - : A particular style of Chinese characters that are between serif-style Song and cursive-style Kai forms. This style is often used for government documents.
 
-### Valid family names
-
-Font family names must either be given quoted as strings, or unquoted as a sequence of one or more identifiers. This means that punctuation characters and digits at the start of each token must be escaped in unquoted font family names.
-
-It is a **good practice** to quote font family names that contain white space, digits, or punctuation characters other than hyphens.
-
-For example, the following declarations are valid:
-
-```css example-good
-font-family: "Goudy Bookletter 1911", sans-serif;
-```
-
-The following declarations are **invalid**:
-
-```css-nolint example-bad
-font-family: Goudy Bookletter 1911, sans-serif;
-font-family: Red/Black, sans-serif;
-font-family: "Lucida" Grande, sans-serif;
-font-family: Ahem!, sans-serif;
-font-family: test@foo, sans-serif;
-font-family: #POUND, sans-serif;
-font-family: Hawaii 5-0, sans-serif;
-```
-
-The following example is technically **valid** but is not recommended:
-
-```css
-font-family:
-  Gill Sans Extrabold,
-  sans-serif;
-```
-
 ## Formal definition
 
 {{cssinfo}}
@@ -210,6 +184,34 @@ font-family:
 
 {{EmbedLiveSample("Some_common_font_families", 600, 220)}}
 
+### Valid family names
+
+The following declarations are valid:
+
+```css example-good
+font-family: "Goudy Bookletter 1911", sans-serif;
+```
+
+The following declarations are invalid:
+
+```css-nolint example-bad
+font-family: Goudy Bookletter 1911, sans-serif;
+font-family: Red/Black, sans-serif;
+font-family: "Lucida" Grande, sans-serif;
+font-family: Ahem!, sans-serif;
+font-family: test@foo, sans-serif;
+font-family: #POUND, sans-serif;
+font-family: Hawaii 5-0, sans-serif;
+```
+
+The following example is technically valid but is not recommended:
+
+```css
+font-family:
+  Gill Sans Extrabold,
+  sans-serif;
+```
+
 ## Specifications
 
 {{Specifications}}