@ryuxdsgn/design-intelligence 2.13.1 → 2.13.2

package/dist/intelligence/analyze.js

@@ -126,7 +126,7 @@ Each item above carries its label and source; RYUX Knowledge screen_ids where us
 - Whether the amounts are real data or examples
 \`\`\`
 
-### 6. Optional: a visual direction, not a copy
+### 6. Optional: a Visual Brief, not a copy
 
 When asked to make something "with the same visual language", extract the direction (traits, art
 direction, composition habits, motion personality) and write it as a Visual Brief for the new

package/dist/intelligence/content.js

@@ -55,7 +55,7 @@ export const RULES = [
             num: 1,
             title: "State the context first",
             level: "required",
-            do: "Before designing, write down the user, their task, the business goal, the design intent (what the user must understand, feel, and do), the information that matters, the primary action, the constraints, and what success looks like. Take what the prompt and DESIGN.md already give; ask only when a missing answer materially affects the user flow, what the product can do, or whether the content is correct, or when neither the prompt nor DESIGN.md sets the UI or motion direction, at most three questions in one message, most consequential first (none when the context is complete). Otherwise make the smallest reasonable assumption, write it down, and continue.",
+            do: "Before designing, write down the user, their task, the business goal, the design intent (what the user must understand, feel, and do), the information that matters, the primary action, the constraints, and what success looks like.\n  - Take what the prompt and DESIGN.md already give.\n  - Ask only when a missing answer materially affects the user flow, what the product can do, or whether the content is correct, or when neither the prompt nor DESIGN.md sets the UI or motion direction: at most three questions in one message, most consequential first, none when the context is complete.\n  - Otherwise make the smallest reasonable assumption, write it down, and continue.",
             dont: "Start from a generic template with no stated user or task, or ask questions the prompt or DESIGN.md already answers.",
             why: "Without a task, design and review drift into taste.",
             basis: "ryux-critique playbook; NNGroup task-based evaluation",
@@ -66,7 +66,7 @@ export const RULES = [
             title: "Unknowns stay assumptions",
             level: "required",
             gate: "hard",
-            do: "Sort what the brief does not say into three kinds. Design assumptions (low-risk visual or structural choices such as a merchant category icon or grouping by date): decide them from the context. Unconfirmed capabilities (an action or feature the category usually has, such as sharing a receipt): convention is not proof, so ask when it materially changes the flow or scope; otherwise you may propose it, listed as unconfirmed, never as a requirement. Facts, claims, and policies: take them only from the brief, the repo, or the product's own docs (feature and tool names, commands, integrations, platforms, pages, fees, timings, guarantees).",
+            do: "Sort what the brief does not say into three kinds:\n  - Design assumptions (low-risk visual or structural choices such as a merchant category icon or grouping by date): decide them from the context.\n  - Unconfirmed capabilities (an action or feature the category usually has, such as sharing a receipt): convention is not proof, so ask when it materially changes the flow or scope; otherwise you may propose it, listed as unconfirmed, never as a requirement.\n  - Facts, claims, and policies: take them only from the brief, the repo, or the product's own docs (feature and tool names, commands, integrations, platforms, pages, fees, timings, guarantees).",
             dont: "Invent business rules, policies, guarantees, metrics, user data, permissions, pricing, requirements, or API behavior, or name a tool, command, integration, platform, or page the product does not have. Do not present an unconfirmed capability as a confirmed one.",
             notWhen: "This rule is not a reason to drop content the brief implies or to leave a screen looking unfinished: sample content is RX-AS-03, design assumptions are yours to make.",
             why: "Invented facts turn into promises and bugs that someone has to unwind; a screen trimmed to the brief's literal words reads unfinished and hides what still needs confirming.",
@@ -100,7 +100,7 @@ export const RULES = [
             num: 5,
             title: "The product's market first",
             level: "required",
-            do: "Start from how users in the product's own market pay, sign in, write addresses, and read money and dates; check a pattern from another market before reusing it. Take the market from the brief or the codebase, and ask when it is unclear. When the brief does not name payment methods (or another market-standard capability), show the market's standard set as unconfirmed capabilities, labeled as proposed in Assumptions, rather than leaving them out: a market's table stakes are not \"for later\" (RX-AS-06). Ask when the set would change the flow.",
+            do: "Start from how users in the product's own market pay, sign in, write addresses, and read money and dates; check a pattern from another market before reusing it.\n  - Take the market from the brief or the codebase, and ask when it is unclear.\n  - When the brief does not name payment methods (or another market-standard capability), show the market's standard set as unconfirmed capabilities, labeled as proposed in Assumptions, rather than leaving them out: a market's table stakes are not \"for later\" (RX-AS-06). Ask when the set would change the flow.",
             dont: "Import one market's checkout, currency, language, or tax rules into a product built for another market.",
             why: "Payment, address, and trust habits differ by market (local payment rails, address formats, messaging channels).",
             basis: "ryux taxonomy of local patterns",
@@ -331,7 +331,7 @@ export const RULES = [
             num: 13,
             title: "Each transition means one thing",
             level: "required",
-            do: "Choose how a screen arrives by what it means, and keep that meaning across the product: push to go one level deeper (back returns), replace to move to a new stage (back does not return to the old one), a modal for a self-contained task the user finishes or cancels, a sheet for a short interruption that keeps the screen behind it in view. Follow the platform's back gesture and button.",
+            do: "Choose how a screen arrives by what it means, and keep that meaning across the product:\n  - push to go one level deeper (back returns)\n  - replace to move to a new stage (back does not return to the old one)\n  - a modal for a self-contained task the user finishes or cancels\n  - a sheet for a short interruption that keeps the screen behind it in view\n  - Follow the platform's back gesture and button.",
             dont: "Open the same kind of screen as a push in one place and a modal in another, push a step the user can never usefully go back to, or put a long multi-step task in a sheet.",
             why: "People predict where back goes from how a screen arrived; a mixed model makes every exit a guess.",
             basis: `Apple HIG and Material navigation; pattern also in ${AP}, navigation semantics; written for RYUX`,
@@ -588,7 +588,7 @@ export const RULES = [
             title: "One name per thing",
             level: "required",
             gate: "lock",
-            do: "Use one term for each concept across screens, buttons, and messages. Use one label for each intent too: the same action is \"Start\" everywhere, not \"Start\" here and \"Let's start\" there. Write product and brand names exactly as the brief or brand guide gives them, including the wordmark; when an older design in the file disagrees with the brief, follow the brief and say so.",
+            do: "Use one term for each concept across screens, buttons, and messages.\n  - Use one label for each intent too: the same action is \"Start\" everywhere, not \"Start\" here and \"Let's start\" there.\n  - Write product and brand names exactly as the brief or brand guide gives them, including the wordmark; when an older design in the file disagrees with the brief, follow the brief and say so.",
             dont: "Call the same thing \"pesanan\", \"order\", and \"transaksi\" on different screens, or restyle a brand name (RYUX as \"ryux\") because an older frame did.",
             why: "Changing terms make users wonder whether it is a different thing; a misspelled brand name looks careless or fake.",
             basis: `Nielsen heuristic 4 (1994); ${RUN}: pen.dev hero wordmark`,
@@ -625,7 +625,7 @@ export const RULES = [
             tradeoff: "emphasizing one thing de-emphasizes the rest",
             level: "required",
             gate: "lock",
-            do: "Make the primary action and the key information the most prominent things in each area, with one clear focal point. Place each control next to the data it changes (a hide-balance toggle beside the balance it hides, not in the header), and make the primary action read as an action, not a place: its own button with an action label. It may sit in the center of a bottom bar when it is clearly different from the tabs (its own shape, color, and size, with room around it), but it is never styled as one of the tabs and never crammed between them. Use one display size per screen, for its single most important number or heading.",
+            do: "Make the primary action and the key information the most prominent things in each area, with one clear focal point.\n  - Place each control next to the data it changes (a hide-balance toggle beside the balance it hides, not in the header).\n  - Make the primary action read as an action, not a place: its own button with an action label. It may sit in the center of a bottom bar when it is clearly different from the tabs (its own shape, color, and size, with room around it), but it is never styled as one of the tabs and never crammed between them.\n  - Use one display size per screen, for its single most important number or heading.",
             dont: "Give everything equal weight, let decoration outrank content, park a control far from what it acts on, or make the main action look like one more tab.",
             why: "Hierarchy is how users know what to read and do first; a control beside its data shows what it changes, and an action that looks like a tab reads as a place, not a task.",
             basis: "NNGroup visual hierarchy; Gestalt proximity; Fitts's law (Fitts 1954) for the primary action's size and reach; ryux four-problems blind rating, rater 1 (product designer), 2026-10-16: a hide toggle far from the balance and a CTA crowding the bottom nav were reasons not to ship; explore-judge blind rating 2026-10-18: the same rater shipped a screen with a distinct centered pay button in the bottom bar",
@@ -638,7 +638,7 @@ export const RULES = [
             tradeoff: "a scale limits choices; occasional exceptions need a written reason",
             level: "preferred",
             gate: "lock",
-            do: "Use the project's spacing and type scale, or define one (for example multiples of 4 or 8) and align elements to a shared grid. Keep a screen's main content to two or three text sizes, the most important the largest, and count them on the render (RX-AS-10). State the shape lock in one sentence, a radius per component role (\"action buttons pill, cards 16, inputs 12, sheets 28\"), and keep emphasis inside the type family (weight or size), not a second face dropped into one word.",
+            do: "Use the project's spacing and type scale, or define one (for example multiples of 4 or 8), and align elements to a shared grid.\n  - Keep a screen's main content to two or three text sizes, the most important the largest, and count them on the render (RX-AS-10).\n  - State the shape lock in one sentence, a radius per component role (\"action buttons pill, cards 16, inputs 12, sheets 28\").\n  - Keep emphasis inside the type family (weight or size), not a second face dropped into one word.",
             dont: "Pick spacing and sizes one element at a time.",
             why: "A scale produces rhythm and makes hierarchy legible.",
             basis: `Material Design 8dp grid; NNGroup principles of visual design (scale: two or three sizes); shape lock and in-family emphasis: pattern also in ${AP}; written for RYUX`,
@@ -652,7 +652,7 @@ export const RULES = [
             tradeoff: "fewer colors means relying on type and space for emphasis",
             level: "preferred",
             gate: "lock",
-            do: "Use a small set of colors with defined roles: surface, text, accent for the primary action, and status colors. Pick one grey family, warm or cool, for surfaces, borders, and secondary text. Elements that behave the same look the same, and elements that behave differently look different: a destructive action has its own color role, not the primary accent. Lower importance with size, weight, or position, never by lowering text contrast.",
+            do: "Use a small set of colors with defined roles: surface, text, accent for the primary action, and status colors.\n  - Pick one grey family, warm or cool, for surfaces, borders, and secondary text.\n  - Elements that behave the same look the same, and elements that behave differently look different: a destructive action has its own color role, not the primary accent.\n  - Lower importance with size, weight, or position, never by lowering text contrast.",
             dont: "Introduce new colors per component, or use the accent for decoration.",
             why: "When color has a role, the accent and status colors mean something.",
             basis: `ryux visual principle; NNGroup principles of visual design (contrast signals a different function; similarity); isolation effect (von Restorff 1933): the one item that differs is the one remembered, so the accent marks only the primary action; one grey family: pattern also in ${AP}; written for RYUX`,
@@ -702,7 +702,7 @@ export const RULES = [
             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. 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.",
+            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",
@@ -715,7 +715,7 @@ export const RULES = [
             title: "Motion earns its level",
             level: "contextual",
             when: "the design adds motion or transitions",
-            do: "Classify each motion: L1 state feedback, L2 component transition, L3 page transition, L4 storytelling, L5 decorative. The higher the level, the stronger the reason it needs. Then weigh how often people see it: a surface opened many times a day (command palette, shortcut, core navigation, list selection) appears and closes without movement, at most a fade too short to notice; standard transitions belong to occasional surfaces (modal, drawer, toast), and expression to rare or first-time moments. Take timing and easing from one motion personality, define them once as motion tokens, animate transform and opacity rather than layout properties, and honor reduced motion (RX-A11Y-08). Anything that opens and closes (menu, popover, dialog, drawer) uses transitions that can reverse halfway, so a close or reopen mid-animation turns back from where it is, and it closes no slower than it opened.",
+            do: "Classify each motion: L1 state feedback, L2 component transition, L3 page transition, L4 storytelling, L5 decorative; the higher the level, the stronger the reason it needs.\n  - Weigh how often people see it: a surface opened many times a day (command palette, shortcut, core navigation, list selection) appears and closes without movement, at most a fade too short to notice; standard transitions belong to occasional surfaces (modal, drawer, toast), and expression to rare or first-time moments.\n  - Take timing and easing from one motion personality, define them once as motion tokens, animate transform and opacity rather than layout properties, and honor reduced motion (RX-A11Y-08).\n  - Anything that opens and closes (menu, popover, dialog, drawer) uses transitions that can reverse halfway, so a close or reopen mid-animation turns back from where it is, and it closes no slower than it opened.",
             dont: "Animate everything, give a surface people open many times a day an entrance they must sit through, play an open-only keyframe animation on something people can close or reopen at any moment, use one generic duration and easing (transition: all 0.3s) everywhere, let decorative motion delay content or input, or move data the user is reading (a balance, an amount, a table value) for effect.",
             why: "Motion directs attention; unearned motion steals it from the task and can make some people unwell.",
             basis: `NNGroup animation and usability guidance; WCAG 2.3.3 animation from interactions; frequency check: pattern also in ${EK} find-animation-opportunities; reversible open and close: pattern also in ${EK} animate; default timing, press state, and still data: pattern also in ${AP}; all written for RYUX`,
@@ -727,12 +727,12 @@ export const RULES = [
             num: 12,
             title: "A point of view on expressive surfaces",
             level: "contextual",
-            when: "the surface is expressive: a hero, landing page, onboarding, empty state, or brand moment, or the brief asks for a new look or more personality; on a new product's task UI, the brand layer only (see Not when)",
-            do: "Before designing, make two or three directions, each with a name, a concept taken from the product's own idea (for a tool about evidence: receipts, citations, marks of proof), and a signature element (type, composition, imagery, or motion). Render them as frames of the main state with the same content, different on at least two structural axes (information order, layout model, interaction model, type class, colour temperature), rate each against criteria taken from the brief, recommend one (RX-PR-09), and let the user choose; then make the rest of the design serve the chosen signature and put its concept in the Visual Brief. When the brief names reference products, read each one before it shapes the direction: the principle you borrow, what stays theirs (colours, mascot, signature features), and where you use it.",
-            dont: "Show directions that differ only in colour or copy, choose for the user without showing them, or let the signature be the category's default (for developer tools a terminal or agent-session panel; for SaaS a dashboard screenshot; copy on the left and product on the right), or relabel that default as a concept. A product screen can support the signature, not be it. Turn a named reference into adjectives (\"calm, white, soft\") or copy what belongs to its brand.",
+            when: "the surface is expressive: a hero, landing page, onboarding, empty state, or brand moment, or the brief asks for a new look or more personality; on a new product's task UI, the brand layer only (see Do)",
+            do: "Run Explore (capabilities/design.md, stage 3) with alternatives that each carry a name, a concept taken from the product's own idea (for a tool about evidence: receipts, citations, marks of proof), and a signature element (type, composition, imagery, or motion); then make the rest of the design serve the chosen signature and put its concept in the Visual Brief.\n  - On task UI: the alternatives are structure hypotheses and the conventions that must hold stay fixed. A new product's brand layer must carry one signature from its own domain (a mark, the type voice, a colour temperature, or one brand moment in the flow), never a layout change and never decoration without a job (RX-AS-05). Record it in the Delivery Gate UI line.\n  - When the brief names reference products, read each one before it shapes the alternatives: the principle you borrow, what stays theirs (colours, mascot, signature features), and where you use it.",
+            dont: "Show alternatives that differ only in colour or copy, choose for the user without showing them, or let the signature be the category's default (for developer tools a terminal or agent-session panel; for SaaS a dashboard screenshot; copy on the left and product on the right), or relabel that default as a concept. A product screen can support the signature, not be it. Turn a named reference into adjectives (\"calm, white, soft\") or copy what belongs to its brand.",
             why: "Users remember a product by its idea; a correct but generic surface is forgotten and could belong to any competitor.",
             basis: "brand and art direction practice; RX-UI-05 layout from content; rendered variants on named axes, compared side by side, chosen by the user: pattern also in emilkowalski/skills (MIT) prototype; written for RYUX",
-            notWhen: "task UI such as forms, tables, settings, and checkout, where restraint and convention win: the alternatives come from Explore (capabilities/design.md, step 3) as structure hypotheses, and the conventions that must hold stay fixed. A new product's brand layer must carry one signature from the product's own domain (a mark, the type voice, a colour temperature, or one brand moment in the flow), never a layout change and never decoration without a job (RX-AS-05). Record it in the Delivery Gate UI line",
+            notWhen: "an existing product whose brand system already sets the brand layer, or a small change inside a fixed design system; follow it",
             tradeoff: "a strong idea takes a decision someone may disagree with; keep it honest and on brand",
             check: "the swap test (RX-AS-09); review",
         },
@@ -754,7 +754,7 @@ export const RULES = [
             title: "Type that is set, not only sized",
             level: "preferred",
             gate: "lock",
-            do: "Keep body paragraphs at 45 to 75 characters per line, checked in the render; take line-height from size (about 1.5 for body, 1.2 to 1.3 for headings, about 1.1 for display); open small uppercase labels slightly (about 0.05em) and tighten large display text slightly; use tabular figures for numbers that are compared or that change (amounts, tables, timers); use at most two families and three weights; balance headings so none ends on one stranded word.",
+            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",
@@ -803,7 +803,7 @@ export const RULES = [
             title: "Tokens over one-off values",
             level: "preferred",
             gate: "lock",
-            do: "Use tokens or variables for color, spacing, radius, elevation, and type. First look for the ones that exist (DESIGN.md, a tokens or theme file in the repo, the design file's variables and components, a linked library) and use them. When the project has none, define them before the first frame: color roles, a spacing scale, a radius scale, and a type scale (sizes, and font families). Name color tokens by role (surface, text, accent, status), not by value, so a second theme is a swap of values, not a rename. In a design tool, create them as the tool's variables and reference them in every value, and make anything that repeats (a row, a button, a bar) a component. After rendering, count the values that are still literal, by kind, and turn each into a token or name why it is an exception.",
+            do: "Use tokens or variables for color, spacing, radius, elevation, and type.\n  - First look for the ones that exist (DESIGN.md, a tokens or theme file in the repo, the design file's variables and components, a linked library) and use them.\n  - When the project has none, define them before the first frame: color roles, a spacing scale, a radius scale, and a type scale (sizes and font families).\n  - Name color tokens by role (surface, text, accent, status), not by value, so a second theme is a swap of values, not a rename.\n  - In a design tool, create them as the tool's variables, reference them in every value, and make anything that repeats (a row, a button, a bar) a component.\n  - After rendering, count the values that are still literal, by kind, and turn each into a token or name why it is an exception.",
             dont: "Hard-code one-off values for things the system already defines, or define tokens for color only and leave spacing, radius, and type size literal.",
             why: "Tokens keep changes consistent and reviewable; values that are not tokens drift from frame to frame and state to state.",
             basis: "W3C Design Tokens Community Group; ryux four-problems baseline 2026-10-16: in all 12 runs, with or without RYUX, spacing, radius, and font size were 100% literal",
@@ -1060,7 +1060,7 @@ export const RULES = [
             num: 14,
             title: "Test logic and critical flows",
             level: "required",
-            do: "Write unit tests for every new or changed pure function (calculations, formatting, validation, state transitions), including edge cases such as zero, empty, maximum, and invalid input, and integration tests for critical flows (checkout, payment, form submit, sign-in) covering the success and failure paths. Use the repo's test runner and conventions; with none, propose one as an assumption and ask before adding the dependency. Run the tests.",
+            do: "Write the tests, then run them:\n  - unit tests for every new or changed pure function (calculations, formatting, validation, state transitions), including edge cases such as zero, empty, maximum, and invalid input\n  - integration tests for critical flows (checkout, payment, form submit, sign-in), covering the success and failure paths\n  - the repo's test runner and conventions; with none, propose one as an assumption and ask before adding the dependency",
             dont: "Ship changed logic without tests, write snapshot-only tests or tests that mock the code under test, or claim tested without running the tests.",
             why: "Tests catch the regressions review misses, before users find them in production.",
             basis: "Testing practice; owner review 2026-10-06",
@@ -1082,7 +1082,7 @@ export const RULES = [
             num: 1,
             title: "Render, inspect, fix, render again",
             level: "required",
-            do: "Render the result at the target viewport (browser, screenshot, or design-tool export), inspect the main state, one empty or error state, and the smallest supported width, look for the defects source code hides (misaligned edges, type or spacing off the scale, density wrong for the task, overflow and clipping, a component that looks different from its siblings, a control that does nothing), rank issues by impact, fix from the top, and render again; name the widths and states you inspected, and if no render tool is available, say so in the report. Whether the design itself is right or intentional is Critique's call; QA reports what it can verify.",
+            do: "Render the result at the target viewport (browser, screenshot, or design-tool export).\n  - Inspect the main state, one empty or error state, and the smallest supported width.\n  - Look for the defects source code hides: misaligned edges, type or spacing off the scale, density wrong for the task, overflow and clipping, a component that looks different from its siblings, a control that does nothing.\n  - Rank issues by impact, fix from the top, and render again. Name the widths and states you inspected; if no render tool is available, say so in the report.\n  - Whether the design itself is right or intentional is Critique's call; QA reports what it can verify.",
             dont: "Claim visual quality for a layout you have only seen as code, or fix by guesswork without checking the result.",
             why: "Overlaps and clipping are invisible in source and obvious on screen; the loop turns a draft into a reviewed result.",
             basis: `${RUN}: two runs shipped overlaps they never saw`,
@@ -1173,7 +1173,7 @@ export const RULES = [
             num: 5,
             title: "Decoration passes a purpose gate",
             level: "required",
-            do: "For each potentially decorative pattern, answer three questions: purpose (what does it do?), contribution (what does it add to understanding, interaction, or the product's character?), and necessity (would something simpler do the same?). Keep it only when all three have a real answer. Three feature cards pass when the features are equal and compared; when one matters more, give it more weight instead.",
+            do: "For each potentially decorative pattern, answer three questions, and keep it only when all three have a real answer:\n  - purpose: what does it do?\n  - contribution: what does it add to understanding, interaction, or the product's character?\n  - necessity: would something simpler do the same?\n  - Three feature cards pass when the features are equal and compared; when one matters more, give it more weight instead.",
             dont: "Keep cards, gradients, badges, shadows, or animation that have no reason, or accept \"it looks more interesting\" as one.",
             why: "Unjustified decoration is what makes AI-generated UI look the same.",
             basis: "ryux anti-slop principle",
@@ -1217,12 +1217,12 @@ export const RULES = [
             num: 9,
             title: "Clean is not the same as designed",
             level: "contextual",
-            when: "the surface is expressive: a hero, landing page, onboarding, empty state, or brand moment, or the brief asks for a new look or more personality; on a new product's task UI, the brand layer only (see Not when)",
-            do: "Run the swap test honestly: replace the name and logo with a competitor's in the same category. If the layout, the visual, and the headline would still work for them, the surface has no point of view yet; give it one (RX-UI-12). Report the answer in the Delivery Gate.",
+            when: "the surface is expressive: a hero, landing page, onboarding, empty state, or brand moment, or the brief asks for a new look or more personality; on a new product's task UI, the brand layer only (see Do)",
+            do: "Run the swap test honestly: replace the name and logo with a competitor's in the same category. If the layout, the visual, and the headline would still work for them, the surface has no point of view yet; give it one (RX-UI-12). Report the answer in the Delivery Gate.\n  - On task UI: keep the structure familiar and run the test on the brand layer only (palette, type, surfaces, iconography, map styling). On a new product, \"only the logo would change\" is a FAIL.",
             dont: "Treat a tidy, generic layout as done because it passes every other gate; generic restraint is slop too.",
             why: "Removing slop is the floor, not the ceiling; interchangeable design makes the product forgettable.",
             basis: "ryux delivery principle; Critique Design Read: specificity",
-            notWhen: "task UI, where familiarity is the point: keep the structure familiar, but run the swap test on the brand layer (palette, type, surfaces, iconography, map styling) and report the answer. On a new product, \"only the logo would change\" is a FAIL (RX-UI-12)",
+            notWhen: "an existing product whose brand system already defines the surface; follow it",
             tradeoff: "takes a design decision, not only removals",
             check: "swap test; review",
         },
@@ -1231,7 +1231,7 @@ export const RULES = [
             title: "Count before handoff",
             level: "required",
             gate: "lock",
-            do: "Before handing off, count on the render or in the design file's variables, and report the counts: accent hues 1 (status colors, and secondary colors the brand defines, are named and excluded); grey families 1; corner radii only from the scale, matching the shape lock; display sizes per screen 1; text sizes in a screen's main content 3 at most; icon sets 1, in the chosen icon style; emoji in interface chrome 0; invented logos or app icons 0 (RX-AS-11); gradients without a brand reason 0; labels for the same intent 1. A count over its limit fails unless the brief or DESIGN.md gives the reason.",
+            do: "Before handing off, count on the render or in the design file's variables, and report the counts against these limits:\n  - accent hues 1 (status colors, and secondary colors the brand defines, are named and excluded)\n  - grey families 1\n  - corner radii only from the scale, matching the shape lock\n  - display sizes per screen 1; text sizes in a screen's main content 3 at most\n  - icon sets 1, in the chosen icon style\n  - emoji in interface chrome 0; invented logos or app icons 0 (RX-AS-11); gradients without a brand reason 0\n  - labels for the same intent 1\n  - A count over its limit fails unless the brief or DESIGN.md gives the reason.",
             dont: "Judge consistency by eye only, or hand off a screen with five accent hues, mixed icon sets, or two labels for one action because it looks fine.",
             why: "Counts are harder to talk past than impressions; a design that passed a by-eye review still shipped five hues and the wrong tab icons.",
             basis: `isolation effect (von Restorff 1933): several accents cancel each other out; pattern also in ${AP}, anti-slop counts; written for RYUX; owner review 2026-10-17: withryux.pen passed RYUX with 5+ hues and wrong tab icons`,
@@ -1243,7 +1243,7 @@ export const RULES = [
             level: "required",
             gate: "hard",
             when: "the design has a logo, wordmark, app icon, or favicon",
-            do: "Use the brand's own file wherever the product's mark appears: look in the repo (public/, assets/, the app icon and favicon), DESIGN.md, the design file's components, and what the user attached, and name the file you used. With no file, set the product name in plain text in the brand's type, or leave a visible [LOGO] placeholder, and list the mark as missing in the handoff.",
+            do: "Use the brand's own file wherever the product's mark appears.\n  - Look in the repo (public/, assets/, the app icon and favicon), DESIGN.md, the design file's components, and what the user attached, and name the file you used.\n  - With no file, set the product name in plain text in the brand's type, or leave a visible [LOGO] placeholder, and list the mark as missing in the handoff.",
             dont: "Stand in for the mark with initials in a circle, an emoji, a generic shape, an invented SVG, a letter cut into a tile, or the name typeset to look like a logo; generate a favicon or app icon the user did not ask for; or redraw the brand's mark instead of using its file. Designing a mark is its own task, done only when the user asks for it.",
             why: "An invented mark looks finished and is the first thing a team has to throw away; it also passes for a decision nobody made.",
             basis: `pattern also in superdesign-skill (MIT), logo invariant; RX-UI-13 asset provenance; ryux owner review 2026-10-18 (the logo and favicon are the owner's to make); written for RYUX`,

package/dist/intelligence/critique.js

@@ -11,7 +11,7 @@ decisions; it is not Analyze (what exists) or QA (does the build match its desig
 orchestrator, not a pile of rules: it analyzes the design, reasons with the RYUX knowledge modules,
 pulls evidence from RYUX Knowledge, and reports findings someone can act on. In the core workflow
 (SKILL.md) it runs Understand and the critique half of Build and critique; a finding that
-contradicts a chosen design is a reason to Reconsider it (capabilities/design.md, step 4).
+contradicts a chosen design is a reason to Reconsider it (capabilities/design.md, stage 4).
 
 \`\`\`
 Critique

package/dist/intelligence/guides.js

@@ -28,18 +28,17 @@ design-system, accessibility, responsive, frontend, and anti-slop. Evidence come
 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 the capabilities apart, never one generic "design" answer: Analyze says what exists, Design what
-to do and why, Critique whether a decision is right, QA whether the build matches the intent.`;
-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 before deciding; separate observed
-facts from assumptions; prefer evidence over aesthetic preference; do not invent requirements;
-explain meaningful decisions with their trade-off; validate before claiming.`;
+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
+taste; invent no requirements; give each meaningful decision its trade-off; validate before claiming.`;
 export const CORE_WORKFLOW = `One workflow, six stages; each entry point runs the stages it needs.
 
 1. **Understand**: who, what task, which product and market (RX-PR-01). Read the RYUX project
    context in DESIGN.md, then the product docs (Product docs paths, else PRD.md, docs/prd*,
    docs/product*, README), and name what you read. Separate facts, assumptions, and unknowns
-   (RX-PR-02); ask and record direction as in capabilities/design.md, step 1. DESIGN.md is
+   (RX-PR-02); ask and record direction as in capabilities/design.md, stage 1. DESIGN.md is
    direction, not evidence. Read the entry point's file and only the modules the task table lists.
 2. **Frame**: the user's task, the flow, what must be seen first, the primary action, and three to
    five success criteria from the brief, written before any alternative exists.
@@ -64,7 +63,7 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
 
 1. **Understand.** Who, what task, which product and market, and the design intent
    (knowledge/product.md). Take it from the prompt, then DESIGN.md, then knowledge and evidence.
-   Read the product docs first (the router, step 1). Ask only when a missing answer materially
+   Read the product docs first (the router, stage 1). Ask only when a missing answer materially
    affects the user flow, what the product can do, or whether the content is correct, those
    questions alone, most consequential first, at most three, in one message, before designing.
    A product rule that changes which states or actions the screen has (refunds, fees, what happens
@@ -118,52 +117,57 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
 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
-   into the full design (states, widths, Visual Direction, RX-UI-10), write the Design Direction
+   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.
    **Modes after the choice.** Refine improves the chosen alternative without losing its hypothesis.
    Reconsider returns to an unchosen alternative when a later finding or new evidence contradicts the
    choice: name the finding, show the alternative again, and let the user decide.
-5. **Design in the tool, then critique it.** Use the Figma MCP or the pen.dev MCP. System first: look for the design
-   system that exists (DESIGN.md, a tokens or theme file in the repo, the design file's variables and
+5. **Design in the tool, then critique it.** Use the Figma MCP or the pen.dev MCP. System first:
+   look for the design system that exists (DESIGN.md, a tokens or theme file in the repo, the design file's variables and
    components, a linked library) and build from it. Create only what is missing: variables for color
    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).
    **Render and inspect.** Screenshot what you made, check it against the direction and the rules,
-   fix, and render again (capabilities/qa.md). Count the values still literal (color, spacing,
-   radius, type size) and turn each into a variable or name the exception, then run the counts of
-   RX-AS-10 (accent hues, grey families, radii, display and text sizes, icon sets, emoji, invented marks, gradients, labels
-   per intent) and report them in the gate. Run the four hierarchy
-   checks from Critique (control beside its data, primary action that reads as an action, not a tab, no fact
-   twice, grouped by what the user checks together), fix what fails, render again, and check each fix.
-   Weight ranking: list the screen's blocks in order of visual weight (size × contrast × surface) and
-   compare it with the priority order from Frame (step 2). If two blocks of different priority render with the
-   same heading style and container, change one. On a checkout or order screen, the choice that sets
-   the price and the total rank first and second. A width check is a test, not a deliverable: list
-   what broke at each width (wrap, truncation, overflow), fix it or record why it is acceptable, and
-   render again; RESPONSIVE PASS names the findings and their fixes. List where
-   the render differs from the Design Direction (hierarchy, states, widths) and fix or record each one. Check the result against the Liveliness you set, and
-   put each prominent or decorative element through the purpose gate (RX-AS-05: purpose,
-   contribution, necessity); on calm task UI, deliberate restraint is a valid answer. Then judge the main state as a
-   reviewer would, not as a checklist: rate Clarity, Hierarchy, and Specificity from the Design Read
-   (capabilities/critique.md), plus Craft (type steps, spacing rhythm, alignment, detail), Strong,
-   Adequate, or Weak with one reason each, and fix anything Weak before the gate. Reference check:
-   put the main state beside two or three reference apps (named in the brief, from the Reference Read,
-   or comparable screens from the ryux MCP) and write, per reference, what holds up and what reads
-   weaker or more generic in yours (surface, hierarchy, brand layer, assets); no score. Fix what reads
-   weaker for the task, and say so when no reference was available. Generated images and illustrations arrive
-   asynchronously: wait until each one has landed and render again before exporting or closing the
-   gate. Never finish with an asset still pending.
-6. **Verify and deliver.** Check every product fact on the canvas (tool and command names,
-   integrations, platforms, pages, numbers) against the brief or the repo (RX-PR-02). Canvas copy is
-   for the team, not for RYUX: annotations, state captions, and labels on the canvas use plain
-   language ("Shown while prices load; button disabled"); rule IDs, gate results, and Decision
-   Receipts go in the Design Direction or the final message, never in frames meant for review or
-   handoff. A handoff frame annotates, in plain language, the interaction behaviour, the truncation
-   rule for each text that can overflow, and each component's code name. Then close with the Delivery Gate, saying what was not designed, such as other widths or states. If you
-   wrote DESIGN.md, say so in the final message: which file and which fields.
+   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).
+   - Counts: run the RX-AS-10 counts and report them in the gate.
+   - Hierarchy: run the four hierarchy checks from Critique (control beside its data, a primary
+     action that reads as an action, not a tab, no fact twice, grouped by what the user checks
+     together); fix what fails and check each fix.
+   - Weight ranking: list the screen's blocks in order of visual weight (size × contrast × surface)
+     and compare it with the priority order from Frame (stage 2). If two blocks of different
+     priority share a heading style and container, change one. On a checkout or order screen, the
+     choice that sets the price and the total rank first and second.
+   - Widths: a width check is a test, not a deliverable. List what broke at each width (wrap,
+     truncation, overflow), fix it or record why it is acceptable, and render again; RESPONSIVE
+     PASS names the findings and their fixes.
+   - Direction: list where the render differs from the Design Direction (hierarchy, states,
+     widths) and fix or record each one, and check the result against the Liveliness you set.
+   - Purpose: put each prominent or decorative element through the purpose gate (RX-AS-05); on
+     calm task UI, deliberate restraint is a valid answer.
+   - Reviewer's read: rate Clarity, Hierarchy, and Specificity from the Design Read
+     (capabilities/critique.md), plus Craft (type steps, spacing rhythm, alignment, detail), Strong,
+     Adequate, or Weak with one reason each; fix anything Weak before the gate.
+   - Reference check: put the main state beside two or three reference apps (named in the brief,
+     from the Reference Read, or comparable screens from the ryux MCP) and write, per reference,
+     what holds up and what reads weaker or more generic in yours (surface, hierarchy, brand layer,
+     assets); no score. Fix what reads weaker for the task; say so when no reference was available.
+   - Assets: generated images and illustrations arrive asynchronously. Wait until each one has
+     landed and render again before exporting or closing the gate; never finish with one pending.
+6. **Verify and deliver.**
+   - Facts: check every product fact on the canvas (tool and command names, integrations,
+     platforms, pages, numbers) against the brief or the repo (RX-PR-02).
+   - Canvas copy is for the team, not for RYUX: annotations, state captions, and labels use plain
+     language ("Shown while prices load; button disabled"). Rule IDs, gate results, and Decision
+     Receipts go in the Design Direction or the final message, never in frames meant for review or
+     handoff.
+   - Handoff: a handoff frame annotates, in plain language, the interaction behaviour, the
+     truncation rule for each text that can overflow, and each component's code name.
+   - Close with the Delivery Gate, saying what was not designed, such as other widths or states. If
+     you wrote DESIGN.md, say so in the final message: which file and which fields.
 
 ${UNTRUSTED_CONTENT}
 
@@ -249,7 +253,7 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
    (knowledge/frontend.md, knowledge/design-system.md). Reuse before creating.
 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, steps 2-4) instead of inventing one in code.
+   first (capabilities/design.md, stages 2-4) instead of inventing one in code.
 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
@@ -258,8 +262,9 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
    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
    change goes back to Design as a new Decision Receipt, and when the code shows the chosen design
-   cannot work (data, platform, performance), say so and send it back to Reconsider. Mark every assumption in the code. Give
-   each piece of logic one home in the repo's existing layers, never a copy (RX-FE-13).
+   cannot work (data, platform, performance), say so and send it back to Reconsider. Mark every
+   assumption in the code. Give each piece of logic one home in the repo's existing layers, never a
+   copy (RX-FE-13).
 5. **Test what can break.** Unit tests for new or changed pure logic, edge cases included;
    integration tests for critical flows such as checkout, payment, and form submit. Use the
    repo's runner; with none, propose one and ask before adding it (RX-FE-14).
@@ -300,7 +305,8 @@ Optional sources (the ryux MCP, Figma, a browser, screenshots, other reference l
 evidence when connected; none is required.`;
 export const CORE_HONESTY = `Report what was checked, how, and what was not available. Do not claim "pixel perfect",
 "fully accessible", "production ready", "senior-level", or "UX optimized" without evidence. Say
-"Keyboard and focus checked by hand; no automated accessibility test was available" instead. Rule IDs and gate results belong in your report, never on the design itself.`;
+"Keyboard and focus checked by hand; no automated accessibility test was available" instead.
+Rule IDs and gate results belong in your report, never on the design itself.`;
 export const CORE_DECISION_RECORD = `For consequential choices (RX-PR-09) and deviations, write **Decision**, **Options** compared, **Evidence**,
 **Trade-off**, and **Choice**. Evidence is Strong (2+ comparable screen_ids), Thin (one, or another context),
 or None (no screen_id: a judgment call). With None on a consequential choice, show options or ask (RX-PR-10).`;
@@ -514,7 +520,7 @@ focal point, hierarchy, negative space, relation to the copy, and balance (RX-UI
 **Expressive surfaces** (hero, landing, onboarding, empty states, brand moments). Restraint keeps
 task UI usable; on expressive surfaces it is only the floor. Work concept, then signature, then
 system:
-1. **Concept**: write two or three directions first (name, concept, signature), then choose one. The idea
+1. **Concept**: explore two or three alternatives first (name, concept, signature; capabilities/design.md, stage 3), then choose one. The idea
    comes from the product itself, not from the category: a tool about evidence might use receipts,
    citations, and marks of proof; a calm finance app might use the ledger. The category default
    (a terminal panel for developer tools, a dashboard screenshot for SaaS) is never the signature.
@@ -677,7 +683,8 @@ Check the stated viewport and the smallest supported width. No horizontal page s
    in the repo's own runner. Run them before claiming the work is done.
 
 Does not cover: visual decisions (see ryux-ui) or component reuse decisions (see ryux-design-system).`,
-    "visual-qa": `As an entry point, Visual QA is the Verify and deliver stage of the core workflow (SKILL.md) for a build; Design and Build also use its loop in Build and critique. It asks one question: **did the implementation match the intended design?** Whether the
+    "visual-qa": `As an entry point, Visual QA is the Verify and deliver stage of the core workflow (SKILL.md)
+for a build; Design and Build also use its loop in Build and critique. It asks one question: **did the implementation match the intended design?** Whether the
 design itself is good is Critique's question (ryux-critique).
 
 **With a reference** (a Figma or pen.dev frame, DESIGN.md, or an approved screenshot):
@@ -722,7 +729,8 @@ widths) or NOT VERIFIED (why); motion read only from code is NOT VERIFIED.
 
 **Rank issues by impact**: blocks the task, misleads (wrong numbers, unclear action), adds friction,
 polish.`,
-    "anti-slop": `Anti-slop runs in Verify and deliver, after design, build, critique, and QA; it is the final quality gate, never the
+    "anti-slop": `Anti-slop runs in Verify and deliver, after design, build, critique, and QA; it is the final
+quality gate, never the
 starting point. Anti-slop is the floor, not the ceiling: a tidy, generic surface still fails on expressive
 surfaces (RX-AS-09), and the point of view comes from RX-UI-12. Anti-slop is not a list of banned
 styles. It has three parts.

package/package.json

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