PRD — Componente Banner no Ocean Design System (Web/iOS/Android)

# PRD — Componente Banner no Ocean Design System (Web/iOS/Android)

**Jira:** [MR-494](https://useblu.atlassian.net/browse/MR-494)
**Figma:** [Ocean DS Core — Variants](https://www.figma.com/design/PgLv9k22CHHZZ867HwN65y/%F0%9F%8C%8A-Ocean-DS-Core?node-id=22177-3976&t=IP6gXHxTgDfOE9gg-4) · [Handoff](https://www.figma.com/design/PgLv9k22CHHZZ867HwN65y/%F0%9F%8C%8A-Ocean-DS-Core?node-id=24332-69742&t=IP6gXHxTgDfOE9gg-4)
**Plataforma(s):** Web / iOS / Android
**Status:** Draft v0 — aguardando incremento de design (Fase 2)
**Autor:** Mateus Amarante Avanco / Squad Design
**Data:** 2026-05-25
**Versao:** 0.4

Originado do card Jira: [MR-494 — [Ocean] Web/iOS/Android - Criar componente Banner](https://useblu.atlassian.net/browse/MR-494)

---

## 1. Contexto e Problema

O Ocean Design System da Blu fornece componentes padronizados para garantir consistencia visual e de comportamento entre as plataformas Web, iOS e Android. Atualmente, o componente **Banner** — destinado a comunicacao promocional e de cross sell — existe apenas como especificacao no Figma (Ocean DS Core) e possui implementacao parcial:

- **Web (ocean-react):** Nao implementado. O componente esta documentado no Figma mas nao existe em `@useblu/ocean-react`. Telas que precisam de banners promocionais recorrem a composicoes ad-hoc ou componentes locais.
- **iOS (ocean-ios):** Nao existe `OceanSwiftUI.Banner` dedicado. O papel e parcialmente coberto por `Ocean.InformativeCard` (UIKit legado) e `OceanSwiftUI.CardGroup` (SwiftUI), gerando inconsistencia e gap de paridade entre plataformas.
- **Android (ocean-android):** Ja possui `OceanBanner` em Compose com estilos (Neutral, Brand, Warning, Custom) e layouts (Large, Small). Serve como referencia de implementacao.

Essa lacuna resulta em:
1. **Inconsistencia visual** — cada time implementa banners de cross sell de forma diferente
2. **Retrabalho** — componentes locais sao criados repetidamente para o mesmo proposito
3. **Gap de paridade** — Android tem o componente, mas Web e iOS nao

Consulta ao Redshift nao aplicavel: feature de criacao de componente no Design System, sem track record de uso de usuario ou metricas de fluxo existente para levantar baseline.

---

## 2. Objetivo

Criar e disponibilizar o componente **Banner** no Ocean Design System para as tres plataformas (Web, iOS, Android), conforme as variants e especificacoes do handoff no Figma, garantindo:

1. Componente reutilizavel e configuravel via props/parametros em todas as plataformas
2. Paridade visual e comportamental entre Web, iOS e Android
3. Disponibilizacao para consumo imediato pelos times de produto para cross sell e comunicacao promocional em qualquer tela/fluxo do portal Blu

---

## 3. Personas Impactadas

| Persona | Papel | Impacto |
|---|---|---|
| Times de Desenvolvimento (Frontend/Mobile) | Consumidores do componente | Ganham componente padronizado para uso em qualquer tela/fluxo de cross sell |
| Time de Design | Mantenedores do Ocean DS | Componente Figma passa a ter implementacao correspondente nas 3 plataformas |
| Supplier (Industria) | Usuario final indireto | Vera banners promocionais consistentes em todas as plataformas |
| Retailer (Varejo) | Usuario final indireto | Vera banners promocionais consistentes em todas as plataformas |

---

## 4. Escopo

### Dentro do Escopo (In Scope)
- Implementacao do componente Banner no repositorio Ocean **Web** (ocean-react) com todas as variants do Figma
- Implementacao do componente Banner no repositorio Ocean **iOS** (ocean-ios) em SwiftUI
- Revisao/alinhamento do componente `OceanBanner` existente no repositorio Ocean **Android** com as variants atuais do Figma
- Todas as variants de `size` (Large, Small) e `type` (Default, Warning, Negative, Emphasys)
- Propriedades configuráveis: title, description, caption, image, backgroundColor, buttons (array de ButtonProperties)
- Documentacao do componente (props, exemplos de uso) em cada plataforma
- Stories (Storybook) para Web
- Testes unitarios (Web)
- View de exemplo no app de exemplo de cada plataforma (iOS/Android) para visualizar o componente na lista de componentes
- Acessibilidade (a11y) conforme padroes do Ocean DS
- Responsividade (Web) e adaptacao a diferentes tamanhos de tela (iOS/Android)

### Fora do Escopo (Out of Scope)
- Implementacao de banners especificos de produto (ex: Credit Upsell Banner, Contextual Hero Banner) — sao componentes locais/Blu Components, nao Ocean DS
- Logica de negocio de cross sell (quais banners exibir, para quem, quando) — responsabilidade das features que consomem o componente
- Integracao com backend/BFF para conteudo dinamico dos banners
- Variantes deprecated do Figma (Banner / Mobile Full-width, Banner / Mobile Card)

### Fases Futuras
- Carousel de banners para rotacao entre multiplos banners na mesma posicao
- Animacoes de entrada/saida do componente
- Variante "Banner Product" e "E-mail Banner" de outras libraries do Figma

---

## 5. Fluxos e Comportamento Esperado

> :warning: Secao parcial na v0 — sera detalhada com os fluxos do Figma na v1.

### Fluxo Principal (conhecido via Jira e Knowledge Base)

O Banner e um componente de UI estatico (nao envolve fluxo de navegacao). Seu comportamento e:

1. Time de produto define onde o Banner sera exibido (home, dashboard, dentro de fluxo especifico)
2. Desenvolvedor instancia o componente Banner com as props adequadas (size, type, title, description, caption, image, backgroundColor, buttons)
3. Componente renderiza conforme a combinacao de props
4. Usuario visualiza o Banner na tela
5. Se o Banner tem botoes (via array de `ButtonProperties`), usuario pode clicar e ser redirecionado para o fluxo de cross sell

**Resultado esperado:** Banner exibido corretamente, responsivo, acessivel, com interacao no CTA funcionando.

### Layouts Conhecidos

**Size=Large (imagem em cima)**
```
+----------------------------+
|                            |
|        [Imagem]            |
|                            |
+----------------------------+
| Titulo                     |
| Descricao                  |
| Caption                    |
|                            |
| [Button 1]  [Button 2]     |
+----------------------------+
```

**Size=Large (sem imagem)**
```
+----------------------------+
| Titulo                     |
| Descricao                  |
| Caption                    |
|                            |
| [Button 1]  [Button 2]     |
+----------------------------+
```

**Size=Small (imagem a direita)**
```
+--------------------+-------+
| Titulo             |       |
| Descricao          |  img  |
| Caption            |       |
| [Button 1]         |       |
+--------------------+-------+
```

**Size=Small (sem imagem)**
```
+----------------------------+
| Titulo                     |
| Descricao                  |
| Caption                    |
|                            |
| [Button 1]                 |
+----------------------------+
```

### Estados de UI
> :warning: A ser detalhado na v1 com base no handoff do Figma.

Estados conhecidos pela knowledge base:
- **Default:** Banner renderizado com conteudo estatico
- **Com imagem / Sem imagem:** controlado pela presenca ou ausencia da prop `image` (se `image` e nil/null, imagem nao e exibida)
- **Com descricao / Sem descricao:** controlado pela presenca ou ausencia da prop `description`
- **Com caption / Sem caption:** controlado pela presenca ou ausencia da prop `caption`
- **Com botoes / Sem botoes:** controlado pelo array de `ButtonProperties` (se vazio ou nil, nenhum botao e exibido)
- **Comportamento:** Nao dismissivel — permanece visivel ate que a condicao que o gerou mude

---

## 6. Componentes do Ocean Design System

> :warning: Secao a ser preenchida na v1 com base no handoff do Figma.

### Mapeamento Preliminar por Plataforma (via Knowledge Base)

| Plataforma | Status Atual | Componente | Observacao |
|---|---|---|---|
| Web (ocean-react) | Nao existe | `Banner` (a criar) | Novo componente — nao ha implementacao atual |
| iOS (ocean-ios) | Nao existe como componente dedicado | `Banner` (a criar em SwiftUI) | `InformativeCard` (UIKit legado) e `CardGroup` cobrem parcialmente, mas nao sao Banner |
| Android (ocean-android) | Existe | `OceanBanner` (Compose) | Ja implementado com Neutral/Brand/Warning/Custom + Large/Small. Revisar alinhamento com Figma atual |

### Referencia da Implementacao Android Existente

```kotlin
// API existente em Android (a ser revisada para alinhar com Figma)
OceanBanner(
    modifier: Modifier,
    style: OceanBannerStyle,       // Neutral | Brand | Warning | Custom
    kind: OceanBannerKind,         // Large(image) | Small(image?)
    title: String,
    description: String = "",
    ctaTitle: String = "",
    onCtaClick: () -> Unit = {},
    ctaIsEnabled: Boolean = true
)
```

### Modelo de Props Sugerido (todas as plataformas)

```
Banner(
    size: Large | Small,
    type: Default | Warning | Negative | Emphasys,
    title: String,
    description: String?,           // opcional — se nil/null, nao exibe descricao
    caption: String?,               // opcional — se nil/null, nao exibe caption
    image: Image?,                  // opcional — se nil/null, nao exibe imagem. Suporta URL remota (Web/Android)
    backgroundColor: Color?,        // opcional — para customizacao
    buttons: [ButtonProperties]     // array de botoes — se vazio, nao exibe botoes. Segue padrao existente no ocean-ios/android (OceanSwiftUI.ButtonProperties)
)
```

> **Nota:** O controle de visibilidade de `description`, `caption`, `image` e `buttons` e feito pela presenca/ausencia do valor (nao por flags `showX`). Isso segue o padrao existente nos componentes Ocean.

---

## 7. Requisitos Funcionais

| ID | Requisito | Prioridade |
|---|---|---|
| RF-01 | Implementar componente Banner em ocean-react (Web) com variants Large e Small | Must Have |
| RF-02 | Implementar componente Banner em ocean-ios (SwiftUI) com variants Large e Small | Must Have |
| RF-03 | Revisar/alinhar `OceanBanner` em ocean-android com Figma atual | Must Have |
| RF-04 | Suportar types: Default, Warning, Negative, Emphasys em todas as plataformas | Must Have |
| RF-05 | Props configuráveis: title, description, caption, image (opcional — se presente mostra, se ausente oculta), backgroundColor, buttons (array de ButtonProperties — se vazio nao mostra botoes) | Must Have |
| RF-06 | Estilo dos botoes derivado automaticamente do type (ex: Brand → SecondarySmall inverse). Botoes definidos via array de ButtonProperties seguindo padrao existente no ocean-ios/android | Must Have |
| RF-07 | Suportar imagem customizada (substituir placeholder) em todas as plataformas, incluindo imagens remotas via URL (Web e Android) | Must Have |
| RF-08 | Criar Stories (Storybook) para Web com Default + 1 story por variante/estado principal | Must Have |
| RF-09 | Criar documentacao no Docusaurus (ocean-docs) para o componente Web | Must Have |
| RF-10 | Atualizar CHANGELOG.md dos pacotes alterados | Must Have |
| RF-11 | Garantir que o componente pode ser instanciado em qualquer tela/fluxo do portal Blu | Must Have |
| RF-12 | Criar view de exemplo no app de exemplo de cada plataforma (iOS/Android) para visualizar o Banner na lista de componentes | Must Have |

*Classificacao MoSCoW — Must Have: imprescindivel para o lancamento; Should Have: importante mas nao bloqueante; Could Have (Nice to Have): valor agregado, fica para depois se faltar tempo; Won't Have: explicitamente fora do escopo desta entrega.*

---

## 8. Requisitos Nao Funcionais

| ID | Categoria | Requisito |
|---|---|---|
| RNF-01 | Acessibilidade | Componente deve seguir padroes de a11y do Ocean DS: labels acessiveis nos botoes, alt text para imagens, suporte a screen readers |
| RNF-02 | Responsividade | Banner Web deve adaptar-se a diferentes larguras de viewport (desktop, tablet, mobile) |
| RNF-03 | Adaptacao Mobile | Banner iOS e Android devem adaptar-se a diferentes tamanhos de tela e orientacoes |
| RNF-04 | Performance | Componente nao deve impactar o tempo de renderizacao da tela (< 16ms por frame) |
| RNF-05 | Compatibilidade | Web: React 18.x. iOS: SwiftUI (versao minima do projeto). Android: Jetpack Compose |
| RNF-06 | Consistencia Visual | Componente deve utilizar tokens do Ocean DS (cores, tipografia, espacamento, border-radius) — nao valores hardcoded |
| RNF-07 | Testes | Cobertura de testes unitarios para Web. iOS e Android nao requerem testes unitarios para componentes DS |

---

## 9. Regras de Negocio

| ID | Regra | Observacao |
|---|---|---|
| RN-01 | Banner nao e dismissivel — permanece visivel ate que a condicao que o gerou mude | Conforme knowledge base: se o usuario pode fechar, e um Alert com button, nao um Banner |
| RN-02 | Banner e posicionado dentro do conteudo da pagina, nao fixo no topo do viewport | Posicao definida pela hierarquia da informacao na tela |
| RN-03 | Nao empilhar multiplos Banners na mesma tela — priorizar o mais relevante ou usar Carousel | Anti-padrao documentado na knowledge base |
| RN-04 | Banner sem nenhum botao (array de buttons vazio) deve ser avaliado — se nao tem CTA, considerar se a informacao deveria ser Alert ou Typography | Anti-padrao documentado na knowledge base |
| RN-05 | Banner para comunicar erros ou avisos de sistema deve usar Alert, nao Banner | Banner e para comunicacao promocional/instrucional |
| RN-06 | Type Negative e para comunicacao de negocio (inadimplencia, risco), nao para erros tecnicos | Conforme knowledge base |
| RN-07 | Web: importacao via Module Federation do mfe-core — `import { Banner } from 'core/ocean-react'` | Conforme padrao de MFEs da Blu |

---

## 10. Criterios de Aceite

> :warning: Secao parcial na v0 — criterios de UI/UX serao adicionados na v1.

### CA-01: Componente Banner implementado em Web (ocean-react)
- **Dado que** o componente Banner nao existe em ocean-react
- **Quando** o desenvolvedor importa o Banner de `@useblu/ocean-react`
- **Entao** o componente e renderizado corretamente com as variants Large e Small, types Default/Warning/Negative/Emphasys, e todas as props configuraveis (title, description, caption, image, backgroundColor, buttons)

### CA-02: Componente Banner implementado em iOS (ocean-ios)
- **Dado que** nao existe `OceanSwiftUI.Banner`
- **Quando** o desenvolvedor instancia `OceanSwiftUI.Banner` em SwiftUI
- **Entao** o componente e renderizado corretamente com paridade visual ao Web e Android

### CA-03: Componente Banner alinhado em Android (ocean-android)
- **Dado que** `OceanBanner` ja existe em Compose
- **Quando** comparado com as variants atuais do Figma
- **Entao** o componente esta alinhado — qualquer divergencia identificada foi corrigida

### CA-04: Paridade visual entre plataformas
- **Dado que** o mesmo Banner (size + type) e renderizado em Web, iOS e Android
- **Quando** comparado visualmente
- **Entao** o resultado e visualmente consistente (respeitando convencoes nativas de cada plataforma)

### CA-05: Documentacao e Stories
- **Dado que** o componente Banner foi implementado em Web
- **Quando** o desenvolvedor acessa Storybook e ocean-docs
- **Entao** existe documentacao completa (props, exemplos de uso) e stories cobrindo todas as variants

### CA-06: Testes unitarios (Web)
- **Dado que** o componente Banner foi implementado em Web
- **Quando** a suite de testes e executada
- **Entao** todos os testes passam cobrindo as combinacoes relevantes de props

### CA-07: View de exemplo nos apps de exemplo (iOS/Android)
- **Dado que** o componente Banner foi implementado em iOS e Android
- **Quando** o desenvolvedor abre o app de exemplo da plataforma
- **Entao** o Banner aparece na lista de componentes com exemplos de todas as variants

---

## 11. Cenarios de Teste

> :warning: Secao parcial na v0 — cenarios de UI serao adicionados na v1.

| ID | Tipo | Cenario | Dados de Entrada | Resultado Esperado |
|---|---|---|---|---|
| CT-01 | Happy Path | Banner Large Default com todas as props | size=Large, type=Default, title="Titulo", description="Desc", caption="Caption", image=placeholder, buttons=[primary] | Banner renderizado com imagem em cima, titulo, descricao, caption e botao primario azul |
| CT-02 | Happy Path | Banner Small Warning sem imagem | size=Small, type=Warning, title="Atencao", image=nil, buttons=[primary] | Banner compacto com fundo laranja claro, sem imagem, com CTA laranja |
| CT-03 | Variante | Banner Emphasys com 2 botoes | size=Large, type=Emphasys, buttons=[primary, tertiary] | Fundo azul escuro, botao secondary branco + botao terciario |
| CT-04 | Edge Case | Banner sem descricao e sem imagem | description=nil, image=nil, buttons=[primary] | Apenas titulo + botao, layout compacto |
| CT-05 | Edge Case | Banner sem nenhum botao | buttons=[] | Banner exibe apenas conteudo informativo (titulo + descricao + imagem) |
| CT-09 | Edge Case | Banner Large sem imagem | size=Large, image=nil, title="Titulo", description="Desc" | Banner Large sem area de imagem, conteudo ocupa toda a area |
| CT-06 | Responsividade | Banner Large em viewport mobile (< 768px) | size=Large, viewport width 375px | Banner adapta-se corretamente sem quebra de layout |
| CT-07 | Acessibilidade | Navegacao por teclado e screen reader no Banner Web | Tab, Enter, VoiceOver/TalkBack | Botoes focaveis, imagem com alt text, titulo anunciado |
| CT-08 | Paridade | Mesmo Banner renderizado em Web, iOS e Android | size=Large, type=Default, mesmas props | Resultado visualmente consistente entre plataformas |

---

## 12. Estrategia de Rollout e Feature Flag

| Campo | Valor |
|---|---|
| Requer feature flag? | Nao |
| Justificativa | Componente de Design System — nao altera comportamento de features existentes. Disponibilizado via nova versao do pacote Ocean DS |
| Rollout | Publicacao de nova versao dos pacotes ocean-react, ocean-ios e ocean-android. Times de produto adotam conforme necessidade |
| Plano de rollback | Reverter versao do pacote Ocean DS caso haja bug critico |

---

## 13. Metricas de Sucesso (KPIs)

| Metrica | Baseline Atual | Meta | Prazo de Avaliacao |
|---|---|---|---|
| Adocao do componente Banner por MFEs/apps | 0 (nao existe em Web/iOS) | >= 3 MFEs/apps usando o componente | 90 dias apos publicacao |
| Reducao de componentes ad-hoc de banner no codebase | A ser medido | Eliminacao de banners ad-hoc em favor do componente padronizado | 6 meses |
| Paridade de componentes entre plataformas (categoria Instructional) | 1/3 plataformas (apenas Android) | 3/3 plataformas | Ao final da entrega |

---

## 14. Dependencias

| Dependencia | Tipo | Status | Responsavel |
|---|---|---|---|
| Handoff do Figma com variants e especificacoes completas | Interna | Disponivel (links no card Jira) | Time de Design |
| Repositorio ocean-web (ocean-react) | Interna | Disponivel | Squad Design System |
| Repositorio ocean-ios | Interna | Disponivel | Squad Design System |
| Repositorio ocean-android | Interna | Disponivel (OceanBanner ja existe) | Squad Design System |
| Review do code review por membro do time | Interna | Pendente | Squad Design System |

---

## 15. Riscos e Consideracoes

| Risco | Probabilidade | Impacto | Mitigacao |
|---|---|---|---|
| Divergencia entre Figma e implementacao Android existente | Media | Medio | Comparar OceanBanner Android com Figma atual na Fase 2. Documentar divergencias |
| iOS nao tem componente Banner e alternativas existentes (InformativeCard/CardGroup) tem API diferente | Alta | Medio | Implementar Banner como componente SwiftUI novo, sem tentar adaptar componentes existentes |
| Novos componentes podem gerar breaking changes se API nao for bem definida | Baixa | Alto | Seguir padroes de API ja estabelecidos no Android (referencia) e Figma (fonte de verdade) |
| Inconsistencia de tokens de design entre plataformas | Media | Medio | Usar tokens oficiais do Ocean DS documentados na knowledge base |

---

## 16. Pontos em Aberto (Open Questions)

### Resolvidos (v0.2)

| ID | Pergunta | Resolucao |
|---|---|---|
| ~~OQ-01~~ | O componente `OceanBanner` Android deve suportar 2 botoes (show1stAction + show2ndAction)? | **Sim.** Deve suportar 2 botoes em todas as plataformas. |
| ~~OQ-02~~ | O componente iOS deve ser criado em SwiftUI ou tambem em UIKit? | **SwiftUI.** O projeto blu-mobile-ios usa `ocean-ios` (v3.8.1703) via Swift Package. Ambos SwiftUI (`OceanSwiftUI`) e UIKit (`OceanComponents`) sao usados no projeto, mas SwiftUI e o padrao moderno. O componente sera implementado em SwiftUI, como `OceanSwiftUI.Banner`. |
| ~~OQ-03~~ | O type `Negative` esta implementado no Android? | **Deve ser implementado em todas as plataformas** — Web, iOS e Android. |
| ~~OQ-04~~ | Suporte a imagens remotas (URL) no Web? | **Sim.** Suporte a imagens remotas em Web e Android. |
| ~~OQ-05~~ | Politica de versionamento (major/minor/patch)? | **Sem politica de versionamento especifica.** |

### Em Aberto

| ID | Pergunta | Responsavel | Prazo |
|---|---|---|---|
| OQ-06 | Detalhamento exato das variants e estados no Figma — a ser extraido na Fase 2 via MCP Figma | Claude Code + MCP Figma | Fase 2 |

---

## 17. Referencias

- **Jira (origem):** [MR-494 — [Ocean] Web/iOS/Android - Criar componente Banner](https://useblu.atlassian.net/browse/MR-494)
- **GitHub Issue (PRD):** [a ser criado ao final desta fase]
- **Figma — Variants:** [Ocean DS Core (Variants)](https://www.figma.com/design/PgLv9k22CHHZZ867HwN65y/%F0%9F%8C%8A-Ocean-DS-Core?node-id=22177-3976&t=IP6gXHxTgDfOE9gg-4)
- **Figma — Handoff:** [Ocean DS Core (Handoff)](https://www.figma.com/design/PgLv9k22CHHZZ867HwN65y/%F0%9F%8C%8A-Ocean-DS-Core?node-id=24332-69742&t=IP6gXHxTgDfOE9gg-4)
- **Knowledge bases lidas:**
  - `CLAUDE.md` — Regras gerais da knowledge base
  - `conventions/ocean-ds.md` — Convencoes do Ocean DS Web
  - `conventions/ocean-ds-contribution.md` — Regras de contribuicao ao ocean-web
  - `conventions/ocean-ds-ios.md` — Convencoes do Ocean DS iOS
  - `conventions/ocean-android.md` — Convencoes do Ocean DS Android
  - `conventions/ux-best-practices.md` — Diretrizes de UX
  - `skills/create-prd.md` — Playbook de geracao de PRD
  - `ux-knowledge-layer/components/decision-tree/decision-tree.md` — Arvore de decisao de componentes
  - `ux-knowledge-layer/components/usage-guidelines/usage-guidelines-instructional.md` — Guidelines de componentes instrucionais (inclui Banner)
  - `ux-knowledge-layer/components/usage-guidelines-ios/instructional.md` — Guidelines iOS instrucionais
  - `ux-knowledge-layer/components/usage-guidelines-android/instructional.md` — Guidelines Android instrucionais
  - `ux-knowledge-layer/components/usage-guidelines-blu/usage-guidelines-blu.md` — Componentes Blu
- **Documentos relacionados:**
  - Ocean DS Web docs: https://ocean-ds.github.io/ocean-web/docs/
  - Ocean DS Icons: https://github.com/ocean-ds/ocean-icons
- **Arquivos identificados no codebase:**
  - Android: `OceanBanner` Composable com `OceanBannerStyle` (Neutral/Brand/Warning/Custom) e `OceanBannerKind` (Large/Small)
  - iOS: `Ocean.InformativeCard` (UIKit legado), `OceanSwiftUI.CardGroup` (SwiftUI) — nao ha Banner dedicado
  - Web: Nenhum componente Banner em ocean-react
- **Prompt do Devin:** [https://app.devin.ai/sessions/32419d06853b4182b406752bcc134115](https://app.devin.ai/sessions/32419d06853b4182b406752bcc134115)


ID	Pergunta	Resolucao
~~OQ-01~~	O componente `OceanBanner` Android deve suportar 2 botoes (show1stAction + show2ndAction)?	Sim. Deve suportar 2 botoes em todas as plataformas.
~~OQ-02~~	O componente iOS deve ser criado em SwiftUI ou tambem em UIKit?	SwiftUI. O projeto blu-mobile-ios usa `ocean-ios` (v3.8.1703) via Swift Package. Ambos SwiftUI (`OceanSwiftUI`) e UIKit (`OceanComponents`) sao usados no projeto, mas SwiftUI e o padrao moderno. O componente sera implementado em SwiftUI, como `OceanSwiftUI.Banner`.
~~OQ-03~~	O type `Negative` esta implementado no Android?	Deve ser implementado em todas as plataformas — Web, iOS e Android.
~~OQ-04~~	Suporte a imagens remotas (URL) no Web?	Sim. Suporte a imagens remotas em Web e Android.
~~OQ-05~~	Politica de versionamento (major/minor/patch)?	Sem politica de versionamento especifica.

Persona	Papel	Impacto
Times de Desenvolvimento (Frontend/Mobile)	Consumidores do componente	Ganham componente padronizado para uso em qualquer tela/fluxo de cross sell
Time de Design	Mantenedores do Ocean DS	Componente Figma passa a ter implementacao correspondente nas 3 plataformas
Supplier (Industria)	Usuario final indireto	Vera banners promocionais consistentes em todas as plataformas
Retailer (Varejo)	Usuario final indireto	Vera banners promocionais consistentes em todas as plataformas

Plataforma	Status Atual	Componente	Observacao
Web (ocean-react)	Nao existe	`Banner` (a criar)	Novo componente — nao ha implementacao atual
iOS (ocean-ios)	Nao existe como componente dedicado	`Banner` (a criar em SwiftUI)	`InformativeCard` (UIKit legado) e `CardGroup` cobrem parcialmente, mas nao sao Banner
Android (ocean-android)	Existe	`OceanBanner` (Compose)	Ja implementado com Neutral/Brand/Warning/Custom + Large/Small. Revisar alinhamento com Figma atual

ID	Requisito	Prioridade
RF-01	Implementar componente Banner em ocean-react (Web) com variants Large e Small	Must Have
RF-02	Implementar componente Banner em ocean-ios (SwiftUI) com variants Large e Small	Must Have
RF-03	Revisar/alinhar `OceanBanner` em ocean-android com Figma atual	Must Have
RF-04	Suportar types: Default, Warning, Negative, Emphasys em todas as plataformas	Must Have
RF-05	Props configuráveis: title, description, caption, image (opcional — se presente mostra, se ausente oculta), backgroundColor, buttons (array de ButtonProperties — se vazio nao mostra botoes)	Must Have
RF-06	Estilo dos botoes derivado automaticamente do type (ex: Brand → SecondarySmall inverse). Botoes definidos via array de ButtonProperties seguindo padrao existente no ocean-ios/android	Must Have
RF-07	Suportar imagem customizada (substituir placeholder) em todas as plataformas, incluindo imagens remotas via URL (Web e Android)	Must Have
RF-08	Criar Stories (Storybook) para Web com Default + 1 story por variante/estado principal	Must Have
RF-09	Criar documentacao no Docusaurus (ocean-docs) para o componente Web	Must Have
RF-10	Atualizar CHANGELOG.md dos pacotes alterados	Must Have
RF-11	Garantir que o componente pode ser instanciado em qualquer tela/fluxo do portal Blu	Must Have
RF-12	Criar view de exemplo no app de exemplo de cada plataforma (iOS/Android) para visualizar o Banner na lista de componentes	Must Have

ID	Categoria	Requisito
RNF-01	Acessibilidade	Componente deve seguir padroes de a11y do Ocean DS: labels acessiveis nos botoes, alt text para imagens, suporte a screen readers
RNF-02	Responsividade	Banner Web deve adaptar-se a diferentes larguras de viewport (desktop, tablet, mobile)
RNF-03	Adaptacao Mobile	Banner iOS e Android devem adaptar-se a diferentes tamanhos de tela e orientacoes
RNF-04	Performance	Componente nao deve impactar o tempo de renderizacao da tela (< 16ms por frame)
RNF-05	Compatibilidade	Web: React 18.x. iOS: SwiftUI (versao minima do projeto). Android: Jetpack Compose
RNF-06	Consistencia Visual	Componente deve utilizar tokens do Ocean DS (cores, tipografia, espacamento, border-radius) — nao valores hardcoded
RNF-07	Testes	Cobertura de testes unitarios para Web. iOS e Android nao requerem testes unitarios para componentes DS

ID	Regra	Observacao
RN-01	Banner nao e dismissivel — permanece visivel ate que a condicao que o gerou mude	Conforme knowledge base: se o usuario pode fechar, e um Alert com button, nao um Banner
RN-02	Banner e posicionado dentro do conteudo da pagina, nao fixo no topo do viewport	Posicao definida pela hierarquia da informacao na tela
RN-03	Nao empilhar multiplos Banners na mesma tela — priorizar o mais relevante ou usar Carousel	Anti-padrao documentado na knowledge base
RN-04	Banner sem nenhum botao (array de buttons vazio) deve ser avaliado — se nao tem CTA, considerar se a informacao deveria ser Alert ou Typography	Anti-padrao documentado na knowledge base
RN-05	Banner para comunicar erros ou avisos de sistema deve usar Alert, nao Banner	Banner e para comunicacao promocional/instrucional
RN-06	Type Negative e para comunicacao de negocio (inadimplencia, risco), nao para erros tecnicos	Conforme knowledge base
RN-07	Web: importacao via Module Federation do mfe-core — `import { Banner } from 'core/ocean-react'`	Conforme padrao de MFEs da Blu

ID	Tipo	Cenario	Dados de Entrada	Resultado Esperado
CT-01	Happy Path	Banner Large Default com todas as props	size=Large, type=Default, title="Titulo", description="Desc", caption="Caption", image=placeholder, buttons=[primary]	Banner renderizado com imagem em cima, titulo, descricao, caption e botao primario azul
CT-02	Happy Path	Banner Small Warning sem imagem	size=Small, type=Warning, title="Atencao", image=nil, buttons=[primary]	Banner compacto com fundo laranja claro, sem imagem, com CTA laranja
CT-03	Variante	Banner Emphasys com 2 botoes	size=Large, type=Emphasys, buttons=[primary, tertiary]	Fundo azul escuro, botao secondary branco + botao terciario
CT-04	Edge Case	Banner sem descricao e sem imagem	description=nil, image=nil, buttons=[primary]	Apenas titulo + botao, layout compacto
CT-05	Edge Case	Banner sem nenhum botao	buttons=[]	Banner exibe apenas conteudo informativo (titulo + descricao + imagem)
CT-09	Edge Case	Banner Large sem imagem	size=Large, image=nil, title="Titulo", description="Desc"	Banner Large sem area de imagem, conteudo ocupa toda a area
CT-06	Responsividade	Banner Large em viewport mobile (< 768px)	size=Large, viewport width 375px	Banner adapta-se corretamente sem quebra de layout
CT-07	Acessibilidade	Navegacao por teclado e screen reader no Banner Web	Tab, Enter, VoiceOver/TalkBack	Botoes focaveis, imagem com alt text, titulo anunciado
CT-08	Paridade	Mesmo Banner renderizado em Web, iOS e Android	size=Large, type=Default, mesmas props	Resultado visualmente consistente entre plataformas

Campo	Valor
Requer feature flag?	Nao
Justificativa	Componente de Design System — nao altera comportamento de features existentes. Disponibilizado via nova versao do pacote Ocean DS
Rollout	Publicacao de nova versao dos pacotes ocean-react, ocean-ios e ocean-android. Times de produto adotam conforme necessidade
Plano de rollback	Reverter versao do pacote Ocean DS caso haja bug critico

Metrica	Baseline Atual	Meta	Prazo de Avaliacao
Adocao do componente Banner por MFEs/apps	0 (nao existe em Web/iOS)	>= 3 MFEs/apps usando o componente	90 dias apos publicacao
Reducao de componentes ad-hoc de banner no codebase	A ser medido	Eliminacao de banners ad-hoc em favor do componente padronizado	6 meses
Paridade de componentes entre plataformas (categoria Instructional)	1/3 plataformas (apenas Android)	3/3 plataformas	Ao final da entrega

Dependencia	Tipo	Status	Responsavel
Handoff do Figma com variants e especificacoes completas	Interna	Disponivel (links no card Jira)	Time de Design
Repositorio ocean-web (ocean-react)	Interna	Disponivel	Squad Design System
Repositorio ocean-ios	Interna	Disponivel	Squad Design System
Repositorio ocean-android	Interna	Disponivel (OceanBanner ja existe)	Squad Design System
Review do code review por membro do time	Interna	Pendente	Squad Design System

Risco	Probabilidade	Impacto	Mitigacao
Divergencia entre Figma e implementacao Android existente	Media	Medio	Comparar OceanBanner Android com Figma atual na Fase 2. Documentar divergencias
iOS nao tem componente Banner e alternativas existentes (InformativeCard/CardGroup) tem API diferente	Alta	Medio	Implementar Banner como componente SwiftUI novo, sem tentar adaptar componentes existentes
Novos componentes podem gerar breaking changes se API nao for bem definida	Baixa	Alto	Seguir padroes de API ja estabelecidos no Android (referencia) e Figma (fonte de verdade)
Inconsistencia de tokens de design entre plataformas	Media	Medio	Usar tokens oficiais do Ocean DS documentados na knowledge base

PRD — Componente Banner no Ocean Design System (Web/iOS/Android) #1250

Description

PRD — Componente Banner no Ocean Design System (Web/iOS/Android)

1. Contexto e Problema

2. Objetivo

3. Personas Impactadas

4. Escopo

Dentro do Escopo (In Scope)

Fora do Escopo (Out of Scope)

Fases Futuras

5. Fluxos e Comportamento Esperado

Fluxo Principal (conhecido via Jira e Knowledge Base)

Layouts Conhecidos

Estados de UI

6. Componentes do Ocean Design System

Mapeamento Preliminar por Plataforma (via Knowledge Base)

Referencia da Implementacao Android Existente

Modelo de Props Sugerido (todas as plataformas)

7. Requisitos Funcionais

8. Requisitos Nao Funcionais

9. Regras de Negocio

10. Criterios de Aceite

CA-01: Componente Banner implementado em Web (ocean-react)

CA-02: Componente Banner implementado em iOS (ocean-ios)

CA-03: Componente Banner alinhado em Android (ocean-android)

CA-04: Paridade visual entre plataformas

CA-05: Documentacao e Stories

CA-06: Testes unitarios (Web)

CA-07: View de exemplo nos apps de exemplo (iOS/Android)

11. Cenarios de Teste

12. Estrategia de Rollout e Feature Flag

13. Metricas de Sucesso (KPIs)

14. Dependencias

15. Riscos e Consideracoes

16. Pontos em Aberto (Open Questions)

Resolvidos (v0.2)

Em Aberto

17. Referencias

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions