# Repository Guidelines

## 项目结构与模块组织

本仓库目前是一个用于制作 Tailwind CSS 模板页面的本地测试项目。根目录下的 `chat.md` 是简短项目说明。新增模板内容时，不要继续堆在根目录，建议按用途组织：

- `src/`：HTML 页面、组件片段或模板源文件。
- `assets/`：图片、字体和其他静态资源。
- `preview/`：独立 Nginx 静态预览配置，支持视频分段读取。
- `tests/`：检查脚本或视觉测试样例。
- `dist/` 或 `build/`：生成产物；不要手动编辑生成文件。

截图复刻和页面效果测试统一放在 `src/` 下，按创建顺序命名为 `page1.html`、`page2.html`、`page3.html`。页面专用截图和素材放在对应目录，例如 `assets/page1/`、`assets/page2/`。

后续如果加入构建工具，配置文件放在仓库根目录。

## 构建、测试与本地开发命令

当前没有包管理文件或构建脚本。只有在项目确实需要时再添加命令。后续可能使用：

默认模板预览地址为 `https://tp.supersite.host/`，页面使用 `https://tp.supersite.host/src/pageN.html`。本机检查仍可使用 `http://127.0.0.1:8088/`，由 `templates-preview.service` 托管。修改本机预览配置后，先运行 `rtk proxy /usr/sbin/nginx -t -c /home/templates/preview/nginx.conf`，通过后再运行 `rtk proxy systemctl restart templates-preview.service`。域名配置在 `preview/tp.supersite.host.conf`，修改后运行 `rtk proxy /usr/sbin/nginx -t`，通过后运行 `rtk proxy systemctl reload nginx`。

模板列表首页为自动生成的 `src/index.html`，截图存放在 `assets/gallery/`。新增或修改模板后运行 `rtk proxy node preview/build-gallery.cjs` 更新列表和首屏截图；该脚本使用本机现有 Playwright 和 Chromium，预览服务需已启动。修改首页结构请编辑生成脚本，不要直接修改生成的 HTML。

- `npm install`：在存在 `package.json` 后安装前端依赖。
- `npm run dev`：启动本地模板预览服务。
- `npm run build`：编译 Tailwind 输出到 `dist/`。
- `npm test`：在测试存在后运行自动化检查。

Agent 执行 shell 命令时遵循 `/root/.codex/RTK.md`：命令前加 `rtk`，例如 `rtk npm run build`。

## 代码风格与命名约定

优先使用简单的静态模板。页面样式只能使用 Tailwind CSS utility class，不要在 `<style>` 中定义 `.icon`、`.card`、`.nav-*` 等自定义 class，也不要把通用样式藏进自定义选择器。HTML、CSS、JSON、JavaScript 使用 2 个空格缩进。普通模板文件使用小写 kebab-case，例如 `pricing-page.html` 或 `hero-section.html`；截图复刻任务优先使用 `pageN.html`，例如 `page1.html`。

SVG 图标使用普通 inline SVG。不要使用 `<symbol>`、`<use href="#...">` 或 `id` sprite 复用。图标尺寸、颜色、描边使用 Tailwind class 或 SVG 原生属性，例如 `class="h-[18px] w-[18px] shrink-0 fill-none stroke-current stroke-[1.8]"`。

页面中不要使用 emoji、表情字符或文本箭头符号，例如 `→`、`↗`、`⌄`、星星评分、场景图标、提示符号等都要换成风格一致的 inline SVG 图标，并用 Tailwind 控制尺寸、颜色和对齐。

模板 HTML 中不要使用 `<span>` 标签。需要行内容器或徽标时，优先使用 `div`、`b`、`small`、`em`、`strong` 等合适标签，并用 Tailwind class 控制显示方式。

除正文段落外，不要使用 `<p>` 标签。导航、按钮、卡片元信息、标签、计数、徽标、图标说明等 UI 文本一律使用 `div`、`b`、`small`、`em`、`strong` 等标签承载。

下拉框不要使用浏览器默认箭头。`select` 使用 `appearance-none` 和足够右内边距（例如 `pr-9`），外层用 `relative`，右侧放 `pointer-events-none absolute right-3 top-1/2 -translate-y-1/2` 的 inline SVG chevron，避免图标贴边。

资源命名保持清晰，例如 `assets/logo-dark.svg`、`assets/dashboard-preview.png`。

## 测试规范

当前没有配置测试框架。现阶段在浏览器中手动检查移动端和桌面端宽度即可。若后续出现非平凡交互，在 `tests/` 下添加最小可用检查，并把运行命令记录到本文档。

`page11` 生成面板已有浏览器回归检查，使用本机现有 Playwright 和 Chromium（预览服务需已启动）：

```bash
rtk proxy env PLAYWRIGHT_MODULE=/tmp/codex-pw/node_modules/playwright-core CHROME_BIN=/root/.cache/ms-playwright/chromium-1200/chrome-linux64/chrome node tests/page11-generator.cjs
```

测试仅拦截本地模拟请求，不调用真实生成服务；接口约定见 `assets/page11/GENERATOR.md`。

## 提交与 Pull Request 规范

当前目录不是 Git 仓库，因此没有现有提交规范。如果后续初始化 Git，提交信息使用简短祈使句，例如 `Add pricing template`。Pull Request 应包含变更摘要、涉及的模板路径、视觉变更截图，以及执行过的构建或手动验证说明。

## 安全与配置提示

不要提交密钥、生产凭据或私有客户素材。除非仓库明确要求，否则不要把依赖目录和构建产物纳入版本控制。