The four-pillar roadmap: library, templates, experience metrics, versions, walkthroughs, studio, and the experiment

.claude/skills/uxcli/SKILL.md

@@ -32,6 +32,8 @@ Use this bounded path for ordinary UI work. Read a reference only where a step n
    needs, the commitments already signed over it, and what the last run saw. Read it top to bottom.
    If there is no journey or no understanding on disk, the card says so; go to `references/understand.md`
    and `references/journey.md` before writing any UI.
+   If you do not know the product's field from sources, research it first: `npx -y @junixlabs/uxcli
+   template` names a starting point for the kind of product, and `references/research.md` is how.
 3. **Draw before you build.** First pick the lens for what the person does on this screen —
    `marketing`, `content`, `data`, `workspace`, `shop` or `transaction` — and read its checklist,
    `lenses/<kind>.md` in this skill: named designers' rules, each with its source and what to look
@@ -60,6 +62,9 @@ Use this bounded path for ordinary UI work. Read a reference only where a step n
    Read each card. A `fail` names the element, the place, the rule and how to check it yourself; fix
    that element and run again. Never edit a journey, a commitment or a probe to make a run pass.
    Then review the built screen through its lens, the same way, and `uxcli review check`.
+   Then read what the person goes through: `npx -y @junixlabs/uxcli experience --page` — steps, clicks,
+   typing, scrolls, waits and a keystroke-level estimate per journey, each finding pinned on the step's
+   screenshot, and what moved since the walk before. Report each finding in its words; they never block.
 6. **Say done only at exit 0**, and say what was measured. Anything else, say what stands in the way.
    `references/before-done.md` is the full sequence and the list of what exit 0 does not cover.
 
@@ -96,6 +101,9 @@ Before you design or change a screen, you read `uxcli context show` for the jour
 | `references/journey.md` | the card says no journey, or a flow has changed shape: states as signals, hooks, workflows |
 | `references/mockups.md` | a screen the journey names has no mockup or no pick: variants, hooks, `pick.json` |
 | `references/understand.md` | the card says no understanding, or an insight the screen leans on is missing or a hypothesis |
+| `references/versions.md` | a walk showed something worth changing: naming versions, a redesign proposal with evidence, comparing two versions |
+| `references/research.md` | you do not know the product's field from sources yet: where to look, what to come back with, how to write it down |
+| `templates/<id>.md` | the product is a kind uxcli has a template for — `workspace`, `shop`, `landing`: screens and their lens, journeys to walk, what to research |
 | `lenses/<kind>.md` | before you draw or change a screen: the checklist for its kind of UI — `marketing`, `content`, `data`, `workspace`, `shop`, `transaction` |
 | `references/lenses.md` | how to pick the lens, answer it, write the review, and pass `review check` |
 | `references/principles.md` | a verdict is `not-committed` and the project should decide; proposing a commitment |

.claude/skills/uxcli/references/research.md

@@ -0,0 +1,61 @@
+# research — learning the domain before you design for it
+
+Read when: you are about to design for a product whose field you do not already know from sources —
+its vocabulary, its rules, what its people do all day and what goes wrong for them. A screen designed
+from what a model assumes about a field looks plausible and fails the person who works in it. This is
+how you find out first, and how you write down what you found so the next agent does not have to.
+
+## Start from the kind of product
+
+```bash
+npx -y @junixlabs/uxcli template                 # workspace, shop, landing
+npx -y @junixlabs/uxcli template show <id>       # screens and their lens, journeys to walk, what to research
+npx -y @junixlabs/uxcli template apply <id>      # the actor questions, written as unknowns (creates only)
+```
+
+A template is where research starts, not what it found: every line about people in it is a question.
+If no template fits, take the closest one's questions as a checklist and say which you skipped.
+
+## Where to look, in order of how much it can carry
+
+| Rank | Source | What it can tell you | `evidence` when it becomes a viewpoint or an insight |
+|---|---|---|---|
+| 1 | The project's own data: analytics, support tickets, interview notes, sales calls, the running product | What these people actually do and where they get stuck | insight `source.type` = analytics, interview, ticket, run |
+| 2 | Regulations and standards for the field: laws, WCAG, industry rules | What must be true whatever anyone prefers | `author`, with the clause quoted |
+| 3 | Published research with a method: Baymard, NN/g studies, peer-reviewed HCI | What holds across many products of this kind, and how strongly | `study` |
+| 4 | Public design systems and style guides: GOV.UK, Carbon, Primer, Polaris, USWDS | Patterns that were tested and are maintained, with usage rules | `author` |
+| 5 | Products people in the field already use, and their reviews | The conventions they expect and the complaints they repeat | `secondary`, the review quoted |
+| 6 | Community practice: articles, talks, threads | Ideas worth testing | `folklore` — never more than a hypothesis |
+
+The lenses (`lenses/<kind>.md`) and the topic pools behind them are rank 3 and 4, already fetched and
+quoted. Read them for the kind of screen; research is for what they cannot know — this field.
+
+## What to come back with
+
+1. **The field's words.** The terms people in the field use for its records, states and outcomes, each
+   with where you saw it. Labels, headings and messages use these words, not the database's.
+2. **The rules.** What a regulation or standard requires of this kind of screen (consent, retention,
+   disclosure, accessibility), quoted with its clause.
+3. **The work.** Which task is repeated most, how often, under what pressure, on which device — from
+   rank 1 sources if the project has them; otherwise it stays an unknown.
+4. **The conventions.** How two or three products the people already use handle the same task, and what
+   their reviews complain about. A convention people already know is a reason, not a rule.
+5. **The open questions.** Everything you could not settle, as questions in the actor's `unknowns[]`.
+
+## How to write it down
+
+- A finding about people or about this field is an insight (`references/understand.md`): one claim,
+  its `source`, the exact numbers or words in `evidence[]`, and what would prove it wrong.
+- A finding about how screens of this kind should work is a candidate viewpoint: who said it, where,
+  their words. Bring it to the person running you; uxcli's pools only carry what someone can cite.
+- Fetch what you cite in this session and quote it exactly. A page you could not open is not a source:
+  say so and leave the question open.
+- Then design: `uxcli context show <journey>`, the lens for each screen the template names, and the
+  mockups (`references/mockups.md`).
+
+## What you do not do
+
+- Fill an unknown from what you expect the field to be like. An unanswered question stays a question.
+- Treat a competitor's screen as evidence that its pattern works. It is evidence that it exists.
+- Raise community advice above a hypothesis because several people repeat it.
+- Quote from memory. If the words are not in something you fetched, they are not a quote.

.claude/skills/uxcli/references/versions.md

@@ -0,0 +1,43 @@
+# versions — proposing a better version, and showing it is better
+
+Read when: a walk of a journey showed something worth changing, or you are about to change a screen
+that a journey goes through. A version names one walk so it is kept; a redesign proposal says what to
+change and points at the evidence; the next version is compared with the last, step by step.
+
+## The loop
+
+```bash
+npx -y @junixlabs/uxcli run .uxcli/journeys/<id>.json             # walk it
+npx -y @junixlabs/uxcli experience --page                          # what the person goes through, pinned on screenshots
+npx -y @junixlabs/uxcli version save <id> v1 --note="as it is"     # name that walk; it is kept against pruning
+# write the redesign proposal (below); a person approves it; draw and build the change
+npx -y @junixlabs/uxcli run .uxcli/journeys/<id>.json
+npx -y @junixlabs/uxcli version save <id> v2 --note="call button above the fold" --proposal=proposals/P-0012.json
+npx -y @junixlabs/uxcli experience --journey=<id> --from=v1 --to=v2 --page   # both pictures of every step, what moved
+```
+
+## A redesign proposal
+
+`.uxcli/proposals/P-xxxx.json` with `"kind": "redesign"`, `target` naming the journey and step
+(`journeys/<id>.json#<step>`), `statement` saying what changes for the person, and `evidence[]` citing
+what the walk showed — one entry per finding it answers:
+
+```json
+{ "run": "runs/R-…", "check": "experience.reach", "observed": "[data-uxcli=call-action] 2 scrolls away at 390x844", "what": "the call button is below the fold on a phone" }
+```
+
+A proposal with no evidence is an opinion; cite the walk, the lens viewpoint, or the insight it rests
+on. A person approves it before it is built. Name the version that answers it with `--proposal`.
+
+## Saying it is better
+
+Report the comparison in its own words: the steps, typing, scrolls and estimate that moved, the
+findings that went away and the ones that appeared. A version with fewer findings and a higher
+estimate is not simply better; say both. The metrics are findings, not verdicts, and nobody was
+watched: a better walk is evidence for the change, not proof that people prefer it.
+
+## What you do not do
+
+- Rewrite or delete a version. A new walk gets a new name.
+- Save a version of a walk you did not make on the final files.
+- Call a change better without the comparison, or show only the numbers that improved.

