{"openapi":"3.1.0","info":{"title":"API da identidade visual byescaleira","version":"1.1.0","description":"Os tokens, os temas, os produtos e as datas especiais da identidade visual byescaleira. Só leitura, pública e sem chave.","license":{"name":"Todos os direitos reservados"}},"servers":[{"url":"https://design.byescaleira.com"}],"tags":[{"name":"Tokens","description":"O tokens.json inteiro e o CSS gerado dele, como estão no repositório."},{"name":"Temas","description":"O design system resolvido para um modo, um contraste, um produto e uma data especial."},{"name":"Produtos","description":"A camada de cada produto: nome, símbolo, cores de dado e formato do destaque."},{"name":"Datas especiais","description":"Os períodos das datas especiais e a data de um dia."},{"name":"Ferramentas","description":"Conferências que ajudam a aplicar a identidade."},{"name":"Referência","description":"As páginas da referência e a skill, em Markdown, para agentes e ferramentas."}],"paths":{"/api/v1/tokens":{"get":{"operationId":"getTokens","tags":["Tokens"],"summary":"O tokens.json inteiro","description":"A fonte única da identidade, exatamente como está no repositório: cores nos dois temas, alto contraste, tipografia, espaço, raio, fio, sombra, movimento, layout e datas especiais, cada valor com a nota de uso.","parameters":[],"responses":{"200":{"description":"O arquivo tokens/tokens.json.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tokens.css":{"get":{"operationId":"getTokensCss","tags":["Tokens"],"summary":"As variáveis CSS","description":"O web/tokens.css: claro e escuro pela preferência do sistema, alto contraste por `prefers-contrast` e as datas por `data-season`. É o mesmo arquivo do pacote npm.","parameters":[],"responses":{"200":{"description":"O web/tokens.css.","content":{"text/css":{"schema":{"type":"string"}}}}}}},"/api/v1/tailwind.css":{"get":{"operationId":"getTailwindCss","tags":["Tokens"],"summary":"O tema do Tailwind v4","description":"O web/tailwind.css, para importar depois do tokens.css. Desliga a paleta padrão do Tailwind.","parameters":[],"responses":{"200":{"description":"O web/tailwind.css.","content":{"text/css":{"schema":{"type":"string"}}}}}}},"/api/v1/themes":{"get":{"operationId":"listThemes","tags":["Temas"],"summary":"Os temas, os produtos e as datas","description":"O que dá para combinar: os quatro temas (claro, escuro e os dois com alto contraste), os produtos e as datas especiais, com a data de hoje.","parameters":[],"responses":{"200":{"description":"A lista, com o endereço de cada tema em JSON e em CSS.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/themes/{theme}":{"get":{"operationId":"getTheme","tags":["Temas"],"summary":"Um tema resolvido","description":"Todos os tokens com os valores do tema, já resolvidos: `accent` vira a cor de `ink`, no alto contraste os cinzas e os fios viram tinta, o produto acrescenta as cores de dado (`data-<nome>`) e a data acrescenta `season`. Termine o nome do tema em `.css` para receber as variáveis CSS num `:root` só.","parameters":[{"name":"theme","in":"path","required":true,"description":"O tema. Com `.css` no fim, a resposta é CSS.","schema":{"type":"string","enum":["light","dark","light-high-contrast","dark-high-contrast","light.css","dark.css","light-high-contrast.css","dark-high-contrast.css"]},"example":"dark"},{"name":"product","in":"query","required":false,"description":"Acrescenta a camada de um produto: nome, símbolo e cores de dado.","schema":{"type":"string","enum":["clio"]}},{"name":"season","in":"query","required":false,"description":"A data especial: o id de uma data, `auto` (a data do dia, ou nenhuma) ou `none`. Padrão: `none`.","schema":{"type":"string","enum":["none","auto","ano-novo","carnaval","pascoa","festa-junina","dia-da-advocacia","independencia","dia-das-criancas","natal"]}},{"name":"date","in":"query","required":false,"description":"O dia para `season=auto`, em aaaa-mm-dd. Padrão: hoje, no fuso de São Paulo.","schema":{"type":"string"},"example":"2026-12-20"}],"responses":{"200":{"description":"O tema em JSON.","content":{"application/json":{"schema":{"type":"object"}},"text/css":{"schema":{"type":"string"}}}},"400":{"description":"Parâmetro inválido: a mensagem diz o formato certo.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Não existe: a mensagem diz quais valores existem.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/products":{"get":{"operationId":"listProducts","tags":["Produtos"],"summary":"Os produtos","description":"Cada produto que usa a identidade, com o nome e o endereço dos detalhes.","parameters":[],"responses":{"200":{"description":"A lista de produtos.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/products/{product}":{"get":{"operationId":"getProduct","tags":["Produtos"],"summary":"Um produto","description":"O arquivo do produto (products/<id>/<id>.json): nome, marca escrita, sigla por extenso, formato do destaque e cores de dado.","parameters":[{"name":"product","in":"path","required":true,"description":"O id do produto.","schema":{"type":"string","enum":["clio"]},"example":"clio"}],"responses":{"200":{"description":"O produto.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Não existe: a mensagem diz quais valores existem.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/products/{product}/mark.svg":{"get":{"operationId":"getProductMark","tags":["Produtos"],"summary":"O símbolo do produto","description":"O símbolo em SVG, só para ícone de app e de aba. No escuro, o quadrado continua ink, ou seja, fica claro.","parameters":[{"name":"product","in":"path","required":true,"description":"O id do produto.","schema":{"type":"string","enum":["clio"]},"example":"clio"},{"name":"theme","in":"query","required":false,"description":"O modo do símbolo. Padrão: `light`.","schema":{"type":"string","enum":["light","dark"]}}],"responses":{"200":{"description":"O símbolo.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Não existe: a mensagem diz quais valores existem.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/seasons":{"get":{"operationId":"listSeasons","tags":["Datas especiais"],"summary":"As datas especiais","description":"Todas as datas, com o período de cada uma no ano do dia pedido, a data em vigor e as próximas.","parameters":[{"name":"date","in":"query","required":false,"description":"O dia de referência, em aaaa-mm-dd. Padrão: hoje.","schema":{"type":"string"},"example":"2026-12-20"}],"responses":{"200":{"description":"As datas, a data em vigor e as próximas.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetro inválido: a mensagem diz o formato certo.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/seasons/current":{"get":{"operationId":"getCurrentSeason","tags":["Datas especiais"],"summary":"A data especial de um dia","description":"A data em vigor no dia pedido, com a cor nos dois modos, ou `null` quando não há nenhuma.","parameters":[{"name":"date","in":"query","required":false,"description":"O dia, em aaaa-mm-dd. Padrão: hoje, no fuso de São Paulo.","schema":{"type":"string"},"example":"2027-02-08"}],"responses":{"200":{"description":"A data em vigor, ou null.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetro inválido: a mensagem diz o formato certo.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/seasons/{season}":{"get":{"operationId":"getSeason","tags":["Datas especiais"],"summary":"Uma data especial","description":"Uma data, com o período no ano pedido.","parameters":[{"name":"season","in":"path","required":true,"description":"O id da data.","schema":{"type":"string","enum":["ano-novo","carnaval","pascoa","festa-junina","dia-da-advocacia","independencia","dia-das-criancas","natal"]},"example":"carnaval"},{"name":"year","in":"query","required":false,"description":"O ano do período. Padrão: o ano de hoje.","schema":{"type":"string"},"example":"2027"}],"responses":{"200":{"description":"A data e o período.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetro inválido: a mensagem diz o formato certo.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Não existe: a mensagem diz quais valores existem.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/contrast":{"get":{"operationId":"checkContrast","tags":["Ferramentas"],"summary":"Conferir o contraste","description":"O contraste entre duas cores, pela conta da WCAG 2.x. Aceita hex (`#5c5c5c`) ou nome de token (`ink-muted`), que é resolvido no `theme`. O design system exige 4,5:1 em todo texto.","parameters":[{"name":"foreground","in":"query","required":true,"description":"A cor do texto ou da marca: hex ou nome de token.","schema":{"type":"string"},"example":"ink-muted"},{"name":"background","in":"query","required":true,"description":"A cor do fundo: hex ou nome de token.","schema":{"type":"string"},"example":"paper"},{"name":"theme","in":"query","required":false,"description":"O tema em que os nomes de token são resolvidos. Padrão: `light`.","schema":{"type":"string","enum":["light","dark","light-high-contrast","dark-high-contrast"]}}],"responses":{"200":{"description":"A razão e se passa para texto, texto grande e marca gráfica.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Parâmetro inválido: a mensagem diz o formato certo.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/reference":{"get":{"operationId":"listReference","tags":["Referência"],"summary":"As páginas da referência","description":"As páginas da referência da skill, com o endereço do Markdown de cada uma.","parameters":[],"responses":{"200":{"description":"A lista de páginas.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/reference/{page}":{"get":{"operationId":"getReferencePage","tags":["Referência"],"summary":"Uma página da referência","description":"O Markdown de uma página da referência, como está no repositório. `skill` devolve o SKILL.md.","parameters":[{"name":"page","in":"path","required":true,"description":"O nome da página.","schema":{"type":"string","enum":["skill","android","apple","componentes","cor","datas","escrita","forma","marca","mudar","principios","slides","tipografia","tokens","web","windows"]},"example":"cor"}],"responses":{"200":{"description":"A página em Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Não existe: a mensagem diz quais valores existem.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}