@staff0rd/assist 0.384.3 → 0.385.1

package/claude/skills/make-a-deck.md

@@ -0,0 +1,43 @@
+# Make a Deck: Slide Presentation in HTML
+
+Build a slide presentation as a single HTML file with fixed-size slides (typically 1920×1080, 16:9) that letterbox to any viewport. Use this when the user asks for a deck, presentation, slides, or pitch. Don't hand-roll the scaling — use the deck shell starter.
+
+## Phase 1: Discovery
+
+Confirm before building: **audience** (determines tone and density); **format** (aspect ratio — 16:9 default — and slide count: a 10-minute deck is ~10 slides, a 30-minute one ~20–25); **tone** (formal corporate, casual internal, marketing-bold, technical); **source content** (read any PRD or existing material before sketching); **speaker notes** (off by default, only when explicitly requested); **brand / design system** (always confirm — if none, invoke `frontend-aesthetic-direction` before drawing).
+
+If the user gave enough context (e.g., "make a 5-slide deck for engineering all-hands from this PRD"), skip the question round.
+
+## Phase 2: Plan the layout system
+
+Before building any slide, commit to a layout system and vocalize it in a comment block at the top of the file. A typical deck has 4–6 layout types: cover/title, section header (full-bleed color or image), content slide (headline + chart/image/list), quote/pull-out, comparison/two-column, closing/CTA. For each: background treatment, headline size and position, body content area, footer (page number, brand mark, none).
+
+Limit the deck to **1–2 background colors**; section headers may break to a third, no more.
+
+## Phase 3: Build the deck shell
+
+Use the deck-shell starter (`copy_starter_component` with `kind: "deck_stage.js"`) — it handles scaling/letterboxing, keyboard and tap navigation, the slide counter, localStorage persistence, print-to-PDF, and `data-om-validate` tagging. Each slide is a direct child `<section>` of `<deck-stage>`.
+
+Give each slide a `data-screen-label` so the user can reference it by name when commenting (`<section data-screen-label="01 Title">`). **Labels are 1-indexed** to match the slide counter the user sees.
+
+## Phase 4: Build slide-by-slide
+
+Build in order, and show the user the file after 1–2 slides — don't perfect 15 in private and then reveal. Per slide:
+
+- **Type.** Body never under 24px on a 1920×1080 canvas, ideally 32px+; headlines 60–96px+.
+- **Hierarchy.** One primary message per slide; supporting elements smaller and more muted.
+- **Imagery.** From the design system, or honest placeholders (striped background, monospace label). No hand-drawn SVG filler.
+- **No filler slides.** "Why choose us?" / "About this deck" cost the user attention — cut them.
+- **Charts.** Show what matters; cut columns and data points that don't support the slide's point.
+
+Use the design system's spacing and color tokens — no new values inline.
+
+## Phase 5: Speaker notes (only if requested)
+
+When asked: add a `<script type="application/json" id="speaker-notes">` array in the head, one entry per slide, written as full conversational scripts (not bullet outlines). Slides with notes can carry less on-screen text. The shell renders them automatically.
+
+## Phase 6: Verify and deliver
+
+Walk the deck top to bottom in the preview: scaling at multiple viewport sizes, counter increments correctly, keyboard nav (arrows, space) works, nothing overflows slide bounds, type meets the 24px+ minimum, contrast passes WCAG (invoke `accessibility-audit` for thoroughness).
+
+For end-of-turn delivery, surface the final HTML file and call the verifier subagent for the thorough pass. Summarize briefly: caveats (e.g., placeholder imagery still needed), next steps (e.g., real charts to swap in), and decisions the user should sign off on.

package/claude/skills/make-a-prototype.md

