# Wearos Watchface Codex

> 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.

- Skill: `kerneldroid/wearos-watchface-codex` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add kerneldroid/wearos-watchface-codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kerneldroid/wearos-watchface-codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kerneldroid (https://skillmd.com/u/kerneldroid)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kerneldroid/wearos-watchface-codex

---


# 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](references/version-matrix.md) when the target device or os floor is unclear or mixed
- use [references/gw7-diagnosis.md](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](references/provider-menu-checklist.md) when a custom provider does not appear in the complication chooser
- use [references/svg-pipeline.md](references/svg-pipeline.md) when converting one svg into a real face or complication layout
- use [references/source-map.md](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](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](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](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 `ComplicationSlot`s. 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](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](references/version-matrix.md)
- gw7 invisibility diagnosis: [references/gw7-diagnosis.md](references/gw7-diagnosis.md)
- provider chooser checklist: [references/provider-menu-checklist.md](references/provider-menu-checklist.md)
- svg conversion contract: [references/svg-pipeline.md](references/svg-pipeline.md)
- docs and repo references: [references/source-map.md](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.