@ryuxdsgn/design-intelligence 2.13.7 → 2.14.0

package/dist/adapters.js

@@ -15,7 +15,7 @@ export const AGENTS_MD_INLINE = { id: "agents-md", label: "Any other agent (rule
 // Old per-concern installs (ruleset RX-1.x) mapped to the new skills, for --concerns.
 // RX-1.x --concerns values mapped to current skill ids (kept for migration).
 export const LEGACY_CONCERNS = {
-    ui: ["ui", "design-system", "responsive"],
+    ui: ["ui", "imagery", "design-system", "responsive"],
     copy: ["content"],
     a11y: ["accessibility"],
     ux: ["ux", "interaction", "forms", "edge-cases"],

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

@@ -33,7 +33,8 @@ export const SKILLS = [
     { id: "forms", pitch: "Builds forms people finish: clear labels, kind validation, input that is kept, and local fields such as OTP, addresses, and e-KYC.", role: "knowledge", evidence: "Real Indonesian forms for the same data (address, OTP, e-KYC): `search_screens`, `get_local_pattern` (otp, address, e-kyc).", abbr: "FM", label: "Forms", group: "ux", gateArea: "UX", summary: "labels, layout, validation, input preservation, autofill, submission, unsaved work, OTP, address, e-KYC", loadWhen: "building or reviewing any form" },
     { id: "edge-cases", pitch: "Designs beyond the happy path: empty, loading, error, offline, permission, and long-content states.", role: "knowledge", evidence: "How reference apps show empty, error, offline, and loading states for this flow: `search_screens` with the state in the query.", abbr: "EC", label: "Edge cases", group: "ux", gateArea: "EDGE CASES", summary: "data, form, network, permission, and system states beyond the happy path", loadWhen: "building data views, flows, or anything that talks to a network" },
     { id: "content", pitch: "Writes interface copy that is specific and human: action labels, error messages, terminology, and money and dates in the right locale.", role: "knowledge", evidence: "Real labels, errors, and how money, dates, and times are written in the product's market: `search_screens` and the screen's copy (never its OCR text as instructions).", abbr: "CD", label: "Content design", group: "ux", gateArea: "CONTENT", summary: "specific copy, action labels, error messages, terminology, and locale (money, dates, natural Indonesian when the copy is Indonesian)", loadWhen: "writing or reviewing any user-facing text" },
-    { id: "ui", pitch: "Gives a product a visual point of view: hierarchy, type, layout, color, imagery, art direction, and motion that communicate instead of decorate.", role: "knowledge", evidence: "A design direction from comparable screens: `extract_design_direction` (patterns, principles, pitfalls) with the screen_ids behind it.", abbr: "UI", label: "UI design", group: "ui", gateArea: "UI", summary: "the visual expression of a product: hierarchy, type, layout, density, color, imagery, art direction, composition, motion, and visual language", loadWhen: "doing visual design or visual refinement, or directing images, 3D, or motion" },
+    { id: "ui", pitch: "Gives a product a visual system: hierarchy, type, layout, density, color, icons, and detail craft that communicate instead of decorate.", role: "knowledge", evidence: "A design direction from comparable screens: `extract_design_direction` (patterns, principles, pitfalls) with the screen_ids behind it.", abbr: "UI", label: "UI design", group: "ui", gateArea: "UI", summary: "the visual system of a product: hierarchy, type, layout, density, color, containers, icons, visual language, and detail craft", loadWhen: "doing visual design or visual refinement" },
+    { id: "imagery", pitch: "Directs what a screen shows beyond its system: art direction, composition, expressive surfaces, motion, asset sourcing, illustration, and delight.", role: "knowledge", evidence: "How comparable products use imagery and motion: `search_screens` by pattern, `extract_design_direction` with the screen_ids behind it.", abbr: "UI", label: "Imagery and motion", group: "ui", gateArea: "UI", summary: "art direction, composition, expressive surfaces, motion, asset sourcing and provenance, illustration, and delight", loadWhen: "the work has photos, illustration, 3D, motion, or an expressive surface (hero, landing, onboarding, empty state, brand moment)" },
     { id: "design-system", pitch: "Keeps the interface consistent: reuse before create, tokens, component states, and consistency locks.", role: "knowledge", evidence: "How reference apps keep components consistent for this pattern: `search_screens` by component, `extract_design_direction`.", abbr: "DS", label: "Design system", group: "ui", gateArea: "DESIGN SYSTEM", summary: "search before create, tokens, component states, consistency locks", loadWhen: "adding or changing components, styles, or tokens" },
     { id: "accessibility", pitch: "Makes the interface work for everyone: semantics, keyboard, focus, contrast, target size, and reduced motion, checked against WCAG 2.2.", role: "knowledge", evidence: "Standards are the main evidence (WCAG 2.2 success criteria); reference screens show local patterns that meet them: `search_screens`.", abbr: "A11Y", label: "Accessibility", group: "ui", gateArea: "ACCESSIBILITY", summary: "semantics, keyboard, focus, contrast, targets, names, errors, reduced motion", loadWhen: "building or reviewing any UI" },
     { id: "responsive", pitch: "Makes layouts hold up at every width: what to prioritize, simplify, reorganize, and stack.", role: "knowledge", evidence: "How reference flows adapt across widths when captured: `get_flow`, `search_screens` for the mobile pattern.", abbr: "RD", label: "Responsive design", group: "ui", gateArea: "RESPONSIVE", summary: "prioritize, simplify, reorganize; tables, overlays, overflow, safe areas", loadWhen: "building a layout that ships to more than one width" },
@@ -130,6 +131,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", [
         {
@@ -770,6 +784,57 @@ export const RULES = [
             check: "review",
             formerly: ["RX-C-02"],
         },
+        {
+            num: 10,
+            title: "Visual language is chosen, not defaulted",
+            level: "preferred",
+            do: "Derive the art direction from the brand, the audience, the product context, and reference screens, and write it as a Visual Brief (template in knowledge/imagery.md) (objective, concept, composition, color, material, lighting, motion, avoid) before designing an expressive surface or generating images, 3D, or motion.\n  - For a new product, decide the brand direction before the tokens, task UI included: palette, type, and shape follow from the product's character (fast, warm, trusted, and so on), not from the one accent that passes contrast.",
+            dont: "Reach for the category cliché (coins, money rain, floating dashboards, or gradient blobs for fintech; generic 3D characters for any app), or write an image prompt without a brief (role, concept, composition).",
+            why: "A default visual language makes the product interchangeable with its competitors.",
+            basis: "art direction practice; RX-AS-05 purpose gate",
+            notWhen: "an existing brand system already defines the visual language; follow it",
+            tradeoff: "a brief takes time before any image exists",
+            check: "the Visual Brief; review",
+        },
+        {
+            num: 14,
+            title: "Type that is set, not only sized",
+            level: "preferred",
+            gate: "lock",
+            do: "Set the type, not only its size:\n  - body paragraphs at 45 to 75 characters per line, checked in the render\n  - line-height from size: about 1.5 for body, 1.2 to 1.3 for headings, about 1.1 for display\n  - small uppercase labels opened slightly (about 0.05em), large display text tightened slightly\n  - tabular figures for numbers that are compared or that change (amounts, tables, timers)\n  - at most two families and three weights\n  - headings balanced so none ends on one stranded word",
+            dont: "Let paragraphs run the full width of a desktop container, use one line-height for every size, set uppercase labels with no tracking, or let amounts in a column shift because digits differ in width.",
+            why: "Line length and leading decide whether text is read or skimmed; aligned figures make numbers comparable at a glance.",
+            basis: "Bringhurst, The Elements of Typographic Style (a measure of 45 to 75 characters; leading by size); WCAG 2.2 SC 1.4.12 text spacing; OpenType tnum; Apple HIG and Material type scales",
+            notWhen: "a single display line or a logo lockup, where the type is an image",
+            tradeoff: "narrower text columns leave more empty space on wide screens",
+            check: "measure the render: characters per line, line-height, letter-spacing, font-variant-numeric, families and weights in use",
+        },
+        {
+            num: 15,
+            title: "Detail craft",
+            level: "preferred",
+            gate: "lock",
+            do: "Center icons on the optical middle of the text beside them and size them to its line-height; match icon stroke to the type weight; right-align (or decimal-align) number columns; take borders, dividers, radii, and shadows from a small token set; truncate long text on purpose, with the full value still reachable (a tooltip, a detail view, or wrapping).",
+            dont: "Let icons sit high or low against their labels, mix stroke weights, center amounts in a table, or invent a one-off shadow for one card.",
+            why: "Each detail is small; together they are what makes a screen look made rather than generated.",
+            basis: "Bringhurst (figures and alignment); Apple HIG and Material iconography (optical size and alignment); owner review 2026-10-17: wrong tab icons in withryux.pen",
+            check: "render inspection at 390 and 1280: icon center within 2 px of the text center; column alignment",
+        },
+        {
+            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("imagery", [
         {
             num: 7,
             title: "Imagery has a job and is what it claims",
@@ -796,18 +861,6 @@ export const RULES = [
             tradeoff: "less freedom to place the subject",
             check: "render at each width; review",
         },
-        {
-            num: 10,
-            title: "Visual language is chosen, not defaulted",
-            level: "preferred",
-            do: "Derive the art direction from the brand, the audience, the product context, and reference screens, and write it as a Visual Brief (objective, concept, composition, color, material, lighting, motion, avoid) before designing an expressive surface or generating images, 3D, or motion.\n  - For a new product, decide the brand direction before the tokens, task UI included: palette, type, and shape follow from the product's character (fast, warm, trusted, and so on), not from the one accent that passes contrast.",
-            dont: "Reach for the category cliché (coins, money rain, floating dashboards, or gradient blobs for fintech; generic 3D characters for any app), or write an image prompt without a brief (role, concept, composition).",
-            why: "A default visual language makes the product interchangeable with its competitors.",
-            basis: "art direction practice; RX-AS-05 purpose gate",
-            notWhen: "an existing brand system already defines the visual language; follow it",
-            tradeoff: "a brief takes time before any image exists",
-            check: "the Visual Brief; review",
-        },
         {
             num: 11,
             title: "Motion earns its level",
@@ -847,30 +900,6 @@ export const RULES = [
             tradeoff: "real or licensed assets take longer than a stock search",
             check: "asset list with sources; review",
         },
-        {
-            num: 14,
-            title: "Type that is set, not only sized",
-            level: "preferred",
-            gate: "lock",
-            do: "Set the type, not only its size:\n  - body paragraphs at 45 to 75 characters per line, checked in the render\n  - line-height from size: about 1.5 for body, 1.2 to 1.3 for headings, about 1.1 for display\n  - small uppercase labels opened slightly (about 0.05em), large display text tightened slightly\n  - tabular figures for numbers that are compared or that change (amounts, tables, timers)\n  - at most two families and three weights\n  - headings balanced so none ends on one stranded word",
-            dont: "Let paragraphs run the full width of a desktop container, use one line-height for every size, set uppercase labels with no tracking, or let amounts in a column shift because digits differ in width.",
-            why: "Line length and leading decide whether text is read or skimmed; aligned figures make numbers comparable at a glance.",
-            basis: "Bringhurst, The Elements of Typographic Style (a measure of 45 to 75 characters; leading by size); WCAG 2.2 SC 1.4.12 text spacing; OpenType tnum; Apple HIG and Material type scales",
-            notWhen: "a single display line or a logo lockup, where the type is an image",
-            tradeoff: "narrower text columns leave more empty space on wide screens",
-            check: "measure the render: characters per line, line-height, letter-spacing, font-variant-numeric, families and weights in use",
-        },
-        {
-            num: 15,
-            title: "Detail craft",
-            level: "preferred",
-            gate: "lock",
-            do: "Center icons on the optical middle of the text beside them and size them to its line-height; match icon stroke to the type weight; right-align (or decimal-align) number columns; take borders, dividers, radii, and shadows from a small token set; truncate long text on purpose, with the full value still reachable (a tooltip, a detail view, or wrapping).",
-            dont: "Let icons sit high or low against their labels, mix stroke weights, center amounts in a table, or invent a one-off shadow for one card.",
-            why: "Each detail is small; together they are what makes a screen look made rather than generated.",
-            basis: "Bringhurst (figures and alignment); Apple HIG and Material iconography (optical size and alignment); owner review 2026-10-17: wrong tab icons in withryux.pen",
-            check: "render inspection at 390 and 1280: icon center within 2 px of the text center; column alignment",
-        },
         {
             num: 16,
             title: "Delight stands on three legs",
@@ -923,19 +952,6 @@ export const RULES = [
             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", [
         {
@@ -1508,6 +1524,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/critique.js

@@ -18,7 +18,7 @@ Critique
      ↓
 Analyze                   what is actually there
      ↓
-knowledge modules         ux, ui, interaction, forms, content, accessibility,
+knowledge modules         ux, ui, imagery, interaction, forms, content, accessibility,
                           responsive, design-system, edge-cases, anti-slop
      ↓
 RYUX Knowledge            real product screens (search_screens, heuristic_eval)
@@ -117,7 +117,8 @@ could carry (RX-UX-08); report extraneous load, never the content the task needs
 | Interaction | ryux-interaction | before, during, result, recovery; confirm or undo; cost upfront; local payments |
 | Forms | ryux-forms | labels, validation, input kept, submission states |
 | Content | ryux-content | specific labels, errors, terminology, Rupiah, dates and numbers |
-| UI | ryux-ui | hierarchy, scale, color roles, density; each visual's job, composition around the copy, motion level; the result against its Visual Brief when there is one |
+| UI | ryux-ui | hierarchy, scale, color roles, density, icons |
+| Imagery and motion | ryux-imagery | each visual's job, composition around the copy, motion level, illustration style; the result against its Visual Brief when there is one |
 | Design system | ryux-design-system | consistency, tokens, component states |
 | Accessibility | ryux-accessibility | contrast, targets, focus, names, color alone |
 | Responsive | ryux-responsive | what changes, stays, disappears, or stacks across widths |

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 |
 | --- | --- | --- |
@@ -22,12 +22,11 @@ file, then only the knowledge modules the task needs (task table below); paths a
 | **Critique** | find what should change first, and why; a heuristic evaluation | \`capabilities/critique.md\` |
 | **QA** | verify a build against the intended design | \`capabilities/qa.md\` |
 
-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
+Knowledge modules (\`knowledge/\`): product, ux, interaction, forms, edge-cases, content, ui, imagery (images, motion,
+illustration, expressive surfaces), 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
@@ -116,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.
@@ -200,7 +204,8 @@ UI direction   layout and grid; type scale; spacing and density; color roles; co
                the icon style (outline or filled, stroke weight, corners)
 Design language personality, tone, interaction personality, density, formality; each with its
                reason from the product, the audience, or the existing system
-Visual direction for expressive surfaces: the Visual Brief (knowledge/ui.md, Visual production)
+Visual direction for expressive surfaces: the Visual Brief (knowledge/imagery.md, Visual production)
+Illustration   the written style (RX-UI-17), before the first drawing; "none" when the design has none
 Motion direction each motion: purpose (what it communicates: state change, feedback, spatial
                relationship, progress, hierarchy), lifecycle (before, trigger, transition, new
                state, feedback), level L1 to L5, timing and easing from one personality,
@@ -246,7 +251,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-19); this
+Visual, motion, and asset rules and tables live in knowledge/ui.md and knowledge/imagery.md; this
 direction only records the choices made with them.`;
 export const BUILD_BODY = `# RYUX Build
 
@@ -267,7 +272,7 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
    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
+   transitions, read knowledge/imagery.md (RX-UI-11) before writing any: how often the surface is seen
    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.
@@ -491,7 +496,8 @@ Does not cover: layout of the text (see ryux-ui).`,
     ui: `**Visuals are not decoration. They are communication.** RYUX UI owns the visual expression of
 a product: what each visual decision communicates, why it exists, and how it behaves. Functional UI
 helps the user read, decide, or act. Anything decorative needs a stated reason (see the purpose
-gates in ryux-anti-slop). It works in four layers.
+gates in ryux-anti-slop). This module is the visual system; art direction, motion, assets, and
+illustration live in knowledge/imagery.md, read when the work has them.
 
 **1. UI system.** Work in this order:
 1. **Hierarchy**: what is read first, second, third? The primary action and key information win.
@@ -521,7 +527,13 @@ their text, sized to its line-height, with a stroke that matches the type weight
 right or on the decimal. Borders, dividers, and shadows come from one small token set. Long text
 truncates on purpose, with the full value still reachable.
 
-**2. Art direction.** Each visual has a job (RX-UI-07), its composition leaves room for the
+Does not cover: component reuse and tokens (see ryux-design-system), or imagery, motion, and
+assets (see knowledge/imagery.md).`,
+    imagery: `**What a screen shows beyond its system.** Read this with ryux-ui when the work has photos,
+illustration, 3D, motion, or an expressive surface (hero, landing, onboarding, empty state, brand
+moment). It works in three layers.
+
+**1. Art direction.** Each visual has a job (RX-UI-07), its composition leaves room for the
 content (RX-UI-09), and the visual language is chosen, not defaulted (RX-UI-10). Name the visual
 language in a few words (editorial, product-centric, human, technical, playful, premium,
 institutional) and its form (shape language, geometric or organic, flat or with depth).
@@ -548,7 +560,7 @@ Then run the swap test (RX-AS-09): with a competitor's name and logo, would anyt
 If not, the surface has no point of view yet. Stay honest while being bold: a strong idea never
 needs invented numbers, people, or logos.
 
-**3. Motion.** Start from purpose: what the motion communicates; with no purpose, no motion.
+**2. Motion.** Start from purpose: what the motion communicates; with no purpose, no motion.
 Then ask how often someone will see it. The more often, the less of it they should notice: what
 people open many times a day (a command palette, a shortcut, core navigation) appears at once, and
 expression is kept for occasional or first-time moments. A purpose does not outweigh frequency.
@@ -584,7 +596,7 @@ defaults as soon as the product sets its own. Data the user is reading (a balanc
 table value) does not move for effect. With reduced motion requested, large movement becomes a fade
 or a cut (RX-A11Y-08).
 
-**4. Visual production.** Decide where each asset comes from before making anything (RX-UI-13):
+**3. Visual production.** Decide where each asset comes from before making anything (RX-UI-13):
 
 | Asset | First choice | Then | Never |
 | --- | --- | --- | --- |
@@ -613,6 +625,8 @@ Concept:        the visual thesis, in one sentence
 Subject:        what is shown (the product concept, not a generic person or device)
 Visual language: editorial / product-centric / technical / ..., and the art direction
 Form:           shape language, geometric or organic, depth
+Illustration:   when there is any, its written style before the first drawing (RX-UI-17): line,
+                shape, colour tokens, depth and detail, subject, characters
 Composition:    where the subject sits, and the space kept for copy
 Color, material, lighting: from the product palette; surfaces; direction and softness
 Motion:         level (L1 to L5) and personality
@@ -629,7 +643,8 @@ drawing, plus a character system when it has people or a mascot, and record it a
 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).`,
+Does not cover: the visual system, hierarchy, type, and icons (see ryux-ui), or component reuse
+and tokens (see ryux-design-system).`,
     "design-system": `Prioritize the existing system. Before creating anything:
 
 1. Search existing components.

package/dist/render.js

@@ -37,7 +37,7 @@ export function deliveryGateTemplate() {
     const lines = [...GATE_AREAS, "FINAL"].map((a) => a === "FINAL"
         ? `${a.padEnd(width)}PASS | FAIL | NOT VERIFIED`
         : a === "UI"
-            ? `${a.padEnd(width)}PASS | FAIL | NOT VERIFIED | N/A  · one-line reason · point of view: <concept> | task UI, signature: <signature>`
+            ? `${a.padEnd(width)}PASS | FAIL | NOT VERIFIED | N/A  · one-line reason · point of view: <concept> | task UI, signature: <signature> · illustration style: <where written> | none`
             : a === "PRODUCT"
                 ? `${a.padEnd(width)}PASS | FAIL | NOT VERIFIED | N/A  · one-line reason · evidence Strong | Thin | None`
                 : a === "EDGE CASES"
@@ -72,14 +72,14 @@ ${CORE_EVIDENCE}
 
 ${LEVELS}
 
-## Hard Gates (always apply)
-
-No written exception; fix before delivery.
+## Hard Gates (always apply; no written exception, fix before delivery)
 
 ${hardGatesBrief()}
 
 ## Task table: which knowledge to read
 
+A small change (a copy fix, one component, one state) reads only the module it touches, plus anti-slop for visual work; any other task reads its row, plus \`knowledge/imagery.md\` when it has photos, illustration, 3D, motion, or an expressive surface:
+
 ${activationTable()}
 
 ## Delivery Gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuxdsgn/design-intelligence",
-  "version": "2.13.7",
+  "version": "2.14.0",
   "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": {