---
title: "Guides da Apple em Markdown e JSON para agentes"
description: "Duas edições na URL transformam qualquer guide da Apple — Human Interface Guidelines e referência de API — em Markdown ou JSON limpo, sem HTML e com muito menos tokens."
canonical: "https://ronanrodrigo.dev/notes/apple-guides-markdown"
markdown: "https://ronanrodrigo.dev/notes/apple-guides-markdown.md"
last-updated: "2026-09-15"
---
## Human Interface Guidelines em Markdown

Os guides da Apple ficam disponíveis como documento limpo quando `tutorials/data/` entra antes de `design/` e a URL termina em `.md` ou `.json`. A dica foi publicada por Linda Dong, design evangelist da Apple, como forma de entregar um guide legível a agentes de código gastando menos tokens do que a página renderizada.

Tomando como exemplo a página sobre projetar para o iPhone Duo — um app que se adapta às duas telas e mantém a experiência contínua quando o aparelho abre e fecha —, o endereço de leitura fica:

- Markdown: `https://developer.apple.com/tutorials/data/design/human-interface-guidelines/designing-for-iphone-duo.md`
- JSON: `https://developer.apple.com/tutorials/data/design/human-interface-guidelines/designing-for-iphone-duo.json`

O `.md` abre com um bloco de metadados em comentário HTML (`title`, `framework`, `role`) antes do texto, o que dispensa raspar o DOM para saber o que veio na resposta.

[Veja a página original](https://developer.apple.com/design/human-interface-guidelines/designing-for-iphone-duo)

## A mesma regra na referência de API

A referência de frameworks segue o mesmo princípio: `tutorials/data/` depois do host e a extensão no fim. Para símbolos de framework, o JSON é o formato com estrutura útil — traz o resumo, a hierarquia, as seções de tópicos e a disponibilidade por plataforma, como iOS 13.0+ para `View` no SwiftUI. O `.md` equivalente responde depois de um redirecionamento para o caminho limpo, então convém seguir redirects ao baixar.

[Tutorial: View (SwiftUI)](https://developer.apple.com/documentation/swiftui/view)

## Espelho que troca o host

O Sosumi.ai faz a conversão trocando `developer.apple.com` pelo domínio próprio na URL, inclusive nas páginas da HIG, e a discussão no Hacker News rendeu ressalvas práticas: assinaturas de função que aparecem em forma de link podem perder o texto verbatim, e a leitura em Markdown também ajuda quem usa leitor de tela. O projeto nasceu justamente para levar docs da Apple a quem precisa de contexto de código.

[Leia a discussão](https://news.ycombinator.com/item?id=45063874)

## Snapshot offline em Markdown e JSON

Para trabalhar sem rede, o Apple Developer Documentation Offline Archive baixa Swift, SwiftUI, UIKit e o restante da documentação como Markdown limpo, com atualização incremental que só rebaixa páginas alteradas. O caso de uso declarado é indexar um snapshot local em RAG sem depender de chamadas externas.

[Consulte o repositório](https://github.com/OxADD1/Apple-Developer-Documentation-Offline-Archive)