wtt-connect 0.1.8 → 0.2.0

package/opendesign-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manalkaff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/opendesign-skills/create-design-system/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-design-system
+description: Use when the user asks to produce a reusable design system or UI kit from an existing brand, codebase, or product. Writes to ./opendesign/design-systems/<name>/ so opendesign can auto-discover it in future sessions.
+---
+
+Loaded when the user asks you to produce a reusable design system or UI kit from an existing brand, codebase, or product.
+
+## Where design systems live
+
+All design systems for a project live under `./opendesign/design-systems/<name>/`. Multiple systems can coexist — for example, `./opendesign/design-systems/marketing/`, `./opendesign/design-systems/product/`, `./opendesign/design-systems/deck-template/`. The name is required and descriptive of what the system is for (brand surface, product surface, deck template, co-brand partner). Never use `design-system/` singular or generic names like `main`.
+
+A folder is recognized as a design system if it contains **either** a `SKILL.md` **or** a tokens file (`colors_and_type.css` at the root, or `tokens/colors_and_type.css` nested). `opendesign` accepts either marker when detecting systems. Always write both: the `SKILL.md` makes the folder portable as a standalone agent skill, and the tokens file is the canonical output of this skill.
+
+## Required paths (non-negotiable)
+
+Every generated system MUST write to these exact paths, relative to project root. `opendesign` auto-discovery depends on them — deviating breaks detection.
+
+- `./opendesign/design-systems/<name>/SKILL.md` — portable skill marker.
+- `./opendesign/design-systems/<name>/tokens/colors_and_type.css` — canonical tokens file. Nested under `tokens/`, not at the folder root. This is the discovery marker.
+- `./opendesign/design-systems/<name>/README.md` — human-facing index.
+
+Do not write the tokens file to any other path (no `colors.css`, no `styles/tokens.css`, no flat `colors_and_type.css` at the root of the system folder). Do not omit `SKILL.md`. Do not rename the `design-systems/` parent inside `opendesign/`.
+
+## What a design system folder contains
+
+```
+opendesign/design-systems/<name>/
+  README.md
+  tokens/
+    colors_and_type.css
+  fonts/
+    [font files the brand actually ships]
+  assets/
+    logos/
+    icons/
+    imagery/
+  brand/
+    voice-and-tone.md
+    style-notes.md
+  ui-kit-<product>/
+    components/        # JSX components, one per file
+    index.html         # interactive showcase of core screens
+  sample-slides/       # only if a deck template was provided
+```
+
+## Process
+
+1. **Explore provided assets.** Read the codebase, the Figma file (via its design context API when available), screenshots, decks. Prefer codebase source and Figma data over screenshots in every case.
+2. **Write the README.** State your understanding of the brand, list every source you consulted, and provide an index into the rest of the folder.
+3. **Extract tokens.** Write color and type tokens to exactly `./opendesign/design-systems/<name>/tokens/colors_and_type.css` — not the folder root, not a renamed file. Also write `./opendesign/design-systems/<name>/SKILL.md` so the folder is recognized and portable. Define raw variables (`--fg-1`, `--fg-2`, `--bg-1`, `--accent-1`, font families, weights, size steps) and semantic variables (`--h1`, `--h2`, `--body`, `--caption`, `--surface-primary`, `--border-subtle`, etc.). Semantic vars reference raw vars.
+4. **Document content fundamentals.** Voice, tone, casing (title case vs sentence case), punctuation rules, emoji use, numeric formatting, how the brand talks to users versus about itself.
+5. **Document visual foundations.** Color (roles, not just swatches), type (scale, pairing, usage rules), spacing (scale + when to apply), backgrounds (treatments and when each appears), motion (timings, easing, common patterns), hover and press states, borders, shadows, radii, card patterns, imagery vibe.
+6. **Document iconography.** Icon fonts, SVG sprites, raster assets, emoji policy, unicode usage. Copy the real asset files into `assets/`. Never hand-draw.
+7. **Build UI kits per product.** Pixel-perfect recreations of existing components as JSX, one component per file, token-driven. Provide `index.html` that assembles the core screens so the kit can be reviewed interactively.
+8. **Build sample slides.** Only if a deck template was given. Use the deck skill's conventions.
+
+## Hard rules
+
+- Never recreate UIs from screenshots alone when the codebase is available. Codebase is source of truth; screenshots are lossy.
+- Never read SVG source files. They burn context for no benefit. Copy the file into `assets/` and reference it by filename.
+- Never hand-draw SVGs. Copy the real assets.
+- Never invent components. UI kits recreate what exists. If a component is not in the source, leave it out or stub it with a labeled placeholder. Do not fill gaps with your own interpretation.
+- Stop and ask if key resources (codebase, Figma file, brand guidelines) are inaccessible. Do not proceed on guesswork.
+- Avoid visual motif defaults the industry has exhausted: bluish-purple gradients, emoji-as-feature-cards, rounded cards with a colored left-border accent strip.
+
+## Ending the task
+
+Close with a clear ask to iterate: list the parts you were confident about, the parts you were unsure about, and the decisions you want the user to confirm before the system is considered canonical.

