From feed6b67ccd6e452319071c70bbc2a2dac117fec Mon Sep 17 00:00:00 2001
From: simbiozizv <simbioziz@gmail.com>
Date: Wed, 30 Sep 2026 16:26:39 +0300
Subject: [PATCH] fix(QueriesNavigation): align navigation layout and schema
 with design

Use Gravity UI spacing and button sizes, update the unknown item icon, and move row styles into their owning components.

Show field descriptions and Datacatalog metadata by default. Keep Sort order and Required available through column settings, and support searching the new metadata.

Validated with TypeScript, ESLint, 31 tests, and library and Storybook builds.
---
 src/components/ClusterRow/ClusterRow.scss     | 11 +++
 src/components/ClusterRow/ClusterRow.tsx      |  1 +
 .../FieldsSearchToolbar.tsx                   |  2 +
 .../FieldsSelector/FieldsSelector.tsx         | 12 ++-
 .../NavigationActionButtons.tsx               |  6 +-
 .../NavigationItemRow/NavigationItemRow.scss  | 16 ++++
 .../NavigationItemRow/NavigationItemRow.tsx   |  1 +
 .../SearchWithButtons/SearchWithButtons.tsx   |  6 +-
 src/helpers/getDefaultNavigationIcon.ts       |  4 +-
 src/modules/ClustersList/ClustersList.scss    | 11 ---
 src/modules/ClustersList/ClustersList.tsx     |  1 -
 .../NavigationDetail/NavigationDetail.scss    | 31 +++++--
 .../NavigationDetail/NavigationDetail.tsx     |  2 +
 .../NavigationHeader/NavigationHeader.tsx     |  2 +-
 .../NavigationItemsList.scss                  | 83 +++++++------------
 .../internal/NavigationItemsListHeader.scss   | 11 +--
 .../NavigationSchema/NavigationSchema.scss    | 39 +++++----
 .../NavigationSchema/NavigationSchema.tsx     |  6 +-
 .../helpers/buildSchemaColumns.tsx            | 19 ++++-
 .../NavigationSchema/helpers/filterSchema.ts  |  2 +
 src/modules/NavigationSchema/i18n/en.json     | 15 ++--
 src/modules/NavigationSchema/i18n/ru.json     | 15 ++--
 .../NavigationSchema/story/mockData.ts        | 18 +++-
 .../QueriesNavigation/QueriesNavigation.scss  | 20 +++--
 .../QueriesNavigation/QueriesNavigation.tsx   |  2 +
 src/types/navigation.ts                       |  2 +
 tests/components/NavigationSchema.test.tsx    | 62 ++++++++++++++
 27 files changed, 268 insertions(+), 132 deletions(-)
 create mode 100644 src/components/ClusterRow/ClusterRow.scss
 create mode 100644 src/components/NavigationItemRow/NavigationItemRow.scss
 delete mode 100644 src/modules/ClustersList/ClustersList.scss
 create mode 100644 tests/components/NavigationSchema.test.tsx

diff --git a/src/components/ClusterRow/ClusterRow.scss b/src/components/ClusterRow/ClusterRow.scss
new file mode 100644
index 0000000..9270ed1
--- /dev/null
+++ b/src/components/ClusterRow/ClusterRow.scss
@@ -0,0 +1,11 @@
+.qp-cluster-row {
+    width: 100%;
+    padding: 0 var(--g-spacing-3) 0 var(--g-spacing-4);
+    box-sizing: border-box;
+    cursor: pointer;
+
+    &__title {
+        flex-grow: 1;
+        min-width: 0;
+    }
+}
diff --git a/src/components/ClusterRow/ClusterRow.tsx b/src/components/ClusterRow/ClusterRow.tsx
index 7d6df73..d19e843 100644
--- a/src/components/ClusterRow/ClusterRow.tsx
+++ b/src/components/ClusterRow/ClusterRow.tsx
@@ -1,6 +1,7 @@
 import React, {FC} from 'react';
 import {Avatar, Flex, Text} from '@gravity-ui/uikit';
 import cn from 'bem-cn-lite';
