Oma AI-tuotesuunnittelun työnkulku ilman Figmaa

Tuotesuunnittelu ilman Figmaa toimii, kun tuotteella on jo kypsä design-järjestelmä. Oma AI-tuotesuunnittelun työnkulku käyttää kolmea agentin taitoa: ui-design tutkii yhdeksän eri suuntaa, ui-implement muuttaa valitun suunnan tuotteeksi ja ui-walkthrough tarkistaa jokaisen tilan sisäänrakennetulla Agent Browserilla. Teen silti päätökset itse; agentti hoitaa toistuvan tuotannon ja tarkistuksen.

Useimmat tuotteen ominaisuudet eivät ala tyhjästä. Kun tuote on ollut olemassa jonkin aikaa, sen perussuunnittelupäätökset ovat jo koodissa. Painikkeet, syötteet, kortit, navigaatio, välit, värit, tekstit, hover-tilat ja mobiilikäytös on kaikki määritelty. Näiden osien uudelleenrakentaminen Figmaan tarkoittaa usein samojen komponenttien raahaamista toiselle kanvaasille ennen kuin ne rakennetaan uudelleen tuotteeseen.

Suunnittelija tekee edelleen tuotevalinnat. Agentti poistaa suuren osan toistuvasta kokoamisesta ja tarkistamisesta. Tämä toimii, koska Zerolla on jo melko kypsä design-järjestelmä.

1. Aloita tuotesuunnittelu ilman Figmaa design-järjestelmällä

Ilman Figmaa työskentely ei tarkoita työskentelyä ilman suunnittelusääntöjä. Se vaatii selkeämmät säännöt.

Zerossa agentti voi tarkastella:

• Olemassa olevia komponentteja: painikkeet, syötteet, pudotusvalikot, kortit, dialogit ja navigaatio
• Vakiintuneita välejä, typografiaa, värejä, reunoja ja kulmien pyöristyksiä
• Olemassa olevia hover-, valittu-, pois käytöstä-, tyhjä- ja mobiilitiloja
• Tekstikäytäntöjä, kuten lauseen aloitus isolla ja lyhyet käyttäjälle näkyvät nimet
• Oikeita näyttöjä, jotka osoittavat, miten nämä osat yhdistyvät

Nämä viitteet vastaavat tavallisiin suunnittelukysymyksiin. Uuden syötteen tulisi näyttää samalta kuin jo julkaistut syötteet. Uuden kortin tulisi käyttää samaa pintaa ja pyöristystä kuin lähin olemassa oleva kortti. Kuvakepainikkeen hover-palaute tulee olla sama kuin muilla kuvakepainikkeilla.

Tämä antaa agentille rajat. Se voi tutkia ominaisuuden rakennetta keksimättä uutta visuaalista kieltä joka näytölle.

Figma on edelleen hyödyllinen, kun tiimi luo uutta brändiä, komponenttijärjestelmää tai vuorovaikutusta, jolla ei ole läheistä tuoteviitettä. Mutta kun järjestelmä on kypsä, toimiva tuote voi olla pääasiallinen suunnittelupinta. Tämä on ominaisuustason versio design-as-code-työnkulusta, jolla rakensimme Zeron uudelleen.

2. Käytä ui-design:ää yhdeksän tuotesuunnittelusuunnan tutkimiseen

Jokainen ominaisuus vaatii silti tutkimista. En halua, että agentti ottaa ensimmäisen lauseeni ja muuttaa sen heti koodiksi.

Aloitan ui-design:llä. Annan agentille nykyisen näytön, käyttäjän ongelman, tavoitteen ja tärkeimmät rajoitteet. Agentti lukee olemassa olevat tuotekäytännöt ja palauttaa yhden suositellun suunnan sekä yhdeksän vaihtoehtoa.

Yksinkertaisesti: taito tallentaa nykyisen näytön, luo yhden suositellun suunnan, tutkii yhdeksän erilaista vaihtoehtoa, esittelee kompromissit ja odottaa ihmisen valintaa.

Suunnittelun ajattelu tämän ohjeen taustalla

Tämä ohje ei ole vain lista visuaalisia sääntöjä. Se muuttaa suunnittelijan normaalin prosessin toistettavaksi sarjaksi:

1. Ymmärrä ennen ehdottamista. Tallenna nykyinen näyttö ja lue ympäröivä tuote ennen kuin teet mitään.
2. Ajattele järjestelminä. Käytä olemassa olevia komponentteja, mallisivuja, vuorovaikutusmalleja ja tekstisääntöjä lähtömateriaalina.
3. Estä uudelleenkeksiminen. AI pyrkii luomaan uuden mallin, jos kehotus on epämääräinen. Ohje käskee etsimään lähimmän julkaistun komponentin tai sivun ja käyttämään sitä muistinvaraisen arvauksen sijaan.
4. Tutki ennen valintaa. After-ankkuri antaa yhden uskottavan suunnan. Yhdeksän vaihtoehtoa avaavat erilaisia päätöksiä asettelusta, hierarkiasta, tiheydestä, aloituspisteestä ja tiedon paljastamisesta.
5. Erota tutkiminen ja sitoutuminen. Agentti pysähtyy vaihtoehtojen esittämiseen. Ihminen vertaa kompromissit ja valitsee ennen koodin aloittamista.
6. Arvioi koko kokemus. Tekstit, hover-palaute, tilat, mobiilikäytös ja visuaalinen johdonmukaisuus ovat osa suunnittelua, eivät toteutuksen jälkisiivousta.

