workbuddy-theme-studio

name

workbuddy-theme-studio

description

Create, study, edit, adapt, iteratively improve, package, verify, import, and preview visual theme assets for WorkBuddy Skins and WorkBuddy. Use when Codex needs to learn transferable design mechanisms from excellent references without copying them; turn a reference image, photo, mood board, style description, or existing artwork into a safe signed `.wbtheme`; generate hero and light/dark previews with Agent image tools; derive accessible palette tokens; run evidence-based optimization loops; maintain a provenance-aware design memory; export or troubleshoot a WorkBuddy Skins theme; or install and apply a finished theme for visual QA.

WorkBuddy Theme Studio

Act as a creative director, evaluator, and release engineer. Convert intent and references into a controlled design system, generate a coherent data-only WorkBuddy theme, improve it through evidence-based critique, and prove the exported package is valid and usable.

Load only the needed references

• Read references/creative-direction.md before analyzing or generating artwork.
• Read references/design-learning-loop.md before studying references, using design memory, scoring a result, or iterating.
• Read references/theme-contract.md before writing theme files or exporting a package.
• Read references/ui-grammar.md before choosing layout or component styling.
• Read references/visual-qa.md before judging previews or applying a theme.

Workflow

1. Inspect the target and inputs

1. Locate the WorkBuddy Skins repository and workbuddy-skins-cli. Prefer an existing release binary; otherwise build the workspace CLI.
2. Inspect every supplied reference image before editing or generation.
3. Inspect any existing theme source, manifest, palette, package, or WorkBuddy screenshot.
4. Ask only for decisions that materially change the result. Infer a safe working direction from the product context when possible.

2. Study references without copying

For each reference, separate content from transferable mechanism. Record provenance, rights status, observed composition, hierarchy, material, light, color, motion cues, craft decisions, anti-patterns, and the boundaries that prevent literal imitation.

Search the project design-memory directory for applicable confirmed rules before inventing a new direction. Treat memory as evidence, not authority: apply a rule only when its context matches the current job. Never promote brand identifiers, artist identity, characters, logos, confidential data, or a source's unique composition into reusable memory.

3. Write design declarations

Record these decisions before generating:

• user intent and target audience
• production or director mode
• Creative Deviation level 0–5
• subject and narrative hierarchy
• one primary visual subject, its normalized focal point, and responsive crop priority
• Style DNA: line language, material, composition, lighting, color, and mood
• elements that must be preserved, removed, or avoided
• light/dark palette strategy
• asset provenance and license status
• all eight adaptive UI grammar fields and the closest comparison theme

Also declare the primary WorkBuddy job, content safe zones, palette semantics, allowed visual primitives, forbidden motifs, package constraints, evaluation gate, and success evidence. If a required token or theme slot does not exist, record the gap instead of inventing an unsupported field.

Do not imitate a living artist by name. Translate references into observable visual attributes. Preserve identity, logos, text, or product details only when the user authorizes them.

Choose UI grammar from the theme's job, composition, and material—not by recoloring the last theme. Before assembly, compare it with the closest existing theme and require at least three differing grammar fields, normally including layoutPreset or quickActionStyle.

4. Create the hero artwork

Use the available Agent image-generation or image-editing tool for visual creation. For edits, inspect the source first and include all target images through the tool's supported reference mechanism.

Generate the hero as a wide composition designed for 2168 × 725 pixels. Keep important subjects and high-frequency detail away from likely text and control zones. Request no embedded UI, buttons, logos, watermarks, or small text unless explicitly required.

After generation, identify the primary subject center as integer x/y percentages. Preview background-size: cover crops at 3:1, 16:9, and 1:1; adjust the focal point or artwork until the subject remains legible in all three. Never assume 50% 50% is correct merely because it is the CSS default.

Treat generation as an art pass, not a file-format pass. After generation, use deterministic local image tooling to crop or resize to the exact dimensions without stretching. Prefer PNG for graphic art and transparency, JPEG/WebP only when they materially reduce photographic size without visible damage.

5. Derive tokens and previews

1. Derive light and dark tokens from the artwork, then check readable contrast and semantic separation.
2. Keep the two appearances recognizably related; do not merely invert colors.
3. Create preview-light.png and preview-dark.png as honest previews of each appearance. Do not use the same preview for both unless they are visually indistinguishable by design.
4. Keep assets/hero.png, both previews, and the palette tokens consistent. If a palette or hero changes, regenerate both previews.

When an actual WorkBuddy screenshot is unavailable, render a restrained token-driven preview rather than duplicating the hero:

python3 <skill-dir>/scripts/render_theme_preview.py \
  --hero <hero.png> --palette <light-or-dark.json> \
  --appearance <light-or-dark> --output <preview.png>

