# RapidAir Reference Playbook

This is the reference example for turning a UX audit into farmable design work. RapidAir is useful because it exercised the whole path end to end:

```text
run code -> audit -> code -> Figma -> Figma Make -> React demo -> Vercel
```

The reusable `/ux-audit` skill lives in `rolemodel-design-audit`. This file captures how the workflow behaved on a real project so future audits can copy the good parts, avoid the brittle parts, and produce stronger downstream work.

## 1. Run the product code

The work began in the running product, not in a document. We traced the main journey, watched the interaction flow in context, and used that first pass to decide which parts of the experience deserved deeper attention.

That gave the audit two useful artifacts before any report existed: a working mental model of the product and an initial map of the areas worth auditing more deeply. Starting there kept later recommendations tied to real friction instead of isolated screenshots.

The weak point was practical rather than conceptual. Local environment assumptions can slow the first hour when the app is not already easy to boot, and useful observations disappear if no one records the critical journey. Every audit should begin with the product running and one documented pass through the primary workflow.

## 2. Audit the experience

The audit used consistent lenses across usability, accessibility, onboarding, consistency, and visual systems, but the real breakthrough came from how the findings were shaped. Instead of dumping defects into a list, the work separated internal notes from partner-facing framing and organized the story as Then / Now / Next.

That structure changed the feel of the deliverable. The strongest message was not "here are the bugs." It was that the product already had good bones, and the surrounding experience could now catch up to the engineering. Thematic lenses made that argument easier to absorb than severity sorting alone.

The first run also showed where discipline matters. It is easy to create sections before there is a real design response, and the language drifted toward hedging until it was tightened into recommendations. The partner report should read like a magazine, not a bug report. Only elevate findings that can support a persuasive story and, when possible, a visible direction.

## 3. Turn findings into a report artifact

**What happened**
- Built the report in code as a branded, reusable slide/document artifact.
- Refined the content until the deck held together visually and rhetorically.

**Artifacts produced**
- Static HTML report bundle in this folder
- Reusable branded assets, local fonts, and audit components

**What worked well**
- Coding the report made the output reproducible and easier to improve systematically.
- A consistent structure across sections made later export work far more predictable.

**Where it broke down / needed manual cleanup**
- Some slides initially included placeholders for ideas that had no supporting design yet.
- Low-opacity text, absolute-positioned children, and inconsistent section structure created downstream Figma cleanup.

**Repeatable rule**
- Before handoff, verify the report has only real sections, readable text, stable vertical rhythm, and no layout tricks that make export fragile.

## 4. Move the report into Figma

**What happened**
- Imported the coded artifact into Figma so the report could become a design object, not just a web page.
- Used Figma as the review surface for layout, hierarchy, and presentation quality.

**Artifacts produced**
- Figma-ready report frames
- Tokenized color direction for the design system conversation

**What worked well**
- Figma made the work easier to review with designers and gave the audit a more natural bridge into future product design.
- Keeping sections structurally consistent reduced import weirdness.

**Where it broke down / needed manual cleanup**
- Export failed when the local server root was assumed incorrectly.
- The import exposed layout shortcuts that looked acceptable in-browser but were brittle as design artifacts.

**Repeatable rule**
- Confirm the server root before export, and design the coded report as if it will later become editable layout in Figma.

## 5. Use Figma Make to explore the better future

**What happened**
- Turned the strongest recommendations into visible interface directions rather than leaving them abstract.
- Used design exploration to test whether the audit pointed toward coherent product change.

**Artifacts produced**
- Proposed interface concepts for the highest-value opportunities

**What worked well**
- Concrete concepts made the audit easier to discuss and made the opportunities feel actionable.
- The work shifted from critique to momentum: “here is what better could look like.”

**Where it broke down / needed manual cleanup**
- Concept generation is only useful when the audit has already chosen the right problems.
- More concepts are not automatically better; excess scope weakens the deck.

**Repeatable rule**
- Design only the opportunities that strengthen the story. Do not generate screens just to fill space.

## 6. Build the React demo

**What happened**
- Converted the clearest design direction into an interactive React demo so people could feel the improved workflow, not merely inspect mockups.

**Artifacts produced**
- Interactive demo app in the sibling RapidAir demo repository

**What worked well**
- The demo made the future state legible to non-designers and created a stronger bridge from audit to implementation.
- It let the team validate motion, sequencing, and interaction details that static screens cannot prove.

**Where it broke down / needed manual cleanup**
- The demo has its own lifecycle, dependencies, and local changes, so it should remain a separate repo/submodule rather than being absorbed into the audit catalog.

**Repeatable rule**
- Use a coded demo when interaction is the argument. Keep it separate from the static report when it becomes a real app with its own history.

## 7. Publish to Vercel

**What happened**
- Published the static report and interactive demo so they could be shared, reviewed, and revisited without local setup.

**Artifacts produced**
- Shareable report deployment
- Shareable interactive demo deployment

**What worked well**
- Vercel turned the audit from a local artifact into something that could circulate and keep working after the meeting ended.
- Publishing forced the folder structure and asset strategy to become real instead of theoretical.

**Where it broke down / needed manual cleanup**
- Publication gets messy when report assets, demos, and reusable workflow code are all mixed together.

**Repeatable rule**
- Publish from a clean static bundle, keep reusable skill logic elsewhere, and keep large demos in their own repositories.

## The repeatable version

For future audit-farming work, the minimum durable pipeline is:

1. Run the product and document the primary journey.
2. Audit the experience through consistent lenses.
3. Convert the findings into a confident partner narrative.
4. Produce only the design directions the story truly needs.
5. Use Figma for reviewable design artifacts.
6. Build a React demo only when interaction itself needs to be proven.
7. Publish the final outputs so the work is easy to review and easy to reuse.

## What this example established

- Audits are more valuable when they create a path forward, not just a list of defects.
- The report, the design concepts, and the prototype are one pipeline with different jobs.
- A useful farming system needs both repeatability and judgment: the process should be stable, but the amount of design work should scale with what the product actually needs.