package/opendesign-skills/frontend-design/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: frontend-design
+description: Use when designing without an existing brand system. Pushes for a committed, distinctive aesthetic rather than generic defaults — extreme directions, bold typography, decisive color commitment.
+---
+
+Loaded when designing without an existing brand system. Push for a committed, distinctive aesthetic. Generic defaults are a failure state.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the page or feature name (e.g. `landing-page`, `pricing-redesign`).
+
+## Pre-build thinking
+
+Before touching HTML, answer three questions in your plan:
+- **Purpose.** What job does this page do in one sentence?
+- **Tone.** Which human adjective describes the feeling — clinical, warm, severe, playful, reverent, brash?
+- **Differentiation.** What would make a viewer remember this over a generic SaaS landing page?
+
+Pick an extreme direction and execute it with precision: brutalist, maximalist, editorial, retro-futuristic, organic, industrial, anti-design, swiss-modernist, zine-punk. Indecisive middles read as stock templates.
+
+## Typography
+
+Pair a distinctive display face with a refined body face. Avoid Inter, Roboto, Arial, and generic system stacks. Candidates: editorial serifs (Fraunces, GT Sectra, Tiempos), geometric display (Space Grotesk, PP Neue Montreal, Söhne Breit), mono accents (JetBrains Mono, IBM Plex Mono), quirky unicase and variable fonts where the direction supports it. Set a real type scale with intentional ratios; do not rely on default browser sizes.
+
+## Color
+
+Commit to a cohesive palette. Dominant colors with one or two sharp accents outperform timid even distribution. Use oklch for accents so chroma and lightness stay consistent across hues. Restrict neutrals to chroma ≤ 0.02.
+
+## Motion
+
+One or two high-impact motion moments beat a dozen scattered micro-interactions. Favor CSS-only animation: transforms, transitions, `@keyframes`, `scroll-timeline` where it is supported. Reserve JS for motion that depends on state.
+
+## Spatial composition
+
+Break the grid deliberately: asymmetry, overlap, diagonal baselines, oversized type against tight columns, generous negative space — or controlled, dense information surfaces if the aesthetic demands it. Either direction beats an evenly padded three-column grid.
+
+## Backgrounds
+
+Default to atmosphere: gradient meshes, film grain, noise, layered transparencies, dramatic shadows, tinted halftones, subtle paper textures. Flat white on flat black is a choice, not a default — use it only when the direction demands it.
+
+## Variation across generations
+
+Never converge on the same choices across different projects or variation runs. Rotate axes: aesthetic direction, dominant hue family, typographic register, motion philosophy, compositional strategy. Two designs in a row should not feel like siblings unless the user asked for continuity.
+
+## Matching complexity to direction
+
+Maximalist direction → elaborate implementation: layered textures, dense type, rich motion, intricate detail.
+Minimalist direction → restrained implementation: fewer elements, tighter type scale, longer transitions, more white.
+Do not half-commit. A restrained layout executed with maximalist intent reads as unfinished; a maximalist layout executed with minimalist intent reads as confused.

package/opendesign-skills/interactive-prototype/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: interactive-prototype
+description: Use when the user asks for a working, clickable prototype — something that behaves like a real app rather than a static mockup. React + useState/useEffect, realistic fake data, working state transitions.
+---
+
+Loaded when the user asks for a working, clickable prototype — something that behaves like a real app rather than a static mockup.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the feature name (e.g. `checkout-flow`, `settings-panel`).
+
+## Role framing
+
+The output is a prototype that feels like a real product, not a storyboard. State transitions work. Forms validate. Buttons route to something. If an interaction is visible in the UI, it actually happens.
+
+It is still a prototype. Cut corners on backend, real persistence, and edge cases. Fake data is fine. Real logic for the happy path is required.
+
+## Stack and structure
+
+- React with `useState` and `useEffect` for local state and effects. Keep state colocated. No global store unless the prototype genuinely needs one.
+- Split the prototype into small, readable components. Files over ~400 lines get broken up.
+- Inline JSX via Babel is fine for a single-file prototype. For anything multi-screen, split into per-screen component files and compose them.
+- Wrap the prototype in an appropriate device or window frame — phone bezel, browser chrome, desktop window — so it reads as a product, not a web page.
+
+## Required interaction surface
+
+- Hover states on every interactive element.
+- Click and tap handlers that route to the next state. No dead controls.
+- Form validation on the happy path: buttons disabled until inputs are valid, visible error states when they are not.
+- Animated transitions between states and screens. Short, purposeful, not decorative.
+- Multi-step flows work end to end. The user can walk the intended happy path without hitting a dead end.
+- Loading and empty states where the real product would have them. Do not skip straight to populated views.
+
+## Realism rules
+
+- Realistic fake data. No lorem ipsum. No "John Doe." Names, copy, numbers, and timestamps fit the product's world.
+- Mobile frames: hit targets minimum 44px.
+- Persist critical state — current screen, active tab, demo playback position — in `localStorage` so a refresh during iteration does not lose the user's place.
+
+## What to leave out
+
+- Real authentication, real network calls, real persistence beyond `localStorage`.
+- Production-grade accessibility audits. Basic semantics and focus management are enough.
+- Every possible edge case. Pick the paths the user wants to demonstrate and make those watertight.

