Como a fragmentação visual nasce em aplicativos com múltiplas squads
Em aplicativos mobile mantidos por cinco ou mais squads em paralelo, a inconsistência visual quase nunca vem de descuido individual. Ela nasce do ritmo de entrega. Uma squad precisa subir um fluxo de contratação até sexta-feira, copia o código de um botão primário de outra tela, altera o cornerRadius para bater com um protótipo novo do Figma e fixa um código hexadecimal direto no arquivo. Três sprints depois, o app tem quatro variações de botão primário, três tons ligeiramente diferentes da cor da marca e telas que ignoram completamente o ajuste de tamanho de fonte do usuário.
Quando a empresa decide corrigir a acessibilidade ou atualizar a identidade visual, descobre que precisa caçar centenas de literais espalhados por dezenas de módulos. Um Design System mobile bem governado resolve exatamente esse custo de coordenação: ele trata tokens visuais e componentes de interface como um produto interno versionado, com contratos públicos estáveis e processo claro de evolução entre Design e Engenharia.
Princípio de manutenção de longo prazo: uma biblioteca de componentes sem governança vira apenas mais uma pasta de código legado. Sem tokens semânticos, versionamento previsível e testes de regressão visual, cada squad volta a criar componentes paralelos em poucos meses.
Estruturando Design Tokens em três camadas com suporte real a acessibilidade
A base técnica de um Design System sustentável começa pela separação dos tokens em três níveis. O primeiro nível reúne os tokens primitivos, que armazenam valores puros de cor, espaçamento e escala tipográfica sem contexto de tela (por exemplo, Palette.gold500 ou Space.s16). O segundo nível define os tokens semânticos, que expressam intenção de uso (Surface.primary, Text.secondary, Action.destructive) e permitem alternar automaticamente entre tema claro, tema escuro e alto contraste. O terceiro nível traz os tokens de componente, usados apenas quando um elemento precisa de ajuste fino sem afetar o restante da interface (como o preenchimento interno de um botão compacto).
Um erro muito frequente em implementações SwiftUI e UIKit iniciais é fixar tamanhos de fonte literais como .font(.system(size: 16, weight: .bold)). Quando você fixa o tamanho em pontos sem escala dinâmica, o aplicativo ignora o Dynamic Type configurado nos ajustes de acessibilidade do iOS. Usuários com baixa visão aumentam o tamanho do texto no sistema e o botão continua minúsculo ou corta o rótulo.
Abaixo está uma modelagem de tokens em Swift que já entrega suporte a Dark Mode, alto contraste e Dynamic Type compartilhados entre UIKit e SwiftUI:
import UIKit
import SwiftUI
public enum DSTokens {
public enum Spacing {
public static let xSmall: CGFloat = 4
public static let small: CGFloat = 8
public static let medium: CGFloat = 16
public static let large: CGFloat = 24
public static let xLarge: CGFloat = 32
}
public enum Radius {
public static let small: CGFloat = 6
public static let medium: CGFloat = 10
public static let pill: CGFloat = 999
}
public enum ColorToken {
public static var surfacePrimary: UIColor {
UIColor { traits in
if traits.userInterfaceStyle == .dark {
return traits.accessibilityContrast == .high
? UIColor(red: 0.00, green: 0.01, blue: 0.02, alpha: 1.0)
: UIColor(red: 0.03, green: 0.06, blue: 0.10, alpha: 1.0)
}
return UIColor(red: 0.98, green: 0.98, blue: 0.99, alpha: 1.0)
}
}
public static var actionPrimary: UIColor {
UIColor { traits in
traits.userInterfaceStyle == .dark
? UIColor(red: 0.84, green: 0.64, blue: 0.35, alpha: 1.0)
: UIColor(red: 0.56, green: 0.39, blue: 0.17, alpha: 1.0)
}
}
public static var textOnAction: UIColor {
UIColor { traits in
traits.userInterfaceStyle == .dark ? .black : .white
}
}
}
public enum Typography {
public static func uiFont(for style: UIFont.TextStyle, weight: UIFont.Weight) -> UIFont {
let baseSize: CGFloat
switch style {
case .headline: baseSize = 16
case .body: baseSize = 15
case .caption1: baseSize = 12
default: baseSize = 15
}
let base = UIFont.systemFont(ofSize: baseSize, weight: weight)
return UIFontMetrics(forTextStyle: style).scaledFont(for: base)
}
}
}
public extension Color {
static var dsSurfacePrimary: Color { Color(uiColor: DSTokens.ColorToken.surfacePrimary) }
static var dsActionPrimary: Color { Color(uiColor: DSTokens.ColorToken.actionPrimary) }
static var dsTextOnAction: Color { Color(uiColor: DSTokens.ColorToken.textOnAction) }
} Centralizar a resolução dinâmica no UIColor e expor extensões finas para SwiftUI.Color garante que um rebranding ou ajuste de contraste em um único arquivo atualize telas antigas em UIKit e telas novas em SwiftUI ao mesmo tempo, sem divergência de tonalidade.
Coexistência entre UIKit (ViewCode) e SwiftUI sem duplicar regras
Quase todo aplicativo iOS corporativo com mais de três anos de estrada vive uma transição longa: o núcleo transacional continua em UIKit com ViewCode, enquanto jornadas novas já nascem em SwiftUI. O dilema do time de Design System é decidir se mantém implementações paralelas ou se envelopa componentes SwiftUI dentro de UIHostingController para servir ao UIKit.
A resposta pragmática que aprendi em produção é não forçar um único caminho para tudo. Para componentes atômicos usados dentro de listas longas (botões, badges, inputs e linhas de extrato dentro de UITableViewCell ou UICollectionViewCell), manter uma especificação visual compartilhada (DSButtonSpec) com implementações nativas enxutas em UIKit e SwiftUI evita problemas de scroll engasgado e recálculo incorreto de altura do UIHostingController em versões mais antigas do iOS. Já para componentes compostos que aparecem uma vez por tela (como banners promocionais, cards de resumo ou bottom sheets), renderizar uma view SwiftUI via UIHostingConfiguration (iOS 16+) reduz bastante o código duplicado.
import SwiftUI
public struct DSButtonConfiguration: Equatable {
public let verticalPadding: CGFloat
public let cornerRadius: CGFloat
public let minHeight: CGFloat
public static let primary = DSButtonConfiguration(
verticalPadding: DSTokens.Spacing.medium,
cornerRadius: DSTokens.Radius.medium,
minHeight: 48
)
}
public struct DSPrimaryButton: View {
private let title: String
private let isLoading: Bool
private let action: () -> Void
private let config: DSButtonConfiguration
public init(
title: String,
isLoading: Bool = false,
config: DSButtonConfiguration = .primary,
action: @escaping () -> Void
) {
self.title = title
self.isLoading = isLoading
self.config = config
self.action = action
}
public var body: some View {
Button(action: action) {
HStack(spacing: DSTokens.Spacing.small) {
if isLoading {
ProgressView()
.tint(.dsTextOnAction)
}
Text(title)
.font(.headline)
.multilineTextAlignment(.center)
.lineLimit(2)
}
.foregroundStyle(Color.dsTextOnAction)
.frame(maxWidth: .infinity, minHeight: config.minHeight)
.padding(.horizontal, DSTokens.Spacing.medium)
.padding(.vertical, config.verticalPadding)
.background(Color.dsActionPrimary)
.clipShape(RoundedRectangle(cornerRadius: config.cornerRadius, style: .continuous))
}
.disabled(isLoading)
.accessibilityLabel(isLoading ? "\(title), carregando" : title)
}
} Repare na altura mínima de 48 pontos (acima dos 44 pt mínimos recomendados pela Apple para área de toque), no lineLimit(2) para não truncar palavras quando o usuário ativa texto gigante no Dynamic Type e no estado explícito de VoiceOver durante o carregamento. São detalhes simples que elevam muito a qualidade percebida do produto.
Modelos de governança: qual estrutura evita gargalo?
Código bom não basta se o processo de contribuição trava as squads. Quando o time central vira um cartório que leva três sprints para aprovar uma variação de input, as squads dão um jeito de contornar a biblioteca e copiam o componente localmente. Por outro lado, liberar commits sem revisão nenhuma transforma o pacote em um depósito de casos específicos impossível de manter.
| Modelo de governança | Como opera | Vantagem principal | Principal ponto de falha |
|---|---|---|---|
| Centralizado | Um time dedicado constrói e mantém 100% dos componentes | Alta consistência visual e API muito coesa | Vira gargalo rápido quando mais de 6 squads demandam novidades |
| Federado puro | Cada squad contribui direto no repositório sem time fixo | Baixo custo de estrutura e entregas locais rápidas | Falta dono para dívida técnica, acessibilidade e migrações de iOS |
| Híbrido (Core + Contribuição via RFC) | Núcleo pequeno cuida de tokens, arquitetura e revisão; squads enviam PRs com RFC curta | Equilibra consistência com escala entre 10 ou mais squads | Exige SLA claro de revisão de PR (ex.: até 24h úteis) para não travar entregas |
No modelo híbrido, uma regra simples poupa muitas discussões: um padrão só sobe para o Design System central se for usado por pelo menos duas jornadas diferentes ou fizer parte da identidade básica do aplicativo. Componentes muito específicos de um único fluxo continuam vivendo dentro do pacote da própria feature, aproveitando os tokens semânticos globais. Essa fronteira conversa diretamente com o isolamento de pacotes explicado em arquitetura modular e deeplinks em apps iOS.
Versionamento semântico, deprecação e armadilhas de Snapshot Testing
Publicar o Design System como um pacote SPM versionado exige disciplina com SemVer. Nunca altere a assinatura de um inicializador público ou remova uma propriedade em uma versão Minor. Em vez disso, introduza a nova API mantendo a antiga marcada com @available(*, deprecated, message: "Use init(title:isLoading:action:)") por pelo menos dois ciclos de release. Assim nenhuma squad fica impedida de subir um hotfix urgente por causa de quebra de compilação vinda da biblioteca visual.
Para evitar regressões visuais silenciosas, os testes de snapshot automatizados no CI são indispensáveis, mas escondem duas armadilhas técnicas que já vi derrubar pipelines inteiros. A primeira é a variação de renderização entre versões de simulador: atualizar o runner de iOS 17 para iOS 18 muda o kerning de fonte em um pixel e invalida duzentas imagens de referência de uma vez. A solução é fixar a versão exata do simulador e do Xcode no workflow de snapshots e regenerar referências apenas em PRs explícitos de upgrade de toolchain. A segunda armadilha é testar somente o caso padrão (tema claro, fonte normal); configure a matriz de snapshots para validar também Dark Mode e uma escala grande de acessibilidade (.accessibilityExtraLarge), pegando textos cortados antes de ir para a App Store.
Por fim, um Design System só ganha adoção real quando é fácil descobrir o que já existe. Manter um app de catálogo interno compilável (Showcase App) e documentação viva alinhada ao código, seguindo práticas como as que descrevo em documentação técnica viva e modelagem visual, reduz drasticamente a duplicação acidental de componentes.
Quando formalizar e checklist de PR para componentes
Se o aplicativo tem menos de quatro desenvolvedores iOS e ainda está validando encaixe de produto, montar um comitê formal e pipelines separados de pacote vai atrasar o negócio sem retorno proporcional. Comece leve: um arquivo de tokens semânticos, cinco componentes base e revisão entre pares. Formalize versionamento, RFC curta e testes de snapshot assim que duas ou mais squads começarem a tocar a interface ao mesmo tempo.
Checklist objetivo para aprovar novos componentes ou evoluções no pacote de Design System:
- O componente consome exclusivamente tokens semânticos de cor, tipografia e espaçamento, sem literais hardcoded.
- Foram testados os modos claro, escuro, alto contraste e Dynamic Type ampliado sem truncamento ou sobreposição de elementos.
- Áreas interativas respeitam no mínimo 44x44 pontos e possuem labels, traits e estados de acessibilidade adequados para VoiceOver.
- Mudanças que quebram compatibilidade vêm acompanhadas de marcação
deprecatedna API anterior ou incremento explícito de versão Major com guia curto de migração. - Snapshots atualizados acompanham o PR e o componente foi adicionado ao aplicativo interno de catálogo para descoberta pelas outras squads.
