@cognitvs/a11y-widget 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @cognitvs/a11y-widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Widget de acessibilidade digital moderno, plug-and-play e 100% agnóstico de frameworks (Web Component nativo em TypeScript). Desenvolvido pela **Cognitvs** em conformidade com as diretrizes de acessibilidade **WCAG 2.1**.
+
+[![NPM Version](https://img.shields.io/npm/v/@cognitvs/a11y-widget.svg)](https://www.npmjs.com/package/@cognitvs/a11y-widget)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![WCAG 2.1](https://img.shields.io/badge/WCAG-2.1%20AA-0077d4.svg)](https://www.w3.org/WAI/standards-guidelines/wcag/)
+[![Demonstração ao Vivo](https://img.shields.io/badge/Demo%20ao%20Vivo-a11y--cognitvs.vercel.app-0077d4.svg?style=flat&logo=vercel)](https://a11y-cognitvs.vercel.app)
+
+<p align="center">
+  <a href="https://a11y-cognitvs.vercel.app" target="_blank" rel="noopener noreferrer">
+    <img src="https://a11y-cognitvs.vercel.app/print_01.png" alt="Demonstração do widget de acessibilidade Cognitvs com painel expandido e opções assistivas" width="100%" />
+  </a>
+</p>
+
+---
+
+## 🌟 Destaques
+
+- 🧩 **Zero Dependências de Runtime:** Pacote leve, seguro e 100% autocontido.
+- 🛡️ **Encapsulamento com Shadow DOM:** Não conflita com estilos existentes da sua aplicação.
+- 🌐 **Compatível com Qualquer Stack:** React, Next.js, Vue, Nuxt, Angular, Svelte, Qwik ou HTML puro.
+- ⚡ **Persistência Inteligente:** Lembra as escolhas do usuário no `localStorage`.
+- 🦻 **Tradutor LIBRAS (VLibras Oficial):** Integração com avatar do governo brasileiro sob demanda.
+- 🗣️ **Leitor de Tela Nativo com Efeito Karaokê:** Destaca palavras uma a uma durante a leitura falada.
+- 🧲 **Ímã de Cursor Magnético:** Atração suave do mouse aos botões e links para pessoas com tremor essencial ou dificuldades motoras.
+
+---
+
+## 📦 Instalação
+
+```bash
+npm install @cognitvs/a11y-widget
+```
+
+Ou usando `yarn` / `pnpm`:
+
+```bash
+pnpm add @cognitvs/a11y-widget
+```
+
+---
+
+## 🚀 Como Usar
+
+### 1. Via CDN (HTML Puro ou CMS como WordPress/Webflow)
+
+Basta adicionar a tag `<script>` no seu documento:
+
+```html
+<!-- Carrega o componente -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/@cognitvs/a11y-widget/dist/a11y-widget.js"></script>
+
+<!-- Insere o widget -->
+<cognitvs-a11y></cognitvs-a11y>
+```
+
+### 2. Em Projetos Modernos (React, Next.js, Vue, Vite, etc.)
+
+No arquivo de entrada da sua aplicação (ex: `main.ts`, `index.tsx`, `App.tsx` ou layout principal):
+
+```ts
+import '@cognitvs/a11y-widget';
+```
+
+Em seguida, utilize o elemento customizado no seu template ou JSX:
+
+```html
+<cognitvs-a11y></cognitvs-a11y>
+```
+
+*(No React/Next.js com TypeScript, se necessário declare a tag intrínseca ou utilize `dangerouslySetInnerHTML` / componente wrapper).*
+
+---
+
+## ⚙️ Atributos e Customização
+
+O componente aceita atributos HTML para adequar-se à identidade visual do seu projeto:
+
+```html
+<cognitvs-a11y
+  theme="auto"
+  accent-color="#ea580c"
+  position="bottom-right"
+  storage-prefix="minha_empresa"
+  show-banner="true"
+></cognitvs-a11y>
+```
+
+| Atributo | Padrão | Descrição |
+|---|---|---|
+| `accent-color` | `#ea580c` | Cor primária dos botões, bordas e destaques. |
+| `theme` | `auto` | Tema do painel (`auto`, `light` ou `dark`). |
+| `position` | `bottom-right` | Posição na tela (`bottom-right` ou `bottom-left`). |
+| `storage-prefix`| `cognitvs` | Prefixo das chaves gravadas no `localStorage`. |
+| `show-banner` | `true` | Exibe o aviso superior de acessibilidade na primeira visita. |
+
+---
+
+## ♿ Recursos Disponíveis
+
+### Ajustes Visuais
+- **Escala de Fonte:** Redimensiona o texto da página de 80% até 200%.
+- **Alto Contraste:** Modo de contraste reforçado com bordas visíveis.
+- **Máscara de Leitura:** Foco visual que escurece o restante da tela (modos inteligente e livre).
+- **Filtros de Daltonismo:** Protanopia, Deuteranopia, Tritanopia e Monocromia via matriz SVG calibrada.
+
+### Audição e Fala
+- **Leitor de Tela (TTS):** Síntese de voz com destaque karaokê e controle de velocidade (0.5x, 1x, 1.5x).
+- **Tradutor LIBRAS:** Ativação instantânea do VLibras oficial.
+
+### Interação e Mobilidade
+- **Ponteiro Gigante:** Cursor ampliado de alta visibilidade.
+- **Navegação por Teclado:** Foco nítido com anéis de alto contraste via tecla `TAB`.
+- **Rolagem Assistida:** Botões laterais para navegação rápida de página.
+- **Ímã de Cliques:** Atração física do cursor a elementos clicáveis (força suave e forte).
+- **Destacar Links:** Realça botões e hiperlinks clicáveis na interface.
+
+### Cognitivo e Foco
+- **Pausar Animações:** Desativa transições, GIFs e animações CSS (`prefers-reduced-motion`).
+- **Ajuste para Dislexia:** Substituição de tipografia para leitura facilitada.
+- **Espaçamento de Texto:** Aumenta entrelinhas e espaçamento entre letras.
+
+---
+
+## 🔒 Segurança e Privacidade
+
+- **Zero Coleta de Dados:** Toda a configuração do usuário é mantida exclusivamente no navegador (`localStorage`).
+- **Sem Risco de Supply Chain:** Não há dependências de terceiros empacotadas no bundle final.
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença **MIT**. Desenvolvido com carinho pela equipe **[Cognitvs](https://cognitvs.vercel.app)**.