@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-vue3-project-standard/references/vue3-project-structure.md

@@ -0,0 +1,177 @@
+# Vue 3 project structure and component standards
+
+## 项目结构
+
+以下为中大型 Vue 3 项目的业界最佳实践结构，按项目实际情况裁剪：
+
+```
+src/
+├── app/                        # 应用入口与全局配置
+│   ├── App.vue                 # 根组件
+│   ├── main.ts                 # 应用启动入口
+│   └── router.ts               # 路由实例与配置
+│
+├── pages/                      # 页面组件（与路由一一对应）
+│   ├── Dashboard/
+│   │   ├── DashboardPage.vue
+│   │   ├── components/         # 页面私有组件
+│   │   └── composables/        # 页面私有 composables
+│   ├── UserList/
+│   └── Settings/
+│
+├── layouts/                    # 布局组件
+│   ├── MainLayout.vue          # 主布局（侧边栏 + 顶栏 + 内容区）
+│   ├── AuthLayout.vue          # 登录/注册页布局
+│   └── BlankLayout.vue         # 空白布局（错误页等）
+│
+├── features/                   # 功能模块（按业务领域划分）
+│   ├── auth/
+│   │   ├── components/         # 模块组件
+│   │   ├── composables/        # 模块 composables
+│   │   ├── api.ts              # 模块 API 调用
+│   │   ├── types.ts            # 模块类型定义
+│   │   ├── constants.ts        # 模块常量
+│   │   └── index.ts            # 模块公开导出
+│   └── order/
+│
+├── components/                 # 全局共享 UI 组件
+│   ├── AppButton/
+│   │   ├── AppButton.vue
+│   │   └── __tests__/
+│   ├── AppModal/
+│   ├── AppForm/
+│   └── AppErrorBoundary/
+│
+├── composables/                # 全局共享 composables
+│   ├── useAuth.ts
+│   ├── useDebounce.ts
+│   └── useMediaQuery.ts
+│
+├── services/                   # API 基础层
+│   ├── request.ts              # Axios/fetch 实例与拦截器
+│   └── endpoints/              # API 端点定义（如按领域拆分）
+│
+├── stores/                     # Pinia 状态管理
+│   ├── authStore.ts
+│   └── uiStore.ts
+│
+├── locales/                    # 国际化语言包
+│   ├── zh-CN.json              # 中文
+│   ├── en-US.json              # 英文
+│   └── index.ts                # i18n 实例初始化（vue-i18n）
+│
+├── assets/                     # 静态资源
+│   ├── images/                 # 图片（PNG、JPG、WebP）
+│   ├── icons/                  # SVG 图标
+│   └── fonts/                  # 自定义字体
+│
+├── config/                     # 应用配置
+│   ├── env.ts                  # 环境变量类型化封装
+│   └── features.ts             # Feature Flags 管理
+│
+├── types/                      # 全局共享类型
+│   ├── api.ts                  # API 响应/请求通用类型
+│   ├── models.ts               # 业务实体类型
+│   └── global.d.ts             # 全局类型扩展（组件类型、模块声明等）
+│
+├── utils/                      # 纯工具函数
+│   ├── format.ts               # 日期、数字、货币格式化
+│   ├── validators.ts           # 表单校验规则
+│   └── storage.ts              # LocalStorage / SessionStorage 封装
+│
+├── directives/                 # 自定义指令
+│   ├── vPermission.ts          # 权限指令
+│   └── vClickOutside.ts        # 点击外部关闭
+│
+├── plugins/                    # Vue 插件注册
+│   ├── i18n.ts                 # vue-i18n 插件配置
+│   └── index.ts                # 插件统一注册入口
+│
+├── styles/                     # 全局样式与主题
+│   ├── global.css              # 全局基础样式（reset / normalize）
+│   ├── variables.css           # CSS 变量（颜色、间距、字号）
+│   ├── breakpoints.ts          # 响应式断点常量
+│   └── themes/                 # 主题定义
+│       ├── light.css           # 亮色主题变量
+│       ├── dark.css            # 暗色主题变量
+│       └── index.ts            # 主题切换逻辑
+│
+└── constants/                  # 全局常量
+    ├── routes.ts               # 路由路径常量
+    └── config.ts               # 业务常量（分页大小、超时时间等）
+```
+
+### 关键原则
+
+- `pages/` 做路由映射和布局组合，不放业务逻辑
+- `layouts/` 定义页面骨架（侧边栏、顶栏、面包屑），由路由配置的 `component` 引用
+- `features/` 按业务领域划分，模块内自包含（components + composables + api + types）
+- `components/` 仅放无业务耦合的通用组件，可跨项目复用
+- `composables/` 仅放通用逻辑（防抖、媒体查询等），业务 composables 放到对应 feature 中
+- `locales/` 存放语言包 JSON 文件，模板中使用 `$t('key')` 而非硬编码文案
+- `assets/` 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF
+- `config/` 封装环境变量和 Feature Flags，禁止组件中直接读取 `import.meta.env`
+- `styles/themes/` 通过 CSS 变量实现主题切换，组件中引用变量而非硬编码颜色
+- 每个模块通过 `index.ts` 管控公开 API，避免深层路径导入
+
+## 组件设计规范
+
+- 使用 `<script setup lang="ts">`
+- 明确使用 `defineProps` / `defineEmits` 并附带类型
+- 可复用逻辑优先提取到 composables
+- 保持 template 可读，避免过深条件嵌套
+- 优先使用计算属性，而不是重复维护状态
+- 避免构建大型单体组件；**单文件规模**见 `templates/shared/rules/fec-vue.md`「**组件文件规模**」（约 300 行内为佳，逾 500 行或复杂度过高拆子组件与 Composables）
+- 优先使用强类型的 props、emits 和暴露方法
+- 遵循仓库的文件与目录命名规范
+- 优先复用现有 UI 组件和 Token
+
+### 组件分层
+
+```
+页面组件 (Pages)          → 路由映射、布局组合
+  └── 容器组件 (Containers)  → 数据获取、状态编排
+       └── 业务组件 (Features) → 领域逻辑展示
+            └── 通用组件 (UI)   → 纯展示，无业务耦合
+```
+
+## 注释规范
+
+- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。
+- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。
+- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。
+- **公开 API**：composable 或模块的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。
+
+## TypeScript 规范
+
+通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+
+Vue 规范只补充 SFC、Props / Emits、暴露方法、Provide / Inject 和 composable 响应性类型；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+
+### Vue 3 项目补充约定
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string;
+  items: Item[];
+  loading?: boolean;
+}
+
+interface Emits {
+  (e: "select", item: Item): void;
+  (e: "delete", id: string): void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+});
+
+const emit = defineEmits<Emits>();
+</script>
+```
+
+- Props 和 Emits 使用 TypeScript interface 定义
+- 使用 `withDefaults` 设置默认值
+- `defineExpose` 暴露的方法需有类型约束
+

package/skills/fec-vue3-project-standard/references/vue3-state-api-quality.md

@@ -0,0 +1,216 @@
+# Vue 3 state, API, and quality patterns
+
+## 状态管理（Pinia）
+
+| 状态类型           | 推荐方案                      |
+| ------------------ | ----------------------------- |
+| 组件内临时 UI 状态 | `ref` / `reactive`            |
+| 跨组件共享业务状态 | Pinia store                   |
+| 服务端数据缓存     | VueQuery / 自定义 composable  |
+| URL 驱动状态       | 路由参数 / `useRoute().query` |
+| 表单状态           | VeeValidate / FormKit         |
+
+### Pinia Store 规范
+
+使用 Composition API 风格（`setup store`）：
+
+```typescript
+// stores/authStore.ts
+export const useAuthStore = defineStore("auth", () => {
+  const user = ref<User | null>(null);
+  const token = ref<string | null>(localStorage.getItem("token"));
+
+  const isLoggedIn = computed(() => !!token.value);
+
+  async function login(credentials: LoginParams) {
+    const res = await authApi.login(credentials);
+    user.value = res.user;
+    token.value = res.token;
+    localStorage.setItem("token", res.token);
+  }
+
+  function logout() {
+    user.value = null;
+    token.value = null;
+    localStorage.removeItem("token");
+  }
+
+  return { user: readonly(user), isLoggedIn, login, logout };
+});
+```
+
+### Store 原则
+
+- 每个 store 职责单一，按领域拆分
+- 对外暴露 `readonly` 的状态，通过 action 修改
+- 不要在 store 中存放 UI 临时状态（modal 开关、表单输入等）
+- 服务端数据优先用请求库管理，而非手动存入 store
+
+## API 层规范
+
+### 请求实例
+
+```typescript
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.request.use((config) => {
+  const authStore = useAuthStore();
+  if (authStore.token) {
+    config.headers.Authorization = `Bearer ${authStore.token}`;
+  }
+  return config;
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      const authStore = useAuthStore();
+      authStore.logout();
+      router.push({ name: "Login" });
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+### API 函数
+
+```typescript
+// features/user/api.ts
+export function getUserList(
+  params: UserQueryParams,
+): Promise<PageResult<User>> {
+  return request.get("/users", { params });
+}
+
+export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return request.put(`/users/${id}`, data);
+}
+```
+
+- API 函数按 feature 组织，而非全部堆在一个文件
+- 请求参数和响应都有类型约束
+- 拦截器统一处理认证、错误格式化
+
+## 错误处理
+
+### 全局错误捕获
+
+```typescript
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+  reportError(err, { component: instance?.$options.name, info });
+};
+```
+
+### 组件级错误
+
+- 使用 `onErrorCaptured` 在父组件中捕获子组件错误
+- 数据请求失败需有用户可见的提示和重试机制
+- 不要吞掉错误（空 catch 块）
+
+## 自定义指令
+
+```typescript
+// directives/vPermission.ts
+export const vPermission: Directive<HTMLElement, string> = {
+  mounted(el, binding) {
+    const authStore = useAuthStore();
+    if (!authStore.hasPermission(binding.value)) {
+      el.parentNode?.removeChild(el);
+    }
+  },
+};
+```
+
+- 指令只处理 DOM 层面的操作
+- 业务逻辑不要放在指令中
+- 需要响应式更新时实现 `updated` 钩子
+
+## 样式规范
+
+- 使用 `<style scoped>` 隔离样式
+- 深度选择器使用 `:deep()` 而非已废弃的 `::v-deep`
+- 与项目现有样式体系保持一致
+- 动态样式优先使用 `:class` / `:style` 绑定
+- 复杂主题切换使用 CSS 变量
+- 主题/全局变量通过 CSS 变量或 Token 管理
+
+## 测试规范
+
+### 必须测试
+
+- 核心交互行为（点击、输入、提交）
+- 条件渲染（loading / error / empty / data）
+- Emits 的触发和 payload
+- 关键 composables 的返回值
+- Pinia store 的 action 和 getter
+
+### 测试风格
+
+```typescript
+describe("UserForm", () => {
+  it("should emit submit with valid data", async () => {
+    const wrapper = mount(UserForm);
+
+    await wrapper.find('[data-testid="username"]').setValue("test");
+    await wrapper.find("form").trigger("submit");
+
+    expect(wrapper.emitted("submit")?.[0]).toEqual([{ username: "test" }]);
+  });
+
+  it("should show validation error on empty submit", async () => {
+    const wrapper = mount(UserForm);
+    await wrapper.find("form").trigger("submit");
+    expect(wrapper.text()).toContain("用户名不能为空");
+  });
+});
+```
+
+### Store 测试
+
+```typescript
+describe("authStore", () => {
+  beforeEach(() => setActivePinia(createPinia()));
+
+  it("should login and set user", async () => {
+    const store = useAuthStore();
+    await store.login({ username: "admin", password: "pass" });
+    expect(store.isLoggedIn).toBe(true);
+  });
+});
+```
+
+
+## 反模式
+
+- 在模板驱动组件中内联大段业务逻辑
+- 本该用 computed 却使用大范围 watcher
+- 事件 payload 不明确
+- 在纯展示组件中直接混入原始 API 调用
+- ref 和 props 没有类型约束
+- 用 `watch` + 手动赋值模拟 computed
+- 在一个组件中混入无关职责
+- 用大范围全局样式覆盖去解决局部 UI 问题
+- 将所有状态推入 Pinia store，而非就近管理
+- 在 `components/` 中放业务耦合组件
+- 直接从 feature 内部深层路径导入，绕过 `index.ts`
+
+## 输出检查清单
+
+- [ ] 文件结构与项目约定一致（pages / features / components 分离）
+- [ ] 使用 `<script setup lang="ts">`
+- [ ] Props / Emits 类型完整
+- [ ] 解释性注释是否优先使用中文且点到要害
+- [ ] 可复用逻辑已提取到 composable
+- [ ] Loading / Error / Empty 状态均已处理
+- [ ] 路由组件使用动态 import 加载
+- [ ] 状态管理方案合理（就近原则）
+- [ ] API 调用有类型约束和统一错误处理
+- [ ] 样式使用 scoped 隔离
+- [ ] 关键行为有测试覆盖

package/skills/fec-web-video-presentation/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: fec-web-video-presentation
+description: Use when turning an article, talk script, lesson, product demo, or narrated explanation into a recordable 16:9 web presentation with step-driven scenes, optional narration alignment, theme tokens, and screen-recording guidance; Chinese triggers include 网页视频, 动态演示, 口播稿转视频, 可录屏演示, 16:9 演示.
+---
+
+# 网页视频演示
+
+## Purpose
+
+把文章、口播稿、课程、产品讲解或技术分享转成可录屏的 16:9 网页演示。产物应像一个可点击推进的视频舞台：每一步承载一个口播节拍，视觉设计服务内容节奏，并能用浏览器稳定录制。
+
+## Procedure
+
+1. 判断输入形态
+   - 用户给文章或长文时，先拆成口播稿和 outline。
+   - 用户给现成口播稿时，保留原顺序，只补 outline、章节和 step。
+   - 用户只给主题但没有内容时，先要求素材、大纲或目标要点；不要替用户虚构整篇内容。
+
+2. 生成内容计划
+   - 按 [content-plan.md](references/content-plan.md) 输出 script 与 outline。
+   - script 决定讲述顺序和每个节拍；outline 决定章节、step、估时、屏幕信息和素材清单。
+   - outline 只描述内容密度和画面任务，不提前写死具体动画实现。
+
+3. 对齐演示系统
+   - 从 [theme-system.md](references/theme-system.md) 或 [starter-themes.json](data/starter-themes.json) 选择一个 starter theme，也可以按项目品牌重新定义 token。
+   - 使用 [create-video-presentation.mjs](scripts/create-video-presentation.mjs) 创建最小 Vite + React + TypeScript 演示骨架：
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs ./presentation --theme editorial-slate
+     ```
+   - 如只想预览可选主题或计划写入内容：
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --list-themes
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --dry-run ./presentation --theme editorial-slate
+     ```
+
+4. 实现章节
+   - 每章按 [chapter-craft.md](references/chapter-craft.md) 实现。
+   - 每个 step 独占舞台，屏幕只承载当前口播节拍需要用户理解的核心内容。
+   - 章节必须有可见的视觉演示、图形、布局变化、状态推进或数据/媒体呈现；不要交付纯文本幻灯片。
+   - 第一章应作为风格锚点优先完成并验收，再继续其它章节。
+
+5. 录屏和音频
+   - 使用 [recording-and-audio.md](references/recording-and-audio.md) 检查舞台比例、导航、录制模式和可选音频同步。
+   - 音频可以来自用户已有文件、宿主工具或项目自己的 TTS 流程；本技能不绑定特定 TTS 供应商。
+
+6. 交付前验证
+   - 浏览器打开演示，检查 16:9 缩放、键盘/点击推进、step 数、文本溢出、隐藏控件、控制台错误和录屏路径。
+   - 若章节数量、顺序或 step 数变化，重置本地持久化 key 或清理旧进度，避免恢复到不存在的 step。
+
+## Constraints
+
+- 不把网页视频做成普通营销落地页、静态 PPT 或长滚动文章。
+- 不复制参考项目的主题、模板章节、长提示词或脚手架实现；按当前项目生成原创骨架。
+- 不在 outline 阶段锁死每个动画名称；动画应由章节内容关系驱动。
+- 不使用假数据、假引用、假产品截图或不可检查媒体填充画面。
+- 不让控件、页码、说明文字或调试面板污染录屏画面；必要控件默认隐藏或弱化。
+- 不为音频合成引入项目外供应商约定；TTS 属于可选适配层。
+
+## Expected Output
+
+输出 script、outline、可运行的 16:9 网页演示骨架或章节实现，并说明主题、章节/step 数、录屏方式、可选音频路径和验证结果。最终演示应可通过点击或键盘稳定推进，视觉节奏贴合口播内容，且适合浏览器录屏。

package/skills/fec-web-video-presentation/data/starter-themes.json

@@ -0,0 +1,59 @@
+[
+  {
+    "id": "editorial-slate",
+    "name": "Editorial Slate",
+    "bestFor": "technical explainers, product narratives, engineering talks",
+    "tokens": {
+      "stageBg": "#f6f1e8",
+      "stageFg": "#17201b",
+      "mutedFg": "#69736d",
+      "accent": "#a83d2d",
+      "accent2": "#2b6b72",
+      "panel": "#fffaf0",
+      "line": "#d9cab8",
+      "shadow": "0 24px 80px rgba(23, 32, 27, 0.12)",
+      "fontDisplay": "Georgia, 'Times New Roman', serif",
+      "fontBody": "Inter, ui-sans-serif, system-ui, sans-serif",
+      "radius": "10px",
+      "stepDuration": "4200ms"
+    }
+  },
+  {
+    "id": "console-amber",
+    "name": "Console Amber",
+    "bestFor": "debug stories, infrastructure demos, security walkthroughs",
+    "tokens": {
+      "stageBg": "#10110f",
+      "stageFg": "#f5ead2",
+      "mutedFg": "#a99b80",
+      "accent": "#ffb84d",
+      "accent2": "#6bd5c8",
+      "panel": "#191a16",
+      "line": "#3c3529",
+      "shadow": "0 28px 90px rgba(0, 0, 0, 0.38)",
+      "fontDisplay": "ui-monospace, SFMono-Regular, Consolas, monospace",
+      "fontBody": "Inter, ui-sans-serif, system-ui, sans-serif",
+      "radius": "6px",
+      "stepDuration": "3800ms"
+    }
+  },
+  {
+    "id": "studio-paper",
+    "name": "Studio Paper",
+    "bestFor": "design reviews, lessons, product tours, calm keynote chapters",
+    "tokens": {
+      "stageBg": "#fbfbf7",
+      "stageFg": "#24211d",
+      "mutedFg": "#6f6a62",
+      "accent": "#2457a6",
+      "accent2": "#d95f37",
+      "panel": "#ffffff",
+      "line": "#dedbd2",
+      "shadow": "0 18px 64px rgba(36, 33, 29, 0.1)",
+      "fontDisplay": "Aptos Display, Avenir Next, ui-sans-serif, system-ui, sans-serif",
+      "fontBody": "Aptos, Avenir Next, ui-sans-serif, system-ui, sans-serif",
+      "radius": "14px",
+      "stepDuration": "4000ms"
+    }
+  }
+]

package/skills/fec-web-video-presentation/references/chapter-craft.md

@@ -0,0 +1,37 @@
+# Chapter Craft
+
+## Stage Rules
+
+- Use a fixed 16:9 stage, normally 1920 by 1080, scaled to the viewport.
+- A chapter is a pure function of the current step.
+- One step should focus on one visual idea.
+- Lists reveal one meaningful item at a time.
+- Use hidden or low-emphasis controls so the recording surface stays clean.
+- Keep large text readable when screen-recorded and compressed.
+
+## Visual Decisions
+
+Before implementing a chapter, answer:
+
+- What is the relationship between this step and the previous step: contrast, reveal, zoom, sequence, proof, consequence, or recap?
+- What should the viewer remember after this step?
+- Which source detail makes the screen more specific than a generic slide?
+- Is this a diagram, object, quote, metric, timeline, interface state, or spatial metaphor?
+- What can move because the content itself changes, rather than because everything needs an entrance animation?
+
+## Anti-Patterns
+
+- Synchronized stagger of many bullets when the narration discusses them one by one.
+- Purple gradient backgrounds, floating decoration, or generic cards that do not explain the content.
+- Fake dashboards, fake screenshots, fake citations, or invented metrics.
+- Tiny body text that looks fine in a browser but fails in recorded video.
+- Persistent chrome, large page numbers, or visible instructions in the recording frame.
+
+## Completion Check
+
+- Every step renders a complete screen.
+- Text fits at the target stage size.
+- The chapter still makes sense if the recording pauses on any step.
+- Visual state follows narration order.
+- Any media used is local, real, generated for the task, or clearly marked as a placeholder.
+- Keyboard and click navigation still work after the chapter is registered.

package/skills/fec-web-video-presentation/references/content-plan.md

@@ -0,0 +1,38 @@
+# Content Plan
+
+## Script
+
+Use the same language as the source material unless the user asks otherwise. Convert written text into spoken wording, but keep the author's claims, order, names, and important numbers intact.
+
+For every script:
+
+- Keep one idea per beat.
+- Remove footnote-like detours unless they are central to the story.
+- Mark uncertain facts instead of smoothing them into confident claims.
+- Keep technical names exact.
+- Prefer short sentences that can be spoken without rereading.
+
+## Outline
+
+The outline is the implementation contract for the web presentation.
+
+Include:
+
+- Title and intended audience.
+- Total target duration.
+- Chapters with stable ids.
+- Step count per chapter.
+- One screen task per step.
+- Content pool per chapter: facts, numbers, quotes, examples, media, diagrams, or UI states available for visuals.
+- Asset list with owner, path, missing status, and replacement strategy.
+
+Avoid:
+
+- Naming concrete animations too early.
+- Specifying CSS implementation details.
+- Stuffing several list items into one step when they need separate attention.
+- Adding unsupported claims just to make a scene feel full.
+
+## Acceptance
+
+A content plan is ready when another implementer can build the presentation without deciding what each chapter says, what each step reveals, or which source facts are available for visuals.

package/skills/fec-web-video-presentation/references/recording-and-audio.md

@@ -0,0 +1,33 @@
+# Recording And Audio
+
+## Recording Modes
+
+Manual mode:
+
+- Click, Space, ArrowRight, or PageDown advances one step.
+- ArrowLeft or PageUp goes back.
+- Best when a human narrator is recording live.
+
+Auto mode:
+
+- Uses per-step durations from the project data.
+- Best when narration audio is already aligned or when making a clean screen capture.
+
+## Recording Checklist
+
+- Browser console has no errors.
+- Stage is centered and scaled without distortion.
+- No horizontal or vertical scrollbars appear inside the capture frame.
+- Controls are hidden unless hovered or focused.
+- Current step persists only when helpful; reset it after changing chapter order or step count.
+- Record a 10 second sample before doing the full take.
+
+## Audio Policy
+
+Audio is optional. A project may use:
+
+- Existing narration files from the user.
+- Host-native TTS or voiceover tools.
+- A project-owned TTS pipeline.
+
+Keep audio alignment provider-neutral. Store segment text and file paths in project data, but do not encode a vendor-specific API contract into the skill.

package/skills/fec-web-video-presentation/references/theme-system.md

@@ -0,0 +1,36 @@
+# Theme System
+
+Themes are starting points, not templates. A theme defines the visual climate of the recording surface while leaving chapters free to create content-specific layouts.
+
+## Token Roles
+
+Use semantic CSS variables:
+
+- `--stage-bg`
+- `--stage-fg`
+- `--muted-fg`
+- `--accent`
+- `--accent-2`
+- `--panel`
+- `--line`
+- `--shadow`
+- `--font-display`
+- `--font-body`
+- `--radius`
+- `--step-duration`
+
+## Starter Theme Policy
+
+The bundled starter themes are intentionally few:
+
+- Use them to create a runnable skeleton.
+- Replace colors and type choices when a real brand or product context exists.
+- Do not let all chapters become identical; keep typography and color coherent while varying layout and visual devices per chapter.
+
+## Custom Theme Checklist
+
+- Contrast passes for recorded text.
+- Accent colors have different semantic jobs.
+- Background supports compression without muddy gradients.
+- Typography remains readable at 1080p and in lower-resolution reuploads.
+- Motion can be reduced without destroying meaning.