@ryuxdsgn/design-intelligence 2.13.6 → 2.13.8

package/dist/cli/index.js

@@ -167,16 +167,22 @@ async function runInstall(flags) {
     }
     if (nonInteractive)
         return;
+    let answers = {};
     if (!scope.global) {
         const s = await p.confirm({ message: "Set up project context now? Every question can be skipped.", initialValue: true });
         if (p.isCancel(s))
             return cancel();
-        if (s && !(await setupInteractive(scope.root)))
-            return cancel();
-        if (!s)
+        if (s) {
+            const a = await setupInteractive(scope.root);
+            if (!a)
+                return cancel();
+            answers = a;
+        }
+        else
             p.log.info(`Set it up later with: ${CLI_CMD} setup`);
     }
-    p.outro(`RYUX is ready. Try: ${pc.cyan('"Design a transaction detail page for our app."')}`);
+    p.note(suggestionsText(answers), "Try");
+    p.outro("RYUX is ready.");
 }
 async function runUpdate(flags) {
     const scope = scopeOf(flags);
@@ -578,11 +584,40 @@ async function setupInteractive(root) {
     p.log.info("Teach RYUX about this project. Every question can be skipped: blanks stay unknown, and RYUX asks when they matter.");
     const answers = await askContext(root);
     if (!answers)
-        return false;
+        return null;
     const body = await writeContext(root, answers);
     p.log.success(`${CONTEXT_FILE} updated · ${filledCount(body)} of ${ASKED_FIELDS.length} setup fields filled`);
-    return true;
+    return answers;
+}
+/** Curated, per product kind (setup's Product answer): a typical screen and flow to name in example prompts. */
+const SUGGESTED = {
+    "Online store": { screen: "the checkout page", flow: "our checkout flow" },
+    "Payments or finance": { screen: "the transaction detail screen", flow: "our send-money flow" },
+    "Marketplace": { screen: "the seller's new listing form", flow: "our listing flow" },
+    "Booking or scheduling": { screen: "the date and time slot picker", flow: "our booking flow" },
+    "SaaS or dashboard": { screen: "the billing settings page", flow: "our onboarding flow" },
+    "Content or media": { screen: "the article reading page", flow: "our sign-up flow" },
+    "Internal tool": { screen: "the orders table with filters", flow: "our approval flow" },
+};
+/** Three concrete prompts, one per entry point, from the setup answers; the README examples when there are none. */
+function promptSuggestions(answers) {
+    const kind = Object.keys(SUGGESTED).find((k) => (answers["Product"] ?? "").startsWith(k));
+    if (!kind) {
+        return [
+            "Design the transaction detail screen for our wallet, in pen.dev.",
+            "Critique our pricing page at https://example.com/pricing.",
+            "Analyze this checkout screen (screenshot attached).",
+        ];
+    }
+    const { screen, flow } = SUGGESTED[kind];
+    const changing = /existing flow|redesign/i.test(answers["Current work"] ?? "");
+    return [
+        `Design ${screen} for our app.`,
+        `Critique ${flow} and tell us what to fix first.`,
+        changing ? `Analyze ${flow} before we change it (screenshots attached).` : `QA the build of ${screen} against the design.`,
+    ];
 }
+const suggestionsText = (answers) => [...promptSuggestions(answers).map((s) => `"${s}"`), "", "RYUX may ask up to three questions first."].join("\n");
 async function runSetup(flags) {
     if (flags.global) {
         console.error(`setup is per project. Run it inside the project folder: ${CLI_CMD} setup`);
@@ -599,6 +634,7 @@ async function runSetup(flags) {
     if (Object.keys(fromFlags).length) {
         const body = await writeContext(root, fromFlags);
         console.log(`${pc.green("✓ ")}${CONTEXT_FILE} updated · ${filledCount(body)} of ${ASKED_FIELDS.length} setup fields filled`);
+        console.log(`\nTry:\n${suggestionsText(fromFlags).split("\n").map((l) => (l ? `  ${l}` : "")).join("\n")}`);
         return;
     }
     if (!process.stdin.isTTY) {
@@ -609,8 +645,10 @@ async function runSetup(flags) {
     }
     p.intro(pc.bgCyan(pc.black(" RYUX setup ")));
     p.log.message(KEY_LEGEND);
-    if (!(await setupInteractive(root)))
+    const answers = await setupInteractive(root);
+    if (!answers)
         return cancel();
+    p.note(suggestionsText(answers), "Try");
     p.outro(`RYUX is ready. Next: ${CLI_CMD} check`);
 }
 async function runInit(flags) {

package/dist/intelligence/content.js

@@ -130,6 +130,19 @@ export const RULES = [
             basis: "ryux evidence principle",
             check: "review",
         },
+        {
+            num: 11,
+            title: "An AI feature has a written standard for its output",
+            level: "contextual",
+            when: "the product shows content generated by AI: an answer, a summary, a draft, a recommendation",
+            do: "Before designing it, write what good and bad output look like, per kind of response:\n  - Sort the responses the feature gives (a short answer, an open explanation, a list, a draft, a refusal) and write pass criteria for each kind, concrete enough for a reviewer to check: \"answers the question in the first sentence; at most two related details\", not \"not too verbose\".\n  - Design the states generated output brings: a long and a short answer, no answer or a refusal, an answer that is wrong, slow generation, and a failed request (RX-EC-01).\n  - Hand the criteria to the team as the feature's test: real inputs checked against them before launch, and again after every model or prompt change.",
+            dont: "Design an AI feature around one ideal sample answer, judge its output by feel, or leave out the states where the output is wrong, empty, or slow.",
+            why: "Generated output cannot be specified exactly, so the design is only as good as its definition of good; a screen built around one perfect answer breaks on the next one.",
+            basis: "NNGroup design critique in the AI era (criteria per response type; judge, evaluate, iterate; watch for regressions); RX-EC-01",
+            notWhen: "AI that works behind the scenes and shows users no generated content",
+            tradeoff: "criteria per response type take time before the first screen and need real inputs to write well",
+            check: "review: a criteria list per response type, and the wrong, empty, slow, and failed states in the design",
+        },
     ]),
     ...skill("ux", [
         {
@@ -884,6 +897,58 @@ export const RULES = [
             tradeoff: "the reflective layer needs knowledge of what users value, which may need research",
             check: "review; Critique Design Read",
         },
+        {
+            num: 17,
+            title: "Illustration follows a written style",
+            level: "contextual",
+            when: "the design adds or makes illustration (spot, empty state, onboarding, hero) and the brand has no illustration system",
+            do: "Before the first drawing, write the style in five lines (six with characters) in DESIGN.md or the Assumptions:\n  - line: stroke weight and cap, or no stroke\n  - shape: geometric or hand-drawn, and the corner radius\n  - colour: 2 to 4 tokens from the palette, one accent\n  - depth and detail: flat, one shadow tone, or 3D; how much detail\n  - subject: objects from the product, people, or abstract\n  - characters, when the style has people or a mascot: proportions, face detail, the range of people shown, and a short set of poses and expressions; one character system across the product\n  - Derive each line from the visual language (RX-UI-10): the stroke from the icon set, the radius from the components, the colour from the tokens. Functional icons stay in the icon set (RX-UI-13), not in the illustration style.\n  - Record the style as a Decision Receipt: evidence from a brand guide, references, or the brief; Evidence None when it is derived from the visual language alone.",
+            dont: "Draw in the generator's default style (flat people with oversized limbs, gradient blobs, isometric 3D), or mix line and filled illustration in one product.",
+            why: "Without a written style, illustration drifts toward the generator's default and away from the UI around it.",
+            basis: "Art direction practice (a written illustration style); RX-UI-10 chosen visual language; anti-slop tell (generic illustration); owner review 2026-10-22: request for illustration guidance",
+            notWhen: "the brand already has an illustration system; follow it (RX-UI-13)",
+            tradeoff: "one more step before the first drawing, and less variety",
+            check: "review",
+        },
+        {
+            num: 18,
+            title: "A set reads as one family",
+            level: "contextual",
+            when: "the product uses more than one illustration (empty states, onboarding steps, errors)",
+            do: "Make the set together: same canvas and framing, same stroke and palette, same subject scale, viewpoint, and level of detail.\n  - Tie each subject to the screen's job: an empty state shows what will appear there, not a mascot shrugging.\n  - Put the set side by side before handoff and fix the one that stands out.",
+            dont: "Make each illustration in a separate prompt and hand them off without comparing them, or give one more detail or colour than the rest.",
+            why: "Users read a mismatched set as a mistake or a different product, and a generator drifts in style from prompt to prompt.",
+            basis: "Design-system practice (one illustration family); RX-DS-02 consistency; owner review 2026-10-22: request for illustration guidance",
+            notWhen: "a single illustration",
+            tradeoff: "the whole set is redone when the style changes",
+            check: "render, side by side",
+        },
+        {
+            num: 19,
+            title: "Illustration ships as a themed, accessible asset",
+            level: "contextual",
+            when: "illustration goes into a build, or into a design file that will be built",
+            do: "Flat and line art as SVG: colours from tokens (currentColor or CSS variables) so dark mode follows (RX-DS-05), a viewBox with no fixed size, no embedded raster, no text inside the art; text stays in the HTML so it can be translated and scaled.\n  - Raster art (generated or 3D) at 2x the displayed size, compressed, with width and height set so the layout does not jump.\n  - Decorative art gets aria-hidden or an empty alt; art that carries meaning gets alt text that says the meaning, not the drawing (RX-A11Y-04).",
+            dont: "Hard-code colours that vanish on dark, bake words into the image, ship an export with editor metadata, or write alt text that describes the picture (\"a woman holding a box\") instead of what it means.",
+            why: "Art that ignores tokens breaks in other themes, text inside an image cannot be read, translated, or zoomed, and alt text that only describes the drawing says nothing.",
+            basis: "WCAG 2.2 SC 1.1.1 (non-text content); RX-DS-03; RX-DS-05; RX-A11Y-04; owner review 2026-10-22: request for illustration guidance",
+            notWhen: "a concept frame that will not be built",
+            tradeoff: "SVG built from tokens takes longer than one export",
+            check: "render in every theme; read the SVG source",
+        },
+        {
+            num: 20,
+            title: "An icon means one thing, and says it",
+            level: "preferred",
+            when: "the design uses icons for actions, navigation, or status",
+            do: "Pick each icon for the action or concept it stands for, not for its look.\n  - One icon, one meaning across the product: no icon for two actions, no two icons for one action.\n  - Pair the icon with a text label unless it is one of the few users know without one in this context (search, close, back, menu, home). Keep the label in a tab bar, on uncommon actions, and on destructive ones.\n  - Tell look-alikes apart by what they do: back leaves the screen, close dismisses a sheet or modal; delete removes, cancel stops.\n  - Use the platform's icon for platform actions (share differs on iOS and Android).",
+            dont: "Choose an icon because it looks good, reuse one icon for two meanings, or ship an icon-only control whose meaning users have to guess.",
+            why: "Few icons are recognised without a label; an ambiguous icon costs more than a word, and an icon whose meaning changes breaks what users learned.",
+            basis: "NNGroup icon usability; Nielsen heuristic 4 (consistency and standards); Apple HIG and Material iconography",
+            notWhen: "a dense expert tool whose users learn the set; then a tooltip plus an accessible name",
+            tradeoff: "labels take space, especially in toolbars and tab bars",
+            check: "review: list each icon with its meaning and flag duplicates; heuristic_eval H-04",
+        },
     ]),
     ...skill("design-system", [
         {
@@ -963,7 +1028,7 @@ export const RULES = [
             title: "Readable text, reachable targets",
             level: "required",
             gate: "hard",
-            do: "Keep body text around 14 to 16px on mobile, and touch targets at least 24×24px, preferably 44×44px.",
+            do: "Keep body text around 14 to 16px on mobile, and touch targets at least 24×24px, preferably 44×44px. The target is the hit area, not the glyph: a 20 to 24px icon sits inside a 44×44 button.",
             dont: "Shrink body text or crowd small targets together.",
             why: "Small text and targets cause misreads and mis-taps.",
             basis: "WCAG 2.2 SC 2.5.8 (24px minimum); Apple HIG 44pt; Material 48dp; Fitts's law (Fitts 1954): bigger and nearer targets are faster to hit",
@@ -987,7 +1052,7 @@ export const RULES = [
             title: "Semantic structure, native controls, and names",
             level: "required",
             gate: "hard",
-            do: "Use real headings, landmarks, lists, buttons, links, and the right input types before custom elements, and give icon-only buttons and meaningful images an accessible name or alt text.",
+            do: "Use real headings, landmarks, lists, buttons, links, and the right input types before custom elements, and give icon-only buttons and meaningful images an accessible name or alt text. Hide decorative icons and images from assistive technology (aria-hidden, or an empty alt).",
             dont: "Build structure or controls from styled divs, or ship unlabeled icon buttons.",
             why: "Assistive technology navigates by semantics and announces unlabeled buttons as just \"button\"; native controls bring keyboard and platform behavior for free.",
             basis: "WCAG 2.2 SC 1.1.1, 1.3.1, and 4.1.2",
@@ -1456,6 +1521,7 @@ export const ACTIVATION = [
     { task: "Checkout or payment", skills: ["product", "interaction", "forms", "content", "edge-cases", "ui", "anti-slop"] },
     { task: "Data-heavy view (list, table, dashboard)", skills: ["ux", "edge-cases", "responsive", "design-system", "frontend", "ui", "anti-slop"] },
     { task: "Frontend logic or utilities (formatting, state, data shown to users)", skills: ["frontend", "content", "edge-cases"] },
+    { task: "AI feature (generated answers, summaries, drafts)", skills: ["product", "ux", "content", "edge-cases", "anti-slop"] },
     { task: "Copy only (UI text, chat, announcements)", skills: ["content", "anti-slop"] },
     { task: "Visual refinement", skills: ["ui", "design-system", "visual-qa", "anti-slop"] },
 ];

package/dist/intelligence/guides.js

@@ -11,8 +11,8 @@ generator, an anti-slop framework, a design system, or a prompt library.
 \`\`\`
 Understand → Frame → Explore → Evaluate and select → Build and critique → Verify and deliver → done
 \`\`\``;
-export const CORE_CAPABILITIES = `Tell RYUX what you are doing; RYUX decides what it needs to know. Pick the entry point, read its
-file, then only the knowledge modules the task needs (task table below); paths are relative to this skill's folder.
+export const CORE_CAPABILITIES = `Tell RYUX what you are doing; RYUX decides what it needs to know (no task named: offer three concrete tasks for this project as choices,
+from DESIGN.md and the repo's screens). Pick the entry point, read its file, then only the knowledge modules the task needs (task table below); paths are relative to this skill's folder.
 
 | Entry point | When | Read |
 | --- | --- | --- |
@@ -25,9 +25,8 @@ file, then only the knowledge modules the task needs (task table below); paths a
 Knowledge modules (\`knowledge/\`): product, ux, interaction, forms, edge-cases, content, ui,
 design-system, accessibility, responsive, frontend, and anti-slop. Evidence comes from the brief, the
 project, product data, standards, and the ryux MCP when connected; none is required. Every entry point ends at the quality gates: the Hard
-Gates below and the Delivery Gate, with anti-slop as the last check, never the starting point.
-
-Keep them apart: Analyze says what exists, Design what to do, Critique if it is right, QA if it matches.`;
+Gates below and the Delivery Gate, with anti-slop as the last check, never the starting point. Keep them apart:
+Analyze says what exists, Design what to do, Critique if it is right, QA if it matches.`;
 export const CORE_PRINCIPLE = `Novelty is not a goal; a recognisable brand layer is: familiar structure, distinct surface.
 Optimize for clarity, usability, consistency, product fit, accessibility, and intentional decisions.
 Understand the context first; keep observed facts apart from assumptions; prefer evidence over
@@ -44,7 +43,7 @@ export const CORE_WORKFLOW = `One workflow, six stages; each entry point runs th
 3. **Explore**: on a new or complex surface, two or three alternatives that differ in hypothesis and
    structure, not paint; reference screens through the ryux MCP when connected. A small change skips it.
 4. **Evaluate and select**: rate the alternatives against the Frame criteria with evidence
-   (RX-PR-09, RX-PR-10); the user picks; write the Decision Receipt.
+   (RX-PR-09, RX-PR-10); the user picks from options (capabilities/design.md); write the Decision Receipt.
 5. **Build and critique**: design or implement the choice, render, inspect, and fix; Reconsider an
    unchosen alternative when a finding contradicts the choice, and say why.
 6. **Verify and deliver**: Hard Gates, the Delivery Gate, honest claims, and a user test plan (RX-UX-12).
@@ -73,7 +72,11 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    (character, or brand colour and type) or the motion direction, ask for it in that message (it
    counts toward the three) instead of choosing it yourself. **No DESIGN.md and no product docs is the
    case where these questions matter most, never a reason to skip them:** ask, then wait for the
-   answer before designing. Complete context means no questions. Never ask what the prompt, DESIGN.md, or the
+   answer before designing. Complete context means no questions.
+   **Ask as choices.** When you ask, or the user picks (stage 4, Reconsider), use the agent's
+   question or choice tool if it has one: two to four options per question, the recommended one
+   first and labeled, and room for the user's own answer. Without such a tool, write numbered
+   options with the recommendation first, so the user can answer with a number. Never ask what the prompt, DESIGN.md, or the
    product docs already answer. For the rest, make the smallest reasonable assumption, write it
    down, and continue (RX-PR-01, RX-PR-02).
    **Record direction answers.** When the user answers a UI or motion direction question, write the
@@ -85,7 +88,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    **What exists.** When there is a screen, product, or design system already, read its
    analysis or run Analyze first (capabilities/analyze.md). Existing screens, components, and any
    screenshot or reference provided are your examples: read them before choosing patterns, take
-   their principles, and never copy their facts. Understand before you design. When the task
+   their principles, and never copy their facts. A request to copy a screenshot as it is goes to
+   Build as a recreate (capabilities/build.md, step 2). Understand before you design. When the task
    redesigns or improves what exists, list what works and keep it; change only what has a named
    problem (RX-UX-10).
    **Modules.** Read the modules the task needs from the task table before deciding anything, for example ux,
@@ -115,7 +119,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    - A small change, or a screen inside a fixed design system, skips Explore: say so and continue.
 4. **Evaluate and select.** Rate each alternative against the Frame criteria, Strong, Adequate, or
    Weak with one reason each, rate the evidence (RX-PR-10), and recommend one with a Decision Receipt.
-   "It looks better" is not a reason. Then stop and let the user choose. Build only the chosen one
+   "It looks better" is not a reason. Then stop and let the user choose, with the alternatives as
+   options and your recommendation first (stage 1, "Ask as choices"). Build only the chosen one
    into the full design (states, widths, Visual Brief, RX-UI-10), write the Design Direction
    below, and mark the others on the canvas as not chosen. When the user has already said to pick for
    them, continue with the recommendation and say so.
@@ -130,7 +135,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    roles, spacing, radius, and type sizes and families before the first frame, and components for
    repeated elements (RX-DS-03). Building the system does not replace the states: design every
    state that matters (empty, loading, error, including content that fails to load) and every width
-   you claim, and source assets on purpose (RX-UI-13).
+   you claim, and source assets on purpose (RX-UI-13); illustration follows a written style and is
+   made as one set (RX-UI-17, RX-UI-18).
    **Render and inspect.** Screenshot what you made, check it against the direction and the rules,
    fix, and render again (capabilities/qa.md). Then, on the render:
    - Literal values: turn each into a variable or name the exception (RX-DS-03).
@@ -244,7 +250,7 @@ Dissent      evidence only one source holds, or the case for an option not chose
 Evidence names its count and never generalizes past it. "Evidence None, Confidence Low, Why:
 business priority was not provided" is a valid receipt; keep it visible instead of upgrading it.
 
-Visual, motion, and asset rules and tables live in knowledge/ui.md (RX-UI-07 to RX-UI-13); this
+Visual, motion, and asset rules and tables live in knowledge/ui.md (RX-UI-07 to RX-UI-19); this
 direction only records the choices made with them.`;
 export const BUILD_BODY = `# RYUX Build
 
@@ -259,10 +265,15 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
 2. **Find the design source**: the Design Direction, a Figma or pen.dev design, a DESIGN.md, or an
    approved mockup; it is the spec. If there is none, run Design's Frame, Explore, and Evaluate
    first (capabilities/design.md, stages 2-4) instead of inventing one in code.
+   A screenshot or another product's page is a reference, not the spec, unless the user asks to
+   recreate it ("recreate", "match this", "samakan"). Then match it, let QA compare at the same
+   viewport, and still leave out another product's brand, logo, and content (RX-AS-11). With no word
+   either way, design from its principles and write "reference, not recreate" in Assumptions.
 3. **Read the modules the task needs** from the task table: for example accessibility, responsive,
    and edge-cases for any UI, and forms and content for a form. When the build adds motion or
    transitions, read knowledge/ui.md (RX-UI-11) before writing any: how often the surface is seen
-   decides how much it moves.
+   decides how much it moves. When it adds illustration, read RX-UI-19: SVG coloured from tokens,
+   no text inside, alt text that says the meaning.
 4. **Implement faithfully.** Use semantic elements, existing components, and real data paths.
    Build must not invent business rules, prices, or limits; API behavior or response shapes; or
    data presented as real (RX-FE-02, RX-PR-02). It must not silently change a design decision: a
@@ -493,7 +504,7 @@ gates in ryux-anti-slop). It works in four layers.
 4. **Density**: compact for repeat work, roomier for first-time or high-stakes decisions.
 5. **Color**: roles first (surface, text, accent for the primary action, status); contrast checked.
 6. **Containers**: use a container only when it groups or separates something.
-7. **Icons**: next to labels, from one set, at consistent sizes.
+7. **Icons**: next to labels, from one set, at consistent sizes, one meaning each (RX-UI-20).
 
 **Justify values.** Every value comes from the scale and has a reason you can say in one line:
 "12px between these two fields because they belong together; 24px before the next group because it
@@ -617,6 +628,11 @@ Sources:        reference screen_ids or the analysis it came from
 A generated image is illustrative art; never present it as a real customer or a real product
 screen (RX-UI-07).
 
+**Illustration.** With no brand system to follow, write the style in five lines before the first
+drawing, plus a character system when it has people or a mascot, and record it as a Decision
+Receipt (RX-UI-17); make a set together and compare it side by side (RX-UI-18), and ship it as SVG
+coloured from tokens, with no text inside and alt text that says the meaning (RX-UI-19).
+
 Does not cover: component reuse and tokens (see ryux-design-system).`,
     "design-system": `Prioritize the existing system. Before creating anything:
 
@@ -708,6 +724,11 @@ Card radius | 16px                 | 8px            | half the radius | minor
 
 **Without a reference**, check the build against its own intent and the rules below.
 
+**Illustration** (when the build has any): it matches the written style (RX-UI-17), a set reads as one
+family side by side (RX-UI-18), it reads at its real displayed size including the smallest width, it
+works in every theme, and nothing the user needs exists only in the image (RX-UI-19). Without a
+render, report these as NOT VERIFIED.
+
 **Loop**: implement → render → compare → fix → render again.
 
 **Render with what is available**, in this order: the project's own preview or test setup;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuxdsgn/design-intelligence",
-  "version": "2.13.6",
+  "version": "2.13.8",
   "description": "RYUX: design intelligence for AI agents and designers. One skill, five entry points: Analyze, Design, Build, Critique, and QA, for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Cline, Copilot, and more.",
   "type": "module",
   "bin": {