Tätä järjestelmäajattelua haluan taidolta: ymmärrä olemassa oleva tuote, tutki sen sisällä ja tee sitten selkeä valinta.

Tässä on alkuperäinen ohje kokonaisuudessaan, suoraan työnkulusta:

Alkuperäinen ui-design-ohje kokonaisuudessaan

# vm0 / Zero UI Design Rules

## Workflow — visuals first, code later

**Do not jump to code.** When this skill is invoked, the first deliverable is always a set of rendered mockups for Ming to look at. Implementation happens only after a direction is chosen.

### Step 1 — Capture the "before"

- If a screen already exists, render its current state as the **before** image (screenshot the running app, or render the existing component as a static preview).
- If the request is for a brand-new screen, the "before" is either the closest existing screen or a blank state — make this explicit in the caption.

### Step 2 — Produce a single "after" anchor

- One mockup that represents your best-guess interpretation of the request, fully obeying every rule below (components, sentence case, agent-detail inputs/dropdowns, chat-composer card radii, add-schedule button, IconButton hovers, gray-50 surfaces).
- Pair it with the **before** side-by-side. Label them clearly: `Before` / `After`.

### Step 3 — Generate 9 variant explorations

After the before/after pair, produce **9 distinct variant mockups** for the same screen. Each variant should explore a meaningfully different design axis — not 9 color tweaks. Cover a spread such as:

1. Layout — single column vs. split / sidebar / grid
2. Density — compact vs. spacious
3. Hierarchy — which element leads visually
4. Surface treatment — flat vs. card-grouped vs. divided sections
5. Entry point — inline action vs. dedicated CTA vs. empty-state hero
6. Copy framing — instructive vs. minimal vs. conversational
7. Disclosure — everything visible vs. progressive reveal / accordions
8. Composition — content-led vs. control-led
9. A deliberately unconventional / "wild card" direction worth seeing once

Each variant must still respect the non-negotiables (sentence case, reuse components, agent-detail input/dropdown style, chat-composer radii, add-schedule button, IconButton hover, gray-50 neutrals). Variants explore *layout and emphasis*, not "what if we ignored the design system."

### Step 4 — Present, then wait

- Show all images to Ming in one message: the `Before / After` pair first, then the 9 variants numbered 1–9 with a one-line caption each describing the axis being explored.
- Ask which direction (or which mix) to pursue.
- Do not begin implementation until Ming picks a direction.

### Rendering the images

- Preferred path: build static HTML/React previews that use real Tailwind tokens from `turbo/apps/platform`, screenshot them, and upload via `okou web upload-file`.
- For quick exploration: the `v0` skill can generate variant mockups from a prompt — but the prompt must explicitly enumerate the rules below (sentence case, agent-detail inputs, chat-composer radius, etc.) so v0 doesn't produce generic SaaS UI.
- If image generation is unavailable for the session, fall back to clearly-labeled ASCII / textual wireframes for all 11 frames (before, after, 9 variants) and call this out — never silently skip the visuals step.

---

# Design Rules

These are the non-negotiable design conventions for any new UI shipped inside the vm0 platform (`turbo/apps/platform`). Apply them before writing components, and audit existing PRs against them during review.

## Core principles

1. **Reuse, don't reinvent.** Always check existing primitives in `turbo/apps/platform/src/components/` and view-level patterns under `src/views/` before introducing a new component. If a similar interaction already ships in agent detail, schedule, or chat composer, copy that pattern rather than designing a parallel one.
2. **Match the Zero design language.** Soft surfaces, neutral grays, generous radii, subtle borders, no harsh shadows. The visual baseline is "calm, opinionated, slightly editorial" — never SaaS-default.
3. **Speak from the user's seat.** Copy should describe what *they* are about to do or see, not what the system is doing. Keep it short — usually a single sentence, max two.

## Reference patterns (copy these directly)

| Element             | Reference source                                  | Why |
|---------------------|---------------------------------------------------|-----|
| Text / textarea input | Agent detail page input (`src/views/agent-detail/`) | Established padding, border, focus state, placeholder treatment |
| Dropdown / select     | Agent detail page dropdown                         | Established trigger style, menu radius, item hover, check mark placement |
| Card / panel radius   | Chat composer card (look for `composer` components) | Sets the canonical card radius and surface style across the app |
| Primary page button   | "Add schedule" button on the schedule page          | The neutral-dark primary used everywhere *outside* of modals |
| Modal primary button  | The brand primary color (only inside dialogs/popovers) | Modals retain the brand-color primary; pages do not |
| Icon-only button      | Existing IconButton with hover background           | Every clickable icon must have a visible hover state |

When in doubt, open the reference component in the codebase, read its props and class names, and mirror them. Do not approximate from memory.

## Copy guidelines

