gcwing OpenBitFun Appearance Authoring
Use this Skill as the authority for what a OpenBitFun skin may change and how that change is represented. Let the user's assets, product direction, and the selected example determine the visual design.
The bundled registry and package references define capabilities. Files under examples/ define optional style choices; they never expand the contract or prescribe coverage for another skin.
Route the task
- For a new or repaired package, read authoring-workflow.md and package-contract.md.
- For renderer configuration, also read renderer-contracts.md.
- For generated video or WebP assets, also read media-quality-policy.md.
- For a style-specific design, load only the closest example after reading the parent workflow.
- For import failures, inspect the issue path, query that surface, and repair the sparse manifest instead of copying another package.
- For OpenBitFun contract changes, synchronize the registry before changing examples or skins.
Discover the exposed surface
Run commands from this Skill directory:
python scripts/openbitfun_appearance.py contract list components
python scripts/openbitfun_appearance.py contract list scenes
python scripts/openbitfun_appearance.py contract list renderers
python scripts/openbitfun_appearance.py contract show components <component-id>
python scripts/openbitfun_appearance.py contract show scenes <scene-id>
python scripts/openbitfun_appearance.py contract properties
python scripts/openbitfun_appearance.py contract tokens theme
python scripts/openbitfun_appearance.py contract tokens widget
Only author registered surfaces, Parts, facets, states, renderer adapters, tokens, and Style IR properties returned by these commands. A Part descriptor may further restrict its allowed properties.
A component owns only the Parts returned for that component. Nested visual owners expose their own component ids and must be styled through those ids. Do not infer Parts from DOM structure, another skin, or an example surface plan.
Surface-level states may use an ancestorPart selector rooted at root. Define the state rule using the registered state id; do not reproduce host selectors in the package.
Important independent owners include toolbar-mode, floating-mini-chat, session-menu, composer-voice-input, miniapp-bubble-welcome, session-title-config, assistant-card, workspace-item, external-mcp-overview, miniapp-customize-panel, user-message-edit-composer, voice-input-diagnostics, flow-chat-turn-rail, copyable-text-preview, reasoning-preset-selector, reasoning-config-panel, reasoning-preset-editor, market-account-controls, and miniapp-market-view. Query each owner before styling it. This list is a navigation aid, not an exhaustive contract; the registry is authoritative.
The following Parts are not registered and must not be used:
toolbar-mode.inputtoolbar-mode.sessionMenufloating-mini-chat.inputfloating-mini-chat.inputBarfloating-mini-chat.sessionMenu
Author a sparse package
Initialize the smallest valid overlay:
python scripts/openbitfun_appearance.py init <project-dir> --id <id> --name "<name>" --mode <light-or-dark>
Edit <project-dir>/appearance.json and declare only the values the skin needs to change. OpenBitFun merges the package over its built-in light or dark Appearance.
Packages may contain PNG, JPEG, WebP, and GIF images. MP4 or WebM is allowed only through top-level backgroundMedia, and every video requires an image poster. CSS files, selectors, markup, scripts, fonts, remote URLs, SVG, and executable content are unsupported.
Select a style example
Currently bundled:
| Example | Load when | Do not inherit blindly |
|---|---|---|
| cinematic-animated-wallpaper | Animated character artwork, source-derived glass materials, image-led cards, or illustrated dialogs | Its asset roles, crop defaults, palette, and selected surface plan |
Read style-example-contract.md before adding or restructuring an example. An example is a design recipe validated against the registry, not a second contract snapshot.
Validate importability
python scripts/openbitfun_appearance.py validate <project-dir>
python scripts/openbitfun_appearance.py build <project-dir> --output <skin>.openbitfun-appearance
python scripts/openbitfun_appearance.py validate <skin>.openbitfun-appearance
python scripts/openbitfun_appearance.py inspect <project-or-archive>
When a OpenBitFun checkout is available, verify with the production registry, Validator, Compiler, and packaged-video display-dimension probe:
python scripts/verify_host.py <openbitfun-repo> <skin>.openbitfun-appearance --report <host-verification.json> --strict-warnings
Standalone validation proves package and bundled-registry compatibility. Host verification proves the selected checkout accepts and compiles the package. Neither proves runtime visual quality; import the skin and inspect the actual surfaces.
Reuse deterministic support
Example authors may import:
scripts/build_support.pyfor JSON, hashing, package initialization, validation, archive creation, host verification, build-record checks, and runtime checklist creation.scripts/media_support.pyfor video probing, contact sheets, robust frame extraction, normalized crops, WebP output, VP9 encoding, preview sheets, and host video limits.
Keep style-specific asset roles, crop decisions, palettes, material construction, renderer choices, surface selection, and runtime checks inside the example.
Maintain the registry
Treat the bundled registry as the offline authority. Confirm it before targeting a checkout:
python scripts/sync_registry.py <openbitfun-repo> --check
The check compares the exported Appearance contract, not provenance-only commit or timestamp fields. Unrelated OpenBitFun commits do not invalidate a compatible snapshot.
Refresh it only from a clean checkout after OpenBitFun changes Appearance descriptors:
python scripts/sync_registry.py <openbitfun-repo>
Do not hand-edit references/appearance-registry.json. Use --allow-dirty only for local investigation, never for a distributed snapshot.