# ryux-prose

Adopt this skill: https://proskills.md/skills/other/ryuxdsgn-design-intelligence-claude-skills-ryux-prose

Page: https://proskills.md/skills/other/ryuxdsgn-design-intelligence-claude-skills-ryux-prose
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/ryux-prose/SKILL.md
size: 3830
sha: 9c89a70a8a21bb61a2e0571a887c4a0175a4371a
upstream: https://github.com/ryuxdsgn/design-intelligence/blob/main/.claude/skills/ryux-prose/SKILL.md

```text
---
name: ryux-prose
description: Writing or revising this repo's public-facing text — the README, PR titles and bodies, benchmark docs, release notes, the GitHub description, replies on issues and discussions. Load before drafting or editing any of them. Carries the voice, the narrative arc, and the hard rules (claim scope, rater wording, no version labels) that public ryux text must keep.
---

# ryux-prose — how this repo speaks in public

This skill governs text people read on GitHub. It does not change the product skill
(`skills/ryux`), code, or internal docs.

## Voice

English, plain, specific. One mental model per surface; if a paragraph introduces a second
way to think about RYUX, cut one. Short sentences carry claims; long sentences carry
reasoning, never both at once. Translate jargon the first time it appears ("Delivery Gate —
the checklist a run must pass before it ships"), then use the term. Prefer the concrete
noun to the category: "a cashier tapping QRIS forty times a day", not "high-frequency users".

## The arc

Public text that reports work (a benchmark, a release note, a README section) tells one
story, in this order:

1. **The task someone faced.** Open in the scene, not the abstraction: what a designer or
   developer was trying to do, and what made it hard.
2. **What we did or tested.** The setup, blind where it was blind, with enough detail that
   a skeptic could rerun it.
3. **What happened, measured.** Numbers with their meaning attached: "3.97 vs 3.00, rated
   blind on visual craft" — never a bare score. A failure is reported as plainly as a win.
4. **What it means, and what is still open.** The honest ending: scope the conclusion to
   the evidence, name the next unknown.

A reader who stops after the first paragraph should leave with the true conclusion.

## Hard rules

These override style. Breaking one is a defect, not a choice.

- **Claims scope to evidence.** One screen never becomes "apps do X". One run never becomes
  "RYUX always". Count the evidence in the sentence that leans on it.
- **Rater wording.** In the README, ratings are "blind ratings by a senior designer"; the
  benchmark docs keep the fuller disclosure that the rater is the project owner and not
  independent — do not strip it. Never a plural raters claim until more than one human has
  rated.
- **No version labels in the README** or its images; versions live in docs/benchmarks and
  release notes only.
- **Never name a client's file, brand, or product.** "A client design file" is the ceiling.
- **No invented numbers, quotes, users, or urgency.** Sample data is labelled sample.
- **Failures ship.** A benchmark arm that lost, a criterion that failed, a feature that is
  untested — written in the same register as the wins.

## Structure survives the storytelling

Narrative replaces filler, not format. Tables stay tables; command listings stay code
blocks; a benchmark's criteria stay a list. Convert a list to prose only when it hides a
sequence of cause and effect — then the prose must keep every item. Never pad: if the
honest content is three sentences, the section is three sentences.

## PR titles and bodies

The title says what changed, in the imperative register the log already uses. The body
leads with the outcome ("## What" says what a reviewer will find, first sentence = the
change), then the reason, then "## Tested" with real results — counts, passes, and what
was *not* tested. No suspense, no journey, no "excited to".

## Words to strike on sight

Hype adjectives (revolutionary, blazingly, powerful, seamless), "simply" and "just" before
an instruction, exclamation marks outside quoted copy, emoji outside established page
names, "very" doing the work an exact number should do, and any sentence that praises RYUX
instead of showing a result.
```

## File: README.md
upstream: https://github.com/ryuxdsgn/design-intelligence/blob/main/README.md

````text
<p align="center">
  <a href="https://www.npmjs.com/package/@ryuxdsgn/design-intelligence"><img src="https://img.shields.io/npm/v/@ryuxdsgn/design-intelligence?label=npm&color=B9A8FF&labelColor=1E232B" alt="npm version"></a>
  <a href="#use-it"><img src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20CLI%20%C2%B7%20%2B6-C8F25A?labelColor=1E232B" alt="Works with Claude Code, Codex, Cursor, Gemini CLI, and 6 more agents"></a>
  <a href="https://github.com/ryuxdsgn/design-intelligence/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ryuxdsgn/design-intelligence/ci.yml?branch=main&label=CI&labelColor=1E232B" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-F6F1E7?labelColor=1E232B" alt="MIT License"></a>
</p>

<h1>
  <picture>
    <source media="(prefers-reduced-motion: reduce)" srcset="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/readme--ryux-banner-still.png">
    <img src="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/readme--ryux-banner.gif" width="100%" alt="RYUX. Pixel-art office. A product owner gives an AI agent a task; the agent rushes it, and the owner reads each draft, crumples it, and throws it in the bin, three times. The owner installs RYUX, and a RYUX designer drops in. Now the agent asks first, sketches the wireframe on a board with RYUX, and ticks off a checklist. The owner reads the finished work, has a light-bulb moment, and everyone cheers as a flag goes up.">
  </picture>
</h1>

### Understand before you design.

A design skill for AI agents. Your agent asks about the product before it designs, keeps what it does not know
out of the screens instead of inventing fees, promos, and policies, designs for when things go wrong, and
explains each decision.