- **User-perspective phrasing.** "Connect your inbox" beats "Inbox connection required". "No agents yet" beats "Agent list is empty".
- **Brevity over completeness.** A short line outperforms a complete sentence. Trim filler ("simply", "please", "in order to").
- **Sentence case for everything.** Labels, headings, buttons, menu items, table columns — all sentence case ("Model providers", "API keys", "Add schedule"). Never Title Case. Never `uppercase` via CSS on section headers. If you find a Title-Case or all-caps label, fix it.
- **No caption-case "decorative" labels** above fields or sections — they read as form-y and dated. Use a normal label or skip the label if the field is self-evident.
- **No trailing punctuation** on standalone labels or buttons. Periods are for body copy and helper text.
- When renaming a string, grep the codebase for the old string and tests for it — labels are referenced in tests and translations.

## Components and structure

- Always build pages out of existing components (`Button`, `Input`, `Select`, `Card`, `IconButton`, dialog primitives, etc.). New components are a last resort and require a reason.
- Look for an existing layout/template (settings page, list page, detail page) and inherit its scaffolding. Don't re-derive page structure.
- When adding to a settings-style page, match the section spacing, divider treatment, and form-row width used by neighboring sections.

## Buttons

- **Page primary** (the main CTA on a page) → match the "Add schedule" button on the schedule page. This is the neutral dark/solid primary used app-wide outside dialogs.
- **Modal primary** (the confirm button inside dialogs/popovers) → uses the brand primary color. Pages do not.
- **Secondary / ghost buttons** → reuse the existing variants; do not invent new ones.
- **Icon buttons** → must have a hover background (typically `hover:bg-gray-50` or the established IconButton hover token). Never ship a bare hoverless icon as a click target.
- All buttons should respect the existing height tokens — don't introduce one-off sizes.

## Inputs

- Mirror the agent detail input: same padding, same border, same focus ring (or lack thereof — check the reference before adding a focus ring), same placeholder color.
- Multi-line: use the agent detail textarea pattern (auto-grow or fixed rows as in reference).
- Don't put a colon at the end of field labels.
- Helper text below the input, in muted gray, single line.

## Dropdowns / selects

- Mirror the agent detail dropdown: same trigger appearance, same menu radius, same item padding, same hover/selected states.
- The menu should not be wider than its trigger unless the content demands it.
- Avoid nested submenus unless an existing dropdown already uses them.

## Cards and surfaces

- Card radius and surface style match the chat composer card. Do not introduce a smaller or larger radius without a reason.
- Borders are subtle (single hairline in the existing border token). No drop shadows unless the chat composer uses one.
- Neutral surfaces on mobile / light gray fills (active pill backgrounds, icon container fills, etc.) → `bg-gray-50`. `gray-100` and `gray-200` have repeatedly been called too dark — start at `gray-50`.

## Focus and interaction

- Don't add custom `:focus-visible` box-shadows or outlines to nav/marketing elements — reuse the hover color shift instead. (Same restraint generally applies inside the platform unless a reference component has an explicit focus ring.)
- Every interactive element (button, icon button, row, link) needs a visible hover state. Test by hovering each one before considering the design done.
- Disabled states use the existing disabled tokens; don't hand-roll a faded color.

## Review checklist

Before declaring a UI ready, walk through:

1. Did I reuse existing components instead of building new ones?
2. Did I match an existing page template / layout?
3. Are inputs visually identical to agent detail inputs?
4. Are dropdowns visually identical to agent detail dropdowns?
5. Do cards match the chat composer radius and surface?
6. Is every label sentence case? Any leftover Title Case or all-caps?
7. Is the copy short and written from the user's seat?
8. Is the page primary the "Add schedule"-style button? Is the brand primary used only inside modals?
9. Does every icon button have a hover background?
10. Did I hover every interactive element to confirm feedback?

If any answer is "no", fix it before opening the PR.

## When in doubt

- Open the reference component, read its source, and copy the structure.
- If two reference components disagree, prefer the more recently shipped one (check git log).
- If the design genuinely needs a new primitive, raise it with Ming before building it — bundled redesign work belongs in one PR with him as the reviewer.

Yhdeksän vaihtoehdon ei tarvitse olla yhdeksän valmista suunnittelua. Niiden tehtävä on antaa tarpeeksi vaihtelua, jotta näen ongelman eri tavalla ja pääsen oikeaan suuntaan. Jos konsepti on tuotteen ulkopuolella, itsenäinen React-prototyyppi voi silti auttaa. Tässä ominaisuudessa pysyin oikean tuotteen järjestelmässä.

Todellinen esimerkki: Zeron navigaatio

Zerossa oli alun perin yksi 300 pikselin sivupalkki, jossa oli tuotekohteet, kiinnitetyt agentit ja keskusteluketjut. Se teki kolmea työtä yhtä aikaa. Halusin erottaa nämä tehtävät muuttamatta keskustelualueen rakennetta.

Tutkimuksen tuoteohje oli:

/ui-design

Toista Zeron kolmen alueen navigaation suunnitteluvaihe oikeasta historiallisesta lähtökohdasta. Erottele tuotekohteet, agentit ja keskustelut selkeämmiksi alueiksi muuttamatta keskustelualueen rakennetta. Käytä oikeita Zero-tunnuksia, kuvakkeita ja komponentteja. Tuota uskollinen Before, yksi vahva After ja yhdeksän aidosti erilaista vaihtoehtoa. Älä muokkaa tuotekoodia tai esitä mallinnosta selainnäyttönä.

