vybekiit 0.7.3 → 0.7.7

package/dist/global-skills/expo-brownfield/SKILL.md

@@ -52,3 +52,11 @@ npx create-expo-app@latest my-project --template default@sdk-55
 ```
 
 Pin the same Expo SDK across both the RN project and any embedded dependencies.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-brownfield" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/expo-brownfield/references/brownfield-isolated.md

@@ -13,9 +13,9 @@ If a single team owns both layers, is comfortable with React Native tooling and
 
 ## What you produce
 
-| Platform | Artifact                                                                                                                                                                                            | Default location                                              |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Android  | `{group}:{libraryName}:{version}` AAR                                                                                                                                                               | Local Maven (`~/.m2`) by default; remote Maven also supported |
+| Platform | Artifact                                                                                                                                                                                                                | Default location                                              |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Android  | `{group}:{libraryName}:{version}` AAR                                                                                                                                                                                   | Local Maven (`~/.m2`) by default; remote Maven also supported |
 | iOS      | Set of `.xcframework`s — see [the iOS section below](#ios) for how `ios.buildReactNativeFromSource` (default `false` on SDK 56+) controls whether you get 5 frameworks or 2 — or a single Swift Package via `--package` | `./artifacts`                                                 |
 
 The JavaScript bundle is **embedded inside the artifact** in release builds, so the native app does not need Metro at runtime in production.
@@ -49,6 +49,15 @@ npx expo install expo-brownfield
 
 The plugin self-registers in `app.json` with defaults derived from your app config.
 
+### Check what the host app already ships
+
+Before picking Expo modules, audit the host app's dependencies. The artifact's libraries meet the host's at build time, and version clashes surface as duplicate-class errors or forced upgrades.
+
+- **Jetpack Compose** — `@expo/ui` re-declares recent Compose and Material3 versions, and is pulled transitively by `expo-router`. A host pinned to older Compose gets force-upgraded. Exclude it with `expo.autolinking.android.exclude` if the RN screens don't need it.
+- **OkHttp, Kotlin stdlib, Material Components** — arrive as ordinary Maven dependencies of the artifact; Gradle resolves the highest version, which can bump the host's copies.
+
+When a shared library must stay at the host's version, exclude the Expo module that brings it, or (with fused publishing, below) mark the group as host-provided.
+
 ### Configure the plugin (optional)
 
 To override the auto-generated names, expand the plugin entry in `app.json`:
@@ -162,6 +171,37 @@ npx expo-brownfield build:android --task publishReleasePublicationToCompanyRepos
 npx expo-brownfield tasks:android   # list available publish tasks and repositories
 ```
 
+#### Fused publishing (single fat AAR)
+
+> **Version note:** requires minimum SDK 56. Earlier versions only support the per-module publishing above.
+
+The default publish flow emits one Maven coordinate per autolinked Expo module. For remote distribution, `--fused` collapses everything into one fat AAR per build variant:
+
+```sh
+npx expo-brownfield build:android --fused --repo MavenLocal
+```
+
+This publishes two coordinates — `{group}:{libraryName}-fused-release` and `{group}:{libraryName}-fused-debug`, which the host wires per build type:
+
+```kotlin
+dependencies {
+  releaseImplementation("com.example:mybrownfield-fused-release:1.0.0")
+  debugImplementation("com.example:mybrownfield-fused-debug:1.0.0")
+}
+```
+
+The debug AAR contains debug-compiled modules (dev menu, Metro reload); the release AAR embeds the JS bundle. Published metadata pins the matching React Native variant, so a debug host consuming only the release AAR still resolves release RN correctly.
+
+Not everything is fused: the React Native runtime, Kotlin stdlib, host-common libraries (Material, Guava, OkHttp, Fresco), `androidx.*`, and detected KMP umbrella modules stay external and are declared as ordinary POM dependencies. Gradle properties tune the behavior for unusual dependency graphs:
+
+| Property                              | Effect                                                                                                                               |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `brownfield.fused.skip`               | Gradle project names to leave out of the AAR (pair with `strip-packages`).                                                           |
+| `brownfield.fused.strip-packages`     | Package prefixes to remove from `ExpoModulesPackageList` — avoids `NoClassDefFoundError` for skipped modules.                        |
+| `brownfield.fused.androidx-fuse`      | Extra `androidx.*` groups to fuse instead of keeping external.                                                                       |
+| `brownfield.fused.exclude-transitive` | Extra groups to keep external (still declared in the POM).                                                                           |
+| `brownfield.fused.host-provided`      | Groups the host already ships (e.g. Glide, Compose): excluded from the AAR **and** from the POM, so the host's version is untouched. |
+
 ### iOS
 
 ```sh
@@ -179,7 +219,10 @@ To force source builds on SDK 56+, add `expo-build-properties` to `app.json`:
 {
   "expo": {
     "plugins": [
-      ["expo-build-properties", { "ios": { "buildReactNativeFromSource": true } }],
+      [
+        "expo-build-properties",
+        { "ios": { "buildReactNativeFromSource": true } }
+      ],
       "expo-brownfield"
     ]
   }
@@ -258,6 +301,12 @@ dependencyResolutionManagement {
 
 If the artifact is published to a remote Maven, declare that repository in the same `dependencyResolutionManagement` block instead — credentials follow Gradle's standard `maven { url = uri(...); credentials { username = ...; password = ... } }` form.
 
+#### Host app requirements
+
+- **`minSdk` 24 or higher** — React Native's floor. Hosts below it fail at manifest merge with `uses-sdk:minSdkVersion XX cannot be smaller than version 24`.
+- **Permissions merge in from the Expo modules** (e.g. storage permissions from media modules). Hosts that enforce a permission allowlist can strip unwanted entries in their manifest with `tools:node="remove"` or reconcile attribute conflicts with `tools:replace`.
+- **Native libraries ship for every ABI enabled at publish time.** Left unfiltered, this can multiply the host APK size. Constrain ABIs when publishing (`reactNativeArchitectures=arm64-v8a` in the Expo project's `gradle.properties`) or filter in the host with `ndk.abiFilters` / APK splits.
+
 #### Show a React Native screen
 
 Extend `BrownfieldActivity` and call `showReactNativeFragment()`:

package/dist/global-skills/expo-data-fetching/SKILL.md

@@ -447,3 +447,11 @@ User: "Where should I put my API key?"
 
 User: "How do I load data for a page in Expo Router?"
 -> See references/expo-router-loaders.md for route-level loaders (web, SDK 55+). For native, use React Query or fetch.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-data-fetching" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/expo-design-system/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: expo-design-system
+description: Framework (OSS). Build and maintain a design system inside an Expo app - a reusable theme of design tokens (color, spacing, typography, radius, shadow, motion), reusable component structure with variant/size/state prop conventions, and rules for when to extract a repeated view into a shared component. Use when creating or organizing theme files and design tokens (theme.ts / theme/), extending an existing theme or styling library (NativeWind, Tamagui, Restyle, Unistyles) in its own idiom, standardizing styles so screens (including AI-generated ones) look consistent and polished, building an in-app component library, or auditing an app for design-system drift (hardcoded colors, spacing, fonts). For platform styling specifics (semantic colors, HIG rules, native controls) use expo-native-ui; for Tailwind/CSS setup use expo-tailwind-setup; for folder layout of a new app use expo-project-structure.
+version: 1.0.0
+license: MIT
+---
+
+# Expo Design Systems
+
+Make every screen in an app draw from one visual source of truth: a token theme and a small set of reusable components. This skill defines where tokens live, what they cover, how reusable components are shaped, and when a repeated view earns promotion into the system.
+
+Sibling skills own the layers around this one:
+
+- `expo-native-ui` - platform styling rules (HIG, semantic colors, controls, shadows syntax). Follow it for **what values look native**; follow this skill for **where values live and how they're reused**.
+- `expo-tailwind-setup` - if the project uses Tailwind, tokens live in `global.css` as CSS variables instead of TypeScript. The scales and naming in this skill still apply; only the storage format changes.
+- `expo-project-structure` - folder skeleton for new apps.
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  audit.md      Audit an existing app for design-system drift: grep checks,
+                scoring rubric, incremental adoption plan, and templates for
+                documenting or extending components
+```
+
+## Adopt Before You Build
+
+In an app that already has screens, the first move is detection, not construction. Before writing any token file:
+
+1. **Look for a declared system.** Check `package.json` for a styling library - NativeWind/Tailwind (use `expo-tailwind-setup`), Tamagui, Restyle, Unistyles, styled-components. Then look for a token file: `theme.ts`, `src/theme/`, `constants/theme.ts`, or `constants/Colors.ts` (the create-expo-app default).
+2. **If one exists, it is the source of truth.** Extend it in its own idiom - its names, its scale, its storage format. Audit drift against that system, not against the examples below.
+3. **If only de facto values exist** - the same greys and paddings repeated across screens, no theme file - there is no system yet. Those values are the input to the scales, not the authority: derive tokens from the most frequent ones, snapped to the 4-point grid (`references/audit.md` §5).
+4. **Never introduce a second system beside an existing one.** A fresh `src/theme/` next to a Tamagui config is design-system drift, not adoption.
+
+Only when nothing exists do the defaults below apply as written.
+
+## The Theme
+
+In an app without an existing system, all design tokens live under `src/theme/`. In a project without a `src/` folder (the default `create-expo-app` template has `app/`, `components/`, and `constants/` at the root), use the equivalent top-level location - typically `theme/` or the existing `constants/` - and keep the same file layout. Start small and split by token class as it grows:
+
+```
+src/theme/
+  colors.ts       # see expo-native-ui "Colors" for the palette pattern
+  spacing.ts
+  typography.ts
+  radius.ts
+  shadows.ts
+  motion.ts
+  index.ts        # re-exports everything: import { spacing, type } from "@/theme"
+```
+
+A brand-new app can begin with a single `src/theme.ts` holding all of the objects below, then promote it to the folder form once any one class needs its own file (same promotion rule as components). Either way there is exactly **one** theme entry point - never two competing token files.
+
+Rules that make a theme worth having:
+
+- **Every repeated visual value is a token.** A literal that appears twice belongs in the theme.
+- **Components import tokens; screens import components.** A screen file that imports `spacing` for layout padding is fine; a screen file redefining a button color is drift.
+- **Never hardcode** hex colors, font sizes, or spacing multiples outside `src/theme/`. One-off values that are genuinely local (an icon's 17px optical nudge) may stay inline - with a comment saying why.
+
+### Colors
+
+Build the palette from platform semantic colors: `Color` from `expo-router` wrapped in `Platform.select`, centralized in `theme/colors.ts`. Semantic colors resolve on-device and adapt to light/dark automatically - prefer them for backgrounds, labels, and separators. (`expo-native-ui` "Colors" covers the full palette and rationale; the minimal version is:)
+
+```tsx
+// theme/colors.ts
+import { Platform } from "react-native";
+import { Color } from "expo-router";
+
+export const colors = {
+  label: Platform.select({
+    ios: Color.ios.label,
+    android: Color.android.dynamic.onSurface,
+    default: "#000000",
+  })!,
+  secondaryLabel: Platform.select({
+    ios: Color.ios.secondaryLabel,
+    android: Color.android.dynamic.onSurfaceVariant,
+    default: "#3c3c43",
+  })!,
+  separator: Platform.select({
+    ios: Color.ios.separator,
+    android: Color.android.dynamic.outlineVariant,
+    default: "#c6c6c8",
+  })!,
+  systemBackground: Platform.select({
+    ios: Color.ios.systemBackground,
+    android: Color.android.dynamic.surface,
+    default: "#ffffff",
+  })!,
+  systemBlue: Platform.select({
+    ios: Color.ios.systemBlue,
+    android: Color.android.dynamic.primary,
+    default: "#007aff",
+  })!,
+  // Deliberately fixed: text on a tinted (accent) surface stays white in both modes.
+  onTint: "#ffffff",
+};
+```
+
+Add brand colors as explicit light/dark pairs only when the brand requires values the platform doesn't provide:
+
+```tsx
+// theme/colors.ts (brand additions)
+import { useColorScheme } from "react-native";
+
+const brandPalette = {
+  light: { accent: "#5B21B6", accentContrast: "#FFFFFF" },
+  dark: { accent: "#A78BFA", accentContrast: "#1E1B4B" },
+} as const;
+
+export function useBrandColors() {
+  const scheme = useColorScheme();
+  return brandPalette[scheme === "dark" ? "dark" : "light"];
+}
+```
+
+Keep the brand set tiny (accent, accentContrast, maybe a tint per feature). Everything else stays semantic.
+
+**Static-safe vs hook-only.** The two patterns above have different reach - keep the boundary explicit:
+
+- Semantic/platform colors (`colors` above) are **static-safe**: they resolve on-device, so plain token files like `theme/typography.ts` can import them at module scope.
+- Brand light/dark pairs are **hook-only**: `useBrandColors()` reads the color scheme at render time, so brand colors can only be applied inside components. A static token file cannot call the hook.
+- Never mix the two in one file. If a static style (a `type` ramp step, a `variants` object) needs the brand accent, either apply the brand color in the component at render time, or wrap the pair in a static dynamic color (`DynamicColorIOS` on iOS) so it becomes static-safe.
+
+### Spacing
+
+One scale, based on a 4-point grid. Name steps by size, not by use:
+
+```tsx
+// theme/spacing.ts
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+  xxl: 48,
+} as const;
+```
+
+- Use `gap` with spacing tokens for layout rhythm (`expo-native-ui` prefers gap over margin).
+- Screen edge padding is `spacing.md` unless the design says otherwise - pick one and keep it.
+- If a layout needs a value between steps, use the nearest step. The grid is the point.
+- If the same in-between multiple of 4 keeps recurring (12 and 20 are common), add it to the scale as a named step instead of scattering literals. The audit whitelist must then include it too.
+
+### Typography
+
+Define named text styles, not raw font sizes. Mirror the platform ramp (Apple text styles) so sizes feel native:
+
+```tsx
+// theme/typography.ts
+import { TextStyle } from "react-native";
+import { colors } from "./colors";
+
+export const type = {
+  largeTitle: { fontSize: 34, fontWeight: "700", color: colors.label },
+  title: { fontSize: 22, fontWeight: "600", color: colors.label },
+  headline: { fontSize: 17, fontWeight: "600", color: colors.label },
+  body: { fontSize: 17, fontWeight: "400", color: colors.label },
+  subhead: { fontSize: 15, fontWeight: "400", color: colors.secondaryLabel },
+  caption: { fontSize: 12, fontWeight: "400", color: colors.secondaryLabel },
+} as const satisfies Record<string, TextStyle>;
+```
+
+If the project bundles static font files (one file per weight, loaded with `expo-font` or the config plugin), set weight via `fontFamily` names instead and omit `fontWeight` - otherwise iOS synthesizes the weight or falls back to the system font:
+
+```tsx
+headline: { fontSize: 17, fontFamily: "SFProRounded-Semibold", color: colors.label },
+```
+
+Expose them through one component so screens never touch `fontSize`:
+
+```tsx
+// components/themed-text.tsx
+import { Text, TextProps } from "react-native";
+import { type } from "@/theme";
+
+export function ThemedText({
+  variant = "body",
+  style,
+  ...props
+}: TextProps & { variant?: keyof typeof type }) {
+  return <Text style={[type[variant], style]} {...props} />;
+}
+```
+
+Screen titles still come from the navigation stack header (`expo-native-ui` rule), so `largeTitle` is mostly for non-stack contexts.
+
+### Radius
+
+```tsx
+// theme/radius.ts
+export const radius = {
+  sm: 8,
+  md: 12,
+  lg: 16,
+  full: 9999, // capsules
+} as const;
+```
+
+Pair every non-capsule radius with `borderCurve: "continuous"` (per `expo-native-ui`).
+
+### Shadows
+
+Shadows are `boxShadow` strings (never legacy shadow/elevation props - see `expo-native-ui`). Two or three elevation levels are enough:
+
+```tsx
+// theme/shadows.ts
+export const shadows = {
+  card: "0 1px 2px rgba(0, 0, 0, 0.05)",
+  raised: "0 4px 12px rgba(0, 0, 0, 0.10)",
+  overlay: "0 8px 24px rgba(0, 0, 0, 0.18)",
+} as const;
+```
+
+### Motion
+
+Durations and shared spring/easing configs, so animations across the app feel related:
+
+```tsx
+// theme/motion.ts
+export const motion = {
+  fast: 150, // state feedback: press, toggle
+  base: 250, // element transitions: enter/exit
+  slow: 400, // large surfaces: sheets, screens
+} as const;
+```
+
+Reanimated caveat: don't pass `Color`/`PlatformColor` token values into Reanimated styles - use static colors there (see `expo-native-ui`).
+
+## Reusable Components
+
+The theme controls values; components control structure. Shared primitives live in `src/components/` (see `expo-project-structure`).
+
+### The component contract
+
+Every design-system primitive defines, explicitly:
+
+- **Variants** - visual intent: `primary`, `secondary`, `ghost`, `destructive`. Add a variant only when a real screen needs it.
+- **Sizes** - `sm`, `md`, `lg`. Default `md`. Sizes map to spacing/typography tokens, never to fresh numbers.
+- **States** - default, **pressed** (not hover - this is touch), disabled, loading. Handle pressed with a `Pressable` style function; never leave a tappable element without pressed feedback.
+- **Style override** - accept a `style` prop and merge it **last**, so callers can adjust layout (margins, flex) without forking the component. Callers may override layout, not identity - a caller changing a button's colors is a signal the variant set is missing something.
+
+```tsx
+// components/button.tsx
+import { Pressable, ActivityIndicator, ViewStyle, StyleProp } from "react-native";
+import { colors, spacing, radius } from "@/theme";
+import { ThemedText } from "./themed-text";
+
+const variants = {
+  primary: { backgroundColor: colors.systemBlue, color: colors.onTint },
+  secondary: { backgroundColor: colors.separator, color: colors.label },
+} as const;
+
+const sizes = {
+  sm: { paddingVertical: spacing.xs, paddingHorizontal: spacing.sm },
+  md: { paddingVertical: spacing.sm, paddingHorizontal: spacing.md },
+} as const;
+
+export function Button({
+  variant = "primary",
+  size = "md",
+  title,
+  loading,
+  disabled,
+  style,
+  onPress,
+}: {
+  variant?: keyof typeof variants;
+  size?: keyof typeof sizes;
+  title: string;
+  loading?: boolean;
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  onPress?: () => void;
+}) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      disabled={disabled || loading}
+      onPress={onPress}
+      style={({ pressed }) => [
+        {
+          backgroundColor: variants[variant].backgroundColor,
+          borderRadius: radius.md,
+          borderCurve: "continuous",
+          alignItems: "center",
+          opacity: disabled ? 0.4 : pressed ? 0.7 : 1,
+          ...sizes[size],
+        },
+        style, // caller overrides merge last
+      ]}
+    >
+      {loading ? (
+        <ActivityIndicator color={variants[variant].color as string} />
+      ) : (
+        <ThemedText variant="headline" style={{ color: variants[variant].color }}>
+          {title}
+        </ThemedText>
+      )}
+    </Pressable>
+  );
+}
+```
+
+### Composition over configuration
+
+When a component's props start describing *content* (`leftIcon`, `subtitle`, `footerText`, `badgeCount`), stop adding props and accept `children` instead. A `Card` that renders `children` with token padding outlives any `Card` with twelve content props. Reserve props for the contract above: variant, size, state, style.
+
+### When to extract - and when not to
+
+Promote a view into `src/components/` when **all** of these hold:
+
+1. It appears (or is about to appear) in **two or more screens**. Until then it stays colocated in `screens/<name>/` (see `expo-project-structure`).
+2. It has a **nameable role** ("Card", "EmptyState", "Badge") - not "the thing on the profile screen".
+3. Its API is **smaller than its implementation**. If the props would just re-expose every internal style, it isn't a reusable component yet - it's a screen fragment.
+
+Promotion path: inline JSX → component in `screens/<name>/` → `src/components/`. Move one step at a time, when the trigger fires - never speculatively. Wrong abstractions cost more than duplication; a second copy of a view is cheaper than a primitive with a bad API.
+
+Do **not** wrap platform components that already carry the design language (`Switch`, `DateTimePicker`, stack headers, `@expo/ui` views) just to route them through the system. Native styling *is* the design system for those.
+
+## Where Decisions Live
+
+| Decision | Lives in | Example |
+|---|---|---|
+| A visual value used anywhere twice | `src/theme/` | brand accent, spacing step |
+| Structure + variants of a reused element | `src/components/` | Button, Card, EmptyState |
+| One screen's private composition | `screens/<name>/` | profile header layout |
+| One-off local adjustment | inline, with a comment | optical nudge on an icon |
+| Screen titles, top-level chrome | navigation stack options | header title, large title |
+
+## Self-Critique Pass
+
+After building or changing a screen, screenshot it and check it against these principles (from [Expo's design-principles guide](https://expo.dev/blog/how-to-apply-professional-design-principles-in-ai-app-development)). Each one maps to a system fix, not a local tweak:
+
+- **Hierarchy / contrast** - is the most important element obviously first? Fix with `type` ramp steps, not ad-hoc font sizes.
+- **Proximity / white space** - do related items sit closer than unrelated ones? Fix with `gap` + spacing tokens.
+- **Repetition / unity** - do all corners, shadows, and accents match? If not, a value escaped the theme - move it in.
+- **Alignment** - do edges share axes? Fix with consistent screen edge padding.
+
+The pass is complete only when all four checks pass, or every failing value has moved into the theme or a component. If a screen fails the same check twice, the fix belongs in the theme or a component - not in the screen.
+
+## Auditing an Existing App
+
+To measure drift in an app that already has screens - hardcoded hex values, arbitrary spacing, inconsistent component APIs - follow `./references/audit.md`. It contains grep-based checks, a scoring rubric, an incremental adoption order for fixing a drifted app, and templates for documenting existing components and proposing new ones.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-design-system" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/expo-design-system/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Design Systems"
+  short_description: "Build a design system in an Expo app: a token theme (color, spacing, typography, radius, shadow, motion), reusable component conventions, and audits for design-system drift (hardcoded style values)"
+  default_prompt: "Use $expo-design-system to set up or maintain the app's design system: create the src/theme token files, shape reusable components with variant/size/state props, decide when a repeated view becomes a shared component, and audit screens for design-system drift (hardcoded style values)."

package/dist/global-skills/expo-design-system/references/audit.md

@@ -0,0 +1,185 @@
+# Design System Audit
+
+Measure how far an existing Expo app has drifted from a single visual source of truth, then document or extend components with a consistent template.
+
+Run the audit **before** proposing changes. Report findings first; apply fixes only when asked.
+
+## 0. Locate the directories first
+
+Do **not** assume a `src/` folder. The default `create-expo-app` template puts `app/`, `components/`, and `constants/` at the repo root, and running the checks below against a nonexistent `src/` returns zero hits - a false clean bill.
+
+Before any grep, identify and record:
+
+- **Source directories** - every directory holding app code (`src`, or e.g. `app components constants hooks`).
+- **Theme location** - the token directory or file (`src/theme`, `theme`, `constants`, or a single `theme.ts`). If none exists yet, note that as the first finding.
+- **The existing system, if any** - a styling library in `package.json` (NativeWind, Tamagui, Restyle, Unistyles, styled-components) per `SKILL.md` "Adopt Before You Build". Record which one. The checks below assume this skill's defaults - plain `StyleSheet`, `boxShadow` strings, one `src/theme` entry point. An app on a styling library fails several of them while being perfectly consistent in its own idiom. Audit such an app against its own system: its token names, its scale, its config file as the single entry point. Adapt or skip a check rather than reporting a false violation.
+
+Substitute them into the shell variables below; every check uses them.
+
+```bash
+SRC="app components constants"   # this project's source directories
+THEME="constants"                # this project's theme directory (excluded from hits)
+```
+
+## 1. Token coverage checks
+
+Run from the repo root. Each hit outside the theme directory is a candidate for tokenization - not automatically a violation (check for the "one-off, with a comment" exemption in `SKILL.md`).
+
+```bash
+# Hardcoded hex colors outside the theme
+grep -rEn '#[0-9a-fA-F]{3,8}\b' $SRC --include='*.tsx' --include='*.ts' | grep -v "^$THEME/"
+
+# Raw fontSize (should come from the type ramp / ThemedText)
+grep -rn 'fontSize:' $SRC --include='*.tsx' | grep -v "^$THEME/"
+
+# Spacing values outside the named steps of the scale.
+# The whitelist is the project's actual scale (here: the example scale from
+# SKILL.md) - substitute the project's steps before running. Multiples of 4
+# that are not named steps (12, 20, 40, ...) are flagged on purpose: the rule
+# is "use the nearest step". If one keeps recurring, the fix is to add it to
+# the scale and to this whitelist, not to ignore the hits.
+grep -rEn '(padding|margin|gap)[A-Za-z]*:\s*[0-9]+' $SRC --include='*.tsx' \
+  | grep -vE ':\s*(0|4|8|16|24|32|48)\b' | grep -v "^$THEME/"
+
+# Raw borderRadius (should use radius tokens)
+grep -rn 'borderRadius:' $SRC --include='*.tsx' | grep -v "^$THEME/"
+
+# Legacy shadows (banned by expo-native-ui - must be boxShadow)
+grep -rEn 'shadow(Color|Offset|Opacity|Radius)|elevation:' $SRC --include='*.tsx'
+
+# Multiple theme entry points (there must be exactly one)
+ls src/theme.ts src/theme/index.ts theme.ts theme/index.ts constants/theme.ts 2>/dev/null
+```
+
+For a Tailwind project (`expo-tailwind-setup`), also check for values that bypass `global.css` variables: arbitrary-value classes like `p-[13px]` or `text-[#5B21B6]`.
+
+```bash
+grep -rEn 'className="[^"]*\[[^"]*\]' $SRC --include='*.tsx'
+```
+
+## 2. Scoring
+
+Turn raw hit counts into a comparable score so runs can be tracked over time:
+
+```bash
+# Source lines of code (the denominator)
+find $SRC -name '*.tsx' -o -name '*.ts' | xargs wc -l | tail -1
+```
+
+For each category: **score = escapes per 100 source lines** (hits ÷ SLOC × 100, one decimal).
+
+| Score per category | Reading |
+|---|---|
+| < 0.5 | Healthy - fix opportunistically |
+| 0.5 - 2.0 | Drifting - schedule cleanup for the worst files |
+| > 2.0 | Systemic - the token or component for this category is missing or unused; fix the system first (see §5) |
+
+Report the per-category scores in the summary. The overall priority order falls out of the scores: the highest-scoring category is usually the first migration target.
+
+## 3. Component completeness
+
+For each component in the shared components directory (`src/components/`, or `components/` in a root-level layout), check it against the contract in `SKILL.md`:
+
+| Check | Pass condition |
+|---|---|
+| Variants | Visual intent is a `variant` prop, not boolean soup (`isPrimary`, `isGhost`) |
+| Sizes | Sizes map to spacing/typography tokens |
+| Pressed state | Tappable components give pressed feedback via a `Pressable` style function |
+| Disabled / loading | Handled, and disabled blocks `onPress` |
+| Style override | Accepts `style`, merged last |
+| Accessibility | `accessibilityRole` set; touch target ≥ 44pt |
+| Tokens only | No literals that duplicate a theme value |
+
+## 4. Report format
+
+```markdown
+## Design System Audit
+
+### Summary
+Screens reviewed: [X] | Components reviewed: [X] | Issues: [X]
+
+### Token coverage
+| Category | Tokens defined | Escapes found | Score (per 100 SLOC) | Worst offenders |
+|---|---|---|---|---|
+| Colors | [X] | [X] hardcoded hex | [X.X] | [files] |
+| Spacing | [X] | [X] non-step values | [X.X] | [files] |
+| Typography | [X] | [X] raw fontSize | [X.X] | [files] |
+| Radius / shadows / motion | [X] | [X] | [X.X] | [files] |
+
+### Component completeness
+| Component | Variants | States | Overrides | Tokens | Notes |
+|---|---|---|---|---|---|
+| Button | OK | missing pressed | OK | OK | ... |
+
+### Extraction candidates
+Views repeated across ≥2 screens that are still colocated or duplicated:
+1. [view] - appears in [screens] - suggested name: [Component]
+
+### Priority actions
+1. [Highest-leverage fix - usually the most-duplicated escaped value]
+2. ...
+```
+
+## 5. Adopting incrementally
+
+An app with dozens of escapes is migrated in order, never big-bang. A big-bang conversion produces one huge unreviewable diff and usually stalls half-done.
+
+1. **Create the tokens first.** Derive the scales from the values the audit found most often, snapped to the grid. A theme built from the app's real values gets adopted; an aspirational one gets bypassed.
+2. **Typography before spacing.** Convert raw `fontSize` to the `type` ramp + `ThemedText` first: it is the highest-visibility win and touches the fewest layout decisions. Then spacing, then colors, then radius/shadows.
+3. **Convert one worst-offender file completely** and use it as the reference pattern for the rest of the migration.
+4. **Then convert per-screen**, one screen per commit, using the audit greps scoped to that screen to verify it comes out clean.
+5. **Re-run the audit after each phase** and record the scores from §2 - they should fall monotonically.
+
+## 6. Documenting an existing component
+
+```markdown
+## Component: [Name]
+
+[What it is and when to use it - one paragraph.]
+
+### Variants
+| Variant | Use when |
+|---|---|
+| primary | The screen's single main action |
+
+### Props
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+
+### States
+default / pressed / disabled / loading - visual + behavior for each.
+
+### Accessibility
+Role, touch target, screen reader label.
+
+### Do / Don't
+| Do | Don't |
+|---|---|
+| [best practice] | [anti-pattern seen in this repo] |
+```
+
+## 7. Proposing a new component
+
+Before designing a new primitive, prove the existing set can't cover it:
+
+```markdown
+## Proposed: [Name]
+
+### Problem
+[The repeated need, and the ≥2 screens that have it.]
+
+### Why existing components aren't enough
+| Closest component | What's shared | What's missing |
+|---|---|---|
+
+### API
+Props table (variant / size / state / style only - content via children).
+
+### Tokens used
+Colors: [...] Spacing: [...] Typography: [...] Radius: [...]
+
+### Open questions
+[Decisions that need a human, e.g. does this need a destructive variant?]
+```
+
+If the "what's missing" column is empty for any row, extend that component's variants instead of adding a new one.