6. Evaluate and optimize

Evaluate the delivered artifact, not the prompt or intention. Use the gate, weighted dimensions, blockers, issue routing, and stop conditions in references/design-learning-loop.md.

For each iteration:

1. Collect fresh evidence from the actual image, preview, structural validator, and—when authorized—the live app.
2. Score subchecks before dimension totals.
3. Identify blockers before polish opportunities.
4. Route the highest-impact issue to exactly one owner: brief, domain, craft, tokens, asset, preview, package, or evaluator.
5. Make one targeted change and preserve all passing invariants.
6. Re-evaluate with comparable evidence and log the delta.

Do not regenerate merely because the score is imperfect. Stop on gate pass, plateau, repeated blocker, or exhausted iteration budget. Escalate a declaration gap instead of hiding it with another prompt.

7. Assemble the source folder

Create a brief JSON following references/theme-contract.md, then run:

python3 <skill-dir>/scripts/assemble_theme.py \
  --brief <theme-brief.json> \
  --hero <hero.png> \
  --preview-light <preview-light.png> \
  --preview-dark <preview-dark.png> \
  --output <theme-source>

Use --replace only after confirming the exact output directory is disposable. The script refuses unsafe or incomplete inputs and never creates a signature.

8. Validate and export

Run the local source validator first:

python3 <skill-dir>/scripts/validate_theme_source.py <theme-source>

Run the design gate with a Python runtime that provides Pillow:

python3 <skill-dir>/scripts/audit_theme_design.py \
  <theme-source> --gate release \
  --compare-ui <closest-existing-theme-source> \
  --live-evidence <live-evidence.json> \
  --provenance-review <provenance-review.json> \
  --json-out <audit.json>

Treat every reported blocker as a failed gate. A release audit also requires live evidence and cleared provenance; do not downgrade it to prototype merely to obtain a pass.

For commercial release, record the human reviewer's role, date, decision, declaration, and review scope in a provenance-review JSON file. The reviewer may be the theme author when they explicitly accept responsibility for commercial-use and redistribution review. This record documents the decision; do not misrepresent it as independent legal advice.

Create a publisher key only when the user explicitly wants a new publisher identity. Never overwrite a key and never place a production secret inside the theme source, repository, .wbtheme, or delivery folder.

Pack with the guarded release script. It uses the official CLI, requires the publisher to exist in the same registry embedded by WorkBuddy Skins, and performs a real import into an isolated temporary store. A package is not deliverable unless this command succeeds:

python3 <skill-dir>/scripts/package_theme.py \
  <theme-source> <name>-<version>.wbtheme \
  --cli <workbuddy-skins-cli> \
  --key-id <publisher-key-id> \
  --secret-key <publisher.secret> \
  --publisher-registry <WorkBuddy Skins-repo>/dist/publishers.public.json

Do not bypass the registry check with a standalone public key: a cryptographically valid package from an unregistered publisher still cannot be imported by the distributed application. Export only the import-tested .wbtheme package and any explicitly requested public documentation; never export the signing secret.

9. Import, apply, and visually verify

Import with WorkBuddy Skins or workbuddy-skins-cli import. Applying a theme changes the live WorkBuddy appearance and may require restarting or attaching to WorkBuddy, so explain the effect and obtain authorization immediately before disrupting a running app.

Verify both light and dark modes across the home view and content-heavy routes. Confirm native navigation, cards, text, composer controls, keyboard focus, and click targets remain usable. Restore the official appearance if the result fails or the user asks to roll back.

Non-negotiable guardrails

• Keep .wbtheme data-only: JSON, PNG/JPEG/WebP, previews, metadata, license, and generated signature only.
• Never add CSS, JavaScript, HTML, fonts, remote URLs, scripts, executables, or native libraries.
• Never fabricate ownership or licensing. Mark unknown provenance and stop before commercial export.
• Never expose a signing secret in logs, prompts, screenshots, source control, or package contents.
• Never distort an image to fit. Crop with intent, expand with an image tool, or regenerate.
• Never approve a preview from visual appeal alone; run structural validation and package verification.
• Never present the generated preview shell as an exact WorkBuddy screenshot; label it as a token-driven preview until live QA replaces it.
• Keep expression subordinate to purpose: use Production Mode by default and increase Creative Deviation only when the brief justifies it.
• Never call model self-approval "learning." Promote a design rule only from explicit user judgment or repeated evidence across distinct themes.
• Never let learned rules silently override the current user's intent, accessibility, package safety, or product declarations.

Completion report

Return the creative mode and deviation level, reference mechanisms learned, optimization iterations and score deltas, unresolved declaration gaps, source directory, final .wbtheme path, verification result, public-key path used for verification, asset provenance status, and remaining visual caveats.