@@ -0,0 +1,56 @@
+# Make a Prototype: Interactive Clickable Prototype
+
+Build a working interactive prototype — clickable, navigable, with real state and feedback. Use this when the user asks for a prototype, mockup, demo, or "make it interactive." **Prototypes interact** — static screenshots strung together with `<a>` tags don't count; the point is to test the flow with real clicking, typing, validating, succeeding, failing.
+
+## Phase 1: Discovery
+
+Confirm before building: **the flow** (screens, entry point, goal state — map it as a list); **fidelity** (hi-fi or mid-fi); **device frame** (desktop browser, iOS, Android, macOS window); **variations** (one flow or several to compare); **brand / design system** (always confirm — if none, invoke `frontend-aesthetic-direction` first); **sample data** (real-looking content, no Lorem ipsum).
+
+## Phase 2: Map screens and state
+
+Write the flow down before building, and drop it into the file as a comment block so the user can see the plan:
+
+```
+Screens:
+  1. Welcome — "Get started" CTA → 2
+  2. Email entry — validate format → 3 on valid, inline error on invalid
+  3. Profile — name, photo upload → 4
+  4. Success — "You're in" → 1 (loop demo)
+
+State:
+  - currentScreen: 1
+  - email: ""
+  - emailError: null
+```
+
+## Phase 3: Build screen-by-screen
+
+For each screen: mount it in the DOM (display toggling or React state within a single page); hi-fi visuals matching the design system — real components, not generic boxes; plausible real content (actual names, product copy, numbers); one primary CTA per screen, secondary actions smaller and de-emphasized.
+
+Use the right device frame via `copy_starter_component`: `ios_frame.jsx`, `android_frame.jsx`, `macos_window.jsx`, or `browser_window.jsx`. The frame stays fixed; the prototype lives inside it.
+
+## Phase 4: Wire up interactions
+
+Every interaction wired, not just the happy path:
+
+- **Navigation.** Primary CTAs advance, back moves backward, state persists across screens.
+- **Form validation.** Empty submit → inline error; bad format → specific field-tied error; valid → proceed.
+- **Loading states.** Async actions show a loading indicator and disable the button against double-submit. Fake the latency with `setTimeout` — don't skip the loading state because the work is fake; it's part of what's being tested.
+- **Success and error feedback.** Toast, inline confirmation, or page transition; errors clear and tied to their field or action.
+- **State changes.** Toggling, selecting, filtering all update the UI immediately.
+
+## Phase 5: Sub-state and persistence
+
+Make meaningful sub-state reactive: selection state, filter/sort state, modal/dropdown open-state (focus moves into the modal, Escape closes it), form values and errors.
+
+Persist what matters across reload via `localStorage`: current screen, form drafts, tweak values (see `make-tweakable`). Refreshing mid-iteration is one of the most common user actions — state that doesn't survive makes the prototype feel broken.
+
+## Phase 6: Verify
+
+Walk the full flow in the preview: every CTA leads somewhere, every form validates, every error is clear and recoverable, every async action shows feedback, every state change is visible, keyboard navigation works (Tab through, Enter to submit, Escape to close), focus is visible. If you can't verify a behavior, say so in the summary rather than claiming success.
+
+## Phase 7: Variations (if requested)
+
+Expose variations as tweaks in a floating panel (`make-tweakable`), side-by-side on a canvas (`design_canvas.jsx` starter), or in-prototype toggles. **Don't scatter v1.html / v2.html / v3.html across the project — one file, many variants.**
+
+Summarize briefly: what flows work, what's faked (e.g., "submit calls a setTimeout fake"), what's open for the user to decide.

package/claude/skills/make-tweakable.md

