# Regras de Desenvolvimento
## SCSS
**1.** O SCSS deve seguir exatamente a mesma estrutura do HTML quando se tratar da hierarquia.
### Exemplo
```scss
.home-about {
.container {
.box-left {
.image {
}
}
.box-right {
.content {
p {
}
ul {
}
}
}
}
}
```
---
**2.** Utilizar `@use` ao invés de `@import`.
---
**3.** Evitar duplicação de código.
---
**4.** Utilizar mixins sempre que possível.
* O projeto possui diversos mixins compartilhados, como `styled-lists-*`, que alimentam outros blocos.
* Utilizar o import abaixo quando necessário.
```scss
@use "../../../assets/scss/framework/mixins" as *;
```
---
**5.** Não utilizar IDs para estilização.
---
**6.** Não rodar:
```text
node esbuild.js
```
---
**7.** Todo `script.js` deve permanecer dentro da própria pasta do bloco se houver necessidade..
* Nunca criar arquivos JavaScript compartilhados entre blocos, salvo quando solicitado.
---
**8.** Seguir sempre o padrão de responsividade existente em:
```text
assets/scss/utilities/media
```
Utilizar sempre:
```scss
@include mq.below(md) {
}
```
### Exemplo
```scss
.element {
padding: 40px;
@include mq.below(md) {
padding: 20px;
}
}
```
### Imports padrão
```scss
@use "../../../assets/scss/utilities/media" as mq;
```
---
**9.** Utilizar ao máximo as variáveis já existentes no projeto.
Arquivo principal:
```text
assets/scss/theme/_variables.scss
```
---
**10.** Quando for necessário declarar uma cor diretamente, prezar por hexadecimal.
---
**11.** Para cores com opacidade, preferir hexadecimal com alpha ao invés de `rgba()`.
### Não fazer
```scss
background: rgba(0, 0, 0, 0.3);
```
### Fazer
```scss
color: var(--color-primary);
background: var(--color-background);
background: #0000004d;
```
Ou qualquer variável global existente no projeto.
---
**12.** A tipografia existente deve ser preservada.
* Não alterar sem autorização.
---
**13.** Sempre reutilizar o sistema existente em `_buttons.scss`, que diz respeito aos botões do site.
---
**14.** Criar botão novo somente mediante solicitação explícita.
---
**15.** Antes de alterar qualquer componente, identificar se as classes internas já possuem um arquivo dono.
---
**16.** As classes abaixo pertencem ao sistema e devem ser alteradas apenas em seus respectivos arquivos.
* `.btn` pertence ao sistema de botões (`_buttons.scss`).
* `.menu-toggle` pertence ao Main Navigation.
* `.menu-toggle__hamburger` pertence ao Main Navigation.
* `.menu-toggle__hamburger span` e qualquer linha interna do hamburger pertencem ao Main Navigation.
---
**17.** O `menu-toggle` é um pedaço de código pertencente à pasta **Main Navigation**.
* Não alterar seu comportamento fora do componente responsável.
---
**18.** Sempre que existir uma área de conteúdo renderizada pelo CMS, aplicar suporte para listas.
### Exemplo
```scss
.content {
ul {
@include styled-lists-dots;
// @include styled-lists;
}
}
```
### Regra
`styled-lists-dots` é o padrão.
Utilizar `styled-lists` somente quando solicitado.
Aplica-se principalmente para:
* `.content`
* `.editor-content`
* `.wysiwyg`
* `.text-content`
Ou qualquer bloco que renderize conteúdo vindo do CMS.
---
**19.** Utilizar como padrão a chamada abaixo.
O terceiro parâmetro (`2`) deve permanecer como padrão.
Alterar apenas quando houver necessidade explícita de controlar a sequência de animação. Em alguns casos esse valor pode ser alterado para mudar a animação de forma sequencial.
```php
<?php echo _mm_get_content('all', '', 2); ?>
<?php echo _mm_get_content('eyebrow', '', 2); ?>
<?php echo _mm_get_content('title', '', 2); ?>
<?php echo _mm_get_content('content', '', 2); ?>
<?php echo _mm_get_content('cta_buttons', '', 2); ?>
```
---
**20.** Utilizar sempre o padrão de animações do projeto.
# Animações
O projeto possui um padrão de animação global em:
```text
assets/scss/framework/_animations.scss
assets/js/utilities/animations.js
```
## Regra obrigatória
Sempre utilizar as classes existentes de animação.
Não criar animações locais dentro de componentes sem solicitação explícita.
## Classes disponíveis
### Classe base
```text
animate
```
Obrigatória para o JS observar o elemento e adicionar `in-view`.
### Direções disponíveis
```text
fade-up
fade-down
fade-left
fade-right
```
### Delays disponíveis
```text
delay-1 até delay-15
```
Cada número equivale a `100ms` depois que o elemento recebe `in-view`.
### Exemplo
```html
class="animate fade-up delay-2"
```
## Padrão recomendado
Para conteúdo comum, utilizar:
```html
class="animate fade-up delay-2"
```
Para conteúdo dinâmico via helper, manter:
```php
<?php echo _mm_get_content('title', '', 2); ?>
<?php echo _mm_get_content('content', '', 2); ?>
<?php echo _mm_get_content('cta_buttons', '', 2); ?>
```
Alterar o terceiro parâmetro apenas quando houver necessidade explícita de controlar a sequência.
## Image reveal
Também existem classes para reveal de imagem:
```text
image-reveal
image-reveal--reverse
```
Utilizar apenas quando o efeito de cortina de imagem for necessário.
---
## Procedures / Navegação ACF
**21.** Quando for apenas renderizar o menu, utilizar:
```php
<?php _mm_render_procedures(); ?>
```
### Regras
Utilizar o helper acima sempre que possível.
Caso seja necessário acessar campos adicionais ou propriedades específicas dos itens:
* Não utilizar o helper.
* Construir a estrutura manualmente.
* Utilizar loop próprio.
### Repeater ACF
Sempre que os dados vierem de um Repeater:
```php
have_rows()
the_row()
get_sub_field()
```
A estrutura deve ser construída manualmente.
Não utilizar helpers automáticos quando for necessário acessar informações específicas do item.
---
## Comentários
**22.** Não adicionar comentários novos.
### Regra obrigatória
Preservar apenas comentários já existentes no projeto.
### Não fazer
```php
// Novo comentário criado pelo Codex
```
### Fazer
Manter apenas comentários que já estavam presentes originalmente.
---
## Alterações Estruturais
As seguintes áreas não devem ser modificadas sem autorização explícita:
* Variáveis globais.
* Sistema de botões.
* Sistema tipográfico.
* Mixins globais.
* Estrutura principal do framework.
Caso uma alteração seja necessária, solicitar aprovação antes de implementar.
---
**23.** Utilizar sempre uma estrutura semântica para montar o HTML.
Preferir nomes como:
* `box-left`
* `box-right`
* `box-center`
* `box-top`
* `box-bottom`
Sempre utilizar nomes de acordo com a posição do elemento dentro do bloco.
Exemplo:
Se um bloco possuir `box-top` e `box-bottom`, e dentro do `box-top` existirem duas colunas, utilizar:
* `box-left`
* `box-right`
Aplicar esse padrão em toda a estrutura do projeto.
---
## Imagens
**24.** Imagens vindas de campos ACF devem utilizar o helper existente:
```php
<?php echo _mm_get_image( $image['id'] ); ?>
```
Não montar manualmente a tag `<img>` com `url`, `alt`, `width` ou `height` quando o helper puder ser utilizado.
Todas as imagens de um mesmo bloco devem seguir o mesmo padrão de renderização.
Para texturas, grafismos, formas e imagens estritamente decorativas, utilizar preferencialmente o clone `Decor Images` e o helper existente:
```php
<?php _mm_decor_images(); ?>
<?php _mm_decor_images('block'); ?>
```
Não criar um campo ACF específico para textura ou imagem decorativa quando o sistema `Decor Images` atender à necessidade.
**25.** no layout do bloco dar preferencia por display grid e suas frações referentes dando preferencia por 1fr e o restante maior que 1fr,sempre, salvo excessão.
**26.** sempre quando pedir um bloco especifico use h2 ou outro h que identifique o tamanho. mais jamais h1. so pode h1 no hero e outros blocos.
**27.** no bloco hero o eyebrow e subtitle tem ficar dentro do h1 como span.
**28.** a altura dos blocos geralmente não é definido por altura em height e sim por valores de padding ou margin nos elementos dentro de cada div ou outra tag.
**29.** eyebrow, h1, p, e eyebron vem da _typography.scss. não ajustar manualmente.
**30.** quando fizer um bloco ou for alterar lembre de ajustar o acf incluindo o que for necessario. e tambem organizar com o field TAB.
Instruções públicas para IA
Documento público do CodeCraft destinado ao Codex e outros agentes de inteligência artificial.