优化前端组件

设计与多媒体 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时应用此技能

适用于呈现交互式 UI 的任何内容:布局镶边 — Header、Footer、Sidebar、Drawer、面包屑。交互式基元 - 下拉菜单、大型菜单、弹出窗口、披露、对话框、工具提示、选项卡、列表框、组合框、语言切换器、移动菜单。可组合的视觉块,可以稍后添加子项(卡片、横幅、CTA),并且结构应保持开放以供扩展。

核心原则

每条原则在references/下都有一个主题参考,其中包含完整的细节。模块化文件布局。每个文件一个问题。子组件位于功能文件夹中与其父组件相邻的位置。数据位于同一位置。 → references/file-layout.md 默认情况下无头 UI。任何具有 Headless UI 等效项的交互式原语都使用它。不要滚动定制的打开/关闭状态机。 v2 的细节(何时使用 transition 道具、anchor 而不是手动定位、点击外部错误)很重要。 → references/headless-ui.md

快速启动

对于典型的新布局组件(抽屉、侧边栏、大型菜单等):阅读 references/file-layout.md 了解文件夹结构和 TypeScript 约定。阅读 references/headless-ui.md 选择正确的原语并避免 v2 陷阱。阅读references/accessibility.md和references/rtl.md以了解“完成”是什么样子。请参阅references/header-reference.md(CMS 驱动)和references/footer-reference.md(CMS 驱动),了解如何应用每个原则的带注释演练。

创作清单

在考虑完成任何布局/UI 组件之前:文件布局遵循 src/components/layout/<Feature>/,每个文件有一个关注点;每个交互原语都使用 Headless UI; HUI 涵盖的内容没有手动打开/关闭状态。 npm run lint干净; npx tsc --noEmit很干净。通过 Tab 键浏览每个交互式表面 - 焦点始终可见,Esc 关闭覆盖层,单击外部关闭覆盖层。

参考文献

references/file-layout.md — 文件夹结构、数据托管、服务器与客户端拆分、命名、TypeScript 约定。 references/headless-ui.md - 原始查找表,v2 细节,Popover 和 Disclosure 的带注释示例。 references/accessibility.md — A11y 清单,其中包含每个项目的基本原理和代码模式。 references/rtl.md — RTL 原则、逻辑属性映射、useDocumentLanguage 钩子、翻转什么和不翻转什么。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
设计与多媒体
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Optimizely Frontend Component Conventions

Principles for building UI components in this codebase. The Header at `src/components/blocks/Header/` and Footer at `src/components/blocks/Footer/` are the canonical reference implementations — when in doubt, mirror their structure.

## When to apply this skill

Apply to anything that renders interactive UI:

- Layout chrome — `Header`, `Footer`, `Sidebar`, `Drawer`, breadcrumbs.
- Interactive primitives — dropdowns, mega menus, popovers, disclosures, dialogs, tooltips, tabs, listboxes, comboboxes, language switchers, mobile menus.
- Composable visual blocks where children may be added later (cards, banners, CTAs) and the structure should stay open for extension.

Do **not** apply this skill to pure CMS content type definitions (use `optimizely-cms-content-types`) or deployment scripts (use `optimizely-frontend-hosting`).

## Core principles

Each principle has a topical reference under `references/` with the full detail.

1. **Modular file layout.** One concern per file. Subcomponents live next to their parent in a feature folder. Data is colocated. → `references/file-layout.md`

2. **Headless UI by default.** Any interactive primitive that has a Headless UI equivalent uses it. Don't roll bespoke open/close state machines. The v2 specifics (when to use `transition` prop, `anchor` instead of hand-positioning, the click-outside bug) matter. → `references/headless-ui.md`

3. **Accessibility is part of "done."** Native semantics first, visible focus rings on every interactive element, ARIA wired correctly on toggles, list semantics on lists. → `references/accessibility.md`

4. **RTL by default.** Use logical CSS properties so `<html dir="rtl">` flips the layout for free. Never hand-write `dir="rtl"` on individual elements. → `references/rtl.md`

5. **Open-for-extension data shapes.** Schemas should let new entries (children, items, sections) render correctly with zero component edits. The mega menu pattern is the canonical example. → `references/mega-menu-pattern.md`

6. **Server-first, client when needed.** Mark a file `"use client"` only when it actually uses hooks, refs, event handlers, or browser APIs. → `references/file-layout.md` (Server vs client section)

7. **Keep visual styling out of CMS content types.** Visual variants belong in display templates (see `optimizely-cms-content-types`), not in component prop enums.

8. **High-level architecture and patterns.** This skill captures the high-level architecture and patterns for layout components, including the rationale for the principles above and how they work together to create a scalable, maintainable codebase. → `references/layout-architecture.md`

9. **Content resolution.** — how content resolution works for layout components, including the use of `getContent` and `getLink` helpers, the `ContentResolver` component, and best practices for structuring content types to work well with these patterns. → `references/content-resolution.md`

## Quick start

For a typical new layout component (a drawer, a sidebar, a mega menu, etc.):

1. Read `references/file-layout.md` for the folder structure and TypeScript conventions.
2. Read `references/headless-ui.md` to pick the right primitive and avoid the v2 pitfalls.
3. Read `references/accessibility.md` and `references/rtl.md` to know what "done" looks like.
4. Look at `references/header-reference.md` (CMS driven) and `references/footer-reference.md` (CMS driven) for annotated walkthroughs of how each principle is applied.
5. If something breaks, check `references/troubleshooting.md` first — most frontend bugs in this codebase have already been encountered and documented.

## Authoring checklist

Before considering any layout/UI component done:

1. File layout follows `src/components/layout/<Feature>/` with one concern per file;
2. Every interactive primitive uses Headless UI; no hand-rolled open/close state for things HUI covers.
3. `npm run lint` is clean; `npx tsc --noEmit` is clean.
4. Tab through every interactive surface — focus is always visible, Esc closes overlays, click-outside closes overlays.
5. Set `<html dir="rtl">` in DevTools and confirm the layout mirrors with no overlap, no off-canvas, and direction-implying icons (arrows) flip while neutral icons (chevrons-down) stay.
6. At the `lg` breakpoint boundary, desktop and mobile UIs are mutually exclusive.
7. Adding a new entry to the data file renders correctly with zero component edits.

## References

- `references/file-layout.md` — Folder structure, data colocation, server-vs-client split, naming, TypeScript conventions.
- `references/headless-ui.md` — Primitive lookup table, v2 specifics, annotated examples for Popover and Disclosure.
- `references/accessibility.md` — A11y checklist with the rationale and code patterns for each item.
- `references/rtl.md` — RTL principles, logical-property mapping, `useDocumentLanguage` hook, what to flip and what not to.
- `references/mega-menu-pattern.md` — Schema and adaptive-layout rules; how to add a new category with zero component edits.
- `references/header-reference.md` — Annotated walkthrough of the Header (state-owning shell, Headless UI, RTL toggle, mega menu, mobile drawer); the Header refactor fix log.
- `references/footer-reference.md` — Annotated walkthrough of the Footer (server-rendered, content-info landmark, link grid, social icons); the Footer audit fix log; responsive-grid defaults.
- `references/troubleshooting.md` — Click-outside doesn't close, Tab stops invisible, span-as-link, RTL doesn't mirror, hydration warnings, file-truncation recovery.
- `references/search-reference` — Annotated walkthrough of the Search

---
> Source: [abhinavssingh/training-saas-site](https://github.com/abhinavssingh/training-saas-site) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。