diff --git a/src/docs/fileStructure/fileStructure.stand.mdx b/src/docs/archive/fileStructure/fileStructure.stand.mdx__ similarity index 100% rename from src/docs/fileStructure/fileStructure.stand.mdx rename to src/docs/archive/fileStructure/fileStructure.stand.mdx__ diff --git a/src/docs/fileStructure/fileStructure.stand.tsx b/src/docs/archive/fileStructure/fileStructure.stand.tsx__ similarity index 100% rename from src/docs/fileStructure/fileStructure.stand.tsx rename to src/docs/archive/fileStructure/fileStructure.stand.tsx__ diff --git a/src/docs/addComponent/addComponent.stand.mdx b/src/docs/contributers/addComponent/addComponent.stand.mdx similarity index 100% rename from src/docs/addComponent/addComponent.stand.mdx rename to src/docs/contributers/addComponent/addComponent.stand.mdx diff --git a/src/docs/addComponent/addComponent.stand.tsx b/src/docs/contributers/addComponent/addComponent.stand.tsx similarity index 100% rename from src/docs/addComponent/addComponent.stand.tsx rename to src/docs/contributers/addComponent/addComponent.stand.tsx diff --git a/src/docs/addComponent/components/addComponentData/AddComponentData.css b/src/docs/contributers/addComponent/components/addComponentData/AddComponentData.css similarity index 100% rename from src/docs/addComponent/components/addComponentData/AddComponentData.css rename to src/docs/contributers/addComponent/components/addComponentData/AddComponentData.css diff --git a/src/docs/addComponent/components/addComponentData/AddComponentData.tsx b/src/docs/contributers/addComponent/components/addComponentData/AddComponentData.tsx similarity index 100% rename from src/docs/addComponent/components/addComponentData/AddComponentData.tsx rename to src/docs/contributers/addComponent/components/addComponentData/AddComponentData.tsx diff --git a/src/docs/addIcons/__stand__/addIcons.design.stand.mdx b/src/docs/contributers/addIcons/__stand__/addIcons.design.stand.mdx similarity index 100% rename from src/docs/addIcons/__stand__/addIcons.design.stand.mdx rename to src/docs/contributers/addIcons/__stand__/addIcons.design.stand.mdx diff --git a/src/docs/addIcons/__stand__/addIcons.dev.stand.mdx b/src/docs/contributers/addIcons/__stand__/addIcons.dev.stand.mdx similarity index 100% rename from src/docs/addIcons/__stand__/addIcons.dev.stand.mdx rename to src/docs/contributers/addIcons/__stand__/addIcons.dev.stand.mdx diff --git a/src/docs/addIcons/__stand__/addIcons.stand.mdx b/src/docs/contributers/addIcons/__stand__/addIcons.stand.mdx similarity index 100% rename from src/docs/addIcons/__stand__/addIcons.stand.mdx rename to src/docs/contributers/addIcons/__stand__/addIcons.stand.mdx diff --git a/src/docs/addIcons/__stand__/addIcons.stand.tsx b/src/docs/contributers/addIcons/__stand__/addIcons.stand.tsx similarity index 100% rename from src/docs/addIcons/__stand__/addIcons.stand.tsx rename to src/docs/contributers/addIcons/__stand__/addIcons.stand.tsx diff --git a/src/docs/addIcons/__stand__/images/10-finder.png b/src/docs/contributers/addIcons/__stand__/images/10-finder.png similarity index 100% rename from src/docs/addIcons/__stand__/images/10-finder.png rename to src/docs/contributers/addIcons/__stand__/images/10-finder.png diff --git a/src/docs/addIcons/__stand__/images/11-github.png b/src/docs/contributers/addIcons/__stand__/images/11-github.png similarity index 100% rename from src/docs/addIcons/__stand__/images/11-github.png rename to src/docs/contributers/addIcons/__stand__/images/11-github.png diff --git a/src/docs/addIcons/__stand__/images/4-figma-union.png b/src/docs/contributers/addIcons/__stand__/images/4-figma-union.png similarity index 100% rename from src/docs/addIcons/__stand__/images/4-figma-union.png rename to src/docs/contributers/addIcons/__stand__/images/4-figma-union.png diff --git a/src/docs/addIcons/__stand__/images/7-figma.png b/src/docs/contributers/addIcons/__stand__/images/7-figma.png similarity index 100% rename from src/docs/addIcons/__stand__/images/7-figma.png rename to src/docs/contributers/addIcons/__stand__/images/7-figma.png diff --git a/src/docs/addIcons/__stand__/images/8-github.png b/src/docs/contributers/addIcons/__stand__/images/8-github.png similarity index 100% rename from src/docs/addIcons/__stand__/images/8-github.png rename to src/docs/contributers/addIcons/__stand__/images/8-github.png diff --git a/src/docs/addIcons/__stand__/images/Export.image.png b/src/docs/contributers/addIcons/__stand__/images/Export.image.png similarity index 100% rename from src/docs/addIcons/__stand__/images/Export.image.png rename to src/docs/contributers/addIcons/__stand__/images/Export.image.png diff --git a/src/docs/addIcons/__stand__/images/Icon1.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon1.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon1.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon1.image.svg diff --git a/src/docs/addIcons/__stand__/images/Icon2.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon2.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon2.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon2.image.svg diff --git a/src/docs/addIcons/__stand__/images/Icon3.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon3.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon3.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon3.image.svg diff --git a/src/docs/addIcons/__stand__/images/Icon5.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon5.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon5.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon5.image.svg diff --git a/src/docs/addIcons/__stand__/images/Icon6.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon6.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon6.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon6.image.svg diff --git a/src/docs/addIcons/__stand__/images/Icon7.image.svg b/src/docs/contributers/addIcons/__stand__/images/Icon7.image.svg similarity index 100% rename from src/docs/addIcons/__stand__/images/Icon7.image.svg rename to src/docs/contributers/addIcons/__stand__/images/Icon7.image.svg diff --git a/src/docs/addIcons/__stand__/images/Image4.image.png b/src/docs/contributers/addIcons/__stand__/images/Image4.image.png similarity index 100% rename from src/docs/addIcons/__stand__/images/Image4.image.png rename to src/docs/contributers/addIcons/__stand__/images/Image4.image.png diff --git a/src/docs/code/code.stand.mdx b/src/docs/contributers/code/code.stand.mdx similarity index 100% rename from src/docs/code/code.stand.mdx rename to src/docs/contributers/code/code.stand.mdx diff --git a/src/docs/code/code.stand.tsx b/src/docs/contributers/code/code.stand.tsx similarity index 100% rename from src/docs/code/code.stand.tsx rename to src/docs/contributers/code/code.stand.tsx diff --git a/src/docs/commits/commits.stand.mdx b/src/docs/contributers/commits/commits.stand.mdx similarity index 100% rename from src/docs/commits/commits.stand.mdx rename to src/docs/contributers/commits/commits.stand.mdx diff --git a/src/docs/commits/commits.stand.tsx b/src/docs/contributers/commits/commits.stand.tsx similarity index 100% rename from src/docs/commits/commits.stand.tsx rename to src/docs/contributers/commits/commits.stand.tsx diff --git a/src/docs/componentGuide/componentGuide.stand.mdx b/src/docs/contributers/componentGuide/componentGuide.stand.mdx similarity index 100% rename from src/docs/componentGuide/componentGuide.stand.mdx rename to src/docs/contributers/componentGuide/componentGuide.stand.mdx diff --git a/src/docs/componentGuide/componentGuide.stand.ts b/src/docs/contributers/componentGuide/componentGuide.stand.ts similarity index 100% rename from src/docs/componentGuide/componentGuide.stand.ts rename to src/docs/contributers/componentGuide/componentGuide.stand.ts diff --git a/src/docs/componentGuide/images/component_guide10.png b/src/docs/contributers/componentGuide/images/component_guide10.png similarity index 100% rename from src/docs/componentGuide/images/component_guide10.png rename to src/docs/contributers/componentGuide/images/component_guide10.png diff --git a/src/docs/componentGuide/images/component_guide11.png b/src/docs/contributers/componentGuide/images/component_guide11.png similarity index 100% rename from src/docs/componentGuide/images/component_guide11.png rename to src/docs/contributers/componentGuide/images/component_guide11.png diff --git a/src/docs/componentGuide/images/component_guide12.png b/src/docs/contributers/componentGuide/images/component_guide12.png similarity index 100% rename from src/docs/componentGuide/images/component_guide12.png rename to src/docs/contributers/componentGuide/images/component_guide12.png diff --git a/src/docs/componentGuide/images/component_guide_1.png b/src/docs/contributers/componentGuide/images/component_guide_1.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_1.png rename to src/docs/contributers/componentGuide/images/component_guide_1.png diff --git a/src/docs/componentGuide/images/component_guide_2.png b/src/docs/contributers/componentGuide/images/component_guide_2.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_2.png rename to src/docs/contributers/componentGuide/images/component_guide_2.png diff --git a/src/docs/componentGuide/images/component_guide_3.png b/src/docs/contributers/componentGuide/images/component_guide_3.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_3.png rename to src/docs/contributers/componentGuide/images/component_guide_3.png diff --git a/src/docs/componentGuide/images/component_guide_4.png b/src/docs/contributers/componentGuide/images/component_guide_4.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_4.png rename to src/docs/contributers/componentGuide/images/component_guide_4.png diff --git a/src/docs/componentGuide/images/component_guide_5.png b/src/docs/contributers/componentGuide/images/component_guide_5.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_5.png rename to src/docs/contributers/componentGuide/images/component_guide_5.png diff --git a/src/docs/componentGuide/images/component_guide_6.png b/src/docs/contributers/componentGuide/images/component_guide_6.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_6.png rename to src/docs/contributers/componentGuide/images/component_guide_6.png diff --git a/src/docs/componentGuide/images/component_guide_7.png b/src/docs/contributers/componentGuide/images/component_guide_7.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_7.png rename to src/docs/contributers/componentGuide/images/component_guide_7.png diff --git a/src/docs/componentGuide/images/component_guide_8.png b/src/docs/contributers/componentGuide/images/component_guide_8.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_8.png rename to src/docs/contributers/componentGuide/images/component_guide_8.png diff --git a/src/docs/componentGuide/images/component_guide_9.png b/src/docs/contributers/componentGuide/images/component_guide_9.png similarity index 100% rename from src/docs/componentGuide/images/component_guide_9.png rename to src/docs/contributers/componentGuide/images/component_guide_9.png diff --git a/src/docs/contribute/__stand__/contribute.design.stand.mdx b/src/docs/contributers/contribute/__stand__/contribute.design.stand.mdx similarity index 100% rename from src/docs/contribute/__stand__/contribute.design.stand.mdx rename to src/docs/contributers/contribute/__stand__/contribute.design.stand.mdx diff --git a/src/docs/contribute/__stand__/contribute.dev.stand.mdx b/src/docs/contributers/contribute/__stand__/contribute.dev.stand.mdx similarity index 100% rename from src/docs/contribute/__stand__/contribute.dev.stand.mdx rename to src/docs/contributers/contribute/__stand__/contribute.dev.stand.mdx diff --git a/src/docs/contribute/__stand__/contribute.stand.mdx b/src/docs/contributers/contribute/__stand__/contribute.stand.mdx similarity index 100% rename from src/docs/contribute/__stand__/contribute.stand.mdx rename to src/docs/contributers/contribute/__stand__/contribute.stand.mdx diff --git a/src/docs/contribute/__stand__/contribute.stand.tsx b/src/docs/contributers/contribute/__stand__/contribute.stand.tsx similarity index 100% rename from src/docs/contribute/__stand__/contribute.stand.tsx rename to src/docs/contributers/contribute/__stand__/contribute.stand.tsx diff --git a/src/docs/issue/issue.stand.mdx b/src/docs/contributers/issue/issue.stand.mdx similarity index 100% rename from src/docs/issue/issue.stand.mdx rename to src/docs/contributers/issue/issue.stand.mdx diff --git a/src/docs/issue/issue.stand.tsx b/src/docs/contributers/issue/issue.stand.tsx similarity index 100% rename from src/docs/issue/issue.stand.tsx rename to src/docs/contributers/issue/issue.stand.tsx diff --git a/src/docs/review/review.stand.mdx b/src/docs/contributers/review/review.stand.mdx similarity index 100% rename from src/docs/review/review.stand.mdx rename to src/docs/contributers/review/review.stand.mdx diff --git a/src/docs/review/review.stand.tsx b/src/docs/contributers/review/review.stand.tsx similarity index 100% rename from src/docs/review/review.stand.tsx rename to src/docs/contributers/review/review.stand.tsx diff --git a/src/docs/docs/docs.stand.mdx b/src/docs/docs/docs.stand.mdx deleted file mode 100644 index 20707e2..0000000 --- a/src/docs/docs/docs.stand.mdx +++ /dev/null @@ -1,260 +0,0 @@ -import { MdxMenu } from '@consta/stand'; - -Этот документ о том, как писать документацию для компонентов. В разделе про [структуру](#структура) есть шаблон: можно скопировать и использовать. - - - -- [Структура](#структура-компонента) -- [Настройки компонента](#настройки-компонента) -- [Вкладки](#вкладки) - - [Обзор](#обзор) - - [Код и свойство](#код-и-свойство) - - [Дизайнерам](#дизайнерам) - - [Песочница](#песочница) - - [Кастомная вкладка](#кастомная-вкладка) -- [Меню на странице](#меню-на-странице) -- [Витрина](#витрина) - - - -## Когда нужна документация - -Почти всегда. Когда вы создаёте новый компонент или вносите важные изменения. Например, добавляете новое свойство: нужно добавить его в таблицу, пояснить, как оно работает и добавить пример. - -## Структура компонента - -Вся информация о компоненте складывается в **папку компонента** — `src/components/ComponentName` - -Например: - -```tsx -src / components / Button; -``` - -[Подробнее о файловой структуре компонента](##LIBS.LIB.STAND/lib:portal/stand:portal-filestructure) - -Устаревшие и новые компоненты складываются в папки с соответствующим названием, например: - -```tsx -src / components / Button; //стабильный компонент -src / components / ButtonDeprecated; //устаревшая версия -src / components / ButtonCanary; //версия в работе -``` - -Документация для компонента складывается в папку `src/components/ComponentName/__stand__`. - -## Настройки компонента - -Настроить компонент можно в конфиге страницы: `src/components/ComponentName/__stand__/ComponentName.stand.tsx` - -```tsx -export default createStand({ - title: 'Avatar', // заголовок страницы - id: 'Avatar', // идентификатор страницы, используется в ссылках - group: 'components', // группа в меню - description: 'Аватар. Разные формы, цвета и размеры.', // краткое описание - version: '1.0.0', // версия библиотеки, в которой появился компонент - status: 'stable', // статус компонента - sandbox: 'avatar-quh7em', // идентификатор песочницы - figma: - 'https://www.figma.com/embed?embed_host=uikit.consta.design&url=https://www.figma.com/file/v9Jkm2GrymD277dIGpRBSH/Consta-UI-Kit?node-id=56%3A30966', - // ссылка на макет компонента в Figma - order: 10, // порядок в группе -}); -``` - -**Версия** — `version` — версия библиотеки, в которой появился этот компонент. Формат: `'x.x.x'`, где `x` — целое число. Версию можно посмотреть по истории коммитов на GitHub, у макета компонента в Figma нужно указать ту же версию. - -**Статус** — статус компонента в процессе разработки. - -Варианты: - -- `stable` — стабильный компонент. -- `deprecated` — устаревшая версия. Будет удалён, когда версия библиотеки поднимется до мажорной. -- `canary` — экспериментальная версия. Её можно использовать, но параметры компонента могут немного поменяться. - -## Вкладки - -Вкладки нужны для навигации по странице. На обычной странице может не быть вкладок. На странице компонента обычно есть хотя бы две вкладки — **Обзор** и **Код и свойство**. - -### Обзор - -Чтобы добавить текст для этой вкладки, в папке с документацией для компонента создайте файл `ComponentName.stand.mdx`. - -Вкладка **Обзор** появляется, если на странице есть ещё хотя бы одна вкладка. Если вкладок больше нет, содержимое обзора выводится на основной странице. - -На этой вкладке обычно размещается краткое описание компонента: что это за компонент, зачем он нужен, в каких случаях используется, какие у него есть аналоги. - -В этой же вкладке отображается [витрина компонента](#витрина). Если её нет, после описания можно добавить визуальный пример. - -### Код и свойство - -Чтобы добавить вкладку **Код и свойство**, в папке с документацией компонента создайте файл `ComponentName.dev.stand.mdx`. - -В этой вкладке — информация для разработки. - -#### Шаблон - -``` - - - [Первый раздел](#раздел-один) - - [Второй раздел](#раздел-два) - - [Третий раздел](#раздел-три) - - [Список свойств](#свойства) - - [Пример использования](#пример) - - -`import {ComponentName} from @consta/lib/ComponentName;` - -## Раздел один - -Описание — код примера — визуальный пример - -## Раздел два - -## Раздел три - -## Свойства - -| Свойство | Тип и значения | По умолчанию | Описание | -| -------- | -------------- | ------------ | -------- | -| [``](#) | `string` | - | | -| [``](#) | `string` | - | | -| [``](#) | `string` | - | | -| [``](#) | `string` | - | | -| `` | `string` | - | | -| `` | `string` | - | | - -## Пример - -``` - -**Примеры** нужны в каждом разделе. Сначала визуальный пример, потом — его код. - -**Код примера** нужно оформить так, чтобы его можно было скопировать и сразу использовать. - -> Примеров много не бывает! Но если их правда много, код для каждого можно не писать, просто понятно указать параметры. - -Если в тексте документации много полноценных примеров, пример в конце можно не добавлять. - -**Текст в примерах:** - -- Пишем на русском языке. -- Не используем специфические нефтяные термины и ситуации. -- Стараемся придумать понятный и простой текст. - -**Таблица со свойствами** - -Нужна во всех компонентах (исключения редки). В документации [графиков](##LIBS.LIB/lib:charts) описываем самые основные свойства и даём ссылку на документацию исходного компонента. - -С названия свойства ставим ссылку на раздел, в котором оно подробно описывается. - -В таблице есть повторяющиеся свойства. Их описания стараемся сделать одинаковыми (в планах — сделать единый источник для таких описаний). - -### Дизайнерам - -В этой вкладке подгружается макет компонента из Figma. - -Чтобы добавить эту вкладку, укажите ссылку на файл (или фрейм с компонентом) в Figma в настройках страницы `src/components/ComponentName/__stand__/ComponentName.stand.tsx`, в параметре `figma`. - -[Посмотреть пример](#настройки-компонента) - -### Песочница - -Примеры для песочницы собираем в сервисе Sandbox (для этого есть аккаунт). - -Чтобы добавить эту вкладку, укажите идентификатор примера из Sandbox в настройках страницы: `src/components/ComponentName/__stand__/ComponentName.stand.tsx`, в параметре `sandbox`. - -[Посмотреть пример](#настройки-компонента) - -### Кастомная вкладка - -В любую библиотеку можно добавить новую вкладку. - -Как это сделать: - -1. Перенесите конфиг из `node_modules/@consta/stand/scripts/config.js` в папку проекта в `scripts/config.js`. -2. В конфиге добавьте идентификаторы всех вкладок в массив `standTabs`. - -Например, так: - -```json -standTabs: ['dev', 'design', 'use'], -``` - -> Вкладки `dev` и `design` используются по умолчанию. - -Новую вкладку лучше называть одним словом. - -3. В `package.json` указажите конфиг для `stand:generate`: - -```json -"stand:generate": "node node_modules/@consta/stand/scripts/standGenerate.js --config=scripts/config.js", -``` - -4. Опишите настройки для вкладок в `src/stand/standConfig.ts` : - -```tsx -export const { createStand } = createConfig({ -../../.. -standTabs: [ - // табы поумолчанию - { id: '', label: 'Обзор' }, - { id: 'dev', label: 'Разработчикам' }, - { id: 'design', label: 'Дизайнерам', figma: true }, - { id: 'sandbox', label: 'Песочница', sandbox: true }, - // свои табы - { id: 'use', label: 'Как использовать' }, - ], -../../.. -}); -``` - -Чтобы изменить порядок отображения вкладок на странице, измените их порядок в массиве `standTabs`. - -После этого, в папке компонента, нужно создать файл с названием вкладки. Например, чтобы добавить вкладку с идентификатором `use` для компонента `Attachment`, в папке с этим компонентом создайте файл `Attachment.use.stand.mdx`. В него можно добавить содержимое для этой вкладки. - -## Меню на странице - -Чтобы добавить меню для навигации по вкладке, импортируйте компонент `MdxMenu` и добавьте пункты со ссылками на заголовки. - -Например, меню на этой странице добавляется так: - -``` -import { MdxMenu } from '@consta/stand'; - - - - - [Структура](#структура-компонента) - - [Настройки - компонента](#настройки-компонента) - - [Вкладки](#вкладки) - - [Обзор](#обзор) - - [Код и свойство](#код-и-свойство) - - [Дизайнерам](#дизайнерам) - - [Песочница](#песочница) - - [Кастомная вкладка](#кастомная-вкладка) - - [Меню на - странице](#меню-на-странице) - - [Витрина](#витрина) - -; -``` - -**Примечания:** - -- После тега `` и перед `` обязательно оставьте пустую строку. -- Ссылка формируется из заголовка автоматически, все пробелы и спецсимволы заменяются на дефис `-`, все заглавные пункты становятся строчными. -- Текст ссылки в меню может быть любым (и не совпадать с текстом заголовка). -- На любой заголовок на странице можно [поставить ссылку](##LIBS) с любой другой страницы. - -## Витрина - -Витрина добавляется на главную страницу компонента, в **Обзор**, сразу после вкладок. На ней можно менять свойства компонента и смотреть, что с ним происходит. - -Чтобы добавить витрину, в папке с документацией для компонента создайте файл `ComponentName.variants.tsx`. - -В этом файле опишите параметры, которые хотите вывести на витрину, и вызовите компонент с этими параметрами. - -- [Посмотреть параметры для витрины](https://github.com/consta-design-system/stand/blob/main/src/exportAtoms/variants/variants.ts) -- [Посмотреть пример витрины](https://github.com/consta-design-system/uikit/blob/dev/src/components/Attachment/__stand__/Attachment.variants.tsx) diff --git a/src/docs/docsPortal/docsPortal.stand.mdx b/src/docs/docsPortal/docsPortal.stand.mdx deleted file mode 100644 index 9f60f40..0000000 --- a/src/docs/docsPortal/docsPortal.stand.mdx +++ /dev/null @@ -1,176 +0,0 @@ -import { MdxMenu } from '@consta/stand'; - -Документация дизайн-системы работает на кастомном движке, который разработала и поддерживает команда Consta. - -Портал с документацией объединяет все библиотеки Consta. Библиотеки находятся в разных репозиториях, в каждом репозитории — своя документация. Портал автоматически собирает страницу со списком библиотек и показывает все библиотеки на одном сайте — на одном домене и под общей шапкой. - -##### Преимущества движка - -- Сборка документации из разных репозиториев в один веб-документ, с общей навигацией и оформлением. -- Кастомная витрина для демонстрации компонентов, с разными вариантами представления и просмотра (десктоп, планшет, телефон). -- Песочница Sandbox. -- Статусы компонентов (можно добавить любые). -- Поиск по компонентам с фильтрами для статусов (`Deprecated`, `Canary`), адаптированный к нашим процессам разработки. -- Кастомные вкладки в статьях. - - - -- [Портал](#портал) - - [Список библиотек](#список-библиотек) - - [Левое меню](#левое-меню) -- [Библиотеки](#библиотеки) - - - -## Портал - -- [Адрес портала](##HOME) -- [Репозиторий](https://github.com/consta-design-system/portal) - -Портал — это рамка для всех библиотек. - -Что есть на портале: - -- Левое меню -- [Главная страница](/) — со списком разделов и библиотек -- [Статьи и гайды](##LIBS.LIB.STAND/lib:portal/stand:startwork-faq) по дизайн-системе - -### Список библиотек - -Список библиотек собирается из всех репозиториев дизайн-системы на [главной странице](##LIBS) портала. - -Библиотеки нужно добавлять в список вручную. Контент для конкретной библиотеки обновляется в самой библиотеке. - -#### Как обновить список библиотек - -##### Шаг 1. Обновите конфиг стенда в библиотеке - -В репозитории библиотеки, которую нужно обновить или добавить на страницу, заполните конфигурационный файл стенда `stand/standConfig.ts` и выложите в продакшен в основную ветку (обычно это `master`). - -##### Шаг 2. Добавьте репозиторий библиотеки - -Добавьте репозиторий и ветку, из которой нужно взять данные для библиотеки, в список [clone-repositories.sh](https://github.com/consta-design-system/portal/blob/master/clone-repositories.sh) - -Например, так: - -```tsx -git clone -b master https://${REPO_ACCESS_TOKEN}@github.com/consta-design-system/uikit.git ./repositories/uikit` -``` - -##### Шаг 3. Добавьте алиас библиотеки - -Добавьте алиас библиотеки в [webpack.config.js](https://github.com/consta-design-system/portal/blob/master/webpack.config.js) в объект `repos`: - -```tsx -const repos = [ - 'analytic-ui', - 'uikit', - 'charts', - 'header', - 'stats', - 'react-big-calendar-adapter', - 'gantt-task-react-adapter', - 'rc-tree-adapter', - 'rc-table-adapter', - 'ag-grid-adapter', - 'widgets', - 'amcharts-map-examples', - 'gpn-responses', - 'icons', -]; -``` - -Это нужно для работы абсолютных путей через `##`. - -Например, конструкция `##/utils/bem` в репозитории `@consta/uikit` обрабатывается как `/repositories/uikit/utils/bem`, а в `@consta/header` — как `/repositories/header/utils/bem`. - -##### Шаг 4. Соберите портал - -``` -# клонируйте репозитории -yarn clone-repos - -# копируйте зависимости репозиториев в проект (если нужно) -yarn copy-deps - -# установите зависимости -yarn install - -# запустите стенд -yarn start -``` - -### Левое меню - -Левое меню собирается автоматически из всех статей в проекте. - -Чтобы добавить статью в левое меню, нужно: - -##### Шаг 1. Добавить новую группу статей - -Добавьте группу для статьи в настройки библиотеки `src/stand/standConfig.ts` в объект `groups`. - -Например, так: - -```tsx -groups: [ - { - title: 'О дизайн-системе', - id: 'about', - }, -]; -``` - -##### Шаг 2. Указать, что статья относится к этой группе - -В настройках статьи (`src/<Название статьи>/<Название статьи>.stand.mdx`), в параметре `group` укажите идентификатор этой группы: - -```tsx -export default createStand({ - title: 'О дизайн-системе', //заголовок страницы - id: 'aboutConsta', //идентификатор, отображается в url - group: 'about', //группа в меню - order: 10, //порядок в группе - visibleOnHeader: true, //показывать в верхнем меню -}); -``` - -## Библиотеки - -Все библиотеки устроены одинаково: внутри есть статьи, у каждой статьи есть свои настройки, статьи собираются на странице **Обзор** (`<адрес портала>` + `libs`). [Посмотреть список библиотек](/) - -Левое меню собирается и настраивается так же, [как на портале](#левое-меню). - -### Настройки библиотеки - -Конфигурационный файл библиотеки: `src/stand/standConfig.ts`. - -```tsx -import { createConfig } from '@consta/stand'; - -import image from './ConstaImage.png'; -import description from './description.mdx'; -import { StandPageDecoration as standPageDecoration } from './standPageDecoration'; - -export const { createStand } = createConfig({ - title: 'Consta UI Kit', - id: 'uikit', - groups: [ - { - title: 'Документация', - id: 'about', - }, - { - title: 'Компоненты', - id: 'components', - view: 'card', - }, - ], - group: 'Библиотеки', // группа в списке библиотек на портале - image, // изображение на главной странице библиотеки - description, // описание на главной странице библиотеки - standPageDecoration, // темы - repositoryUrl: 'https://github.com/consta-design-system/uikit', // репозиторий библиотеки на GitHub - order: 1, // порядок в группе на портале -}); -``` diff --git a/src/docs/docsStyle/docsStyle.stand.mdx b/src/docs/guidelines/docsStyle/docsStyle.stand.mdx similarity index 100% rename from src/docs/docsStyle/docsStyle.stand.mdx rename to src/docs/guidelines/docsStyle/docsStyle.stand.mdx diff --git a/src/docs/docsStyle/docsStyle.stand.tsx b/src/docs/guidelines/docsStyle/docsStyle.stand.tsx similarity index 100% rename from src/docs/docsStyle/docsStyle.stand.tsx rename to src/docs/guidelines/docsStyle/docsStyle.stand.tsx diff --git a/src/docs/docsStyle/examples/DocsStyleExampleName/DocsStyleExampleName.tsx b/src/docs/guidelines/docsStyle/examples/DocsStyleExampleName/DocsStyleExampleName.tsx similarity index 100% rename from src/docs/docsStyle/examples/DocsStyleExampleName/DocsStyleExampleName.tsx rename to src/docs/guidelines/docsStyle/examples/DocsStyleExampleName/DocsStyleExampleName.tsx diff --git a/src/docs/fontInter/__stand__/components/images/font-replace-pic-1.png b/src/docs/guidelines/fontInter/__stand__/components/images/font-replace-pic-1.png similarity index 100% rename from src/docs/fontInter/__stand__/components/images/font-replace-pic-1.png rename to src/docs/guidelines/fontInter/__stand__/components/images/font-replace-pic-1.png diff --git a/src/docs/fontInter/__stand__/components/newFontPictures.tsx b/src/docs/guidelines/fontInter/__stand__/components/newFontPictures.tsx similarity index 100% rename from src/docs/fontInter/__stand__/components/newFontPictures.tsx rename to src/docs/guidelines/fontInter/__stand__/components/newFontPictures.tsx diff --git a/src/docs/fontInter/__stand__/fontInter.design.stand.mdx b/src/docs/guidelines/fontInter/__stand__/fontInter.design.stand.mdx similarity index 100% rename from src/docs/fontInter/__stand__/fontInter.design.stand.mdx rename to src/docs/guidelines/fontInter/__stand__/fontInter.design.stand.mdx diff --git a/src/docs/fontInter/__stand__/fontInter.dev.stand.mdx b/src/docs/guidelines/fontInter/__stand__/fontInter.dev.stand.mdx similarity index 100% rename from src/docs/fontInter/__stand__/fontInter.dev.stand.mdx rename to src/docs/guidelines/fontInter/__stand__/fontInter.dev.stand.mdx diff --git a/src/docs/fontInter/__stand__/fontInter.stand.mdx b/src/docs/guidelines/fontInter/__stand__/fontInter.stand.mdx similarity index 100% rename from src/docs/fontInter/__stand__/fontInter.stand.mdx rename to src/docs/guidelines/fontInter/__stand__/fontInter.stand.mdx diff --git a/src/docs/fontInter/__stand__/fontInter.stand.tsx b/src/docs/guidelines/fontInter/__stand__/fontInter.stand.tsx similarity index 100% rename from src/docs/fontInter/__stand__/fontInter.stand.tsx rename to src/docs/guidelines/fontInter/__stand__/fontInter.stand.tsx diff --git a/src/docs/prototype/prototype.stand.mdx b/src/docs/guidelines/prototype/prototype.stand.mdx similarity index 100% rename from src/docs/prototype/prototype.stand.mdx rename to src/docs/guidelines/prototype/prototype.stand.mdx diff --git a/src/docs/prototype/prototype.stand.tsx b/src/docs/guidelines/prototype/prototype.stand.tsx similarity index 100% rename from src/docs/prototype/prototype.stand.tsx rename to src/docs/guidelines/prototype/prototype.stand.tsx diff --git a/src/docs/tableComparison/tableComparison.stand.mdx b/src/docs/guidelines/tableComparison/tableComparison.stand.mdx similarity index 100% rename from src/docs/tableComparison/tableComparison.stand.mdx rename to src/docs/guidelines/tableComparison/tableComparison.stand.mdx diff --git a/src/docs/tableComparison/tableComparison.stand.tsx b/src/docs/guidelines/tableComparison/tableComparison.stand.tsx similarity index 100% rename from src/docs/tableComparison/tableComparison.stand.tsx rename to src/docs/guidelines/tableComparison/tableComparison.stand.tsx diff --git a/src/docs/units/units.stand.mdx b/src/docs/guidelines/units/units.stand.mdx similarity index 100% rename from src/docs/units/units.stand.mdx rename to src/docs/guidelines/units/units.stand.mdx diff --git a/src/docs/units/units.stand.tsx b/src/docs/guidelines/units/units.stand.tsx similarity index 100% rename from src/docs/units/units.stand.tsx rename to src/docs/guidelines/units/units.stand.tsx diff --git a/src/docs/workflow/workflow.stand.mdx b/src/docs/guidelines/workflow/workflow.stand.mdx similarity index 100% rename from src/docs/workflow/workflow.stand.mdx rename to src/docs/guidelines/workflow/workflow.stand.mdx diff --git a/src/docs/workflow/workflow.stand.tsx b/src/docs/guidelines/workflow/workflow.stand.tsx similarity index 100% rename from src/docs/workflow/workflow.stand.tsx rename to src/docs/guidelines/workflow/workflow.stand.tsx diff --git a/src/docs/howToGo/howToGo.stand.mdx b/src/docs/howToGo/howToGo.stand.mdx deleted file mode 100644 index a3dcd1a..0000000 --- a/src/docs/howToGo/howToGo.stand.mdx +++ /dev/null @@ -1,64 +0,0 @@ -## Подключите библиотеки - -[Быстрый старт](##LIBS.LIB.STAND/lib:portal/stand:startwork-start) - -## Посмотрите, каких компонентов вам не хватает - -В дизайн-системе есть самые основные компоненты для разработки интерфейсов. Скорее всего, вам понадобится несколько уникальных компонентов или доработок. Должно быть примерно так: - -- 80% — компоненты из дизайн-системы, -- 20% — новые компоненты и доработки. - -Посмотрите заранее, что уже есть, а что вам может понадобиться. - -**Где смотреть:** - -### Библиотека компонентов - -- [Репозиторий](https://github.com/consta-design-system/uikit) -- [Песочница и документация](##LIBS.LIB/lib:uikit) - -### Библиотека графиков - -- [Репозиторий](https://github.com/consta-design-system/charts) -- [Песочница и документация](##LIBS.LIB/lib:charts) - -Если что-то не нашлось, проверьте, может быть, задача на доработки, которые нужны вам, уже запланирована или в работе. - -### Заявки на доработки (issues) - -- [Список](https://github.com/consta-design-system/uikit/issues) -- [Доска](https://github.com/consta-design-system/uikit/projects/1) - -### Задачи в работе (PR) - -- [PR](https://github.com/consta-design-system/uikit/pulls) - -Если нужных компонентов нигде нет, что ж. Некоторые компоненты мы берём в работу, но что-то вам придётся добавить самостоятельно. - -## Отправьте запрос на доработку дизайн-системы - -### Когда стоит это делать - -- Вы нашли ошибку в работе наших компонентов. -- Ваша доработка или улучшение компонента будет полезна многим. -- Новый компонент часто используется в проектировании интерфейсов (во всех дизайн-системах есть, а у нас нет). - -### Как отправить запрос на доработку - -1. Создайте [issue](https://github.com/consta-design-system/uikit/issues/new). -2. Подробно опишите, какие возможности нужно добавить и какие задачи они будут решать. - -Если хотите самостоятельно добавить новый компонент, напишите, как вы собираетесь его реализовывать, в общих чертах (какой API будет у компонента, спорные технические моменты и т. д.). - -3. Дождитесь ответа от команды Consta. - -> Лучше сделать отдельный issue для каждой доработки - -## Для контрибьюторов: отправьте доработки - -Это для тех, кто договорился с командой дизайн-системы, что будет самостоятельно делать доработку. - -Отправьте PR в ветку dev в [нашем репозитории](https://github.com/consta-design-system/uikit). - -Подробности об оформлении PR и совместной работе над дизайн-системой — в [инструкции для контрибьюторов](##LIBS.LIB.STAND/lib:portal/stand:contributers-owerview). diff --git a/src/docs/howToGo/howToGo.stand.tsx__ b/src/docs/howToGo/howToGo.stand.tsx__ deleted file mode 100644 index 3a3ece7..0000000 --- a/src/docs/howToGo/howToGo.stand.tsx__ +++ /dev/null @@ -1,8 +0,0 @@ -import { createStand } from '##/stand/standConfig'; - -export default createStand({ - title: 'Как перейти на Consta', - id: 'howToGo', - group: 'workflow', - order: 12, -}); diff --git a/src/docs/portal/formattingRules/examples/FormattingRulesExampleName/FormattingRulesExampleName.tsx b/src/docs/portal/formattingRules/examples/FormattingRulesExampleName/FormattingRulesExampleName.tsx new file mode 100644 index 0000000..8675403 --- /dev/null +++ b/src/docs/portal/formattingRules/examples/FormattingRulesExampleName/FormattingRulesExampleName.tsx @@ -0,0 +1,25 @@ +import { Example } from '@consta/stand'; +import React from 'react'; + +export const TextExampleName = () => { + return ( + + ); +}; diff --git a/src/docs/portal/formattingRules/formattingRules.stand.mdx b/src/docs/portal/formattingRules/formattingRules.stand.mdx new file mode 100644 index 0000000..67024a2 --- /dev/null +++ b/src/docs/portal/formattingRules/formattingRules.stand.mdx @@ -0,0 +1,758 @@ +import { MdxTabs } from '@consta/stand'; +import { MdxMenu } from '@consta/stand'; +import { MdxImage } from '@consta/stand'; +import { MdxCollapse } from '@consta/stand'; +import { MdxInformer } from '@consta/stand'; +import example from './images/example.png'; +import { TextExampleName } from './examples/FormattingRulesExampleName/FormattingRulesExampleName.tsx'; + + + +- [Заголовки](#заголовки) +- [Выделение текста](#выделение-текста) + - [Жирный шрифт](#жирный-шрифт) + - [Моноширинный шрифт](#моноширинный-текст) + - [Кавычки](#кавычки) +- [Списки](#списки) + - [Нумерованные](#нумерованные) + - [Маркированные](#маркированные) + - [Вложенные](#вложенные) +- [Ссылки](#ссылки) + - [Внутренние](#внутренние) + - [Внешние](#внешние) +- [Таблицы](#таблицы) +- [Блоки кода](#блоки-кода) +- [Изображения](#изображения) +- [Заметка](#заметка) +- [Раскрывающиеся блоки](#раскрывающиеся-блоки) +- [Пример компонента](#пример-компонента) +- [Табы](#табы) + - [Код и пример компонента](#код-и-пример-компонента) + - [Остальные случаи](#остальные-случаи) +- [Меню](#меню) +- [Стрелочка](#стрелочка) + + + +В этом разделе только инструкция по форматированию текста. Правила, которые отвечают за стиль написания, читай в разделе [Стилизация контента](https://www.notion.so/114c4fa839ec80bca000ddc79269bbf3?pvs=21). + +## Заголовки + +Используйте заголовки для разделения текста на логические блоки. Количество символов `#` определяет уровень заголовка. Например: + + +<> + +```markdown +# Заголовок 1 уровня + +## Заголовок 2 уровня + +### Заголовок 3 уровня +``` + + + +<> + +# Заголовок 1 уровня + +## Заголовок 2 уровня + +### Заголовок 3 уровня + + + + +В Consta заголовок первого уровня задается в файле .tsx. Чтобы разделить основные темы внутри раздела, используйте заголовок второго уровня. Подробнее о структуре файлов читай на странице. + + + Рекомендуем не использовать заголовки ниже третьего уровня. Если нужно больше, + имеет смысл декомпозировать саму страницу. + + +## Выделение текста + +Чтобы изменить начертание текста, выделите его с двух сторон спецсимволами следующим образом: `<спецсимвол>текст<спецсимвол>`. + +### Жирный шрифт + +Чтобы использовать жирный шрифт, поставьте две звездочки с каждой стороны от выделенного текста. Старайтесь не выделять текст жирным, если только совсем не нужно сакцентировать внимание на чем-либо. + +Используйте жирный шрифт для выделения в тексте: + +- названий интерфейсных элементов, +- сообщения об ошибке или текста, который пользователь видит на экране. + +Пример: + + +<> + +```markdown +В поле **Имя пользователя** введите ваш логин. +``` + + + +<> + +В поле **Имя пользователя** введите ваш логин. + + + + +### Моноширинный шрифт + +Чтобы использовать моноширинный шрифт, окружите его символом `` ` `` с каждой стороны. Используйте моноширинный шрифт для выделения в тексте: + +- названий компонентов, +- названий свойств, +- имен переменных в тексте. + +Пример: + + +<> + +```markdown +Чтобы настроить иконку файла, задайте расширение в свойстве `fileExtensions`. +``` + + + +<> + +Чтобы настроить иконку файла, задайте расширение в свойстве `fileExtensions`. + + + + +### Кавычки + +Используйте кавычки только для цитирования или выделения символа или термина. Основной тип кавычек «елочки». В качестве альтернативы кавычкам используйте [жирный](#жирный-шрифт) или [моноширинный шрифт](#моноширинный-шрифт). + +## Списки + +В синтаксисе Markdown есть несколько видов списков. Для их оформления перед каждым пунктом нужно поставить подходящий тег и отделить его от текста пробелом. + +### Нумерованные + +Для создания нумерованного списка перед пунктами нужно поставить число с точкой. При этом нумерация в разметке ленивая. Неважно, какие именно числа вы напишете: Markdown пронумерует список автоматически. Пример: + + +<> + +```markdown +1. Элемент 1 +2. Элемент 2 +3. Элемент 3 +``` + + + +<> + +1. Элемент 1 +2. Элемент 2 +3. Элемент 3 + + + + +### Маркированные + +Для создания маркированного списка нужно поставить перед каждым пунктом звёздочку `*`, дефис `-` или плюс `+`. Мы используем дефис. Пример: + + +<> + +```markdown +- Элемент 1 +- Элемент 2 +- Элемент 3 +``` + + + +<> + +- Элемент 1 +- Элемент 2 +- Элемент 3 + + + + +### Вложенные + +Чтобы создать вложенный список, нужно поставить перед его пунктами табуляцию или несколько пробелов. В Markdown одна табуляция соответствует четырём пробелам. + +Список одного вида можно вкладывать в любой другой. + +Пример: + + +<> + +```markdown +- Утром + 1. Пресс качать + 2. Бегать + 3. Отжиматься +- Вечером + 1. Отдыхать + 2. Спать +``` + + + +<> + +- Утром + 1. Пресс качать + 2. Бегать + 3. Отжиматься +- Вечером + 1. Отдыхать + 2. Спать + + + + + + Избегайте излишнего использования вложенных списков. + + +## Ссылки + +### Внутренние + +Внутренние ссылки оформляются так: + +```markdown +[текст_ссылки](##LIBS.LIB.STAND.TAB/lib:<библиотека>/stand:<раздел>/tab:<страница>/hash:<подзаголовок>) +``` + +Пример: + + +<> + +```markdown +Импортируйте в корневой файл [пресет](##LIBS.LIB.STAND.TAB/lib:uikit/stand:components-theme-stable/tab:dev/hash:пресеты). +``` + + + +<> + +Импортируйте в корневой файл [пресет](##LIBS.LIB.STAND.TAB/lib:uikit/stand:components-theme-stable/tab:dev/hash:пресеты). + + + + +Подробнее об устройстве портала Consta читайте в разделе Организация папок и файлов. + +### Внешние + +Используйте ссылки для перехода на внешние ресурсы. Для создания ссылки используйте квадратные скобки `[]` для текста ссылки и круглые скобки `()` для URL-адреса. Пример: + + +<> + +```markdown +Полный список репозиториев смотрите [на нашей странице в GitHub](https://github.com/consta-design-system). +``` + + + +<> + +Полный список репозиториев смотрите [на нашей странице в GitHub](https://github.com/consta-design-system). + + + + +## Таблицы + +Используйте таблицы для представления данных в виде таблицы. Для создания таблицы используйте символ `|`. Пример: + + +<> + +```markdown +| Заголовок 1 | Заголовок 2 | +| ----------- | ----------- | +| Ячейка 1.1 | Ячейка 1.2 | +| Ячейка 2.1 | Ячейка 2.2 | +``` + + + +<> + +| Заголовок 1 | Заголовок 2 | +| ----------- | ----------- | +| Ячейка 1.1 | Ячейка 1.2 | +| Ячейка 2.1 | Ячейка 2.2 | + + + + +## Блоки кода + +Используйте код для выделения фрагментов кода или команд. Для выделения кода используйте символ ``` (обратный апостроф). Пример: + + +<> + +````markdown +```tsx + console.log('onClick')} +/> +``` +```` + + + +<> + +```tsx + console.log('onClick')} +/> +``` + + + + +## Изображения + +Чтобы использовать изображение в тексте: + +1. Импортируйте компонент изображения в нужный файл: + +```jsx +import { MdxImage } from '@consta/stand'; //код для импорта изображений +``` + +2. Оформите изображения его по [правилам](https://www.notion.so/10cc4fa839ec8018abcadde94014b3c4?pvs=21). +3. Импортируйте изображение: + +```jsx +import example from './images/example.jpg'; //импорт самого изображения +``` + +4. Вставьте его после текстового описания: + + +<> + +```markdown + +``` + + + +<> + + + + + + +## Заметка + +Заметка — это выделяющийся блок с важной информацией. + +Чтобы использовать заметку: + +1. Импортируйте компонент заметки: + +```jsx +import { MdxInformer } from '@consta/stand'; +``` + +2. Вставьте заметку в контент: + +```markdown + + При переключении основной темы вложенная тема не поменяется. + +``` + +В зависимости от содержания используют заметки с различными заголовками и оформлением. Всего 4 типа заметок: + +- **Совет** – рекомендация. + + +<> + +```markdown + + Если на проекте нет дизайнера, используйте дизайн-систему как брендбук. Размеры, цвета и другие параметры можно взять из библиотек Consta в Figma. + +``` + + + +<> + + + Если на проекте нет дизайнера, используйте дизайн-систему как брендбук. + Размеры, цвета и другие параметры можно взять из библиотек Consta в Figma. + + + + + +- **Примечание** – дополнительная информация. Тип по умолчанию. + + +<> + +```markdown + + При переключении основной темы вложенная тема не поменяется. + +``` + + + +<> + + + При переключении основной темы вложенная тема не поменяется. + +/> + + + + +- **Предупреждение** – предостережение. + + +<> + +```markdown + + Мы не поддерживаем Internet Explorer и старую версию Edge. + +``` + + + +<> + + + Мы не поддерживаем Internet Explorer и старую версию Edge. + + + + + +- **Внимание** – ограничение. + + +<> + +```markdown + + Назначить нового автора страницы может ее действующий автор или администратор организации. + +``` + + + +<> + + + Назначить нового автора страницы может ее действующий автор или администратор + организации. + + + + + +## Раскрывающиеся блоки + +Раскрывающийся блок, коллапс – это специальный блок на странице, который позволяет в любой момент развернуть информацию и свернуть её обратно. + +Чтобы использовать коллапс: + +1. Импортируйте компонент коллапса в нужный документ: + +```jsx +import { MdxCollapse } from '@consta/stand'; +``` + +2. Вставьте раскрывающийся блок в необходимое место контента: + + +<> + +```markdown + + +Ни малейшего понятия + + +``` + + + +<> + + + +Ни малейшего понятия + + + + + + +## Пример компонента + +Все примеры компонентов лежат в папке `examples` в папке компонента. + +Чтобы вставить пример использования компонента: + +1. Импортируйте пример компонента в нужный документ: + +```jsx +import { TextExampleName } from './examples/FormattingRulesExampleName/FormattingRulesExampleName.tsx'; +``` + +2. Вставьте пример компонента в необходимое место контента: + + +<> + +```jsx + +``` + + + +<> + + + + + + +## Табы + +Табы разделяют содержимое на части и показывают только одну из них в определённый момент времени. Переход к другой части контента осуществляется посредством нажатия на соответствующее название вкладки. + +В Consta табы на данный момент нашли два применения: + +- Просмотр кода и примера компонента, +- Когда нужно разбить информацию на категории. Например, у инструкций одна цель, но ее можно достичь разными способами. + +### Код и пример компонента + +Чтобы на одной вкладке отобразить код примера, а на другой – сам пример: + +1. Импортируйте компонент табов в нужный документ: + +```jsx +import { MdxTabs } from '@consta/stand'; +``` + +2. Вставьте пример компонента в необходимое место контента: + + +<> + +````markdown + + +```tsx +import { Example } from '@consta/stand'; +import React from 'react'; + +export const TextExampleName = () => { + return ( + + ); +}; +``` + + + + +```` + + + +<> + + + +```tsx +import { Example } from '@consta/stand'; +import React from 'react'; + +export const TextExampleName = () => { + return ( + + ); +}; +``` + + + + + + + + +### Остальные случаи + +Чтобы на одной вкладке отобразить код примера, а на другой – сам пример: + +1. Импортируйте компонент табов в нужный документ: + +```jsx +import { MdxTabs } from '@consta/stand'; +``` + +2. Вставьте пример компонента в необходимое место контента: + + +<> + +```markdown + +<> + +Тут могла бы быть ваша инструкция для npm + + + +<> + +А тут – для yarn + + + +``` + + + +<> + + +<> + +Тут могла бы быть ваша инструкция для npm + + + +<> + +А тут – для yarn + + + + + + + +## Меню + +Меню — это сгруппированный набор ссылок с названиями подзаголовков, облегчающий переход между ними. Меню обязательно на каждой странице (только если подзаголовков нет или он один). + +Чтобы создать меню: + +1. Импортируйте компонент меню в нужный документ: + +```jsx +import { MdxTabs } from '@consta/stand'; +``` + +2. Вставьте компонент меню сразу после строк импорта: + +```jsx + +``` + +3. Наполняйте компонент вручную по следующим правилам: + + - оформляйте пункты меню по принципу `-[Пункт меню](#пункт-меню)` + - отбивайте подзаголовки ниже H2 табом в соответствии с их уровнем. + +Пример: + +```markdown + + +- [Заголовки](#заголовки) +- [Выделение текста](#выделение-текста) + - [Жирный шрифт](#жирный-шрифт) + - [Моноширинный текст](#моноширинный-текст) + - [Кавычки](#кавычки) +- [Примечание](#примечание) +- [Списки](#списки) + + +``` + +Содержимое меню отображается в боковой панели. + +## Стрелочка + +Чтобы вставить —> в текст, используйте символы `—>`. + +Стрелочка полезна, когда: + +1. Много пунктов и их можно сократить за счет стрелочки, +2. Действие элементарное и не имеет смысла создавать список из двух пунктов. diff --git a/src/docs/portal/formattingRules/formattingRules.stand.tsx b/src/docs/portal/formattingRules/formattingRules.stand.tsx new file mode 100644 index 0000000..b385c66 --- /dev/null +++ b/src/docs/portal/formattingRules/formattingRules.stand.tsx @@ -0,0 +1,8 @@ +import { createStand } from '##/stand/standConfig'; + +export default createStand({ + title: 'Форматирование текста', + id: 'formatting-rules', + group: 'portal', + order: 810, +}); diff --git a/src/docs/portal/formattingRules/images/example.png b/src/docs/portal/formattingRules/images/example.png new file mode 100644 index 0000000..3298fc7 Binary files /dev/null and b/src/docs/portal/formattingRules/images/example.png differ diff --git a/src/docs/portal/glossary/examples/GlossaryExample/GlossaryExample.tsx b/src/docs/portal/glossary/examples/GlossaryExample/GlossaryExample.tsx new file mode 100644 index 0000000..5bdcf5f --- /dev/null +++ b/src/docs/portal/glossary/examples/GlossaryExample/GlossaryExample.tsx @@ -0,0 +1,44 @@ +import { Example } from '@consta/stand'; +import React from 'react'; + +export const Alternative = () => { + return ( + + ); +}; + +export const RoleOfTheElement = () => { + return ( + + ); +}; diff --git a/src/docs/portal/glossary/glossary.stand.mdx b/src/docs/portal/glossary/glossary.stand.mdx new file mode 100644 index 0000000..4e36fba --- /dev/null +++ b/src/docs/portal/glossary/glossary.stand.mdx @@ -0,0 +1,229 @@ +import { MdxMenu, MdxInformer } from '@consta/stand'; +import { + Alternative, + RoleOfTheElement, +} from './examples/GlossaryExample/GlossaryExample.tsx'; + + + +- [Термины](#термины) +- [Англицизмы](#англицизмы) +- [Сокращения](#сокращения) +- [IT-жаргон](#it-жаргон) + - [Как использовать IT-жаргон, чтобы вас поняли?](#как-использовать-it-жаргон-чтобы-вас-поняли) + - [Альтернативные слова](#альтернативные-слова) + + + +## Термины + +**API** +Программный интерфейс, предоставляющий разработчикам возможности для взаимодействия с компонентами или системой. В контексте дизайн-системы — это описание доступных свойств, методов и событий для компонентов. + +**Адаптивные компоненты** +Компоненты, которые автоматически изменяют внешний вид и поведение в зависимости от контекста, например, размера экрана или устройства пользователя. + +**Алиас библиотеки** +Упрощённое имя для ссылки на библиотеку или её часть, используемое для сокращения путей и удобства импорта. + +**Брендбук** +Документ, который описывает основные принципы визуальной идентичности бренда, включая шрифты, цвета, логотипы и стили. В отсутствие брендбука дизайн-система может быть использована как его замена. + +**Дизайн-спецификация** +Пояснения к работе элементов интерфейса и значимым параметрам в вёрстке, фиксирующие ограничения системы, правила поведения элементов при взаимодействии с пользователем и реакциях системы. Может включать описания состояний, размеров, цветов, отступов и анимаций. + +**Дизайн-токен, токен** +Набор стандартизированных переменных, описывающих основные элементы визуального языка: цвета, шрифты, размеры, отступы, стили элементов и параметры анимации. Используются для обеспечения единого стиля и упрощения изменений в дизайн-системе. + +**Дочерний компонент** +Компонент, который используется внутри родительского компонента для создания сложной структуры интерфейса. Например, элементы списка в компоненте **ContextMenu**. + +**DOM-элемент** +Узел в дереве DOM (Document Object Model), который описывает HTML-тег, его атрибуты и возможные обработчики событий. DOM-элементы используются для работы с разметкой на стороне клиента. + +**Контрол** +Элемент интерфейса, который даёт пользователю возможность взаимодействовать с системой. Примеры: кнопки, переключатели, поля ввода. + +**Лейблы** + +1. Подписи или текстовые метки, используемые для идентификации контролов, таких как поля ввода или чекбоксы. +2. В контексте задач или тикетов: текстовые маркеры, помогающие классифицировать задачи. Например, по функциональности или состоянию. + +**Модификатор** +Дополнительный класс или атрибут, который изменяет внешний вид или поведение базового компонента. Например, модификатор может определять размер кнопки или её состояние. + +**Проксирование** +Передача или делегирование свойств и методов от одного объекта (например, компонента) к другому. Может использоваться для передачи атрибутов от корневого элемента к вложенным или дочерним элементам. + +**Пресет** +Сохранённые настройки, которые определяют тему проекта. Пресет включает параметры для генерации конкретных CSS-файлов, таких как цвета, типографика или тени, упрощая применение тем. + +**Рефакторинг** +Процесс изменения внутренней структуры кода без изменения его поведения и API. Основная цель — улучшение читаемости, производительности или поддерживаемости. + +**Семантические имена** +Имена переменных или свойств, которые точно отражают их назначение в контексте интерфейса. Например, вместо `--main-color` используется `--button-primary-background`. + +**Стенд** +Тестовая среда для демонстрации и проверки компонентов дизайн-системы. + +## Англицизмы + +Мы с командой договорились, как писать заимствованные слова, чтобы обеспечить консистентность текста. + +**Апрув** +Подтверждение или согласие на изменение. +Пример: «Для мержа PR требуется как минимум два апрува». + +**Баг** +Ошибка в коде или работе программы. +Пример: «Исправьте баг, чтобы функция заработала корректно». + +**Баг-репорт** +Описание ошибки для её последующего устранения. +Пример: «Создайте баг-репорт с шагами для воспроизведения проблемы». + +**Брейкпоинт** +Место, где выполнение программы останавливается. +Пример: «Хелпер `getLastPoint` возвращает последний пересечённый брейкпоинт». + +**Бэклог** +Список задач или требований, ожидающих выполнения. +Пример: «Перед началом спринта обновите бэклог». + +**Вьюпорт** +Видимая пользователю область веб-страницы, то, что может увидеть пользователь, не прибегая к прокрутке. +Пример: «Не показывайте `Tooltip` за пределами вьюпорта». + +**Деплой** +Процесс переноса кода из среды разработки на рабочий сервер. В деплой входит сборка и упаковка приложения, его тестирование и развёртывание на сервере или устройстве. + +**Дроп** +Событие `drop`, когда элемент или выделенный текст перетаскивается на допустимую цель перетаскивания. + +**Коммит** +Фиксация изменений в репозитории. +Пример: «Сделайте коммит с описанием внесённых изменений». + +**Конфиг** +Файл или набор настроек для конфигурации проекта. +Пример: «Настройки можно изменить в конфиге проекта». + +**Колбэк** +Функция, которая должна быть выполнена после того, как другая функция завершит работу. +Пример: «Колбэк отрабатывает каждый раз при открытии/закрытии выпадающего списка». + +**Контрол** +Интерфейсный элемент для взаимодействия пользователя с системой. + +**Лейбл** +Подпись к элементу пользовательского интерфейса. + +**Мейнтейнер** +Человек, который отвечает за поддержку и развитие проекта. +Пример: «Мейнтейнеры проекта должны проверить изменения перед их слиянием». + +**Мёрж** +Объединение веток в репозитории. +Пример: «Выполните мёрж изменений в основную ветку». + +**Плейсхолдер** +Значение подсказки. + +**Промис** +Объект, который представляет собой результат выполнения какого-либо кода. + +**Пропс** +Аргумент-объект, передаваемый компоненту. +Пример: «Для объявления пропсов лучше использовать type, а не interface». + +**Пулреквест** (PR) +Запрос на внесение изменений в репозиторий. +Пример: «Отправьте пулреквест в ветку dev для проверки изменений». + +**Ресайз** +Изменение размера элемента. + +**Ресайзер** +Контрол для изменения размера элемента. + +**Селект** +Выпадающий список для выбора значений. +Пример: «В первом селекте выберите ветку dev, во втором — свою». + +**Скоуп** +Область применения или ответственности. +Пример: «Скоуп изменений был ограничен только обновлением документации». + +**Скролл** +Форма передачи информации, при которой текст или изображение передвигается в вертикальном либо в горизонтальном направлении, чтобы увидеть дополнительную информацию в окне. +Пример: «Если табы не умещаются, появляется скролл». + +**Тикет** +Конкретная задача из бэклога, оформленная в системе трекинга. +Пример: «Все тикеты с высоким приоритетом должны быть завершены до релиза». + +**Фолбэк** +Запасной вариант, используемый, если основной функционал недоступен. +Пример: «Если браузер не поддерживает эту функцию, настройте фолбэк». + +**Форк** +Копия репозитория с возможностью самостоятельной доработки. +Пример: «Для выполнения этой задачи создайте форк репозитория». + +**Фрейм** +Область или компонент в дизайнерской программе. +Пример: «Укажите ссылку на фрейм в Figma в описании задачи». + +**Хак** +Обходной путь или нестандартное решение. +Пример: «Этот хак помог исправить проблему совместимости в старых браузерах». + +**Хелпер** +Многократно используемый фрагмент кода, который можно использовать во всём приложении. +Пример: «Сделаем хелпер `upper`, который будет брать строку из контекста и возвращать ее в верхнем регистре». + +## Сокращения + +**БЭМ** (Блок, Элемент, Модификатор) +Компонентный подход к веб-разработке, в основе которого лежит принцип разделения интерфейса на независимые блоки. + +## IT-жаргон + +### Как использовать IT-жаргон, чтобы вас поняли? + +Не вставляйте английские слова, чтобы не было эффекта «Смотря какой fashion, смотря какой fabric». Способы решения: + +- Заменяйте альтернативами на русском языке, если такие есть. Например, не «хоткей», а «горячая клавиша». Это важно, потому что так текст станет понятнее для пользователей, если они не знакомы с английским термином или только осваиваются в IT. + + + +- Указывайте роль элемента. Например, «эффект `hover`», а не «эффект hover» или «ховер эффект». Это важно, потому что так вы сразу покажете название свойства, элемента, переменной в программе. + + + +- Если собираетесь использовать профессионализмы в доке, вносите их глоссарий и давайте им определения. Так вы поможете пользователям быстрее погрузиться в контекст продукта. + + + +Учитывайте, что язык постоянно развивается и то, что было жаргонизмом вчера, может стать общеизвестным словом сегодня. Следите за трендами и обновляйте глоссарий. + + + +### Альтернативные слова + +Здесь мы перечислим профессиональные жаргоны, которые могут использовать программисты и дизайнеры в своей работе и порекомендуем альтернативы для понятной замены таких слов в документации. + +- Айтем – элемент, +- Аутлайн – обводка, +- Блюр – размытие, +- Бордер – граница, +- Лоадер – индикатор загрузки, +- Модалка – всплывающее окно, +- Паддинг – внутренний отступ. + + + +Дополняйте глоссарий и предлагайте изменения, если нашли спорный момент. Мы рады вашему участию! + + diff --git a/src/docs/docsPortal/docsPortal.stand.tsx b/src/docs/portal/glossary/glossary.stand.tsx similarity index 62% rename from src/docs/docsPortal/docsPortal.stand.tsx rename to src/docs/portal/glossary/glossary.stand.tsx index 07b38ee..a59fa98 100644 --- a/src/docs/docsPortal/docsPortal.stand.tsx +++ b/src/docs/portal/glossary/glossary.stand.tsx @@ -1,8 +1,8 @@ import { createStand } from '##/stand/standConfig'; export default createStand({ - title: 'Портал', - id: 'docsPortal', + title: 'Глоссарий', + id: 'glossary', group: 'portal', - order: 810, + order: 850, }); diff --git a/src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.mdx b/src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.mdx new file mode 100644 index 0000000..8129261 --- /dev/null +++ b/src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.mdx @@ -0,0 +1,74 @@ +import { MdxTabs } from '@consta/stand'; +import { MdxMenu } from '@consta/stand'; +import { MdxInformer } from '@consta/stand'; + + + +- [Типы веток и коммитов](#типы-веток-и-коммитов) +- [Оформить ветку](#оформить-ветку) +- [Оформить коммит](#оформить-коммит) +- [Оформить пулреквест](#оформить-пулреквест) + + + +## Типы веток и коммитов + +- **feat** — добавление нового функционала. +- **fix** — исправление багов. +- **refactor** — изменения в кодовой базе, не добавляющие новые функции и не исправляющие ошибки (например, улучшение структуры кода). +- **docs** — обновление или добавление документации. +- **chore** — мелкие изменения, не влияющие на функциональность (например, обновление зависимостей). +- **changelog** — обновления, касающиеся истории изменений. +- **release** — коммиты для выпуска версии проекта. + +## Оформить ветку + +Чтобы оформить название ветки, используйте формат: + +- `<тип>/<компонент>` – если работа ведется в рамках одной сущности, +- `<тип>/<краткое-описание-изменений>` – если изменения затрагивают несколько сущностей. + +Где: + +- `тип` – это [тип изменений](https://www.notion.so/12ac4fa839ec80f09234fb3ae3ddb79a?pvs=21), +- `компонент` – это сущность, которой коснулись изменения. Это может быть и название компонента, и раздел документации на Портале, и отдельный функционал Consta типа [Конструктора тем](##THEME_CONSTRUCTOR), +- `краткое-описание-изменений` – небольшое, но емкое описание изменений. + + + Не используйте вложенные названия веток, такие как `fix/AutoComplete/bug`. + Подобная структура ломает навигацию. + + +### Примеры + +- `feat/Dropdown` — для добавления нового функционала в Dropdown. +- `docs/ContributingGuide` — для обновления гайдлайнов по контрибьютингу. +- `docs/fix-links` – для правки ссылок в нескольких файлоы с документацией. + +## Оформить коммит + +В названии первого коммита используйте формат `<тип>(<компонент>): <краткое описание изменений>`, где: + +- `тип` – это [тип изменений](#типы-веток-и-коммитов), +- `компонент` – это сущность, которой коснулись изменения. Это может быть и название компонента, и раздел документации на Портале, и отдельный функционал Consta типа [Конструктора тем](##THEME_CONSTRUCTOR), +- `краткое описание изменений` – небольшое, но емкое описание изменений. Подробное описание изменений давайте в описании коммита. + + + Если коммит включает в себя множество изменений, опустите название сущности. + + +### Примеры + +- `fix(AutoComplete): fix search bug` +- `feat(Button): add loading state` +- `release: 5.2.0` + +## Оформить пулреквест + +Оформляйте пулреквест так, чтобы вы и другие ревьюеры видели и понимали, что изменилось: + +- в описании дайте ссылку на измененную страницу со стенда пулреквеста. +- привяжите пулреквест к задачке с [командной доски](https://github.com/orgs/consta-design-system/projects/7). Для этого описании или в теле первого коммита напишите `closes scope/repo#issue`. Например, `closes consta-design-system/uikit#3481`. +- включите краткое описание, зачем проводилась эта работа, включая релевантные ссылки. +- указывайте, когда вы ожидаете ответ. Если реквест в процессе работы, то общепринятой практикой является добавление префикса **[WIP]** (work in progress) к его названию. +- @упоминайте тех, кого вы хотите видеть в обсуждении. diff --git a/src/docs/docs/docs.stand.tsx b/src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.tsx similarity index 53% rename from src/docs/docs/docs.stand.tsx rename to src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.tsx index 7912595..19663cb 100644 --- a/src/docs/docs/docs.stand.tsx +++ b/src/docs/portal/makingBranchesAndCommits/makingBranchesAndCommits.stand.tsx @@ -1,8 +1,8 @@ import { createStand } from '##/stand/standConfig'; export default createStand({ - title: 'Документация для компонента', - id: 'docs', + title: 'Работа с Git', + id: 'work-with-git', group: 'portal', - order: 820, + order: 830, }); diff --git a/src/docs/portal/namingRules/namingRules.stand.mdx b/src/docs/portal/namingRules/namingRules.stand.mdx new file mode 100644 index 0000000..7423366 --- /dev/null +++ b/src/docs/portal/namingRules/namingRules.stand.mdx @@ -0,0 +1,436 @@ +import { MdxMenu, MdxInformer } from '@consta/stand'; + + + +- [Общие рекомендации](#общие-рекомандации) + - [Английский язык](#английский-язык) + - [Единообразие](#единообразие) + - [S-I-D](#s-i-d) + - [Сокращения](#сокращения) + - [Дублирование контекста](#дублирование-контекста) + - [Отображение ожидаемого результата](#отображение-ожидаемого-результата) +- [Правила наименования переменных](#правила-наименования-переменных) + - [Значения и массивы](#значение-и-массивы) + - [Функции](#функции) + - [A/HC/LC Паттерн](#a/hc/lc-паттерн) + - [Префикс](#префикс) + - [Действия](#действия) + - [Контекст](#контекст) + - [Обработчики событий](#обработчики-событий) +- [Правила наименования файлов и папок](#правила-наименования-файлов-и-папок) + + + +## Общие правила + +### Английский язык + +Используйте английский язык при именовании переменных и функций. + +```jsx +/* Плохо */ +const primerNombre = 'Gustavo'; +const amigos = ['Kate', 'John']; + +/* Хорошо */ +const firstName = 'Gustavo'; +const friends = ['Kate', 'John']; +``` + +### Единообразие + +Выберите одно соглашение об именовании и следуйте ему. Это может быть `camelCase`, `PascalCase`, `snake_case` или `kebab-case`. + +Так как Consta разработана на React, везде, кроме названий компонентов, мы будем использовать нотацию `camelCase`. + +```jsx +/* Плохо */ +const page_count = 5; +const shouldUpdate = true; + +/* Хорошо */ +const pageCount = 5; +const shouldUpdate = true; + +/* Тоже хорошо */ +const page_count = 5; +const should_update = true; +``` + +### S-I-D + +Имя должно быть коротким, интуитивно понятным и описательным: + +- **Коротким (Short)**. Имя не должно занимать много времени, чтобы набираться и, следовательно, запоминаться; +- **Интуитивно понятным (Intuitive)**. Имя должно звучать естественно, как можно ближе к обыденной речи; +- **Описательным (Descriptive)**. Имя должно наиболее эффективно отражать то, что оно делает/чем обладает. + +```jsx +/* Плохо */ +const a = 5; // "a" может означать что угодно +const isPaginatable = a > 10; // "Paginatable" звучит крайне неестественно +const shouldPaginatize = a > 10; // Придуманные глаголы — это так весело! + +/* Хорошо */ +const postCount = 5; +const hasPagination = postCount > 10; +const shouldPaginate = postCount > 10; // альтернативно +``` + +### Сокращения + +Не используйте сокращения. Они не способствуют ничему, кроме снижения читабельности кода. Найти короткое, описательное имя может быть сложно, но сокращение не является оправданием для отказа от этого. + +```jsx +/* Плохо */ +const onItmClk = () => {}; + +/* Хорошо */ +const onItemClick = () => {}; +``` + +### Дублирование контекста + +Имя не должно дублировать контекст, в котором оно определено. Всегда удаляйте контекст из имени, если это не ухудшает его читабельность. + +```jsx +class MenuItem { + /* Имя метода дублирует контекст (который "MenuItem") */ + handleMenuItemClick = (event) => { ... } + + /* Читается хорошо, как `MenuItem.handleClick()` */ + handleClick = (event) => { ... } +} +``` + +### Отображение ожидаемого результата + +Имя должно отражать ожидаемый результат. + +```jsx +/* Плохо */ +const isEnabled = itemCount > 3; +return