wearos-watchface-codex

name: wearos-watchface-codex description: create, port, audit, and debug wear os watch faces and complication providers for galaxy watch and pixel watch using watch face format, watch face studio, and complication data sources. use when coding agent must turn svg or design assets into a buildable watch face, make complication slots or providers appear in menus, add ambient or animation safely, or diagnose why a face installs but does not appear on gw7, galaxy watch, or pixel watch. especially use for wear os 5, 5.1, and 6 compatibility decisions, wff version selection, and resource-only packaging.

wear os watchface codex

Scope

This skill is wff-first. Use it to build or debug watch faces, not generic wear os apps.

When the user says "widget" on a watch face, assume complication unless tiles are explicitly requested.

Load the relevant references before acting:

• use references/version-matrix.md when the target device or os floor is unclear or mixed
• use references/gw7-diagnosis.md when a face installs but does not show in the face list, picker, or customize flow
• use references/provider-menu-checklist.md when a custom provider does not appear in the complication chooser
• use references/svg-pipeline.md when converting one svg into a real face or complication layout
• use references/source-map.md when exact docs, official samples, or community repos are needed

Non-negotiable rules

1. Treat gw7, gw ultra, and other watches launched with wear os 5+ as wff-only for fresh watch-face installs. Do not generate a jetpack WatchFaceService or wearable support library face for those requests.
2. Do not default to wff v4. Pick the lowest wff version that supports the requested features and the real minimum target os.
3. Keep the watch-face bundle resource-only. Put provider logic and general app logic in a separate module or app.
4. Do not try to solve "face not visible on gw7" by toggling random metadata first. Diagnose artifact type and wff/minSdk floor before touching Editable, Category, or slot settings.
5. Never invent wff xml. If tag or attribute syntax is uncertain, copy exact syntax from the official docs or the official sample.
6. Never claim that svg typography becomes live complication typography. Live complication text uses the system font.
7. Keep watch face, provider, and watch face push responsibilities separate. Watch Face Push is optional and is not the fix for ordinary picker visibility.

Workflow decision tree

1. Classify the request:
   • build or port a face -> follow build or port a face below
   • debug gw or pw visibility -> follow diagnose invisible face below
   • fix complication slot menu -> follow fix slots in editor below
   • fix provider menu -> follow fix provider chooser below
   • convert one svg -> follow svg pipeline below
2. Choose the compatibility floor using references/version-matrix.md.
3. Ship the smallest correct deliverable: face module only, or face plus separate provider app.
4. Validate on the named device class before adding polish.

Build or port a face

1. Start from the official wff project shape:
   • AndroidManifest.xml
   • res/raw/watchface.xml
   • res/xml/watch_face_info.xml
   • preview asset
2. For simple projects, keep the face definition in res/raw/watchface.xml. Do not rename the default file unless you also manage shapes and file mapping intentionally.
3. In AndroidManifest.xml:
   • include uses-feature android.hardware.type.watch
   • set android:hasCode="false"
   • set android:label
   • add com.google.wear.watchface.format.version
4. In watch_face_info.xml:
   • always set Preview
   • set Editable=true only when the face actually has settings or non-fixed complications
   • do not expect Editable to make an invisible face appear
5. Put all app logic outside the face bundle. If the request needs custom data, create a separate provider app.
6. Add ambient and aod early. Remove the second hand and simplify lit pixels.
7. Add complications only where geometry is real and readable.

Diagnose invisible face

Read references/gw7-diagnosis.md and follow this order exactly:

1. Is this actually a wff bundle?
2. Is the chosen wff version or minSdk too new for the minimum target device?
3. Is the face packaged as a separate resource-only bundle?
4. Are the core files present and named correctly?
5. Only after 1 to 4 pass, inspect watch-face metadata and picker behavior.

Use this symptom map:

• installs as an app, never becomes a selectable face -> wrong artifact type or wrong compatibility floor
• selectable face exists but no Edit button -> Editable problem, or no real settings or slots
• decorative slot frame exists but is not selectable -> not a real ComplicationSlot, or missing bounds or types
• provider app is installed but absent in chooser -> provider manifest or service problem, not face metadata

Fix slots in editor

A slot must be a real ComplicationSlot, not painted art.

Minimum conditions:

• Editable=true in watch_face_info.xml when slots are meant to be user-editable
• slot has slotId
• slot has supportedTypes
• slot has a bounding area
• slot has displayName
• slot renders at least one Complication per supported type
• total slots is at most 8

If the user used wfs, remember that complications are independent and cannot be grouped with other components.

Fix provider chooser

Use references/provider-menu-checklist.md.

Hard requirements:

• separate watch app or module
• SuspendingComplicationDataSourceService
• BIND_COMPLICATION_PROVIDER
• update-request intent filter
• SUPPORTED_TYPES
• UPDATE_PERIOD_SECONDS or explicit push strategy
• monochrome service icon
• useful getPreviewData()

Match provider types to slot types. Do not blame the face first when the provider is missing.

Svg pipeline

Use one svg as source of truth only if you convert semantics, not just pixels.

1. Preserve the original svg.
2. Extract or infer:
   • background art
   • hour, minute, second layers if analog
   • complication frames
   • slot geometry
   • ambient simplification
3. If the svg is flat and unlabeled, infer at most 1, 2, or 4 slots unless the geometry is unmistakable.
4. Prefer vector output for simple paths. Rasterize complex filters, masks, or blend-heavy art.
5. Build live complications with real ComplicationSlots. Do not bake fake live text into static svg art.
6. If custom data is requested in the picker, build a separate provider app.

For the exact layer-id contract and fallback extraction rules, load references/svg-pipeline.md.

Animation and ambient

Animation is optional. Ambient is not.

Rules:

• make time and complications readable before adding motion
• prefer transform-driven motion over frame-heavy loops
• stop or simplify animation in ambient
• never keep the second hand in ambient
• keep lit pixels low and assets small
• if using wfs, do not use lottie in current workflows

Wfs guardrails

Use wfs only when the user wants a visual-first workflow or .wfs deliverables.

Keep these constraints in mind:

• wfs faces still need the correct wff floor for the target device
• keep fewer than 8 visible complications in both normal and ambient modes
• no second hand in ambient
• no lottie in current wfs workflow
• avoid edge-hugging art because burn-in shifting can move it
• complications cannot be grouped with other components

Watch Face Push

Only use Watch Face Push when the user explicitly needs app-driven or marketplace-style installation.

Do not use it as a workaround for a normal face not showing up in the picker.

When used, keep it behind a wear os 6 capability check and keep the pushed face itself in wff.

Output contract

When building:

• return a buildable wff face module
• return a separate provider app only if custom data is required
• state the chosen compatibility floor explicitly: target os, wff version, and minSdk
• keep notes short and actionable

When auditing:

• patch the minimum files required
• explain whether the root cause is artifact type, compatibility floor, metadata, slots, or provider
• do not rewrite a correct wff face into a code-based face

Resource map

• compatibility and versioning: references/version-matrix.md
• gw7 invisibility diagnosis: references/gw7-diagnosis.md
• provider chooser checklist: references/provider-menu-checklist.md
• svg conversion contract: references/svg-pipeline.md
• docs and repo references: references/source-map.md

Default stance

Prefer the officially documented wff path, the lowest compatible wff version, a separate provider app when needed, and conservative slot geometry. On gw7-class devices, "face never appears in downloaded faces" is usually not a cosmetic metadata bug; treat it as a format, version, or package-structure problem first.