ui-lab

Laboratório de UI: sugestões de UX

Uma sugestão de UX passa por três fases:

1. Prototipar — apenas o código do laboratório muda, na plataforma que as notas do projeto indicam. O proprietário navega pelas opções.
2. Fechar a rodada — a rodada é etiquetada e documentada em docs/ux-history/, e seus arquivos de laboratório são excluídos.
3. Promover — após o proprietário escolher uma opção e aprovar um plano, ela se torna a tela real, com sua lógica compartilhada e a outra plataforma quando o aplicativo a possui.

As notas de laboratório do projeto

Esta skill é o processo; as especificidades de cada projeto estão em seu .claude/ui-lab.md. Leia-o antes de qualquer outra coisa. Ele fornece:

• Plataforma: qual aplicativo de laboratório usar nesta máquina (uname -s), seu id, onde o código do laboratório fica e o comando que abre uma tela;
• Pastas de opções: a pasta e o pacote por plataforma, e onde as strings ficam;
• Arquivos: o tema ou as cores que a tela de uma opção usa, e para onde seu estado vai na promoção;
• Dados de exemplo: a partir do que as opções constroem seus dados;
• Fakes e casos extremos: quais dados inventados não podem ser mostrados neste aplicativo e os casos a verificar;
• Capturas de tela: como tirar uma por plataforma;
• Promover: caminhos de destino, tratamento da outra plataforma, documentos a atualizar e os comandos de construção de release;
• como o próprio laboratório funciona (um link de documento).

As notas vencem onde diferem desta skill. Se o projeto não tiver .claude/ui-lab.md, ou se faltar algo que esta skill precisa abaixo, pergunte ao proprietário em vez de adivinhar e adicione a resposta às notas.

Fase 1: prototipar

Trabalhe em um branch ux/<tela> a partir do atual, para que outra máquina possa puxar a rodada. Se a árvore tiver alterações não confirmadas que não são suas, pergunte antes de mudar.

Uma pasta por opção

Cada opção vive em sua própria pasta (as notas dizem onde), para que possa ser excluída, revivida ou promovida sozinha. Ela fica no pacote de telas, então promovê-la é uma movimentação de arquivo.

Arquivo	Contém	Na promoção
<Tela>Option<B>	a tela, <Tela>Screen<B>(state, actions): qualidade de produção (as strings e o tema do aplicativo, conforme as notas) e livre de tipos de laboratório	move para dentro do aplicativo
<Tela>Option<B>State	estado que a lógica do aplicativo ainda não produz, modelado como ela o produziria	move para onde as notas dizem
<Tela>Option<B>Lab	seus dados de exemplo, comportamento simulado, ações vazias e seu valor LabOption com o que falsifica acima dele	excluído
as strings da opção, quando o aplicativo usa recursos de string (nomes e localização conforme as notas)	o novo texto da opção	move para as strings do aplicativo

• Além da pasta (e arquivos de string onde os recursos não podem ficar nela), uma opção adiciona uma linha: sua entrada na lista de sua tela em LabScreens (<tela>OptionB,).
• Tudo na pasta é private exceto a tela, seu estado e o valor LabOption, cujos nomes carregam a opção, para que as opções nunca entrem em conflito.
• Uma opção que precisa de uma versão modificada de um componente existente do aplicativo usa sua própria cópia, em sua pasta.
• Os dados de exemplo vêm das fontes que as notas nomeiam, como estão, mais o que a opção adiciona em seu arquivo Lab. Não invente texto onde as notas dizem que os dados são reais.

Passos

1. Abra a tela no laboratório e veja current, a tela como o aplicativo a tem agora.
2. Escreva 2–3 direções distintas como opções a, b, c após current, cada uma com uma nota de uma linha sobre o que muda.
3. Acima de cada valor LabOption, liste o que a opção falsifica: dados que faltam na lógica do aplicativo, comportamento que não foi construído e o que dados inventados não podem mostrar (as notas listam os usuais deste aplicativo).
4. Verifique os casos extremos que as notas listam, mais o que for incomum para a tela. Um caso que muda o design torna-se sua própria opção (a-rtl, a-dark).
5. Construa, abra cada opção e veja uma captura de tela (comandos nas notas; a skill android-emulator cobre dispositivos Android). Uma captura de tela toda preta de um telefone significa que ele está bloqueado: peça ao proprietário para desbloqueá-lo.
6. Faça commit no branch e informe ao proprietário os ids das opções (<tela> <opção>), o que cada uma falsifica e o dispositivo.

Quando o proprietário pedir para alterar uma opção, a alteração se torna uma nova opção em sua própria pasta (b2 ao lado de b). Opções que o proprietário descarta permanecem até o fechamento da rodada, para que a etiqueta da rodada as contenha todas.

Fase 2: fechar a rodada

Quando o proprietário escolheu uma opção ou recusou todas:

1. Etiquete o último commit da rodada, enquanto todas as opções ainda estão nele, e envie a etiqueta: git tag ux/<tela>/<aaaa-mm-dd> && git push origin ux/<tela>/<aaaa-mm-dd>. A etiqueta mantém o código acessível após o branch desaparecer; uma segunda rodada no mesmo dia recebe -2.
2. Escreva docs/ux-history/<tela>/<aaaa-mm-dd>-<tópico>.md no formato abaixo e vincule-o de onde as notas dizem (um documento da tela, por exemplo).
3. Exclua as pastas das outras opções, arquivos de string e linhas de LabScreens; a opção escolhida permanece até a fase 3.
4. Faça commit. Com todas as opções recusadas, a rodada termina aqui: mescle o branch (o arquivo de histórico é sua única alteração duradoura) ou exclua-o, conforme preferir o proprietário.

# <Tela> — <tópico> (<aaaa-mm-dd>, <plataforma>)

Etiqueta: `ux/<tela>/<aaaa-mm-dd>`

## Opções
- **a — <nome>**: <o que muda>. *Escolhida*, promovida em <commit>.
- **b — <nome>**: <o que muda>. *Recusada*: <motivo do proprietário, quando informado>.

## O que falsificaram
- b: <o que o protótipo mostrou que o aplicativo ainda não pode fazer>.

## Revivendo uma opção
    git checkout ux/<tela>/<aaaa-mm-dd> -- <pasta da opção> <arquivos de string>
Em seguida, adicione `<Tela>Option<B>,` a `LabScreens`.
Construído contra <componentes e dados de exemplo que usou> a partir da etiqueta. Erros de compilação após reviver estão nas cópias da opção e nos dados de exemplo; corrija-os lá.

Revivendo

Quando o proprietário pedir uma opção anterior, siga seu arquivo de histórico: faça checkout dos caminhos da etiqueta em um branch ux/<tela>, adicione a linha LabScreens, corrija o que não compila mais dentro da pasta da opção e abra-a. Ela se torna então uma opção ativa de uma nova rodada.

Fase 3: promover

Com a rodada fechada em uma opção escolhida, entre no modo de plano (EnterPlanMode) e apresente o plano com ExitPlanMode; o proprietário o aprova com seu botão. O plano cobre:

• os arquivos que se movem e a tela que substituem;
• o trabalho de lógica por trás de cada item falsificado: as alterações propostas de estado, view model ou controlador, e seus testes;
• a outra plataforma, quando o aplicativo a possui, conforme as notas;
• os documentos que as notas dizem para atualizar.

Após a aprovação, no mesmo branch:

1. git mv o arquivo de tela da opção para dentro do aplicativo (destino conforme as notas), substituindo a tela antiga, e dê à função ou à view o nome da tela.
2. Mova suas strings para as do aplicativo, sem o prefixo ou a tabela da opção.
3. Mova seu estado para onde as notas dizem, faça a lógica do aplicativo produzi-lo com testes e conecte as ações.
4. Reintegre seus componentes copiados de volta aos originais e exclua o resto de sua pasta e sua linha LabScreens; aponte o current da tela em LabScreens para a tela promovida.
5. Construa o release com os comandos das notas, onde qualquer referência ao código do laboratório falha na compilação.
6. Faça as partes de outra plataforma e de documentos do plano e coloque o commit de promoção no arquivo de histórico da rodada.

Mesclar o branch é decisão do proprietário.