+import './ClusterRow.scss';
 import {NavigationCluster} from '../../types/navigation';
 
 const block = cn('qp-cluster-row');
diff --git a/src/components/FieldsSearchToolbar/FieldsSearchToolbar.tsx b/src/components/FieldsSearchToolbar/FieldsSearchToolbar.tsx
index e478908..3b0b09d 100644
--- a/src/components/FieldsSearchToolbar/FieldsSearchToolbar.tsx
+++ b/src/components/FieldsSearchToolbar/FieldsSearchToolbar.tsx
@@ -27,6 +27,7 @@ export function FieldsSearchToolbar<K extends string = string>({
 
     return (
         <SearchWithButtons
+            gap={2}
             value={search}
             placeholder={searchPlaceholder}
             onUpdate={onSearchUpdate}
@@ -36,6 +37,7 @@ export function FieldsSearchToolbar<K extends string = string>({
                     ? [
                           <FieldsSelector<K>
                               key="fields-selector"
+                              buttonView="flat"
                               fields={fields}
                               value={visibleFields}
                               onChange={onVisibleFieldsChange}
diff --git a/src/components/FieldsSelector/FieldsSelector.tsx b/src/components/FieldsSelector/FieldsSelector.tsx
index e3a1d61..59c5731 100644
--- a/src/components/FieldsSelector/FieldsSelector.tsx
+++ b/src/components/FieldsSelector/FieldsSelector.tsx
@@ -1,5 +1,5 @@
 import React, {ReactNode, useState} from 'react';
-import {Button, Flex, Icon, Popup, Text} from '@gravity-ui/uikit';
+import {Button, type ButtonProps, Flex, Icon, Popup, Text} from '@gravity-ui/uikit';
 import GearIcon from '@gravity-ui/icons/svgs/gear.svg';
 import CheckIcon from '@gravity-ui/icons/svgs/check.svg';
 import {useToggle} from '../../helpers/useToggle';
@@ -17,6 +17,7 @@ export type FieldsSelectorProps<K extends string = string> = {
     value: K[];
     onChange: (value: K[]) => void;
     buttonLabel?: string;
+    buttonView?: ButtonProps['view'];
 };
 
 const block = cn('qp-fields-selector');
@@ -26,6 +27,7 @@ export const FieldsSelector = <K extends string = string>({
     value,
     onChange,
     buttonLabel = i18n('action_configure-visible-fields'),
+    buttonView = 'normal',
 }: FieldsSelectorProps<K>) => {
     const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null);
     const [open, toggleOpen] = useToggle(false);
@@ -37,7 +39,13 @@ export const FieldsSelector = <K extends string = string>({
 
     return (
         <>
-            <Button ref={setButtonElement} onClick={toggleOpen} aria-label={buttonLabel}>
+            <Button
+                view={buttonView}
+                size="m"
+                ref={setButtonElement}
+                onClick={toggleOpen}
+                aria-label={buttonLabel}
+            >
                 <Icon data={GearIcon} size={16} />
             </Button>
             <Popup
diff --git a/src/components/NavigationActionButtons/NavigationActionButtons.tsx b/src/components/NavigationActionButtons/NavigationActionButtons.tsx
index a8a744d..6b7dfff 100644
--- a/src/components/NavigationActionButtons/NavigationActionButtons.tsx
+++ b/src/components/NavigationActionButtons/NavigationActionButtons.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import {Button, Flex} from '@gravity-ui/uikit';
+import {Button, type ButtonProps, Flex} from '@gravity-ui/uikit';
 import type {NavigationAction} from '../../types/navigation';
 
 export type NavigationActionButtonsProps<TArg> = {
@@ -7,6 +7,7 @@ export type NavigationActionButtonsProps<TArg> = {
     arg: TArg;
     className?: string;
     buttonClassName?: string;
+    size?: ButtonProps['size'];
 };
 
 export function NavigationActionButtons<TArg>({
@@ -14,6 +15,7 @@ export function NavigationActionButtons<TArg>({
     arg,
     className,
     buttonClassName,
+    size = 's',
 }: NavigationActionButtonsProps<TArg>) {
     const visibleActions = actions?.filter((action) => !action.hidden) ?? [];
 
@@ -27,7 +29,7 @@ export function NavigationActionButtons<TArg>({
                 <Button
                     key={action.id}
                     view="flat"
-                    size="s"
+                    size={size}
                     disabled={action.disabled}
                     title={action.title}
                     aria-label={action.title}
diff --git a/src/components/NavigationItemRow/NavigationItemRow.scss b/src/components/NavigationItemRow/NavigationItemRow.scss
new file mode 100644
index 0000000..f55a634
--- /dev/null
+++ b/src/components/NavigationItemRow/NavigationItemRow.scss
@@ -0,0 +1,16 @@
+.qp-navigation-item-row {
+    width: 100%;
+    padding: 0 var(--g-spacing-3) 0 var(--g-spacing-4);
+    box-sizing: border-box;
+    cursor: pointer;
+
+    &__title {
+        flex-grow: 1;
+        min-width: 0;
+    }
+
+    &_disabled {
+        color: var(--g-color-text-secondary);
+        cursor: default;
+    }
+}
diff --git a/src/components/NavigationItemRow/NavigationItemRow.tsx b/src/components/NavigationItemRow/NavigationItemRow.tsx
index 346e703..d20895f 100644
--- a/src/components/NavigationItemRow/NavigationItemRow.tsx
+++ b/src/components/NavigationItemRow/NavigationItemRow.tsx
@@ -1,6 +1,7 @@
 import React, {FC} from 'react';
 import {Flex, Icon, Text} from '@gravity-ui/uikit';
 import cn from 'bem-cn-lite';
+import './NavigationItemRow.scss';
 import {NavigationItem} from '../../types/navigation';
 import {getDefaultNavigationIcon} from '../../helpers/getDefaultNavigationIcon';
 
diff --git a/src/components/SearchWithButtons/SearchWithButtons.tsx b/src/components/SearchWithButtons/SearchWithButtons.tsx
index 9a83782..b720c3b 100644
--- a/src/components/SearchWithButtons/SearchWithButtons.tsx
+++ b/src/components/SearchWithButtons/SearchWithButtons.tsx
@@ -1,5 +1,5 @@
 import React, {FC} from 'react';
-import {Flex, TextInput} from '@gravity-ui/uikit';
+import {Flex, type FlexProps, TextInput} from '@gravity-ui/uikit';
 import cn from 'bem-cn-lite';
 import './SearchWithButtons.scss';
 
@@ -11,6 +11,7 @@ export type SearchWithButtonsProps = {
     endButtons?: React.ReactNode[];
     onUpdate?: (value: string) => void;
     className?: string;
+    gap?: FlexProps['gap'];
 };
 
 const block = cn('qp-search-with-buttons');
@@ -26,12 +27,13 @@ export const SearchWithButtons: FC<SearchWithButtonsProps> = ({
     endButtons,
     onUpdate,
     className,
+    gap = 1,
 }) => {
     const hasInnerButtons = Boolean(innerButtons?.length);
     const hasEndButtons = Boolean(endButtons?.length);
 
     return (
-        <Flex gap={1} className={block(null, className)}>
+        <Flex gap={gap} className={block(null, className)}>
             <TextInput
                 className={block('input')}
                 value={value}
diff --git a/src/helpers/getDefaultNavigationIcon.ts b/src/helpers/getDefaultNavigationIcon.ts
index cb2a28d..02387e5 100644
--- a/src/helpers/getDefaultNavigationIcon.ts
+++ b/src/helpers/getDefaultNavigationIcon.ts
@@ -1,6 +1,6 @@
 import type {IconData} from '@gravity-ui/uikit';
 import BanIcon from '@gravity-ui/icons/svgs/ban.svg';
-import EyeSlashIcon from '@gravity-ui/icons/svgs/eye-slash.svg';
+import CircleQuestionIcon from '@gravity-ui/icons/svgs/circle-question.svg';
 import FileTextIcon from '@gravity-ui/icons/svgs/file-text.svg';
 import FolderIcon from '@gravity-ui/icons/svgs/folder.svg';
 import LayoutHeaderCellsLargeIcon from '@gravity-ui/icons/svgs/layout-header-cells-large.svg';
@@ -26,7 +26,7 @@ export function getDefaultNavigationIcon(
         case 'link':
             return LinkIcon;
         case 'unknown':
-            return EyeSlashIcon;
+            return CircleQuestionIcon;
         default:
             return BanIcon;
     }
diff --git a/src/modules/ClustersList/ClustersList.scss b/src/modules/ClustersList/ClustersList.scss
deleted file mode 100644
index b6082f6..0000000
--- a/src/modules/ClustersList/ClustersList.scss
+++ /dev/null
@@ -1,11 +0,0 @@
-.qp-cluster-row {
-  width: 100%;
-  padding: 0 var(--g-spacing-2);
-  box-sizing: border-box;
-  cursor: pointer;
-
-  &__title {
-    flex-grow: 1;
-    min-width: 0;
-  }
-}
diff --git a/src/modules/ClustersList/ClustersList.tsx b/src/modules/ClustersList/ClustersList.tsx
index 339ce05..c40b57f 100644
--- a/src/modules/ClustersList/ClustersList.tsx
+++ b/src/modules/ClustersList/ClustersList.tsx
@@ -4,7 +4,6 @@ import type {NavigationCluster, RenderNavigationCluster} from '../../types/navig
 import {ClusterRow} from '../../components/ClusterRow';
 import {LazyList} from '../../components/LazyList';
 import {NAVIGATION_ROW_HEIGHT} from '../../constants/row';
-import './ClustersList.scss';
 
 const block = cn('qp-clusters-list');
 
diff --git a/src/modules/NavigationDetail/NavigationDetail.scss b/src/modules/NavigationDetail/NavigationDetail.scss
index 1db8840..23f3f79 100644
--- a/src/modules/NavigationDetail/NavigationDetail.scss
+++ b/src/modules/NavigationDetail/NavigationDetail.scss
@@ -1,13 +1,26 @@
 .qp-navigation-detail {
-  min-width: 0;
+    min-width: 0;
 
-  &__tabs {
-    overflow-x: auto;
-  }
+    &__header,
+    &__tabs,
+    &__search,
+    &__content {
+        margin-inline: var(--g-spacing-3) var(--g-spacing-2);
+    }
 
-  &__content {
-    min-width: 0;
-    overflow-x: hidden;
-    overflow-y: auto;
-  }
+    &__header,
+    &__tabs,
+    &__search {
+        flex-shrink: 0;
+    }
+
+    &__tabs {
+        overflow-x: auto;
+    }
+
+    &__content {
+        min-width: 0;
+        overflow-x: hidden;
+        overflow-y: auto;
+    }
 }
diff --git a/src/modules/NavigationDetail/NavigationDetail.tsx b/src/modules/NavigationDetail/NavigationDetail.tsx
index f982d74..fa16df4 100644
--- a/src/modules/NavigationDetail/NavigationDetail.tsx
+++ b/src/modules/NavigationDetail/NavigationDetail.tsx
@@ -97,6 +97,7 @@ export const NavigationDetail: React.FC<NavigationDetailProps> = ({
     return (
         <Flex direction="column" gap={2} className={block(null, className)}>
             <NavigationHeader
+                className={block('header')}
                 location={location}
                 actions={mergedActions}
                 renderActions={renderActions}
@@ -114,6 +115,7 @@ export const NavigationDetail: React.FC<NavigationDetailProps> = ({
                     />
                     {config.hasSearch && (
                         <SearchWithButtons
+                            className={block('search')}
                             placeholder={config.searchPlaceholder}
                             value={search}
                             onUpdate={handleSearchUpdate}
diff --git a/src/modules/NavigationHeader/NavigationHeader.tsx b/src/modules/NavigationHeader/NavigationHeader.tsx
index a3161c0..c83469f 100644
--- a/src/modules/NavigationHeader/NavigationHeader.tsx
+++ b/src/modules/NavigationHeader/NavigationHeader.tsx
@@ -40,7 +40,7 @@ export const NavigationHeader: FC<NavigationHeaderProps> = ({
             {renderActions ? (
                 renderActions({location, actions: actions ?? []})
             ) : (
-                <NavigationActionButtons actions={actions} arg={location} />
+                <NavigationActionButtons size="m" actions={actions} arg={location} />
             )}
         </Flex>
     );
diff --git a/src/modules/NavigationItemsList/NavigationItemsList.scss b/src/modules/NavigationItemsList/NavigationItemsList.scss
index a4f2675..bf2ad72 100644
--- a/src/modules/NavigationItemsList/NavigationItemsList.scss
+++ b/src/modules/NavigationItemsList/NavigationItemsList.scss
@@ -1,65 +1,40 @@
-.qp-navigation-item-row {
-  width: 100%;
-  padding: 0 var(--g-spacing-2);
-  box-sizing: border-box;
-  cursor: pointer;
-
-  &__title {
-    flex-grow: 1;
-    min-width: 0;
-  }
-
-  &_disabled {
-    color: var(--g-color-text-secondary);
-    cursor: default;
-  }
-}
-
-.qp-navigation-items-list-header {
-  padding: 0 var(--g-spacing-2);
-
-  &__button {
-    padding-left: 0;
-  }
-}
-
 .qp-navigation-items-list {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
+    display: flex;
+    flex-direction: column;
+    height: 100%;
 
-  &__header {
-    height: 28px;
-  }
+    &__header {
+        height: 28px;
+    }
 
-  &__list {
-    flex-grow: 1;
-    min-height: 0;
+    &__list {
+        flex-grow: 1;
+        min-height: 0;
 
-    .g-list__item_selected:hover {
-      background-color: var(--g-color-base-selection-hover);
+        .g-list__item_selected:hover {
+            background-color: var(--g-color-base-selection-hover);
+        }
     }
-  }
 
-  &__empty {
-    display: flex;
-    flex-direction: column;
-    flex-grow: 1;
-    min-height: 0;
-  }
+    &__empty {
+        display: flex;
+        flex-direction: column;
+        flex-grow: 1;
+        min-height: 0;
+    }
 
-  &__parent-row {
-    flex-shrink: 0;
-    height: 32px;
-    cursor: pointer;
+    &__parent-row {
+        flex-shrink: 0;
+        height: 32px;
+        cursor: pointer;
 
-    &:hover {
-      background-color: var(--g-color-base-simple-hover);
+        &:hover {
+            background-color: var(--g-color-base-simple-hover);
+        }
     }
-  }
 
-  &__empty-content {
-    flex-grow: 1;
-    min-height: 0;
-  }
+    &__empty-content {
+        flex-grow: 1;
+        min-height: 0;
+    }
 }
diff --git a/src/modules/NavigationItemsList/internal/NavigationItemsListHeader.scss b/src/modules/NavigationItemsList/internal/NavigationItemsListHeader.scss
index e158b47..24967ed 100644
--- a/src/modules/NavigationItemsList/internal/NavigationItemsListHeader.scss
+++ b/src/modules/NavigationItemsList/internal/NavigationItemsListHeader.scss
@@ -1,6 +1,7 @@
 .qp-navigation-items-list-header {
-  &__sort {
-    cursor: pointer;
-    user-select: none;
-  }
-}
\ No newline at end of file
+    padding: 0 var(--g-spacing-3) 0 var(--g-spacing-4);
+    &__sort {
+        cursor: pointer;
+        user-select: none;
+    }
+}
diff --git a/src/modules/NavigationSchema/NavigationSchema.scss b/src/modules/NavigationSchema/NavigationSchema.scss
index 77d7914..e23b5be 100644
--- a/src/modules/NavigationSchema/NavigationSchema.scss
+++ b/src/modules/NavigationSchema/NavigationSchema.scss
@@ -1,24 +1,29 @@
 .qp-navigation-schema {
-  --data-table-border-color: var(--g-color-line-generic);
+    --data-table-border-color: var(--g-color-line-generic);
 
-  min-width: 0;
+    min-width: 0;
 
-  &__error {
-    display: block;
-  }
+    &__error {
+        display: block;
+    }
 
-  &__table {
-    overflow-x: auto;
-  }
+    &__table {
+        overflow-x: auto;
+    }
 
-  .data-table__row,
-  .data-table__head {
-    height: 40px;
-  }
+    &__name {
+        white-space: normal;
+        overflow-wrap: anywhere;
+    }
 
-  .data-table__th,
-  .data-table__td {
-    border-width: 0 0 1px;
-    vertical-align: middle;
-  }
+    .data-table__row,
+    .data-table__head {
+        height: 40px;
+    }
+
+    .data-table__th,
+    .data-table__td {
+        border-width: 0 0 1px;
+        vertical-align: middle;
+    }
 }
diff --git a/src/modules/NavigationSchema/NavigationSchema.tsx b/src/modules/NavigationSchema/NavigationSchema.tsx
index f40540d..13f9054 100644
--- a/src/modules/NavigationSchema/NavigationSchema.tsx
+++ b/src/modules/NavigationSchema/NavigationSchema.tsx
@@ -66,7 +66,11 @@ export function NavigationSchema<TColumn extends NavigationSchemaColumn = Naviga
     const [activeVisibleColumns, handleVisibleColumnsChange] = useVisibleColumns(allColumnNames, {
         value: visibleColumns,
         onChange: onVisibleColumnsChange,
-        defaultValue: defaultVisibleColumns,
+        defaultValue:
+            defaultVisibleColumns ??
+            (tableColumns
+                ? undefined
+                : allColumnNames.filter((name) => name !== 'sortOrder' && name !== 'required')),
     });
 
     const displayedColumns = useMemo(
diff --git a/src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx b/src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx
index adf294a..6cbb9b9 100644
--- a/src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx
+++ b/src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx
@@ -19,10 +19,18 @@ export function buildSchemaColumns<TColumn extends NavigationSchemaColumn>(
         {
             name: 'name',
             header: i18n('title_column-name'),
+            width: 200,
             render: ({row}) => (
-                <Flex inline gap={1} alignItems="center">
-                    <Text>{row.name}</Text>
-                    {row.sortOrder && <Icon data={SORT_ICONS[row.sortOrder]} size={14} />}
+                <Flex direction="column" gap={1} className="qp-navigation-schema__name">
+                    <Flex gap={1} alignItems="center">
+                        <Text>{row.name}</Text>
+                        {row.sortOrder && <Icon data={SORT_ICONS[row.sortOrder]} size={14} />}
+                    </Flex>
+                    {row.description && (
+                        <Text variant="caption-2" color="secondary">
+                            {row.description}
+                        </Text>
+                    )}
                 </Flex>
             ),
         },
@@ -31,6 +39,11 @@ export function buildSchemaColumns<TColumn extends NavigationSchemaColumn>(
             header: i18n('title_column-type'),
             render: ({row}) => row.type ?? i18n('value_empty'),
         },
+        {
+            name: 'datacatalogDescription',
+            header: i18n('title_column-datacatalog-description'),
+            render: ({row}) => row.datacatalogDescription ?? i18n('value_empty'),
+        },
         {
             name: 'sortOrder',
             header: i18n('title_column-sort-order'),
diff --git a/src/modules/NavigationSchema/helpers/filterSchema.ts b/src/modules/NavigationSchema/helpers/filterSchema.ts
index 979ed17..4132e5e 100644
--- a/src/modules/NavigationSchema/helpers/filterSchema.ts
+++ b/src/modules/NavigationSchema/helpers/filterSchema.ts
@@ -12,6 +12,8 @@ export function filterSchema<TColumn extends NavigationSchemaColumn>(
     return columns.filter((column) => {
         return (
             column.name.toLowerCase().includes(query) ||
+            (column.description?.toLowerCase().includes(query) ?? false) ||
+            (column.datacatalogDescription?.toLowerCase().includes(query) ?? false) ||
             (column.type?.toLowerCase().includes(query) ?? false)
         );
     });
diff --git a/src/modules/NavigationSchema/i18n/en.json b/src/modules/NavigationSchema/i18n/en.json
index cdf6a04..a03db10 100644
--- a/src/modules/NavigationSchema/i18n/en.json
+++ b/src/modules/NavigationSchema/i18n/en.json
@@ -1,9 +1,10 @@
 {
-    "title_column-name": "Name",
-    "title_column-type": "Type",
-    "title_column-sort-order": "Sort order",
-    "title_column-required": "Required",
-    "value_sort-ascending": "Ascending",
-    "value_sort-descending": "Descending",
-    "value_empty": "—"
+  "title_column-name": "Name and Title",
+  "title_column-type": "Type",
+  "title_column-sort-order": "Sort order",
+  "title_column-required": "Required",
+  "value_sort-ascending": "Ascending",
+  "value_sort-descending": "Descending",
+  "value_empty": "—",
+  "title_column-datacatalog-description": "Datacatalog description"
 }
diff --git a/src/modules/NavigationSchema/i18n/ru.json b/src/modules/NavigationSchema/i18n/ru.json
index c950222..9b73d82 100644
--- a/src/modules/NavigationSchema/i18n/ru.json
+++ b/src/modules/NavigationSchema/i18n/ru.json
@@ -1,9 +1,10 @@
 {
-    "title_column-name": "Имя",
-    "title_column-type": "Тип",
-    "title_column-sort-order": "Сортировка",
-    "title_column-required": "Обязательное",
-    "value_sort-ascending": "По возрастанию",
-    "value_sort-descending": "По убыванию",
-    "value_empty": "—"
+  "title_column-name": "Имя и описание",
+  "title_column-type": "Тип",
+  "title_column-sort-order": "Сортировка",
+  "title_column-required": "Обязательное",
+  "value_sort-ascending": "По возрастанию",
+  "value_sort-descending": "По убыванию",
+  "value_empty": "—",
+  "title_column-datacatalog-description": "Описание Datacatalog"
 }
diff --git a/src/modules/NavigationSchema/story/mockData.ts b/src/modules/NavigationSchema/story/mockData.ts
index 437cf97..60b3210 100644
--- a/src/modules/NavigationSchema/story/mockData.ts
+++ b/src/modules/NavigationSchema/story/mockData.ts
@@ -1,8 +1,22 @@
 import type {NavigationSchemaColumn} from '../../../types/navigation';
 
 export const SCHEMA_COLUMNS: NavigationSchemaColumn[] = [
-    {name: 'id', type: 'int64', sortOrder: 'ascending', required: true},
-    {name: 'created_at', type: 'string', sortOrder: 'descending', required: true},
+    {
+        name: 'id',
+        description: 'Unique record identifier',
+        datacatalogDescription: 'Primary key',
+        type: 'int64',
+        sortOrder: 'ascending',
+        required: true,
+    },
+    {
+        name: 'created_at',
+        description: 'Date and time when the record was created',
+        datacatalogDescription: 'Creation timestamp',
+        type: 'string',
+        sortOrder: 'descending',
+        required: true,
+    },
     {name: 'title', type: 'string', required: true},
     {name: 'status', type: 'string'},
     {name: 'payload', type: 'any'},
diff --git a/src/modules/QueriesNavigation/QueriesNavigation.scss b/src/modules/QueriesNavigation/QueriesNavigation.scss
index 775171f..9b1f7da 100644
--- a/src/modules/QueriesNavigation/QueriesNavigation.scss
+++ b/src/modules/QueriesNavigation/QueriesNavigation.scss
@@ -1,9 +1,17 @@
 .qp-queries-navigation {
-  height: 100%;
+    height: 100%;
+    min-height: 0;
+    min-width: 0;
 
-  &__empty,
-  &__error {
-    padding: var(--g-spacing-2);
-    text-align: center;
-  }
+    &__header,
+    &__search {
+        margin-inline: var(--g-spacing-3) var(--g-spacing-2);
+        flex-shrink: 0;
+    }
+
+    &__empty,
+    &__error {
+        padding: var(--g-spacing-2);
+        text-align: center;
+    }
 }
diff --git a/src/modules/QueriesNavigation/QueriesNavigation.tsx b/src/modules/QueriesNavigation/QueriesNavigation.tsx
index 9fd1046..99eff4d 100644
--- a/src/modules/QueriesNavigation/QueriesNavigation.tsx
+++ b/src/modules/QueriesNavigation/QueriesNavigation.tsx
@@ -131,6 +131,7 @@ export const QueriesNavigation = <
     return (
         <Flex direction="column" gap={1} className={block(null, className)}>
             <NavigationHeader
+                className={block('header')}
                 location={location}
                 actions={actions}
                 renderActions={renderActions}
@@ -139,6 +140,7 @@ export const QueriesNavigation = <
                 onLoadSuggestions={onLoadSuggestions}
             />
             <SearchWithButtons
+                className={block('search')}
                 placeholder={i18n('field_search-placeholder')}
                 value={searchValue}
                 onUpdate={onSearchUpdate}
diff --git a/src/types/navigation.ts b/src/types/navigation.ts
index a780fcf..3b0f201 100644
--- a/src/types/navigation.ts
+++ b/src/types/navigation.ts
@@ -99,6 +99,8 @@ export type NavigationSchemaSortOrder = 'ascending' | 'descending';
 
 export type NavigationSchemaColumn = {
     name: string;
+    description?: string;
+    datacatalogDescription?: string;
     type?: string;
     sortOrder?: NavigationSchemaSortOrder;
     required?: boolean;
diff --git a/tests/components/NavigationSchema.test.tsx b/tests/components/NavigationSchema.test.tsx
new file mode 100644
index 0000000..f5fe9f8
--- /dev/null
+++ b/tests/components/NavigationSchema.test.tsx
@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+
+import React from 'react';
+import {renderToStaticMarkup} from 'react-dom/server';
+import {describe, expect, it} from 'vitest';
+import {NavigationSchema} from '../../src/modules/NavigationSchema';
+import {filterSchema} from '../../src/modules/NavigationSchema/helpers/filterSchema';
+import type {NavigationSchemaColumn} from '../../src/types/navigation';
+
+const columns: NavigationSchemaColumn[] = [
+    {
+        name: 'id',
+        type: 'int64',
+        description: 'Unique record identifier',
+        datacatalogDescription: 'Primary key',
+        required: true,
+    },
+    {name: 'created_at', type: 'timestamp'},
+];
+
+function renderSchema(props: Partial<React.ComponentProps<typeof NavigationSchema>> = {}) {
+    const container = document.createElement('div');
+    container.innerHTML = renderToStaticMarkup(
+        <NavigationSchema data={{columns, loaded: true}} hideToolbar {...props} />,
+    );
+    return container;
+}
+
+describe('NavigationSchema design columns', () => {
+    it('shows descriptions and catalog metadata in three default columns', () => {
+        const container = renderSchema();
+        expect(container.querySelectorAll('thead th')).toHaveLength(3);
+        expect(container.textContent).toContain('Unique record identifier');
+        expect(container.textContent).toContain('Primary key');
+    });
+
+    it('keeps the existing optional columns available through visibleColumns', () => {
+        const container = renderSchema({visibleColumns: ['name', 'sortOrder', 'required']});
+        expect(container.querySelectorAll('thead th')).toHaveLength(3);
+        expect(container.textContent).not.toContain('Primary key');
+        expect(container.querySelector('tbody svg')).not.toBeNull();
+    });
+
+    it('preserves custom table columns without applying default visibility', () => {
+        const container = renderSchema({
+            view: {
+                tableColumns: [{name: 'required', header: 'Custom required', render: () => 'yes'}],
+            },
+        });
+        expect(container.querySelectorAll('thead th')).toHaveLength(1);
+        expect(container.textContent).toContain('Custom required');
+        expect(container.textContent).toContain('yes');
+    });
+
+    it('searches descriptions and supports rows without metadata', () => {
+        expect(filterSchema(columns, ' IDENTIFIER ')).toEqual([columns[0]]);
+        expect(filterSchema(columns, 'PRIMARY')).toEqual([columns[0]]);
+        expect(filterSchema(columns, 'timestamp')).toEqual([columns[1]]);
+        expect(filterSchema(columns, 'missing')).toEqual([]);
+        expect(filterSchema(columns, ' ')).toEqual(columns);
+    });
+});