@ryuxdsgn/design-intelligence 2.19.7 → 2.20.0

package/dist/intelligence/content.js

@@ -51,6 +51,7 @@ const RUN = "ryux run 2026-10-02";
 const AS = "anti-slop (MIT)";
 const EK = "emilkowalski/skills (MIT)";
 const AP = "appllama-app-design-skill (MIT)";
+const DS_LIBRARY = "Building or changing reusable components or variables in a design tool (Figma, pen.dev) or a component library, meant to be used by designers and in code.";
 export const RULES = [
     ...skill("product", [
         {
@@ -879,10 +880,10 @@ export const RULES = [
             level: "contextual",
             gate: "lock",
             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.\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.",
+            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 (menu, dropdown, tabs, list selection) gets a short transition that can be interrupted, about 150 to 250 ms of opacity with a small scale or a few pixels of movement from its trigger, and only a keyboard-opened command palette or shortcut appears at once; standard transitions belong to occasional surfaces (modal, drawer, toast), and expression to rare or first-time moments, where a completed payment or a first success may celebrate once without moving the amount.\n  - When a control changes what is shown (tabs, segmented control, filter), the content moves with it: the indicator slides by transform and the panels cross-fade with a few pixels of travel in the same direction, together.\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 longer than about 250 ms or one they must wait for, move a tab indicator while the panel content snaps, freeze it with no transition at all when a short one would show where it came from, repeat a celebration, 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`,
+            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}; short transitions on frequent surfaces, content that moves with its control, and one celebration on rare moments: ryux owner blind ratings 2026-10-18 (explore-judge Part C, motion-loosen round 1) and hero-finance follow-up; all written for RYUX`,
             notWhen: "L1 feedback on standard controls that follows the platform defaults",
             tradeoff: "fewer flourishes on marketing pages",
             check: "review; reduced-motion test",
@@ -895,7 +896,7 @@ export const RULES = [
             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. Carry the borrowed character at the strength the brief asks for: when it asks for a reference's feel (playful, chunky, gamified), the feel shows on every main screen, in type weight, shape, colour energy, and one brand moment, not only in a button detail. A reference's signature mechanics (a streak, a daily goal, a score) are unconfirmed capabilities: propose them, never show them as facts.",
             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; owner review of a no-skill vs RYUX run (2026-10-20): RYUX kept the reference's feel to one button detail",
+            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; fit first with craft as tie-break, pairwise with a runner-up: ryux owner blind ratings 2026-10-18 (judge round 1: weighting distinctiveness picked against the designer); written for RYUX; owner review of a no-skill vs RYUX run (2026-10-20): RYUX kept the reference's feel to one button detail",
             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",
@@ -1056,7 +1057,7 @@ export const RULES = [
             title: "The component sheet is a spec",
             level: "preferred",
             gate: "lock",
-            do: "Lay out each component as a labeled grid: one row per property, one column per state (default, hover on web, pressed, disabled, loading, error), each cell labeled with its variant name, and one line of usage under each component; no overlapping or clipped variants. Render and inspect the sheet like a screen.",
+            do: "Lay out each component as a labeled grid: one row per property, one column per state (default, hover on web, pressed, disabled, loading, error), each cell labeled with its variant name, and one line of usage under each component; no overlapping or clipped variants. Render and inspect the sheet like a screen.\n  - When the component ships to code, put its contract beside the grid: one row per property with its design-tool type, values, default, the code prop it maps to (or \"none: CSS state\"), and a note. Designers and developers read the same table.",
             dont: "Leave variants scattered, unlabeled, or cut off at the frame edge.",
             why: "Developers build from the component sheet; a variant they cannot find or read gets rebuilt or guessed.",
             basis: "ryux run: blind review of a delivery flow 2026-10-20; design-system practice; written for RYUX",
@@ -1064,6 +1065,74 @@ export const RULES = [
             tradeoff: "takes time to lay out; pays back at handoff",
             check: "render the sheet; every variant visible and labeled",
         },
+        {
+            num: 7,
+            title: "Property names are the code's props",
+            level: "contextual",
+            gate: "lock",
+            when: DS_LIBRARY,
+            do: "Name each component property and value the way the code names the prop: camelCase names (variant, size, hasLeadingIcon) and lowercase values (primary, secondary, sm, md). When the repo already has the component, take its prop names; otherwise agree them once in the contract (RX-DS-06) and use them on both sides.",
+            dont: "Name properties for one audience, such as Type=Primary Big in the design file and kind=\"main\" in code, or rename a value on one side only.",
+            why: "When the panel and the props use the same words, handoff needs no translation table and nobody guesses which variant is which.",
+            basis: "Design-system practice; Figma component properties and Code Connect (help.figma.com); written for RYUX",
+            check: "compare the property and value names in the design file with the contract and the code props",
+        },
+        {
+            num: 8,
+            title: "Each property has the type its job needs",
+            level: "contextual",
+            when: DS_LIBRARY,
+            do: "Use a variant property for a change in look or structure (variant, size); a boolean for a part that shows or hides (hasLeadingIcon); an instance swap for the icon or slot that fills it (leadingIcon); a text property for copy (label). Set a default for each, the one used most.",
+            dont: "Make an icon position or a label a variant, or add a variant per icon.",
+            why: "The right property type keeps the variant count small and the panel readable, and maps one to one to a prop, a boolean, a slot, or a string in code.",
+            basis: "Design-system practice; Figma component properties: variant, boolean, instance swap, text (help.figma.com); written for RYUX",
+            check: "review the property list against the contract",
+        },
+        {
+            num: 9,
+            title: "Variants stay few and valid",
+            level: "contextual",
+            when: DS_LIBRARY,
+            do: "Before building, multiply the values of every variant axis. Above about 48 variants, or when some combinations make no sense (a loading state on a link-style button), split the component, turn an axis into a boolean or instance swap, or leave the invalid combinations out and note them in the contract.",
+            dont: "Build every combination because the tool can, or add an axis for one case.",
+            why: "Each extra axis multiplies what designers scroll through and developers must support; invalid combinations get used.",
+            basis: "Design-system practice; ryux owner review 2026-10-25 (3 hierarchies × 3 sizes × 4 states is 36 before icons); written for RYUX",
+            tradeoff: "a split component is one more name to find",
+            check: "count the variants per component set; list the combinations left out and why",
+        },
+        {
+            num: 10,
+            title: "Interaction states are spec, data states are props",
+            level: "contextual",
+            when: DS_LIBRARY,
+            do: "Draw hover, pressed, and focus as variants so the look is specified, and mark them in the contract as CSS states with no prop. Make disabled, loading, selected, and error props, because the product sets them.",
+            dont: "Map state=hover to a prop, or leave loading and error as drawings with no prop behind them.",
+            why: "A hover prop has nothing to set it, and a loading state with no prop never ships.",
+            basis: "ryux owner review 2026-10-25 of a design-system proposal; W3C WAI-ARIA states; written for RYUX",
+            check: "every state in the contract is either a prop or marked CSS state",
+        },
+        {
+            num: 11,
+            title: "Components bind semantic variables",
+            level: "contextual",
+            when: DS_LIBRARY,
+            do: "Keep variables in two layers: primitives (blue/500, space/4) and semantic roles that point to them (text/accent, surface/raised, space/control-gap). Components bind only the semantic layer; themes and brands are modes of the semantic collection. Give code the same names as tokens.",
+            dont: "Bind a component to a primitive, or make a second theme by duplicating components.",
+            why: "With one semantic layer, a theme or rebrand changes values in one place and every component follows, in the design file and in code.",
+            basis: "W3C Design Tokens Community Group (aliases); Figma variables and modes (help.figma.com); extends RX-DS-03",
+            check: "count component values bound to a primitive or to no variable",
+        },
+        {
+            num: 12,
+            title: "Components resize like the code",
+            level: "contextual",
+            when: DS_LIBRARY,
+            do: "Build each component with auto layout, padding and gap bound to spacing variables, and a stated resize rule (hug the content, or fill the container). Check it with the longest real label, including Indonesian copy, which often runs longer than English, and at the smallest width it is used in.",
+            dont: "Position layers absolutely inside a component, or set a fixed width that clips a long label.",
+            why: "A component that does not resize the way the code does gets detached in the design file and rebuilt in code.",
+            basis: "Design-system practice; Figma auto layout (help.figma.com); RX-RD-01; written for RYUX",
+            check: "render each component with its longest label and at its smallest width",
+        },
     ]),
     ...skill("accessibility", [
         {
@@ -1291,10 +1360,10 @@ export const RULES = [
             num: 14,
             title: "Test logic and critical flows",
             level: "required",
-            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",
+            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\n  - while iterating, run the tests the change touches; run the whole suite once before handing off, with quiet output (a summary or dot reporter, failures in full)",
             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",
+            basis: "Testing practice; owner review 2026-10-06; ryux run: food-delivery round 2 (2026-10-27) ran the full suite 21 times in one build, about a quarter of its steps",
             check: "run the project's tests",
         },
         {
@@ -1325,10 +1394,10 @@ 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).\n  - Inspect the main state, one empty or error state, and the smallest supported width (RX-RD-01), plus the largest text size on native.\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.",
+            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 (RX-RD-01), plus the largest text size on native.\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  - Look at the states of one width together: tile their screenshots into one contact sheet and inspect that, open a single screenshot only to check a defect up close, and after a fix render again only what it touched.\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`,
+            basis: `${RUN}: two runs shipped overlaps they never saw; ryux run: food-delivery round 2 (2026-10-27) read 21 screenshots one at a time, and every read stays in the context for the rest of the build`,
             check: "screenshot",
         },
         {
@@ -1587,6 +1656,7 @@ export const QUALITY_LOCKS = [
     { item: "Color roles", rules: ["RX-UI-04"] },
     { item: "Terminology", rules: ["RX-CD-05"] },
     { item: "Components", rules: ["RX-DS-02"] },
+    { item: "Component property names", rules: ["RX-DS-07"] },
     { item: "Interaction patterns and states", rules: ["RX-DS-02"] },
     { item: "Responsive behavior", rules: ["RX-RD-06"] },
     { item: "Visual hierarchy", rules: ["RX-UI-01"] },

package/dist/intelligence/guides.js

@@ -73,7 +73,8 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    audience than this brief) sets no direction for this task: say so, and treat direction as unset.
    **Direction is the user's call:** when neither the prompt nor DESIGN.md sets the UI direction
    (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
+   counts toward the three) instead of choosing it yourself; on an expressive surface, ask in the
+   same question for one product or site whose look they like, as a taste anchor. **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.
    **Voice and tone** is not asked by default: when the field is blank, infer it from the product's
@@ -138,8 +139,15 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
      directing it.
    - 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, with the alternatives as
+   Weak with one reason each, fit first: the user's main task (can it be done fast, where the hand
+   is), what must be seen first, how much space the layout spends on what matters, and the
+   conventions that must hold. Fit decides. Craft (hierarchy at a glance, type and spacing,
+   distinctiveness by the swap test, RX-AS-09) only breaks a tie between alternatives equally strong
+   on fit; a more distinctive alternative never wins over one that is easier to use or wastes less
+   space. Compare in pairs ("A beats B on reach because …"), rate the evidence (RX-PR-10), recommend
+   one with a Decision Receipt, name the runner-up and what would make it win, and say "close call"
+   when it is one. When the user gave a reference or a taste anchor, the alternative closest to it
+   wins a tie. "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
@@ -157,6 +165,12 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    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); illustration follows a written style and is
    made as one set (RX-UI-17, RX-UI-18).
+   **Building a component library** (RX-DS-07 to RX-DS-12): write the contract first (RX-DS-06),
+   then variables (primitives, semantic roles, modes), then components. In Figma, building needs the
+   Figma MCP with \`use_figma\` (the remote server and a Full seat); without it, build in pen.dev or
+   deliver the contract and sheet as a spec and say what was not built. Work in a draft or a
+   duplicate file, build in small steps (one collection or one component set per call), bind every
+   value to a variable, and render the sheet after each component set.
    **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).
@@ -227,6 +241,10 @@ patterns fit the context, and how the result is evaluated.
    unless they agree to change it, and keep the context block's field lines as \`setup\` writes them. End with a
    short list of what changed and why.
 6. Close with a Delivery Gate scaled to a document: PRODUCT, UX, and CONTENT; the other areas N/A.
+7. **Hand off to the build.** The file now carries the decisions, so the build does not need this session's
+   history. When the session is already long (references read, images, several rounds), say so and suggest
+   building in a fresh session that starts from DESIGN.md: every later step rereads the whole history, which is
+   most of a long build's cost.
 
 \`\`\`
 # DESIGN.md
@@ -631,9 +649,16 @@ If not, the surface has no point of view yet. Stay honest while being bold: a st
 needs invented numbers, people, or logos.
 
 **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.
+Then ask how often someone will see it. The more often, the shorter and quieter it is, not absent:
+what people open many times a day (a menu, a dropdown, tabs, list selection) gets a short transition
+they can interrupt, about 150 to 250 ms of opacity with a small scale or a few pixels of movement
+from its trigger; only a command palette or shortcut opened from the keyboard appears at once.
+When a control changes what is shown (tabs, a segmented control, a filter), move the content with
+it, not only the control: the indicator slides by transform, the old panel fades out while the new
+one fades in and travels a few pixels in the same direction, together, in one easing. A tab whose
+indicator moves while the panel snaps feels unfinished.
+Expression is kept for occasional or first-time moments, and a rare moment such as a completed
+payment may celebrate once: brief, never repeated, never moving the amount, a fade under reduced motion.
 Every motion follows one lifecycle: before, trigger, transition, new state, feedback.
 The states themselves (waiting, result, recovery) are defined in ryux-interaction (RX-IX-01,
 RX-IX-02); motion only makes them visible, and it never compensates for weak UX. Decide the trigger,
@@ -833,7 +858,10 @@ check the motion rules already in force (RX-UI-11, RX-A11Y-08):
 - a close mid-way turns back from where it is, with no jump to fully open and no restart;
 - closing takes no longer than opening; entrances never use ease-in;
 - only transform and opacity move; a menu grows from its trigger, a drawer from its own edge;
-- what people open many times a day (menus, tabs) appears at once or with a short fade;
+- what people open many times a day (menus, tabs) uses a short transition, 250 ms or less, that a
+  click can interrupt; a command palette opened from the keyboard appears at once;
+- when tabs or a segmented control switch, the panel content moves with the indicator, not only
+  the indicator;
 - reduced motion leaves a fade or a cut, no movement;
 - after a dialog or drawer closes, focus is back on the control that opened it.
 Then record the interaction and step through it frame by frame: look for broken or skipped frames,

package/package.json

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