Ensimmäinen tutkimus oli liian varovainen. Useat vaihtoehdot muuttivat leveyksiä ja valintatyylejä, mutta ne näyttivät silti samalta sivupalkilta. Hylkäsin tämän sarjan ja pyysin agenttia tekemään erot näkyviksi tietoarkkitehtuurin tasolla.

Toinen ajo palautti yhdeksän aidosti erilaista suuntaa. Ryhmittelin ne 3 × 3 -taulukkoon, jotta niitä on helppo verrata ilman pitkää kuvakaistaa. Jokainen pikkukuva avautuu blogin kuvakatselijaan.

1. Ylänavigaatio	2. Kokoontaittuva laatikko	3. Ketju ensin
Siirrä kohteet keskustelun yläpuolelle	Piilota kohteet kunnes tarvitaan	Tee keskusteluista pääasiallinen navigaatio
4. Agentti ensin	5. Keskustelu ensin	6. Komentokäynnistin
Valitse agentti ennen ketjuja	Näytä kiinnitetyt agentit keskustelun yläpuolella	Avaa kohteet haettavasta valikosta
7. Laajennettava kisko	8. Kojelauta-aloitus	9. Alatelakka
Laajenna kapea kisko vain tarvittaessa	Aloita viimeisimmästä työstä	Siirrä kohteet alareunaan

En valinnut mitään näistä kehyksistä sellaisenaan. Käytin niitä päättämään, mikä säilyy ja mikä muuttuu. Lopullinen suunta käytti kapeaa kohdekiskoa, erillistä keskustelukiskoa, viittä näkyvää kiinnitettyä agenttia ja olemassa olevaa keskustelualuetta.

Tärkein ui-design:n tuotos ei ollut pelkkä kuva. Se oli lyhyt päätöskirjaus:

• Pidä 68 pikselin kohdekisko ja 300 pikselin keskustelukisko
• Näytä viisi kiinnitettyä agenttipaikkaa
• Pidä valinta hillittynä mutta luettavana
• Näytä järjestelyohjeet vain vedon aikana
• Pidä keskustelu ja olemassa oleva mobiililaatikko ennallaan

Tämä riitti toteutuksen aloittamiseen.

3. Käytä ui-implement:ää valitun suunnittelun muuttamiseen koodiksi

Kun olen valinnut suunnan ja yhdistänyt tuotekoodin, agentti työskentelee suoraan koodissa. En piirrä valittua kehystä ensin Figmaan.

Yksinkertaisesti: ui-implement ohittaa tutkimisen, koska suunta on jo valittu. Se etsii lähimmät oikeat komponentit ja sivurakenteen, rakentaa niillä, tarkistaa tuloksen ja varmistaa ominaisuuden selaimessa.

Mitä tämä ohje suojaa

• Valittua suuntaa ei saa suunnitella uudelleen toteutuksen aikana.
• Agentin on aloitettava lähimmällä olemassa olevalla komponentilla ja mallisivulla.
• Uudelleenkäyttö voittaa uuden komponentin, ellei tuotteessa ole todellista aukkoa.
• Itsetarkistus ja selainkatselmus havaitsevat epäjohdonmukaiset tekstit, tilat ja vuorovaikutukset.
• Jos tuoteratkaisu on yhä auki, työ palaa ui-design:een.

Näin design-järjestelmä pysyy aktiivisena toteutuksen aikana. Se ei ole dokumentti, jonka agentti lukee kerran. Se ohjaa, mitä komponentteja valitaan ja miten valmis kokemus tarkistetaan.

Tässä on alkuperäinen ohje kokonaisuudessaan, suoraan työnkulusta:

Alkuperäinen ui-implement-ohje kokonaisuudessaan

# vm0 / Zero UI Implementation Rules

## Workflow — implement directly

When this skill is invoked, **skip the mockup and variant exploration phase**. Start implementing in `turbo/apps/platform` immediately, applying every design rule below.

### Step 1 — Locate the reference components

Before writing a line, open the reference components you'll mirror:

- Input / textarea → `src/views/agent-detail/` input
- Dropdown / select → `src/views/agent-detail/` dropdown
- Card / panel radius → chat composer card
- Page primary button → "Add schedule" button on the schedule page
- Icon-only button → existing `IconButton` with hover background

Read their props and class names. Mirror them — do not approximate from memory.

### Step 2 — Find the closest existing page template

Open the nearest existing page of the same shape (settings, list, detail) and inherit its scaffolding: section spacing, divider treatment, form-row width. Don't re-derive page structure.

### Step 3 — Build, then self-audit

Implement the screen with existing primitives from `turbo/apps/platform/src/components/`. When you think it's done, walk the **Review checklist** at the bottom of this skill before reporting back. Fix every "no" answer before declaring the work complete.

### Step 4 — Verify in the browser

For any UI work, start the dev server and exercise the feature in a browser before reporting the task as done. Hover every interactive element, test the golden path and edge cases, and watch for regressions in neighboring screens. Type-check and tests verify code, not feature correctness — if you can't open the browser, say so explicitly.

