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

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–4 (npm run docs:build-content reaproveita o cache do Notion já versionado no repo).

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.