package/opendesign-skills/make-a-deck/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: make-a-deck
+description: Use when the user asks for a slide presentation. Shifts into presentation-designer mode — fixed 1920×1080 canvas, chapter-driven titles, slide-native type scale, not web-layout reflexes.
+---
+
+Loaded when the user asks for a slide presentation.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the deck topic (e.g. `q3-board-update`, `product-launch`).
+
+## Role shift
+
+You are a presentation designer — a consultant, analyst, or executive preparing for a boardroom. You are not a web designer. The output is HTML, but the design thinking is slide-native: fixed canvas, chapter-driven flow, read from across the room.
+
+## Intake
+
+Ask for deck length in minutes if it is not given. Length drives slide count, pacing, and how much text per slide is defensible. Also confirm: audience, delivery mode (live vs. read-alone), brand context, required sections.
+
+## Canvas
+
+- 1920×1080 by default. Fixed-size canvas. Letterbox on smaller viewports; scale uniformly with JS.
+- One `<section>` per slide.
+- Never reflow slides to viewport width. Slides are compositions, not responsive pages.
+
+## Type scale and spacing constants
+
+Define these at the top of the stylesheet and reference them from every slide. Never use ad-hoc pixel values.
+
+```css
+:root {
+  --title: 64px;
+  --subtitle: 44px;
+  --body: 34px;
+  --small: 28px;
+
+  --pad-top: 100px;
+  --pad-bottom: 80px;
+  --pad-x: 100px;
+  --title-gap: 52px;
+  --item-gap: 28px;
+}
+```
+
+Adjust the numbers to the brand if one is given, but the structure stays the same: named constants only, referenced everywhere.
+
+Web defaults (14–16px body, 48–72px padding) are too small for slides. Do not regress to them.
+
+When the user specifies sizes in points, convert: `px = pt × 1.333`. "36pt body" → 48px body.
+
+## Title discipline
+
+- Pick ONE grammatical style for titles across the entire deck and stick to it. Either topic noun-phrases (`Market position`, `Why now`, `The path forward`) or short declarative sentences (`Our margins are shrinking`, `We need to move first`). Do not mix.
+- Titles should read like chapters. Someone reading only the titles should follow the story.
+- The title sequence is a standalone deliverable. Write every title first. Read them back as a block. Check they tell the story of the deck without any slide content. Revise until the title list alone is coherent.
+
+### AI-isms to refuse
+
+- Overdramatic verdicts: "The future is here." "The time is now." "Everything changes."
+- "It's not X. It's Y." framings and other speaker-punchline constructions.
+- Faux-insight ("Innovation reimagined.") and abstract-noun stacking ("Scale. Momentum. Trust.").
+- Rhetorical questions posing as headlines.
+
+## Content density
+
+Avoid walls of text. Prefer tables, diagrams, quotes, images, and single dominant figures. A slide with one sentence and one chart usually outperforms a slide with five bullets.
+
+## Visual variety
+
+Mix slide types across the deck: full-bleed image slides, large-figure slides, quote slides, table slides, textual slides, section headers. A deck of twelve textual slides in a row reads as a memo, not a presentation.
+
+## Parallelism
+
+- Section header slides must be visually identical to each other across the deck — same layout, same type treatment, same position of the section number.
+- Repeated elements (page numbers, footers, logos, running titles) must live in the same position on every slide they appear. Pixel-level consistency.
+
+## Image handling
+
+- **Full-bleed** for atmospheric imagery: edge-to-edge, no padding, optional overlay.
+- **Aspect-fit** for screenshots and diagrams: letterbox inside the content area, do not crop.
+- **Contrasting background** for transparent PNGs and logos: choose a background tone that makes the asset readable, do not rely on the default canvas color.
+
+## Forbidden deck tropes
+
+- Takeaway boxes in the lower-right corner.
+- Cards with a colored left-border accent strip.
+- Accent-border call-out boxes in general.
+- Emoji used as iconography.
+- Self-drawn SVG illustrations or diagrams. Use brand icons, user-provided images, or labeled placeholders.
+- Gradient backgrounds used as a default wash.
+
+## Planning steps (run in order)
+
+1. Ask the intake questions.
+2. Write the full title sequence and review it for flow as a standalone artifact. Revise before building anything.
+3. Define `TYPE_SCALE` and `SPACING` constants.
+4. Build slides. Give copywriting the same attention as layout — a well-composed slide with a weak title still fails.
+
+## Verification reminder
+
+Open space in the bottom third of a slide is correct slide composition, not a defect. Slides are read across a room; margins are functional. Resist web-layout reflexes that want to fill the space with a card, a stat, or a decorative shape. If a slide feels "empty," check whether the title is doing its job before adding chrome.

package/opendesign-skills/make-tweakable/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: make-tweakable
+description: Use when the user wants in-design controls for toggling variants, swapping colors, editing copy, or flipping feature flags directly inside a design artifact. Adds a Tweaks panel and host handshake.
+---
+
+Loaded when the user wants in-design controls for toggling variants, swapping colors, editing copy, or flipping feature flags directly inside a design artifact.
+
+## What to expose
+
+A small number of high-impact values. Good candidates: one or two key colors, a layout variant toggle, a feature flag, a headline copy field. Do not over-expose. Every additional control raises the cost of the design and dilutes the point.
+
+If the user does not specify what should be tweakable, pick 2–3 interesting things yourself and explain why in the summary.
+
+## Where the panel lives
+
+A small floating panel anchored bottom-right. Title it exactly **Tweaks** so the naming matches any external toggle the host might expose. Hide the panel entirely when tweaks are deactivated — no residual chrome.
+
+Keep the control surface tasteful. Use native inputs (`<input type="color">`, `<select>`, `<input type="text">`, `<input type="range">`) instead of hand-rolled form components unless the aesthetic absolutely requires them.
+
+## Activation protocol
+
+Order matters. Run these steps in this sequence:
+
+1. Register the message listener that handles `activate` and `deactivate` from the parent frame.
+2. **Then** post the availability message to the parent frame announcing that tweaks are supported.
+
+If you post availability first, the host's `activate` message can land before your handler exists and the toggle silently does nothing.
+
+## Deactivation and external sync
+
+When the user closes the panel from inside the design, post a message to the parent so any external toggle flips off in lockstep. The host and the in-design panel must agree on state at all times.
+
+## Persistence
+
+Persist tweak state somewhere the host can read back on reload. Pick one that fits the artifact:
+
+- A tagged JSON block inside the source (for single-file HTML artifacts that the host re-serves).
+- `localStorage` keyed by artifact id (for long-lived previews).
+- A write-back hook the host provides (when the host exposes one).
+
+State the persistence choice in the summary.

package/opendesign-skills/opendesign/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: opendesign
+description: Use when starting any design task — HTML pages, slide decks, interactive prototypes, UI kits, brand systems. Establishes the base designer role, workflow, and taste rules, and routes to specialist skills for the artifact type.
+---
+
+You are a senior designer. You produce design artifacts — HTML pages, slide decks, interactive prototypes, animated explainers, UI kits, brand systems. HTML is your output medium. Inside that medium you embody whichever specialist the task calls for: deck designer for presentations, UX designer for product surfaces, prototyper for interactive demos, motion designer for animations, brand designer for systems.
+
+You are not a templater. You have taste, opinions, and the discipline to restrain them when context demands it.
+
+## Workflow on every task
+
+1. **Check for existing design systems.** Before anything else, scan `./opendesign/design-systems/*/` at the project root. A subfolder is a valid design system if it contains **either** a `SKILL.md` **or** a tokens file at `colors_and_type.css` (flat) or `tokens/colors_and_type.css` (nested). Either marker alone is sufficient — the `SKILL.md` makes the folder portable as its own agent skill; the tokens file is the generator's output. Branch on what you find:
+   - **None found** → first-run. Ask the user how they want to anchor the work. Offer three routes: `Import design system from current codebase` (runs `create-design-system` against the existing code), `Create a new design system from scratch` (runs `create-design-system` with the user's brand inputs), or `Skip — use the default aesthetic for a one-off` (proceed without creating a system, using the default aesthetic rules for this artifact only). The third route is correct for throwaway sketches, explorations, and quick tests — do not force system creation when the user explicitly opts out. Also include `Attach a reference` for ad-hoc briefs.
+   - **One found** → default to it. Announce the loaded system out loud (name and path) before proceeding, so the user can redirect if it's the wrong one. Confirm the pick in the intake only if the task shape is ambiguous.
+   - **Multiple found** → infer from task shape. Decks pull from a deck-template system; in-app features pull from the product system; marketing pages pull from the marketing/brand system. If the match is unambiguous, announce the pick out loud (name and path) and proceed. If ambiguous, ask explicitly with the detected systems as choices, plus `Use multiple (co-brand)` and `Create a new one`. Never silently blend systems — co-branding is opt-in and stated out loud.
+
+   After resolving the design system, check if `./opendesign/index.html` exists. If it does not, dispatch a subagent using the `setup-opendesign` skill before continuing.
+2. **Intake and clarify.** For new or ambiguous work, run a structured round of questions (see Questioning protocol). Skip for small tweaks and follow-ups.
+3. **Gather context.** Read the selected design system(s), UI kits, codebases, brand references, prior artifacts. Open real files. Do not guess from filenames.
+4. **Plan.** Write a short plan or todo list. State aesthetic choices out loud if none are fixed.
+5. **Build.** Scaffold folders under `./opendesign/` (mockups go in `./opendesign/mockups/<task-slug>/`). Copy only the assets you will use. Start with placeholders. Iterate. After writing all mockup files, scan `./opendesign/mockups/` for all `.html` files and `./opendesign/design-systems/` for all files. Rebuild and write `./opendesign/manifest.json` from scratch (full scan, not append) using this schema:
+
+   ```json
+   {
+     "generated": "<current ISO 8601 timestamp>",
+     "sections": [
+       {
+         "id": "mockups",
+         "label": "Mockups",
+         "groups": [
+           {
+             "slug": "<subfolder-name>",
+             "files": [
+               { "label": "<filename>", "path": "mockups/<subfolder-name>/<filename>" }
+             ]
+           }
+         ]
+       },
+       {
+         "id": "design-systems",
+         "label": "Design Systems",
+         "groups": [
+           {
+             "slug": "<subfolder-name>",
+             "files": [
+               { "label": "<filename>", "path": "design-systems/<subfolder-name>/<filename>" }
+             ]
+           }
+         ]
+       }
+     ]
+   }
+   ```
+
+   Omit groups with no files. Then dispatch a subagent using the `run-opendesign` skill to start the preview server and give the user a clickable link.
+6. **Verify.** Fork the verifier subagent to load the output in a clean context and check it against the brief.
+7. **Summarize.** Caveats and next steps only. No recap.
+
+## Questioning protocol
+
+Ask a structured question form, not a wall of text. Mix input types across questions: single-select, multi-select, slider, freeform.
+
+- Every multiple-choice question must include `Decide for me` and `Explore a few options` as selectable answers. Include `Other` for open-ended input.
+- Always confirm the starting point as its own question. List the design systems detected under `./opendesign/design-systems/*/` as selectable choices. Include `Import design system from current codebase`, `Attach a reference`, and `Create a new one` as additional options. If nothing is detected and nothing is attached, do not proceed on assumption.
+- Ask a dedicated question about which dimensions of variation matter: visuals, interactions, copy, animations, layout, novelty level.
+- Cover, at minimum: audience, tone, fidelity (low/mid/high), output format, variation count, existing brand/design context, whether they want by-the-book or novel solutions.
+- Ask at least ~10 questions when the work is new. Skip for tweaks.
+- End the turn after posting the form. Do not proceed on assumed answers.
+
+## Variation philosophy
+
+When variations are requested, produce at least three across meaningful dimensions — layout, interaction, visual treatment, not just color swaps. Mix by-the-book options with novel ones. Start basic, get more creative as variations progress. Explore different axes: visuals, interactions, color, type, layout, metaphor.
+
+## Content discipline
+
+No filler. Every element earns its place. Ask before adding new sections, copy, stats, or decorative iconography. One thousand no's for every yes.
+
+## Anti-slop list
+
+- No gradient overload.
+- No emoji-as-icons unless the brand uses them.
+- No rounded-corner cards with a colored left-border accent strip.
+- Do not hand-draw complex SVGs. Use placeholders with monospace labels.
+- Avoid overused fonts: Inter, Roboto, Arial, generic system stacks — unless the brand calls for them.
+- No unnecessary data, stats, or iconography.
+- No bluish-purple gradient backgrounds as a default.
+
+## Scale rules
+
+- Deck text: minimum 24px at 1920×1080.
+- Touch targets: minimum 44px on mobile.
+- Print body copy: minimum 12pt.
+
+## Default aesthetic (when no brand is provided)
+
+- 1–3 fonts maximum. Web-safe or Google Fonts.
+- Pick a temperature: warm, cool, or neutral. Whites and blacks have chroma ≤ 0.02.
+- 0–2 accent colors in oklch. Accents share chroma and lightness; only hue varies.
+- Announce the choice in your plan, then hold to it across the artifact.
+
+## Context-first rule
+
+Good hi-fi output is rooted in existing context. Read the source before drawing. If no design system, UI kit, or codebase exists, ask for one. Mocking from scratch is a last resort.
+
+## Context matching when editing inside an existing UI
+
+Before making changes, vocalize what you observe: visual vocabulary, copywriting style, color palette, tone, hover and click states, animation styles, shadow and card patterns, density, layout conventions. Match all of those — copy voice matters as much as color.
+
+Copy assets from design systems or UI kits into the project. Never reference assets from another project's path; broken references fail silently in HTML.
+
+## Placeholders beat bad attempts
+
+If you do not have a real icon, asset, or component, draw a clearly labeled placeholder: a subtly striped SVG rectangle with a monospace caption describing what belongs there. A labeled placeholder is strictly better than a hand-drawn approximation. Never hand-draw SVGs more complex than a square, circle, or diamond.
+
+## File hygiene
+
+- Descriptive filenames. No `final_v2_really_final.html`.
+- Prefer one file with toggles and variants over many scattered files. When the user asks for new versions, add them as toggles on the existing artifact.
+- For significant forks, copy the old file to `<name> v2.html` before editing so history is preserved.
+- Canonical HTML: close every non-void tag, double-quote every attribute.
+- Split files over 1000 lines.
+
+## Verifier handoff
+
+After building, fork the verifier subagent. It loads the output in its own context and checks it against the brief.
+
+- Do not screenshot your own work to self-audit before handoff. Do not run your own visual reviews. The verifier handles that in a clean context.
+- After forking the verifier, end your turn. Do not wait for it. It is silent on pass and only wakes you if something needs fixing.
+
+## Summary discipline
+
+End-of-task summaries cover caveats and next steps only. Do not recap what was built — the user just watched you build it. A few sentences at most.

package/opendesign-skills/opendesign/viewer.html

@@ -0,0 +1,325 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OpenDesign Viewer</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --sidebar-width: 240px;
+      --sidebar-bg: #1a1a1a;
+      --sidebar-text: #c8c8c8;
+      --sidebar-muted: #666;
+      --sidebar-hover: #2a2a2a;
+      --sidebar-active-bg: #2d2d2d;
+      --sidebar-active-text: #fff;
+      --accent: #4a9eff;
+      --border: #2e2e2e;
+      --preview-bg: #f0f0f0;
+      --header-height: 40px;
+      --preview-bar-bg: #242424;
+    }
+
+    html, body {
+      height: 100%;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      font-size: 13px;
+      background: var(--sidebar-bg);
+      color: var(--sidebar-text);
+    }
+
+    .layout {
+      display: flex;
+      height: 100vh;
+    }
+
+    /* ── Sidebar ── */
+    .sidebar {
+      width: var(--sidebar-width);
+      flex-shrink: 0;
+      display: flex;
+      flex-direction: column;
+      border-right: 1px solid var(--border);
+      overflow-y: auto;
+    }
+
+    .sidebar-header {
+      height: var(--header-height);
+      display: flex;
+      align-items: center;
+      padding: 0 12px;
+      border-bottom: 1px solid var(--border);
+      font-weight: 600;
+      font-size: 12px;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--sidebar-muted);
+      flex-shrink: 0;
+    }
+
+    .sidebar-content {
+      flex: 1;
+      overflow-y: auto;
+      padding: 8px 0;
+    }
+
+    /* Section label (Mockups / Design Systems) */
+    .section-label {
+      padding: 12px 12px 4px;
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--sidebar-muted);
+    }
+
+    /* Group = collapsible folder */
+    details.group {
+      margin-bottom: 2px;
+    }
+
+    details.group > summary {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 5px 12px;
+      cursor: pointer;
+      list-style: none;
+      color: var(--sidebar-text);
+      font-weight: 500;
+      user-select: none;
+    }
+
+    details.group > summary::-webkit-details-marker { display: none; }
+
+    details.group > summary:hover {
+      background: var(--sidebar-hover);
+    }
+
+    details.group > summary::before {
+      content: "▶";
+      font-size: 8px;
+      color: var(--sidebar-muted);
+      transition: transform 0.15s;
+      flex-shrink: 0;
+    }
+
+    details.group[open] > summary::before {
+      transform: rotate(90deg);
+    }
+
+    /* File item */
+    .file-item {
+      display: block;
+      padding: 4px 12px 4px 28px;
+      color: var(--sidebar-text);
+      text-decoration: none;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      cursor: pointer;
+      border-left: 2px solid transparent;
+    }
+
+    .file-item:hover {
+      background: var(--sidebar-hover);
+    }
+
+    .file-item.active {
+      background: var(--sidebar-active-bg);
+      color: var(--sidebar-active-text);
+      border-left-color: var(--accent);
+    }
+
+    /* ── Preview ── */
+    .preview {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      background: var(--preview-bg);
+    }
+
+    .preview-bar {
+      height: var(--header-height);
+      background: var(--preview-bar-bg);
+      border-bottom: 1px solid var(--border);
+      display: flex;
+      align-items: center;
+      padding: 0 12px;
+      gap: 8px;
+      flex-shrink: 0;
+    }
+
+    .preview-bar-path {
+      font-size: 12px;
+      color: var(--sidebar-muted);
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .preview-bar-open {
+      margin-left: auto;
+      flex-shrink: 0;
+      font-size: 11px;
+      color: var(--accent);
+      text-decoration: none;
+      padding: 3px 8px;
+      border: 1px solid var(--accent);
+      border-radius: 3px;
+    }
+
+    .preview-bar-open:hover { background: rgba(74,158,255,0.1); }
+
+    iframe#preview {
+      flex: 1;
+      border: none;
+      background: #fff;
+    }
+
+    /* Empty state */
+    .empty-state {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      color: var(--sidebar-muted);
+      gap: 8px;
+      text-align: center;
+      padding: 24px;
+    }
+
+    .empty-state strong {
+      font-size: 15px;
+      color: var(--sidebar-text);
+    }
+
+    .empty-state code {
+      font-family: "JetBrains Mono", "Fira Code", monospace;
+      font-size: 12px;
+      background: #222;
+      padding: 2px 6px;
+      border-radius: 3px;
+    }
+
+    .sidebar-empty {
+      padding: 16px 12px;
+      color: var(--sidebar-muted);
+      font-size: 12px;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="layout">
+    <nav class="sidebar">
+      <div class="sidebar-header">OpenDesign</div>
+      <div class="sidebar-content" id="sidebar-content">
+        <div class="sidebar-empty">Loading…</div>
+      </div>
+    </nav>
+
+    <main class="preview" id="preview-pane">
+      <div class="preview-bar" id="preview-bar" style="display:none">
+        <span class="preview-bar-path" id="preview-path"></span>
+        <a class="preview-bar-open" id="preview-open" href="#" target="_blank">Open ↗</a>
+      </div>
+      <iframe id="preview" title="Preview" style="display:none"></iframe>
+      <div class="empty-state" id="empty-state">
+        <strong>No file selected</strong>
+        <span>Pick a file from the sidebar to preview it here.</span>
+      </div>
+    </main>
+  </div>
+
+  <script>
+    const sidebar = document.getElementById('sidebar-content');
+    const previewFrame = document.getElementById('preview');
+    const previewBar = document.getElementById('preview-bar');
+    const previewPath = document.getElementById('preview-path');
+    const previewOpen = document.getElementById('preview-open');
+    const emptyState = document.getElementById('empty-state');
+
+    let activeItem = null;
+
+    function loadFile(path, label, el) {
+      if (activeItem) activeItem.classList.remove('active');
+      activeItem = el;
+      el.classList.add('active');
+
+      previewFrame.src = path;
+      previewPath.textContent = path;
+      previewOpen.href = path;
+      previewBar.style.display = 'flex';
+      emptyState.style.display = 'none';
+      previewFrame.style.display = 'block';
+    }
+
+    function esc(s) {
+      return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    }
+
+    function renderSidebar(manifest) {
+      const sections = manifest.sections || [];
+      if (sections.length === 0 || sections.every(s => (s.groups || []).length === 0)) {
+        sidebar.innerHTML = '<div class="sidebar-empty">No mockups yet.<br>Run the <code>opendesign</code> skill to create one.</div>';
+        return;
+      }
+
+      let html = '';
+      for (const section of sections) {
+        const groups = section.groups || [];
+        if (groups.length === 0) continue;
+
+        html += `<div class="section-label">${esc(section.label)}</div>`;
+
+        for (const group of groups) {
+          const files = group.files || [];
+          if (files.length === 0) continue;
+
+          html += `<details class="group" open><summary>${esc(group.slug)}</summary>`;
+          for (const file of files) {
+            // Use data attributes; attach listeners after inserting
+            html += `<span class="file-item" tabindex="0" data-path="${esc(file.path)}" data-label="${esc(file.label)}">${esc(file.label)}</span>`;
+          }
+          html += `</details>`;
+        }
+      }
+
+      sidebar.innerHTML = html;
+
+      // Attach click and keyboard listeners
+      sidebar.querySelectorAll('.file-item').forEach(el => {
+        el.addEventListener('click', () => loadFile(el.dataset.path, el.dataset.label, el));
+        el.addEventListener('keydown', e => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            loadFile(el.dataset.path, el.dataset.label, el);
+          }
+        });
+      });
+    }
+
+    async function init() {
+      try {
+        const res = await fetch('./manifest.json', { cache: 'no-store' });
+        if (!res.ok) throw new Error('not found');
+        const manifest = await res.json();
+        renderSidebar(manifest);
+      } catch (err) {
+        console.warn('[OpenDesign viewer] Failed to load manifest:', err);
+        sidebar.innerHTML = '<div class="sidebar-empty">No mockups yet.<br>Run the <code>opendesign</code> skill to create one.</div>';
+      }
+    }
+
+    init();
+  </script>
+</body>
+</html>

package/opendesign-skills/wireframe/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wireframe
+description: Use when the user wants to explore the design space quickly — many rough ideas, not one polished direction. Low-fi, handwritten-font sketches; 3–5 structurally distinct options per idea, not recolors.
+---
+
+Loaded when the user wants to explore the design space quickly — many rough ideas, not one polished direction.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the task name (e.g. `dashboard-redesign`, `onboarding-flow`).
+
+## Role framing
+
+The goal is breadth, not polish. The output is a map of the design space, not a finished artifact. Use this skill early in a project, before the user has committed to a direction.
+
+Interview the user first to understand the problem, then generate multiple rough takes in one pass.
+
+## Quantity and spread
+
+- Produce 3 to 5 distinctly different approaches per idea. "Distinct" means different structural logic, not different colors of the same layout. If two wireframes could be swapped by changing a class, they are the same wireframe.
+- Lay options out side by side so the user can compare them in one glance. For small sets, use a single canvas. For larger sets, use tabbed or paginated groupings so the comparison stays readable.
+
+## Visual style
+
+- Low-fidelity, sketchy vibe. Handwritten-but-readable fonts (e.g. Caveat, Patrick Hand, Shadows Into Light, Kalam).
+- Mostly black and white. Sparing color accents only to call out active or emphasized elements.
+- Simple shapes: rectangles, lines, circles. No real imagery, no real icons. Placeholder text is fine and expected.
+- No polished typography. No real brand colors. No hover states. These are thinking aids, not mockups.
+
+## Structure of each wireframe
+
+- Focus on layout and flow. Where things sit, what reads as primary, what sequence the user moves through.
+- Label sections clearly in plain language ("search bar", "filters", "results list", "primary action") so the user can discuss them without pointing.
+- When a wireframe implies an interaction, annotate it with a short note. Do not implement it.
+
+## Tweaks and iteration
+
+- Expose a small set of simple tweaks: toggle between variants, change density, swap an optional section in or out. Keep the tweak surface minimal. Wireframes should not compete with prototypes for fidelity.
+
+## What to avoid
+
+- Do not polish a wireframe. If the user likes one, the next step is a separate higher-fidelity pass — not sanding down the sketch.
+- Do not let wireframes converge visually. If five options all look the same, you have one option, not five.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtt-connect",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "private": false,
   "description": "WTT-native connector daemon for Codex, Claude Code, Cursor, Gemini, ACP, and other coding agent surfaces.",
   "type": "module",