@@ -0,0 +1,66 @@
+# Make Tweakable: Add In-Design Tweak Controls
+
+Add a floating control panel to a finished design that lets the user adjust selected aspects live — colors, fonts, spacing, copy, layout variants, feature flags. Use this when the user wants to "play with options," "see different versions," or compare visual choices. **One file, many variants** — no v1.html / v2.html / v3.html scatter.
+
+## Phase 1: Identify what should be tweakable
+
+Confirm with the user — or propose and check — which aspects to expose: color (primary, accent, background tone), typography (family, base size, scale ratio), density (tight / normal / loose), layout variant, component variants (filled/ghost buttons, card treatment), copy (headline, subhead, CTA text), feature flags (show/hide sections).
+
+**Keep the tweak surface small** — 3–8 controls. A few meaningful axes to explore, not a Figma clone. If the user didn't ask for tweaks but the design has obvious axes of variation, add 1–2 by default to surface interesting possibilities.
+
+## Phase 2: Design the tweak panel
+
+The panel lives inside the prototype, floating (typically bottom-right), semi-transparent with a subtle border, titled **"Tweaks"** to match the toolbar toggle. Use the right control per value type: color picker for colors; dropdown or button group for fonts and variants; slider with sensible min/max for numbers; toggle for booleans; text input for copy. Keep controls compact — a narrow stacked column beats a sprawling panel.
+
+## Phase 3: Wire up the live updates
+
+Use CSS custom properties for visual tokens so everything referencing them updates:
+
+```js
+document.documentElement.style.setProperty("--tweak-primary", newColor);
+```
+
+For non-CSS values (copy, layout variants, feature flags), use JS state with re-render or DOM manipulation.
+
+## Phase 4: Implement the host protocol
+
+The host environment exposes a toolbar toggle for the tweak panel. **Order matters** — if you announce availability before the listener exists, the host's activate message lands on nothing and the toggle silently does nothing:
+
+1. **Register a `message` listener on `window` first:**
+   - `{type: '__activate_edit_mode'}` → show the Tweaks panel
+   - `{type: '__deactivate_edit_mode'}` → hide it
+2. **Then announce availability:**
+   ```js
+   window.parent.postMessage({ type: "__edit_mode_available" }, "*");
+   ```
+3. **When a value changes, persist it** by posting back (partial updates are fine — only included keys are merged):
+   ```js
+   window.parent.postMessage(
+   	{ type: "__edit_mode_set_keys", edits: { primaryColor: "#FF6600" } },
+   	"*",
+   );
+   ```
+
+## Phase 5: Persist defaults on disk
+
+Wrap tweakable defaults in comment markers so the host can rewrite them:
+
+```js
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/ {
+	primaryColor: "#D97757",
+	fontSize: 16,
+	dark: false,
+}; /*EDITMODE-END*/
+```
+
+The block between markers **must be valid JSON** (double-quoted keys and strings), and there must be exactly one such block, inside an inline `<script>` in the root HTML file. The host merges edits into it and writes the file back, so changes survive reload.
+
+## Phase 6: Hide the controls when off
+
+With Tweaks toggled off, the panel is entirely hidden — not dimmed, not collapsed to a corner. This is non-negotiable: any visible edit-mode chrome makes the design look unfinished.
+
+## Phase 7: Verify and summarize
+
+In the preview: toggle the panel on/off via the toolbar; change each tweak and confirm it updates live; reload and confirm values persist; check the design reads as a finished artifact with the panel off.
+
+Summarize: tweaks exposed and their value types, defaults, tweaks considered but excluded (and why), whether the set covers the user's exploration axes.

package/claude/skills/polish-pass.md

@@ -0,0 +1,43 @@
+# Polish Pass: End-of-Design Quality Gate
+
+Run a comprehensive quality check before a design is shown to stakeholders or shipped. **A polished and an unpolished design are the same idea executed at different levels of care — and the gap is what people actually see.** This is the umbrella for the four narrower review skills; use it as the final gate before delivery.
+
+## Phase 1: Confirm scope
+
+Polish the HTML file the user just finished or asked about; otherwise the project's main deliverable; if unclear, ask. Read it and note the medium (slide / page / mobile / dashboard), the deployment context (internal / customer-facing / marketing), and any stated constraints.
+
+If the design is clearly mid-flight (broken layout, missing sections, placeholder content still being iterated), say so and ask whether to polish now or after the structure settles.
+
+## Phase 2: Launch four review agents in parallel
+
+Use the ${AGENT_TOOL_NAME} tool to launch all four agents concurrently in a single message. Each runs the equivalent of one standalone review skill, scoped to this file.
+
+Instruct every agent explicitly: **report every issue found, including uncertain and low-severity ones, with a confidence and severity estimate for each.** Coverage is the agent's job; filtering and prioritization happen in Phase 3. An agent that self-censors "minor" findings silently lowers recall.
+
+1. **Accessibility audit** (`accessibility-audit`): contrast and color (WCAG AA minimums, color-only signaling, pure white/black); semantic HTML and structure (headings, button vs div, labels, alt text, ARIA discipline); keyboard navigation and focus (reachability, tab order, visible focus); motion, forms, and hit-target size.
+2. **AI slop check** (`ai-slop-check`): aggressive gradients; emoji decoration; default left-border cards; hand-drawn SVG; overused default fonts (Inter, Roboto, Arial, Fraunces, bare system stacks); the editorial-warm house style as a silent default (cream + serif display + terracotta, without a brand reason); pure white/black; invented colors; off-scale spacing.
+3. **Hierarchy and rhythm review** (`hierarchy-rhythm-review`): primary/secondary/tertiary differentiation via size, color, weight, position, density, and the 5-second test; spacing and type scale discipline, repetition, strategic variation, palette discipline, section structure, alignment.
+4. **Interaction states pass** (`interaction-states-pass`): per-element default/hover/active/disabled/focus/loading; transition timing (0.15–0.3s state changes, longer entry/exit); `prefers-reduced-motion`; action feedback and state visibility.
+
+## Phase 3: Aggregate, deduplicate, prioritize
+
+Wait for all four agents. Merge duplicate findings (e.g., "focus ring removed" from both accessibility and interaction-states). Group into:
+
+1. **Blockers** — accessibility failures (contrast under WCAG, missing keyboard support, removed focus rings, missing labels). These break the design for real users; fix all.
+2. **Quality issues** — AI slop tropes, broken hierarchy, missing interaction states. These cheapen the design; fix all.
+3. **Polish recommendations** — subtler improvements (color tone shift, spacing-scale tightening). Apply when in scope; flag when out.
+
+## Phase 4: Fix and re-verify
+
+Fix every blocker and quality issue directly. For ambiguous fixes (e.g., the design uses Inter but no brand font is stated), pick a defensible default and note it so the user can override. Note and skip clear false positives (e.g., a third-party embed's contrast).
+
+Then re-check the high-risk areas: did contrast fixes wash out a brand color? Do the new focus rings overlap neighboring content? Does the primary CTA now actually feel primary? Fix what looks off; flag what you're unsure about.
+
+## Phase 5: Final summary
+
+Report concisely — the user can ask for detail:
+
+- **Verdict** — "Ready to ship" / "Ready after user reviews flagged decisions" / "Needs more iteration before polish makes sense"
+- **Blockers fixed and polish applied** — counts by category
+- **Open decisions** — judgment calls to sign off (font choice, color tone shift, emphasis level)
+- **Out of scope** — noticed but untouched (copy edits, content additions, new features)

package/claude/skills/wireframe.md

@@ -0,0 +1,48 @@
+# Wireframe: Explore Many Ideas Quickly
+
+Produce low-fidelity wireframes or storyboards to explore a flow, layout, or idea before committing to hi-fi design. Use this when the user wants to "explore options," "sketch something out," or "see a few directions," or when the problem is open enough that hi-fi work would be wasted. **Wireframes are disposable** — their value is breadth of options, not the fidelity of any one.
+
+## Phase 1: Understand the goal
+
+Confirm: **what's being explored** (a screen, a flow, a navigation pattern, an information hierarchy, an interaction model); **the user goal** on this screen or flow; **constraints** (mobile or desktop, existing context or greenfield, non-negotiable elements); **number of variations** (3 minimum, 5–6 ceiling per round); **axis of variation** (layout? density? step count? CTA placement?).
+
+If the user just says "wireframe a sign-up flow," propose 2–3 axes (e.g., "single-page form vs multi-step wizard vs progressive disclosure") and ask which to explore.
+
+## Phase 2: Establish wireframe conventions
+
+Stick to the wireframe visual language so the user reads them as wireframes, not broken hi-fi:
+
+- **Greyscale only** — black, white, 2–3 grays; no brand color
+- **System sans-serif** — no type personality; the user shouldn't form font opinions yet
+- **Boxes for content areas**, labeled ("headline", "image", "feature card")
+- **Striped placeholders for imagery** with monospace labels (`product shot 1200×800`) — never real images; they pull focus
+- **Ipsum or skeleton copy** — no final copy at this stage
+- **Annotations welcome** — numbered callouts on key decisions
+
+This is the one context where hand-drawn-feeling SVG (rectangles, lines, simple icons) is acceptable — everything is at the same low fidelity.
+
+## Phase 3: Sketch variations
+
+Produce **at least 3** variations differing on the established axis. Lay single-screen variations side-by-side with the `design_canvas.jsx` starter; build flow variations as small storyboards (3–5 screens each).
+
+Vary across layout (centered / split-screen / grid), information density, flow structure (single page / multi-step / progressive disclosure), CTA placement, or navigation pattern. Order from most by-the-book to most novel — the user picks something interesting more readily when the safe option sits next to a riskier one.
+
+Write down each variation's distinguishing structure before sketching it. Left unspecified, variations converge on near-identical layouts — make the differences deliberate, and make at least one genuinely off-distribution.
+
+## Phase 4: Annotate
+
+Add 2–4 annotation points per variation, placed next to it (not in a separate doc), so the user reads the variation and its rationale together:
+
+```
+- Variation 1 (single-column wizard): simple, focused, but slow
+- Variation 2 (single-page form): fastest path, heavy first impression
+- Variation 3 (progressive disclosure): balances both, more JS state
+```
+
+## Phase 5: Capture decisions and hand off
+
+After the user picks a direction, capture: the chosen variation (or hybrid), what attracted them to it, what they explicitly rejected, and any new constraints surfaced. This becomes the brief for the hi-fi follow-up.
+
+Then suggest `make-a-prototype` (hi-fi interactive), `make-a-deck` (if the wireframe was for a presentation), or another low-fi round. Don't invest hi-fi polish in the wireframes themselves — they've served their purpose.
+
+Summarize: variations produced, axis of variation, recommended next step, open questions surfaced.