create-yss-spec 1.1.1 → 1.1.3

package/template/.codex/skills/product-design/references/communication-protocol.md

@@ -0,0 +1,45 @@
+# Communication Protocol
+
+This applies to every Product Design skill.
+
+Talk to the user like a design partner, not a debugger.
+
+Default response shape:
+
+- Lead with the visible result, decision, or blocker.
+- Keep progress updates short, warm, and non-technical.
+- Explain what changed in plain product or design language.
+- Give the clickable preview URL when there is one.
+- Name trade-offs or misses plainly.
+- End with one concise suggested next step for the user's current task or goal.
+- Avoid walls of bullets and overwhelming the user.
+- Prioritize pithy, explicit prose that is helpful and minimizes jargon.
+
+Do not lead with:
+
+- Tool names
+- File paths
+- Package commands
+- Trace or debug details
+- Internal workflow names
+- Verification mechanics
+
+Use technical detail only when:
+
+- The user asks for it
+- Something is blocked
+- The detail changes what the user should do next
+
+Final response continuation:
+
+- Every final response should end with exactly one useful next action, phrased as a natural sentence or question in the ordinary prose of the response.
+- Make the next step specific to the active Product Design goal, such as reviewing a preview, choosing a direction, approving an implementation pass, tightening one screen, or sharing a target route or reference.
+- If the response is blocked on missing input, make the unresolved question the final next step.
+- Do not end with only a bare confirmation, file path, preview link, or "done" message while a concrete Product Design next step remains.
+- Skip the next step only when the user explicitly asks for no follow-up, clearly closes the task, or another active workflow already owns the final next action.
+
+When providing commentary and in-progress updates:
+
+- Speak with the user like a teammate.
+- Keep them updated with pithy, high-signal updates about the task at hand.
+- Briefly explain important decisions and context.

package/template/.codex/skills/product-design/references/critical-overrides.md

