feat: добавить навигацию и fallback для документаций

- подключён рендер task-list чекбоксов в VitePress - добавлена общая навигация к списку документаций и репозиторию - синхронизирована тема главной страницы и VitePress - добавлен HTML-каркас главной страницы для клиентов без JS - обновлено авторство документации в футере
2026-05-13 16:23:08 +03:00
parent 7554ce58db
commit ab72c06fd5
12 changed files with 451 additions and 18 deletions
--- a/docs/figma-adaptive-standards/.vitepress/config.ts
+++ b/docs/figma-adaptive-standards/.vitepress/config.ts
@@ -1,5 +1,7 @@
 import { defineConfig } from 'vitepress';
+import taskLists from 'markdown-it-task-lists';
 import llmstxt from 'vitepress-plugin-llms';
+import { themeSyncHead } from '../../shared/vitepress/themeHead';
 import { sidebar, site } from '../docs.config';

 export default defineConfig({
@@ -9,9 +11,15 @@ export default defineConfig({
  outDir: site.outDir,
  srcDir: 'content',
  cleanUrls: true,
+  head: [...themeSyncHead],
  vite: {
    plugins: [llmstxt()],
  },
+  markdown: {
+    config(md) {
+      md.use(taskLists);
+    },
+  },
  themeConfig: {
    sidebar,
    socialLinks: [],
--- a/docs/figma-adaptive-standards/.vitepress/theme/index.ts
+++ b/docs/figma-adaptive-standards/.vitepress/theme/index.ts
@@ -0,0 +1 @@
+export { default } from '../../../shared/vitepress/theme';
--- a/docs/shared/vitepress/HomeLink.vue
+++ b/docs/shared/vitepress/HomeLink.vue
@@ -0,0 +1,174 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  variant?: 'back' | 'repo' | 'screen'
+}>(), {
+  variant: 'back',
+})
+
+const repositoryUrl = 'https://gromlab.ru/gromov/docs'
+</script>
+
+<template>
+  <a
+    v-if="variant === 'back'"
+    class="docsNavLink docsBackLink"
+    href="/"
+    target="_self"
+    aria-label="Вернуться к списку документаций"
+  >
+    <span class="docsBackIcon" aria-hidden="true">←</span>
+    <span>К списку документаций</span>
+  </a>
+
+  <a
+    v-else-if="variant === 'repo'"
+    class="docsRepoLink"
+    :href="repositoryUrl"
+    target="_blank"
+    rel="noopener noreferrer"
+    aria-label="Открыть репозиторий"
+    title="Репозиторий"
+  >
+    <svg aria-hidden="true" viewBox="0 0 24 24">
+      <path d="M12 .5a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57l-.02-2.04c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1.01-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .5Z" />
+    </svg>
+  </a>
+
+  <nav v-else class="docsNavLinks" aria-label="Навигация документации">
+    <a
+      class="docsNavLink"
+      href="/"
+      target="_self"
+      aria-label="Вернуться к списку документаций"
+    >
+      <span class="docsBackIcon" aria-hidden="true">←</span>
+      <span>К списку документаций</span>
+    </a>
+    <a
+      class="docsNavLink"
+      :href="repositoryUrl"
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-label="Открыть репозиторий документации"
+    >
+      <svg class="docsScreenRepoIcon" aria-hidden="true" viewBox="0 0 24 24">
+        <path d="M12 .5a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57l-.02-2.04c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1.01-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .5Z" />
+      </svg>
+      Репозиторий
+    </a>
+  </nav>
+</template>
+
+<style scoped>
+.docsBackLink {
+  margin-left: 16px;
+  margin-right: 16px;
+}
+
+.docsNavLinks {
+  display: inline-flex;
+  align-items: center;
+}
+
+.docsNavLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+  font-weight: 600;
+  line-height: var(--vp-nav-height);
+  text-decoration: none;
+  transition: color 0.2s;
+}
+
+.docsBackIcon {
+  color: var(--vp-c-text-3);
+  font-size: 15px;
+  transition: color 0.2s;
+}
+
+.docsNavLink:hover {
+  color: var(--vp-c-brand-1);
+}
+
+.docsNavLink:hover .docsBackIcon {
+  color: var(--vp-c-brand-1);
+}
+
+.docsNavLink:focus-visible {
+  border-radius: 4px;
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.docsRepoLink {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: var(--vp-nav-height);
+  margin-left: 12px;
+  color: var(--vp-c-text-2);
+  transition: color 0.2s;
+}
+
+.docsRepoLink:hover {
+  color: var(--vp-c-brand-1);
+}
+
+.docsRepoLink:focus-visible {
+  border-radius: 6px;
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.docsRepoLink svg,
+.docsScreenRepoIcon {
+  width: 18px;
+  height: 18px;
+  fill: currentColor;
+}
+
+.docsNavLinks {
+  align-items: stretch;
+  flex-direction: column;
+  gap: 0;
+  margin: 0;
+  padding: 8px 0 12px;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.docsNavLinks .docsNavLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 0;
+  color: var(--vp-c-text-1);
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.docsScreenRepoIcon {
+  flex: 0 0 auto;
+}
+
+@media (max-width: 767px) {
+  .docsBackLink,
+  .docsRepoLink {
+    display: none;
+  }
+}
+
+@media (min-width: 768px) {
+  .docsNavLinks {
+    display: none;
+  }
+}
+
+@media (min-width: 960px) {
+  .docsBackLink {
+    margin-left: 24px;
+  }
+}
+</style>
--- a/docs/shared/vitepress/theme.ts
+++ b/docs/shared/vitepress/theme.ts
@@ -0,0 +1,15 @@
+import { h } from 'vue';
+import DefaultTheme from 'vitepress/theme';
+import type { Theme } from 'vitepress';
+import HomeLink from './HomeLink.vue';
+
+export default {
+  extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      'nav-bar-content-before': () => h(HomeLink, { variant: 'back' }),
+      'nav-bar-content-after': () => h(HomeLink, { variant: 'repo' }),
+      'nav-screen-content-before': () => h(HomeLink, { variant: 'screen' }),
+    });
+  },
+} satisfies Theme;
--- a/docs/shared/vitepress/themeHead.ts
+++ b/docs/shared/vitepress/themeHead.ts
@@ -0,0 +1,18 @@
+import type { HeadConfig } from 'vitepress';
+
+export const themeSyncHead: HeadConfig[] = [
+  [
+    'script',
+    { id: 'sync-docs-theme' },
+    `;(() => {
+      const theme = localStorage.getItem('vitepress-theme-appearance')
+      if (theme) return
+
+      const legacyTheme = localStorage.getItem('all-docs-theme')
+      if (!legacyTheme) return
+
+      localStorage.setItem('vitepress-theme-appearance', legacyTheme === 'system' ? 'auto' : legacyTheme)
+      localStorage.removeItem('all-docs-theme')
+    })()`,
+  ],
+];
--- a/docs/slm-design/.vitepress/config.ts
+++ b/docs/slm-design/.vitepress/config.ts
@@ -1,5 +1,7 @@
 import { defineConfig } from 'vitepress';
+import taskLists from 'markdown-it-task-lists';
 import llmstxt from 'vitepress-plugin-llms';
+import { themeSyncHead } from '../../shared/vitepress/themeHead';
 import { sidebar, site } from '../docs.config';

 export default defineConfig({
@@ -9,9 +11,15 @@ export default defineConfig({
  outDir: site.outDir,
  srcDir: 'content',
  cleanUrls: true,
+  head: [...themeSyncHead],
  vite: {
    plugins: [llmstxt()],
  },
+  markdown: {
+    config(md) {
+      md.use(taskLists);
+    },
+  },
  themeConfig: {
    sidebar,
    socialLinks: [],
--- a/docs/slm-design/.vitepress/theme/index.ts
+++ b/docs/slm-design/.vitepress/theme/index.ts
@@ -0,0 +1 @@
+export { default } from '../../../shared/vitepress/theme';
--- a/index.html
+++ b/index.html
@@ -5,10 +5,172 @@
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Единое пространство для идей, черновиков и первых версий документаций" />
+    <script>
+      ;(() => {
+        const theme = localStorage.getItem('vitepress-theme-appearance') || localStorage.getItem('all-docs-theme') || 'auto'
+        const normalizedTheme = theme === 'system' ? 'auto' : theme
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
+        const resolvedTheme = normalizedTheme === 'auto' ? (prefersDark ? 'dark' : 'light') : normalizedTheme
+
+        document.documentElement.dataset.theme = normalizedTheme
+        document.documentElement.classList.toggle('dark', resolvedTheme === 'dark')
+        document.documentElement.style.colorScheme = resolvedTheme
+      })()
+    </script>
+    <style>
+      .static-shell {
+        max-width: 960px;
+        margin: 0 auto;
+        padding: 48px 24px;
+        color: CanvasText;
+        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        line-height: 1.55;
+      }
+
+      .static-shell h1 {
+        margin: 0 0 16px;
+        font-size: clamp(32px, 6vw, 56px);
+        line-height: 1;
+      }
+
+      .static-shell p {
+        margin: 0;
+      }
+
+      .static-lead {
+        max-width: 760px;
+        color: color-mix(in srgb, CanvasText 72%, Canvas);
+        font-size: 18px;
+      }
+
+      .static-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        margin-top: 24px;
+      }
+
+      .static-docs {
+        display: grid;
+        gap: 16px;
+        margin: 40px 0;
+        padding: 0;
+        list-style: none;
+      }
+
+      .static-card {
+        padding: 20px;
+        border: 1px solid color-mix(in srgb, CanvasText 18%, Canvas);
+        border-radius: 16px;
+        background: color-mix(in srgb, CanvasText 4%, Canvas);
+      }
+
+      .static-card h2 {
+        margin: 0 0 8px;
+        font-size: 22px;
+        line-height: 1.2;
+      }
+
+      .static-meta {
+        margin-bottom: 8px;
+        color: color-mix(in srgb, CanvasText 58%, Canvas);
+        font-size: 13px;
+        font-weight: 700;
+        text-transform: uppercase;
+      }
+
+      .static-links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        margin-top: 14px;
+      }
+
+      .static-shell a {
+        color: LinkText;
+      }
+
+      .static-footer {
+        color: color-mix(in srgb, CanvasText 58%, Canvas);
+        font-size: 13px;
+      }
+    </style>
    <title>Документация</title>
  </head>
  <body>
-    <div id="root"></div>
+    <div id="root">
+      <main class="static-shell" aria-labelledby="static-title">
+        <header>
+          <h1 id="static-title">Документация</h1>
+          <p class="static-lead">
+            Единое пространство для идей, черновиков и первых версий документаций,
+            которые ещё формируются и постепенно становятся самостоятельными материалами.
+          </p>
+          <div class="static-actions">
+            <a href="https://gromlab.ru/gromov/docs">Репозиторий</a>
+          </div>
+        </header>
+
+        <section aria-labelledby="static-docs-title">
+          <h2 id="static-docs-title">Список документаций</h2>
+          <ul class="static-docs">
+            <li class="static-card">
+              <article>
+                <div class="static-meta">Архитектура · Доступно</div>
+                <h2><a href="/slm-design/">SLM Design</a></h2>
+                <p>
+                  Архитектура frontend-приложений, где слои задают направление зависимостей,
+                  модули становятся границами ответственности, а явный DI через фабрики удерживает домены изолированными и предсказуемыми.
+                </p>
+                <div class="static-links" aria-label="LLM-артефакты SLM Design">
+                  <a href="/slm-design/llms.txt">llms.txt</a>
+                  <a href="/slm-design/llms-full.txt">llms-full.txt</a>
+                </div>
+              </article>
+            </li>
+
+            <li class="static-card">
+              <article>
+                <div class="static-meta">Стиль проекта · Скоро</div>
+                <h2>NextJS Style Guide</h2>
+                <p>
+                  Правила организации Next.js-приложений, роутинга, серверных границ и проектных соглашений.
+                </p>
+              </article>
+            </li>
+
+            <li class="static-card">
+              <article>
+                <div class="static-meta">Стиль кода · Скоро</div>
+                <h2>React Style Guide</h2>
+                <p>
+                  Практики написания React-компонентов, хуков, состояния и клиентского UI-кода.
+                </p>
+              </article>
+            </li>
+
+            <li class="static-card">
+              <article>
+                <div class="static-meta">Макеты · Доступно</div>
+                <h2><a href="/figma-adaptive-standards/">Figma Adaptive Standards</a></h2>
+                <p>
+                  Стандарты и требования к подготовке адаптивных макетов в Figma: брейкпоинты,
+                  ресайз в диапазоне, Auto Layout/Constraints, компоненты, сетка, типографика, состояния UI, A11y и передача в разработку.
+                </p>
+                <div class="static-links" aria-label="LLM-артефакты Figma Adaptive Standards">
+                  <a href="/figma-adaptive-standards/llms.txt">llms.txt</a>
+                  <a href="/figma-adaptive-standards/llms-full.txt">llms-full.txt</a>
+                </div>
+              </article>
+            </li>
+          </ul>
+        </section>
+
+        <footer class="static-footer">
+          Автор документации: <a href="https://gromlab.ru/gromov">Сергей Громов</a>
+        </footer>
+      </main>
+    </div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
 </html>
--- a/package-lock.json
+++ b/package-lock.json
@@ -21,6 +21,7 @@
        "eslint-plugin-react-hooks": "^7.1.1",
        "eslint-plugin-react-refresh": "^0.5.2",
        "globals": "^17.6.0",
+        "markdown-it-task-lists": "^2.1.1",
        "tsx": "^4.21.0",
        "typescript": "~5.8.3",
        "typescript-eslint": "^8.59.2",
@@ -3862,6 +3863,13 @@
        "markdown-it": "bin/markdown-it.mjs"
      }
    },
+    "node_modules/markdown-it-task-lists": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/markdown-it-task-lists/-/markdown-it-task-lists-2.1.1.tgz",
+      "integrity": "sha512-TxFAc76Jnhb2OUu+n3yz9RMu4CwGfaT788br6HhEDlvWfdeJcLUsxk1Hgw2yJio0OXsxv7pyIPmvECY7bMbluA==",
+      "dev": true,
+      "license": "ISC"
+    },
    "node_modules/markdown-it/node_modules/entities": {
      "version": "4.5.0",
      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
--- a/package.json
+++ b/package.json
@@ -28,6 +28,7 @@
    "eslint-plugin-react-hooks": "^7.1.1",
    "eslint-plugin-react-refresh": "^0.5.2",
    "globals": "^17.6.0",
+    "markdown-it-task-lists": "^2.1.1",
    "tsx": "^4.21.0",
    "typescript": "~5.8.3",
    "typescript-eslint": "^8.59.2",
--- a/src/App.css
+++ b/src/App.css
@@ -378,6 +378,15 @@
  text-align: center;
 }

+.footer a {
+  color: var(--text-secondary);
+  text-decoration: none;
+}
+
+.footer a:hover {
+  color: var(--accent-cool);
+}
+
@media (max-width: 768px) {
  .page {
    justify-content: flex-start;
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -3,15 +3,17 @@ import { useEffect, useLayoutEffect, useState } from 'react'
 import { docs } from './config/docs.config'
 import './App.css'

-type ThemeMode = 'system' | 'dark' | 'light'
-type ResolvedTheme = Exclude<ThemeMode, 'system'>
+type ThemeMode = 'auto' | 'dark' | 'light'
+type ResolvedTheme = Exclude<ThemeMode, 'auto'>

 const DARK_THEME_QUERY = '(prefers-color-scheme: dark)'
-const THEME_STORAGE_KEY = 'all-docs-theme'
+const THEME_STORAGE_KEY = 'vitepress-theme-appearance'
+const LEGACY_THEME_STORAGE_KEY = 'all-docs-theme'
 const repositoryUrl = 'https://gromlab.ru/gromov/docs'
+const authorUrl = 'https://gromlab.ru/gromov'

 const themeOptions: ReadonlyArray<{
-  value: Exclude<ThemeMode, 'system'>
+  value: Exclude<ThemeMode, 'auto'>
  ariaLabel: string
  title: string
 }> = [
@@ -55,7 +57,7 @@ const themeIconByMode = {
 const canUseDom = () => typeof window !== 'undefined' && typeof document !== 'undefined'

 const isThemeMode = (value: string | null): value is ThemeMode => {
-  return value === 'system' || value === 'dark' || value === 'light'
+  return value === 'auto' || value === 'dark' || value === 'light'
 }

 const getSystemTheme = (): ResolvedTheme => {
@@ -65,15 +67,20 @@ const getSystemTheme = (): ResolvedTheme => {
 }

 const resolveTheme = (theme: ThemeMode): ResolvedTheme => {
-  return theme === 'system' ? getSystemTheme() : theme
+  return theme === 'auto' ? getSystemTheme() : theme
 }

 const getStoredTheme = (): ThemeMode => {
-  if (!canUseDom()) return 'dark'
+  if (!canUseDom()) return 'auto'

  const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY)
+  const legacyTheme = window.localStorage.getItem(LEGACY_THEME_STORAGE_KEY)

-  return isThemeMode(storedTheme) ? storedTheme : 'dark'
+  if (isThemeMode(storedTheme)) return storedTheme
+  if (legacyTheme === 'system') return 'auto'
+  if (isThemeMode(legacyTheme)) return legacyTheme
+
+  return 'auto'
 }

 const applyTheme = (theme: ThemeMode) => {
@@ -82,14 +89,11 @@ const applyTheme = (theme: ThemeMode) => {
  const resolvedTheme = resolveTheme(theme)

  document.documentElement.dataset.theme = theme
+  document.documentElement.classList.toggle('dark', resolvedTheme === 'dark')
  document.documentElement.style.colorScheme = resolvedTheme

-  if (theme === 'system') {
-    window.localStorage.removeItem(THEME_STORAGE_KEY)
-    return
-  }
-
  window.localStorage.setItem(THEME_STORAGE_KEY, theme)
+  window.localStorage.removeItem(LEGACY_THEME_STORAGE_KEY)
 }

 function useTheme() {
@@ -106,11 +110,12 @@ function useTheme() {

    const mediaQuery = window.matchMedia(DARK_THEME_QUERY)
    const handleSystemThemeChange = () => {
-      if (theme !== 'system') return
+      if (theme !== 'auto') return

      const nextResolvedTheme = resolveTheme(theme)

      document.documentElement.style.colorScheme = nextResolvedTheme
+      document.documentElement.classList.toggle('dark', nextResolvedTheme === 'dark')
      setResolvedTheme(nextResolvedTheme)
    }

@@ -119,13 +124,34 @@ function useTheme() {
    return () => mediaQuery.removeEventListener('change', handleSystemThemeChange)
  }, [theme])

+  useEffect(() => {
+    if (!canUseDom()) return undefined
+
+    const syncStoredTheme = () => {
+      setTheme(getStoredTheme())
+    }
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === THEME_STORAGE_KEY || event.key === LEGACY_THEME_STORAGE_KEY) {
+        syncStoredTheme()
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+    window.addEventListener('focus', syncStoredTheme)
+
+    return () => {
+      window.removeEventListener('storage', handleStorageChange)
+      window.removeEventListener('focus', syncStoredTheme)
+    }
+  }, [])
+
  return { theme, resolvedTheme, setTheme }
 }

 function ThemeToggle() {
  const { theme, resolvedTheme, setTheme } = useTheme()
-  const toggleTheme = (value: Exclude<ThemeMode, 'system'>) => {
-    setTheme(theme === value ? 'system' : value)
+  const toggleTheme = (value: Exclude<ThemeMode, 'auto'>) => {
+    setTheme(theme === value ? 'auto' : value)
  }

  return (
@@ -282,7 +308,9 @@ function App() {
        })}
      </section>

-      <footer className="footer">Рабочее пространство документаций</footer>
+      <footer className="footer">
+        Автор документации: <a href={authorUrl}>Сергей Громов</a>
+      </footer>
    </main>
  )
 }
				`@@ -0,0 +1 @@`
				`export { default } from '../../../shared/vitepress/theme';`