Guia de Aprimoramento de Estilos

Este guia documenta os tokens do sistema de design e as classes de componentes implementados em styles/custom.css. Ele serve como referência para tokens de borda, superfície, sombra, raio, botão, gradiente, transição, foco e tipografia utilizados em todo o tema.

Status: Todos os tokens de design e classes de componentes descritos abaixo estão implementados e disponíveis para uso.

Como Ler Este Guia

Cada seção documenta uma categoria de token:

1. Definições de token — propriedades CSS customizadas com valores para modo claro/escuro
2. Mapeamento de componentes — quais componentes do tema utilizam cada token
3. Notas de implementação — orientações de uso e considerações de acessibilidade

As tabelas de tokens são divididas por modo claro e modo escuro quando os valores diferem.

---

1. Sistema de Cores

Bordas com Transparência Alpha

O tema utiliza bordas com transparência alpha em vez de cores cinza sólidas. Isso permite que as bordas se adaptem naturalmente a qualquer plano de fundo.

/* Padrão de borda com transparência alpha */
border: 1px solid var(--f5-border-default);  /* neutral at 20% alpha */

Tokens de Borda

/* Light mode */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 at 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 at 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 at 40% */
}

/* Dark mode */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 at 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 at 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 at 40% */
}

Casos de Uso das Bordas

Token	Opacidade	Caso de Uso
--f5-border-faint	10%	Separadores sutis, linhas de tabela
--f5-border-default	20%	Bordas padrão, contornos de cartão
--f5-border-strong	40%	Bordas enfatizadas, estados ativos

Status: Completo — implementado em styles/custom.css.

Cores de Superfície Interativa

Tokens de superfície semânticos para estados de hover e ativo.

Superfícies no Modo Claro

Token	Valor	Finalidade
--f5-white	#ffffff	Planos de fundo principais
--f5-white-1	#faf9f7	Barra lateral, áreas sutis
--f5-white-2	#f5f5f5	Superfícies elevadas
--f5-surface-hover	var(--f5-white-2)	Preenchimento de hover
--f5-surface-active	var(--f5-white-3)	Preenchimento pressionado/ativo

Superfícies no Modo Escuro

Token	Valor	Finalidade
--f5-black	#000000	Planos de fundo principais
--f5-black-4	#222222	Barra lateral, áreas sutis
--f5-surface-hover	var(--f5-black-3)	Preenchimento de hover
--f5-surface-active	var(--f5-black-2)	Preenchimento pressionado/ativo

Definições de Tokens de Superfície

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

Status: Completo — implementado em styles/custom.css.

---

2. Sistema de Elevação e Sombra

Escala de Sombras

O tema utiliza sombras alpha com toque neutro com valores de dupla camada para profundidade natural. O modo claro usa --f5-black-3 (#343434) como base de toque; o modo escuro usa #cccccc.

Sombras no Modo Claro

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

Sombras no Modo Escuro

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

Mapeamento de Sombras por Componente

Componente	Nível de Sombra
.swatch, .icon-card	--f5-shadow-low (em repouso)
.starlight-aside	--f5-shadow-low
.expressive-code .frame	--f5-shadow-mid
.mermaid-container	--f5-shadow-mid
Cartões ao passar o cursor	--f5-shadow-mid
Menus suspensos, popovers	--f5-shadow-high
Modais	--f5-shadow-higher

Status: Completo — todos os níveis de sombra (inset, low, mid, high, higher) implementados em styles/custom.css.

---

3. Escala de Raio de Borda

Tokens de Raio

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — badges, tags */
  --f5-radius-sm: 0.3125rem;   /* 5px — nav items, small controls */
  --f5-radius-md: 0.375rem;    /* 6px — cards, code blocks */
  --f5-radius-lg: 0.5rem;      /* 8px — modals, large containers */
  --f5-radius-full: 999px;     /* pills, fully rounded */
}

Mapeamento de Raio por Componente

Componente	Token de Raio
.swatch	--f5-radius-md (6px)
.icon-card	--f5-radius-md (6px)
.starlight-aside	--f5-radius-md (6px)
.expressive-code .frame	--f5-radius-md (6px)
.mermaid-container	--f5-radius-lg (8px)
.edit-link	--f5-radius-full (pílula)
Itens de navegação da barra lateral	--f5-radius-sm (5px)
Badges	--f5-radius-xs (3px)

Status: Completo — escala de raio (xs, sm, md, lg, full) implementada em styles/custom.css.

---

4. Estilização da Navegação da Barra Lateral

Estilos dos Itens da Barra Lateral

/* Sidebar navigation items */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* Light mode hover */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* Dark mode hover */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* Active page indicator */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 light */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → adjust for readability */
}

Indicador de Acento à Esquerda

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* compensate for border */
}

Status: Completo — hover, estado ativo e indicador de acento da barra lateral implementados em styles/custom.css.

---

5. Sistema de Botões

Variantes de Botão

/* Primary — using F5 Red as brand action */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* Secondary — outline style */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* Tertiary — ghost/text-only */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

Escala de Tamanhos de Botão

Tamanho	Padding	Tamanho da Fonte	Altura Mínima
Pequeno	0.375rem 0.75rem	0.8125rem (13px)	32px
Médio (padrão)	0.625rem 1rem	0.875rem (14px)	40px
Grande	0.75rem 1.5rem	1rem (16px)	48px

Status: Completo — todas as variantes de botão (primary, secondary, tertiary, critical) e escala de tamanhos (sm, padrão, lg) implementadas em styles/custom.css.

