Skip to content

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

Open
Open
PRD — Componente Banner no Ocean Design System (Web/iOS/Android)#1247
@devin-ai-integration

Description

@devin-ai-integration
devin-ai-integration
bot
opened on May 25, 2026

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

Jira: MR-494
Figma: Ocean DS Core — Variants · Handoff
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.2

Originado do card Jira: MR-494 — [Ocean] Web/iOS/Android - Criar componente Banner

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-ds-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, showDescription, image, showImage, show1stAction, show2ndAction
  • Documentacao do componente (props, exemplos de uso) em cada plataforma
  • Stories (Storybook) para Web
  • Testes unitarios
  • 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

⚠️ 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, image, acoes)
  3. Componente renderiza conforme a combinacao de props
  4. Usuario visualiza o Banner na tela
  5. Se o Banner tem CTA (botao primario e/ou terciario), 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                  |
|                            |
| [Primary]  [Tertiary]      |
+----------------------------+

Size=Small (imagem a direita)

+--------------------+-------+
| Titulo             |       |
| Descricao          |  img  |
|                    |       |
| [Primary]          |       |
+--------------------+-------+

Estados de UI

⚠️ 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: showImage controla visibilidade
  • Com descricao / Sem descricao: showDescription controla visibilidade
  • Com 1 acao / Com 2 acoes / Sem acoes: show1stAction e show2ndAction controlam
  • Comportamento: Nao dismissivel — permanece visivel ate que a condicao que o gerou mude

6. Componentes do Ocean Design System

⚠️ 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-ds-android) Existe OceanBanner (Compose) Ja implementado com Neutral/Brand/Warning/Custom + Large/Small. Revisar alinhamento com Figma atual

Referencia da Implementacao Android Existente

// API existente em Android
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
)

7. Plano de Tracking de Eventos (blu-lytics)

⚠️ Secao parcial na v0 — sera detalhada na v1 com os eventos mapeados por fluxo de tela.

Padroes identificados nos repositorios de tracking:

  • blu-lytics (Web/TypeScript):

    • sendCustomEvent(eventName: string, properties: { [key: string]: string | boolean | number }) — evento customizado com propriedades
    • sendScreenEvent(screenName: string) — evento de visualizacao de tela
    • Ferramentas: Fullstory, Mixpanel, Clarity, Sentry
    • Propriedades default podem ser setadas via setDefaultProperties() e sao mergeadas em todo evento

  • lytics-mobile-ios (Swift):

    • Protocolo EventType = LyticsBase & Identifiable & DataContainer
    • Providers registrados via Lytics.register(provider:)
    • Dispatchers: EventDispatcher, ScreenDispatcher, ErrorDispatcher, UserIdentificationDispatcher

  • lytics-mobile-android:

    • Repositorio vazio (apenas .git). Espera-se que siga o mesmo padrao dos demais.

Eventos ja existentes no dominio:

  • Nao ha eventos de tracking especificos para o componente Banner no codebase atual, pois o componente nao existe em Web e iOS.
  • O tracking sera definido pelas features que consomem o Banner (ex: banner_cross_sell_viewed, banner_cross_sell_clicked), nao pelo componente em si.

8. 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-ds-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, showDescription, image, showImage, show1stAction, show2ndAction Must Have
RF-06 Botao primario com estilo derivado automaticamente do type (ex: Brand → SecondarySmall inverse) 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

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.

9. 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 todas as combinacoes de props relevantes

10. 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 nenhuma acao (show1stAction=false + show2ndAction=false) 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

11. Criterios de Aceite

⚠️ 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 configuráveis

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-ds-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

  • Dado que o componente Banner foi implementado
  • Quando a suite de testes e executada
  • Entao todos os testes passam cobrindo as combinacoes relevantes de props

12. Cenarios de Teste

⚠️ Secao parcial na v0 — cenarios de UI e tracking 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", image=placeholder, show1stAction=true Banner renderizado com imagem em cima, titulo, descricao e botao primario azul
CT-02 Happy Path Banner Small Warning sem imagem size=Small, type=Warning, title="Atencao", showImage=false, show1stAction=true Banner compacto com fundo laranja claro, sem imagem, com CTA laranja
CT-03 Variante Banner Emphasys com 2 acoes size=Large, type=Emphasys, show1stAction=true, show2ndAction=true Fundo azul escuro, botao secondary branco + botao terciario
CT-04 Edge Case Banner sem descricao e sem imagem showDescription=false, showImage=false Apenas titulo + acoes, layout compacto
CT-05 Edge Case Banner sem nenhuma acao show1stAction=false, show2ndAction=false Banner exibe apenas conteudo informativo (titulo + descricao + imagem)
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

13. 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-ds-android. Times de produto adotam conforme necessidade
Plano de rollback Reverter versao do pacote Ocean DS caso haja bug critico

14. 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

15. 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-ds-android Interna Disponivel (OceanBanner ja existe) Squad Design System
Review do code review por membro do time Interna Pendente Squad Design System

16. 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
lytics-mobile-android repo vazio — sem padrao de tracking para referencia Android Baixa Baixo Seguir padrao do blu-lytics (Web) e lytics-mobile-ios como referencia

17. 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

18. Referencias

  • Jira (origem): MR-494 — [Ocean] Web/iOS/Android - Criar componente Banner
  • GitHub Issue (PRD): [a ser criado ao final desta fase]
  • Figma — Variants: Ocean DS Core (Variants)
  • Figma — Handoff: Ocean DS Core (Handoff)
  • 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-ds-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
  • Repositorios de tracking lidos: Pagnet/blu-lytics, Pagnet/lytics-mobile-ios, Pagnet/lytics-mobile-android (vazio)
  • Documentos relacionados:
  • 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions