Add JSON Schema for clerk-theme.json

[csandman]

Hey team! Love the new native component support you added for Expo. I've been using it in our Expo app and it's been great so far.

One thing I noticed while setting up the theming is there's no JSON schema for clerk-theme.json, which means you don't get any autocomplete or validation while editing the file. I ended up writing one myself based on the validation logic in app.plugin.js and thought it might be worth Clerk shipping officially.

What it would look like

A schema covering the 15 color tokens, darkColors, and the design object (borderRadius and fontFamily). The fontFamily description could note that it's iOS only since Android ignores it.

Why it's worth doing

• Autocomplete while editing — instead of having to look up which color keys are valid, your editor just shows them to you as you type (built-in to VS Code/Cursor).
• Typos in color keys or invalid hex strings get flagged immediately, before you even run prebuild. Right now you only find out something is wrong when the build fails.
• Developers might not know darkColors or fontFamily exist unless they happen to read the docs on theming specifically or dig into the plugin source. A schema surfaces all the options in the editor.

This might only be a small quality of life improvement, but it definitely improves the dev experience in my opinion!

How to publish it

The lowest-friction approach would be to commit the schema to the @clerk/expo package and host it at a stable URL. It could be used like this manually:

"$schema": "https://raw.githubusercontent.com/clerk/javascript/refs/heads/main/packages/expo/clerk-theme.schema.json"

Then submit a PR to SchemaStore with a fileMatch entry for clerk-theme.json. Once that's merged, VS Code and Cursor automatically apply the schema to anyone's clerk-theme.json with zero configuration on their end. This is exactly how Expo handles app.json: https://github.com/expo/expo/tree/main/docs/public/static/schemas.

Here's the schema I wrote as a starting point if it's helpful!

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "clerk-theme",
  "title": "Clerk Native Theme",
  "description": "Theme configuration for @clerk/expo native components (iOS SwiftUI + Android Jetpack Compose).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string"
    },
    "colors": {
      "$ref": "#/$defs/colorMap",
      "description": "Light mode color overrides."
    },
    "darkColors": {
      "$ref": "#/$defs/colorMap",
      "description": "Dark mode color overrides."
    },
    "design": {
      "type": "object",
      "additionalProperties": false,
      "description": "Design token overrides.",
      "properties": {
        "fontFamily": {
          "type": "string",
          "description": "Font family applied across all Clerk native components. iOS only — ignored on Android."
        },
        "borderRadius": {
          "type": "number",
          "description": "Base border radius (in points/dp) applied to buttons, inputs, and cards."
        }
      }
    }
  },
  "$defs": {
    "hexColor": {
      "type": "string",
      "pattern": "^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$",
      "description": "Hex color string (#RRGGBB or #RRGGBBAA)."
    },
    "colorMap": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "primary": {
          "$ref": "#/$defs/hexColor",
          "description": "Primary brand color — used for buttons and active states."
        },
        "primaryForeground": {
          "$ref": "#/$defs/hexColor",
          "description": "Text/icon color on top of primary-colored surfaces."
        },
        "background": {
          "$ref": "#/$defs/hexColor",
          "description": "Page/card background."
        },
        "foreground": {
          "$ref": "#/$defs/hexColor",
          "description": "Default text color."
        },
        "input": {
          "$ref": "#/$defs/hexColor",
          "description": "Input field background."
        },
        "inputForeground": {
          "$ref": "#/$defs/hexColor",
          "description": "Input field text color."
        },
        "border": {
          "$ref": "#/$defs/hexColor",
          "description": "Border color for inputs and dividers."
        },
        "ring": {
          "$ref": "#/$defs/hexColor",
          "description": "Focus ring color."
        },
        "muted": {
          "$ref": "#/$defs/hexColor",
          "description": "Muted/subtle surface color."
        },
        "mutedForeground": {
          "$ref": "#/$defs/hexColor",
          "description": "Text color on muted surfaces."
        },
        "neutral": {
          "$ref": "#/$defs/hexColor",
          "description": "Neutral UI elements."
        },
        "shadow": {
          "$ref": "#/$defs/hexColor",
          "description": "Shadow color."
        },
        "danger": {
          "$ref": "#/$defs/hexColor",
          "description": "Error/destructive state color."
        },
        "success": {
          "$ref": "#/$defs/hexColor",
          "description": "Success state color."
        },
        "warning": {
          "$ref": "#/$defs/hexColor",
          "description": "Warning state color."
        }
      }
    }
  }
}