STYLE_GUIDE.md

# Viva Mais AI Style Guide

Viva Mais AI is a local-first WhatsApp copilot for travel agencies. The visual
system should make the app feel friendly and memorable while keeping the CRM
dashboard calm enough for repeated professional use.

## Brand Idea

The mascot is a robot cowfish: round, curious, helpful, and travel-ready. It
combines a cowfish silhouette with a friendly visor face, teal fins, tiny horns,
an antenna, and a travel tag charm.

Use the mascot as the emotional layer of the product:

- Friendly, not childish.
- Operational, not decorative only.
- Travel-agency warm, not generic SaaS blue.
- Local-first and private, not cloud-magic mysterious.

## Asset Inventory

| Asset | Path | Use |
| --- | --- | --- |
| Horizontal logo | `assets/brand/vivamais-ai-logo-horizontal.png` | App header, README hero, Space card. |
| Square logo | `assets/brand/vivamais-ai-logo-square.png` | Social previews, thumbnails, square placements. |
| App icon | `assets/brand/vivamais-ai-app-icon.png` | Space avatar, favicon source, launcher icon. |
| Logo mark | `assets/brand/vivamais-ai-mark.png` | Compact badge mark when text is already nearby. |
| Wordmark | `assets/brand/vivamais-ai-wordmark.png` | Places where the mascot would be too large. |
| Mascot cutout | `assets/mascot/robot-cowfish.png` | Empty states, welcome panels, hero visuals. |
| Mascot 512 | `assets/mascot/robot-cowfish-512.png` | Smaller UI placements. |
| State sheet | `assets/mascot/robot-cowfish-state-sheet.png` | Reference sheet for all mascot states. |
| Brand preview | `assets/previews/brand-assets-preview.png` | Quick visual QA and documentation. |
| Animation preview | `assets/previews/mascot-animation-spritesheets-preview.png` | QA board for the sprite animations. |

## Logo Rules

- Keep the circular cowfish mark to the left of the wordmark in horizontal
  layouts.
- Keep `Viva Mais` in Navy and `AI` in Coral.
- Keep the route line under the wordmark subtle; it is a motion cue, not a
  divider.
- Do not recreate the logo with generated text. Use the provided PNGs so the
  name stays readable.
- Give the horizontal logo clear space at least equal to the cowfish antenna
  height.
- Use the square logo when the available width is less than `480px`.
- Avoid placing the logo over busy photos, gradients, or patterned surfaces.

## Mascot States

| State | Path | Suggested UI moment |
| --- | --- | --- |
| Smiling | `assets/mascot/states/robot-cowfish-smiling.png` | Ready, idle, welcome, success-neutral. |
| Thinking | `assets/mascot/states/robot-cowfish-thinking.png` | Q&A, reasoning, extracting insights. |
| Loading puffed | `assets/mascot/states/robot-cowfish-loading-puffed.png` | Model processing, upload parsing, waiting. |
| Scanning document | `assets/mascot/states/robot-cowfish-scanning-document.png` | Receipt, ticket, voucher, or document OCR. |
| Celebrating reservation | `assets/mascot/states/robot-cowfish-celebrating-reservation.png` | Reservation found, sale completed, payment matched. |
| Sleepy low-power | `assets/mascot/states/robot-cowfish-sleepy-low-power.png` | No file, paused session, empty state. |

Use one mascot state per major panel. Avoid placing multiple large mascots in a
single viewport unless it is documentation or a preview board.

## Mascot Animation Assets

Each animation has both a GIF and a horizontal spritesheet. Spritesheets are
`4096x512`: eight `512x512` frames in a single row. Frame `n` starts at
`x = n * 512`.

| State | Spritesheet | GIF |
| --- | --- | --- |
| Smiling | `assets/mascot/spritesheets/robot-cowfish-smiling-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-smiling.gif` |
| Thinking | `assets/mascot/spritesheets/robot-cowfish-thinking-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-thinking.gif` |
| Loading puffed | `assets/mascot/spritesheets/robot-cowfish-loading-puffed-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-loading-puffed.gif` |
| Scanning document | `assets/mascot/spritesheets/robot-cowfish-scanning-document-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-scanning-document.gif` |
| Celebrating reservation | `assets/mascot/spritesheets/robot-cowfish-celebrating-reservation-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-celebrating-reservation.gif` |
| Sleepy low-power | `assets/mascot/spritesheets/robot-cowfish-sleepy-low-power-spritesheet.png` | `assets/mascot/gifs/robot-cowfish-sleepy-low-power.gif` |

Keep the state-specific GIFs separate. Do not use a single mixed-state GIF for
loading, because it makes the pet jump between unrelated actions.

## Tab Icons

| Tab | Icon |
| --- | --- |
| Resumo | `assets/tabs/tab-resumo.png` |
| Orcamentos | `assets/tabs/tab-orcamentos.png` |
| Reservas | `assets/tabs/tab-reservas.png` |
| Embarques | `assets/tabs/tab-embarques.png` |
| Pagamentos | `assets/tabs/tab-pagamentos.png` |
| Pedidos | `assets/tabs/tab-pedidos.png` |
| Hospedagens | `assets/tabs/tab-hospedagens.png` |
| Documentos | `assets/tabs/tab-documentos.png` |
| Nao categorizados | `assets/tabs/tab-nao-categorizados.png` |
| Conversa | `assets/tabs/tab-conversa.png` |
| Rastreamento | `assets/tabs/tab-rastreamento.png` |

The tab icons are transparent skeuomorphic travel glyphs in the Navy/teal
palette with soft glossy highlights, designed to sit directly on dark
backgrounds (the sidebar and the summary board) without a plate. They should be
displayed at `28px` to `32px` in tabs and the board, and can scale to `64px` in
empty states or summaries.

## UI Shape Language

- Use compact cards for repeated data, not large decorative hero cards.
- Prefer `8px` radius for dashboard cards and inputs.
- Use circular or softly rounded icon badges for navigation and status.
- Keep icon strokes Navy and use a single accent per icon.
- Avoid nested cards. Use spacing, section bands, and clear headings instead.
- Keep text density appropriate for a CRM: compact, scan-friendly, and calm.

## Illustration Rules

- The cowfish should always have Mango body, Coral spots, Teal fins, Navy visor,
  tiny horns, antenna, and travel tag.
- Keep the face expressive with simple visor eyes; do not add a mouth outside
  the visor unless it is inside the generated state art.
- Travel cues should be small: tag, suitcase, boarding pass, route line,
  document scan beam.
- Do not introduce other mascots or animals.
- Do not use realistic fish photography, dark sci-fi robots, or generic
  chatbot heads.

## Motion Rules

Recommended placements:

- Upload processing: `robot-cowfish-loading-puffed.gif`.
- Vision extraction: `robot-cowfish-scanning-document.gif`.
- Q&A: `robot-cowfish-thinking.gif`.
- Done state: `robot-cowfish-celebrating-reservation.gif`.
- Empty state: `robot-cowfish-sleepy-low-power.gif` or
  `robot-cowfish-smiling.gif`.

Keep the GIF under the main status message or beside a progress area. Do not
place animated mascot states inside dense tables.