优化前端组件
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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 -->
章节与文件索引
按说明文件中的顺序排列。
何时应用此技能
核心原则
快速启动
创作清单
参考文献
文件/命令 -> src/components/blocks/Header/ · src/components/blocks/Footer/ · Header · Footer · Sidebar · Drawer · optimizely-cms-content-types · optimizely-frontend-hosting
内容校验值 -> d036ae38113d
当前原文的自动摘译,尚未人工审校。
何时应用此技能
适用于呈现交互式 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钩子、翻转什么和不翻转什么。