Uso por agents consumidoresUsage by consumer agents

Como agents devem implementar telas em projetos consumidores usando o DS TIS.How agents should build screens in consumer projects with DS TIS.

Esta página é gerada automaticamente por scripts/sync-docs.mjs. Edite as fontes Markdown, não este HTML.This page is generated automatically by scripts/sync-docs.mjs. Edit the Markdown sources, not this HTML.

Este guia é a instrução oficial para agents IA que precisam implementar telas em aplicações consumidoras usando o DS TIS. Ele não substitui AGENTS.md, que é voltado para manutenção deste repositório. Aqui o foco é consumo: montar telas reais com a API pública do pacote, sem inventar uma camada oficial que não existe.

Use este guia antes de gerar, revisar ou refatorar qualquer tela em um app consumidor.

Escopo

O DS TIS é stack-agnóstico. A base pública estável é HTML, CSS e JavaScript distribuídos pelo pacote ds-tis. React possui uma distribuição beta por source registry shadcn, e Angular possui uma biblioteca nativa beta validada por tarball local. As duas continuam dependentes do CSS e dos tokens públicos do DS.

Não apresente @tis/react como pacote público nem @tis/angular como publicado no npm. Use uma saída somente quando docs/api/components.json marcar seu status como beta ou stable. Para Vue, Svelte e componentes React ou Angular ainda indisponíveis, qualquer wrapper continua sendo uma adaptação local do projeto consumidor.

A regra operacional para agents é literal: nao invente wrappers oficiais. Fora do catálogo beta, documente o wrapper como código local da aplicação.

Entradas esperadas

Antes de implementar, o agent deve reunir:

objetivo da tela ou fluxo;
stack e convenções do projeto consumidor;
versão instalada do pacote ds-tis, quando disponível;
rotas, layouts, providers e padrões locais já existentes;
lista de estados esperados: loading, empty, error, disabled, success, read-only, destructive e responsive;
restrições de acessibilidade, idioma, dados e permissões.

Se essas entradas não estiverem claras, inspecione o projeto primeiro. Pergunte ao owner somente quando a decisão mudar comportamento de produto, dados reais, permissões ou arquitetura local.

Fontes obrigatórias

Antes de escrever markup novo, consulte as fontes públicas do DS:

README.md para instalação e imports principais;
docs/llms.txt para o índice leve consumível por LLMs;
docs/llms-full.txt para contexto textual completo;
docs/api/components.json para componentes, implementações por tecnologia (implementations.web, implementations.ark, implementations.react e implementations.angular), readiness, responsabilidade, variantes, tokens consumidos e metadados de runtime JS (runtime.level, runtime.module, runtime.init, runtime.destroy, runtime.events);
docs/api/tokens.json para camadas Foundation, Semantic e Component;
páginas HTML dos componentes em docs/<component>.html;
templates em docs/templates/ e exports ds-tis/templates/*, quando o fluxo se aproxima de um padrão já publicado.

Não dependa de memória ou suposições sobre classes. Quando houver dúvida, leia a página do componente e a API JSON.

O tarball inclui o contexto machine-readable. Depois da instalação, leia pelos exports ds-tis/metadata, ds-tis/metadata/components, ds-tis/metadata/tokens, ds-tis/agent-guide, ds-tis/agent-guide/en, ds-tis/llms e ds-tis/llms-full, ou diretamente em node_modules/ds-tis/docs/. Sem o pacote instalado, use o fallback público https://tis-experience.github.io/ds-tis/docs/api/components.json.

ds-tis/metadata aponta para consumer-context.json: um manifesto pequeno com entrypoints oficiais, tecnologias disponíveis, registry React, versão, fontes de verdade e contrato responsivo. JSON modules podem exigir import attribute na stack usada; agents e scripts também podem ler o arquivo diretamente pelo package resolver ou filesystem.

Readiness e responsabilidade

Antes de escolher um componente, leia readiness e responsibility em docs/api/components.json:

Readiness	Uso esperado
`app-ready`	Recomendado para aplicações dentro da API pública documentada.
`composition`	Público e estável, mas a aplicação mantém orquestração, navegação ou estado entre as partes.
`experimental`	Não usar em fluxo crítico sem aceitar explicitamente a limitação em `readinessNotes`.

responsibility.model informa quem mantém o comportamento:

native: use o elemento HTML adequado; o app controla dados e eventos de negócio;
presentation: não há runtime de componente; o app fornece conteúdo e contexto;
consumer: o DS entrega a composição visual, mas o app mantém a orquestração;
ds-runtime: o DS mantém a interação reutilizável; inicialize o módulo indicado em runtime.

Não promova localmente um componente Experimental a App-ready. Se o projeto completar um gap com código próprio, declare que ele é uma adaptação local e registre a demanda no DS.

Imports oficiais

Instale a versão corrente pelo npm registry:

npm install ds-tis

A versão estável é instalada por npm install ds-tis. Em produção, prefira "ds-tis": "1.0.0" no package.json; npm install ds-tis@beta fica reservado a futuras pré-releases. Fallback por release GitHub: npm install github:tis-experience/ds-tis#v1.0.0.

Importe o CSS público uma vez no entrypoint global do app:

import 'ds-tis/css';

Para Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs e Tooltip, inicialize o comportamento público quando o app renderizar ou hidratar os componentes. Ao desmontar (SPA, rota, portal), chame o destroy correspondente para limpar listeners:

import { initAccordions, destroyAccordions } from 'ds-tis/accordion';
import { initComboboxes, destroyComboboxes } from 'ds-tis/combobox';
import { initModals, destroyModals } from 'ds-tis/modal';
import { initActionMenus, destroyActionMenus } from 'ds-tis/menu';
import { initPopovers, destroyPopovers } from 'ds-tis/popover';
import { initToasts, destroyToasts } from 'ds-tis/toast';
import { initTabs, destroyTabs } from 'ds-tis/tabs';
import { initTooltips, destroyTooltips } from 'ds-tis/tooltip';

initAccordions();
initComboboxes();
initModals();
initActionMenus();
initPopovers();
initToasts();
initTabs();
initTooltips();

// ao sair da view / unmount:
destroyAccordions();
destroyComboboxes();
destroyModals();
destroyActionMenus();
destroyPopovers();
destroyToasts();
destroyTabs();
destroyTooltips();

Ter módulo required não significa automaticamente estar App-ready. Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs e Tooltip concluíram o gate executável da ADR-020. Seus módulos continuam obrigatórios quando os componentes forem usados, pois mantêm o contrato interativo e acessível publicado.

No Combobox App-ready, o foco DOM permanece no input enquanto as setas atualizam aria-activedescendant; Escape fecha o listbox sem remover esse foco. O evento ds-combobox-change expõe value, input, root e a option selecionada em detail.

No Modal App-ready, apenas os irmãos fora do caminho do diálogo recebem inert; o runtime preserva e restaura o estado anterior de cada nó. ds-modal-open e ds-modal-close expõem overlay, dialog e a referência de foco relevante em detail.

No Action Menu App-ready, menuitem, menuitemradio e menuitemcheckbox fazem parte do contrato. Itens aria-disabled permanecem alcançáveis pelo foco, mas não ativam nem fecham o menu; typeahead, setas, Home/End e Escape são mantidos pelo runtime.

No Tabs App-ready, o runtime mantém exatamente um tab no fluxo de foco, ignora tabs disabled nas setas/Home/End, sincroniza aria-selected com hidden nos painéis e garante entrada de foco no tabpanel selecionado. Botões de tab sem type explícito são normalizados para type="button", evitando submit acidental quando o componente está dentro de um formulário. ds-tabs-change expõe root, tab, panel e tab anterior em detail.

No Tooltip App-ready, o runtime assegura role="tooltip", ID e aria-describedby válidos mesmo quando o markup omite esses atributos. Foco e hover abrem sem mover o foco DOM; blur e saída conjunta fecham; Escape mantém o conteúdo dispensado até pointer/foco saírem. A área de conteúdo permanece hoverable conforme WCAG 1.4.13. ds-tooltip-show e ds-tooltip-hide expõem root, trigger e content em detail.

Para customização de tema, use o theme engine público:

import { applyTheme, toCssSnippet } from 'ds-tis/theme';

Quando fizer sentido partir de um template, use os exports publicados:

import loginTemplate from 'ds-tis/templates/login.html?raw';

O caminho ds-tis/templates/* referencia templates HTML públicos. Adapte conteúdo, rotas e dados ao app consumidor; não copie textos fictícios para produção.

React beta pelo registry shadcn

O pacote @tis/react não é público. A API React beta é distribuída como source pelo canal versionado https://tis-experience.github.io/ds-tis/registry/v1.

Descubra o catálogo em ds-tis/metadata/components ou no fallback público docs/api/components.json. Instale somente quando implementations.react.status for beta; use implementations.react.item como nome do item.

Configure o namespace no components.json do app:

{
  "registries": {
    "@tis": "https://tis-experience.github.io/ds-tis/registry/v1/{name}.json"
  }
}

Depois instale apenas o necessário:

npx shadcn@latest add @tis/button @tis/field @tis/input

O catálogo beta React evolui de forma independente. Não mantenha uma lista local nem deduza nomes shadcn: leia implementations.react.status e implementations.react.item em docs/api/components.json.

Não confunda as quatro saídas da ADR-023. Em docs/api/consumer-context.json, outputPolicy.outputs lista HTML/CSS/JS, Ark/Zag, React/shadcn/Base UI e Angular como alternativas coexistentes. A saída React usa technologies.react.distribution: "shadcn-registry", behaviorArchitecture: "base-ui" e providerRole: "output-provider". Isso não transforma Base UI em core nem substitui as outras saídas. Consulte o status da saída escolhida; não misture imports ou instruções entre elas.

O source instalado pertence ao app consumidor e pode ser revisado ou composto localmente. Preserve as classes públicas, o primeiro import global @import "ds-tis/css", as relações ARIA e as dependências fixadas pelo item.

Angular beta nativo

@tis/angular ainda não está publicado no registry npm. Use o tarball validado somente quando implementations.angular.status for beta; derive o entrypoint de implementations.angular.entrypoint e mantenha ds-tis/css como import global. Componentes Angular com status planned não possuem API oficial utilizável.

Runtime JS por componente

Consulte docs/api/components.json antes de importar módulos JS. Cada componente expõe runtime:

Campo	Significado
`null`	CSS-only — sem módulo JS publicado.
`runtime.level: "required"`	O contrato interativo e acessível depende de init (Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs e Tooltip).
`runtime.level: "optional"`	Reservado para enhancement que não seja necessário ao contrato acessível; nenhum módulo atual usa este nível.
`runtime.module`	Export do pacote (`ds-tis/accordion`, `ds-tis/combobox`, `ds-tis/modal`, `ds-tis/menu`, `ds-tis/popover`, `ds-tis/toast`, `ds-tis/tabs`, `ds-tis/tooltip`).
`runtime.init`	Função a chamar após render/hydration (`initAccordions`, `initComboboxes`, `initModals`, `initActionMenus`, `initPopovers`, `initToasts`, `initTabs`, `initTooltips`).
`runtime.destroy`	Função a chamar ao desmontar (`destroyAccordions`, `destroyComboboxes`, `destroyModals`, `destroyActionMenus`, `destroyPopovers`, `destroyToasts`, `destroyTabs`, `destroyTooltips`).
`runtime.events`	Eventos públicos emitidos pelo módulo (`ds-modal-open`, `ds-combobox-change`, etc.).

O array runtimeModules no topo de components.json lista todos os módulos publicados. Não importe JS de componentes com runtime: null.

Contrato responsivo

O DS usa estratégia intrinsic-first e não publica breakpoints automáticos. publicBreakpoints é uma lista vazia por design: variantes sm, md, lg ou full são escolhas explícitas do produto, não regras ativadas pela viewport. Consulte responsiveContract, responsiveProfiles e o campo responsive de cada componente em ds-tis/metadata/components.

container: o componente preserva sua anatomia na largura oferecida; o app mantém grid e reflow;
viewport-constrained: Modal e Tooltip aplicam limites intrínsecos contra a viewport;
consumer-managed-horizontal: Tabs, Breadcrumb e Pagination não removem nem resumem itens; o app decide overflow, redução ou composição alternativa;
consumer-selectable-width: Button oferece escolhas explícitas de largura; o app decide quando usá-las.

O tarball é exercitado em 320×568, 568×320 e 1280×800. Isso prova a fixture de referência e os limites de overlays; não substitui teste do conteúdo, zoom, idioma, orientação e layout reais do produto consumidor.

Regras de implementação

Escolha componentes existentes antes de criar markup ad hoc. Consulte readiness, responsibility e runtime em docs/api/components.json.
Use a anatomia pública do componente conforme documentada. Não use classes internas isoladas como se fossem componentes autônomos.
Formulários devem compor ds-field com o controle real: ds-input, ds-select, ds-textarea, ds-combobox, ds-checkbox, ds-radio ou ds-toggle. Para Input, o campo nativo continua dentro da anatomia pública com ds-input__field.
Não hardcode #hex, rgb(), px ou rem quando existir token, classe, variante ou utilitário público do DS para o mesmo papel.
Preserve a cadeia visual do DS. Tokens públicos aparecem como CSS variables var(--ds-...); não invente valores locais para cor, spacing, radius, border, typography ou focus ring sem justificar.
Preserve acessibilidade: landmarks semânticos, heading order, labels, aria-*, aria-describedby, aria-expanded, aria-current, teclado, estados disabled/error/read-only e focus ring visível.
Estados não são decoração. Implemente loading, empty, error, disabled, hover, focus e responsive quando fizerem parte do fluxo esperado.
Ícones devem seguir o padrão do projeto consumidor quando houver biblioteca instalada; quando a tela reproduzir exemplos do DS, prefira o mesmo vocabulário visual documentado.
Em React ou Angular, prefira a saída oficial quando o respectivo status for beta; nos demais casos e em Vue/Svelte, declare o wrapper como adaptação local e não invente pacote, entrypoint ou item oficial.
Não altere tokens, CSS gerado ou documentação do DS a partir do projeto consumidor. Se encontrar gap real, registre a limitação e abra demanda para o DS.

Fluxo recomendado

Leia o pedido, identifique a stack e encontre o entrypoint global onde ds-tis/css deve ser importado.
Faça inventário das partes da tela: navegação, formulário, feedback, cards, overlays, listas, loading, empty states e ações.
Mapeie cada parte para componentes DS existentes e confira readiness. Só use markup local quando o DS não tiver componente adequado.
Consulte a página HTML do componente e docs/api/components.json antes de escrever a anatomia.
Implemente com classes públicas do DS, sem copiar classes internas fora do contexto do componente.
Inicialize módulos JS quando components.json indicar runtime — required sempre; optional quando a tela precisar de teclado, overlay ou focus management completo.
Aplique tema com ds-tis/theme somente quando a tela tiver requisito de brand/mode em runtime.
Rode os testes e linters do projeto consumidor. Quando possível, valide acessibilidade com axe, Playwright, browser real ou ferramenta equivalente.
Entregue evidências: componentes usados, imports, tokens/classes relevantes, validação a11y e limites assumidos.

Adaptação por framework

React instala os componentes beta pelo registry; Angular instala os entrypoints beta da biblioteca nativa. Fora dessas coberturas, React, Angular, Vue e Svelte podem renderizar a anatomia pública do DS por meio de componentes locais. Toda adaptação local deve:

manter os nomes de classes públicas do DS;
preservar labels, IDs, aria-* e relações for/id;
expor props locais alinhadas ao produto, não prometer API oficial do DS;
manter inicialização de módulos JS depois do render/hydration quando necessário;
evitar recriar comportamento complexo quando o DS já exporta helper público, como ds-tis/combobox.

Exemplo de limite correto: "Criei AppTextField no app consumidor usando ds-field + ds-input; isso é wrapper local do app, não componente oficial exportado por ds-tis."

Prompt curto para agent consumidor

Copie este bloco para iniciar um agent que vai implementar uma tela usando o DS TIS em um projeto consumidor:

Role: Agent consumidor do DS TIS.

Artefato de entrada:
- Pedido da tela/fluxo.
- Stack do projeto consumidor.
- Arquivos atuais do app que definem layout, estilos globais, rotas e componentes locais.
- Versao instalada de ds-tis, se existir.

Fontes obrigatorias:
- README.md
- docs/llms.txt
- docs/llms-full.txt
- docs/api/consumer-context.json (tecnologias e registry)
- docs/api/components.json (implementations, readiness, responsibility e runtime)
- docs/api/tokens.json
- docs/<component>.html dos componentes usados
- docs/templates/ ou ds-tis/templates/* quando houver template aplicavel

Regras:
- Instale via `npm install ds-tis`; durante a beta, fixe a versão exata em produção.
- Importe ds-tis/css uma vez no entrypoint global.
- Para React, quando implementations.react.status for beta, configure @tis em components.json e instale implementations.react.item via shadcn. Nunca invente @tis/react ou um item ausente.
- Para Angular, quando implementations.angular.status for beta, instale o tarball validado e importe implementations.angular.entrypoint. Não anuncie @tis/angular como pacote npm público.
- Para cada componente usado, derive o módulo de `runtime.module` em docs/api/components.json; quando `runtime.level` for required, chame init após render/hydration e destroy antes do unmount.
- Prefira componentes app-ready; trate composition como fronteira explícita do app e não use experimental em fluxo crítico sem registrar a limitação.
- Use ds-tis/theme apenas para requisito real de tema/brand em runtime.
- Escolha componentes existentes antes de criar markup ad hoc.
- Use anatomia publica dos componentes; nao use classes internas isoladas.
- Form controls devem compor ds-field + controle real, como ds-input + ds-input__field.
- Nao hardcode hex/rgb/px/rem quando existir token, classe ou variante publica.
- Preserve landmarks, labels, aria-*, teclado, focus ring e estados disabled/error/read-only.
- Fora das coberturas React/Angular beta e em Vue/Svelte, adapte a anatomia publica em wrappers locais do app e declare esse limite.

Saida esperada:
- Arquivos alterados.
- Componentes DS usados e por que foram escolhidos.
- Imports DS adicionados.
- Tokens/classes publicas relevantes.
- Evidencia de acessibilidade e teclado.
- Limites assumidos ou gaps do DS que precisam virar demanda.

Bloqueado antes de:
- Criar API oficial do DS que nao existe.
- Alterar tokens ou CSS do pacote ds-tis dentro do app consumidor.
- Trocar componente DS existente por markup ad hoc sem justificar.
- Remover labels, aria-* ou focus ring.

Checklist de entrega

Antes de concluir, o agent deve reportar:

componentes DS usados e componentes descartados;
readiness e responsabilidade dos componentes usados;
imports e distribuição usados: ds-tis/css, módulos JS com runtime, itens @tis/* do registry, ds-tis/theme e/ou ds-tis/templates/*;
classes públicas principais usadas, como ds-field, ds-input e ds-input__field;
tokens CSS relevantes quando houver customização via var(--ds-...);
evidência de acessibilidade: labels, landmarks, aria-*, teclado, focus ring e contraste quando aplicável;
estados implementados: default, hover, focus, disabled, error, loading, empty e responsive conforme o fluxo;
limitações assumidas e gaps que precisam ser tratados no DS ou no produto.

Se um item não se aplica, declare o motivo. Não deixe ausência de estado ou acessibilidade implícita.

This guide is the official instruction for AI agents implementing screens in consumer applications with DS TIS. It does not replace AGENTS.md, which is for maintaining this repository. The focus here is consumption: building real screens with the package's public API without inventing an official layer that does not exist.

Use this guide before generating, reviewing or refactoring any screen in a consumer application.

Scope

DS TIS is stack-agnostic. Its stable public foundation is HTML, CSS and JavaScript distributed by the ds-tis package. React has a beta source distribution through a shadcn registry, and Angular has a native beta library validated through a local tarball. Both continue to depend on public DS CSS and tokens.

Do not present @tis/react as a public package or @tis/angular as published on npm. Use an output only when docs/api/components.json marks its status as beta or stable. For Vue, Svelte, and unavailable React or Angular components, wrappers remain local consumer-project adaptations.

The operating rule for agents is explicit: do not invent official wrappers. Outside the beta catalog, document the wrapper as application-local code.

Expected inputs

Before implementing, the agent must gather:

the goal of the screen or flow;
the consumer project's stack and conventions;
the installed ds-tis version, when available;
existing routes, layouts, providers and local patterns;
expected states: loading, empty, error, disabled, success, read-only, destructive and responsive;
accessibility, language, data and permission constraints.

If these inputs are unclear, inspect the project first. Ask the owner only when the decision changes product behavior, real data, permissions or local architecture.

Required sources

Before writing new markup, consult the public DS sources:

README.md for installation and primary imports;
docs/llms.txt for the lightweight LLM index;
docs/llms-full.txt for complete canonical context;
docs/api/components.json for components, technology implementations (implementations.web, implementations.ark, implementations.react, and implementations.angular), readiness, responsibility, variants, consumed tokens and JS runtime metadata (runtime.level, runtime.module, runtime.init, runtime.destroy, runtime.events);
docs/api/tokens.json for Foundation, Semantic and Component layers;
component pages at docs/<component>.html;
templates under docs/templates/ and exports under ds-tis/templates/* when the flow matches a published pattern.

Do not depend on memory or assumptions about classes. When in doubt, read the component page and the JSON API.

The tarball includes machine-readable context. After installation, read it through ds-tis/metadata, ds-tis/metadata/components, ds-tis/metadata/tokens, ds-tis/agent-guide, ds-tis/agent-guide/en, ds-tis/llms and ds-tis/llms-full, or directly from node_modules/ds-tis/docs/. Without the package, use the public fallback https://tis-experience.github.io/ds-tis/docs/api/components.json.

ds-tis/metadata points to consumer-context.json, a compact manifest with official entrypoints, available technologies, the React registry, version, sources of truth and the responsive contract. JSON modules may require an import attribute in some stacks; agents and scripts may also read the file through the package resolver or filesystem.

Readiness and responsibility

Before selecting a component, read readiness and responsibility in docs/api/components.json:

Readiness	Expected use
`app-ready`	Recommended for applications within the documented public API.
`composition`	Public and stable, but the application owns orchestration, navigation or shared state.
`experimental`	Do not use in a critical flow without explicitly accepting the limitation in `readinessNotes`.

responsibility.model identifies who owns behavior:

native: use the appropriate HTML element; the app owns data and business events;
presentation: there is no component runtime; the app supplies content and context;
consumer: the DS provides visual composition, while the app owns orchestration;
ds-runtime: the DS owns reusable interaction; initialize the module declared in runtime.

Do not promote an Experimental component to App-ready locally. If the project fills a gap with custom code, identify it as a local adaptation and record the demand for the DS.

Official imports

Install the current version from the npm registry:

npm install ds-tis

Install the stable release with npm install ds-tis. In production, prefer "ds-tis": "1.0.0" in package.json; reserve npm install ds-tis@beta for future prereleases. GitHub release fallback: npm install github:tis-experience/ds-tis#v1.0.0.

Import the public CSS once in the application's global entrypoint:

import 'ds-tis/css';

For Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs and Tooltip, initialize the public behavior after render or hydration. On teardown (SPA route, view or portal), call the corresponding destroy function to remove listeners:

import { initAccordions, destroyAccordions } from 'ds-tis/accordion';
import { initComboboxes, destroyComboboxes } from 'ds-tis/combobox';
import { initModals, destroyModals } from 'ds-tis/modal';
import { initActionMenus, destroyActionMenus } from 'ds-tis/menu';
import { initPopovers, destroyPopovers } from 'ds-tis/popover';
import { initToasts, destroyToasts } from 'ds-tis/toast';
import { initTabs, destroyTabs } from 'ds-tis/tabs';
import { initTooltips, destroyTooltips } from 'ds-tis/tooltip';

initAccordions();
initComboboxes();
initModals();
initActionMenus();
initPopovers();
initToasts();
initTabs();
initTooltips();

// when leaving the view / unmounting:
destroyAccordions();
destroyComboboxes();
destroyModals();
destroyActionMenus();
destroyPopovers();
destroyToasts();
destroyTabs();
destroyTooltips();

A required module does not automatically make a component App-ready. Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs and Tooltip have completed the executable ADR-020 gate. Their modules remain required whenever those components are used because they preserve the published interactive and accessible contract.

In the App-ready Combobox, DOM focus stays on the input while arrow keys update aria-activedescendant; Escape closes the listbox without moving focus. The ds-combobox-change event exposes value, input, root and the selected option in detail.

In the App-ready Modal, only siblings outside the dialog path receive inert; the runtime preserves and restores each node's previous state. ds-modal-open and ds-modal-close expose the overlay, dialog and relevant focus reference in detail.

In the App-ready Action Menu, menuitem, menuitemradio and menuitemcheckbox are part of the contract. aria-disabled items remain focusable but do not activate or close the menu; typeahead, arrows, Home/End and Escape are maintained by the runtime.

In the App-ready Tabs, the runtime keeps exactly one tab in the focus order, skips disabled tabs with arrows and Home/End, synchronizes aria-selected with hidden on panels and ensures focus entry on the selected tabpanel. Tab buttons without an explicit type are normalized to type="button", preventing accidental form submission. ds-tabs-change exposes the root, tab, panel and previous tab in detail.

In the App-ready Tooltip, the runtime ensures valid role="tooltip", ID and aria-describedby even when the markup omits them. Focus and hover open it without moving DOM focus; blur and leaving both trigger and content close it; Escape keeps it dismissed until pointer and focus leave. Content stays hoverable under WCAG 1.4.13. ds-tooltip-show and ds-tooltip-hide expose the root, trigger and content in detail.

For theme customization, use the public theme engine:

import { applyTheme, toCssSnippet } from 'ds-tis/theme';

When a published template is a useful starting point, use its export:

import loginTemplate from 'ds-tis/templates/login.html?raw';

ds-tis/templates/* points to public HTML templates. Adapt content, routes and data to the consumer application; do not copy fictional text into production.

React beta through the shadcn registry

The @tis/react package is not public. The beta React API is distributed as source through the versioned channel https://tis-experience.github.io/ds-tis/registry/v1.

Discover the catalog through ds-tis/metadata/components or the public docs/api/components.json fallback. Install only when implementations.react.status is beta; use implementations.react.item as the item name.

Configure the namespace in the app's components.json:

{
  "registries": {
    "@tis": "https://tis-experience.github.io/ds-tis/registry/v1/{name}.json"
  }
}

Then install only what is needed:

npx shadcn@latest add @tis/button @tis/field @tis/input

The React beta catalog evolves independently. Do not maintain a local list or infer shadcn names: read implementations.react.status and implementations.react.item in docs/api/components.json.

Do not conflate the four outputs defined by ADR-023. In docs/api/consumer-context.json, outputPolicy.outputs lists HTML/CSS/JS, Ark/Zag, React/shadcn/Base UI, and Angular as coexisting alternatives. The React output uses technologies.react.distribution: "shadcn-registry", behaviorArchitecture: "base-ui", and providerRole: "output-provider". This does not turn Base UI into the core or replace the other outputs. Read the status of the selected output and never mix imports or instructions across them.

Installed source belongs to the consumer app and can be reviewed or composed locally. Preserve public classes, the first global @import "ds-tis/css", ARIA relationships, and dependencies pinned by the item.

Native Angular beta

@tis/angular is not published on the npm registry. Use the validated tarball only when implementations.angular.status is beta; derive the entrypoint from implementations.angular.entrypoint and keep ds-tis/css as the global import. Angular components with planned status do not expose a usable official API.

JavaScript runtime by component

Read docs/api/components.json before importing JS modules. Each component exposes runtime:

Field	Meaning
`null`	CSS-only; no published JS module.
`runtime.level: "required"`	The interactive and accessible contract depends on initialization (Accordion, Combobox, Modal, Action Menu, Popover, Toast, Tabs and Tooltip).
`runtime.level: "optional"`	Reserved for enhancements unnecessary to the accessible contract; no current module uses this level.
`runtime.module`	Package export (`ds-tis/accordion`, `ds-tis/combobox`, `ds-tis/modal`, `ds-tis/menu`, `ds-tis/popover`, `ds-tis/toast`, `ds-tis/tabs`, `ds-tis/tooltip`).
`runtime.init`	Function called after render or hydration.
`runtime.destroy`	Function called during teardown.
`runtime.events`	Public events emitted by the module.

The top-level runtimeModules array in components.json lists every published module. Do not import JS for components with runtime: null.

Responsive contract

The DS uses an intrinsic-first strategy and publishes no automatic breakpoints. publicBreakpoints is intentionally empty: sm, md, lg and full variants are explicit product choices, not viewport-triggered rules. Read responsiveContract, responsiveProfiles and each component's responsive field in ds-tis/metadata/components.

container: the component preserves its anatomy in the supplied width; the app owns grid and reflow;
viewport-constrained: Modal and Tooltip apply intrinsic viewport limits;
consumer-managed-horizontal: Tabs, Breadcrumb and Pagination do not remove or summarize items; the app decides overflow, reduction or an alternative composition;
consumer-selectable-width: Button provides explicit width choices; the app decides when to apply them.

The tarball is exercised at 320×568, 568×320 and 1280×800. This proves the reference fixture and overlay limits; it does not replace tests with the consumer product's content, zoom, language, orientation and layout.

Implementation rules

Choose existing components before creating ad hoc markup. Read readiness, responsibility and runtime in docs/api/components.json.
Use the documented public anatomy. Do not use isolated internal classes as autonomous components.
Forms must combine ds-field with the actual control: ds-input, ds-select, ds-textarea, ds-combobox, ds-checkbox, ds-radio or ds-toggle. For Input, the native field remains inside the public anatomy with ds-input__field.
Do not hardcode #hex, rgb(), px or rem when a public token, class, variant or utility exists for the same role.
Preserve the DS visual chain. Public tokens appear as var(--ds-...); do not invent local values for color, spacing, radius, border, typography or focus ring without justification.
Preserve accessibility: semantic landmarks, heading order, labels, aria-*, aria-describedby, aria-expanded, aria-current, keyboard support, disabled/error/read-only states and a visible focus ring.
States are not decoration. Implement loading, empty, error, disabled, hover, focus and responsive states when they belong to the expected flow.
Icons should follow the consumer project's library when one exists; when reproducing DS examples, prefer the documented visual vocabulary.
In React or Angular, prefer the official output when its status is beta; otherwise, and in Vue/Svelte, declare the wrapper as a local adaptation and do not invent an official package, entrypoint, or item.
Do not change DS tokens, generated CSS or documentation from the consumer project. Record real gaps and open a demand for the DS.

Recommended workflow

Read the request, identify the stack and find the global entrypoint for ds-tis/css.
Inventory the screen: navigation, forms, feedback, cards, overlays, lists, loading, empty states and actions.
Map each part to an existing DS component and check readiness. Use local markup only when no suitable DS component exists.
Read the component HTML page and docs/api/components.json before writing anatomy.
Implement with public DS classes without copying internal classes outside their component context.
Initialize JS modules when components.json declares a runtime: always for required, and for optional when the screen needs the enhancement.
Apply ds-tis/theme only for an actual runtime brand or mode requirement.
Run the consumer project's tests and linters. When possible, validate accessibility with axe, Playwright, a real browser or an equivalent tool.
Deliver evidence: components, imports, relevant tokens/classes, accessibility validation and assumed limits.

Framework adaptation

React installs beta components through the registry; Angular installs beta entrypoints from the native library. Outside those coverage sets, React, Angular, Vue, and Svelte may render public DS anatomy through local components. Every local adaptation must:

preserve public DS class names;
preserve labels, IDs, aria-* and for/id relationships;
expose local product-aligned props without promising an official DS API;
initialize JS modules after render or hydration when required;
avoid recreating complex behavior when the DS already exports a public helper such as ds-tis/combobox.

Correct boundary example: "I created AppTextField in the consumer application using ds-field + ds-input; this is a local app wrapper, not an official component exported by ds-tis."

Short prompt for a consumer agent

Copy this block to start an agent that will implement a screen with DS TIS in a consumer project:

Role: DS TIS consumer agent.

Input artifact:
- Screen or flow request.
- Consumer project stack.
- Current app files defining layout, global styles, routes and local components.
- Installed ds-tis version, if any.

Required sources:
- README.md
- docs/llms.txt
- docs/llms-full.txt
- docs/api/consumer-context.json (technologies and registry)
- docs/api/components.json (implementations, readiness, responsibility and runtime)
- docs/api/tokens.json
- docs/<component>.html for every component used
- docs/templates/ or ds-tis/templates/* when a relevant template exists

Rules:
- Install with `npm install ds-tis`; pin the exact version in production during beta.
- Import ds-tis/css once in the global entrypoint.
- In React, when implementations.react.status is beta, configure @tis in components.json and install implementations.react.item through shadcn. Never invent @tis/react or a missing item.
- In Angular, when implementations.angular.status is beta, install the validated tarball and import implementations.angular.entrypoint. Do not advertise @tis/angular as a public npm package.
- For each component, derive the module from runtime.module in docs/api/components.json; when runtime.level is required, call init after render/hydration and destroy before unmount.
- Prefer App-ready components; treat Composition as an explicit app boundary and do not use Experimental in critical flows without recording the limitation.
- Use ds-tis/theme only for an actual runtime theme or brand requirement.
- Choose existing components before creating ad hoc markup.
- Use public component anatomy; do not use isolated internal classes.
- Form controls must combine ds-field with the actual control, such as ds-input + ds-input__field.
- Do not hardcode hex/rgb/px/rem when a public token, class or variant exists.
- Preserve landmarks, labels, aria-*, keyboard behavior, focus ring and disabled/error/read-only states.
- Outside the React/Angular beta coverage and in Vue/Svelte, adapt public anatomy through local app wrappers and state that boundary.

Expected output:
- Changed files.
- DS components used and why.
- Added DS imports.
- Relevant public tokens and classes.
- Accessibility and keyboard evidence.
- Assumed limits or DS gaps that require a demand.

Blocked before:
- Creating an official DS API that does not exist.
- Changing ds-tis package tokens or CSS inside the consumer application.
- Replacing an existing DS component with ad hoc markup without justification.
- Removing labels, aria-* or focus ring.

Delivery checklist

Before finishing, the agent must report:

DS components used and alternatives rejected;
readiness and responsibility for each component used;
imports and distribution used: ds-tis/css, JS modules with runtime, @tis/* registry items, ds-tis/theme and/or ds-tis/templates/*;
main public classes such as ds-field, ds-input and ds-input__field;
relevant CSS tokens when customization uses var(--ds-...);
accessibility evidence: labels, landmarks, aria-*, keyboard, focus ring and contrast when applicable;
implemented states: default, hover, focus, disabled, error, loading, empty and responsive as required by the flow;
assumed limitations and gaps that belong in the DS or product backlog.

If an item does not apply, state why. Never leave missing states or accessibility implicit.