rn-agent-kit 0.0.0-stage → 0.2.0

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.
Files changed (36) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +176 -2
  3. package/dist/cli.js +2916 -0
  4. package/dist/cli.js.map +1 -0
  5. package/dist/scripts/figma-tokens.js +1284 -0
  6. package/dist/scripts/figma-tokens.js.map +1 -0
  7. package/dist/scripts/validate-jira-tickets.js +169 -0
  8. package/dist/scripts/validate-jira-tickets.js.map +1 -0
  9. package/package.json +64 -4
  10. package/skills/expo-cli/SKILL.md +213 -0
  11. package/skills/figma-to-tokens/SKILL.md +288 -0
  12. package/skills/github-actions-ci/SKILL.md +124 -0
  13. package/skills/maestro-e2e/SKILL.md +256 -0
  14. package/skills/prd-to-jira/SKILL.md +237 -0
  15. package/skills/rn-architecture/SKILL.md +207 -0
  16. package/skills/rn-native-android-ios/SKILL.md +195 -0
  17. package/skills/rn-sdk-integrations/SKILL.md +274 -0
  18. package/skills/rn-typescript-react/SKILL.md +247 -0
  19. package/skills/ticket-to-code/SKILL.md +192 -0
  20. package/templates/config/rn-agent-kit.json +4 -0
  21. package/templates/eslint/eslint.config.snippet.mjs +16 -0
  22. package/templates/eslint/rn-agent-kit-rules.cjs +137 -0
  23. package/templates/jira-ticket.md +78 -0
  24. package/templates/maestro/smoke.yaml +4 -0
  25. package/templates/scaffold/.husky/commit-msg +4 -0
  26. package/templates/scaffold/.husky/pre-commit +4 -0
  27. package/templates/scaffold/.prettierignore +6 -0
  28. package/templates/scaffold/.prettierrc +6 -0
  29. package/templates/scaffold/commitlint.config.cjs +4 -0
  30. package/templates/scaffold/eslint.config.js +22 -0
  31. package/templates/scaffold/jest.config.cjs +9 -0
  32. package/templates/scaffold/tsconfig.json +13 -0
  33. package/templates/workflows/ci.yml +120 -0
  34. package/templates/workflows/e2e-android.yml +158 -0
  35. package/templates/workflows/e2e-ios.yml +134 -0
  36. 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