---

6. Planos de Fundo de Hero e Cabeçalho

Gradientes de Hero

Utilizando a paleta da marca F5:

/* Primary hero gradient — River blue */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* Faint page wash — subtle warm tone */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* Eggplant variant for feature pages */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* Red brand variant for announcements */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

Técnicas de Sobreposição de Gradiente

/* Radial vignette for depth */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* Bottom fade to page background */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

Status: Completo — gradientes de hero (primary, eggplant, red, faint) e sobreposições (hero-fade, hero-vignette) implementados em styles/custom.css.

---

7. Efeitos de Hover e Transições

Tokens de Transição

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

Token	Duração	Easing	Caso de Uso
--f5-transition-fast	0.15s	ease	A maioria dos estados de hover, mudanças de cor
--f5-transition-base	0.2s	ease	Preenchimentos de fundo, mudanças de borda
--f5-transition-bounce	0.2s	cubic-bezier(0.68, -0.2, 0.265, 1.15)	Interruptores, toggles
--f5-transition-decelerate	0.6s	cubic-bezier(0.5, 1, 0.89, 1)	Indicadores de aba, painéis deslizantes
--f5-transition-spring	0.2s	cubic-bezier(0.54, 1.5, 0.38, 1.11)	Tooltips, entrada de popover

O Que Animar

Propriedade	Seguro para Animar	Observações
background-color	Sim	Padrão para preenchimentos de hover
color	Sim	Mudanças de cor de texto
border-color	Sim	Ênfase de borda ao passar o cursor
box-shadow	Sim	Mudanças de elevação (use will-change se houver travamento)
transform	Sim	Escala, translação para feedback
opacity	Sim	Aparecer/desaparecer gradualmente
width, height	Evitar	Causa refluxo de layout
padding, margin	Evitar	Causa refluxo de layout

Mapeamento de Transições por Componente

/* Sidebar nav items */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* Cards — shadow lift on hover */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* Buttons */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* Links */
a {
  transition: color var(--f5-transition-fast);
}

Status: Completo — todos os cinco tokens de transição (fast, base, bounce, decelerate, spring) e transições de componentes implementados em styles/custom.css.

---

8. Sistema de Anel de Foco

Tokens de Anel de Foco

O tema utiliza um padrão de anel duplo com um anel interno embutido e um brilho externo:

/* Action focus — using F5 River blue */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* Apply to interactive elements */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* Critical variant for destructive buttons */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

Notas de Acessibilidade

• O padrão de anel duplo atende aos requisitos de Aparência de Foco do WCAG 2.2 (contorno contrastante mínimo de 2px)
• Utilizar box-shadow em vez de outline permite que o raio de borda seja respeitado
• :focus-visible garante que o anel apareça apenas para navegação por teclado, não para cliques do mouse

Status: Completo — padrão de foco de anel duplo (action, critical) e estilos :focus-visible implementados em styles/custom.css.

---

9. Tipografia

Pilha de Fontes

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

Escala Tipográfica

Escala	Tamanho	Altura de Linha	Uso
Display 500	1.875rem (30px)	1,267	--sl-text-h1
Display 400	1.5rem (24px)	1,333	--sl-text-h2
Display 300	1.125rem (18px)	1,333	--sl-text-h3
Display 200	1rem (16px)	1,5	--sl-text-h4
Display 100	0.8125rem (13px)	1,385	Texto overline
Body 300	1rem (16px)	1,5	Corpo principal
Body 200	0.875rem (14px)	1,429	Texto da barra lateral, legendas
Body 100	0.8125rem (13px)	1,385	Letras miúdas

Características Principais

Aspecto	Valor	Observações
Altura de linha dos títulos	1.1	Títulos compactos para impacto da marca; considerar 1.2 para legibilidade
Altura de linha do corpo	1.5 (padrão Starlight)	Adequada para leitura
Família de fontes	Fontes customizadas da marca	proximaNova (corpo), neusaNextProWide (títulos)
Pesos dos títulos	h1-h2: 700, h3: 500, h4-h6: 700 uppercase	Opinativo para consistência da marca

Prioridade: Nenhuma alteração necessária. A tipografia atual está bem definida e adequada à marca. Ajuste menor na altura de linha dos títulos (1.1 para 1.2) é opcional.

---

10. Registro de Alterações da Implementação

Todos os tokens de design foram implementados ao longo de cinco sprints:

Sprint	Escopo	Tokens Adicionados
1. Fundação	Sombras + raio de borda	--f5-shadow-* (5 níveis), --f5-radius-* (5 níveis)
2. Barra Lateral + Superfícies	Navegação + tokens interativos	--f5-surface-hover, --f5-surface-active, --f5-border-* (3 níveis), --f5-transition-fast
3. Botões	Sistema de componentes	.btn-primary, .btn-secondary, .btn-tertiary, .btn-critical, variantes de tamanho
4. Gradientes de Hero	Utilitários de plano de fundo	.hero-gradient-primary, -eggplant, -red, -faint, .hero-vignette, .hero-fade
5. Foco + Transições	Acessibilidade + refinamento	--f5-focus-action, --f5-focus-critical, --f5-transition-* (5 tokens), efeitos de hover em cartões

---

Referência Rápida: Resumo dos Tokens

Todas as Propriedades Customizadas

:root {
  /* Border radius scale */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* Transition timing */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* Focus rings */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* Dark mode shadows (default) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* Dark mode borders */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* Dark mode surfaces */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* Light mode shadows */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* Light mode borders */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* Light mode surfaces */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}