Дополняет доки <dfn>, <abbr>, <dl>, <dd>, <dt> (#4709)

* Причёмывает демки `<abbr>` * Дополняет текст `<abbr>` * Причёсывает демки `<dfn>` * Дополняет текст, меняет структуру `<dfn>` * Дополняет текст `<dl>`, `<dd>`, `<dt>` * Исправляет неточность * Меняет высоту демок * Уточняет дополнения про доступность * Принимает правки Co-authored-by: Alena Batitskaia <[email protected]> --------- Co-authored-by: Alena Batitskaia <[email protected]>
doka-guide · Oct 9, 2023 · 93bc183 · 93bc183
1 parent dc3242d
commit 93bc183
Show file tree

Hide file tree

Showing 7 changed files with 242 additions and 89 deletions.
diff --git a/html/abbr/demos/un/index.html b/html/abbr/demos/un/index.html
@@ -1,40 +1,64 @@
 <!DOCTYPE html>
 <html lang="ru">
 <head>
-  <title>ООН — <abbr> — Дока</title>
+  <title>Аббревиатура ООН — <abbr> — Дока</title>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
   <style>
+    *, *::before, *::after {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
     html {
-      height: 100%;
-      margin-top: 0;
-      margin-bottom: 0;
+      color-scheme: dark;
+      font-size: 24px;
     }
 
     body {
-      min-height: 100%;
-      margin-top: 0;
-      margin-bottom: 0;
+      min-height: 100vh;
+      padding: 50px;
       display: flex;
-      justify-content: center;
       align-items: center;
-      background-color: #18191c;
-      color: white;
+      justify-content: center;
+      background-color: #18191C;
+      color: #000000;
       font-family: "Roboto", sans-serif;
-      font-size: 24px;
     }
 
     p {
-      text-align: center;
+      margin: 7px 0;
+      font-size: 1rem;
+      line-height: 1.4;
+    }
+
+    .container {
+      width: 65%;
+      padding: 55px 40px;
+      background-color: #FF8630;
+    }
+
+    @media (max-width: 768px) {
+      body {
+        padding: 30px;
+      }
+
+      .container {
+        width: 100%;
+        padding: 55px 30px;
+      }
     }
   </style>
 </head>
 <body>
-  <p>
-    <abbr title="Организация объединённых наций">ООН</abbr> — международная организация, созданная для поддержания и укрепления международного мира и безопасности, а также развития сотрудничества между государствами
-  </p>
+  <div class="container">
+    <p>
+      <abbr title="Организация объединённых наций">ООН</abbr> — международная организация, созданная для поддержания и укрепления международного мира и безопасности, а также развития сотрудничества между государствами.
+    </p>
+  </div>
 </body>
 </html>
diff --git a/html/abbr/demos/with-dfn/index.html b/html/abbr/demos/with-dfn/index.html
@@ -6,34 +6,61 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
   <style>
-    html, body {
-      height: 100%;
-      margin-top: 0;
-      margin-bottom: 0;
+    *, *::before, *::after {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    html {
+      color-scheme: dark;
+      font-size: 24px;
     }
 
     body {
+      min-height: 100vh;
+      padding: 50px;
       display: flex;
-      justify-content: center;
       align-items: center;
-      background-color: #18191c;
-      color: white;
+      justify-content: center;
+      background-color: #18191C;
+      color: #000000;
       font-family: "Roboto", sans-serif;
     }
 
     p {
-      font-size: 30px;
-      text-align: center;
+      margin: 7px 0;
+      font-size: 1rem;
+      line-height: 1.4;
+    }
+
+    .container {
+      width: 65%;
+      padding: 55px 40px;
+      background-color: #FF8630;
+    }
+
+    @media (max-width: 768px) {
+      body {
+        padding: 30px;
+      }
+
+      .container {
+        width: 100%;
+        padding: 55px 30px;
+      }
     }
   </style>
 </head>
 <body>
-  <p>
-    <dfn>
-      Организация объединённых наций (<abbr title="Организация объединённых наций">ООН</abbr>) — международная организация, созданная для поддержания и укрепления международного мира и безопасности, а также развития сотрудничества между государствами
-    </dfn>
-  </p>
+  <div class="container">
+    <p>
+      <dfn>
+        Организация объединённых наций (<abbr title="Организация объединённых наций">ООН</abbr>) — международная организация, созданная для поддержания и укрепления международного мира и безопасности, а также развития сотрудничества между государствами.
+      </dfn>
+    </p>
+  </div>
 </body>
 </html>
diff --git a/html/abbr/index.md b/html/abbr/index.md
@@ -3,8 +3,11 @@ title: "`<abbr>`"
 description: "Правильный способ расшифровать аббревиатуры."
 authors:
   - xpleesid
+contributors:
+  - tatianafokina
 keywords:
   - акроним
+  - a11y
 related:
   - html/dl-dd-dt
   - html/global-attrs
@@ -19,7 +22,7 @@ tags:
 
 ## Пример
 
-Тегу `<abbr>` можно задать атрибут `title`, где будет раскрыта аббревиатура. В `title` допускается писать только расшифровку аббревиатуры и ничего больше. Также можно использовать [глобальные атрибуты](/html/global-attrs/).
+Тегу `<abbr>` можно задать [атрибут `title`](/html/global-attrs/#title), где будет раскрыта аббревиатура. В `title` допускается писать только расшифровку аббревиатуры и ничего больше. Также можно использовать другие [глобальные атрибуты](/html/global-attrs/).
 
 Некоторые браузеры подчёркивают текст внутри `<abbr>` пунктирной линией, а при наведении выводят всплывающую подсказку, в которой будет содержимое атрибута `title`. Но не все 🤔
 
@@ -29,11 +32,11 @@ tags:
   — международная организация, созданная для
   поддержания и укрепления международного
   мира и безопасности, а также развития
-  сотрудничества между государствами
+  сотрудничества между государствами.
 </p>
 ```
 
-<iframe title="Пример с ЮНЕСКО" src="demos/un/" height="200"></iframe>
+<iframe title="Пример с аббревиатурой ООН" src="demos/un/" height="410"></iframe>
 
 ## Как пишется
 
@@ -46,9 +49,17 @@ tags:
     (<abbr title="Организация объединённых наций">ООН</abbr>)
     — международная  организация, созданная для
     поддержания и укрепления международного мира и безопасности,
-    а также развития сотрудничества между государствами
+    а также развития сотрудничества между государствами.
   </dfn>
 </p>
 ```
 
-<iframe title="Пример с тегом dfn" src="demos/with-dfn/" height="200"></iframe>
+<iframe title="Пример с тегом dfn" src="demos/with-dfn/" height="450"></iframe>
+
+### Доступность
+
+Атрибут `title` для `<abbr>` полезен с точки зрения вёрстки, но абсолютно недоступен для пользователей клавиатуры и мобильных устройств. Подсказка из `title` не всплывает при клавиатурном фокусе и тапе.
+
+Также у `title` есть проблемы с точки зрения взаимодействия пользователей мышек. Не всем понятно, что при наведении на слово с пунктирной линией всплывёт подсказка. К тому же легко забыть стилизовать аббревиатуры так, чтобы они не были похожи на ссылки.
+
+Если очень нужна всплывающая подсказка для аббревиатур, лучше сделать кастомный тултип с [`ролью tooltip`](/a11y/role-tooltip/).
diff --git a/html/dfn/demos/basic/index.html b/html/dfn/demos/basic/index.html
@@ -6,34 +6,59 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
   <style>
+    *, *::before, *::after {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
     html {
-      height: 100%;
+      color-scheme: dark;
+      font-size: 24px;
     }
 
     body {
-      min-height: 100%;
+      min-height: 100vh;
+      padding: 50px;
       display: flex;
-      justify-content: center;
       align-items: center;
-      box-sizing: border-box;
-      margin: 0;
-      padding: 20px;
-      background-color: #18191c;
-      color: white;
+      justify-content: center;
+      background-color: #18191C;
+      color: #000000;
       font-family: "Roboto", sans-serif;
-      font-size: 24px;
     }
 
     p {
-      text-align: center;
+      margin: 7px 0;
+      font-size: 1rem;
+      line-height: 1.4;
+    }
+
+    .container {
+      width: 65%;
+      padding: 55px 40px;
+      background-color: #FF8630;
+    }
+
+    @media (max-width: 768px) {
+      body {
+        padding: 30px;
+      }
+
+      .container {
+        width: 100%;
+        padding: 55px 30px;
+      }
     }
   </style>
 </head>
 <body>
-  <p>
-    <dfn><abbr>ЧАВО</abbr></dfn> — сокращённая форма фразы «Часто задаваемые вопросы». Используется на русскоязычных сайтах в качестве аналога английской аббревиатуры <abbr>FAQ</abbr>
-  </p>
+  <div class="container">
+    <p>
+      <dfn><abbr>ЧАВО</abbr></dfn> — сокращённая форма фразы «Часто задаваемые вопросы». Используется на русскоязычных сайтах в качестве аналога английской аббревиатуры <abbr>FAQ</abbr>.
+    </p>
+  </div>
 </body>
 </html>
diff --git a/html/dfn/demos/link/index.html b/html/dfn/demos/link/index.html
@@ -6,42 +6,81 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
   <style>
+    *, *::before, *::after {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
     html {
-      height: 100%;
+      color-scheme: dark;
+      font-size: 24px;
     }
 
     body {
-      min-height: 100%;
+      min-height: 100vh;
+      padding: 50px;
       display: flex;
-      justify-content: center;
       align-items: center;
-      flex-direction: column;
-      margin: 0;
-      padding: 20px;
-      box-sizing: border-box;
-      background-color: #18191c;
-      color: white;
+      justify-content: center;
+      background-color: #18191C;
+      color: #FFFFFF;
       font-family: "Roboto", sans-serif;
-      font-size: 24px;
     }
 
     p {
-      text-align: center;
+      margin: 7px 0;
+      font-size: 1rem;
+      line-height: 1.4;
     }
 
-    a, a:visited {
-      color: white;
+    .container {
+      width: 65%;
+      padding: 55px 40px;
+    }
+
+    a {
+      border-radius: 3px;
+      color: inherit;
+      -webkit-text-decoration-color: #FF8630;
+      text-decoration-color: #FF8630;
+      text-decoration-thickness: 2px;
+      transition: background-color 0.2s linear;
+    }
+
+    a:hover, a:focus {
+      background-color: #FF8630;
+      transition: background-color 0.2s linear;
+      outline-width: 0;
+    }
+
+    abbr[title] {
+      -webkit-text-decoration-color: #FF8630;
+      text-decoration-color: #FF8630;
+    }
+
+    @media (max-width: 768px) {
+      body {
+        padding: 30px;
+      }
+
+      .container {
+        width: 100%;
+        padding: 55px 30px;
+      }
     }
   </style>
 </head>
 <body>
-  <p>
-    <dfn id="chavo"><abbr title="Часто задаваемые вопросы">ЧАВО</abbr></dfn> — сокращённая форма фразы «Часто задаваемые вопросы».
-  </p>
-  <p>
-    Перед обращением в техподдержку убедитесь, что вы прочитали раздел <a href="#chavo"><abbr title="Часто задаваемые вопросы">ЧАВО</abbr></a> и там нет решения Вашей проблемы.
-  </p>
+  <div class="container">
+    <p>
+      <dfn id="chavo"><abbr title="Часто задаваемые вопросы">ЧАВО</abbr></dfn> — сокращённая форма фразы «Часто задаваемые вопросы».
+    </p>
+    <p>
+      Перед обращением в техподдержку убедитесь, что вы прочитали раздел <a href="#chavo"><abbr title="Часто задаваемые вопросы">ЧАВО</abbr></a> и там нет решения вашей проблемы.
+    </p>
+  </div>
 </body>
 </html>