Primeiros passos com a Lily

Instalação

A Lily é publicada como repositórios Git separados por framework. A forma mais rápida de experimentá-la é clonar o repositório headless da sua pilha:

git clone https://github.com/LilyDesignSystem/lily-design-system-react-headless
cd lily-design-system-react-headless
pnpm install

O mesmo padrão funciona para os outros frameworks:

• @lilydesignsystem/html-headless — não precisa instalar; copie os arquivos .html
• @lilydesignsystem/svelte-headless — pnpm install
• @lilydesignsystem/react-headless — pnpm install
• @lilydesignsystem/vue-headless — pnpm install
• @lilydesignsystem/angular-headless — pnpm install
• @lilydesignsystem/nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

As bibliotecas headless foram feitas para ser clonadas ou incorporadas ao projeto — trate o código-fonte como a fonte da verdade e copie o que precisar. Os assistentes de preferências também são distribuídos como pacotes instaláveis, com um pipeline de build e publicação (npm para os frameworks JS, NuGet para o Blazor).

Usar um componente headless

Os componentes headless trazem HTML semântico, ARIA e propriedades — mas nenhum CSS. Aqui está um botão em cada framework:

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

Usar um exemplo estilizado

Os aplicativos de exemplo incluem CSS, rotas e páginas de demonstração completas. A forma mais rápida de experimentar é iniciar o aplicativo de exemplo SvelteKit, Next, Nuxt, Analog ou Eleventy e ver a demonstração em /components.

git clone https://github.com/LilyDesignSystem/lily-design-system-svelte-sveltekit-examples
cd lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

Depois abra http://localhost:5173 e navegue por /components.

Estilização e tokens de design

Cada componente é renderizado com uma única classe em kebab-case no elemento raiz. Por exemplo, <Button> gera <button class="button">. Estilize como quiser:

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

A paleta de cores padrão da Lily (usada nos aplicativos de exemplo) é:

• Primária: #2563eb
• Perigo: #dc2626
• Aviso: #f59e0b
• Sucesso: #16a34a
• Fundo da página: #f9fafb
• Fundo do cartão: #ffffff

São sugestões, não exigências. Troque-as pela paleta da sua própria marca e a Lily se adapta com prazer.

Temas prontos

Não quer escrever CSS do zero? A Lily traz 45 temas de referência independentes no diretório themes/. Cada um é uma folha de estilo que mira as classes de gancho da Lily — vincule-a e pronto, está estilizado:

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

O conjunto abrange:

• Setor público — NHS England, NHS Scotland e NHS Wales (variantes para pacientes e para profissionais), GOV.UK GDS e o Sistema de design web dos EUA.
• Inspirados em fornecedores — Adobe Spectrum, Mozilla Protocol.
• Uso geral — claro, escuro, nord, dracula, wireframe e mais umas trinta.

Os seletores dos temas usam :where(...), então o seu próprio CSS sempre vence em especificidade. Combine-os com o assistente theme-picker abaixo para trocar em tempo de execução, ou siga o tutorial de temas.

Assistentes de preferências

Cada framework tem um catálogo complementar *-helpers com oito pequenos seletores (e um picker-bar que os reúne). Cada um é um botão de ícone headless que abre um popup — uma lista de opções, uma lista de links, um formulário de busca ou (no date-time-picker) um diálogo de seleção de data — e não um <select> nativo; é seguro para SSR e não traz CSS:

• theme-picker — carrega folhas de estilo de tema em tempo de execução trocando um <link> gerenciado, define data-theme no documento e, opcionalmente, persiste em localStorage.
• locale-picker — define lang e dir (com detecção automática de escrita da direita para a esquerda) para que a sua biblioteca de i18n acompanhe; não faz tradução alguma.
• text-size-picker — define data-text-size no documento; o seu CSS associa cada valor a um tamanho de fonte.
• motion-picker — define data-motion no documento, partindo da configuração de redução de movimento do visitante; o seu CSS e os seus scripts decidem o que suprimir.
• search-picker — um botão de ícone que abre um campo de busca; ao enviar, navega para uma página de busca. Cuida de uma ação, não de uma preferência.
• link-picker — um ícone de início que abre um menu com os links de página definidos pelo seu aplicativo (Início, Sobre nós, Fale conosco, Política de privacidade, …). Cuida de uma ação, não de uma preferência.
• share-picker — abre a folha de compartilhamento nativa ou uma lista de destinos fornecida pelo consumidor, além de copiar a URL. Cuida de uma ação, não de uma preferência: não aplica nada, não persiste nada.
• date-time-picker — um campo de texto mais um diálogo de seleção de data APG para uma data, uma hora ou ambas. Cuida de um valor de formulário, não de uma preferência: a string ISO faz o caminho de ida e volta com <input type="date">.

