Workbuddy dream skin skill

WorkBuddy Dream Skin

Create polished WorkBuddy skins and inject them with the tested safe runtime. Preserve app behavior before visual ambition.

Required workflow

1. Inspect WorkBuddy, references, and any existing theme project.

2. Confirm the installed WorkBuddy executable and version. Default to %LOCALAPPDATA%\Programs\WorkBuddy\WorkBuddy.exe.

3. Infer one host appearance from the reference image or user request: light or dark. If neither clearly indicates one, choose the mode that best supports the requested palette and state the choice. A skin must target exactly one appearance, never both.

4. Classify rights before generation: use original-personal-use only when the creator owns the theme identity and all included assets; use fan-noncommercial for celebrities, photographs, existing characters, franchises, trademarks, or other third-party IP. AI-generated imagery does not convert third-party characters or likenesses into owned IP.

5. Audit visible pages and stable classes in the selected WorkBuddy appearance. Cover new task, assistant/知柚, projects, experts/connectors, automation, more/files, menus, and account panel.

6. Define a coherent visual system: palette, typography, spacing, surfaces, illustration safe zones, interactive states, and responsive behavior.

7. For user-requested movie, IP, character, or highly specific visual themes, redesign the main workspace background, sidebar background, and component styling instead of directly cropping, recoloring, or otherwise reusing provided reference screenshots as final assets. Use references only for mood, composition, subject cues, and palette.

8. Generate all project-bound raster image assets for those themes with the imagegen skill/tool before using them in the skin. Keep UI text and controls out of background images.

9. For deep customization, capture the live WorkBuddy DOM through a one-time Console/CDP read and turn it into a selector map before writing page-specific CSS:

   node scripts/extract_selector_map.mjs --port 9222 --page welcome --output dom-audit/selector-map.json
   python scripts/generate_theme_from_selector_map.py --selector-map dom-audit/selector-map.json --theme-id <id> --theme-name "<name>" --theme-kind <light|dark> --license-type <original-personal-use|fan-noncommercial> --output <folder>
   

   This is an audit/generation step only. Do not leave a websocket attached, do not poll /json, and do not install DOM observers for persistence.

10. Scaffold the runtime with:

python scripts/scaffold_theme.py --theme-id <id> --theme-name "<name>" --theme-kind <light|dark> --license-type <original-personal-use|fan-noncommercial> --output <folder>

11. Implement the theme in themes/<id>/theme.css, register assets in theme.json, and keep the required themeKind, author, official-source, contact, licenseType, and licenseFile metadata.
12. Launch through the generated .cmd; switch WorkBuddy through its native appearance control, tolerate the expected renderer reload, verify the persisted appearance, then reconnect and inject CSS. Never edit app.asar or packaged application files.
13. Verify visual quality and real interaction with mouse/keyboard in the declared appearance, not DOM inspection alone.
14. Package the finished skin as a manager-compatible .wbskin when the workspace has workbuddy-skin-manager/scripts/package-wbskin.mjs:

npm --prefix workbuddy-skin-manager run pack:wbskin -- <theme-folder> <output.wbskin>

15. Test restore, then launch again so the final state matches the user's request.

Read references/licensing.md before selecting a license type or distributing a skin.

Non-negotiable safety rules

• Never modify, unpack, repack, replace, or patch resources/app.asar.
• Never overwrite WorkBuddy's bundled CSS or JavaScript.
• Connect to CDP only for initial injection or an explicit local CSS save.
• Never poll /json, periodically scan targets, or keep a CDP websocket attached.
• Never install a document-wide MutationObserver for theme persistence.
• Never force WorkBuddy's own light/dark classes, VS Code theme attributes, or React state. Appearance binding must invoke WorkBuddy's native light/dark control and verify its persisted agent-ui-theme value.
• Inject one <style data-workbuddy-theme> and only add a dedicated body data attribute.
• Do not use backdrop-filter, fixed background attachment, or large translucent GPU layers unless separately proven stable in the installed Electron version.
• Do not animate transform on [role="menu"], [role="listbox"], [role="dialog"], Radix/Floating UI roots, or other positioned popup roots. Their inline transform is their anchor coordinate.
• Keep generated .ps1 and .cmd runtime files ASCII-only for Windows PowerShell 5.1 compatibility. Theme CSS and docs may use UTF-8.

Read references/safety-and-injection.md before creating or changing the injector.

Design rules

