front-design

Front Design (Knock-Knock Edition)

Этот навык предназначен для создания эстетичных, производительных и архитектурно правильных интерфейсов для мессенджера Knock-Knock.

Основные принципы (Knock-Knock Core)

1. Mobile First: Любой интерфейс сначала проектируется для мобильного экрана. Desktop-версия является адаптивным расширением.
2. Radix UI Base: Используйте кастомные примитивы Radix (<Flex>, <Box>, <Text>, <Container>, <Section>) для построения разметки. Избегайте использования div для лейаутов.
3. Единый источник истины (Tokens): Используйте CSS-переменные, определенные в app/src/index.css.
4. Никаких инлайн-стилей: Стилизация выполняется через пропсы или CSS Modules.
5. React 19.2 Standards:
   • Используй фичи и типы из последней версии React (19.2). Не используй устаревшие методы (например, forwardRef больше не нужен, ref передается как обычный проп).
   • Предпочитай нативные API и новые React хуки (например, useActionState, useFormStatus, useOptimistic).
6. Internationalization (i18n):
   • No Hardcode: Текст в UI никогда не пишется хардкодом.
   • Используй хук: const { t } = useTranslation(); -> t('auth.login.title').
   • Приоритет: Русский язык — база, Английский — второй.
   • Нейминг ключей: Используй семантическую вложенность (page.component.element).
7. Темизация: Интерфейс должен идеально выглядеть как в светлой, так и в темной теме, используя семантические переменные (например, --main-background, --foreground).

Дизайн-система и токены

При написании стилей или компонентов ВСЕГДА обращайтесь к переменным из index.css:

Цвета и семантика

• --primary: Основной акцентный цвет (обычно blue-9).
• --background: Фон приложения.
• --surface: Цвет панелей и карточек.
• --destructive: Цвета для ошибок и удаления.

Отступы (Spacing)

Используйте системные переменные для консистентности:

• --space-xs (8px), --space-sm (12px), --space-md (16px), --space-lg (24px) и т.д.

Типографика

Используйте var(--font-sans) и системные размеры:

• --text-sm (14px), --text-base (16px), --text-lg (18px) и т.д.

Правила реализации

1. Верстка лейаутов

Используйте кастомные Radix UI компоненты для структуры:

import { Text, Button } from '@/components/ui';
import { Flex, Box } from '@/components/layout';
import styles from './MyComponent.module.css';

export const MyComponent = () => (
  <Flex direction="column" gap="3" className={styles.container}>
    <Box>
      <Text size="5" weight="bold">Заголовок</Text>
    </Box>
    {/* Контент */}
  </Flex>
);

2. CSS Modules

Если пропсов Radix недостаточно, используйте CSS Modules. Внутри модулей можно обращаться к глобальным переменным:

/* MyComponent.module.css */
.container {
  padding: var(--space-md);
  background: var(--surface);
  border-radius: var(--radius-md);
  border: 1px solid var(--border);
}

Стандарты Дизайна: Premium Glassmorphism

Философия Ядра

• НИКАКОГО ПЛОСКОГО ДИЗАЙНА (NO FLAT): Каждая поверхность должна иметь глубину (градиенты, глянец, стекло или тени).
• НИКАКОГО ПРОСТОГО БЕЛОГО: Светлая тема должна использовать текстурированные или градиентные фоны (Пастельная Сетка или Кремовая Бумага).
• НИКАКОГО ПРОСТОГО ЧЕРНОГО: Темная тема должна использовать глубокие цветные градиенты (Космический Индиго или Лесной Зеленый).
• ГАРМОНИЯ И СИММЕТРИЯ: Компоненты должны быть визуально сбалансированы. Отступы должны быть симметричными, элементы выравнены по сетке или оптическому центру. Избегайте визуального шума, "рваных" краев и диспропорций.

Утвержденные Темы

1. Default ⭐ (По умолчанию для новых пользователей)

   • data-theme="default", дефолтный mode: light
   • Ключевые слова: Чисто, знакомо, практично (WA-инспирд).
   • Light: #f0f2f5 фон, #ffffff панели, #00a884 акцент, #d9fdd3 исходящие
   • Dark: #111b21 фон, #202c33 панели, #00a884 акцент, #005c4b исходящие
   • Типографика: Helvetica Neue, Helvetica, Arial, -apple-system, sans-serif

2. Cosmic Neon

   • data-theme="neon"
   • Ключевые слова: Киберпанк, Будущее, Голография.
   • Палитра: Фиолетовые/Индиго фоны, Неоновые Голубые/Розовые акценты.
   • Стекло: Сильное размытие (20px), матовый эффект.

3. Emerald Luxury

   • data-theme="emerald"
   • Ключевые слова: VIP, Природа, Золото, Платина.
   • Палитра: Глубокие Лесные/Угольные фоны, Изумрудные/Золотые акценты.
   • Стекло: Чёткие, тонкие границы (Золото/Серебро), слабое размытие.

Mobile First Компоненты

• Поля ввода: Формы «Таблетки» (Pill-shape) — в default со светлым фоном, в neon/emerald — с glassmorphism.
• Навигация: Для default — чёткие бары. Для Neon/Emerald — стеклянные.
• Типографика: default → Helvetica Neue. neon/emerald → Inter или Outfit.

CSS Архитектура

• Используйте только семантические переменные: --surface, --accent-primary, --border, --muted.
• Никогда не хардкодьте HEX значения в CSS-модулях — только через var(--*).
• Поддержка трёх тем: [data-theme='default'], [data-theme='neon'], [data-theme='emerald'].
• CSS Layers (@layer) под полным запретом из-за риска перекрытия базовых стилей (Radix UI не работает с кастомными слоями корректно).
• Container Queries используются по умолчанию для создания компонентов, меняющих верстку (например, переход из Landscape в Portrait ориентацию карточек) в зависимости от контейнера.

3. Анимации

Используйте CSS-анимации для микровзаимодействий. Для сложных переходов страниц используйте возможности TanStack Router. Оставляйте анимации лёгкими, чтобы не блокировать основной поток (важно для криптографии).

Чего следует ИЗБЕГАТЬ

• Generic AI Style: Стандартные фиолетовые градиенты на белом фоне.
• Инлайн-стили: style={{ marginTop: '10px' }} и style={{ color: 'var(--primary)' }} в компонентах — запрещено.
• div-soup: Использование div там, где подходит Flex или Box.
• Жёсткие значения: Не пишите в модулях 16px, пишите var(--space-md).
• HEX в CSS-модулях: Не color: #00a884, а color: var(--accent-primary).

Референсы

• Radix UI vs CSS Modules — когда и что использовать.
• Mobile-First Patterns — паттерны для мессенджера.
• Theming & Colors — глубокая работа с темами.
• DESIGN_SYSTEM_PLAN.md — план рефакторинга CSS, полная палитра default-темы.