git clone https://github.com/LilyDesignSystem/lily-design-system-svelte-helpers

O catálogo Svelte é a referência canônica; as versões para React, Vue, Angular, HTML, Nunjucks, Web Components e Blazor correspondem a ele contrato por contrato. Veja o tutorial de assistentes.

Acessibilidade

Os componentes miram a WCAG 2.2 AAA. Eles seguem estes padrões:

• Elementos HTML semânticos em vez de <div> genéricos.
• <label for="id"> ligando rótulos aos campos.
• aria-labelledby / aria-describedby para referências cruzadas.
• aria-invalid + aria-errormessage para estados de erro.
• role="alert" e aria-live para conteúdo dinâmico.
• aria-pressed, aria-expanded, aria-current para o estado.
• tabindex itinerante para grades.

Os indicadores de foco são intencionalmente fornecidos pelo consumidor — a Lily nunca desenha um anel de foco padrão que conflite com o seu design. Os aplicativos de exemplo mantêm uma linha de base limpa no axe-core em todas as rotas.

Internacionalização

Todo rótulo, texto de exemplo, mensagem de erro e texto de botão é uma propriedade. Não há textos fixos no código. Conecte o framework de tradução que preferir — Paraglide, i18next, vue-i18n, react-intl, arquivos .resx, o que for.

Para datas, números e moedas, os componentes aceitam strings já formatadas: você formata com Intl.DateTimeFormat / Intl.NumberFormat / sua biblioteca preferida e repassa o resultado.

O assistente locale-picker sinaliza a localidade escolhida para a sua biblioteca de i18n definindo lang e dir na raiz do documento.

Testes

Cada subprojeto de framework traz seus próprios testes usando sua pilha idiomática:

• HTML: WebDriverIO rodando em navegadores reais.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (pelo plugin Vite do Analog).
• Nunjucks: Vitest com um auxiliar de renderização.
• Blazor: bUnit.

Os testes usam somente os comparadores nativos do Vitest — nunca os do jest-dom. Isso mantém os conjuntos de testes portáteis. Os aplicativos de exemplo acrescentam conjuntos Playwright de ponta a ponta, linhas de base de acessibilidade com axe-core e uma varredura de tamanhos de janela responsivos.

Agentes de IA

Este site publica llms.txt e llms.json na raiz — um mapa curado de suas páginas mais importantes, para qualquer ferramenta que siga a convenção llms.txt.

O monorrepositório canônico também traz duas habilidades do Claude: lily-design-system-skill, uma habilidade de uso geral que cobre os conceitos, a terminologia e os padrões de composição da Lily para quem constrói com o sistema, e lily-design-system-maintainer-skill, uma habilidade técnica que cobre a organização de arquivos obrigatórios e as ferramentas do monorrepositório para quem trabalha nele. Ambas ficam na raiz do monorrepositório canônico.

Solução de problemas

Como contribuir

A Lily é jovem e recebe bem a colaboração. As contribuições mais úteis no momento são:

• Novos componentes (especialmente padrões de sistemas de design consolidados).
• Novos temas — cada um é uma folha de estilo independente, um primeiro pull request bem delimitado.
• Melhor estilização dos exemplos — mostre o que é possível.
• Traduções dos textos dos aplicativos de exemplo.
• Relatos de bugs com um caso reproduzível mínimo.
• Auditorias de acessibilidade com leitores de tela e tecnologias assistivas.

Abra issues e pull requests no repositório correspondente em github.com/LilyDesignSystem.

Comunidade e suporte

• Perguntas e relatos de bugs — abra uma issue no repositório correspondente em github.com/LilyDesignSystem.
• E-mail — o responsável lê joel@joelparkerhenderson.com e recebe bem colaboração, orientação e comentários.
• Espelhos — a Lily também é enviada para o Codeberg e o GitLab, para que você participe pela plataforma de sua preferência.
• Conduta — o projeto segue um código de conduta padrão; seja gentil e presuma boa-fé.

Perguntas frequentes