@kenlo/sds-design-system

v1.0.2

Published

2 days ago

SDS, the Site Design System — Marko 5 components for Kenlo's public products (Site, Landing Page, Blog)

SDS — Site Design System

Componentes Marko 5 para os produtos públicos da Kenlo: Site, Landing Page e Blog.

O SDS é irmão do KDLS, não uma versão dele. O KDLS é React e atende os produtos internos; o SDS é Marko e atende o que o visitante vê. Os dois nascem dos mesmos tokens de design, e cada um é dono do seu código.

Sem marca. O site de um cliente não é um site da Kenlo, então nenhuma cor, gradiente ou alias da marca existe aqui. O que sobrou é o encaixe: um slot de cor primária que cada site preenche com a sua.

Instalação

npm install @kenlo/sds-design-system

O Marko 5 é peerDependency — o projeto que consome já tem o seu.

Começando

Duas linhas e o sistema está de pé:

// 1. Os tokens. Sem eles nenhum componente tem cor, espaço ou tipografia.
import "@kenlo/sds-design-system/foundations/tokens.css";

// 2. O CSS de cada componente que você usar.
import "@kenlo/sds-design-system/components/Button/Button.css";

As tags não precisam de import. O marko.json na raiz do pacote é o catálogo: o compilador do Marko acha <sds-button> sozinho.

A tipografia vem junto no passo 1, e não há passo para esquecer. A Manrope — a fonte padrão — viaja dentro do pacote, e as regras @font-face estão no próprio tokens.css, que é o arquivo que declara qual fonte usar. Nada é pedido ao Google enquanto a página carrega: o visitante do site é cliente da imobiliária, e o IP dele não sai daqui. As outras cinco opções de data-font estão descritas em Tema, logo abaixo.

<sds-button variant="primary" onClick=salvar>Salvar</sds-button>

<sds-input type="tel-inter" label="Telefone" onChange=(e, valor) => ... />

<sds-card bordered hoverable>
  <sds-text variant="titleSm">Apartamento 42</sds-text>
</sds-card>

Tema

Quatro atributos no <html> decidem a aparência inteira. Um atributo no valor padrão é removido, não escrito — então "sem atributo" é o padrão de instalação.

| Atributo | Valores | Padrão | |---|---|---| | data-theme | light, dark, system | light | | data-color-scheme | neutral, leaf, sand, wood, clay, flower, dusk, sky, sea, lake | neutral | | data-radius | flat, soft, medium, rounded | soft | | data-font | manrope, inter, helvetica, source-sans, nunito, montserrat | manrope |

De onde cada fonte vem, porque isso decide o que o visitante baixa:

| | onde mora | o que o visitante baixa | |---|---|---| | manrope (padrão) | dentro do pacote | ~24 KB — só o subset do idioma dele | | helvetica | na máquina do visitante | nada | | as outras quatro | bucket da Kenlo, publicado pelo KDLS | só o subset do idioma, e só se você escolher |

A Manrope é embarcada de propósito: a fonte padrão não pode depender de rede nenhuma além da do próprio app — se o bucket cair, nenhum produto perde a tipografia junto. As opcionais ficam fora do pacote pelo motivo oposto: os bytes delas não devem pesar em quem nunca escolhe nenhuma.

As quatro opcionais carregam desde 21/09, quando o CORS entrou no bucket. Conferido aqui com npm run check:fonts: 24 de 24 utilizáveis, e num navegador limpo as quatro famílias renderizam.
Com uma ressalva que vale saber. Entre a publicação do bucket e o conserto do CORS, houve uma janela em que os arquivos respondiam sem o cabeçalho. Um navegador que passou por uma dessas URLs nessa janela guardou a resposta ruim — e elas são servidas immutable, com um ano de cache, então ele não revalida. Essa pessoa continua vendo o fallback, e consertar o servidor não a alcança: só um nome de arquivo novo alcança.
A manrope e a helvetica nunca dependeram disso — e essa é exatamente a razão de a padrão vir embarcada.

Há duas portas para escrevê-los, e a diferença importa:

// No servidor, durante o SSR — o primeiro quadro já sai pintado certo.
import { themeAttributes } from "@kenlo/sds-design-system/foundations/theme-server.js";
`<html ${themeAttributes({ colorScheme: "leaf", radius: "flat" })}>`

// No navegador — para mudança ao vivo, como o preview do CMS.
import { configureSds } from "@kenlo/sds-design-system/foundations/theme.js";
configureSds({ theme: "dark" });

Aplicar o tema só pelo navegador pinta o primeiro quadro errado e corrige na frente do visitante. A metade servidor existe para evitar isso.

Cor do cliente

Os dez esquemas da tabela acima são os prontos. Um site com marca própria usa as suas cores, e uma marca tem duas: um destaque e uma complementar. As duas entram em tempo de execução, e há três jeitos de usá-las:

| | destaque | complementar | |---|---|---| | 1 sólida | preenche o slot primário | não é aplicada | | 2 sólidas | preenche o slot primário | pinta o botão ghost, e nada mais | | gradiente | primeiro stop | último stop |

import { applyCustomColor, applyComplementColor, applyCustomGradient,
  clearComplementColor, clearCustomScheme }
  from "@kenlo/sds-design-system/foundations/custom-scheme.js";

applyCustomColor("#2E7D32");                   // nove tons sólidos no slot primário
applyComplementColor("#BF71E5");               // nove tons em --color-complement-10..90
applyCustomGradient(["#2E7D32", "#BF71E5"]);   // nove gradientes
clearComplementColor();                        // derruba só a complementar
clearCustomScheme();                           // derruba as duas

O destaque preenche --color-primary-10..90, os companheiros -solid e o --color-on-primary — este último escolhido por luminância relativa (WCAG), para o texto sobre a cor ficar legível seja ela qual for.

A complementar pinta um controle só: o botão ghost, que é o contornado. É decisão, não limitação — uma segunda cor solta no sistema é como o sistema deixa de ter uma cor.

E ela é uma camada, não um terceiro modo: mora no seu próprio <style>, então trocar o destaque não a derruba junto. Enquanto você não definir nenhuma, o ghost fica exatamente como sempre foi — a leitura é var(--color-complement-50, var(--color-primary-50-solid)), o fallback responde, e nada muda para quem nunca usar isso.

O que vem dentro

46 componentes — de sds-accordion a sds-uploader
85 ícones — Fluent, sociais e próprios, como componentes Marko (sem requisição a terceiros)
Tokens de cor, espaço, tipografia, sombra, raio e movimento
Tema claro e escuro, dez esquemas de cor, quatro esquemas de canto, seis fontes

O pacote leva código-fonte, não build: o seu projeto compila os .marko com o toolchain que já tem.

Documentação

O portal tem todos os componentes com controles ao vivo, a tabela de props de cada um e o código pronto para copiar. Para subir localmente:

git clone https://gitlab.com/kenlo1/kenlo-sites/frontend/sds-design-system.git
npm install
npm run dev

Versionamento

O pacote é público na npm porque os projetos que o consomem precisam instalá-lo sem credencial, igual ao KDLS. Público não quer dizer aberto: o código é proprietário da Kenlo (UNLICENSED) e as contribuições passam pelo repositório no GitLab.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme