wizz-method 1.3.2 → 1.4.1

package/src/skills-lib/design-motion-principles/workflows/audit.md

@@ -0,0 +1,203 @@
+# Workflow: Audit Mode
+
+Review existing motion design and produce a per-designer report. Reconnaissance first, then a full audit, then a structured report. Never apply rules blindly.
+
+## Required Reading
+
+Read as you reach each step (not all upfront):
+1. `references/audit-checklist.md` — your systematic guide (STEP 2)
+2. The weighted designer file(s) — `emil-kowalski.md`, `jakub-krehel.md`, `jhey-tompkins.md` (STEP 2)
+3. `references/accessibility.md` — mandatory every audit (STEP 2)
+4. `references/anti-checklist.md` — the quality gate: AI-slop motion categories + anti-patterns to flag (STEP 2)
+5. `references/output-format.md` — the report template, HTML mode + terminal mode (STEP 3)
+6. `references/demo-shell.html` — the demo-card template for HTML-mode per-finding demos (STEP 3)
+
+---
+
+## STEP 1: Context Reconnaissance (DO THIS FIRST)
+
+Before auditing any code, understand the project context.
+
+### Gather Context
+
+Check these sources:
+1. **CLAUDE.md** — Any explicit context about the project's purpose or design intent
+2. **package.json** — What type of app? (Next.js marketing site vs Electron productivity app vs mobile PWA)
+3. **Existing animations** — Grep for `motion`, `animate`, `transition`, `@keyframes`. What durations are used? What patterns exist?
+4. **Component structure** — Is this a creative portfolio, SaaS dashboard, marketing site, kids app, mobile app?
+
+### Motion Gap Analysis (CRITICAL - Don't Skip)
+
+After finding existing animations, actively search for **missing** animations. These are UI changes that happen without any transition:
+
+**Search for conditional renders without AnimatePresence:**
+```bash
+# Find conditional renders: {condition && <Component />}
+grep -n "&&\s*(" --include="*.tsx" --include="*.jsx" -r .
+
+# Find ternary UI swaps: {condition ? <A /> : <B />}
+grep -n "?\s*<" --include="*.tsx" --include="*.jsx" -r .
+```
+
+**For each conditional render found, check:**
+- Is it wrapped in `<AnimatePresence>`?
+- Does the component inside have enter/exit animations?
+- If NO to both → this is a **motion gap** that needs fixing
+
+**Common motion gap patterns:**
+- `{isOpen && <Modal />}` — Modal appears/disappears instantly
+- `{mode === "a" && <ControlsA />}` — Controls swap without transition
+- `{isLoading ? <Spinner /> : <Content />}` — Loading state snaps
+- `style={{ height: isExpanded ? 200 : 0 }}` — Height changes without CSS transition
+- Inline styles with dynamic values but no `transition` property
+
+**Where to look for motion gaps:**
+- Inspector/settings panels with mode switches
+- Conditional form fields
+- Tab content areas
+- Expandable/collapsible sections
+- Toast/notification systems
+- Loading states
+- Error states
+
+### State Your Inference
+
+After gathering context, tell the user what you found and propose a weighting:
+
+```
+## Reconnaissance Complete
+
+**Project type**: [What you inferred — e.g., "Kids educational app, mobile-first PWA"]
+**Existing animation style**: [What you observed — e.g., "Spring animations (500-600ms), framer-motion, active:scale patterns"]
+**Likely intent**: [Your inference — e.g., "Delight and engagement for young children"]
+
+**Motion gaps found**: [Number] conditional renders without AnimatePresence
+- [List the files/areas with gaps, e.g., "Settings panel mode switches", "Loading states"]
+
+**Proposed perspective weighting**:
+- **Primary**: [Designer] — [Why]
+- **Secondary**: [Designer] — [Why]
+- **Selective**: [Designer] — [When applicable]
+
+Does this approach sound right? Should I adjust the weighting before proceeding with the full audit?
+```
+
+Use the Context-to-Perspective Mapping table in SKILL.md to propose the weighting.
+
+### Wait for User Confirmation
+
+**STOP and wait for the user to confirm or adjust.** Do not proceed to the full audit until they respond.
+
+If `AskUserQuestion` is available, present the decision as tappable options:
+- **Confirm weighting** — Proceed with the proposed primary/secondary/selective designers
+- **Adjust primary** — Swap which designer is primary (e.g., prioritize delight over restraint)
+- **Adjust secondary** — Change the secondary lens while keeping primary
+- **Rebuild weighting** — The project type inference was wrong; start over
+
+Otherwise ask in plain text: "Does this weighting sound right, or should I adjust?"
+
+If they adjust (e.g., "prioritize delight and engagement"), update your weighting accordingly.
+
+---
+
+## STEP 2: Full Audit (After User Confirms)
+
+Once the user confirms, perform the complete audit by reading the reference files in this order:
+
+### 2a. Read the Audit Checklist First
+**Read `references/audit-checklist.md`** — Use this as your systematic guide. It provides the structured checklist of what to evaluate.
+
+### 2b. Read Designer Files for Your Weighted Perspectives
+Based on your context weighting, read the relevant designer files:
+- **Read `references/emil-kowalski.md`** if Emil is primary/secondary — Restraint philosophy, frequency rules, decision frameworks
+- **Read `references/jakub-krehel.md`** if Jakub is primary/secondary — Production polish philosophy, what to check
+- **Read `references/jhey-tompkins.md`** if Jhey is primary/secondary — Playful experimentation philosophy, opportunities to surface
+
+### 2c. Read Topical References as Needed
+- **Read `references/accessibility.md`** — MANDATORY. Always check for prefers-reduced-motion. No exceptions.
+- **Read `references/anti-checklist.md`** — Apply this as the audit's quality gate. AI-slop categories at the top (pulsing indicators, hover-scale-on-everything, stagger-spam, etc.) trigger findings; perspective-specific and general anti-patterns sit below. Each category includes a frequency heuristic so single intentional uses don't trip the gate.
+- **Read `references/performance.md`** — If you see complex animations, check for GPU optimization issues
+- **Read `references/motion-cookbook.md`** — Reference when making specific implementation recommendations (the recommended fix code, including the per-finding demo motion in HTML mode)
+
+---
+
+## STEP 3: Output Format (HTML by default)
+
+The audit produces a **self-contained HTML report** with auto-looping CSS demos beside Critical and Important findings. **Read `references/output-format.md`** for the full template (both HTML mode and terminal mode).
+
+### Default behavior — write and open the HTML report
+
+1. **Resolve the write location.** The file is written to `motion-audits/{project-name}-{ISO-date}.html` in the audited project's root.
+   - **Audited project root**: run `git rev-parse --show-toplevel` from the agent's cwd. If it succeeds, use that path. If it fails (no `.git` ancestor), use cwd.
+   - **`{project-name}`**: the `name` field from `package.json` at the project root if it exists; else the `name` field from `pyproject.toml`; else the basename of the project root. Strip any scoping prefix (`@scope/pkg` → `pkg`) and sanitize to lowercase kebab-case (`[a-z0-9-]`, replace others with `-`).
+   - **`{ISO-date}`**: today's date as `YYYY-MM-DD`.
+   - Example: `<project-root>/motion-audits/my-app-2026-05-20.html`.
+   - Do not modify `.gitignore`. The user sees `motion-audits/` in `git status` and decides whether to ignore it.
+
+2. **Read `references/demo-shell.html`** and use it as the template for each demo card. Embed one card per Critical + Important finding (Opportunities do not get demo cards). Use the suffixed-naming contract — `@keyframes motion-{n}-...` and `.demo-card-{n}__motion-target`, `{n}` = the finding's 1-indexed position across the whole report — so multiple findings don't collide on CSS names.
+
+3. **Generate per-finding motion code** by reading the audited code, the relevant lens reference, and `references/motion-cookbook.md` for the recipe. Use the shell's 0% / 66% / 100% cadence at `animation-duration: 3s` (~2s motion, ~1s hold, loop). The `@keyframes` 100% state must match the motion-target's default static rendering so the shell's `prefers-reduced-motion` guard shows the correct final visual.
+
+4. **Write the file.** Create `motion-audits/` if it doesn't exist. Write the complete self-contained HTML document.
+
+5. **Open in the default browser** via OS-detected Bash dispatch:
+
+   ```bash
+   path="<absolute path to the HTML file>"
+   if [ -n "$WSL_DISTRO_NAME" ] || grep -qi microsoft /proc/version 2>/dev/null; then
+     win_path=$(wslpath -w "$path")
+     cmd.exe /c start "" "$win_path" 2>/dev/null
+   else
+     case "$(uname -s)" in
+       Darwin)               open "$path" ;;
+       Linux)                xdg-open "$path" ;;
+       MINGW*|MSYS*|CYGWIN*) start "" "$path" ;;
+       *)                    echo "Unknown platform — open this file manually: $path" ;;
+     esac
+   fi
+   ```
+
+   If the open command returns non-zero or the platform is unrecognized, print `Open this file in your browser: {absolute path}` and continue. Never abort the audit because of a failed browser-open.
+
+6. **Print the 3-line terminal summary:**
+
+   ```
+   🎬 Motion audit complete — 🔴 {N} Critical · 🟡 {N} Important · 🟢 {N} Opportunities
+   📄 Report: {absolute path}
+   💡 Want the full report inline instead? Re-run with --terminal or say "show inline".
+   ```
+
+### Terminal mode (flag-triggered)
+
+When the user signals terminal mode (`--terminal` / `--inline` / `--no-html` flag, or "show the full report inline" / "skip the HTML" / "terminal only"), **skip the HTML write and the browser-open** and render the decorated-markdown report inline per `references/output-format.md` terminal mode. Do not print the 3-line summary in this case.
+
+Do not summarize the audit content in either mode — users want full per-lens perspectives.
+
+---
+
+## Agent Gotchas (Self-Check Before Writing the Report)
+
+Common failure modes during HTML report generation. Most break silently or only manifest when a second finding lands in the same report.
+
+- **Don't reuse keyframe or class names across findings.** Each demo uses `@keyframes motion-{n}-...` and `.demo-card-{n}__motion-target` where `{n}` is the 1-indexed position across the WHOLE report. Duplicate names mean the second finding shadows the first and the first demo breaks silently.
+- **Don't redefine the shell's CSS variables.** Per-finding code uses `var(--bg)`, `var(--fg)`, `var(--border)`, `var(--accent)`, `var(--loop-dim)`, `var(--sans)`, `var(--mono)`. Hard-coding colors or fonts breaks dark mode and typography consistency.
+- **Don't write per-finding overrides inside the `prefers-reduced-motion` block.** The shell's guard collapses all `[class*="__motion-target"]` animations. Make the `@keyframes` 100% state match the motion-target's default static rendering instead.
+- **Don't include demo cards for Opportunities.** Demos are reserved for Critical and Important. Surface Opportunities in text only.
+- **Don't animate the report itself.** No entrance, scroll, or mount animations on the report chrome — only the demo cards animate. Animating the report reproduces the AI-slop patterns the audit exists to catch.
+- **Don't write to cwd if `git rev-parse --show-toplevel` succeeds.** The report goes to `{project-root}/motion-audits/`. Only fall back to cwd when git returns nonzero.
+- **Don't abort the audit if browser-open fails.** A non-zero exit code is a "no default handler" condition, not an error. Print the path and continue.
+- **Don't modify `.gitignore`.** The skill never touches it. The user adds `motion-audits/` themselves if they want.
+- **Don't summarize per-lens findings.** Each section needs its own findings + working-well items + the `Through {Designer}'s lens:` summary.
+
+---
+
+## Success Criteria
+
+- [ ] Context gathered (CLAUDE.md, package.json, existing animations, structure)
+- [ ] Motion gap analysis run — conditional renders checked for missing animation
+- [ ] Weighting proposed and confirmed by the user
+- [ ] Audit checklist worked through systematically
+- [ ] Anti-checklist applied — AI-slop categories checked against the codebase
+- [ ] Accessibility checked — prefers-reduced-motion verified (mandatory)
+- [ ] HTML report written to `motion-audits/`, opened in browser, 3-line summary printed (or terminal-mode report rendered inline when flagged)
+- [ ] Report follows output-format.md with full per-lens sections; Critical + Important findings have looping demo cards

package/src/skills-lib/design-motion-principles/workflows/create.md

@@ -0,0 +1,87 @@
+# Workflow: Create Mode
+
+Build interactive components with purposeful motion. Light discovery, then generate against the cookbook.
+
+## Required Reading
+
+Read before generating:
+1. `references/motion-cookbook.md` — the recipe source for all motion code
+2. `references/accessibility.md` — `prefers-reduced-motion` is mandatory in everything you generate
+3. `references/creation-gotchas.md` — Claude's failure modes when writing motion; self-check against these
+
+---
+
+## STEP 1: Light Discovery
+
+Establish two things — project context and designer weighting — before generating. Keep it to 1-2 questions.
+
+### Infer First, Ask Second
+
+Check what you can already see:
+- **The request** — what component, what interaction, what stack (React / Framer Motion / CSS / HTML)?
+- **CLAUDE.md, package.json, existing components** — project type and existing animation conventions (durations, easing, libraries)
+
+### Propose Context + Weighting
+
+Map the project type to a perspective weighting using the Context-to-Perspective Mapping table in SKILL.md. State your inference in one short block:
+
+```
+Building: [what — e.g. "a notification toast, React + Framer Motion"]
+Project context: [inferred — e.g. "productivity SaaS dashboard"]
+Proposed weighting: Primary [Designer] · Secondary [Designer]
+```
+
+If `AskUserQuestion` is available and the weighting is genuinely ambiguous, offer:
+- **Confirm** — proceed with the proposed weighting
+- **Adjust** — change primary/secondary designer
+
+Otherwise ask in plain text: "Does this weighting sound right, or should I adjust?"
+
+### Wait Gate
+
+For non-trivial components, **confirm context before generating**. For a small, well-specified request ("add a press-scale to this button"), state the inference in one line and skip straight to STEP 3 — don't manufacture a question.
+
+---
+
+## STEP 2: Load Weighted Knowledge
+
+Based on the confirmed weighting, read the relevant designer file(s):
+- **Read `references/emil-kowalski.md`** if Emil is primary/secondary — restraint, the frequency rule, when NOT to animate
+- **Read `references/jakub-krehel.md`** if Jakub is primary/secondary — production polish judgment, subtlety bar
+- **Read `references/jhey-tompkins.md`** if Jhey is primary/secondary — playful expression, what motion could become
+
+The designer files give you the **judgment** (should this animate, what feel). The cookbook gives you the **code**.
+
+If the component involves complex or numerous animations, also read `references/performance.md`.
+
+---
+
+## STEP 3: Generate
+
+Build the component. Apply, in order:
+
+1. **The frequency gate (Emil)** — Should this animate at all? High-frequency or keyboard-initiated interactions get minimal or no motion. Decide before adding anything.
+2. **Recipes from the cookbook** — Use the weighted designer's patterns. Enter = opacity + translateY + blur. Exit subtler than enter. Custom easing or springs, never bare `ease`.
+3. **Accessibility** — Every animation ships with `prefers-reduced-motion` handling, in the same code. No exceptions, no follow-up.
+4. **Performance** — Animate `transform` / `opacity` / `filter` only. Never `width` / `height` / `top` / `left`.
+5. **Context-appropriate timing** — Emil-weighted → under 300ms. Jakub → 200-500ms polish. Jhey → whatever serves the effect.
+
+---
+
+## STEP 4: Self-Check
+
+Before presenting, verify the generated code against every item in `references/creation-gotchas.md`. Fix anything that matches a gotcha.
+
+Then briefly tell the user the motion decisions you made and why — which designer weighting drove the timing, easing, and whether something was deliberately left un-animated.
+
+---
+
+## Success Criteria
+
+- [ ] Context and weighting confirmed (or inference stated for trivial requests)
+- [ ] Frequency gate applied — motion is purposeful, not decorative-by-default
+- [ ] Recipes drawn from the cookbook, matched to the designer weighting
+- [ ] `prefers-reduced-motion` handled in all generated motion
+- [ ] Only `transform` / `opacity` / `filter` animated
+- [ ] Code self-checked against creation-gotchas.md
+- [ ] Motion decisions explained to the user

package/src/skills-lib/desktop-security/SKILL.md

@@ -15,11 +15,32 @@ description: >
 - contextIsolation: true (obrigatório)
 - sandbox: true quando possível
 - webSecurity: false nunca em produção
+- Nunca carregue conteúdo remoto numa janela com acesso a APIs privilegiadas; conteúdo remoto = sandbox + sem preload sensível
+- Mantenha o Electron atualizado (patches de Chromium/Node chegam por release do Electron)
+
+### Navegação e janelas
+- Bloqueie navegação para fora do app: handler em `will-navigate` que cancela URLs fora da allowlist
+- `setWindowOpenHandler`: negue por padrão (`{ action: "deny" }`), abra externo só o que for aprovado
+- `shell.openExternal` só com URL validada (esquema `https:` e host esperado), nunca com input cru do renderer
 
 ### IPC (comunicação renderer <> main)
-- Valide e sanitize todos os dados vindos do renderer
-- Exponha apenas as funções necessárias via contextBridge
+- Valide e sanitize todos os dados vindos do renderer (o renderer é território hostil: trate como input de usuário)
+- Exponha apenas as funções necessárias via contextBridge, cada uma com assinatura fixa
 - Nunca exponha ipcRenderer diretamente ao renderer
+- Em `ipcMain.handle`, valide tipo e tamanho dos argumentos; se houver múltiplas janelas, cheque `event.senderFrame.url` contra o esperado
+
+```ts
+// preload.ts: superfície mínima, sem repassar ipcRenderer
+contextBridge.exposeInMainWorld("api", {
+  saveNote: (text: string) => ipcRenderer.invoke("notes:save", text),
+})
+
+// main.ts: valida antes de agir
+ipcMain.handle("notes:save", (event, text) => {
+  if (typeof text !== "string" || text.length > 10_000) throw new Error("input inválido")
+  // ...
+})
+```
 
 ### Atualizações automáticas
 - Assine o pacote de atualização com certificado de código (code signing)
@@ -29,8 +50,9 @@ description: >
 ## Armazenamento local
 
 ### O que armazenar localmente
-- Tokens de sessão: keychain do OS (electron-keytar), nunca localStorage
-- Dados do usuário: criptografados com chave derivada da senha do OS
+- Tokens de sessão: `safeStorage` do Electron (usa Keychain no macOS, DPAPI no Windows, libsecret no Linux), nunca localStorage
+  - `safeStorage.encryptString(token)` antes de gravar em disco; `keytar` está arquivado, não use em projeto novo
+- Dados sensíveis do usuário: criptografados via `safeStorage` ou AES-256-GCM com chave guardada no keychain do OS
 
 ### O que nunca armazenar localmente
 - Senhas em texto plano
@@ -41,3 +63,12 @@ description: >
 - Code signing obrigatório (Windows: Authenticode, macOS: Apple Developer ID)
 - Notarização no macOS para distribuição fora da App Store
 - Auto-update com verificação de integridade antes de executar
+
+## Checklist rápido (antes de empacotar)
+- [ ] `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` onde possível?
+- [ ] Nenhuma janela privilegiada carrega URL remota?
+- [ ] `will-navigate` e `setWindowOpenHandler` restringem navegação?
+- [ ] Todo handler de `ipcMain` valida os argumentos?
+- [ ] Tokens em `safeStorage`/keychain, nada sensível em localStorage?
+- [ ] Build assinado (e notarizado no macOS)? Auto-update valida assinatura?
+- [ ] Versão do Electron atual (sem CVE aberta)?