@@ -0,0 +1,58 @@
+# Critical Overrides
+
+These rules override generic assistant defaults for Product Design work.
+
+## Context
+
+- When working inside an existing project or product, find similar flows, screens, components, and UX patterns first. Build on the product's existing design system. Do not reinvent the wheel. Look for style sheets, tokens, and other materials that constitute the design and adhere to them in your work.
+
+## Saved User Context
+
+- If `user-context.md` exists, use it by default.
+- Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets to ground Product Design work.
+- Ideation, prototypes, audits, clones, and critiques should match the saved product context unless the user asks for something different.
+- When a workflow needs visual grounding, attach or include relevant saved screenshots, reference images, tokens, design language, and component references in ImageGen, ideation, prototype, audit, and critique work.
+
+## Design Brief Gate
+
+- For Product Design requests that design, build, prototype, clone, redesign, extend, or generate product UI directions, run `$get-context` before `$ideate`, `$prototype`, `$url-to-code`, or `$image-to-code`.
+- `$get-context` can run in question mode or playback mode. If required product, visual, or interactivity details are missing, ask for them. If those details are already present, play back the brief in a pithy format before moving to the next workflow.
+- Do not proceed to ideation or implementation until the brief has been played back and either confirmed by the user or already confirmed earlier in the thread.
+- A confirmed design brief is not a visual target. Use the confirmed brief as input to `$ideate` unless the user has already provided a concrete visual source such as a URL, screenshot, image, mockup, or Figma frame.
+- After the user approves the design brief and the next step is an involved app, prototype, clone, redesign, or build, send one short expectation-setting note before starting work. Say that involved builds often take about 10-15 minutes, ambitious builds can take longer, and invite the user to grab coffee or tend to other work while Product Design keeps moving. Simpler static prototypes can be faster, often 5-10 minutes. Keep it warm and lightly playful, not apologetic or over-explanatory. Skip this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.
+
+## How to communicate
+
+- Follow [communication-protocol](communication-protocol.md)
+
+## Build Handoff
+
+- After a successful app, prototype, clone, redesign, or image-to-code build, return the prototype link first. This handoff is not blocked by sharing setup.
+- Add one short iteration nudge: ask the user what they want changed next, and mention that annotations are useful for pointed edits.
+- Add one short share nudge. Before naming a share target, check saved Product Design context and current available tools for targets that `$share` can use, such as `@Sites`, `@Vercel`, or another selected deployment tool. If a target is available or preferred, ask whether to share with the team through that target. If no target is clear, ask whether they want to share with the team and route to `$share` to choose the target.
+- Keep the wording plain and human. Example: `Tell me what you'd like to change and we'll iterate. Annotations are great for pointed edits too. Want to share this with your team via @Sites?`
+
+## Re-read this file
+
+- Before every second user-facing assistant message, read this file, reminding of these principles.
+- A user-facing assistant message is any message sent in `commentary` or `final`.
+
+## Explore vs. Design vs. Build
+
+- Do not build from under-specified product context alone.
+- Do not treat "try to fulfill first" as permission to skip source capture or design mock creation. Follow the workflows prescribed in this plugin as contracts.
+- For URLs, capture and open a screenshot first. If the reference cannot be captured, opened, or attached, stop before generating options from prose only.
+- Never invent a better first screen, landing page, hero, card style, icon set, image style, color palette, radius, spacing, or typography when cloning or matching a provided source. Match the source.
+- Check the work like a senior designer. Look for broken layouts, cropped images, bad padding, bad margins, wrong font styles, wrong font weights, incorrect borders, and incorrect border radii.
+- Screenshots are not QA by themselves. Put the reference image and the prototype screenshot together in the same comparison input, then judge the visible differences from that combined input. Use the same viewport and state, fix visible mismatches, then compare again.
+- Build the current screen's interactions. Sidebars, menus, navs, forms, inputs, buttons, tabs, dropdowns, drawers, modals, popovers, carousels, tooltips, filters, toggles, and first-screen controls must be functional and populated with realistic mock data. Do not build new pages or routes unless the user asks for them.
+
+## Browser user
+
+- Only use the user's chosen browser. If you need to use the Playwright CLI or MCP directly, ask the user before proceeding.
+- Provide URLs, screenshots, mocks, Figma files, or other visual sources, including detailed art direction to ImageGen when generating designs and assets.
+
+## Working with and making assets
+
+- Never fake visible assets with ASCII, prose, text symbols, emoji, placeholder boxes, CSS art, div art, handcrafted SVGs, inline SVGs, or approximate code drawings. Use real source assets when available. Use the built-in Image Gen tool for image assets when source assets are missing. Use the closest matching icon library for icons.
+- Work like a designer. Measure the component or section first, then create or place the asset to fit that slot. Match the needed dimensions, crop, subject, palette, and density. Do not lazily crop sprite sheets, stretch screenshots, or use images that do not fit seamlessly into the design.

package/template/.codex/skills/product-design/references/local-prototype-preflight.md

@@ -0,0 +1,16 @@
+# Local Prototype Preflight
+
+Use this before creating a new local prototype.
+
+- Keep the work self-contained in the new project folder.
+- Plugin UI icons live in `../assets/`. Do not put prototype starter code or generated app assets there.
+- The bundled Product Design starter lives in `../templates/prototype/`.
+- Create the app with the bootstrap script. Resolve the script path relative to this file, then run it with an absolute path:
+
+```bash
+node /absolute/path/to/plugins/product-design/scripts/bootstrap-prototype.mjs --dest /absolute/path/to/new-prototype
+```
+
+- Run `npm install` from the generated project root. The generated app includes its own `.npmrc`.
+- Do not replace the starter with static HTML because package install is slow. If install is genuinely blocked, report the blocker.
+- Do not start a server until the route is ready to build.

