@ryuxdsgn/design-intelligence 2.13.6 → 2.13.7

package/dist/intelligence/content.js

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

package/dist/intelligence/guides.js

@@ -85,7 +85,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    **What exists.** When there is a screen, product, or design system already, read its
    analysis or run Analyze first (capabilities/analyze.md). Existing screens, components, and any
    screenshot or reference provided are your examples: read them before choosing patterns, take
-   their principles, and never copy their facts. Understand before you design. When the task
+   their principles, and never copy their facts. A request to copy a screenshot as it is goes to
+   Build as a recreate (capabilities/build.md, step 2). Understand before you design. When the task
    redesigns or improves what exists, list what works and keep it; change only what has a named
    problem (RX-UX-10).
    **Modules.** Read the modules the task needs from the task table before deciding anything, for example ux,
@@ -130,7 +131,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    roles, spacing, radius, and type sizes and families before the first frame, and components for
    repeated elements (RX-DS-03). Building the system does not replace the states: design every
    state that matters (empty, loading, error, including content that fails to load) and every width
-   you claim, and source assets on purpose (RX-UI-13).
+   you claim, and source assets on purpose (RX-UI-13); illustration follows a written style and is
+   made as one set (RX-UI-17, RX-UI-18).
    **Render and inspect.** Screenshot what you made, check it against the direction and the rules,
    fix, and render again (capabilities/qa.md). Then, on the render:
    - Literal values: turn each into a variable or name the exception (RX-DS-03).
@@ -244,7 +246,7 @@ Dissent      evidence only one source holds, or the case for an option not chose
 Evidence names its count and never generalizes past it. "Evidence None, Confidence Low, Why:
 business priority was not provided" is a valid receipt; keep it visible instead of upgrading it.
 
-Visual, motion, and asset rules and tables live in knowledge/ui.md (RX-UI-07 to RX-UI-13); this
+Visual, motion, and asset rules and tables live in knowledge/ui.md (RX-UI-07 to RX-UI-19); this
 direction only records the choices made with them.`;
 export const BUILD_BODY = `# RYUX Build
 
@@ -259,10 +261,15 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
 2. **Find the design source**: the Design Direction, a Figma or pen.dev design, a DESIGN.md, or an
    approved mockup; it is the spec. If there is none, run Design's Frame, Explore, and Evaluate
    first (capabilities/design.md, stages 2-4) instead of inventing one in code.
+   A screenshot or another product's page is a reference, not the spec, unless the user asks to
+   recreate it ("recreate", "match this", "samakan"). Then match it, let QA compare at the same
+   viewport, and still leave out another product's brand, logo, and content (RX-AS-11). With no word
+   either way, design from its principles and write "reference, not recreate" in Assumptions.
 3. **Read the modules the task needs** from the task table: for example accessibility, responsive,
    and edge-cases for any UI, and forms and content for a form. When the build adds motion or
    transitions, read knowledge/ui.md (RX-UI-11) before writing any: how often the surface is seen
-   decides how much it moves.
+   decides how much it moves. When it adds illustration, read RX-UI-19: SVG coloured from tokens,
+   no text inside, alt text that says the meaning.
 4. **Implement faithfully.** Use semantic elements, existing components, and real data paths.
    Build must not invent business rules, prices, or limits; API behavior or response shapes; or
    data presented as real (RX-FE-02, RX-PR-02). It must not silently change a design decision: a
@@ -493,7 +500,7 @@ gates in ryux-anti-slop). It works in four layers.
 4. **Density**: compact for repeat work, roomier for first-time or high-stakes decisions.
 5. **Color**: roles first (surface, text, accent for the primary action, status); contrast checked.
 6. **Containers**: use a container only when it groups or separates something.
-7. **Icons**: next to labels, from one set, at consistent sizes.
+7. **Icons**: next to labels, from one set, at consistent sizes, one meaning each (RX-UI-20).
 
 **Justify values.** Every value comes from the scale and has a reason you can say in one line:
 "12px between these two fields because they belong together; 24px before the next group because it
@@ -617,6 +624,11 @@ Sources:        reference screen_ids or the analysis it came from
 A generated image is illustrative art; never present it as a real customer or a real product
 screen (RX-UI-07).
 
+**Illustration.** With no brand system to follow, write the style in five lines before the first
+drawing, plus a character system when it has people or a mascot, and record it as a Decision
+Receipt (RX-UI-17); make a set together and compare it side by side (RX-UI-18), and ship it as SVG
+coloured from tokens, with no text inside and alt text that says the meaning (RX-UI-19).
+
 Does not cover: component reuse and tokens (see ryux-design-system).`,
     "design-system": `Prioritize the existing system. Before creating anything:
 
@@ -708,6 +720,11 @@ Card radius | 16px                 | 8px            | half the radius | minor
 
 **Without a reference**, check the build against its own intent and the rules below.
 
+**Illustration** (when the build has any): it matches the written style (RX-UI-17), a set reads as one
+family side by side (RX-UI-18), it reads at its real displayed size including the smallest width, it
+works in every theme, and nothing the user needs exists only in the image (RX-UI-19). Without a
+render, report these as NOT VERIFIED.
+
 **Loop**: implement → render → compare → fix → render again.
 
 **Render with what is available**, in this order: the project's own preview or test setup;

package/package.json

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