### When to fall back to ui-design

If the request is open-ended ("design a settings page for X") with no chosen direction, stop and run the `ui-design` skill instead — the before/after + 9 variants exist for exactly that case. `ui-implement` is for when the direction is already decided.

---

# Design Rules

These are the non-negotiable design conventions for any new UI shipped inside the vm0 platform (`turbo/apps/platform`). Apply them while building, and audit your own diff against them before opening the PR.

## Core principles

1. **Reuse, don't reinvent.** Always check existing primitives in `turbo/apps/platform/src/components/` and view-level patterns under `src/views/` before introducing a new component. If a similar interaction already ships in agent detail, schedule, or chat composer, copy that pattern rather than designing a parallel one.
2. **Match the Zero design language.** Soft surfaces, neutral grays, generous radii, subtle borders, no harsh shadows. The visual baseline is "calm, opinionated, slightly editorial" — never SaaS-default.
3. **Speak from the user's seat.** Copy should describe what *they* are about to do or see, not what the system is doing. Keep it short — usually a single sentence, max two.

## Reference patterns (copy these directly)

| Element             | Reference source                                  | Why |
|---------------------|---------------------------------------------------|-----|
| Text / textarea input | Agent detail page input (`src/views/agent-detail/`) | Established padding, border, focus state, placeholder treatment |
| Dropdown / select     | Agent detail page dropdown                         | Established trigger style, menu radius, item hover, check mark placement |
| Card / panel radius   | Chat composer card (look for `composer` components) | Sets the canonical card radius and surface style across the app |
| Primary page button   | "Add schedule" button on the schedule page          | The neutral-dark primary used everywhere *outside* of modals |
| Modal primary button  | The brand primary color (only inside dialogs/popovers) | Modals retain the brand-color primary; pages do not |
| Icon-only button      | Existing IconButton with hover background           | Every clickable icon must have a visible hover state |

When in doubt, open the reference component in the codebase, read its props and class names, and mirror them. Do not approximate from memory.

## Copy guidelines

- **User-perspective phrasing.** "Connect your inbox" beats "Inbox connection required". "No agents yet" beats "Agent list is empty".
- **Brevity over completeness.** A short line outperforms a complete sentence. Trim filler ("simply", "please", "in order to").
- **Sentence case for everything.** Labels, headings, buttons, menu items, table columns — all sentence case ("Model providers", "API keys", "Add schedule"). Never Title Case. Never `uppercase` via CSS on section headers. If you find a Title-Case or all-caps label, fix it.
- **No caption-case "decorative" labels** above fields or sections — they read as form-y and dated. Use a normal label or skip the label if the field is self-evident.
- **No trailing punctuation** on standalone labels or buttons. Periods are for body copy and helper text.
- When renaming a string, grep the codebase for the old string and tests for it — labels are referenced in tests and translations.

## Components and structure

- Always build pages out of existing components (`Button`, `Input`, `Select`, `Card`, `IconButton`, dialog primitives, etc.). New components are a last resort and require a reason.
- Look for an existing layout/template (settings page, list page, detail page) and inherit its scaffolding. Don't re-derive page structure.
- When adding to a settings-style page, match the section spacing, divider treatment, and form-row width used by neighboring sections.

## Buttons

- **Page primary** (the main CTA on a page) → match the "Add schedule" button on the schedule page. This is the neutral dark/solid primary used app-wide outside dialogs.
- **Modal primary** (the confirm button inside dialogs/popovers) → uses the brand primary color. Pages do not.
- **Secondary / ghost buttons** → reuse the existing variants; do not invent new ones.
- **Icon buttons** → must have a hover background (typically `hover:bg-gray-50` or the established IconButton hover token). Never ship a bare hoverless icon as a click target.
- All buttons should respect the existing height tokens — don't introduce one-off sizes.

## Inputs

- Mirror the agent detail input: same padding, same border, same focus ring (or lack thereof — check the reference before adding a focus ring), same placeholder color.
- Multi-line: use the agent detail textarea pattern (auto-grow or fixed rows as in reference).
- Don't put a colon at the end of field labels.
- Helper text below the input, in muted gray, single line.

## Dropdowns / selects

- Mirror the agent detail dropdown: same trigger appearance, same menu radius, same item padding, same hover/selected states.
- The menu should not be wider than its trigger unless the content demands it.
- Avoid nested submenus unless an existing dropdown already uses them.

## Cards and surfaces

- Card radius and surface style match the chat composer card. Do not introduce a smaller or larger radius without a reason.
- Borders are subtle (single hairline in the existing border token). No drop shadows unless the chat composer uses one.
- Neutral surfaces on mobile / light gray fills (active pill backgrounds, icon container fills, etc.) → `bg-gray-50`. `gray-100` and `gray-200` have repeatedly been called too dark — start at `gray-50`.

## Focus and interaction

- Don't add custom `:focus-visible` box-shadows or outlines to nav/marketing elements — reuse the hover color shift instead. (Same restraint generally applies inside the platform unless a reference component has an explicit focus ring.)
- Every interactive element (button, icon button, row, link) needs a visible hover state. Test by hovering each one before considering the design done.
- Disabled states use the existing disabled tokens; don't hand-roll a faded color.

## Review checklist

Before declaring a UI ready, walk through:

1. Did I reuse existing components instead of building new ones?
2. Did I match an existing page template / layout?
3. Are inputs visually identical to agent detail inputs?
4. Are dropdowns visually identical to agent detail dropdowns?
5. Do cards match the chat composer radius and surface?
6. Is every label sentence case? Any leftover Title Case or all-caps?
7. Is the copy short and written from the user's seat?
8. Is the page primary the "Add schedule"-style button? Is the brand primary used only inside modals?
9. Does every icon button have a hover background?
10. Did I hover every interactive element in a browser to confirm feedback?

If any answer is "no", fix it before opening the PR.

## When in doubt

- Open the reference component, read its source, and copy the structure.
- If two reference components disagree, prefer the more recently shipped one (check git log).
- If the design genuinely needs a new primitive, raise it with Ming before building it — bundled redesign work belongs in one PR with him as the reviewer.

Tämä oli ominaisuuskohtainen toteutuskehotus:

/ui-implement

Aloita versiosta 04d642bb. Lisää oletuksena pois päältä oleva työpöytänäkymän jako 68px kohdekiskolla, 300px keskustelukiskolla ja muuttumattomalla keskustelualueella. Pidä vanha 300px sivupalkki, kun jako on pois päältä ja mobiilissa. Näytä viisi kiinnitettyä paikkaa, säilytä käyttäjän järjestys ja näytä järjestelyohjeet vain aktiivisen vedon aikana. Älä tarkista historiallista ominaisuutta tai myöhempiä parannuksia ennen kuin itsenäinen korjaus, testit ja selainnäyttö on jäädytetty.

Navigaatio-ominaisuudessa pyysin agenttia pitämään vanhan sivupalkin, kun ominaisuus on pois päältä, näyttämään uuden kolmiosaisen asettelun, kun se on päällä, säilyttämään olemassa olevan mobiililaatikon ja sallimaan kiinnitettyjen agenttien järjestelyn.

Toteutuksen aikana agentti löysi tärkeän ongelman. Vanha tuote muisti, mitkä agentit oli kiinnitetty, mutta ei niiden järjestystä. Vedon jälkeen järjestys saattoi näyttää oikealta, mutta palautui päivityksen jälkeen.

Agentti teki siis enemmän kuin piirsi vedon tilan. Se tallensi uuden järjestyksen, päivitti sivun ja tarkisti, että järjestys säilyi. Se myös varmisti, että järjestelykahvat näkyivät vain vedon aikana ja katosivat sen jälkeen.

Toteutuksen toimitus näytti kaksi työpöytänäkymää, jotka tarvitsin arviointiin. Näytän ne täysleveinä, jotta käyttöliittymä pysyy luettavana. Mobiilikäytös näkyy myöhemmin walkthrough-vaiheessa tiiviinä puhelinkuvana.

Työpöydän lepotila

Aktiivinen järjestely

Tässä vaiheessa minulla oli toimiva ominaisuus, ei uusi suunnittelutiedosto. Toteutus ei kuitenkaan ollut loppu. Halusin nähdä, mitä oikeasti pyörii julkaistussa esikatselussa.

4. Käytä ui-walkthrough:ää oikean tuotteen tarkistamiseen

Tuotekatselmukset olivat ennen työläitä. Avasin julkaistun esikatselun, valmistelin oikean tilin, kytkin ominaisuuksia päälle ja pois, klikkasin kaikki kontrollit, muutin selainkokoa, otin kuvakaappauksia ja yritin muistaa, mitä tilaa kukin kuva edusti.

Agentilla on sisäänrakennettu Agent Browser, joten voin antaa tämän työn sille.

Työnkulussa on kaksi päävaihetta:

1. Listaa skenaariot ensin. Agentti muuttaa suunnittelu- ja toteutusväitteet tarkistuslistaksi.
2. Suorita tarkistuslista ja liitä todisteet. Se käy jokaisen skenaarion julkaistussa esikatselussa ja palauttaa PASS, FAIL tai BLOCKED sekä kuvakaappauksen jokaisesta merkityksellisestä tilasta.

Mitä tämä ohje muuttaa katselmuksessa

• Agentti listaa skenaariot ennen klikkailua.
• Se käyttää oikeaa julkaistua komponenttia sisäänrakennetulla Agent Browserilla.
• Se tallentaa yhden kuvakaappauksen jokaisesta merkityksellisestä tilasta.
• Se merkitsee jokaisen tarkistuspisteen PASS, FAIL tai BLOCKED.
• Se ei koskaan piilota saavuttamatonta tilaa mallikuvalla.

Tämä muuttaa manuaalisen klikkailun järjestetyksi katselmuspaketiksi. Näen tarkoitetun käytöksen, tuloksen ja todisteet yhdessä.

Koko ohje on alla. Olen kääntänyt sisäisen riippuvuuden nimen lukijalle selkeäksi muotoon ”sisäänrakennettu Agent Browser”; työnkulun logiikka on muuten ennallaan.

Alkuperäinen ui-walkthrough-ohje kokonaisuudessaan

# UI Walkthrough

