Contracts

contracts/ holds everything that must be identical in all three apps. make gen validates it and generates platform code. Generated files are committed and never edited by hand.

app.json#

{
  "name": "GeekNative",
  "id": "com.example.geeknative",
  "version": "1.0.0",
  "build": 1,
  "defaultLocale": "en"
}

In code: AppIdentity.name and AppIdentity.version (iOS), AppIdentity.NAME and AppIdentity.VERSION (Android), AppIdentity.name and AppIdentity.version (web).

tokens.json#

{
  "color": {
    "primary": { "light": "#4F46E5", "dark": "#A5B4FC" },
    "onPrimary": { "light": "#FFFFFF", "dark": "#1E1B4B" }
  },
  "spacing": { "xs": 4, "sm": 8, "md": 12, "lg": 16, "xl": 24, "xxl": 32 },
  "radius": { "sm": 6, "md": 10, "lg": 16, "full": 9999 },
  "typography": {
    "title": { "size": 20, "lineHeight": 26, "weight": 600, "ios": "title3", "android": "titleLarge" }
  },
  "font": { "family": "system" }
}

Names are camelCase letters and digits starting lowercase, and can't be reserved words in Swift, Kotlin or TypeScript (like default or class).

Colors are #RRGGBB or #RRGGBBAA. dark is optional and defaults to light. These colors are required: background, onBackground, surface, onSurface, surfaceVariant, onSurfaceVariant, primary, onPrimary, outline, error and onError. You can add more.

Spacing and radius values are numbers of points (iOS), dp (Android) or pixels (web). A radius of 9999 or more is fully rounded on the web.

Typography entries need:

A body style is required. On iOS, sizes come from Dynamic Type for the mapped style, so text follows the user's text size setting.

Font family must be "system" for now.

Generated#

On Android, screens and app bars sit on background (as on iOS) and surface is used for cards. A color named after another Material 3 role (like secondary) replaces that role's default. On the web, the theme also defines shadcn/ui's variable names (foreground, card, muted, border, ...) mapped onto the tokens, so shadcn/ui components pick up the design. Dark values apply when <html> has the dark class.

strings/#

One JSON file per locale: contracts/strings/en.json, contracts/strings/fr.json, and so on. The default locale's file (from app.json) is the source; other files translate its keys.

{
  "settings.title": "Settings",
  "settings.about.version": "Version {version} ({build:int})",
  "notes.count": { "one": "{count} note", "other": "{count} notes" }
}

Generated#

Files: App/Generated/Localizable.xcstrings and Strings.swift on iOS; res/values/generated_strings.xml (plus values-fr, values-pt-rBR, values-b+zh+Hans and so on) on Android, which also gets app_name; src/generated/strings.ts on web, with setLocale().

icons.json#

{
  "settings": { "ios": "gearshape", "android": "Icons.Filled.Settings", "web": "Settings" },
  "back": { "ios": "chevron.backward", "android": "Icons.AutoMirrored.Filled.ArrowBack", "web": "ArrowLeft" }
}

In code: Image(systemName: AppIcon.settings) on iOS, Icon(AppIcons.settings, contentDescription = ...) on Android, and <AppIcons.settings className="size-6" /> on web.

All generated files#

Validation errors#

Problems are reported with the file and field, so an agent can fix them directly:

✖ contracts/tokens.json color.primary.light must be a hex color like "#4F46E5" or "#4F46E5CC" (got "#4F46E").
✖ contracts/strings/fr.json "settings.about.version" must use the same placeholders and plural shape as en.json.
✖ contracts/icons.json "star" needs "android": a Material icon like "Icons.Filled.Settings" or "Icons.AutoMirrored.Filled.ArrowBack".