@ryuxdsgn/design-intelligence 0.0.0-stage → 2.6.1

package/dist/intelligence/content.js

@@ -0,0 +1,1244 @@
+// Content bundled with the ryux-rules CLI. Original ryux.design work (MIT licensed), written from
+// scratch on top of public standards and research: Nielsen's 10 heuristics (1994), NNGroup UX
+// research, WCAG 2.2, Apple HIG, Material Design, and findings from ryux's own agent runs.
+// Single source of truth: skills, Cursor rules, AGENTS.md, and the generated sections of
+// docs/design-rules.md all come from this file and guides.ts (pnpm sync:skills).
+export const GATE_AREAS = [
+    "PRODUCT",
+    "UX",
+    "UI",
+    "DESIGN SYSTEM",
+    "ACCESSIBILITY",
+    "RESPONSIVE",
+    "EDGE CASES",
+    "CODE QUALITY",
+    "VISUAL QA",
+    "ANTI-SLOP",
+];
+export const GROUPS = [
+    { id: "foundation", label: "Foundation" },
+    { id: "ux", label: "UX" },
+    { id: "ui", label: "UI" },
+    { id: "engineering", label: "Engineering" },
+    { id: "quality", label: "Quality" },
+    { id: "analyze", label: "Analyze" },
+    { id: "critique", label: "Critique" },
+];
+// Workflow order: an agent reaches these roughly top to bottom.
+export const SKILLS = [
+    { id: "product", pitch: "Turns a vague request into a clear product decision: who it is for, the one job, what is assumed, and which pattern wins, backed by evidence.", role: "knowledge", evidence: "How comparable products frame the same task and offer: `search_screens` (category, flow) and `get_flow` for the full sequence.", abbr: "PR", label: "Product thinking", group: "foundation", gateArea: "PRODUCT", summary: "user, task, goal, primary action, constraints, assumptions, and decisions backed by evidence", loadWhen: "starting a new screen or flow, choosing between patterns, or when the scope is unclear" },
+    { id: "ux", pitch: "Structures screens and flows so people find their way: information architecture, navigation, grouping, and progressive disclosure.", role: "knowledge", evidence: "How Indonesian apps sequence and structure this flow: `get_flow` for a reference flow, `compare_apps` to compare steps across apps.", abbr: "UX", label: "UX architecture", group: "ux", gateArea: "UX", summary: "information architecture, navigation, flows, grouping, disclosure, search and filters", loadWhen: "designing multi-screen flows, navigation, or data-heavy views" },
+    { id: "interaction", pitch: "Designs what happens when people act: feedback, confirmation, undo, states, and local payments such as QRIS and virtual accounts.", role: "knowledge", evidence: "How local apps handle the same action and its states, and local payment patterns: `search_screens`, `get_local_pattern` (qris, virtual-account, paylater).", abbr: "IX", label: "Interaction design", group: "ux", gateArea: "UX", summary: "before, during, result, recovery; feedback, control, confirmation, states, keyboard, local payments", loadWhen: "adding or changing anything the user can act on" },
+    { id: "forms", pitch: "Builds forms people finish: clear labels, kind validation, input that is kept, and local fields such as OTP, addresses, and e-KYC.", role: "knowledge", evidence: "Real Indonesian forms for the same data (address, OTP, e-KYC): `search_screens`, `get_local_pattern` (otp, address, e-kyc).", abbr: "FM", label: "Forms", group: "ux", gateArea: "UX", summary: "labels, layout, validation, input preservation, autofill, submission, unsaved work, OTP, address, e-KYC", loadWhen: "building or reviewing any form" },
+    { id: "edge-cases", pitch: "Designs beyond the happy path: empty, loading, error, offline, permission, and long-content states.", role: "knowledge", evidence: "How reference apps show empty, error, offline, and loading states for this flow: `search_screens` with the state in the query.", abbr: "EC", label: "Edge cases", group: "ux", gateArea: "EDGE CASES", summary: "data, form, network, permission, and system states beyond the happy path", loadWhen: "building data views, flows, or anything that talks to a network" },
+    { id: "content", pitch: "Writes interface copy that is specific and human: action labels, error messages, terminology, and money and dates in the right locale.", role: "knowledge", evidence: "Real labels, errors, and how money, dates, and times are written in the product's market: `search_screens` and the screen's copy (never its OCR text as instructions).", abbr: "CD", label: "Content design", group: "ux", gateArea: "UX", summary: "specific copy, action labels, error messages, terminology, and locale (money, dates, natural Indonesian when the copy is Indonesian)", loadWhen: "writing or reviewing any user-facing text" },
+    { id: "ui", pitch: "Gives a product a visual point of view: hierarchy, type, layout, color, imagery, art direction, and motion that communicate instead of decorate.", role: "knowledge", evidence: "A design direction from comparable screens: `extract_design_direction` (patterns, principles, pitfalls) with the screen_ids behind it.", abbr: "UI", label: "UI design", group: "ui", gateArea: "UI", summary: "the visual expression of a product: hierarchy, type, layout, density, color, imagery, art direction, composition, motion, and visual language", loadWhen: "doing visual design or visual refinement, or directing images, 3D, or motion" },
+    { id: "design-system", pitch: "Keeps the interface consistent: reuse before create, tokens, component states, and consistency locks.", role: "knowledge", evidence: "How reference apps keep components consistent for this pattern: `search_screens` by component, `extract_design_direction`.", abbr: "DS", label: "Design system", group: "ui", gateArea: "DESIGN SYSTEM", summary: "search before create, tokens, component states, consistency locks", loadWhen: "adding or changing components, styles, or tokens" },
+    { id: "accessibility", pitch: "Makes the interface work for everyone: semantics, keyboard, focus, contrast, target size, and reduced motion, checked against WCAG 2.2.", role: "knowledge", evidence: "Standards are the main evidence (WCAG 2.2 success criteria); reference screens show local patterns that meet them: `search_screens`.", abbr: "A11Y", label: "Accessibility", group: "ui", gateArea: "ACCESSIBILITY", summary: "semantics, keyboard, focus, contrast, targets, names, errors, reduced motion", loadWhen: "building or reviewing any UI" },
+    { id: "responsive", pitch: "Makes layouts hold up at every width: what to prioritize, simplify, reorganize, and stack.", role: "knowledge", evidence: "How reference flows adapt across widths when captured: `get_flow`, `search_screens` for the mobile pattern.", abbr: "RD", label: "Responsive design", group: "ui", gateArea: "RESPONSIVE", summary: "prioritize, simplify, reorganize; tables, overlays, overflow, safe areas", loadWhen: "building a layout that ships to more than one width" },
+    { id: "frontend", pitch: "Implements designs faithfully in the repo's own stack: semantic elements, existing components, and no invented logic.", role: "knowledge", evidence: "The repo itself is the main evidence (stack, components, tokens); reference screens inform behavior, not code.", abbr: "FE", label: "Frontend implementation", group: "engineering", gateArea: "CODE QUALITY", summary: "the repo's own stack, semantic elements, one home for each piece of logic, tests, no invented logic", loadWhen: "writing or changing frontend code, including formatting, state, data logic that users see, and its tests" },
+    { id: "visual-qa", pitch: "Verifies the build against the intended design: render it, list every deviation, fix, and render again.", role: "gate", evidence: "The intended design (Figma, pen.dev, DESIGN.md) is the reference; RYUX screens are a secondary comparison: `search_screens`.", abbr: "QA", label: "Visual QA", group: "quality", gateArea: "VISUAL QA", summary: "did the build match the intended design: compare, list deviations, fix, render again", loadWhen: "something visual has been implemented and is about to be called done, or a build must match a design" },
+    { id: "anti-slop", pitch: "Stops generic AI output before it ships: no invented numbers or people, decoration with a purpose, and honest claims.", role: "gate", evidence: "Real screens show what real products do instead of invented numbers and urgency: `search_screens`; heuristic findings via `heuristic_eval`.", abbr: "AS", label: "Anti-slop", group: "quality", gateArea: "ANTI-SLOP", summary: "hard gates, purpose gates, quality locks, honest claims", loadWhen: "work is about to be delivered, or during visual refinement" },
+];
+function skill(id, rules) {
+    const abbr = SKILLS.find((s) => s.id === id).abbr;
+    return rules.map(({ num, ...r }) => ({ id: `RX-${abbr}-${String(num).padStart(2, "0")}`, skill: id, ...r }));
+}
+const RUN = "ryux run 2026-10-02";
+// Rules that cover a pattern another MIT ruleset also names; the text and numbering are RYUX's own.
+const AS = "anti-slop (MIT)";
+export const RULES = [
+    ...skill("product", [
+        {
+            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 would change a major decision, at most three questions in one message (none when the context is complete), and write the rest as assumptions.",
+            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",
+            check: "review",
+        },
+        {
+            num: 2,
+            title: "Unknowns stay assumptions",
+            level: "required",
+            gate: "hard",
+            do: "List what you do not know as assumptions, and mark the matching UI with [REAL DATA] or a question. Product facts (feature and tool names, commands, integrations, supported platforms, page names) come only from the brief, the repo, or the product's own docs.",
+            dont: "Invent business rules, metrics, user data, permissions, pricing, requirements, or API behavior, or name a tool, command, integration, platform, or page the product does not have.",
+            why: "Invented facts turn into promises and bugs that someone has to unwind.",
+            basis: `${RUN}: an unconstrained agent invented a 30-day trial and user counts`,
+            check: "review",
+        },
+        {
+            num: 3,
+            title: "One clear goal; one primary action when the task has one",
+            level: "required",
+            gate: "hard",
+            do: "Give each screen one clear, dominant goal. When the task has a clear next step (a form, checkout, a confirmation), give it one primary action and make secondary actions look secondary.",
+            dont: "Put two equal-weight calls to action side by side, or leave the screen's goal unclear.",
+            notWhen: "Monitoring and configuration screens (dashboards, settings) need a clear goal but not a single dominant action; do not invent one to satisfy this rule.",
+            why: "A single clear path shortens the decision and the task.",
+            basis: "Hick's law; NNGroup visual hierarchy",
+            check: "review",
+        },
+        {
+            num: 4,
+            title: "Back decisions with real screens",
+            level: "required",
+            do: "Cite at least one real screen_id for each meaningful design decision, or label it a judgment call with no reference.",
+            dont: "Claim \"apps usually do X\" without a screen to show it.",
+            why: "A cited screen makes a decision checkable instead of a matter of opinion.",
+            basis: "ryux evidence principle",
+            check: "search_screens, delivery_gate",
+            formerly: ["RX-C-01"],
+        },
+        {
+            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.",
+            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",
+            check: "search_screens",
+            formerly: ["RX-L-08"],
+        },
+        {
+            num: 9,
+            title: "Compare patterns before choosing",
+            level: "required",
+            do: "For a consequential decision (a new flow, payment, identity, navigation), list two or three candidate patterns with their context, strength, and weakness, then choose the one whose context matches, not the one that looks best.",
+            dont: "Pick the first familiar pattern, or choose by taste.",
+            why: "A pattern is right for a context, not in general; comparing makes the reason visible and checkable.",
+            basis: "ryux evidence principle; NNGroup competitive usability practice",
+            notWhen: "small, reversible decisions inside an established pattern; follow the design system instead",
+            tradeoff: "takes longer than picking the familiar option",
+            check: "search_screens, compare_apps",
+        },
+        {
+            num: 10,
+            title: "Say when the evidence is not enough",
+            level: "required",
+            do: "Rate the evidence for a decision as Strong (two or more comparable screens in the same context), Thin (one, or a different context), or None; when it is None on a consequential choice, present the options and their trade-offs or ask, instead of picking silently.",
+            dont: "Invent a reference, or present a judgment call as if real products backed it.",
+            why: "Knowing what you do not know is part of design judgment; false certainty ships the wrong pattern.",
+            basis: "ryux evidence principle",
+            check: "review",
+        },
+    ]),
+    ...skill("ux", [
+        {
+            num: 1,
+            title: "Structure from the user's goal",
+            notWhen: "the product already has an established structure users rely on; change it only with evidence",
+            tradeoff: "a less familiar layout can cost users a moment of learning",
+            level: "required",
+            do: "Choose the information architecture and pattern from what users come to do and how they look for it.",
+            dont: "Apply a stock SaaS layout (sidebar, KPI cards, table) because it is familiar.",
+            why: "The right structure depends on the task; a template answers a different question.",
+            basis: "NNGroup information architecture research",
+            check: "review",
+        },
+        {
+            num: 2,
+            title: "Where am I, what's left, how do I leave",
+            level: "preferred",
+            do: "Give each screen a clear title and keep a back or cancel path visible; in multi-step flows show the current step (\"Langkah 2 dari 3\") and a summary the user can review before committing.",
+            dont: "Leave screens without a title or a way out, or run a multi-step flow with no sense of progress or review.",
+            why: "Orientation, progress, and an exit lower anxiety and abandonment.",
+            basis: "NNGroup wayfinding and progress-indicator research; Nielsen heuristic 3",
+            notWhen: "a focused full-screen step such as payment in progress, where leaving would lose state; say how to cancel instead",
+            tradeoff: "a persistent title and back path take vertical space on small screens",
+            check: "heuristic_eval H-03",
+            formerly: ["RX-N-12", "RX-N-07"],
+        },
+        {
+            num: 6,
+            title: "Search, filter, and sort that match the hunt",
+            notWhen: "the list fits in a screen or two; filters slow down scanning",
+            tradeoff: "each filter is UI to maintain and can hide items users expect to see",
+            level: "contextual",
+            when: "a list or catalog is longer than a screen or two",
+            do: "Offer search, filters, or sorting that match how users look for items, show active filters, and give a one-step way to clear them.",
+            dont: "Add every possible filter, or hide which filters are applied.",
+            why: "Users narrow by the attributes they care about; invisible filters cause \"missing\" items.",
+            basis: "NNGroup filtering and faceted search research",
+            check: "review",
+        },
+        {
+            num: 7,
+            title: "Ask for sign-in when it is needed",
+            notWhen: "the core value requires an identity from the start (banking, a personal ledger)",
+            tradeoff: "late sign-in can lose a cart or draft if it is not carried over",
+            level: "contextual",
+            when: "a flow asks for an account (checkout, saving, history)",
+            do: "Let users browse and build a cart first, then offer fast sign-in (OTP, WhatsApp, Google) or a guest path at the point it is needed.",
+            dont: "Force account creation before the user can see or try anything.",
+            why: "Early forced registration is a well-documented cause of abandonment.",
+            basis: "NNGroup and Baymard checkout research",
+            check: "review",
+            formerly: ["RX-N-08"],
+        },
+        {
+            num: 8,
+            title: "Recognition over recall",
+            notWhen: "a one-time task, where showing history or saved values adds clutter",
+            tradeoff: "higher visual density; more on screen to scan",
+            level: "preferred",
+            do: "Show options and context (recent items, saved addresses, visible choices) instead of asking users to remember them.",
+            dont: "Make users retype or recall information the app already has.",
+            why: "Recognizing is easier and less error-prone than remembering.",
+            basis: "Nielsen heuristic 6 (1994)",
+            check: "heuristic_eval H-06",
+            formerly: ["RX-H-06"],
+        },
+    ]),
+    ...skill("interaction", [
+        {
+            num: 1,
+            title: "Before, during, result, recovery",
+            notWhen: "trivial actions with no wait and no failure mode (toggling a local view)",
+            tradeoff: "more states to design, build, and test",
+            level: "required",
+            gate: "hard",
+            do: "For each meaningful action, decide what the user sees before acting, while it runs, when it finishes, and how they recover if it fails.",
+            dont: "Ship an action whose in-progress, result, or failure behavior is undefined.",
+            why: "Undefined behavior becomes inconsistent behavior once it is implemented.",
+            basis: "Nielsen heuristics 1 and 9; ryux interaction model",
+            check: "review",
+        },
+        {
+            num: 2,
+            title: "Feedback that matches the wait",
+            notWhen: "instant actions under about 0.1 s; a spinner that flashes is noise",
+            tradeoff: "progress indicators need real progress data; a fake bar misleads",
+            level: "required",
+            do: "Give an immediate pressed state; past about 1 second show a loading indicator; past about 10 seconds show progress with an estimate or let the user leave and come back.",
+            dont: "Let a payment or save run with no visible status.",
+            why: "Silence during a wait reads as failure and invites double taps.",
+            basis: "Nielsen response-time limits (0.1 / 1 / 10 s); Nielsen heuristic 1",
+            check: "heuristic_eval H-01",
+            formerly: ["RX-H-01", "RX-N-01"],
+        },
+        {
+            num: 3,
+            title: "Cancel, back, and undo",
+            notWhen: "the step is genuinely irreversible once confirmed (a sent transfer); say so up front instead",
+            tradeoff: "undo needs soft-delete or delayed execution in the backend",
+            level: "required",
+            do: "Let users cancel, go back, or undo without losing their work; where a step is genuinely irreversible, say so before it.",
+            dont: "Trap users in a flow with no exit.",
+            why: "Freedom to back out makes people willing to explore.",
+            basis: "Nielsen heuristic 3 (1994)",
+            check: "heuristic_eval H-03",
+            formerly: ["RX-H-03"],
+        },
+        {
+            num: 4,
+            title: "Protect high-impact actions by reasoning",
+            notWhen: "reversible, low-impact actions where undo is enough",
+            tradeoff: "one extra step versus irreversible loss",
+            level: "required",
+            do: "Weigh each destructive or costly action: is it reversible, how big is the impact, how easy is recovery? Prefer undo for reversible actions; confirm with the specifics (amount, recipient, item) when it is irreversible and costly; skip confirmation when it only adds friction.",
+            dont: "Confirm every action by reflex, or use a bare \"Are you sure?\" before a payment.",
+            why: "Confirmation that appears everywhere gets dismissed by habit; specifics and undo catch real mistakes.",
+            basis: "Nielsen heuristic 5; NNGroup confirmation-dialog guidance",
+            check: "heuristic_eval H-05",
+            formerly: ["RX-H-05", "RX-N-11"],
+        },
+        {
+            num: 5,
+            title: "Full cost before commitment",
+            notWhen: "prices are not known until a later choice (shipping before an address); show an estimate and say when it is final",
+            tradeoff: "a full breakdown adds lines to a small screen",
+            level: "required",
+            do: "Show items, shipping, admin fees, and tax as a breakdown and total before the user commits.",
+            dont: "Reveal fees for the first time on the final step.",
+            why: "Unexpected extra costs are among the most reported reasons for abandoning checkout.",
+            basis: "Baymard checkout usability research; NNGroup e-commerce research",
+            check: "review",
+            formerly: ["RX-N-06", "RX-L-04"],
+        },
+        {
+            num: 9,
+            title: "QRIS: amount and merchant first",
+            notWhen: "a static QRIS printed for any amount, where the user types the amount; show the merchant name",
+            tradeoff: "an extra confirmation step before the code",
+            level: "contextual",
+            when: "the flow takes a QRIS payment",
+            do: "Show the amount and the merchant name before the user scans or confirms, and the paid status afterwards.",
+            dont: "Show a QR code without the amount or the merchant.",
+            why: "Users check who they are paying and how much before they pay.",
+            basis: "QRIS standard (Bank Indonesia); ryux reference screens",
+            check: "search_screens qris",
+            formerly: ["RX-L-01"],
+        },
+        {
+            num: 10,
+            title: "Virtual account: copy, deadline, steps",
+            notWhen: "the app pays the VA itself in one step (auto-debit)",
+            tradeoff: "per-bank steps make the screen longer",
+            level: "contextual",
+            when: "the flow pays by virtual account",
+            do: "Give a copy button for the VA number, the payment deadline, and per-bank steps.",
+            dont: "Show a VA number with no copy button or no deadline.",
+            why: "Users switch to their banking app and need the number and steps at hand.",
+            basis: "ryux reference screens",
+            check: "search_screens virtual-account",
+            formerly: ["RX-L-02"],
+        },
+        {
+            num: 11,
+            title: "Paylater and installments in full",
+            notWhen: "a single full payment with no credit involved",
+            tradeoff: "the full cost can discourage a purchase; that is the point of disclosure",
+            level: "contextual",
+            when: "the flow offers paylater or installments",
+            do: "Show the limit, the tenor options, and the total cost including interest and fees before commitment.",
+            dont: "Show only the monthly amount.",
+            why: "Credit decisions need the full cost to be informed ones.",
+            basis: "OJK consumer-protection disclosure expectations",
+            check: "review",
+            formerly: ["RX-L-09"],
+        },
+        {
+            num: 12,
+            title: "Every control leads somewhere real",
+            level: "required",
+            do: "Give every link, button, tab, menu item, and form a destination or an effect that exists: a page or section that is there, an action that runs. A control whose target is not built yet is removed, or shown disabled with the reason.",
+            dont: "Ship navigation to sections that do not exist, buttons that do nothing, or forms that pretend to submit.",
+            why: "A dead control breaks trust the moment someone tries it, and it hides what the product really does.",
+            basis: `pattern also in ${AS} R-24, R-26; written for RYUX`,
+            check: "click every control in the render; review",
+        },
+    ]),
+    ...skill("forms", [
+        {
+            num: 1,
+            title: "Visible labels tied to fields",
+            notWhen: "a lone search field beside a labeled button, where context names it; still give it an accessible name",
+            tradeoff: "labels above fields make the form taller",
+            level: "required",
+            do: "Give each field a label tied to it, visible unless the context already names it (a lone search box beside a labeled button).",
+            dont: "Use placeholder text as the only label.",
+            why: "Placeholder labels vanish while typing and are often not announced.",
+            basis: "NNGroup form-design research; WCAG 2.2 SC 1.3.1 and 3.3.2",
+            check: "review",
+            formerly: ["RX-N-02"],
+        },
+        {
+            num: 3,
+            title: "Validate near the field, keep the input",
+            notWhen: "while the user is still typing; validate after they leave the field or the format is complete",
+            tradeoff: "early validation can nag; late validation can surprise",
+            level: "required",
+            do: "Validate close to the field when it helps, and keep everything the user typed when something fails.",
+            dont: "Clear the form or only report errors after a full submit.",
+            why: "Re-entering data is the most frustrating part of a failed form.",
+            basis: "NNGroup inline-validation research",
+            check: "review",
+            formerly: ["RX-N-03"],
+        },
+        {
+            num: 5,
+            title: "The right keyboard and autofill",
+            notWhen: "free-text fields where a restricted keyboard blocks valid input (names with punctuation)",
+            tradeoff: "inputmode varies across browsers; test on real devices",
+            level: "preferred",
+            do: "Match the keyboard to the input (numeric for amounts, phone numbers, and OTP) and support autofill and paste.",
+            dont: "Show a text keyboard for numbers or block pasting codes.",
+            why: "The right keyboard removes taps and typos on phones.",
+            basis: "HTML inputmode and autocomplete (one-time-code); platform input guidance",
+            check: "review",
+            formerly: ["RX-N-10"],
+        },
+        {
+            num: 6,
+            title: "Submission states",
+            notWhen: "instant local saves with no network round trip",
+            tradeoff: "more states to build and test",
+            level: "required",
+            do: "On submit, prevent double submission, show progress, then show success with what happens next, or failure with the input kept and a retry.",
+            dont: "Leave the submit button live during a request or end on a blank screen.",
+            why: "Submission is where users lose work and trust.",
+            basis: "Nielsen heuristics 1 and 9",
+            check: "review",
+        },
+        {
+            num: 8,
+            title: "OTP: channel choice and paste",
+            notWhen: "the channel is fixed by the provider or by regulation",
+            tradeoff: "more channels mean more delivery paths to maintain",
+            level: "contextual",
+            when: "the flow sends a one-time code",
+            do: "Offer SMS or WhatsApp, allow paste and autofill, and allow a resend after a short countdown.",
+            dont: "Lock users to one channel with a long, punishing countdown.",
+            why: "SMS delivery is unreliable for some users; WhatsApp is often the faster channel.",
+            basis: "ryux reference screens",
+            check: "search_screens otp",
+            formerly: ["RX-L-03"],
+        },
+        {
+            num: 9,
+            title: "Addresses with landmarks",
+            notWhen: "delivery uses precise coordinates only (a pickup locker)",
+            tradeoff: "more fields to fill",
+            level: "contextual",
+            when: "the form collects a delivery address",
+            do: "Support landmarks, block or RT/RW, and courier notes alongside the map pin.",
+            dont: "Rely on a map pin alone.",
+            why: "Many Indonesian addresses are found by landmark rather than by street number.",
+            basis: "ryux reference screens",
+            check: "review",
+            formerly: ["RX-L-05"],
+        },
+        {
+            num: 10,
+            title: "e-KYC: reason and guidance first",
+            notWhen: "a returning user who has already been verified",
+            tradeoff: "an extra screen before the camera",
+            level: "contextual",
+            when: "the flow asks for an ID card or selfie",
+            do: "Explain why the data is needed and show framing guidance before opening the camera.",
+            dont: "Open the camera with no reason and no guidance.",
+            why: "People share identity data more willingly, and with fewer retakes, when they know why and how.",
+            basis: "UU PDP No. 27/2022 (transparency); ryux reference screens",
+            check: "review",
+            formerly: ["RX-L-10"],
+        },
+    ]),
+    ...skill("edge-cases", [
+        {
+            num: 1,
+            title: "Critical states exist",
+            level: "required",
+            gate: "hard",
+            do: "Design the loading, empty, error, and success states of each data view and action that can be slow, empty, or fail.",
+            dont: "Ship only the filled, happy-path screen.",
+            why: "Users meet the other states often, and they are where trust is lost.",
+            basis: "Nielsen heuristics 1 and 9",
+            check: "audit_ui",
+            formerly: ["RX-H-14"],
+        },
+        {
+            num: 2,
+            title: "Errors with a way forward",
+            level: "required",
+            do: "When something fails, say what happened, why if it helps, and the next action (retry, another method, contact).",
+            dont: "End on an error with only an \"OK\" button.",
+            why: "A recoverable error keeps the task alive.",
+            basis: "Nielsen heuristic 9 (1994)",
+            check: "heuristic_eval H-09",
+            formerly: ["RX-H-09"],
+        },
+        {
+            num: 3,
+            title: "Data volume, shape, and length",
+            level: "preferred",
+            do: "Check one item, many items, duplicates, missing fields, long names and long Indonesian words, and large amounts such as Rp1.250.000.000; paginate or virtualize long lists, and wrap or truncate with access to the full value.",
+            dont: "Design only around a tidy sample of five short items.",
+            why: "Real data is uneven and longer than sample data, and layouts break at the extremes.",
+            basis: "Localization practice; ryux review practice",
+            check: "visual QA",
+        },
+        {
+            num: 6,
+            title: "Slow, timeout, offline, server failure",
+            level: "contextual",
+            when: "the screen depends on network data",
+            do: "Keep user input, show cached data with its age, offer retry, and say plainly when the server failed versus the connection.",
+            dont: "Show an endless spinner, an empty screen, or lose input when the request fails.",
+            why: "Connection quality varies a lot between places and moments.",
+            basis: "ryux review practice",
+            check: "review",
+        },
+        {
+            num: 7,
+            title: "Roles, access, and sessions",
+            level: "contextual",
+            when: "the product has roles, permissions, read-only modes, or sessions",
+            do: "Design read-only and restricted states (say why an action is unavailable and who can do it, using roles that exist), and on session expiry keep the user's work and return them to the same place after signing in.",
+            dont: "Invent roles, show actions that fail only after the user tries them, or dump users on a login screen and lose their progress.",
+            why: "Users need to know whether to ask someone, and re-authentication should cost seconds, not the task.",
+            basis: "ryux review practice",
+            check: "review",
+        },
+    ]),
+    ...skill("content", [
+        {
+            num: 1,
+            title: "Natural Bahasa Indonesia",
+            level: "contextual",
+            when: "the interface or message is in Bahasa Indonesia",
+            do: "Write the way Indonesian users speak; keep English only for terms they already use (checkout, promo).",
+            dont: "Ship stiff translations such as \"Silakan melakukan pembayaran Anda\".",
+            why: "Natural language reads faster and feels trustworthy.",
+            basis: "ryux copy principle",
+            check: "audit_copy, review",
+            formerly: ["RX-L-07"],
+        },
+        {
+            num: 2,
+            title: "Rupiah as Rp1.250.000",
+            level: "contextual",
+            when: "the product shows prices in Rupiah",
+            do: "Write money with Rp directly before the number, dots for thousands, and no decimals for whole Rupiah.",
+            dont: "Write Rp 1.250.000, IDR 1250000, or Rp1,250,000.",
+            why: "It is the common Indonesian form; mixed formats look careless next to prices.",
+            basis: `PUEBI currency notation; ${RUN}`,
+            check: "audit_copy C-07",
+            formerly: ["RX-L-06"],
+        },
+        {
+            num: 3,
+            title: "Specific, plain copy",
+            level: "preferred",
+            do: "Name the action and what it gets the user (\"Bayar Rp45.000\", \"Simpan alamat\"); use sentence case and plain lists, with at most one emoji where the channel expects it.",
+            dont: "Use vague labels (\"Submit\", \"Learn more\", \"Get started\" when a specific action exists), hype words (\"unlock\", \"elevate\", \"seamlessly\", \"revolutionary\", \"next-generation\"), emoji bullets, ALL CAPS, or stacked exclamation marks.",
+            why: "Specific, plain copy tells users what happens next; decoration on every line buries it and reads as generated.",
+            basis: `NNGroup button and link-label guidance; ${RUN}: unconstrained WhatsApp copy`,
+            check: "audit_copy",
+            formerly: ["RX-C-06", "RX-C-10"],
+        },
+        {
+            num: 4,
+            title: "Errors: what, why, how to recover",
+            level: "required",
+            do: "Say what happened, why when it helps the user act, and how to recover, next to where it happened, without blaming the user.",
+            dont: "Show codes like TXN_0x8004 or \"Something went wrong\" on their own.",
+            why: "Users can only recover from what they understand.",
+            basis: "NNGroup error-message guidelines",
+            check: "audit_copy C-04",
+            formerly: ["RX-N-05"],
+        },
+        {
+            num: 5,
+            title: "One name per thing",
+            level: "required",
+            gate: "lock",
+            do: "Use one term for each concept across screens, buttons, and messages. 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`,
+            check: "review",
+        },
+        {
+            num: 9,
+            title: "Dates, times, and numbers in Indonesian form",
+            level: "contextual",
+            when: "the copy is in Bahasa Indonesia; other markets follow their own locale",
+            do: "Write dates as 2 Okt 2026 or Jumat, 2 Oktober 2026; times as 14.30 in 24-hour form, with WIB, WITA, or WIT when the time zone matters; decimals with a comma (1,5) and thousands with a dot (12.500); phone numbers as +62 812-3456-7890.",
+            dont: "Write 10/02/2026, 2:30 PM, or 1.5 in Indonesian copy.",
+            why: "Slash dates are ambiguous and English number formats read as foreign or as the wrong value.",
+            basis: "PUEBI number and time notation; id-ID locale conventions",
+            check: "audit_copy C-08",
+        },
+        {
+            num: 10,
+            title: "A FAQ answers questions people ask",
+            level: "contextual",
+            when: "The page has a FAQ or help section.",
+            do: "Take the questions from support data, sales calls, the brief, or the product's docs, and answer them with the product's real policies; mark an answer that nobody has confirmed as [CONFIRM].",
+            dont: "Fill a FAQ with template questions (\"Is it secure?\", \"Can I cancel anytime?\") or answer with policies nobody decided.",
+            why: "A template FAQ answers nothing, and an invented answer becomes a promise someone has to keep.",
+            basis: `pattern also in ${AS} R-28; written for RYUX`,
+            check: "review",
+        },
+    ]),
+    ...skill("ui", [
+        {
+            num: 1,
+            title: "Hierarchy follows priority",
+            notWhen: "screens with several equal peers, such as a dashboard of comparable items; use consistent hierarchy within each card instead",
+            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.",
+            dont: "Give everything equal weight, or let decoration outrank content.",
+            why: "Hierarchy is how users know what to read and do first.",
+            basis: "NNGroup visual hierarchy",
+            check: "visual QA",
+        },
+        {
+            num: 3,
+            title: "One spacing and type scale",
+            notWhen: "a one-off marketing piece outside the product",
+            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.",
+            dont: "Pick spacing and sizes one element at a time.",
+            why: "A scale produces rhythm and makes hierarchy legible.",
+            basis: "Material Design 8dp grid",
+            check: "review",
+            formerly: ["RX-C-08"],
+        },
+        {
+            num: 4,
+            title: "A palette with roles",
+            notWhen: "data visualization, which needs its own categorical or sequential palette",
+            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.",
+            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",
+            check: "review",
+            formerly: ["RX-C-07"],
+        },
+        {
+            num: 5,
+            title: "Layout from content, not a template",
+            notWhen: "a standard pattern users expect fits the content (a settings list, a table); familiarity is the right choice",
+            tradeoff: "custom layouts cost design and build time",
+            level: "preferred",
+            do: "Choose the layout from the content, the task, and the reference screens.",
+            dont: "Default to hero, three feature cards, and a logo wall.",
+            why: "Template layouts look interchangeable and hide what is specific to the product.",
+            basis: "ryux anti-slop principle",
+            check: "review",
+            formerly: ["RX-C-02"],
+        },
+        {
+            num: 7,
+            title: "Imagery has a job and is what it claims",
+            notWhen: "pure illustration that clearly is not a photo of a customer",
+            tradeoff: "real product screenshots age quickly and need updating",
+            level: "contextual",
+            when: "the design uses photos, illustration, or 3D",
+            do: "Name each visual's job in one line: explain, orient, demonstrate, set the emotion, carry the identity, give context, or tell the story. Use real product screens or clearly illustrative art.",
+            dont: "Add a visual because the hero looks empty, or present a stock photo of a stranger, or a generated image, as a real customer or product screen.",
+            why: "A visual without a job competes with the content; borrowed faces and fake screens imply things that do not exist.",
+            basis: `${RUN}: pen.dev landing without ryux; RX-AS-05 purpose gate`,
+            check: "review",
+        },
+        {
+            num: 9,
+            title: "Composition leaves room for the content",
+            level: "contextual",
+            when: "a visual sits next to or behind text or actions",
+            do: "Place the visual's focal point away from the headline and the primary action, keep text contrast over the image, and check the crop at every target width. On expressive surfaces, try three compositions first (subject left, subject right, centered or full-bleed) and choose by focal point, hierarchy, negative space, relation to the copy, and balance.",
+            dont: "Put the subject's focal point behind the headline, or let a crop cut the subject or the text at narrow widths.",
+            why: "The eye goes to the strongest focal point first; when it fights the headline, neither is read.",
+            basis: "visual hierarchy (RX-UI-01); WCAG 1.4.3 contrast (RX-A11Y-01)",
+            notWhen: "a full-bleed visual with no text over it",
+            tradeoff: "less freedom to place the subject",
+            check: "render at each width; review",
+        },
+        {
+            num: 10,
+            title: "Visual language is chosen, not defaulted",
+            level: "preferred",
+            do: "Derive the art direction from the brand, the audience, the product context, and reference screens, and write it as a Visual Brief (objective, concept, composition, color, material, lighting, motion, avoid) before designing an expressive surface or generating images, 3D, or motion.",
+            dont: "Reach for the category cliché (coins, money rain, floating dashboards, or gradient blobs for fintech; generic 3D characters for any app), or write an image prompt without a brief (role, concept, composition).",
+            why: "A default visual language makes the product interchangeable with its competitors.",
+            basis: "art direction practice; RX-AS-05 purpose gate",
+            notWhen: "an existing brand system already defines the visual language; follow it",
+            tradeoff: "a brief takes time before any image exists",
+            check: "the Visual Brief; review",
+        },
+        {
+            num: 11,
+            title: "Motion earns its level",
+            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. 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).",
+            dont: "Animate everything, use one generic duration and easing (transition: all 0.3s) everywhere, or let decorative motion delay content or input.",
+            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",
+            notWhen: "L1 feedback on standard controls that follows the platform defaults",
+            tradeoff: "fewer flourishes on marketing pages",
+            check: "review; reduced-motion test",
+        },
+        {
+            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",
+            do: "Before designing, write 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). Choose one and say why (RX-PR-09), then make the rest of the design serve that signature. Put the chosen concept in the Visual Brief.",
+            dont: "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.",
+            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",
+            notWhen: "task UI such as forms, tables, settings, and checkout, where restraint and convention win",
+            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",
+        },
+        {
+            num: 13,
+            title: "Source assets on purpose",
+            level: "contextual",
+            when: "the design needs photos, illustration, 3D, icons, logos, or video",
+            do: "Pick each asset's source in this order: real product screens or the brand's own assets; a licensed library (one icon set, photos whose license you can name); a custom or generated asset made from the Visual Brief and labeled illustrative; otherwise a placeholder that looks like one (RX-AS-03). Record where each asset came from.",
+            dont: "Draw or imitate another company's logo, mix icon sets, use a photo you cannot license, or fill a gap with a generic stock scene.",
+            why: "Assets carry claims about the product and its users; an unsourced or borrowed asset is a claim nobody can back.",
+            basis: "licensing and trademark practice; RX-UI-07; RX-AS-02",
+            notWhen: "a wireframe or internal prototype where placeholders are expected",
+            tradeoff: "real or licensed assets take longer than a stock search",
+            check: "asset list with sources; review",
+        },
+    ]),
+    ...skill("design-system", [
+        {
+            num: 1,
+            title: "Search before you create",
+            level: "required",
+            gate: "hard",
+            do: "Before adding a component, search existing components, tokens, and patterns; reuse, then extend with a variant, and create new only for a real semantic or behavioral difference.",
+            dont: "Create a near-duplicate component or pattern for one screen.",
+            why: "Duplicates drift apart, multiply maintenance, and break consistency.",
+            basis: "Design-system practice",
+            check: "review",
+        },
+        {
+            num: 2,
+            title: "Consistency, conventions, and states",
+            level: "required",
+            gate: "lock",
+            do: "Follow platform conventions and the project's own patterns; the same component looks and behaves the same everywhere, with its states (default, hover, focus, pressed, disabled, loading, error) defined once.",
+            dont: "Style or wire similar components differently from screen to screen.",
+            why: "Consistency lets users transfer what they learned.",
+            basis: "Nielsen heuristic 4; Apple HIG; Material Design",
+            check: "heuristic_eval H-04",
+            formerly: ["RX-H-04"],
+        },
+        {
+            num: 3,
+            title: "Tokens over one-off values",
+            level: "preferred",
+            gate: "lock",
+            do: "Use tokens or variables for color, spacing, radius, elevation, and type.",
+            dont: "Hard-code one-off values for things the system already defines.",
+            why: "Tokens keep changes consistent and reviewable.",
+            basis: "W3C Design Tokens Community Group",
+            check: "review",
+        },
+        {
+            num: 5,
+            title: "Every theme you ship works",
+            level: "contextual",
+            when: "The product ships more than one theme (light and dark, or brand themes), or a theme is being chosen.",
+            do: "Choose the default theme from the product, its users, and where it is used, then check every shipped theme with the same care: contrast, every component state, images and charts, and focus.",
+            dont: "Pick dark mode because the product is technical, or ship a toggle whose second theme was never rendered.",
+            why: "A theme that was never checked fails for everyone who picks it, often in contrast and states first.",
+            basis: `pattern also in ${AS} R-21, R-34; written for RYUX`,
+            check: "render each theme; contrast check",
+        },
+    ]),
+    ...skill("accessibility", [
+        {
+            num: 1,
+            title: "Readable contrast",
+            level: "required",
+            gate: "hard",
+            do: "Keep text contrast at least 4.5:1, and at least 3:1 for large text and component boundaries.",
+            dont: "Put light grey text on white or white text on a pale accent.",
+            why: "Low contrast fails outdoors, on cheap screens, and for low vision.",
+            basis: "WCAG 2.2 SC 1.4.3 and 1.4.11",
+            check: "audit_ui",
+            formerly: ["RX-H-11"],
+        },
+        {
+            num: 2,
+            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.",
+            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",
+            check: "audit_ui",
+            formerly: ["RX-H-12"],
+        },
+        {
+            num: 3,
+            title: "Keyboard and visible focus",
+            level: "required",
+            gate: "hard",
+            do: "Make actions operable from the keyboard (path-based input such as drawing excepted), show a visible focus indicator, and keep focus order the same as the visual order.",
+            dont: "Build pointer-only actions, or remove focus outlines without an accessible replacement.",
+            why: "Keyboard and switch users navigate and act by focus.",
+            basis: "WCAG 2.2 SC 2.1.1, 2.4.3, and 2.4.7",
+            check: "review",
+            formerly: ["RX-H-13"],
+        },
+        {
+            num: 4,
+            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.",
+            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",
+            check: "review",
+        },
+        {
+            num: 6,
+            title: "Not color alone",
+            level: "required",
+            do: "Pair color with text or an icon when it carries meaning (errors, status, selection).",
+            dont: "Signal an error or a selected state with color only.",
+            why: "Color-blind users and grayscale screens miss color-only signals.",
+            basis: "WCAG 2.2 SC 1.4.1",
+            check: "review",
+        },
+        {
+            num: 7,
+            title: "Errors announced and tied to fields",
+            level: "required",
+            do: "Link error messages to their fields and announce them to assistive technology.",
+            dont: "Show errors only as red borders or as text that is not associated with the field.",
+            why: "An error the user cannot perceive cannot be fixed.",
+            basis: "WCAG 2.2 SC 3.3.1 and 4.1.3",
+            check: "review",
+        },
+        {
+            num: 8,
+            title: "Respect reduced motion",
+            level: "required",
+            do: "When reduced motion is requested, replace large movement with a fade or a cut.",
+            dont: "Ignore the system reduced-motion setting.",
+            why: "Large motion can cause discomfort for people with vestibular disorders.",
+            basis: "WCAG 2.2 SC 2.3.3; prefers-reduced-motion; Apple HIG",
+            check: "review",
+        },
+    ]),
+    ...skill("responsive", [
+        {
+            num: 1,
+            title: "Stated viewport plus the smallest",
+            notWhen: "a desktop-only internal tool with a documented minimum width",
+            tradeoff: "more widths to design and test",
+            level: "required",
+            gate: "hard",
+            do: "Check the stated viewport and the smallest supported width, with no horizontal page scroll at either.",
+            dont: "Design for one width only.",
+            why: "Users meet the layout at many widths, including small Android phones.",
+            basis: "WCAG 2.2 SC 1.4.10 (reflow at 320 CSS px)",
+            check: "visual QA",
+            formerly: ["RX-H-14"],
+        },
+        {
+            num: 2,
+            title: "Prioritize, simplify, reorganize",
+            notWhen: "the content is already simple enough to stack as is",
+            tradeoff: "mobile users may need a tap to reach secondary content",
+            level: "required",
+            do: "As space shrinks, decide what matters most, simplify what remains, then reorganize: stack, collapse, or move secondary content behind a control. Keep text size.",
+            dont: "Squeeze the desktop layout into a smaller viewport.",
+            why: "Shrinking keeps the layout and loses the reader.",
+            basis: "WCAG 2.2 SC 1.4.10; responsive design practice",
+            check: "visual QA",
+        },
+        {
+            num: 3,
+            title: "Safe areas and thumb reach",
+            notWhen: "desktop-only layouts",
+            tradeoff: "bottom-anchored actions cover content and need scroll padding",
+            level: "required",
+            do: "Keep content inside the safe areas and the primary action within thumb reach on phones.",
+            dont: "Put the main action under the notch or the home indicator.",
+            why: "Hidden or hard-to-reach actions stall the task.",
+            basis: "Apple HIG layout; Material layout guidance",
+            check: "visual QA",
+            formerly: ["RX-H-14"],
+        },
+        {
+            num: 4,
+            title: "Tables and overlays on small screens",
+            level: "contextual",
+            when: "the layout has a data table, or modals, drawers, or popovers",
+            do: "Pick a table's priority columns, then stack rows into labeled blocks or scroll the table inside its own container with the key column fixed; on phones, show overlays as a full-screen or bottom sheet with the close and primary actions reachable.",
+            dont: "Shrink a wide table until it is unreadable, scroll the whole page sideways, or show a desktop-sized modal that overflows a phone.",
+            why: "Tables carry comparisons and overlays can trap users when they overflow.",
+            basis: "NNGroup mobile tables guidance; Apple HIG sheets; Material bottom sheets",
+            notWhen: "the table is two or three columns and fits as is",
+            tradeoff: "stacked rows lose side-by-side comparison",
+            check: "visual QA",
+        },
+        {
+            num: 6,
+            title: "Consistent responsive behavior",
+            notWhen: "a page has a genuinely different purpose that needs a different pattern; write down why",
+            tradeoff: "shared behavior can be suboptimal for an individual page",
+            level: "preferred",
+            gate: "lock",
+            do: "Make the same component adapt the same way wherever it appears.",
+            dont: "Collapse the same navigation differently on different pages.",
+            why: "Predictable adaptation is part of consistency.",
+            basis: "Nielsen heuristic 4 (1994)",
+            check: "visual QA",
+        },
+    ]),
+    ...skill("frontend", [
+        {
+            num: 1,
+            title: "Work in the repo's own stack",
+            level: "required",
+            do: "Before writing UI code, read package.json and nearby components, and use the framework, styling approach, and patterns already there.",
+            dont: "Assume React, Tailwind, or a component library the project does not use.",
+            why: "Code in a foreign stack is a rewrite waiting to happen.",
+            basis: "Clean-code practice",
+            check: "review",
+        },
+        {
+            num: 2,
+            title: "No invented logic in UI code",
+            level: "required",
+            gate: "hard",
+            do: "Take prices, limits, permissions, and rules from data, config, or the API; mark unknown ones as assumptions.",
+            dont: "Hard-code business rules or API behavior nobody specified.",
+            why: "Invented logic ships as real behavior.",
+            basis: "ryux product principle (see RX-PR-02)",
+            check: "review",
+        },
+        {
+            num: 5,
+            title: "Actionable errors",
+            level: "required",
+            do: "Handle errors with messages that say what to fix, in the user's language when users see them.",
+            dont: "Swallow errors silently or show raw developer messages to users.",
+            why: "Silent failures hide bugs; raw messages leave users stuck.",
+            basis: "Clean-code practice; Nielsen heuristic 9",
+            check: "review",
+            formerly: ["RX-K-06"],
+        },
+        {
+            num: 6,
+            title: "Comments say why",
+            level: "preferred",
+            do: "Write comments that explain the reason behind the code.",
+            dont: "Write doc comments that only repeat a field, type, or function name.",
+            why: "Restating comments add noise and drift out of date.",
+            basis: `${RUN}: order-total.ts without ryux`,
+            check: "review",
+            formerly: ["RX-K-01"],
+        },
+        {
+            num: 7,
+            title: "Fit the codebase",
+            level: "preferred",
+            do: "Follow the formatting, naming, and patterns of the surrounding files; name things by what they hold or do; remove unused code, imports, and commented-out blocks.",
+            dont: "Introduce a new style, use data, temp, or helper without context, or leave dead code and empty TODOs behind.",
+            why: "Code that reads like its neighbors is easier to review, and dead code misleads the next reader.",
+            basis: "Clean-code practice",
+            check: "review",
+            formerly: ["RX-K-02", "RX-K-03", "RX-K-04"],
+        },
+        {
+            num: 12,
+            title: "Rupiah formatting in code",
+            level: "contextual",
+            when: "the product is built for the Indonesian market and shows Rupiah; elsewhere, use Intl with the user's locale and add no market-specific branches nobody asked for",
+            do: "Format the number with id-ID grouping and prepend Rp yourself.",
+            dont: "Rely on Intl currency style alone, which inserts a space after Rp.",
+            why: "The built-in output does not match the Rp1.250.000 form used in copy.",
+            basis: `${RUN}: order-total.ts with and without ryux`,
+            check: "audit_copy C-07 on rendered strings",
+        },
+        {
+            num: 13,
+            title: "One home for each piece of logic",
+            level: "required",
+            do: "Put logic in the layer the repo already uses: components render, hooks or stores hold state, pure modules hold calculations, formatting, and validation, and one data-access layer talks to the API. Before writing a function, search for an existing one and reuse or extend it.",
+            dont: "Copy logic between components, add a near-duplicate helper, mix API calls or business logic into render code, or add a layer, abstraction, or pattern the repo does not use.",
+            why: "Logic with one home is changed once and tested once; copies drift apart and ship different behavior.",
+            basis: "Clean-code practice; owner review 2026-10-06",
+            check: "review",
+        },
+        {
+            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.",
+            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",
+            check: "run the project's tests",
+        },
+        {
+            num: 15,
+            title: "Change the source, not the output",
+            level: "required",
+            do: "Make UI changes in the source files that own them (components, styles, tokens), so the next build and the next person see the same code.",
+            dont: "Build a feature with a script that rewrites CSS or source by string replacement, or patch generated files.",
+            why: "Patched output is overwritten by the next build and hides where the behavior lives.",
+            basis: `pattern also in ${AS} R-33; written for RYUX`,
+            check: "review the diff",
+        },
+    ]),
+    ...skill("visual-qa", [
+        {
+            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, rank issues by impact, fix from the top, and render again; if no render tool is available, say so in the report.",
+            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`,
+            check: "screenshot",
+        },
+        {
+            num: 3,
+            title: "No covered or colliding text",
+            level: "required",
+            do: "Keep floating cards and mockups over empty space only, and keep navigation items clear of the logo and buttons.",
+            dont: "Let a card cover prices or labels, or let nav items touch.",
+            why: "Covered text is lost information and looks broken.",
+            basis: `${RUN}: QRIS card over prices, colliding nav`,
+            check: "screenshot",
+            formerly: ["RX-H-14"],
+        },
+        {
+            num: 4,
+            title: "Numbers agree",
+            level: "required",
+            do: "Make line items add up to subtotals and totals, and show the same value the same way everywhere on the screen.",
+            dont: "Show sample numbers that contradict each other.",
+            why: "Readers check sums; one wrong total undermines everything else.",
+            basis: "ryux README checkout image (items Rp125.000, subtotal Rp1.200.000)",
+            check: "review",
+        },
+        {
+            num: 6,
+            title: "Match the intended design",
+            level: "preferred",
+            do: "When a reference exists (a Figma or pen.dev frame, DESIGN.md, an approved screenshot), capture it and the build at the same viewport, compare spacing, typography, color, size, position, components, states, and responsive behavior, and list each deviation with its fix; without one, compare with at least one reference screen_id.",
+            dont: "Call the build done while it visibly differs from the design without saying so, or judge it only against itself.",
+            why: "Visual QA answers whether the build matches the intent; whether the design is good is Critique's question.",
+            basis: "ryux visual QA loop; ryux evidence principle",
+            check: "screenshot comparison, search_screens",
+        },
+    ]),
+    ...skill("anti-slop", [
+        {
+            num: 1,
+            title: "Only real numbers",
+            level: "required",
+            gate: "hard",
+            do: "Show counts, ratings, growth, and statistics only with a real source; otherwise leave them out or mark [REAL DATA].",
+            dont: "Invent \"48.000+ users\", \"4,8★\", or \"+12%\".",
+            why: "Invented numbers are false claims, however polished the page.",
+            basis: `${RUN}: pen.dev landing without ryux`,
+            check: "review",
+            formerly: ["RX-C-03"],
+        },
+        {
+            num: 2,
+            title: "No invented people",
+            level: "required",
+            gate: "hard",
+            do: "Use testimonials, names, and faces only when they are real and consented.",
+            dont: "Make up testimonials, reviewers, or customer photos.",
+            why: "Fake people are fake endorsements.",
+            basis: "ryux anti-slop principle",
+            check: "review",
+            formerly: ["RX-C-04"],
+        },
+        {
+            num: 3,
+            title: "Placeholders look like placeholders",
+            level: "required",
+            gate: "hard",
+            do: "Mark temporary content clearly: [REAL DATA], [LOGO], \"Contoh data\".",
+            dont: "Ship placeholder copy or data disguised as final.",
+            why: "Disguised placeholders ship by accident.",
+            basis: "ryux anti-slop principle",
+            check: "audit_copy C-01",
+            formerly: ["RX-C-05"],
+        },
+        {
+            num: 4,
+            title: "No fake urgency",
+            level: "required",
+            gate: "hard",
+            do: "State a deadline or a quota only when it is real, as a plain fact.",
+            dont: "Write \"only 2 left\", \"offer ends tonight\", or fake countdowns with nothing behind them.",
+            why: "Manufactured pressure erodes trust once users notice.",
+            basis: `NNGroup credibility research; ${RUN}: WhatsApp promo`,
+            check: "review",
+            formerly: ["RX-N-09", "RX-C-10"],
+        },
+        {
+            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.",
+            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",
+            check: "review",
+            formerly: ["RX-H-08"],
+        },
+        {
+            num: 6,
+            title: "Complexity with a reason",
+            level: "required",
+            gate: "hard",
+            do: "Remove elements, options, states, code paths, abstractions, and dependencies that serve no stated need.",
+            dont: "Add settings, sections, abstractions, or packages \"for later\", or features because similar products have them.",
+            why: "Unneeded complexity costs every user and every future change.",
+            basis: "Nielsen heuristic 8; clean-code practice",
+            check: "review",
+            formerly: ["RX-K-05"],
+        },
+        {
+            num: 7,
+            title: "Claims match the evidence",
+            level: "required",
+            do: "Describe what was checked and how (\"keyboard and focus checked; no automated accessibility test was available\"). Call a reference an observed pattern, with where it was observed (\"seen in 4 screens across 3 apps\").",
+            dont: "Claim \"pixel perfect\", \"fully accessible\", \"production ready\", \"senior-level\", or \"UX optimized\" without evidence, or call a pattern \"best practice\" because real apps use it.",
+            why: "False confidence hides the work that is still needed.",
+            basis: "ryux delivery principle",
+            check: "review",
+        },
+        {
+            num: 8,
+            title: "Human designer notes",
+            level: "required",
+            do: "Have a person write the \"why it works / weaknesses\" judgment; an agent may summarize it.",
+            dont: "Let an agent author designer notes.",
+            why: "The human judgment is the point of the notes.",
+            basis: "ryux data principle",
+            check: "review",
+            formerly: ["RX-C-09"],
+        },
+        {
+            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",
+            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.",
+            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",
+            tradeoff: "takes a design decision, not only removals",
+            check: "swap test; review",
+        },
+    ]),
+];
+// Rules retired in rules 1.3: merged into another rule, or moved into a skill's guide as guidance.
+// "formerly" keeps the RX-1.x mapping for rules whose content now lives in a guide.
+export const RETIRED = {
+    "RX-PR-06": { to: "ryux-product guide" },
+    "RX-PR-07": { to: "ryux-product guide; RX-AS-06" },
+    "RX-PR-08": { to: "ryux-product guide" },
+    "RX-UX-03": { to: "ryux-ux guide" },
+    "RX-UX-04": { to: "ryux-ux guide" },
+    "RX-UX-05": { to: "RX-UX-02" },
+    "RX-UX-09": { to: "ryux-ux guide", formerly: ["RX-H-02"] },
+    "RX-IX-06": { to: "RX-A11Y-03" },
+    "RX-IX-07": { to: "ryux-interaction guide" },
+    "RX-IX-08": { to: "ryux-interaction guide", formerly: ["RX-H-07"] },
+    "RX-FM-02": { to: "ryux-forms guide" },
+    "RX-FM-04": { to: "ryux-forms guide", formerly: ["RX-N-04"] },
+    "RX-FM-07": { to: "ryux-forms guide" },
+    "RX-EC-04": { to: "RX-EC-03" },
+    "RX-EC-05": { to: "ryux-edge-cases guide" },
+    "RX-EC-08": { to: "RX-EC-07" },
+    "RX-CD-06": { to: "RX-CD-03" },
+    "RX-CD-07": { to: "ryux-content guide", formerly: ["RX-H-10"] },
+    "RX-CD-08": { to: "ryux-content guide" },
+    "RX-UI-02": { to: "RX-AS-05" },
+    "RX-UI-06": { to: "ryux-ui guide" },
+    "RX-UI-08": { to: "ryux-ui guide" },
+    "RX-DS-04": { to: "RX-DS-02" },
+    "RX-A11Y-05": { to: "RX-A11Y-04" },
+    "RX-A11Y-09": { to: "ryux-accessibility guide" },
+    "RX-RD-05": { to: "RX-RD-04" },
+    "RX-FE-03": { to: "RX-A11Y-04" },
+    "RX-FE-04": { to: "ryux-frontend guide" },
+    "RX-FE-08": { to: "RX-FE-07" },
+    "RX-FE-09": { to: "RX-FE-07" },
+    "RX-FE-10": { to: "RX-AS-06" },
+    "RX-FE-11": { to: "ryux-frontend guide" },
+    "RX-QA-02": { to: "RX-QA-01" },
+    "RX-QA-05": { to: "RX-QA-01" },
+    "RX-QA-07": { to: "RX-QA-06" },
+};
+export const PURPOSE_GATES = [
+    { pattern: "Cards", acceptableWhen: "they group related content or separate items the user compares or acts on individually" },
+    { pattern: "Gradients", acceptableWhen: "they carry the brand, show emphasis, or encode a value (a scale or progress)" },
+    { pattern: "Illustrations", acceptableWhen: "they explain a concept, an empty state, or a step that words alone do not" },
+    { pattern: "Decorative icons", acceptableWhen: "they speed recognition of a repeated item or action, next to a text label" },
+    { pattern: "Pills", acceptableWhen: "they show a filter, a selectable option, or a short status" },
+    { pattern: "Badges", acceptableWhen: "they show a count or status the user acts on" },
+    { pattern: "Shadows", acceptableWhen: "they show elevation that matters: an overlay, a draggable or floating element" },
+    { pattern: "Large display type", acceptableWhen: "it carries the single most important message of a page" },
+    { pattern: "Animation", acceptableWhen: "it communicates state, continuity, feedback, or spatial relationships" },
+    { pattern: "Unusual layouts", acceptableWhen: "the content or task genuinely differs from standard patterns" },
+    { pattern: "Generous whitespace", acceptableWhen: "it separates groups or slows a high-stakes decision, not when it hides thin content" },
+    { pattern: "Borders", acceptableWhen: "they separate regions that spacing alone cannot" },
+    { pattern: "Typeface choice", acceptableWhen: "it is chosen for the product's character and legibility, not because it is the model's usual pick" },
+    { pattern: "Background patterns (grid, dots, noise)", acceptableWhen: "they carry the identity or support the content, such as a canvas for a design tool" },
+    { pattern: "Arrows on buttons", acceptableWhen: "the action moves the user somewhere (next step, another page), not on every button" },
+    { pattern: "Glass and blur", acceptableWhen: "one surface needs to show what is behind it (an overlay over content), and text on it keeps its contrast" },
+    { pattern: "Glow", acceptableWhen: "it marks the one element that needs attention, not every card, button, and icon" },
+    { pattern: "Rounded containers", acceptableWhen: "the rounding follows the system radius and the container groups something" },
+];
+// Brief item: each hard-gate failure mapped to the rule that enforces it.
+export const HARD_GATES = [
+    { item: "Fake data or fake metrics", rules: ["RX-AS-01"] },
+    { item: "Fake testimonials or people", rules: ["RX-AS-02"] },
+    { item: "Invented business rules or product requirements", rules: ["RX-PR-02", "RX-FE-02"] },
+    { item: "Placeholder copy shipped as final", rules: ["RX-AS-03"] },
+    { item: "Fake urgency or scarcity", rules: ["RX-AS-04"] },
+    { item: "Missing critical states", rules: ["RX-EC-01"] },
+    { item: "Broken responsive behavior", rules: ["RX-RD-01"] },
+    { item: "Accessibility failures", rules: ["RX-A11Y-01", "RX-A11Y-02", "RX-A11Y-03", "RX-A11Y-04"] },
+    { item: "Unclear goal or competing actions", rules: ["RX-PR-03"] },
+    { item: "Unexplained interaction behavior", rules: ["RX-IX-01", "RX-IX-12"] },
+    { item: "Duplicate components", rules: ["RX-DS-01"] },
+    { item: "Unnecessary complexity", rules: ["RX-AS-06"] },
+];
+// Brief item: consistency that must hold across the product.
+export const QUALITY_LOCKS = [
+    { item: "Spacing", rules: ["RX-UI-03", "RX-DS-03"] },
+    { item: "Typography", rules: ["RX-UI-03", "RX-DS-03"] },
+    { item: "Color roles", rules: ["RX-UI-04"] },
+    { item: "Terminology", rules: ["RX-CD-05"] },
+    { item: "Components", rules: ["RX-DS-02"] },
+    { item: "Interaction patterns and states", rules: ["RX-DS-02"] },
+    { item: "Responsive behavior", rules: ["RX-RD-06"] },
+    { item: "Visual hierarchy", rules: ["RX-UI-01"] },
+    { item: "Radius", rules: ["RX-UI-03", "RX-DS-03"] },
+];
+// Contextual activation: load only what the task needs (core is always loaded).
+export const ACTIVATION = [
+    { task: "UI implementation", skills: ["product", "ux", "ui", "design-system", "frontend", "visual-qa", "anti-slop"] },
+    { task: "Form implementation", skills: ["product", "ux", "forms", "interaction", "accessibility", "edge-cases", "content"] },
+    { task: "Mobile UI", skills: ["ux", "ui", "responsive", "accessibility", "anti-slop"] },
+    { task: "Checkout or payment", skills: ["product", "interaction", "forms", "content", "edge-cases"] },
+    { task: "Data-heavy view (list, table, dashboard)", skills: ["ux", "edge-cases", "responsive", "design-system", "frontend"] },
+    { task: "Frontend logic or utilities (formatting, state, data shown to users)", skills: ["frontend", "content", "edge-cases"] },
+    { task: "Copy only (UI text, chat, announcements)", skills: ["content", "anti-slop"] },
+    { task: "Visual refinement", skills: ["ui", "design-system", "visual-qa", "anti-slop"] },
+];
+export const ALL_SKILL_IDS = SKILLS.map((s) => s.id);
+export const ALL_GROUP_IDS = GROUPS.map((g) => g.id);
+// RYUX Analyze and RYUX Critique are capability skills (playbooks, no generated rules); they install
+// with the "analyze" and "critique" groups.
+export const CAPABILITY_SKILL_IDS = ["analyze", "critique"];
+/** Every installable skill id besides ryux-core: knowledge skills in workflow order, then capabilities. */
+export const ALL_INSTALLABLE_IDS = [...SKILLS.map((s) => s.id), ...CAPABILITY_SKILL_IDS];
+export const skillsInGroups = (groups) => [
+    ...SKILLS.filter((s) => groups.includes(s.group)).map((s) => s.id),
+    ...CAPABILITY_SKILL_IDS.filter((id) => groups.includes(id)),
+];
+// Install presets by who uses RYUX. Designers analyze, critique, and QA; AI coders build and QA.
+export const PRESETS = {
+    designer: { label: "Designer (Analyze, Critique, QA)", groups: ["analyze", "critique", "quality", "ux", "ui"] },
+    builder: { label: "AI coder (Build, QA, Critique)", groups: ["foundation", "ux", "ui", "engineering", "quality", "critique"] },
+    all: { label: "Both", groups: ["foundation", "ux", "ui", "engineering", "quality", "analyze", "critique"] },
+};
+// Where each agent reads skills (SKILL.md folders). Verified against each agent's docs and the
+// conventions used by other skill installers. "pointer" is the instruction file that gets a short
+// marked block telling the agent RYUX is installed (project installs only).
+export const LEVEL_LABEL = {
+    required: "Required",
+    preferred: "Preferred",
+    contextual: "Contextual",
+};