End-to-end visual QA of a vm0/Zero front-end feature in its real per-PR preview. This workflow defines what to verify and how to report the result; it does not define UI-operation tooling.

## Required dependency: built-in Agent Browser

Use the built-in Agent Browser as the single source of truth for every UI interaction, including:

- Discovering and opening the per-PR preview.
- Preview-protection handling and session setup.
- Sign-up, OTP, onboarding, Stripe test checkout, and reaching the live app.
- Enabling feature switches.
- Navigating, interacting with controls, supplying test or mock data, capturing screenshots, uploading artifacts, troubleshooting, and cleanup.

Read and follow the current built-in Agent Browser instructions before taking any UI action. Do not duplicate runtime-specific commands, engine setup, selector mechanics, page-context scripts, session management, or process-cleanup methods in this workflow. If the built-in Agent Browser changes, its current instructions take precedence.

## When to use

- Walk through the UI of a vm0 pull request in its deployed preview.
- Verify an in-app feature that requires authentication, onboarding, billing, feature switches, or a real chat thread.
- Capture faithful screenshots or a short walkthrough video of the feature working in the live application.

## Walkthrough workflow

### 1. Establish the target and scope

- Identify the PR, head commit, changed user-visible behavior, and expected preview.
- Confirm that the deployed preview corresponds to the PR head before testing.
- Read the PR diff and description to derive the critical path and the states that demonstrate the change.
- Do not fix code, resolve conflicts, or change product behavior during a walkthrough unless the user separately requests implementation.

### 2. Reach the feature

Use the built-in Agent Browser to enter the preview and reach the live feature state. Follow its current rules for authentication, onboarding, billing, feature switches, and preview-only bypasses.

If a bypass is used, disclose it in the final report. Never use an onboarding bypass when onboarding itself is under test.

### 3. Define the visual state matrix

Before interacting, list the smallest set of states that proves the feature works. Include the applicable items:

- Initial/default state.
- Open, hover, focus, selected, expanded, or active state.
- Empty and populated states.
- Enabled and disabled states.
- Success, validation, loading, and error states.
- Placement, collision, flip, clipping, and responsive behavior.
- Submission or downstream action when the feature is interactive.

Prefer exercising the actual changed behavior over a generic smoke test.

### 4. Drive the live component

Use the built-in Agent Browser for all interaction and test-data techniques.

Mock or injected content may be used only to place a real application component into a deterministic visual state. The component, styling, and interaction being assessed must remain the live implementation from the PR preview.

For every mocked state:

- Record which content or prerequisite was mocked.
- Distinguish mocked content from real application behavior.
- Never imply that mocked text or data came from a model or production source.
- Exercise the real controls and downstream wiring wherever the environment permits.

### 5. Capture evidence

Use the built-in Agent Browser to capture and upload evidence for the key checkpoints. Each image should prove one meaningful state rather than repeat the same view.

If the user asks for a video, assemble a short captioned walkthrough from the verified checkpoints. Captions should identify the user action and expected result without obscuring the UI.

### 6. Deliver and report

Report:

- PR link, exact preview URL, and tested commit when available.
- Exact user flow exercised.
- Test account when one was created.
- `PASS`, `FAIL`, or `BLOCKED` for each checkpoint.
- Screenshot links and an optional video link with short descriptions.
- Feature switches, bypasses, mock data, and other test-only setup used.
- Failed checks, environment blockers, or verification gaps.

Do not claim the feature is verified unless the live preview flow was exercised and evidence was captured. If the preview is unavailable, report `BLOCKED` with the deployment evidence rather than substituting a local or static replica.

Tämä oli ominaisuuskohtainen walkthrough-kehotus:

/ui-walkthrough

Käytä julkaistua esikatselua vain sisäänrakennetun Agent Browserin kautta selainfaktana. Todista ominaisuuden pois päältä oleva sivupalkki, 68px ja 300px jako, kohteiden järjestys, hover-tilat, viisi kiinnitettyä paikkaa, vain vedon aikana näkyvät kahvat, pysyvä järjestys, ketjun valinta, vieritys ja koko iPhone-laatikko. Palauta PASS, FAIL tai BLOCKED jokaisesta tarkistuspisteestä. Älä korvaa saavuttamatonta tilaa kopiolla.

Tässä ominaisuudessa agentti järjesti walkthrough’n näiden kysymysten ympärille:

• Toimiiko vanha sivupalkki, kun ominaisuus on pois päältä?
• Näkyykö uusi työpöytärakenne, kun se on päällä?
• Ovatko hover- ja valitut tilat näkyviä mutta hillittyjä?
• Ovatko viisi kiinnitettyä agenttia luettavissa?
• Pysyvätkö järjestelykontrollit piilossa, kunnes veto alkaa?
• Säilyykö uusi järjestys päivityksen jälkeen?
• Voinko valita ja vierittää oikeita ketjuja?
• Toimiiko olemassa oleva mobiililaatikko?
• Ovatko kaikki navigaatiokohteet paikallaan ja oikeassa järjestyksessä?

Agentti avasi sitten julkaistun esikatselun uutena käyttäjänä, suoritti käyttöönoton, otti ominaisuuden käyttöön ja kävi listan läpi. Se testasi lepotilan, hover-tilan, vedon, päivityksen, ketjun valinnan, vierityksen ja puhelinasettelun.

