API e conector

Referência da API

Cada endereço da API, com os parâmetros e um exemplo que você testa aqui mesmo. A mesma coisa, para ferramentas, está em /api/openapi.json (OpenAPI 3.1).

#Tokens

O tokens.json inteiro e o CSS gerado dele, como estão no repositório.

#O tokens.json inteiro

GET /api/v1/tokens

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.

200application/json: O arquivo tokens/tokens.json.

Testar

#As variáveis CSS

GET /api/v1/tokens.css

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.

200text/css: O web/tokens.css.

Testar

#O tema do Tailwind v4

GET /api/v1/tailwind.css

O web/tailwind.css, para importar depois do tokens.css. Desliga a paleta padrão do Tailwind.

200text/css: O web/tailwind.css.

Testar

#Temas

O design system resolvido para um modo, um contraste, um produto e uma data especial.

#Os temas, os produtos e as datas

GET /api/v1/themes

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.

200application/json: A lista, com o endereço de cada tema em JSON e em CSS.

Testar

#Um tema resolvido

GET /api/v1/themes/{theme}

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

Parâmetro	Onde	O quê
`theme` obrigatório	caminho	O tema. Com `.css` no fim, a resposta é CSS. Valores: `light`, `dark`, `light-high-contrast`, `dark-high-contrast`, `light.css`, `dark.css`, `light-high-contrast.css`, `dark-high-contrast.css`
`product`	consulta	Acrescenta a camada de um produto: nome, símbolo e cores de dado. Valores: `clio`
`season`	consulta	A data especial: o id de uma data, `auto` (a data do dia, ou nenhuma) ou `none`. Padrão: `none`. Valores: `none`, `auto`, `ano-novo`, `carnaval`, `pascoa`, `festa-junina`, `dia-da-advocacia`, `independencia`, `dia-das-criancas`, `natal`
`date`	consulta	O dia para `season=auto`, em aaaa-mm-dd. Padrão: hoje, no fuso de São Paulo.

200application/json: O tema em JSON.
200text/css: O tema em CSS, com o nome terminado em .css.
404application/json: Não existe: a mensagem diz quais valores existem.
400application/json: Parâmetro inválido: a mensagem diz o formato certo.

Testar

#Produtos

A camada de cada produto: nome, símbolo, cores de dado e formato do destaque.

#Os produtos

GET /api/v1/products

Cada produto que usa a identidade, com o nome e o endereço dos detalhes.

200application/json: A lista de produtos.

Testar

#Um produto

GET /api/v1/products/{product}

O arquivo do produto (products/<id>/<id>.json): nome, marca escrita, sigla por extenso, formato do destaque e cores de dado.

Parâmetro	Onde	O quê
`product` obrigatório	caminho	O id do produto. Valores: `clio`

200application/json: O produto.
404application/json: Não existe: a mensagem diz quais valores existem.

Testar

#O símbolo do produto

GET /api/v1/products/{product}/mark.svg

O símbolo em SVG, só para ícone de app e de aba. No escuro, o quadrado continua ink, ou seja, fica claro.

Parâmetro	Onde	O quê
`product` obrigatório	caminho	O id do produto. Valores: `clio`
`theme`	consulta	O modo do símbolo. Padrão: `light`. Valores: `light`, `dark`

200image/svg+xml: O símbolo.
404application/json: Não existe: a mensagem diz quais valores existem.

Testar

#Datas especiais

Os períodos das datas especiais e a data de um dia.

#As datas especiais

GET /api/v1/seasons

Todas as datas, com o período de cada uma no ano do dia pedido, a data em vigor e as próximas.

Parâmetro	Onde	O quê
`date`	consulta	O dia de referência, em aaaa-mm-dd. Padrão: hoje.

200application/json: As datas, a data em vigor e as próximas.
400application/json: Parâmetro inválido: a mensagem diz o formato certo.

Testar

#A data especial de um dia

GET /api/v1/seasons/current

A data em vigor no dia pedido, com a cor nos dois modos, ou null quando não há nenhuma.

Parâmetro	Onde	O quê
`date`	consulta	O dia, em aaaa-mm-dd. Padrão: hoje, no fuso de São Paulo.

200application/json: A data em vigor, ou null.
400application/json: Parâmetro inválido: a mensagem diz o formato certo.

Testar

#Uma data especial

GET /api/v1/seasons/{season}

Uma data, com o período no ano pedido.

Parâmetro	Onde	O quê
`season` obrigatório	caminho	O id da data. Valores: `ano-novo`, `carnaval`, `pascoa`, `festa-junina`, `dia-da-advocacia`, `independencia`, `dia-das-criancas`, `natal`
`year`	consulta	O ano do período. Padrão: o ano de hoje.

200application/json: A data e o período.
404application/json: Não existe: a mensagem diz quais valores existem.
400application/json: Parâmetro inválido: a mensagem diz o formato certo.

Testar

#Ferramentas

Conferências que ajudam a aplicar a identidade.

#Conferir o contraste

GET /api/v1/contrast

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.

Parâmetro	Onde	O quê
`foreground` obrigatório	consulta	A cor do texto ou da marca: hex ou nome de token.
`background` obrigatório	consulta	A cor do fundo: hex ou nome de token.
`theme`	consulta	O tema em que os nomes de token são resolvidos. Padrão: `light`. Valores: `light`, `dark`, `light-high-contrast`, `dark-high-contrast`

200application/json: A razão e se passa para texto, texto grande e marca gráfica.
400application/json: Parâmetro inválido: a mensagem diz o formato certo.

Testar

#Referência

As páginas da referência e a skill, em Markdown, para agentes e ferramentas.

#As páginas da referência

GET /api/v1/reference

As páginas da referência da skill, com o endereço do Markdown de cada uma.

200application/json: A lista de páginas.

Testar

#Uma página da referência

GET /api/v1/reference/{page}

O Markdown de uma página da referência, como está no repositório. skill devolve o SKILL.md.

Parâmetro	Onde	O quê
`page` obrigatório	caminho	O nome da página. Valores: `skill`, `android`, `apple`, `componentes`, `cor`, `datas`, `escrita`, `forma`, `marca`, `mudar`, `principios`, `slides`, `tipografia`, `tokens`, `web`, `windows`

200text/markdown: A página em Markdown.
404application/json: Não existe: a mensagem diz quais valores existem.

Testar