docs(typography): recommend official font builds in the typography guide (#DS-5791)

apps/docs/src/app/seo-descriptions.ts

@@ -336,8 +336,8 @@ export const DOCS_SEO_DESCRIPTIONS = {
         "ru": "Tree Select позволяет искать и выбирать одно или несколько значений из иерархических данных с сохранением структуры дерева."
     },
     "typography": {
-        "en": "Koobiq typography defines the fonts, weights, and text styles used to create a consistent visual hierarchy in interfaces.",
-        "ru": "Типографика Koobiq определяет шрифты, начертания и текстовые стили для создания единообразной визуальной иерархии в интерфейсах."
+        "en": "Connecting fonts, how the sources differ and how to override the typography styles.",
+        "ru": "Подключение шрифтов, чем отличаются источники и как переопределить стили типографики."
     },
     "username": {
         "en": "The pattern is used when the interface refers to an internal user.",

apps/docs/src/app/structure.ts

@@ -252,7 +252,8 @@ const structure: DocsStructure = makeStructure({
                     },
                     svgPreview: 'typography',
                     hasApi: false,
-                    hasExamples: false
+                    hasExamples: false,
+                    isUpdated: expiresAt('2026-11-10')
                 },
                 {
                     id: DocsStructureItemId.DesignTokens,

apps/docs/src/llms.txt

@@ -19,7 +19,7 @@ Rules for code that uses Koobiq:
 - [Versioning](https://koobiq.io/en/main/versioning.md): Our releases follow the versioning described in the [Semver spec](http://semver.org/).
 - [Theming](https://koobiq.io/en/main/theming.md): A theme in Koobiq is a set of CSS variables.
 - [Localization](https://koobiq.io/en/main/localization.md): Koobiq components render some strings of their own — the filters menu of the filter bar, the tooltips of the code block, the accessible names of every icon-only button, the placeholder of a datepicker, and so on.
-- [Typography](https://koobiq.io/en/main/typography.md): Koobiq typography defines the fonts, weights, and text styles used to create a consistent visual hierarchy in interfaces.
+- [Typography](https://koobiq.io/en/main/typography.md): Where to get the Inter and JetBrains Mono fonts, how the sources differ and how to override the fonts in the interface.
 - [Design tokens](https://koobiq.io/en/main/design-tokens.md): The global CSS custom properties (`--kbq-*`) of the themes: colors, typography, shadows, border radius and sizes.
 - [Schematics](https://koobiq.io/en/main/schematics.md): As part of the **Koobiq** design system, a set of **schematics** is provided — CLI tools designed to automate library installation, perform migrations, and update components in Angular projects.
 - [Upgrade guide](https://koobiq.io/en/main/migration.md): New versions include improvements but also contain **breaking changes**; they must be applied step by step.

packages/components/core/styles/typography/typography.en.mdx

@@ -1,60 +1,73 @@
-Koobiq typography defines the fonts, weights, and text styles used to create a consistent visual hierarchy in interfaces.
+Connecting fonts, how the sources differ and how to override the typography styles.
 
-### Installing Fonts
+### Connecting Fonts
 
-Koobiq uses the [Inter](https://github.com/rsms/inter) and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) font by default.
+Koobiq uses the [Inter](https://github.com/rsms/inter) and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) fonts by default.
 
-| Font           | Weight | Style  |
-| -------------- | ------ | ------ |
-| JetBrains Mono | 400    | Normal |
-| JetBrains Mono | 600    | Normal |
-| JetBrains Mono | 700    | Normal |
-| Inter          | 400    | Normal |
-| Inter          | 400    | Italic |
-| Inter          | 500    | Normal |
-| Inter          | 500    | Italic |
-| Inter          | 600    | Normal |
-| Inter          | 700    | Normal |
+| Font           | Weights                                  |
+| -------------- | ---------------------------------------- |
+| Inter          | 400, 500, 600, 700; italic — 400 and 600 |
+| JetBrains Mono | 400, 600, 700                            |
 
-Add it to your application via [Fontsource](#fontsource), or with the [Google Fonts CDN](#google-fonts-cdn).
+Fonts come from npm packages or are wired up by hand — from files and a CDN link.
 
-#### Fontsource
+#### Packages
 
-Install packages:
+Both fonts are installed from npm packages: [inter-ui](https://www.npmjs.com/package/inter-ui) and [@fontsource/jetbrains-mono](https://www.npmjs.com/package/@fontsource/jetbrains-mono).
 
 ```bash
-npm install @fontsource/inter @fontsource/jetbrains-mono
+npm install inter-ui @fontsource/jetbrains-mono
 ```
 
-Then you add the following code inside your global styles:
+The **inter-ui** package ships `inter.css`, which has the full font feature set — Cyrillic, popular special symbols and the slashed zero. `inter-latin.css` is not used: it has neither Cyrillic nor some of the features.
 
 ```scss
-// Inter
-@import '@fontsource/inter/400.css';
-@import '@fontsource/inter/500.css';
-@import '@fontsource/inter/600.css';
-@import '@fontsource/inter/700.css';
-@import '@fontsource/inter/400-italic.css';
-@import '@fontsource/inter/500-italic.css';
-
-// JetBrains Mono
+@import 'inter-ui/inter.css';
+
 @import '@fontsource/jetbrains-mono/400.css';
 @import '@fontsource/jetbrains-mono/600.css';
 @import '@fontsource/jetbrains-mono/700.css';
 ```
 
-#### Google Fonts CDN
+#### A CDN and self-hosting
+
+Google Fonts does not work for Inter: it serves the font trimmed — without some of the popular symbols and without the features the Koobiq tokens declare, so, for example, the slashed zero does not appear. Inter comes [as files from rsms.me](https://rsms.me/inter/download/), where the archive ships a ready-made stylesheet.
+
+```scss
+@import 'assets/fonts/inter/inter.css';
+```
 
-Add the following code inside your `<head>` tag:
+JetBrains Mono can be linked from Google Fonts:
 
 ```html
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<!-- Inter -->
-<link
-    href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500&display=swap"
-    rel="stylesheet"
-/>
-<!-- JetBrains Mono -->
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet" />
 ```
+
+#### Text styles
+
+A ready-made class uses the separate design token variables: font family, size, line height, letter spacing, weight, text transform and OpenType features. Every class is listed [in the design tokens](/en/main/design-tokens/typography).
+
+The ready-made classes are used in development rather than custom styles assembled from individual variables: the design token variables are there for partial customization. The classes come [with the theme](/en/main/theming/overview), and when it is built from SCSS mixins, `koobiq-typography()` adds them.
+
+```html
+<h2 class="kbq-headline">Heading</h2>
+<p class="kbq-text-normal">Interface text</p>
+```
+
+#### Changing the fonts
+
+The font families are set by global variables, and overriding them changes the fonts across the interface. The override goes after the tokens are connected, otherwise the value from the tokens applies.
+
+```scss
+:root {
+    --kbq-font-family-base: 'MySans', sans-serif;
+    --kbq-font-family-accent: 'MyDisplay', 'MySans', sans-serif;
+    --kbq-font-family-mono: 'MyMono', monospace;
+}
+```
+
+#### Checking the files
+
+A font from any source is checked before installing: it has to contain the characters the interface uses and the OpenType features Koobiq enables. Serving by **unicode-range** — which is what CDNs and the subsets built from them do, Inter in Fontsource for example — drops the features along with the glyphs.

packages/components/core/styles/typography/typography.ru.mdx

@@ -1,60 +1,73 @@
-Типографика Koobiq определяет шрифты, начертания и текстовые стили для создания единообразной визуальной иерархии в интерфейсах.
+Подключение шрифтов, чем отличаются источники и как переопределить стили типографики.
 
-### Добавление шрифтов
+### Подключение шрифтов
 
 Koobiq по умолчанию использует шрифты [Inter](https://github.com/rsms/inter) и [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono).
 
-| Шрифт          | Жирность | Стиль   |
-| -------------- | -------- | ------- |
-| JetBrains Mono | 400      | Обычный |
-| JetBrains Mono | 600      | Обычный |
-| JetBrains Mono | 700      | Обычный |
-| Inter          | 400      | Обычный |
-| Inter          | 400      | Курсив  |
-| Inter          | 500      | Обычный |
-| Inter          | 500      | Курсив  |
-| Inter          | 600      | Обычный |
-| Inter          | 700      | Обычный |
+| Шрифт          | Начертания                             |
+| -------------- | -------------------------------------- |
+| Inter          | 400, 500, 600, 700; курсив — 400 и 600 |
+| JetBrains Mono | 400, 600, 700                          |
 
-Добавьте их в ваше приложение при помощи [Fontsource](#fontsource) или [Google Fonts CDN](#google-fonts-cdn).
+Шрифты подключаются из npm-пакетов или вручную — файлами и ссылкой с CDN.
 
-#### Fontsource
+#### Пакеты
 
-Установите пакеты:
+Оба шрифта устанавливаются из npm-пакетов: [inter-ui](https://www.npmjs.com/package/inter-ui) и [@fontsource/jetbrains-mono](https://www.npmjs.com/package/@fontsource/jetbrains-mono).
 
 ```bash
-npm install @fontsource/inter @fontsource/jetbrains-mono
+npm install inter-ui @fontsource/jetbrains-mono
 ```
 
-Затем добавьте следующий код в ваши глобальные стили:
+Из пакета **inter-ui** подходит `inter.css`: в нем полный набор возможностей шрифта — кириллица, популярные спецсимволы и перечеркнутый ноль. Сборка `inter-latin.css` не используется: в ней нет ни кириллицы, ни части фич.
 
 ```scss
-// Inter
-@import '@fontsource/inter/400.css';
-@import '@fontsource/inter/500.css';
-@import '@fontsource/inter/600.css';
-@import '@fontsource/inter/700.css';
-@import '@fontsource/inter/400-italic.css';
-@import '@fontsource/inter/500-italic.css';
-
-// JetBrains Mono
+@import 'inter-ui/inter.css';
+
 @import '@fontsource/jetbrains-mono/400.css';
 @import '@fontsource/jetbrains-mono/600.css';
 @import '@fontsource/jetbrains-mono/700.css';
 ```
 
-#### Google Fonts CDN
+#### CDN и собственный хостинг
+
+Google Fonts для Inter не подходит: он отдает шрифт обрезанным — без части популярных символов и без фич, объявленных в токенах Koobiq, — например, не отображается перечеркнутый 0. Inter подключается [файлами с rsms.me](https://rsms.me/inter/download/): в архиве готовый файл стилей.
+
+```scss
+@import 'assets/fonts/inter/inter.css';
+```
 
-Добавьте следующий код в тег `<head>`:
+JetBrains Mono можно подключить по ссылке с Google Fonts:
 
 ```html
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<!-- Inter -->
-<link
-    href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500&display=swap"
-    rel="stylesheet"
-/>
-<!-- JetBrains Mono -->
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet" />
 ```
+
+#### Текстовые стили
+
+Готовый класс использует отдельные переменные дизайн-токенов: шрифт, кегль, интерлиньяж, трекинг, вес, регистр и OpenType-фичи. Все классы перечислены [в дизайн-токенах](/ru/main/design-tokens/typography).
+
+В разработке преимущественно используются готовые классы, а не собственные стили из отдельных переменных: переменные дизайн-токенов нужны для частичной кастомизации. Классы приходят [с темой](/ru/main/theming/overview), а при сборке из SCSS-миксинов их добавляет `koobiq-typography()`.
+
+```html
+<h2 class="kbq-headline">Заголовок</h2>
+<p class="kbq-text-normal">Текст интерфейса</p>
+```
+
+#### Изменение шрифтов
+
+Семейства шрифтов заданы глобальными переменными, их переопределение меняет шрифты во всем интерфейсе. Переопределение ставится после подключения токенов, иначе применяется значение из токенов.
+
+```scss
+:root {
+    --kbq-font-family-base: 'MySans', sans-serif;
+    --kbq-font-family-accent: 'MyDisplay', 'MySans', sans-serif;
+    --kbq-font-family-mono: 'MyMono', monospace;
+}
+```
+
+#### Проверка файлов
+
+Перед подключением файл проверяется: в нем должны быть символы, которые использует интерфейс, и OpenType-фичи, которые включает Koobiq. Раздача по **unicode-range** — так работают CDN и собранные из них сабсеты, например Inter в Fontsource, — выбрасывает вместе с глифами и фичи.

tools/cspell-locales/en.json

@@ -63,6 +63,7 @@
         "refreshable",
         "Repobeats",
         "Resizer",
+        "rsms",
         "scrollbars",
         "sidepanel",
         "sidepanels",
@@ -75,6 +76,7 @@
         "unmigrated",
         "unminified",
         "unparseable",
+        "webfonts",
         "xmark",
         "yarnrc"
     ]

tools/cspell-locales/ru.json

@@ -225,6 +225,7 @@
         "рендерится",
         "рендерятся",
         "роутингом",
+        "сабсеты",
         "сайдпанелей",
         "сайдпанели",
         "сайдпанель",
@@ -299,6 +300,7 @@
         "тултипом",
         "тултипы",
         "уплощает",
+        "фичи",
         "форком",
         "форматтер",
         "форматтером",