网站开发规范

UI 组件与交互效果、TypeScript 风格、命名约定、文档 front matter 的具体规范。

UI 组件与交互效果

新增或修改网站交互效果时，优先使用 Chakra UI。先检查仓库已有封装及当前安装版本提供的组件，能满足需求时直接复用或组合，不重复手写弹层定位、焦点管理、键盘导航、外部点击关闭等通用行为，也不为同类需求另引一套 UI 库。

菜单、抽屉、对话框、标签页和折叠内容，优先使用 Menu、Drawer、Dialog、Tabs、Accordion 或 Collapsible。
悬浮说明按内容选择 Tooltip、HoverCard 或 Popover；包含链接、按钮的内容使用可交互浮层。必要信息必须支持键盘和移动端点击访问，不能只依赖 hover。
普通正文继续使用 Markdown，保留 Docusaurus 已有的提示块、代码块和标题锚点。正文需要额外交互时，在 MDX 中复用基于 Chakra 的组件；重复需求再提取轻量封装。
图表、图片预览等专业功能继续使用现有 ECharts、PhotoSwipe 等方案。简单静态排版和装饰效果可保留 CSS，不要求为迁移而重写现有页面。Chakra 无法满足需求时，说明具体限制后采用最小补充实现。
复用 src/theme/Root.tsx 的 Provider 和 src/components/ui/system.ts 的主题配置，沿用站点字体、间距及 --ifm-* 配色。新增通用主题配置集中维护，不在页面重复创建 Provider，不开启影响正文的全局样式重置。
完成后在浏览器检查桌面与移动端、浅色与深色，以及相关的 hover、焦点、选中和禁用状态。涉及弹层时检查键盘操作、关闭后的焦点恢复、滚动与边缘遮挡，并运行与改动相称的类型检查和构建。

TypeScript

严格模式。延续现有配置和主题文件风格：

2 空格缩进，保留分号。
尽量保持小函数、单一职责。
React 主题覆盖应尽量小而明确，放在 src/theme/<组件名>/ 下。

文档 front matter

每个 Markdown 文档必须保留 front matter，例如：

---
slug: /health
icon: apple-whole
description: 健康是一套长期系统，目标是在可持续前提下改善身体、情绪、关系和生活质量。
---

`slug`

文件名使用中文，slug 使用 / 开头的简短英文路径，例如 slug: /cybersecurity-law。slug 必须稳定——一旦发布不应随意变更。

`icon`

根据主体内容设置合理的 icon。图标系统使用 src/components/ItsHoverIcon/icons/ 下的 ItsHover 图标，或 src/components/ItsHoverIcon/index.tsx 中 ICON_ALIASES 已注册的别名。

新增或修改 icon 前需先确认对应图标真实存在，避免使用未注册的 Lucide 名称导致侧边栏图标缺失。

独立发布的 Markdown/MDX 页面均设置图标，包括法规、标准、面试题、诗词与每日记录。文件名以 _ 开头的引用片段不设置图标。

图标来源为 Its Hover。优先复用本地已安装图标；官网展示某个图标不代表本仓库已经安装。名称以本地文件名为准，不推测名称或强行添加 -icon 后缀。

按读者识别的主题选择图标，保持同类页面一致：

页面主题	优先图标
法规与制度正文	`file-description-icon`
标准与检查清单	`unordered-list-icon`
认证与资质	`rosette-discount-check-icon`
历史事件、每日记录与阶段复盘	`history-circle-icon`
文学原文与阅读	`book-icon`
写作规则	`pen-icon`
团队与领导力	`users-group-icon`
隐私、权限与加密	`lock-icon`
漏洞研究	`bug-icon`
评测与统计	`chart-histogram-icon`
开发与配置规则	`code-icon`

shield-check 用于防护、合规总入口和安全保证，target-icon 用于目标与实战检验；不要覆盖所有安全文章或方法文章。栏目入口可以根据主题使用更具体的图标，如跨境使用 globe-icon、基础设施使用 router-icon。

图标由人工核对其存在性、引用片段边界，以及与页面主题的一致性。

`description`（必须）

所有新文档必须在 front matter 中携带 description。用途：站点 SEO、社交分享卡片的 OG/Twitter 摘要。要求：

长度 ≤ 160 字（中文按字符计，英文按词计）。
高度概括本文的核心结论或核心问题，不复述标题。
避免「本文介绍」「本文探讨」「通过 X 阐述 Y」这类废话开头。
直接陈述价值主张，使用与正文相同的判断语气。
多个并列要点时用顿号或分号分隔，不要写成段落。

`published_at`（可选）

需要进入首页近期更新或 RSS 的内容填写首次公开发布日期：

published_at: '2026-09-16'

使用真实有效的 YYYY-MM-DD 日期。发布后保持不变，后续修改不改变首次发布日期。不要使用文件修改时间、Git 提交时间或整理日期替代首次发布日期。历史内容只有在能确认原始发表日期时才补齐；未知日期不猜测。日常记录可以使用记录日期。

最后更新时间（自动获取）

最后更新时间由 docMtimePlugin 从文件当前路径的 Git 提交记录生成 updatedAt，文章操作菜单和首页近期更新共用这份数据，不在 front matter 手工维护 updated_at。该时间表示文件发生过修改，不代表全文重新经过事实核验。缺少 Git 历史时不显示更新时间，也不使用检出或复制产生的文件时间替代。

复核日期字段 last_reviewed 已停用：新文档不填写，修改文档不更新，质量检查不再要求或校验它。旧文档中已有的字段不再被功能代码读取，可在后续编辑时删除，不将其改名为更新时间。

`image`（可选）

文档有配图时填写 image，取正文中第一张图的相对路径（相对于 static/）。无图文档不写 image，让社交分享回退到站点默认 OG 图。

`sidebar_badge: { text: '演讲' }`

带 演讲 徽标的文章属于历史快照，不修改正文。需更新观点时应复制为新文件后再编辑，原文件保留不动。

`sidebar_badge: { text: 'SKILL' }`

带 SKILL 徽标的文档是给 AI 协作助手使用的工作规则文件，统一放在 docs/05-吴飞飞/01-关于/关于FEEI.CN/。读者不必阅读，但维护者更新时需遵循本文档的全部规范。

UI 组件与交互效果​

TypeScript​

文档 front matter​

slug​

icon​

description（必须）​

published_at（可选）​

最后更新时间（自动获取）​

image（可选）​

sidebar_badge: { text: '演讲' }​

sidebar_badge: { text: 'SKILL' }​