Tuloksena oli 11 PASS, 1 FAIL.

Epäonnistuminen oli hyödyllinen. Rakenne ja vuorovaikutukset toimivat, mutta julkaistu esikatselu näytti vain kuusi tuotekohdetta. Activity ja Insights puuttuivat, ja järjestys ei vastannut valittua suunnittelua.

Skenaario	Tulos
Vanha sivupalkki ominaisuuden ollessa pois päältä	PASS
Uusi kolmiosainen työpöytäasettelu	PASS
Hover- ja valitut tilat	PASS
Viisi kiinnitettyä agenttia	PASS
Vain vedon aikana näkyvä järjestelyohje	PASS
Tallennettu järjestys päivityksen jälkeen	PASS
Ketjun valinta ja vieritys	PASS
Olemassa oleva mobiililaatikko	PASS
Kohteiden sisältö ja järjestys	FAIL

Lopullinen toimitus oli järjestetty kuvakaappauspaketti, ei nimetön kansio. Työpöytäkuvat ovat 1440 × 900 pikseliä ja puhelinkuva 1170 × 2532 pikseliä. Ne näkyvät yksi kerrallaan alla, jotta käyttöliittymä pysyy luettavana; klikkaa kuvaa suurentaaksesi sen poistumatta artikkelista.

Ominaisuus pois päältä

Ominaisuus käytössä

Työpöytäasettelu

Kohteen hover

Kiinnitetyn agentin hover

Aktiivinen veto

Tallennettu järjestys

Mobiililaatikko

Tämä mahdollistaa ominaisuuden arvioinnin rakenteellisesti. Näen tarkoitetut skenaariot, todellisen tuloksen ja todisteet yhdessä. Jos jokin epäonnistuu, tiedän tarkalleen, mihin työ palaa.

Miten tiimi ottaa käyttöön tämän AI-tuotesuunnittelun työnkulun

Koko prosessi on lyhyt. Tiimikaverit voivat tallentaa jokaisen vaiheen jaettuna Zero-työnkulkuna sen sijaan, että rakentaisivat prosessin uudelleen muistista.

Vaihe	Syöte	Tuotos
ui-design	Nykyinen näyttö, ongelma, tavoite ja rajoitteet	Yksi suositeltu suunta, yhdeksän vaihtoehtoa ja valitun suunnan kirjaus
ui-implement	Valitun suunnan kirjaus	Arvioitava koodimuutos ja kuvakaappaukset päätiloista
ui-walkthrough	Julkaistu ominaisuus ja odotettu käytös	Järjestetty skenaariolista PASS-, FAIL- tai BLOCKED-kuvakaappauksilla

Tiimikaverin ei tarvitse toistaa omaa suunnittelumakuani. Hänen tulee antaa hyvä konteksti, käyttää jaettua tuotejärjestelmää, tehdä selkeä valinta tutkimisen jälkeen ja tarkistaa selainnäytön todisteet. Samat kolme ihmisen tarkistuspistettä—ongelma, suunta ja hyväksyntä—muovaavat myös sitä, miten johdamme AI-agentteja tiiminä.

Tämä työnkulku ei poista suunnittelukäytäntöä tai -ajattelua. Se siirtää ne kohtiin, joissa niillä on eniten merkitystä: ongelman määrittelyyn, rajoitteiden asettamiseen, suuntien vertailuun, kompromissien valintaan ja toimivan tuotteen arviointiin.

Kun komponenttijärjestelmä on kypsä, minun ei enää tarvitse rakentaa jokaista ominaisuutta vedettävinä lohkoina Figmaan. Voin työskennellä agentin kanssa suoraan tuotteessa, kun design-järjestelmä pitää lopputuloksen yhtenäisenä ja walkthrough pitää tuloksen rehellisenä.

Usein kysytyt kysymykset

Miten rakennat AI-tuotesuunnittelun työnkulun?

Aloita olemassa olevasta tuotejärjestelmästä, älä tyhjästä kehotuksesta. Jaa työ tutkimiseen, toteutukseen ja katselmukseen. Anna agentin tuottaa vaihtoehtoja ja tehdä toistettavat tarkistukset, mutta pidä tuotesuunnittelija vastuussa ongelmasta, valitusta suunnasta ja lopullisesta hyväksynnästä.

Voivatko tuotesuunnittelijat työskennellä ilman Figmaa?

Kyllä, kun tuotteessa on jo vakiintuneet komponentit, sivupohjat ja vuorovaikutusmallit. Figma on edelleen hyödyllinen uudelle visuaaliselle kielelle tai vieraalle vuorovaikutukselle. Tarkoitus ei ole kieltää Figmaa, vaan välttää tunnettujen tuoteratkaisujen rakentaminen uudelleen toiselle kanvaasille.

Korvaako AI tuotesuunnittelijat?

Ei tässä työnkulussa. Agentti kokoaa vaihtoehdot, muokkaa koodia ja tarkistaa skenaariot. Suunnittelija määrittelee ongelman, asettaa rajoitteet, vertaa kompromissit, valitsee suunnan ja päättää, onko toimiva tuote tarpeeksi hyvä julkaistavaksi.