---
description: app-expo 响应式设计规范（mobile-first）
globs: app-expo/src/**/*.{ts,tsx}
alwaysApply: false
---

# App Expo Responsive Design

## 断点与数据源

- 断点定义在 `app-expo/design-tokens.json` 的 `layout.breakpoints`，是唯一数据源。
- Tailwind/NativeWind 的 `sm:`、`md:` 等前缀从 design-tokens 读取，与 JS 共用同一套值。
- 当前断点（mobile-first）：`base` < 390px、`sm` ≥ 390px、`md` ≥ 768px、`lg` ≥ 1024px、`xl` ≥ 1280px、`2xl` ≥ 1536px。

## Mobile-first 原则

- 无前缀的 utility 作用于所有尺寸（最小屏优先）。
- `sm:`、`md:` 等前缀表示「该断点及以上」生效。
- 先实现 base 布局，再按 sm → md → lg 逐步增强。

```tsx
// ✅ GOOD：base 居中，sm 及以上左对齐
<View className="text-center sm:text-left" />

// ✅ GOOD：base 竖排，md 及以上横排
<View className="flex flex-col md:flex-row" />

// ❌ BAD：sm: 不是「小屏」，而是「≥390px」
<View className="sm:text-center" />
```

## 何时用 Tailwind 类 vs Hooks

- **优先用 Tailwind 类**：布局、间距、字号、显示/隐藏等用 `sm:`、`md:` 前缀即可。
- **需要 JS 分支时用 hooks**：`useBreakpointMatches`、`useBreakpointValue`、`isBreakpointUp`（来自 `@/hooks/use-breakpoint`）。

```tsx
// ✅ GOOD：纯样式用 Tailwind
<View className="flex flex-col md:flex-row gap-4 md:gap-6" />

// ✅ GOOD：逻辑分支用 hook
const { isMd } = useBreakpointMatches();
return isMd ? <TabletLayout /> : <MobileLayout />;

// ✅ GOOD：响应式取值用 useBreakpointValue
const columns = useBreakpointValue({ base: 1, sm: 2, md: 3 });
```

## 禁止

- 禁止在 `tailwind.config.js` 中硬编码断点，必须从 `design-tokens.json` 读取。
- 禁止使用 Tailwind 默认 breakpoint（640/768/1024...）覆盖设计；项目已用 390/768/1024... 适配原生设备。
- 禁止在 `layout.ts` 或业务代码中重复定义断点数值。