.claude/skills/uxcli/templates/landing.md

@@ -0,0 +1,83 @@
+# Product site — the `landing` template
+
+Marketing sites for a product or service: a visitor decides in minutes whether to sign up, buy or get in touch.
+
+A template is where research starts, not what it found. Nothing below is a fact about this product's users: the screens and journeys are what products of this kind usually have, and every question is yours to answer from a source before it becomes an insight. `uxcli template apply landing` writes the actor questions into `.uxcli/understanding/actors/`; `references/research.md` in this skill is how to answer them.
+
+## Who uses it
+
+### `evaluating_visitor`
+
+Someone who arrived with a problem and is deciding whether this product solves it.
+
+- What problem were they trying to solve when they arrived, in their own words?
+- Where did they come from (search, a recommendation, an ad, a comparison article)?
+- What do they need to see before they believe it works for someone like them?
+- What stops them from signing up today: price, effort, risk, someone else's approval?
+- Who else is involved in the decision, and what will that person ask?
+
+### `returning_buyer`
+
+Someone who has seen the site before and comes back to compare plans or to buy.
+
+- What did they come back to check?
+- Which plan details decide between two plans for them?
+- What would make them contact sales instead of signing up themselves?
+
+## Screens, and the lens each is read against
+
+| Screen | Lens | What the person does there |
+|---|---|---|
+| Home (`home`) | `marketing` | Understands what this is, who it is for and what to do next. |
+| Feature or use-case page (`feature`) | `marketing` | Sees how the product handles their specific case. |
+| Pricing (`pricing`) | `marketing` | Works out what it will cost them and which plan fits. |
+| Sign up (`sign-up`) | `transaction` | Creates an account with as little as is needed to start. |
+| Contact sales (`contact`) | `transaction` | Asks a question and knows when they will hear back. |
+| Docs or help (`docs`) | `content` | Checks a detail before committing. |
+
+## Journeys to walk first
+
+### `understand-and-sign-up` — Understand the product and sign up
+
+Actor `evaluating_visitor`, through: `home` → `feature` → `sign-up`.
+
+Watch when you walk it:
+
+- What the product is and who it is for is readable without scrolling at a phone viewport.
+- Each view has one primary call to action, and it says what happens when pressed.
+- Count the sign-up fields; each must be needed to start.
+
+### `compare-plans` — Choose a plan
+
+Actor `returning_buyer`, through: `home` → `pricing` → `sign-up`.
+
+Watch when you walk it:
+
+- Prices state the period, the currency and whether tax is included.
+- The differences between plans can be read without hovering or opening anything.
+- The plan chosen on pricing is the plan selected in sign-up.
+
+### `ask-a-question` — Ask sales a question
+
+Actor `returning_buyer`, through: `pricing` → `contact`.
+
+Watch when you walk it:
+
+- The contact form asks only what sales needs to reply.
+- After sending, the page says what happens next and when.
+- An error keeps the message the visitor typed.
+
+## What to research about the domain
+
+- Which words do people in this market use for the problem, as opposed to the product's own feature names?
+- Which competitors do visitors compare against, and how do those sites explain price and value?
+- What proof does this market trust: customer logos, numbers, reviews, certifications, a free trial?
+- Which regulations apply to sign-up and marketing consent here?
+- What questions do sales or support hear most from people who have not bought yet?
+
+## Where research starts
+
+- [Nielsen Norman Group — 10 usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) — The baseline vocabulary for reviewing any screen.
+- [GOV.UK — content design: writing for GOV.UK](https://www.gov.uk/guidance/content-design/writing-for-gov-uk) — Researched guidance on plain language and how people read on screens.
+- [Baymard Institute — research](https://baymard.com/research) — Research on account creation, form length and trust signals before purchase.
+- [Deceptive Patterns (Harry Brignull)](https://www.deceptive.design/) — The catalogue of patterns that win a sign-up and lose the customer.

.claude/skills/uxcli/templates/shop.md

@@ -0,0 +1,85 @@
+# Online shop — the `shop` template
+
+E-commerce and marketplaces: people browse, compare, buy, and come back for their order.
+
+A template is where research starts, not what it found. Nothing below is a fact about this product's users: the screens and journeys are what products of this kind usually have, and every question is yours to answer from a source before it becomes an insight. `uxcli template apply shop` writes the actor questions into `.uxcli/understanding/actors/`; `references/research.md` in this skill is how to answer them.
+
+## Who uses it
+
+### `first_time_shopper`
+
+Someone who arrived from search or an ad and has never bought here.
+
+- What were they looking for when they arrived, in their own words?
+- What do they need to know before trusting this shop with a payment?
+- Which device do they buy on, and do they start on one device and finish on another?
+- What costs or conditions would make them abandon at checkout (delivery price, delivery date, returns)?
+- How do they compare products: by price, by a spec, by reviews, by photos?
+
+### `returning_customer`
+
+Someone who has bought before and comes back to buy again or to check an order.
+
+- Why do they come back: to reorder, to track, to return?
+- Do they expect to be signed in, and what happens if they are not?
+- What would they need to see to resolve an order problem without contacting support?
+
+## Screens, and the lens each is read against
+
+| Screen | Lens | What the person does there |
+|---|---|---|
+| Catalogue or category (`catalogue`) | `shop` | Browses a range and narrows it down. |
+| Search results (`search-results`) | `shop` | Finds the product they have in mind, or a close alternative. |
+| Product page (`product`) | `shop` | Decides whether this is the right product at the right total price and delivery date. |
+| Cart (`cart`) | `transaction` | Checks what they are buying and what it will cost in total. |
+| Checkout (`checkout`) | `transaction` | Gives delivery and payment details once and places the order. |
+| Order confirmation (`confirmation`) | `transaction` | Knows the order went through and what happens next. |
+| Order history (`orders`) | `workspace` | Finds an order, sees where it is, and starts a return. |
+
+## Journeys to walk first
+
+### `find-and-buy` — Find a product and buy it
+
+Actor `first_time_shopper`, through: `search-results` → `product` → `cart` → `checkout` → `confirmation`.
+
+Watch when you walk it:
+
+- The total cost, including delivery, is visible before the last step.
+- Checkout can be finished without creating an account.
+- Count the form fields in checkout; each must be needed to deliver or to charge.
+- An error in checkout keeps everything the shopper already typed.
+
+### `compare-and-choose` — Narrow a range down to one product
+
+Actor `first_time_shopper`, through: `catalogue` → `product` → `catalogue` → `product`.
+
+Watch when you walk it:
+
+- Filters apply without losing scroll position, and say how many results remain.
+- Going back from a product returns to the same place in the list.
+- The facts people compare on are in the same place on every product page.
+
+### `track-and-return` — Find a past order and start a return
+
+Actor `returning_customer`, through: `orders` → `confirmation`.
+
+Watch when you walk it:
+
+- The order's current status and expected date are visible without opening a sub-page.
+- The return starts from the order, not from a help article.
+- Every step says what happens next and when.
+
+## What to research about the domain
+
+- What do shoppers in this category need to see before buying (sizes, compatibility, ingredients, warranty)?
+- Which delivery, payment and return options are expected in this market, and which are legally required?
+- What do customer reviews of this shop and its competitors complain about most?
+- What share of traffic is on phones, and where does it come from (search, social, email)?
+- Which local conventions matter: currency format, address format, phone format, tax shown or not?
+
+## Where research starts
+
+- [Baymard Institute — e-commerce UX research](https://baymard.com/research) — Large-sample usability research on product pages, search, cart and checkout.
+- [Nielsen Norman Group — 10 usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) — The baseline vocabulary for reviewing any screen.
+- [Shopify Polaris](https://polaris.shopify.com/) — Commerce patterns and content guidelines from a platform that runs many shops.
+- [GOV.UK Design System — patterns](https://design-system.service.gov.uk/patterns/) — Researched patterns for addresses, payment details, errors and confirmation pages.