create-yss-spec 1.1.2 → 1.1.3

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

package/template/.codex/skills/product-design/skills/design-qa/references/qa-rubric.md

@@ -0,0 +1,61 @@
+# QA Rubric
+
+Use this rubric for comprehensive design-to-implementation QA.
+
+## Fidelity
+
+- Layout: frame size, grid, alignment, content order, spatial grouping, card radius, elevation, borders.
+- Spacing: page margins, section gaps, item gaps, padding, tap-target spacing, vertical rhythm, cramped text, collapsed sections, and density drift.
+- Typography: font family, weight, size, line height, letter spacing, wrapping, truncation, hierarchy, text density, optical balance, and mismatched display/body treatment.
+- Color: token mapping, contrast, brand palette, state colors, gradients, opacity, shadows.
+- Imagery: all target image assets are accounted for and match subject accuracy, crop, aspect ratio, generated/real image quality, background treatment.
+- Icons: all icons are accounted for and match stroke weight, size, style family, alignment, optical balance, state changes.
+- Shape and surfaces: rounded cards, borders, dividers, shadows, fills, and container treatments match the target rather than generic component defaults.
+- Responsiveness: elements do not overlap, collapse into adjacent sections, clip, wrap awkwardly, or break hierarchy across desktop, tablet, and mobile viewports.
+- Implementation shortcuts: custom CSS art, inline SVG substitutes, placeholder avatars, decorative blobs, and fake product imagery are flagged when they drift from the target design.
+
+## Mandatory Comparison Passes
+
+Do not rely on generic "looks close" judgment. For each design QA pass, inspect and report on these areas:
+
+### Core design and functionality
+
+- Fonts and typography: identify mismatched font family/fallback, weight, scale, line height, letter spacing, antialiasing, text hierarchy, wrapping, truncation, display-vs-body optical treatment, cramped text, and places where text spacing makes the UI feel broken or harder to scan.
+- Spacing and layout: compare frame/crop, alignment, margins, padding, gaps, component sizes, radii, elevation, borders, and vertical rhythm. Cite where spacing drift changes hierarchy, density, readability, or causes elements to collide.
+- Viewport resilience: check desktop, tablet, and mobile widths for overlapping elements, clipped content, collapsing sections, broken grids, awkward wrapping, and controls that become unusable.
+- Colors and tokens: compare palette, gradients, opacity, shadows, contrast, semantic status colors, disabled/active states, and whether implementation tokens map to design intent.
+- Image quality and asset fidelity: check subject match, crop, scale, aspect ratio, sharpness, compression, transparency/masking artifacts, halos, background integration, and raster-vs-vector suitability. Div/CSS art or custom SVG art that replace images in the target design are banned.
+- Copy and content: for any copy that is part of the app, not dynamic content, check that it is coherent, makes sense in the standalone context of the app, and is visually appealing.
+- Icons: zoom in and analyze all visible icons and icons hidden behind controls/interactions to ensure they are fully implemented, aligned, and visually consistent.
+- States and interactions: expand/collapse sidebars, tooltips, forms, hover, focus, active, selected, disabled, loading, success, error, empty states, and any interactive controls needed for a functional frontend.
+- AI shortcut artifacts: flag generic rounded cards, unnecessary borders, decorative CSS blobs, fake SVG illustrations, half-built avatars, mismatched hero art, and custom CSS/SVG replacements where the target called for real imagery, real icons, or a different surface treatment.
+
+### Accessibility
+
+- Contrast, focus indicators, keyboard reachability, semantic controls, labels, alt text, reduced motion.
+- Text scaling and zoom resilience.
+- Tap targets at practical mobile sizes.
+- Layout stability when text wraps, scales, or appears in longer real-world strings.
+
+## Finding Quality
+
+A useful finding includes:
+
+- One specific mismatch or flaw.
+- Design evidence and implementation evidence.
+- User or fidelity impact.
+- Concrete fix, ideally with file/component/token/CSS guidance.
+- Severity based on user impact, not personal taste.
+- The affected fidelity surface when relevant: fonts, spacing, colors, image quality, layout, behavior, accessibility, content, icons, or responsiveness.
+- Crammed text, broken wrapping, mismatched font weights, bad line height, or awkward letter spacing when they affect readability or hierarchy.
+- Elements that overlap, clip, collapse into nearby sections, or break at alternate viewport sizes.
+- Rounded cards, borders, shadows, or container treatments that appear in the implementation but are not present in the target.
+- Borked icons, custom SVGs, half-assed attempts at avatars, hero art mismatches, custom CSS art, and placeholder-looking generated assets.
+- Overflowing text, cramped text, broken layout, missing states, and incomplete interactions.
+
+Avoid:
+
+- Vague statements such as "make it more polished."
+- Criticizing known placeholder content unless it affects the design goal.
+- Treating every pixel difference as a bug when the design intent is preserved.
+- Mixing multiple unrelated flaws into one finding.

package/template/.codex/skills/product-design/skills/get-context/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: get-context
+description: "Mandatory design-brief gate for Product Design build and design workflows. Use before ideation, prototyping, image-to-code builds, redesigns, or product UI work to clarify missing product, visual, and interactivity context or play back the supplied brief before proceeding."
+---
+
+# Get Context
+
+Gather only the context needed for the next design action. This skill resolves or confirms the design brief; it does not implement UI or create durable design artifacts.
+
+Run this skill at the start of Product Design requests that ask to design, build, prototype, clone, redesign, extend, or generate product UI directions.
+
+Use question mode when any of the following are unclear:
+
+- what product, site, feature, workflow, component, or screen is being designed
+- what visual source should determine how it looks
+- what concrete preferences or avoidances should shape visual exploration when no source exists
+- what level of interactivity the user expects
+
+Use playback mode when the user already provided the needed details. In playback mode, do not re-ask answered questions; play back the brief in a pithy format and name the next workflow.
+
+Hard boundary: do not implement UI, scaffold a prototype, start a server, or create files while context is still missing.
+
+## 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.
+
+## Get Context Script
+
+The following three questions should be answered by the user. Adapt the questions based on what the user has provided so far in the conversation. If some or all fields are already known, skip the questions and summarize the design brief in your own words.
+
+The questions to answer are:
+
+> What do you want the thing to do?
+
+> What existing product, design system, Figma file, screenshot, URL, image, or other visual source should it match? If none, what look are you going for? Mention existing design systems already in user-context if they exist.
+
+> What level of interactivity should the thing have?
+
+One of:
+
+- Full interactivity: all controls and states are completely functional and implemented.
+- Static: controls and states are minimally interactive, preferring speed.
+
+After the questions, reply with a pithy design brief that summarizes what you're about to explore. Avoid walls of text at all costs. Be clear and concise.
+
+Example script to follow:
+
+```
+Before I build, the Product Design workflow needs a quick design brief.
+
+What should the login page do? Email/password only, magic link, SSO, sign-up link, forgot password?
+Do you have an existing design system, app, Figma, or screenshot to match?
+If not, what look are you going for?
+Interactivity level: full working form states, or a faster mostly-static mock?
+
+```
+
+## Final message
+
+1. Before proceeding to `$ideate`, `$prototype`, `$url-to-code`, or `$image-to-code`, confirm the design brief by explaining it back to the user in a pithy format as a `final` message.
+
+2. Proceed only after the user confirms the design brief, unless the current thread already contains confirmation of that exact brief. If the user provides feedback, continue to refine the design brief with them.
+
+3. After the user confirms the design brief, send one short expectation-setting note before starting an involved app, prototype, clone, redesign, or build. Example confirmation message with expectations setting:
+
+```text
+Lovely, brief locked. This kind of build usually takes about 10-15 minutes, and ambitious ones can take longer. Good moment to grab coffee or tend to something else; I'll keep moving and bring the prototype back when it is ready.
+```
+
+Do not send this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.
+
+Done means the user has confirmed the design brief.