• Treat illustrations as backgrounds, not screenshots: no baked-in buttons, labels, fake inputs, or menus.
• Reserve low-contrast safe zones for real headings, controls, and message content.
• Scope every rule under body[data-workbuddy-theme="<id>"].
• Enforce one decoration owner per visual region. The outer card may own its background, radius, border, and shadow; its header, identity block, content, and tag-list wrapper stay borderless by default.
• Treat cards as first-class themed surfaces, not host leftovers. Project template cards, expert cards, expert-team cards, featured-scene cards, automation cards, file/library cards, and quick-action cards must use the skin's declared card palette, border, shadow, icon, muted-text, tag, and hover treatment. Do not leave pale host cards floating on a dark illustrated theme, or dark host cards floating on a light illustrated theme, unless that contrast is an explicit part of the visual system and all descendants are readable.
• When card selectors are hashed or version-specific, inspect the live DOM and target the narrow page-scoped outer card selectors, such as project/template card roots and .ec-expert-card / .ec-featured-scene-card. Avoid broad global [class*="card"] fixes unless they are scoped to a semantic page root and verified against chat, dialogs, files, and menus.
• Never draw the same edge with parent and child borders, border plus outline, a border-colored shadow, a border pseudo-element, SVG, or background artwork. Preserve outline only when it is a distinct keyboard focus indicator.
• Use ::before and ::after for light, gradients, shadows, or atmosphere only. Do not generate a rounded outline that coincides with the component edge.
• Individual tags may own capsule borders; the tag-list/footer wrapper must not add a second long capsule around them.
• Prefer stable semantic classes; use partial CSS-module selectors only when necessary and keep them narrowly scoped by page.
• Preserve pointer events, stacking contexts, overflow behavior, focus rings, and portal positioning.
• Add hover and pressed states to triggers, but avoid transforms on triggers that anchor popups when positioning proves sensitive.
• Preserve card click behavior. Expert and expert-team cards must still open their details; if clicking only shows a translucent black overlay, restore the native dialog behavior before continuing visual work. Do not disable dialog-root animations globally, make dialog surfaces transparent, cover dialog content with decorative pseudo-elements, or alter portal/popup pointer events/z-index/positioning for card detail modals.
• Keep code blocks readable and message surfaces opaque enough for long-form assistant content.
• Treat light and dark appearance as separate host states, but support only the themeKind declared by this skin. When changing a surface color, inspect the computed color of its direct text, icon, muted-text, badge, and button descendants in that state; host rules often set these explicitly and stop inheritance.
• Trace every large background through its visible ancestor chain. Inner page roots and split-grid items can remain opaque even when .main-content has the intended artwork.
• Make decorative page topbars transparent only with page- or semantic-class selectors, then explicitly preserve readable title, action, and icon colors.

Read references/design-and-dom.md when auditing pages or building CSS.

Runtime selection

Use assets/runtime-template/ through scripts/scaffold_theme.py. The template provides:

• safe one-time CDP injection;
• local CSS/manifest file watching without periodic WorkBuddy scans;
• PowerShell 5.1-compatible launch and restore scripts;
• explicit --remote-debugging-port launch;
• clean style removal without touching packaged files.

If the user already has a theme project, compare its runtime against the template and patch only the unsafe differences. Preserve their visual assets and unrelated edits.

Console DOM selector pipeline

Use scripts/extract_selector_map.mjs when a skin needs deeper matching than screenshots and known classes provide. It connects to the current WorkBuddy renderer through CDP, evaluates one read-only DOM expression, writes a JSON snapshot, and disconnects. The snapshot groups selectors into buckets such as sidebar, topbar, welcome, chat, composer, cards, menus, dialogs, and Markdown.

Use scripts/generate_theme_from_selector_map.py to turn that snapshot into a normal runtime project. It calls scaffold_theme.py, copies the selector map into themes/<id>/dom-audit/selector-map.json, annotates theme.json, and appends a starter CSS layer with scoped selectors. Treat generated selectors as a first draft: inspect them, narrow risky selectors, and remove sections that were not visible during capture.

Capture multiple maps when the target skin covers multiple pages or menus. Store them under dom-audit/ and merge selectors manually into the theme CSS after reviewing them. Never rely on the selector map alone for final acceptance; the verification gate still requires real interaction and screenshots.

Verification gate

Do not claim completion until all relevant checks pass:

• New task page accepts input and its buttons work.
• Assistant/知柚 page accepts typed text; remove test text without sending.
• Add/function menu opens beside its trigger.
• Model menu opens beside the model trigger.
• Workspace menu opens beside the workspace trigger.
• Account/晓阳 menu opens beside the account trigger.
• The manifest's single declared appearance is selected automatically and passes the relevant page, sidebar, card, topbar, and account-menu contrast checks.
• Project template cards, expert cards, expert-team cards, and featured-scene cards are visually integrated with the theme instead of retaining unmatched host light/dark cards; titles, descriptions, avatars/icons, muted metadata, tags, badges, and summon/action buttons are readable in the declared appearance.
• Clicking expert and expert-team cards opens the full detail dialog or panel, not only a dim overlay. The dialog surface, title, content, close control, summon/action controls, and scrollable body remain visible and interactive.
• Dialogs, listboxes, dropdowns, and notifications do not jump to the top-left.
• No black rectangles, frozen skeletons, blocked clicks, or continuous CDP warnings appear.
• Restore removes the theme; relaunch applies it again.
• Finished skin exports as a .wbskin package that re-imports into WorkBuddy Skin Manager.
• Packaged .wbskin and standalone ZIP files exclude DOM audits, logs, PID files, path records, and other local runtime residue.
• Every distributed skin includes LICENSE.txt; third-party IP notices must not claim ownership of characters, likenesses, photographs, trademarks, or source material.
• python scripts/audit_duplicate_decorations.py themes/<id>/theme.css passes, and visual review confirms no nested rounded frames, double outlines, framed tag groups, or decoration covering primary content.
• app.asar remains untouched.

Use references/qa-checklist.md for the complete test sequence and failure mapping.

Repair priorities

1. Restore interaction and popup positioning.
2. Remove unsafe observers, scans, filters, animations, and stacking changes.
3. Re-test assistant input and account menu.
4. Re-introduce visual styling incrementally.
5. Keep a known-good screenshot and injection log with the theme project.

When a WorkBuddy update changes class names, audit the live DOM again and update only selectors. Do not broaden selectors globally to compensate.

Read references/field-lessons.md before refining a skin from screenshot feedback or changing launcher, manager, selector-map, or packaging behavior.