Como este site é mantido

Boa notícia: quase nada aqui precisa ser escrito à mão. Fora esta seção “Comece aqui”, o resto do site é gerado automaticamente a partir do Notion, do DESIGN.md e dos Storybooks. Mudou algo na fonte? Rode o pipeline de novo — não edite o .mdx direto, porque ele não sobrevive à próxima sincronização.

Cuidado

Arquivos dentro de src/content/docs/foundations/, guidelines/ e components/ têm o comentário gerado por scripts/docs-site/build-content.mjs — não editar à mão no topo. Editar neles é perdido na próxima sincronização. Para mudar o conteúdo, mude a fonte (Notion, DESIGN.md/SCSS, ou os scripts de geração).

O pipeline

Executado a partir da raiz do mds-styles (não de dentro de docs-site/):

npm run docs:sync

Isso roda, em sequência:

1. npm run notion:sync (scripts/notion/sync.js) — busca a database “Componentes” do Notion (definição, quando usar, variantes, escrita de cada componente) e grava scripts/notion/cache/*.md + _pages.json.
2. npm run notion:sync-guidelines (scripts/notion/sync-guidelines.js) — busca a página “Diretrizes da interface do usuário” e toda a árvore de sub-páginas, grava scripts/notion/cache/guidelines/.
3. npm run docs:fetch-storybook-index (scripts/docs-site/fetch-storybook-index.mjs) — baixa o index.json publicado dos dois Storybooks, para saber o ID real de cada story a embutir.
4. npm run docs:fetch-angular-api (scripts/docs-site/fetch-angular-api.mjs) — lê o código do repositório irmão ../mds-angular (ou MDS_ANGULAR_DIR) e grava seletor, inputs, outputs e slots de cada componente em scripts/docs-site/cache/angular-api.json. Sem o repositório por perto, mantém o cache versionado.
5. npm run docs:build-content (scripts/docs-site/build-content.mjs) — junta tudo (Notion + DESIGN.md + IDs do Storybook) e escreve os .mdx em docs-site/src/content/docs/. Inclui a seção Utilitários (Animations, Display, Flexbox, Helpers, Sizing, Text), que não tem fonte no Notion nem no DESIGN.md — é só um embed do grupo Utilities/* do Storybook do mds-styles, então basta o passo 3 (docs:fetch-storybook-index) ter rodado.

O passo 5 também copia o DESIGN.md para docs-site/src/generated/design-md*.md (scripts/docs-site/sync-design-md.mjs, também disponível em npm run docs:design-md), que alimenta a página DESIGN.md em Ferramentas.

Além do que vem do Notion, cada página de componente ganha uma seção Para desenvolvedores gerada do código: exemplo HTML e opções (das stories em src/stories), classes CSS (do SCSS) e a API Angular (do passo 4). Os links de Figma e Storybook vêm das colunas do Notion — o build avisa quando um link está faltando, quebrado ou sem node-id.

Os passos 1–2 exigem um NOTION_TOKEN válido em mds-styles/.env (veja .env.example; a integração do Notion precisa continuar com acesso à página “MDS - Mobiis Design System”). Sem token, rode só os passos 3–5 (npm run docs:build-content reaproveita o cache do Notion já versionado no repo).

Assistente de escrita (kit de IA)

A aba Usar com sua IA da página Assistente de escrita entrega instruções e diretrizes para a pessoa colar na IA que já usa. Elas não são escritas à mão: o passo 5 as monta a partir das diretrizes de escrita, feedback, formulários e estados do Notion, então acompanham o docs:sync. O que é fixo e editável fica em scripts/docs-site/ux-writer/:

• core.md: papel, quem lê, como trabalhar, regras resumidas e o contexto logístico. É aqui que se ajusta o tom ou o vocabulário do setor.
• formato-chat.md: como a IA deve responder (alternativas, “por quê”, quando perguntar).

Os arquivos gerados ficam em docs-site/src/generated/ (ux-writer-*.md) e vão para o repositório, como os .mdx. São três: o prompt completo, as instruções curtas (cabem nos campos com limite de tamanho de Gem e GPT) e as diretrizes para anexar como conhecimento. O site não chama nenhuma IA. As regras do validador (src/lib/writing-rules.mjs) são mantidas à mão: se a diretriz de Estilo de escrita mudar, revise-as.

Quando rodar o quê

Mudou…	Rode
Uma regra de uso/variante/escrita de um componente no Notion	npm run docs:sync
A página “Diretrizes da interface do usuário” no Notion	npm run docs:sync
Um token de cor/tipografia/espaçamento no SCSS do mds-styles	npm run design:build (regenera DESIGN.md) e depois npm run docs:sync
Um componente novo publicado no Storybook (mds-styles ou mds-angular)	npm run docs:sync (o passo 3 recaptura os IDs)
Uma classe utilitária nova/renomeada em Utilities/* no Storybook do mds-styles	npm run docs:sync
Só quer ver o site localmente sem re-sincronizar nada	npm --prefix docs-site run dev

Nota

Componentes com Tipo de componente = Componente React no Notion são ignorados na geração (são protótipos React sem implementação MDS ainda — CSS/mds-styles ou Angular). Quando um desses ganhar implementação real e o campo mudar no Notion, ele passa a ser gerado no próximo docs:sync automaticamente.

O que você pode editar à vontade

• src/content/docs/comece-aqui/** — conteúdo curado à mão (esta página incluída). Fica livre.
• src/components/StorybookEmbed.astro, src/components/FigmaEmbed.astro, astro.config.mjs, src/styles/custom.css — estrutura e visual do site.
• A lógica de geração — o que vira página, como o texto do Notion é organizado — fica em scripts/docs-site/build-content.mjs. Mude ali, nunca no .mdx que ele produz.