package/template/.codex/skills/product-design/scripts/bootstrap-prototype.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const pluginRoot = path.resolve(path.dirname(scriptPath), "..");
+const templateRoot = path.join(pluginRoot, "templates", "prototype");
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) continue;
+    const raw = arg.slice(2);
+    const [key, inlineValue] = raw.split("=", 2);
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function slugify(value) {
+  return (
+    String(value || "prototype")
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "prototype"
+  );
+}
+
+function readText(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+}
+
+function writeText(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, value, "utf8");
+}
+
+function copyDir(source, target) {
+  cpSync(source, target, {
+    recursive: true,
+    force: true,
+    filter(current) {
+      const name = path.basename(current);
+      return !["node_modules", "dist", ".vite", ".turbo", ".DS_Store"].includes(name);
+    },
+  });
+}
+
+function hasFiles(dir) {
+  return existsSync(dir) && readdirSync(dir).length > 0;
+}
+
+function ensureEmptyDest(dest) {
+  if (existsSync(dest) && statSync(dest).isFile()) {
+    throw new Error(`Destination exists and is not a directory: ${dest}`);
+  }
+  if (hasFiles(dest)) {
+    throw new Error(`Destination exists and is not empty: ${dest}`);
+  }
+  mkdirSync(dest, { recursive: true });
+}
+
+function nearestPrototypeRoot(args) {
+  const root = args.root || args.dest || process.cwd();
+  return path.resolve(root);
+}
+
+function packageJsonPath(root) {
+  return path.join(root, "package.json");
+}
+
+function readPackage(root) {
+  const filePath = packageJsonPath(root);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readText(filePath));
+}
+
+function writePackage(root, pkg) {
+  writeText(packageJsonPath(root), `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function setPackageName(root) {
+  const pkg = readPackage(root);
+  if (!pkg) return;
+  pkg.name = slugify(path.basename(root));
+  writePackage(root, pkg);
+}
+
+function setLocalNpmCache(root) {
+  writeText(path.join(root, ".npmrc"), [
+    `cache=${path.join(root, ".npm-cache")}`,
+    "fund=false",
+    "audit=false",
+    "",
+  ].join("\n"));
+}
+
+function createNew(root) {
+  if (!existsSync(templateRoot)) {
+    throw new Error(`Bundled Product Design prototype template is missing: ${templateRoot}`);
+  }
+  ensureEmptyDest(root);
+  copyDir(templateRoot, root);
+  setPackageName(root);
+  setLocalNpmCache(root);
+  return { status: "created", root };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = nearestPrototypeRoot(args);
+
+  if (args.mode && args.mode !== "new") {
+    const mode = String(args.mode);
+    throw new Error(`Unknown mode: ${mode}`);
+  }
+  const result = createNew(root);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/template/.codex/skills/product-design/skills/audit/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: audit
+description: "Audit or critique a product flow, journey, workflow, funnel, onboarding path, checkout path, settings path, screen, or multi-step product experience by capturing screenshots first, placing them in Figma or a local folder, then reporting UX, design, and accessibility findings from that evidence. Use when the user asks to audit, critique, review, inspect, assess, or evaluate a product experience."
+---
+
+# Audit
+
+Use this skill when the user wants to audit or critique a product flow, journey, funnel, onboarding path, checkout path, settings path, screen, or other product experience.
+
+The output is not a loose opinion. The output is:
+
+- Screenshots of the flow
+- Those screenshots placed in the chosen destination
+- A numbered step list
+- UX and design findings tied to steps or screenshots
+- Accessibility risks tied to steps or screenshots
+- Clear limits on what could not be checked from screenshots alone
+
+## Critical Overrides
+
+- Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## User Context
+
+Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+
+Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
+
+Do not inspect every saved reference. Inspect only what the current task needs.
+
+## Route
+
+Before auditing:
+
+1. Identify the product or surface.
+2. Identify the flow or task.
+3. Identify the destination.
+4. Choose the capture tool.
+5. Capture the flow.
+6. Save, inspect, place, and annotate each screenshot.
+
+Destination rules:
+
+- If the user names Figma, use Figma.
+- If the user names a local folder, use that folder.
+- If the destination is missing, ask one question: "Should I put this in Figma or a local folder?"
+
+Capture rules:
+
+- Use the Codex in-app Browser first.
+- If Browser cannot access, control, or screenshot the target, use Chrome [Internal].
+- If Browser and Chrome cannot complete the capture, ask before using Playwright as the fallback.
+- If none of those can capture valid screenshots or control the flow, stop and report the blocker.
+
+Browser capture order:
+
+1. Load the Browser skill before browser work.
+2. Connect to the browser and use the current tab when it already shows the target.
+3. Do not reload or navigate away unless the audit needs a fresh start.
+4. Observe the visible state before acting.
+5. Before each click, type, or key press, use the latest DOM snapshot to target one clear control.
+6. After each action, take the cheapest fresh check that proves what changed: DOM for structure, screenshot for visual state.
+7. Save and inspect the accepted screenshot before using it as audit evidence.
+
+Figma rules:
+
+- If Figma is the destination, load the required Figma skills before creating or editing the file.
+- Keep a local copy of every screenshot even when Figma succeeds.
+- Do not upload a screenshot to Figma until the saved local file has been inspected and accepted.
+- Figma is not done until the screenshots are visibly placed in the Figma output.
+- After placing screenshots in Figma, render or inspect the board and confirm every flow step has the correct screenshot visible in the correct card.
+- If an image is missing, misplaced, blank, or only uploaded as an unused asset, fix it before handoff.
+- If Figma tools cannot create files or place images, save the audit locally and explain the missing Figma capability.
+
+Evidence rules:
+
+- Use only evidence captured in the current audit run.
+- Do not use memory, prior chats, old traces, cached screenshots, or prior generated artifacts as audit evidence unless the user explicitly provides them.
+- Do not audit until the product, flow, destination, and capture tool are known.
+- Do not claim full accessibility compliance from screenshots alone.
+
+## Capture And Audit The Flow
+
+You are an expert design, UX, and accessibility auditor. For each step in the flow, capture what the user sees, observe how the screen behaves, inspect the screenshot, and write audit notes before moving on.
+
+Follow [references/design-audit-framework.md](references/design-audit-framework.md) when deciding what to inspect and how to describe strengths, UX issues, accessibility risks, limits, and recommendations.
+
+Screenshot source rule:
+
+- Use the screenshot you actually saw.
+- Save that exact screenshot to the local audit folder.
+- Open or inspect the saved file before accepting it.
+- If the saved file shows the wrong window, wrong state, blank page, crop, or loading screen, reject it and capture again.
+- When Figma is the destination, upload that accepted local file.
+- After upload, verify the Figma board shows the same step.
+- Do not replace a Browser, Chrome, or Computer Use screenshot with an OS screenshot unless you first prove the saved file shows the same window and state.
+
+For every step:
+
+1. Move to the next step in the requested flow.
+2. Wait until the screen is loaded and visually stable.
+3. Check for loading spinners, blank areas, login walls, error pages, blocked states, cookie dialogs, and half-rendered content.
+4. Capture the screenshot.
+5. Inspect the screenshot before accepting it.
+6. Reject the screenshot if it is blank, loading, cropped, blocked, or showing the wrong state.
+7. Observe behavior that matters for the audit, such as navigation, focus, loading, validation, error handling, empty states, motion, and whether the next action is clear.
+8. Write notes for that step.
+9. In the notes, report strengths, UX issues, accessibility risks, and any limits that made the step difficult to audit.
+10. Save accepted screenshots with numbered names, such as `01-start.png`, `02-form-filled.png`, and `03-confirmation.png`.
+11. Inspect the saved screenshot file before upload or handoff.
+12. Add each accepted screenshot to the chosen destination immediately.
+13. Add the notes for that step to the chosen destination immediately.
+
+If the destination is a local folder:
+
+- Save screenshots in that folder.
+- Save the notes in a file that can be shared at the end.
+
+If the destination is Figma:
+
+- Place screenshots in order, left to right on the same row, with 200px between each one. Go to a new row every 15 screenshots, and separate those rows by 600px.
+- Underneath the screenshot, add text with the Step number and its name, and notes.
+- Keep a local folder copy even when Figma succeeds.
+- When you are done, wrap all of the assets you added in a Section and title the section.
+
+Acceptance checks:
+
+- Every important step in the requested flow has a valid screenshot or a named blocker.
+- Screenshots are saved in order.
+- Screenshots are placed in the chosen destination as they are captured.
+- Notes are placed in the chosen destination as they are written.
+- Every note points to the screenshot or step it describes.
+- Notes explain strengths, UX issues, accessibility risks, and evidence limits when those apply.
+- Accessibility risks say what can be seen from screenshots and what still needs testing.
+- The final screenshot set and notes are enough to support the requested audit.
+
+Blockers:
+
+- The flow cannot be completed.
+- A required step cannot be screenshotted.
+- The source changes in a way that makes the flow unclear.
+- Screenshots cannot be saved or placed in the destination.
+- Notes cannot be written or placed in the destination.
+- The requested claim would require evidence that screenshots cannot provide.
+
+## Final Response
+
+After the flow is captured and notes are written, list every step in the final response.
+
+The final step list MUST include:
+
+- step number
+- short description of the step
+- general health of that step
+
+Also include where the full output was saved or placed.
+
+Keep the language direct. Do not use broad design jargon when a plain phrase works.

package/template/.codex/skills/product-design/skills/audit/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Audit"
+  short_description: "Audit or critique product UX and design from captured screenshots"
+  default_prompt: "Audit this product flow and report UX, design, and accessibility findings."
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/product-design/skills/audit/references/design-audit-framework.md

@@ -0,0 +1,73 @@
+# Design Audit Framework
+
+Use this structure for `audit`.
+
+Use `audit` for systematic assessment across a broader experience, not for feedback on a single artifact.
+
+## Audit modes
+
+- `UX audit`
+- `Accessibility audit`
+- `Combined audit`
+
+## UX audit lenses
+
+- Task entry and discoverability
+- Information architecture
+- Interaction flow and friction
+- Hierarchy and clarity
+- Trust and reassurance
+- Default states and empty states
+- Copy and calls to action
+- Consistency across the experience
+
+## Accessibility audit lenses
+
+- Perceivable content and contrast risks
+- Semantic structure and reading order
+- Keyboard access and focus behavior
+- Target size and interaction affordances
+- Labels, instructions, and error recovery
+- Motion, timing, and state change communication
+- Responsive reflow and zoom resilience
+- Assistive-technology clarity and robustness
+
+## UX audit output structure
+
+1. `Audit scope`
+2. `User goal`
+3. `Strengths`
+4. `Notable risks`
+5. `Opportunity areas`
+6. `Optional comparison context`
+7. `Recommendations`
+
+## Accessibility audit output structure
+
+1. `Audit scope`
+2. `Accessibility target`
+3. `Confirmed strengths`
+4. `Likely issues`
+5. `WCAG-relevant considerations`
+6. `Evidence limits and verification gaps`
+7. `Recommendations`
+
+## Combined audit output structure
+
+1. `Audit scope`
+2. `User goal and accessibility target`
+3. `Strengths`
+4. `UX risks`
+5. `Accessibility risks`
+6. `Opportunity areas`
+7. `Evidence limits and verification gaps`
+8. `Recommendations`
+
+## Guardrails
+
+- Focus on experience patterns, not business strategy.
+- Keep comparator products optional; use them only when they sharpen the audit.
+- Separate structural issues from polish issues.
+- Tie recommendations back to the user goal, workflow, or accessibility outcome.
+- Do not imply full WCAG compliance unless the user has provided the implementation details needed to support that claim.
+- If the request is about a single screen, component, modal, or bounded interaction, keep the audit scoped to that surface.

package/template/.codex/skills/product-design/skills/design-qa/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: design-qa
+description: "Internal prototype QA helper. Use only after a Product Design prototype, URL-to-code build, or image-to-code build has a source visual target and a rendered implementation to compare before handoff. Do not use for broad UX critique, design critique, product audits, or flow reviews; route those user-facing requests to audit."
+---
+
+# Design QA
+
+Use this internal helper to compare a prototype's source design against the rendered implementation before handoff.
+
+Do not use this skill for broad UX critique, design critique, product audits, or flow reviews. Use [audit](../audit/SKILL.md) for those user-facing requests.
+
+Use this skill before every Product Design build handoff.
+
+A passing QA run requires both:
+
+- a source visual target: Figma node, image, screenshot, mockup, or source capture
+- a rendered implementation: local URL, deployed URL, app screen, component, or screenshot
+
+If either artifact cannot be opened, captured, or compared, write `design-qa.md` with `final result: blocked` and name the blocker. Do not let the build skill hand off as done.
+
+## Critical Overrides
+
+Follow [critical-overrides](../../references/critical-overrides.md).
+
+## Workflow
+
+Compare the intended design to the implementation as a product-quality reviewer, not as a generic aesthetic critic. The output must be a prioritized fix list grounded in evidence from both artifacts.
+
+Do not write the QA review from memory, code, or file paths alone. Open or capture both the source design and the implementation first, then compare what is actually visible.
+
+Do not pretend separate image views are side-by-side comparison. Put the source image and the implementation screenshot together in the same comparison input, then judge the visible differences from that combined input.
+
+1. Identify the comparison target.
+   - Determine the source design: Figma node, image, design board, screenshot, spec, or mockup.
+   - Determine the implementation: local URL, deployed URL, app screen, component, screenshot, or code-rendered view.
+   - Match the same viewport, state, theme, device density, route, content, auth state, and interaction state before judging.
+   - If artifacts do not represent the same state, call that out first and avoid false precision.
+
+2. Capture evidence.
+   - For Figma, use design context and screenshot tools when available.
+   - For web/app implementations, open the target in a browser and capture screenshots at the intended viewport.
+   - Capture additional states when relevant: mobile/desktop, hover/focus/active, empty/loading/error, dark/light, and key responsive breakpoints.
+   - Save paths or URLs for screenshots when available so findings can cite evidence.
+   - Capturing screenshots is not enough. Put the source image and the implementation screenshot together in the same comparison input before judging.
+
+3. Normalize before comparing.
+   - Align crop, viewport size, scale, and device frame. Do not compare a framed mockup to an unframed page without noting the mismatch.
+   - Prefer comparing content regions over full browser chrome or surrounding canvas.
+
+4. Compare at the right level of detail.
+   - Use a full-view comparison to judge overall composition, hierarchy, layout, density, and responsive structure.
+   - Use focused region comparisons when important details are too small to judge in the full-view comparison.
+   - Choose focused regions from the actual source and implementation. Use them where fidelity depends on precise typography, alignment, imagery, assets, icons, logos, controls, forms, navigation, tables, dense UI, or visible interaction states.
+   - If no focused region is needed, say why in `design-qa.md`.
+   - Do not pass QA from a full-view comparison alone when important details are not clearly readable.
+
+5. Review systematically.
+   - Read [qa-rubric](./references/qa-rubric.md) when the QA pass spans more than a quick visual check.
+   - Check information architecture, layout, spacing, typography/fonts, color, imagery/image quality, icons, copy, affordances, interaction states, responsiveness, accessibility, and polish.
+   - Always make a specific pass over the five required fidelity surfaces: fonts/typography, spacing/layout rhythm, colors/tokens, image quality, and copy/content. Do this even if the user did not name those areas explicitly.
+   - If the mock does not address some issue you're seeing (e.g. a null state), call that out as a separate finding as a shortcoming of the mock to be addressed.
+   - Your other goal is to decide whether the implementation "looks as good" as the mock. If there are stylistic problems, call them out. If the user's prompt is leaking into the implementation (vs letting the app stand on its own), call that out as well.
+   - Distinguish design drift from intentional product/code constraints. If a deviation may be intentional, phrase it as a question or assumption.
+
+6. Produce a fix-oriented QA report.
+   - Lead with findings, ordered by severity and user impact.
+   - For each finding include: severity, location, what differs, evidence, why it matters, and the concrete fix.
+   - Include exact CSS/component/token suggestions when the implementation context is available.
+   - Separate objective mismatches from subjective polish recommendations.
+   - Do not say a design matches, is done, or is as good as it can get until the required fidelity surfaces have been checked and any remaining differences are explicitly classified as acceptable, expected, or still actionable.
+   - End with a concise implementation checklist.
+
+## Required Fidelity Surfaces
+
+Every QA report must explicitly evaluate these surfaces:
+
+- Fonts and typography: family, fallback, weight, size, line height, letter spacing, antialiasing, hierarchy, wrapping, truncation, and whether display text and small UI text use appropriate optical weights. It is incredibly important to check fonts carefully for fidelity, including looking up similar typefaces or using image analysis to find the font differences.
+- Spacing and layout rhythm: frame size, crop, alignment, margins, padding, grid tracks, section gaps, component spacing, radii, shadows/elevation, and vertical rhythm.
+- Colors and visual tokens: sampled or inferred palette, gradients, opacity, contrast, semantic state colors, foreground/background balance, and whether CSS tokens map to the source design.
+- Image quality and asset fidelity: subject correctness, crop, scale, sharpness, compression, transparency halos, masking, background treatment, raster-vs-vector appropriateness, and whether generated assets match the source art direction. Fail QA if logos, illustrations, decorative marks, product imagery, non-standard icons, or other visible image assets from the visual target were replaced with custom inline SVG, handcrafted SVG, HTML elements, div/span shapes, CSS drawings, gradients, emoji, text glyphs, placeholder shapes, or code-native approximations.
+- Copy and content of app-specific text
+
+## Severity
+
+- `P0`: Blocks core use, severe accessibility failure, broken layout, or impossible task.
+- `P1`: Major design mismatch or usability regression likely to be noticed by users.
+- `P2`: Moderate visual drift, inconsistent state, responsive issue, or fixable polish gap.
+- `P3`: Minor refinement that improves fidelity but does not block acceptance.
+
+## Output Format
+
+Use this structure unless the user asks otherwise:
+
+```markdown
+**Findings**
+- [P1] Short issue title
+  Location: screen/component/selector/file if known.
+  Evidence: design does X, implementation does Y.
+  Impact: why this matters.
+  Fix: concrete change.
+
+**Open Questions**
+- Any ambiguity about intentional deviations, unavailable states, or missing artifacts.
+
+**Implementation Checklist**
+- Ordered fixes that can be executed directly.
+
+**Follow-up Polish**
+- P3 refinements that can improve fidelity after handoff.
+```
+
+If there are no substantive mismatches, say that clearly and list any residual test gaps.
+
+When this skill is used before handoff, save the latest QA report as project-root `design-qa.md`.
+
+`design-qa.md` must include:
+
+- source visual truth path
+- implementation screenshot path
+- viewport
+- state
+- full-view comparison evidence
+- focused region comparison evidence, or why it was not needed
+- findings
+- patches made since the previous QA pass
+- final result
+
+`final result` must be exactly `passed` or `blocked`.
+
+Use `passed` when there are no actionable P0/P1/P2 findings. P3 findings may remain as follow-up polish.
+Use `blocked` when actionable P0/P1/P2 findings remain and name the blocker.
+
+Return the file path with the QA report.

package/template/.codex/skills/product-design/skills/design-qa/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Design QA"
+  short_description: "Internal prototype QA comparison against a visual source"
+  default_prompt: "Review this prototype against its visual source."
+policy:
+  allow_implicit_invocation: false