42 lines
3.2 KiB
Plaintext
42 lines
3.2 KiB
Plaintext
---
|
||
description: app-expo NativeWind utility-first 与 reusable 组件规范
|
||
globs: app-expo/src/**/*.{ts,tsx}
|
||
alwaysApply: false
|
||
---
|
||
|
||
# App Expo Design System
|
||
|
||
- `app-expo/design-tokens.json` 是唯一静态设计源；当前包含语义颜色、字体家族、圆角基准值，以及少量跨端共享的静态布局值（`contentMaxWidth`、`screenGutter`）。
|
||
- `@/constants/theme-bridge` 只服务于不能直接使用 NativeWind className 的运行时场景，例如旧 `Themed*` 组件、导航主题对象、第三方仅接受颜色值的 API。
|
||
- `@/constants/layout` 放 layout/app shell 常量，例如 `MaxContentWidth`、`BottomTabInset`、`ScreenGutter`；其中 `BottomTabInset` 这类环境值不要塞回 design token。
|
||
- 优先使用 NativeWind/Tailwind 原生 utility class 和默认 scale，不要先造一层新的排版或间距命名体系。
|
||
- **禁止**在 `tailwind.config.js` 的 `theme.extend.spacing` 或 `theme.extend.borderRadius` 中注入 design-tokens 的自定义语义名（如 `tight`、`relaxed`、`card`、`card-compact`）。这会与 Tailwind 默认 scale 并行，违反 utility-first 原则。间距用 `gap-2/4/6`、`p-4/6`，圆角用 `rounded-lg/xl/2xl`。
|
||
- 颜色优先使用语义 token，而不是调色板色名。常见包括：
|
||
- 背景：`bg-background`、`bg-card`、`bg-popover`、`bg-muted`、`bg-accent`、`bg-primary`、`bg-secondary`、`bg-destructive`、`bg-success`、`bg-warning`、`bg-info`
|
||
- 文字：`text-foreground`、`text-muted-foreground`、`text-card-foreground`、`text-popover-foreground`、`text-primary-foreground`、`text-secondary-foreground`、以及其他 `*-foreground`
|
||
- 边框和焦点：`border-border`、`border-input`、`ring-ring`
|
||
- 圆角优先使用 `rounded-sm/md/lg/xl`，它们由 `radius` token 派生；不要默认写 `rounded-[Npx]`。
|
||
- 字号、行高、间距优先使用默认 utility：`text-sm/base/lg/xl`、`leading-5/6/7`、`p-2/4/6`、`gap-2/4/6`、`rounded-md/lg`。
|
||
- 只有默认 scale 无法满足并且会被重复复用时，才增加少量自定义 token 或 utility，例如 `max-w-content`、`px-screen-gutter`、`border-hairline` 或少数语义颜色。
|
||
- `@/components/ui/*` 里的 reusable/CLI 生成组件默认不要改；把它们当项目内基础件。
|
||
- 如果需要定制，优先顺序是：传 `className` 覆盖、组合现有 `ui` 组件、新建业务 wrapper 组件；最后才改 `@/components/ui/*` 源码。
|
||
- 不要重新引入 `ThemedText` / `ThemedView` 这类过渡包装层；新页面统一使用 NativeWind utility class 和 `@/components/ui/*`。
|
||
- TypeScript 常量只保留 utility 不方便表达的场景；不要把常见字号、行高、间距重新包装成一套并行设计系统。
|
||
- 如果要新增主题 token，先问一句：这是不是 NativeWind 现有 utility 已经能表达？能表达就直接用 utility。
|
||
|
||
```tsx
|
||
// ✅ GOOD
|
||
<Card className="bg-card">
|
||
<Text variant="h3" className="text-foreground" />
|
||
<Text className="text-base leading-6 text-muted-foreground" />
|
||
<Button className="mt-4 rounded-lg">
|
||
<Text>Continue</Text>
|
||
</Button>
|
||
</Card>
|
||
|
||
// ❌ BAD
|
||
<View className="rounded-[18px] bg-white px-[22px] py-[13px]">
|
||
<Text className="text-[23px] leading-[31px] text-slate-900">Title</Text>
|
||
</View>
|
||
```
|