rn-agent-kit 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +291 -2
- package/dist/cli.js +2916 -0
- package/dist/cli.js.map +1 -0
- package/dist/scripts/figma-tokens.js +1284 -0
- package/dist/scripts/figma-tokens.js.map +1 -0
- package/dist/scripts/validate-jira-tickets.js +169 -0
- package/dist/scripts/validate-jira-tickets.js.map +1 -0
- package/package.json +66 -4
- package/skills/expo-cli/SKILL.md +213 -0
- package/skills/figma-to-tokens/SKILL.md +288 -0
- package/skills/github-actions-ci/SKILL.md +124 -0
- package/skills/maestro-e2e/SKILL.md +256 -0
- package/skills/prd-to-jira/SKILL.md +237 -0
- package/skills/rn-architecture/SKILL.md +207 -0
- package/skills/rn-native-android-ios/SKILL.md +195 -0
- package/skills/rn-sdk-integrations/SKILL.md +274 -0
- package/skills/rn-typescript-react/SKILL.md +247 -0
- package/skills/ticket-to-code/SKILL.md +192 -0
- package/templates/config/rn-agent-kit.json +4 -0
- package/templates/eslint/eslint.config.snippet.mjs +16 -0
- package/templates/eslint/rn-agent-kit-rules.cjs +137 -0
- package/templates/jira-ticket.md +78 -0
- package/templates/maestro/smoke.yaml +4 -0
- package/templates/scaffold/.husky/commit-msg +4 -0
- package/templates/scaffold/.husky/pre-commit +4 -0
- package/templates/scaffold/.prettierignore +6 -0
- package/templates/scaffold/.prettierrc +6 -0
- package/templates/scaffold/commitlint.config.cjs +4 -0
- package/templates/scaffold/eslint.config.js +22 -0
- package/templates/scaffold/jest.config.cjs +9 -0
- package/templates/scaffold/tsconfig.json +13 -0
- package/templates/workflows/ci.yml +120 -0
- package/templates/workflows/e2e-android.yml +158 -0
- package/templates/workflows/e2e-ios.yml +134 -0
- package/templates/workflows/eas-build.yml +94 -0
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: expo-cli
|
|
3
|
+
description: >-
|
|
4
|
+
Expo workflow guidance: when to use Expo, expo-router, prebuild, config
|
|
5
|
+
plugins, EAS Build/Submit/Update, app.config.ts env variants, dev client,
|
|
6
|
+
common errors. Use when starting or migrating an Expo app, configuring EAS,
|
|
7
|
+
writing app.config, adding native modules, or debugging prebuild/dev-client.
|
|
8
|
+
globs: "**/{app,App}.{tsx,ts,jsx,js},**/app.config.*,**/app.json,**/eas.json,**/.eas/**"
|
|
9
|
+
alwaysApply: false
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# expo-cli
|
|
13
|
+
|
|
14
|
+
Follow **Expo docs** (current SDK), **Expo Router**, **EAS Build / Submit / Update**, and **Config plugins**. Prefer the **Expo CNG** (Continuous Native Generation) workflow: treat `android/` / `ios/` as **generated** unless you eject to a long-lived bare fork.
|
|
15
|
+
|
|
16
|
+
## When to use Expo
|
|
17
|
+
|
|
18
|
+
| Choose Expo when | Prefer bare RN CLI when |
|
|
19
|
+
| ------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
20
|
+
| You want OTA updates, EAS, and fast native integration via config plugins | You already maintain large custom native trees outside Expo |
|
|
21
|
+
| Most needs are covered by Expo SDK + config plugins | You must vendor native code Expo cannot generate |
|
|
22
|
+
| Greenfield app | Legacy native app with no migration plan |
|
|
23
|
+
|
|
24
|
+
Default recommendation: **Expo + prebuild + Dev Client + EAS**, not Classic “Expo Go only” for production apps with custom native code.
|
|
25
|
+
|
|
26
|
+
## Expo Router
|
|
27
|
+
|
|
28
|
+
Cite **Expo Router docs**.
|
|
29
|
+
|
|
30
|
+
- File-based routes in `app/`.
|
|
31
|
+
- Use layouts `_layout.tsx`, groups `(auth)`, `(tabs)`.
|
|
32
|
+
- Typed routes: enable experiments / typedRoutes in `app.json` per current SDK docs.
|
|
33
|
+
- Prefer `router.push` / `Link` over imperative React Navigation unless you need nested custom navigators.
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
// ✅ Good
|
|
37
|
+
import { Stack } from "expo-router";
|
|
38
|
+
export default function Layout() {
|
|
39
|
+
return <Stack screenOptions={{ headerShown: false }} />;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// ❌ Bad — duplicate navigation trees fighting Expo Router
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Deep links: configure `scheme` in `app.config.ts` and use Expo Linking helpers (**Expo — Linking**).
|
|
46
|
+
|
|
47
|
+
## Prebuild (CNG)
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
npx expo prebuild
|
|
51
|
+
npx expo prebuild --clean # regenerate native projects
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Rules**
|
|
55
|
+
|
|
56
|
+
- Source of truth: `app.config.ts` + config plugins + `package.json` native deps.
|
|
57
|
+
- **Never hand-edit** generated `android/` / `ios/` in a managed CNG repo unless you have committed them as a bare fork and accept merge pain.
|
|
58
|
+
- After adding a native module: install → add config plugin if required → `prebuild` → run via Dev Client.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
// ✅ Good — customize via config
|
|
62
|
+
export default {
|
|
63
|
+
expo: {
|
|
64
|
+
plugins: [["expo-build-properties", { ios: { deploymentTarget: "15.1" } }]],
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
// ❌ Bad — edit Podfile by hand every week in a CNG project
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Config plugins
|
|
72
|
+
|
|
73
|
+
- Prefer official plugins from Expo modules and well-maintained libraries.
|
|
74
|
+
- Keep plugins in `app.config.ts` (typed) not only `app.json`.
|
|
75
|
+
- Order can matter (auth, notifications, build-properties)—follow each library’s Expo install guide.
|
|
76
|
+
- Local plugins: `plugins/withMyMod.js` + export from config.
|
|
77
|
+
|
|
78
|
+
## EAS Build / Submit / Update
|
|
79
|
+
|
|
80
|
+
Cite **EAS Build**, **EAS Submit**, **EAS Update**.
|
|
81
|
+
|
|
82
|
+
### eas.json (sketch)
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"cli": { "version": ">= 16.0.0", "appVersionSource": "remote" },
|
|
87
|
+
"build": {
|
|
88
|
+
"development": {
|
|
89
|
+
"developmentClient": true,
|
|
90
|
+
"distribution": "internal",
|
|
91
|
+
"channel": "development"
|
|
92
|
+
},
|
|
93
|
+
"staging": {
|
|
94
|
+
"distribution": "internal",
|
|
95
|
+
"channel": "staging",
|
|
96
|
+
"env": { "APP_ENV": "staging" }
|
|
97
|
+
},
|
|
98
|
+
"production": {
|
|
99
|
+
"channel": "production",
|
|
100
|
+
"env": { "APP_ENV": "production" }
|
|
101
|
+
}
|
|
102
|
+
},
|
|
103
|
+
"submit": {
|
|
104
|
+
"production": {}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
eas build --profile development --platform ios
|
|
111
|
+
eas build --profile production --platform all
|
|
112
|
+
eas submit --platform ios
|
|
113
|
+
eas update --channel staging --message "fix checkout"
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Rules**
|
|
117
|
+
|
|
118
|
+
- Match **update channels** to build profiles.
|
|
119
|
+
- Native-breaking changes require a **new binary**, not only `eas update`.
|
|
120
|
+
- Use `runtimeVersion` policy (`appVersion` or fingerprint) per **EAS Update — Runtime versions**.
|
|
121
|
+
|
|
122
|
+
## app.config.ts + env variants
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
// app.config.ts
|
|
126
|
+
import type { ExpoConfig, ConfigContext } from "expo/config";
|
|
127
|
+
|
|
128
|
+
const APP_ENV = process.env.APP_ENV ?? "development";
|
|
129
|
+
|
|
130
|
+
const extras = {
|
|
131
|
+
development: { apiUrl: "https://dev.api.example.com", appEnv: "development" },
|
|
132
|
+
staging: { apiUrl: "https://staging.api.example.com", appEnv: "staging" },
|
|
133
|
+
production: { apiUrl: "https://api.example.com", appEnv: "production" },
|
|
134
|
+
} as const;
|
|
135
|
+
|
|
136
|
+
type AppEnv = keyof typeof extras;
|
|
137
|
+
|
|
138
|
+
export default ({ config }: ConfigContext): ExpoConfig => {
|
|
139
|
+
const env = (APP_ENV in extras ? APP_ENV : "development") as AppEnv;
|
|
140
|
+
const isProd = env === "production";
|
|
141
|
+
|
|
142
|
+
return {
|
|
143
|
+
...config,
|
|
144
|
+
name: isProd ? "MyApp" : `MyApp (${env})`,
|
|
145
|
+
slug: "my-app",
|
|
146
|
+
scheme: "myapp",
|
|
147
|
+
ios: {
|
|
148
|
+
bundleIdentifier: isProd ? "com.example.myapp" : `com.example.myapp.${env}`,
|
|
149
|
+
},
|
|
150
|
+
android: {
|
|
151
|
+
package: isProd ? "com.example.myapp" : `com.example.myapp.${env}`,
|
|
152
|
+
},
|
|
153
|
+
extra: extras[env],
|
|
154
|
+
updates: { url: "https://u.expo.dev/<project-id>" },
|
|
155
|
+
runtimeVersion: { policy: "appVersion" },
|
|
156
|
+
};
|
|
157
|
+
};
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
// ✅ Good — read via expo-constants
|
|
162
|
+
import Constants from "expo-constants";
|
|
163
|
+
export const apiUrl = Constants.expoConfig?.extra?.apiUrl as string;
|
|
164
|
+
|
|
165
|
+
// ❌ Bad — assume process.env.API_URL exists on device without babel plugin / extra
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Use distinct **bundle IDs / applicationIds** per env so staging doesn’t clobber prod on devices.
|
|
169
|
+
|
|
170
|
+
## Dev Client
|
|
171
|
+
|
|
172
|
+
Cite **Expo Dev Clients**.
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
npx expo install expo-dev-client
|
|
176
|
+
eas build --profile development
|
|
177
|
+
npx expo start --dev-client
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
- Use Dev Client when you need custom native code (not available in Expo Go).
|
|
181
|
+
- Expo Go is fine for prototypes with SDK-only APIs.
|
|
182
|
+
|
|
183
|
+
## Common errors and fixes
|
|
184
|
+
|
|
185
|
+
| Symptom | Likely cause | Fix |
|
|
186
|
+
| ---------------------------------------- | --------------------------------- | -------------------------------------------- |
|
|
187
|
+
| “Unable to resolve module” after install | Metro cache / wrong node | `npx expo start -c`; verify `package.json` |
|
|
188
|
+
| Native module null / not found | Binary outdated vs JS | Rebuild Dev Client / EAS binary |
|
|
189
|
+
| Config plugin not applied | Edited native without prebuild | `npx expo prebuild --clean` |
|
|
190
|
+
| OTA “update ignored” | runtimeVersion mismatch | Align policy; ship new binary |
|
|
191
|
+
| Push / permissions missing | Missing plugin usage | Add plugin; rebuild |
|
|
192
|
+
| Duplicate symbols / Pod errors | Manual Podfile drift | Regenerate via prebuild; don’t mix workflows |
|
|
193
|
+
| Wrong env API URL | `APP_ENV` not passed to EAS | Set `env` in `eas.json` profile |
|
|
194
|
+
| Scheme / deep link fails | Missing `scheme` / intent filters | Set in app config; rebuild |
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
# ✅ Good hygiene
|
|
198
|
+
npx expo-doctor
|
|
199
|
+
npx expo install --fix # align versions to SDK
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Common mistakes
|
|
203
|
+
|
|
204
|
+
1. Hand-editing `ios/` / `android/` in a CNG project, then losing changes on `--clean`.
|
|
205
|
+
2. Shipping custom native deps but still trying to run in **Expo Go**.
|
|
206
|
+
3. Using `eas update` for native/SDK upgrades (needs new binary).
|
|
207
|
+
4. Same bundle identifier for dev/staging/prod.
|
|
208
|
+
5. Putting secrets in `extra` that shouldn’t ship in the client.
|
|
209
|
+
6. Forgetting config plugins for notifications, Google Sign-In, etc.
|
|
210
|
+
7. Pinning random Expo package versions instead of `npx expo install`.
|
|
211
|
+
8. Ignoring `expo-doctor` and SDK compatibility tables.
|
|
212
|
+
9. Misaligned EAS **channel** vs who receives updates.
|
|
213
|
+
10. Copy-pasting outdated `app.json` keys from old SDK blog posts—always check current **Expo docs**.
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: figma-to-tokens
|
|
3
|
+
description: Extract design tokens (colors, typography, spacing, radius, shadows, light/dark modes) from a Figma file URL or a Google Stitch design and generate a typed React Native theme. Use when the user shares a Figma/Stitch link, asks to "sync/update/extract design tokens", "set up the theme", "match the design system", or when design/tokens.json is missing or stale. Also use before prd-to-jira. Never hand-write token files; always run the script.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# figma-to-tokens
|
|
7
|
+
|
|
8
|
+
Turns a design source into **one source of truth** and a typed theme, deterministically.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Figma / Stitch ──(agent + MCP)──▶ design/source-snapshot.json
|
|
12
|
+
│ npx rn-agent-kit tokens build (deterministic script)
|
|
13
|
+
▼
|
|
14
|
+
design/tokens.json (W3C DTCG) ──▶ src/shared/theme/tokens.ts (light/dark, typed)
|
|
15
|
+
design/tokens-report.md ──▶ what a human must fix in Figma/Stitch + what changed
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
**Division of labour (important):** you (the agent) only _collect_ raw values into the snapshot.
|
|
19
|
+
The script does ALL naming, alias handling, conversion, diffing and code generation. Never write
|
|
20
|
+
`tokens.json` or `tokens.ts` by hand, and never "improve" generated output; fix the source and re-run.
|
|
21
|
+
|
|
22
|
+
## Hard rules
|
|
23
|
+
|
|
24
|
+
1. Never edit `design/tokens.json`, `src/shared/theme/tokens.ts` or `design/tokens-report.md` manually. They are generated.
|
|
25
|
+
2. Never invent a token. If a value is not in the design source, leave it out. The report will flag the gap.
|
|
26
|
+
3. Components use theme tokens only: no hex/rgb colors, no font-family strings, no magic spacing/radius/font-size numbers (see "Using tokens").
|
|
27
|
+
4. Do not guess dark-mode values. Dark values must come from the source (a Dark mode, or a dark palette).
|
|
28
|
+
5. If the report has `error` items, tell the user and stop before building screens that depend on them.
|
|
29
|
+
6. Never put the Figma token into any file. It lives in the `FIGMA_TOKEN` env var only.
|
|
30
|
+
|
|
31
|
+
## Step 0: Pre-flight
|
|
32
|
+
|
|
33
|
+
- Is there a Figma file URL or a Stitch design? If neither, ask the user for one.
|
|
34
|
+
- Does `design/tokens.json` already exist? Then this is a **re-run**: the script will diff for you.
|
|
35
|
+
- Is `package.json` script `"tokens": "rn-agent-kit tokens"` present? If not, use `npx rn-agent-kit tokens <cmd>`.
|
|
36
|
+
|
|
37
|
+
## Step 1A: Collect from Figma (MCP)
|
|
38
|
+
|
|
39
|
+
Tool names depend on the installed Figma MCP version; use whichever tools return **variables**, **styles** and **node metadata**
|
|
40
|
+
(typically `get_variable_defs`, `get_metadata`, `get_design_context`). If no Figma MCP is configured, stop and tell the user to run `rn-agent-kit doctor`.
|
|
41
|
+
|
|
42
|
+
Collect in this order and write everything into `design/source-snapshot.json`:
|
|
43
|
+
|
|
44
|
+
1. **Variables.** Run the variables tool on the file's top-level frames (every page's main frames), then union the results.
|
|
45
|
+
- If you can obtain the full variables structure (collections + modes + aliases), put it in `variables` (shape below).
|
|
46
|
+
- Otherwise, store the flat result of `get_variable_defs` in `flatVariables` (`{ "color/primary/500": "#3B82F6", ... }`).
|
|
47
|
+
2. **Dark mode.** `get_variable_defs` returns values for the mode applied to the node. To capture dark values, use a frame that has
|
|
48
|
+
Dark mode applied (ask the user to duplicate one key frame in Dark mode if none exists) and store that result in `flatVariablesDark`
|
|
49
|
+
with the same names. Do NOT approximate dark colors.
|
|
50
|
+
3. **Text styles** → `textStyles[]`, **effect styles** → `effectStyles[]`, **paint/color styles** → `colorStyles[]`.
|
|
51
|
+
- `lineHeightPx` / `letterSpacingPx` in px; if Figma gives percent use `lineHeightPercent` / `letterSpacingPercent`.
|
|
52
|
+
- Only visible `DROP_SHADOW` layers become shadows (React Native has no inner shadow).
|
|
53
|
+
4. Record `fileUrl`.
|
|
54
|
+
|
|
55
|
+
Optional shortcut when the user has a Figma token: `FIGMA_TOKEN=... npx rn-agent-kit tokens fetch --url <figma-url>`.
|
|
56
|
+
Limits: the Variables REST API needs a Figma **Enterprise** plan (without it you get styles only; use the MCP path for variables).
|
|
57
|
+
|
|
58
|
+
## Step 1B: Collect from Google Stitch
|
|
59
|
+
|
|
60
|
+
Stitch features and export formats change quickly. Use whatever your Stitch/Stitch-MCP access provides; the most reliable input is the
|
|
61
|
+
**HTML + Tailwind export**, whose `tailwind.config` contains `theme.extend`.
|
|
62
|
+
|
|
63
|
+
1. Open the exported HTML, find the Tailwind config object, and copy `colors`, `spacing`, `borderRadius`, `fontFamily`, `fontSize`, `boxShadow` into `snapshot.tailwind`.
|
|
64
|
+
2. If a dark variant of the design exists, copy its palette into `tailwind.darkColors` (same keys as `colors`).
|
|
65
|
+
3. Use only hex or `rgb()/rgba()` colors. `hsl()`, `oklch()` and CSS variables are reported and skipped.
|
|
66
|
+
4. Stitch has no text styles, so you get `font-size.*`, `line-height.*`, `font-family.*` tokens, not `typography.*`.
|
|
67
|
+
If the project needs full text styles, ask the user to define them in Figma, or add them to the snapshot as `textStyles` manually from the PRD.
|
|
68
|
+
5. You may combine sources: `source: "mixed"` with `variables` (Figma) and `tailwind` (Stitch). On a name collision, the script keeps the first and reports an error.
|
|
69
|
+
|
|
70
|
+
## Snapshot format
|
|
71
|
+
|
|
72
|
+
```jsonc
|
|
73
|
+
{
|
|
74
|
+
"source": "figma", // "figma" | "stitch" | "mixed"
|
|
75
|
+
"fileUrl": "https://www.figma.com/design/AbC123/App",
|
|
76
|
+
"variables": {
|
|
77
|
+
// optional; same shape as Figma REST `meta`
|
|
78
|
+
"variables": {
|
|
79
|
+
"v1": {
|
|
80
|
+
"id": "v1",
|
|
81
|
+
"name": "color/primary/500",
|
|
82
|
+
"resolvedType": "COLOR",
|
|
83
|
+
"variableCollectionId": "c1",
|
|
84
|
+
"valuesByMode": { "m1": { "r": 0.23, "g": 0.51, "b": 0.96, "a": 1 } },
|
|
85
|
+
},
|
|
86
|
+
"s1": {
|
|
87
|
+
"id": "s1",
|
|
88
|
+
"name": "color/background/default",
|
|
89
|
+
"resolvedType": "COLOR",
|
|
90
|
+
"variableCollectionId": "c2",
|
|
91
|
+
"valuesByMode": {
|
|
92
|
+
"m2": { "type": "VARIABLE_ALIAS", "id": "v3" },
|
|
93
|
+
"m3": { "type": "VARIABLE_ALIAS", "id": "v4" },
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
"variableCollections": {
|
|
98
|
+
"c2": {
|
|
99
|
+
"id": "c2",
|
|
100
|
+
"name": "Semantic",
|
|
101
|
+
"defaultModeId": "m2",
|
|
102
|
+
"modes": [
|
|
103
|
+
{ "modeId": "m2", "name": "Light" },
|
|
104
|
+
{ "modeId": "m3", "name": "Dark" },
|
|
105
|
+
],
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
},
|
|
109
|
+
"flatVariables": { "color/primary/500": "#3B82F6", "spacing/md": 16 }, // fallback (single mode)
|
|
110
|
+
"flatVariablesDark": { "color/primary/500": "#60A5FA" }, // same names, Dark applied
|
|
111
|
+
"textStyles": [
|
|
112
|
+
{
|
|
113
|
+
"name": "Heading/H1",
|
|
114
|
+
"fontFamily": "Inter",
|
|
115
|
+
"fontStyle": "Bold",
|
|
116
|
+
"fontSize": 32,
|
|
117
|
+
"lineHeightPx": 40,
|
|
118
|
+
},
|
|
119
|
+
],
|
|
120
|
+
"effectStyles": [
|
|
121
|
+
{
|
|
122
|
+
"name": "Elevation/md",
|
|
123
|
+
"effects": [
|
|
124
|
+
{
|
|
125
|
+
"type": "DROP_SHADOW",
|
|
126
|
+
"visible": true,
|
|
127
|
+
"color": { "r": 0, "g": 0, "b": 0, "a": 0.1 },
|
|
128
|
+
"offset": { "x": 0, "y": 4 },
|
|
129
|
+
"radius": 8,
|
|
130
|
+
"spread": 0,
|
|
131
|
+
},
|
|
132
|
+
],
|
|
133
|
+
},
|
|
134
|
+
],
|
|
135
|
+
"colorStyles": [{ "name": "Brand/Primary", "color": { "r": 1, "g": 0, "b": 0, "a": 1 } }],
|
|
136
|
+
"tailwind": {
|
|
137
|
+
"colors": {},
|
|
138
|
+
"darkColors": {},
|
|
139
|
+
"spacing": {},
|
|
140
|
+
"borderRadius": {},
|
|
141
|
+
"fontFamily": {},
|
|
142
|
+
"fontSize": {},
|
|
143
|
+
"boxShadow": {},
|
|
144
|
+
},
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Colors are Figma-style floats `0..1` in `variables`/styles, and CSS strings in `flatVariables`/`tailwind`.
|
|
149
|
+
Use at least one of `variables`, `flatVariables`, `colorStyles`, `textStyles`, `effectStyles`, `tailwind`.
|
|
150
|
+
|
|
151
|
+
## Step 2: Build
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npx rn-agent-kit tokens build # writes tokens.json, tokens.ts, tokens-report.md (+ ThemeProvider.tsx once)
|
|
155
|
+
npx rn-agent-kit tokens build --strict # exit 1 if the report contains errors (use in CI/agent loops)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Then **read `design/tokens-report.md`** and act on it:
|
|
159
|
+
|
|
160
|
+
| Report item | What you do |
|
|
161
|
+
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
162
|
+
| 🔴 error (`unresolved-alias`, `name-collision`) | Tell the user exactly what to change in Figma/Stitch. Do not work around it in code. |
|
|
163
|
+
| 🟡 `unnamed-token` | List the placeholder names (e.g. "Color 1") and ask the user to rename them semantically. |
|
|
164
|
+
| 🟡 `missing-dark-mode` | Tell the user dark mode will mirror light until a Dark mode exists in the design. |
|
|
165
|
+
| 🟡 `missing-category` | Spacing/radius/typography missing: ask the user to add them as variables/styles; do not invent a scale. |
|
|
166
|
+
| 🟡 `unsupported-effect` | Inner shadows/blur are not supported by RN; propose a design alternative. |
|
|
167
|
+
| 🔵 `font-loading` | Make sure each font family/weight is loaded (expo-font `useFonts` or native linking) under the exact name used in the theme. |
|
|
168
|
+
| 🔵 `single-mode-source` | Explain how to capture Dark values (Step 1A.2 / 1B.2). |
|
|
169
|
+
|
|
170
|
+
Summarize the report to the user in a few lines: counts, top issues, and the "Changes since last run" section.
|
|
171
|
+
|
|
172
|
+
## Step 3: Re-runs and diffs
|
|
173
|
+
|
|
174
|
+
- Re-run Step 1 → `build`. The script diffs against the previous `tokens.json` and lists **Added / Removed / Changed** in the report.
|
|
175
|
+
- **Removed or renamed tokens break code.** Run `npx tsc --noEmit` right after `build`. Every compile error pointing at `theme.*` is a usage you must migrate.
|
|
176
|
+
Do not keep a stale alias to hide the error.
|
|
177
|
+
- Commit `design/source-snapshot.json`, `design/tokens.json`, `design/tokens-report.md` and `tokens.ts` together, in one commit: `chore(design): sync tokens`.
|
|
178
|
+
- Hand-edited `tokens.json`? Run `npx rn-agent-kit tokens generate` to rebuild only `tokens.ts`. The next `build` from the snapshot will overwrite
|
|
179
|
+
hand edits, so put real fixes in the design file.
|
|
180
|
+
|
|
181
|
+
## Token model
|
|
182
|
+
|
|
183
|
+
DTCG file (`design/tokens.json`): `$type`, `$value`, `$description`, aliases like `"{color.primary.500}"`. The **light/default** value is `$value`;
|
|
184
|
+
other modes live in `$extensions.mode`:
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"color": {
|
|
189
|
+
"$type": "color",
|
|
190
|
+
"primary": { "500": { "$value": "#3b82f6" } },
|
|
191
|
+
"background": {
|
|
192
|
+
"default": {
|
|
193
|
+
"$value": "{color.neutral.50}",
|
|
194
|
+
"$description": "Screen background",
|
|
195
|
+
"$extensions": { "mode": { "dark": "{color.neutral.900}" } }
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Naming normalization: names are split on `/`, lower-cased, non-alphanumerics become `-` (`Color/On Surface` → `color.on-surface`).
|
|
203
|
+
Color variables always land under `color.*`.
|
|
204
|
+
|
|
205
|
+
Conversion to React Native values (all done by the script):
|
|
206
|
+
|
|
207
|
+
| DTCG | Theme value |
|
|
208
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
209
|
+
| `color` `#rrggbb[aa]` | string, lower-case |
|
|
210
|
+
| `dimension` `16px` / `1rem` | number `16` (1rem = 16) |
|
|
211
|
+
| `fontWeight` | string `"700"` (RN requirement) |
|
|
212
|
+
| `typography` | `{ fontFamily, fontSize, fontWeight, lineHeight (px), letterSpacing }`, spreadable into a `TextStyle` |
|
|
213
|
+
| `shadow` | `{ shadowColor, shadowOffset, shadowOpacity, shadowRadius (=blur/2), elevation (≈blur/2) }`, first layer only |
|
|
214
|
+
| `duration` | ms number |
|
|
215
|
+
|
|
216
|
+
Theme root keys: `color`→`colors`, `shadow`→`shadows`, `font/family`→`fontFamilies`, `font/size`→`fontSizes`, others keep their name
|
|
217
|
+
(`spacing`, `radius`, `typography`, `opacity`). Nested keys are camelCased (`on-surface` → `onSurface`); numeric keys stay (`primary[500]`).
|
|
218
|
+
`shadowRadius`/`elevation` are heuristics; check shadows visually on Android and iOS.
|
|
219
|
+
|
|
220
|
+
## Using tokens in components
|
|
221
|
+
|
|
222
|
+
```tsx
|
|
223
|
+
// GOOD
|
|
224
|
+
import { useTheme } from '@/shared/theme/ThemeProvider';
|
|
225
|
+
|
|
226
|
+
export function PrimaryButton({ label, onPress }: Props) {
|
|
227
|
+
const { theme } = useTheme();
|
|
228
|
+
return (
|
|
229
|
+
<Pressable
|
|
230
|
+
testID="login-submit"
|
|
231
|
+
onPress={onPress}
|
|
232
|
+
style={{
|
|
233
|
+
backgroundColor: theme.colors.brand,
|
|
234
|
+
paddingVertical: theme.spacing.sm,
|
|
235
|
+
paddingHorizontal: theme.spacing.md,
|
|
236
|
+
borderRadius: theme.radius.md,
|
|
237
|
+
...theme.shadows.md,
|
|
238
|
+
}}
|
|
239
|
+
>
|
|
240
|
+
<Text style={{ ...theme.typography.body.regular, color: theme.colors.text.primary }}>{label}</Text>
|
|
241
|
+
</Pressable>
|
|
242
|
+
);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// BAD: every line below is rejected by the ESLint rule
|
|
246
|
+
style={{ backgroundColor: '#3B82F6', padding: 16, borderRadius: 12, fontFamily: 'Inter', fontSize: 16 }}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
- Static styles that depend on the theme: `useMemo(() => StyleSheet.create({...}), [theme])`; do not create styles inside loops or per-item renders.
|
|
250
|
+
- Need a value that has no token? Do not hardcode it. Add it to the design file, re-run the skill, then use it.
|
|
251
|
+
- `ThemeProvider` follows the system color scheme (`useColorScheme`) and accepts `forcedTheme`. Wrap the app root once.
|
|
252
|
+
|
|
253
|
+
## ESLint guard
|
|
254
|
+
|
|
255
|
+
`rn-agent-kit/no-hardcoded-design-values` (file: `tools/eslint/rn-agent-kit-rules.cjs`, config snippet: `templates/eslint/eslint.config.snippet.mjs`) reports:
|
|
256
|
+
|
|
257
|
+
- hex, `rgb()/rgba()/hsl()/…` color strings and common named colors in `*color` props
|
|
258
|
+
- `fontFamily` string literals
|
|
259
|
+
- numeric `margin*`, `padding*`, `gap`, `border*Radius`, `fontSize`, `lineHeight`, `letterSpacing` (except `0`)
|
|
260
|
+
|
|
261
|
+
Options: `checkColors`, `checkFonts`, `checkDimensions` (set `checkDimensions: false` when adopting in a legacy codebase and tighten later),
|
|
262
|
+
`allowedValues`, `allowedNumbers`, `allowedPaths` (defaults skip `/shared/theme/`, `/design/`, tests and `*.config.*`).
|
|
263
|
+
Never silence the rule with `eslint-disable` to ship a hardcoded value. If the rule flags generated code, fix the generator input.
|
|
264
|
+
|
|
265
|
+
## CI
|
|
266
|
+
|
|
267
|
+
```yaml
|
|
268
|
+
- run: npx rn-agent-kit tokens check # fails if tokens.ts is stale vs tokens.json, or tokens.json is stale vs source-snapshot.json
|
|
269
|
+
- run: npx tsc --noEmit && npx eslint .
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## Common mistakes
|
|
273
|
+
|
|
274
|
+
- Writing colors into `tokens.ts` "just this once". The next build erases it and CI's `tokens check` fails.
|
|
275
|
+
- Passing `get_variable_defs` output for **one** frame and assuming it is the whole design system. Union several frames, then read the report's `missing-category` items.
|
|
276
|
+
- Treating light values as dark values (`flatVariablesDark` copied from light). The report cannot detect this; ask the user if unsure.
|
|
277
|
+
- Leaving designers' placeholder names ("Color 1", "Fill 3") in the file. Components get unusable token names; get them renamed in Figma.
|
|
278
|
+
- Forgetting to load custom fonts. The theme's `fontFamily` must equal the registered font name for that weight, or RN silently falls back to the system font.
|
|
279
|
+
- Using `shadows.*` on a `View` without a background color: iOS then draws no shadow.
|
|
280
|
+
- Re-running `build` and ignoring "Removed" tokens. Run `tsc` and migrate usages.
|
|
281
|
+
|
|
282
|
+
## Done checklist
|
|
283
|
+
|
|
284
|
+
- [ ] `design/source-snapshot.json` committed, `fileUrl` set
|
|
285
|
+
- [ ] `tokens build` ran without errors; `tokens check` passes
|
|
286
|
+
- [ ] Report reviewed; unresolved items communicated to the user (with the exact Figma fix)
|
|
287
|
+
- [ ] `tsc`, ESLint (no hardcoded design values) and unit tests pass
|
|
288
|
+
- [ ] No hardcoded colors/fonts/spacing in components touched by this change
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-actions-ci
|
|
3
|
+
description: >-
|
|
4
|
+
Wire GitHub Actions for RN/Expo apps from rn-agent-kit templates: CI (tsc,
|
|
5
|
+
eslint, jest, tokens check), Android Maestro E2E on PRs, iOS Maestro on
|
|
6
|
+
main/nightly/manual, optional EAS build. Use when adding CI, fixing workflows,
|
|
7
|
+
configuring secrets, or after init --sdlc. Prefer templates/workflows/*;
|
|
8
|
+
pin action versions; use concurrency + caches.
|
|
9
|
+
globs: "**/.github/workflows/*.{yml,yaml}"
|
|
10
|
+
alwaysApply: false
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# github-actions-ci
|
|
14
|
+
|
|
15
|
+
Copy and adapt workflows from **`templates/workflows/`** into the app repo’s `.github/workflows/`. Cite **GitHub Actions** docs, **Maestro**, **Expo EAS**, and this kit’s `tokens check` / `maestro-e2e` skills.
|
|
16
|
+
|
|
17
|
+
## Hard rules
|
|
18
|
+
|
|
19
|
+
1. Prefer the kit templates; do not invent unpinned `uses: some-action@main`.
|
|
20
|
+
2. Keep **concurrency groups** so superseded PR runs cancel.
|
|
21
|
+
3. Cache **npm**, **Gradle**, and **CocoaPods** where those jobs run.
|
|
22
|
+
4. **Never** commit secrets — only `secrets.*` / `vars.*`.
|
|
23
|
+
5. Parse Jira keys from branch names (`feature/APP-123-…`) for ticket comments; skip quietly if no key / no `JIRA_*` secrets.
|
|
24
|
+
6. **`eas-build.yml` is optional** — only copy it if the team uses EAS; otherwise omit it.
|
|
25
|
+
7. Tokens gate: if `design/source-snapshot.json` exists, CI must run `rn-agent-kit tokens check` (or `npm run tokens -- check`) and **fail on drift**.
|
|
26
|
+
|
|
27
|
+
## Workflow map
|
|
28
|
+
|
|
29
|
+
| File | Trigger | Purpose |
|
|
30
|
+
| ----------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
31
|
+
| `ci.yml` | `pull_request` (+ push main) | Node setup + cache → install → `tsc --noEmit` → eslint → jest coverage → **tokens check** → PR sticky comment → Jira comment |
|
|
32
|
+
| `e2e-android.yml` | `pull_request` | KVM → emulator (`reactivecircus/android-emulator-runner`) → debug APK → Maestro → artifacts (junit, screenshots, debug) → PR + Jira comments |
|
|
33
|
+
| `e2e-ios.yml` | push `main`, nightly cron, `workflow_dispatch` | macOS simulator build → Maestro → artifacts. **Not on every PR** (cost). |
|
|
34
|
+
| `eas-build.yml` | **optional** manual / `v*` tags | `eas build` (+ optional submit). Skip if unused. |
|
|
35
|
+
|
|
36
|
+
`init --sdlc` copies `templates/workflows/*` into `.github/workflows/`.
|
|
37
|
+
|
|
38
|
+
## Install into a consumer app
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
mkdir -p .github/workflows
|
|
42
|
+
cp node_modules/rn-agent-kit/templates/workflows/*.yml .github/workflows/
|
|
43
|
+
# or from a cloned kit / after init --sdlc
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Adjust:
|
|
47
|
+
|
|
48
|
+
- `APP_ID` via repo **Variable** `APP_ID` (bundle id / applicationId).
|
|
49
|
+
- Expo vs CLI: templates auto-detect `app.config.*` / `app.json` vs bare `android/`.
|
|
50
|
+
- Jest script must accept `--coverage` (default Vitest/Jest both do with `--`).
|
|
51
|
+
|
|
52
|
+
## CI job details (`ci.yml`)
|
|
53
|
+
|
|
54
|
+
Order matters for fast fail:
|
|
55
|
+
|
|
56
|
+
1. `actions/checkout@v4.2.2`
|
|
57
|
+
2. `actions/setup-node@v4.2.0` + `cache: npm`
|
|
58
|
+
3. `npm ci`
|
|
59
|
+
4. `npx tsc --noEmit`
|
|
60
|
+
5. `npm run lint`
|
|
61
|
+
6. `npm test -- --coverage …`
|
|
62
|
+
7. Tokens: `rn-agent-kit tokens check` when snapshot present
|
|
63
|
+
8. Sticky PR comment (`marocchino/sticky-pull-request-comment@v2.9.0`)
|
|
64
|
+
9. Jira comment via REST v2 if `JIRA_SITE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` set
|
|
65
|
+
|
|
66
|
+
## Android E2E (`e2e-android.yml`)
|
|
67
|
+
|
|
68
|
+
1. Enable KVM udev rule (required for nested virt on GitHub-hosted Ubuntu).
|
|
69
|
+
2. Java 17 + Android SDK + Gradle cache.
|
|
70
|
+
3. Build debug APK:
|
|
71
|
+
- **Expo:** `npx expo prebuild --platform android` then `./gradlew assembleDebug`
|
|
72
|
+
- **CLI:** `./gradlew assembleDebug`
|
|
73
|
+
- Optional EAS local: commented in template
|
|
74
|
+
4. Install Maestro (`get.maestro.mobile.dev`).
|
|
75
|
+
5. `reactivecircus/android-emulator-runner@v2.33.0` → `adb install` → `maestro test maestro/flows --format junit --output … --debug-output …`
|
|
76
|
+
6. Upload `maestro-results/` (+ `~/.maestro/tests/` if present).
|
|
77
|
+
|
|
78
|
+
## iOS E2E (`e2e-ios.yml`) — cost
|
|
79
|
+
|
|
80
|
+
```text
|
|
81
|
+
macOS Actions minutes ≫ Linux. Running Maestro iOS on every PR often dominates the bill.
|
|
82
|
+
Default: main + nightly + manual. Add pull_request only with path filters / labels if needed.
|
|
83
|
+
Prefer Android PR E2E for day-to-day; keep iOS as release gate.
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Pods cached via `actions/cache@v4.2.0` on `Podfile.lock`.
|
|
87
|
+
|
|
88
|
+
## Optional EAS (`eas-build.yml`)
|
|
89
|
+
|
|
90
|
+
- Do **not** add this workflow unless the product ships with EAS.
|
|
91
|
+
- Needs `EXPO_TOKEN`. Submit is opt-in via `workflow_dispatch` input.
|
|
92
|
+
- Prefer EAS-managed credentials; do not put App Store / Play passwords in YAML.
|
|
93
|
+
|
|
94
|
+
## Secrets & variables
|
|
95
|
+
|
|
96
|
+
See README **GitHub Actions secrets**. Minimum for full SDLC comments:
|
|
97
|
+
|
|
98
|
+
| Name | Required for |
|
|
99
|
+
| ---------------- | --------------------------------- |
|
|
100
|
+
| `JIRA_SITE_URL` | Jira comments from CI/E2E |
|
|
101
|
+
| `JIRA_EMAIL` | Jira basic auth |
|
|
102
|
+
| `JIRA_API_TOKEN` | Jira basic auth |
|
|
103
|
+
| `EXPO_TOKEN` | **Only** if using `eas-build.yml` |
|
|
104
|
+
|
|
105
|
+
Repo variable: `APP_ID`.
|
|
106
|
+
|
|
107
|
+
## Common mistakes
|
|
108
|
+
|
|
109
|
+
1. Running iOS E2E on every PR without accepting macOS cost.
|
|
110
|
+
2. Unpinned actions (`@master`).
|
|
111
|
+
3. Skipping tokens check → merged drift in `tokens.ts`.
|
|
112
|
+
4. Maestro selecting by visible text instead of testIDs (`maestro-e2e` skill).
|
|
113
|
+
5. Committing `eas-build.yml` without `EXPO_TOKEN` and wondering why it fails — remove the file instead.
|
|
114
|
+
6. Missing `permissions: pull-requests: write` → sticky comment fails.
|
|
115
|
+
7. No concurrency → stacked emulator jobs exhaust minutes.
|
|
116
|
+
|
|
117
|
+
## Done checklist
|
|
118
|
+
|
|
119
|
+
- [ ] `ci.yml` on PRs with tsc / lint / jest / tokens check
|
|
120
|
+
- [ ] `e2e-android.yml` on PRs with artifacts
|
|
121
|
+
- [ ] `e2e-ios.yml` on main/nightly/manual with cost comment understood
|
|
122
|
+
- [ ] `eas-build.yml` only if team wants EAS
|
|
123
|
+
- [ ] Secrets documented; Jira comments optional but wired
|
|
124
|
+
- [ ] Action versions pinned; caches + concurrency present
|