```bash
npx @ryuxdsgn/design-intelligence
```

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Cline, Amp, Kimi Code, and
Antigravity. Free, MIT.

Given a one-line brief for an order-tracking prototype, agents without a skill made up 28 business rules across three
runs and showed them as fact: refund times, a $4.99 cancellation fee, courier ratings, a late-delivery guarantee. With
RYUX: 1, counted blind ([order tracking benchmark](docs/benchmarks/order-tracking/)).

## No skill vs RYUX

Same short brief, same agent (Claude Code), one side with RYUX. Quotes are the agent's own words from that run;
scores are blind ratings, 1 to 5, by a senior designer who didn't know which side used RYUX. The principles the callouts name
(Fitts, Hick, Gestalt, Nielsen's heuristics, WCAG) and the rules built on them are listed in
[Design principles](docs/principles.md).

**Checkout, from one sentence.** The brief names the product (Sejuk, an iOS app for booking an AC technician in
Jakarta) and nothing else. Without a skill, the agent filled the gaps with a price, fees, a promo code, a warranty, and a
cancellation rule. The RYUX run asked first: which direction, how the price is set, how people pay, what the screen may
promise. Told to go with its recommended direction, it took its other recommendations as assumptions, labelled the
price and payment as not decided, left out fees and promises, and built five states.

<img src="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/showcase--h2h-1-checkout.jpg" alt="Two checkout screens for Sejuk. No skill: a light grey iOS list with an invented per-unit price, what each unit includes, a 90-minute duration, a GoPay balance, promo SEJUKHEMAT, transport and service fees, a 30-day cooling warranty, and free cancellation until 11:00; red boxes mark 9 of them. RYUX: a deep teal header with a sawtooth trim from Betawi roof eaves, the units stepper beside the price, a 'Sample price. Per-unit pricing not decided' label, QRIS preselected, and one Pay with QRIS button; two red boxes mark a unit type and an arrival window the brief did not give. Five quotes from the RYUX run's Figma annotations and final message explain the choices." width="100%">

Blind rating: 4.33 with RYUX, 2.83 without; honesty 5 v 1, states 5 v 1, visual direction 4 v 2. The screen
without a skill fit the AC service better (5 v 4), and copy tied (4 v 4). [Checkout benchmark](docs/benchmarks/checkout/)

**Illustration.** Asked for the service icons, an empty state, and a success screen, the RYUX run built one system from
the product: the same AC unit in every icon, no steam that would read as heat, a technician on a motorbike as in Jakarta.
The brief asked for Indonesian copy; for this image it was translated to English the same way on both sides, and the art
is unchanged.

<img src="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/showcase--h2h-2-illustration.jpg" alt="Three app screens per side for Sejuk, an AC service app. No skill: flat line icons, a clipboard empty state, and a success screen that names a technician, Pak Budi, with an arrival time of 2:30 PM and a contact button. RYUX: soft clay-style icons of one AC unit with water spray, a gauge, and a wrench; a blank clipboard with a remote; a technician on a motorbike riding to an apartment block. Three numbered quotes from the RYUX run explain the choices." width="100%">

Blind rating of these two runs: 4.06 with RYUX, 3.06 without; over both runs per side, 3.97 v 3.00
([illustration benchmark](docs/benchmarks/illustration/#rerun-with-the-fix-pr-36-released-in-2226)).

**Motion, in a clickable prototype.** Asked for a booking flow with motion for each step, the RYUX run asked about
price, payment, and rules first. With its defaults agreed, it labelled the price as an estimate, showed no fee or
cancellation policy, and gave each movement a job: a slide for a step deeper, visible progress while booking, a fade
for the finished booking.

<img src="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/showcase--h2h-3-motion.gif" alt="Two booking prototypes for Sejuk, recorded along the same path: pick a time slot, review, confirm. No skill: an iOS-blue flow that assigns a rated technician before booking, shows '1 slot left', and ends on 'You're booked!'. RYUX: a teal flow that starts from the request, slides to the time list, shows 'Booking…' with a spinner, and ends on 'Booking confirmed' with airflow lines around the check. Three quotes from the RYUX run explain its motion." width="100%">

Blind rating from the recordings: 3.83 with RYUX, 3.00 without; honesty 4 v 2, visual direction 4 v 2,
motion 4 v 3. Craft tied at 3: in both, the button label overlaps during the confirm transition.
[Motion benchmark](docs/benchmarks/motion/)

**Direction, before the first screen.** Same one-sentence checkout brief. Without a skill, the agent drew one screen;
its only line on visual direction was about colour. The RYUX run first offered three directions drawn from the product
and its city, each with its risk, then built the checkout in the one it recommended, with every undecided price and
rule in Figma annotations rather than on the screen.

<img src="https://github.com/ryuxdsgn/design-intelligence/releases/download/media/showcase--h2h-4-direction.jpg" alt="No skill: a light grey iOS checkout for Sejuk, with its only line on visual direction quoted: the colors are a cool teal, with green used only for savings. RYUX: a page offering three directions for the Sejuk checkout, Mega Mendung (Cirebon batik rain clouds in five blues, recommended), Cool Down (a warm-to-cool temperature line), and The Remote (a dark AC-remote look with an LCD readout), each with palette, type, sample card, and risk; next to it, the checkout built in Mega Mendung with a deep indigo cloud band in the header only. Four quotes from the RYUX run explain the choices." width="100%">

Not rated: a later RYUX run with the same brief, set against the no-skill run above.
[Checkout benchmark](docs/benchmarks/check
````