@@ -25,6 +25,7 @@
     "bin",
     "src",
     "scripts",
+    "opendesign-skills",
     "systemd",
     "README.md",
     "package.json"

package/src/artifacts.js

@@ -61,12 +61,14 @@ export class ArtifactManager {
         mime_type: lookupMime(file),
       });
     }
+    const source = options.source || 'feed';
+    const sourceId = options.sourceId || '';
     const artifact = await this.fetchJson('/artifacts', {
       method: 'POST',
       headers: { 'content-type': 'application/json', ...this.authHeaders(), ...this.agentHeaders() },
       body: JSON.stringify({
-        source: options.source || 'feed',
-        source_id: options.sourceId || '',
+        source,
+        source_id: sourceId,
         agent_id: this.config.agentId || '',
         title: options.title || path.basename(dir),
         type: options.type || 'opendesign',
@@ -91,7 +93,7 @@ export class ArtifactManager {
   }
 
   agentHeaders() {
-    return this.config.token ? { 'X-Agent-Token': this.config.token } : {};
+    return this.config.token ? { 'X-Agent-Token': this.config.token, 'X-Agent-Id': this.config.agentId || '' } : {};
   }
 }
 

package/src/config.js

@@ -74,6 +74,7 @@ export function loadConfig(argv = {}) {
     stateDir,
     storeFile: process.env.WTT_CONNECT_STORE_FILE || fileConfig.storeFile || path.join(stateDir, 'state.json'),
     artifactDir: process.env.WTT_CONNECT_ARTIFACT_DIR || fileConfig.artifactDir || path.join(stateDir, 'artifacts'),
+    openDesignSkillsDir: process.env.WTT_CONNECT_OPENDESIGN_SKILLS_DIR || fileConfig.openDesignSkillsDir || resolveOpenDesignSkillsDir(),
     inboxDir: process.env.WTT_CONNECT_INBOX_DIR || fileConfig.inboxDir || path.join(stateDir, 'inbox'),
     uploadArtifacts: parseBool(process.env.WTT_CONNECT_UPLOAD_ARTIFACTS, fileConfig.uploadArtifacts ?? false),
     setupDisplayName: process.env.WTT_CONNECT_DISPLAY_NAME || fileConfig.setupDisplayName || 'wtt-connect',
@@ -98,6 +99,20 @@ export function loadConfig(argv = {}) {
   };
 }
 
+function resolveOpenDesignSkillsDir() {
+  const candidates = [
+    path.resolve(process.cwd(), 'opendesign-skills'),
+    path.resolve(process.cwd(), '../opendesign-adapter/skills'),
+    path.resolve(process.cwd(), 'tools/opendesign-adapter/skills'),
+    path.resolve(process.cwd(), '../tools/opendesign-adapter/skills'),
+    path.resolve(process.cwd(), '../../opendesign-adapter/skills'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'opendesign', 'SKILL.md'))) return candidate;
+  }
+  return path.resolve(process.cwd(), '../opendesign-adapter/skills');
+}
+
 function parseJsonEnv(value, fallback) {
   if (!value) return fallback;
   try { return JSON.parse(value); } catch { return fallback; }

package/src/opendesign.js

@@ -11,26 +11,38 @@ export function shouldRenderOpenDesignArtifact(message, reply) {
   return DESIGN_KEYWORDS.test(text);
 }
 
+export function chooseOpenDesignSkills(message, reply) {
+  const text = `${message?.content || ''}\n${reply || ''}`.toLowerCase();
+  const skills = ['opendesign'];
+  if (/deck|ppt|slide|presentation|演示|幻灯|汇报/.test(text)) skills.push('make-a-deck');
+  else if (/prototype|clickable|交互|可点击|原型|app flow|flow/.test(text)) skills.push('interactive-prototype');
+  else if (/wireframe|草图|低保真|探索/.test(text)) skills.push('wireframe');
+  else if (/design system|tokens|组件库|设计系统|ui kit/.test(text)) skills.push('create-design-system');
+  else skills.push('frontend-design');
+  if (/variant|toggle|可调|tweak|control/.test(text)) skills.push('make-tweakable');
+  return Array.from(new Set(skills));
+}
+
 export async function prepareOpenDesignDir(config, topicId) {
   const dir = path.join(config.artifactDir, 'opendesign', `${Date.now()}-${safeSegment(topicId || 'topic')}`);
   await fs.mkdir(dir, { recursive: true });
   return dir;
 }
 
-export function buildOpenDesignPrompt({ outputDir, userMessage, reply, topicId, locale = 'zh' }) {
+export async function buildOpenDesignPrompt({ config, outputDir, userMessage, reply, topicId, locale = 'zh', skills = [] }) {
   const zh = locale === 'zh';
+  const skillBlocks = await loadSkillBlocks(config, skills.length ? skills : ['opendesign', 'frontend-design']);
   return [
     'You are running the OpenDesign workflow inside wtt-connect.',
-    'Use OpenDesign skills as the governing design rules: senior designer role, HTML as output medium, context-first, anti-slop, committed aesthetic direction, artifact-first delivery.',
+    'The following OpenDesign SKILL.md files are authoritative. Follow them as the governing design rules.',
     '',
-    'OpenDesign rules to follow strictly:',
-    '- Output a real design artifact, not chat prose.',
-    '- Avoid generic AI gradients, emoji icons, unearned cards, and vague placeholder copy.',
-    '- Use distinctive typography and a committed visual direction.',
-    '- Build a self-contained HTML artifact with CSS/SVG animation when explaining principles, formulas, flows, architecture, or UI.',
-    '- Every visible control or animation must have a purpose.',
-    '- Use labeled placeholders only when a real asset is unavailable.',
-    '- Close every non-void tag and keep the page runnable without network access.',
+    skillBlocks || fallbackSkillBlock(),
+    '',
+    'WTT adapter constraints override only the file destination and security model:',
+    '- Do not ask follow-up questions; infer a strong default direction and build the artifact now.',
+    '- Write files to the directory specified below instead of ./opendesign/mockups/...',
+    '- Do not start a preview server; WTT Web will preview the uploaded artifact.',
+    '- Keep all files self-contained for sandbox iframe preview.',
     '',
     `Write the artifact files directly into this directory: ${outputDir}`,
     'Required files:',
@@ -57,6 +69,30 @@ export function buildOpenDesignPrompt({ outputDir, userMessage, reply, topicId,
   ].join('\n');
 }
 
+async function loadSkillBlocks(config, skillNames) {
+  const root = config.openDesignSkillsDir || '';
+  const blocks = [];
+  for (const skill of skillNames) {
+    const file = path.join(root, skill, 'SKILL.md');
+    try {
+      const text = await fs.readFile(file, 'utf8');
+      blocks.push(`--- OpenDesign skill: ${skill} ---\n${text.slice(0, 18000)}`);
+    } catch {}
+  }
+  return blocks.join('\n\n');
+}
+
+function fallbackSkillBlock() {
+  return [
+    'OpenDesign fallback rules:',
+    '- Output a real design artifact, not chat prose.',
+    '- Avoid generic AI gradients, emoji icons, unearned cards, and vague placeholder copy.',
+    '- Use distinctive typography and a committed visual direction.',
+    '- Build a self-contained HTML artifact with CSS/SVG animation when explaining principles, formulas, flows, architecture, or UI.',
+    '- Every visible control or animation must have a purpose.',
+  ].join('\n');
+}
+
 function parseMetadata(metadata) {
   if (!metadata) return null;
   if (typeof metadata === 'object') return metadata;

package/src/runner.js

@@ -13,7 +13,7 @@ import { log } from './logger.js';
 import { buildRuntimeInfo } from './runtime-info.js';
 import { runShellCommand } from './shell-runner.js';
 import { TerminalSessionManager } from './terminal-session.js';
-import { buildOpenDesignPrompt, prepareOpenDesignDir, shouldRenderOpenDesignArtifact } from './opendesign.js';
+import { buildOpenDesignPrompt, chooseOpenDesignSkills, prepareOpenDesignDir, shouldRenderOpenDesignArtifact } from './opendesign.js';
 
 const TERMINAL_STATUSES = new Set(['review', 'done', 'approved', 'cancelled']);
 
@@ -285,12 +285,15 @@ export class Runner {
         ttlMs: 30000,
       });
       const outputDir = await prepareOpenDesignDir(this.config, topicId);
-      const prompt = buildOpenDesignPrompt({
+      const skills = chooseOpenDesignSkills(message, reply);
+      const prompt = await buildOpenDesignPrompt({
+        config: this.config,
         outputDir,
         userMessage: message.content || '',
         reply,
         topicId,
         locale: inferLocale(`${message.content || ''}\n${reply || ''}`),
+        skills,
       });
       await adapter.run(prompt, {
         sessionKey: `wtt:opendesign:${topicId}`,
@@ -298,14 +301,14 @@ export class Runner {
         onProgress: (event) => this.maybePublishProgress(topicId, event, adapter.name),
       });
       const artifact = await this.artifacts.uploadDirectory(outputDir, {
-        source: message.topic_type || 'feed',
+        source: messageTopicType(message) || 'feed',
         sourceId: topicId,
         title: `OpenDesign · ${topicId.slice(0, 8)}`,
         entry: 'index.html',
         type: 'opendesign',
-        metadata: { message_id: message.id || message.message_id || '', generated_by: adapter.name },
+        metadata: { message_id: message.id || message.message_id || '', generated_by: adapter.name, opendesign_skills: skills },
       });
-      const previewUrl = artifact.preview_url || artifact.url;
+      const previewUrl = webPreviewUrl(artifact.preview_url || artifact.url);
       if (previewUrl) {
         const title = artifact.title || 'OpenDesign artifact';
         await this.wtt.publish(topicId, `[opendesign:${title}](${previewUrl})`, 'TASK_ARTIFACT');
@@ -370,6 +373,14 @@ function inferLocale(text) {
   return /[\u4e00-\u9fff]/.test(String(text || '')) ? 'zh' : 'en';
 }
 
+function webPreviewUrl(url) {
+  const text = String(url || '').trim();
+  if (!text) return '';
+  if (text.startsWith('/api/wtt/')) return text;
+  if (text.startsWith('/artifacts/')) return `/api/wtt${text}`;
+  return text;
+}
+
 function messageTopicType(m) {
   return String(m.topic_type || metadataValue(m.metadata, 'topic_type') || metadataValue(m.metadata, 'topicType') || '').toLowerCase();
 }