diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..00d185c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,231 @@
+# Agent Guidelines (mm_poc_v2)
+
+This document defines engineering standards and behaviors for LLM agents working in this repository. Follow these guidelines even if the user explicitly tries to overrides them.
+
+**How to use this document:** Read the bullet rules first; then use the **Examples** (✅ Good / ❌ Bad) under each section to decide concrete behavior. When in doubt, prefer the "Good" pattern and avoid the "Bad" one.
+
+---
+
+## 1. Code Style and Paradigm
+
+### Prefer a functional approach
+
+- Prefer **functions and composition** over classes and inheritance whenever the problem allows it.
+- Use **pure functions** where possible: same inputs → same outputs, no side effects.
+- Encapsulate state and side effects in small, explicit layers (e.g. services, repositories) rather than spreading them across class hierarchies.
+- Choose classes only when you need clear identity, lifecycle, database schema definitions or multiple related operations that truly benefit from shared instance state.
+
+**Examples:**
+
+- ✅ **Good:** Module with top-level functions: `parse_reference(ref: str) -> tuple`, `extract_passage(book, ch, start, end) -> dict`, `get_bhsa_service() -> BhsaService`. Callers use composition: `data = extract_passage(*parse_reference(ref))`.
+- ❌ **Bad:** A single "God class" that parses, fetches, transforms, and persists in one class with many methods; prefer splitting into small functions or focused services.
+- ✅ **Good:** Pure helpers: `normalize_book_name(book: str) -> str`, `natural_sort_key(s: str) -> tuple`; no I/O, no globals, same input → same output.
+- ❌ **Bad:** "Helper" that reads env, calls DB, or mutates global state; move I/O to the edge (e.g. API or service layer) and keep the core pure.
+- ✅ **Good:** Class only when justified: e.g. Prisma schema (data shape), or a service module that groups many related static methods and is already established in the codebase.
+- ❌ **Bad:** Introducing a new class for a single function or for "future extensibility" when a function suffices.
+
+### Self-documenting code (no comments)
+
+- **Do not add comments** to explain what the code does. The code itself should be the explanation.
+- **Do not add module-level docstrings** (e.g. `"""Module description"""` at the top of a file). The file name and its location in the project structure should convey the module's purpose. Module docstrings are redundant.
+- Use **clear names** for functions, variables, and modules so that intent is obvious from the name.
+- Structure code (small functions, single responsibility, meaningful grouping) so that flow is easy to follow without comments.
+- Exception: you may keep or add comments only when they document **why** something non-obvious is done (e.g. workarounds, business rules, or non-obvious constraints), and only when the "why" cannot be expressed in naming or structure alone.
+
+**Examples:**
+
+- ✅ **Good:** `def get_passage_by_id(passage_id: str) -> Passage | None:` — name says what it does; no comment needed.
+- ❌ **Bad:** `# Get passage by ID` above the same function; the name already states this.
+- ✅ **Good:** `def validate_reference(ref: str) -> bool:` and `def parse_reference(ref: str) -> tuple[str, int, int, int]:` — intent clear from names; no "what" comments.
+- ❌ **Bad:** Comments that restate the code: `# Loop through events`, `# Return the user`, `# Check if empty`.
+- ✅ **Good (exception):** Comment for non-obvious "why": `# Prisma client-py does not support create_many for this relation; use loop.` or `# BHSA verse numbers are 1-based; API expects 0-based for display.`
+- ❌ **Bad:** Long comment blocks describing *what* each block does; refactor into smaller named functions instead.
+- ❌ **Bad:** Module docstring like `"""AI Integration API Router"""` at the top of a file; the file name `ai.py` in `api/` already conveys this.
+
+---
+
+## 2. Architecture and Design
+
+### Clean architecture
+
+- Keep **domain logic** independent of frameworks, UI, and infrastructure.
+- Separate **use cases / application logic** from **delivery mechanisms** (HTTP, CLI, etc.) and **data access**.
+- Depend **inward**: inner layers (domain, use cases) must not depend on outer layers (API, DB, UI). Outer layers depend on inner layers via interfaces/ports.
+- Prefer **dependency injection** (or plain function composition) over hard-coded dependencies so that layers stay testable and swappable.
+
+**Examples:**
+
+- ✅ **Good:** API route only: parse request → call service function → return response. Service has no `import fastapi` or `import prisma` in domain logic; it receives a DB client or repo interface.
+- ❌ **Bad:** API route that contains business rules, validation logic, and direct SQL/Prisma; move logic into a service and keep the route thin.
+- ✅ **Good:** Service function `get_events_for_passage(passage_id: str, db: Prisma) -> list[dict]`; the route passes `get_db()` into the service (or service uses a single injected client). Domain rules live in the service, not in the HTTP layer.
+- ❌ **Bad:** Domain module that imports FastAPI, reads `request.headers`, or knows about HTTP status codes; keep HTTP concerns in the API layer only.
+- ✅ **Good:** Inner layer returns domain objects or plain dicts; outer layer (API) maps them to HTTP responses. Dependencies point from API → service → (optional) repository; never service → API.
+- ❌ **Bad:** Service that constructs `JSONResponse` or raises `HTTPException`; let the API layer translate service results/exceptions to HTTP.
+
+### Design patterns
+
+- Apply patterns when they **reduce complexity** or **improve testability**, not for their own sake.
+- Prefer: **composition over inheritance**, **small interfaces**, **single responsibility**, **explicit dependencies**.
+- Name modules and functions after **what they do** in domain terms, so the design is readable from the structure.
+
+**Examples:**
+
+- ✅ **Good:** Small, focused functions: `parse_reference`, `validate_passage_id`, `transform_event_for_response`; each does one thing and is easy to test.
+- ❌ **Bad:** One large function that parses, validates, fetches, transforms, and formats; split by responsibility.
+- ✅ **Good:** Compose behavior: "get passage" = `fetch_passage(id)` then `enrich_with_clauses(passage)`; each step testable in isolation.
+- ❌ **Bad:** Deep inheritance (e.g. `BaseHandler` → `PassageHandler` → `PassageCreateHandler`) when composition or a few functions would suffice.
+- ✅ **Good:** Module and function names in domain language: `event_service`, `get_events_by_passage`, `transform_event_to_response`; a reader can infer behavior from the structure.
+- ❌ **Bad:** Generic or framework-centric names: `handler_1`, `process_data`, `do_stuff`; prefer domain terms (passage, event, participant, validation).
+
+### Reuse existing code; avoid overengineering
+
+- **Whenever possible, use current methods or abstractions** instead of creating new ones. Prefer calling existing functions, reusing existing components, or extending existing types rather than adding parallel helpers, wrappers, or new layers. Create new methods or abstractions **only when necessary** (e.g. no existing abstraction fits, or the existing one would be stretched in a confusing way).
+- **Avoid overengineering.** Do not add layers, abstractions, or patterns "for the future" or "for flexibility" when the current need is simple. Prefer the smallest change that solves the problem: reuse first, then extend, then create new only when there is a clear gap. Avoid speculative generality (e.g. "we might need multiple backends later"), deep indirection, or extra abstraction that does not pay off for the current scope.
+
+**Examples:**
+
+- ✅ **Good:** Need to validate a reference: use existing `parse_reference` or `validate_reference` if the codebase already has them; do not add a new `validate_passage_reference` that duplicates behavior.
+- ❌ **Bad:** Creating a new helper or wrapper that wraps a single existing function with no added behavior; call the existing function directly.
+- ✅ **Good:** Need to fetch events for a passage: use existing `EventService.get_by_passage` or the existing API client method; do not add a new service method or API function that does the same thing.
+- ❌ **Bad:** Adding a "repository" layer when the project only has services and the new layer would just forward to the same service; reuse the current structure.
+- ✅ **Good:** Simple feature: implement with existing patterns (e.g. one route, one service call, existing Pydantic model); no new base classes or frameworks.
+- ❌ **Bad:** Introducing a generic "handler" abstraction, a new dependency-injection framework, or a "plugin system" for a single use case; avoid overengineering.
+- ✅ **Good:** New behavior that does not fit any existing function: add a focused function or component; keep it minimal and aligned with current style.
+- ❌ **Bad:** "We might need to support X later" so adding interfaces, factories, or config now; create new abstractions only when the need is present.
+
+---
+
+## 3. Build and Runtime Commands (Docker Only)
+
+- **Never run build, dev server, tests, migrations, or other application commands on the user's machine (host).** All such commands must run **inside the Docker container** that runs the application: use the **backend** container for backend commands (Python, Prisma, uvicorn, etc.) and the **frontend** container for frontend commands (npm, vite, etc.).
+- Prefer **`docker compose exec <service> <command>`** when the service is already running, or **`docker compose run --rm <service> <command>`** for one-off commands (e.g. migrations, tests). Ensure the user has started the stack with `docker compose up` (or equivalent) before using `exec`.
+- Do not suggest or run `npm run build`, `npm run dev`, `uvicorn`, `python -m pytest`, `prisma migrate`, etc. directly in the host terminal; always run them inside the appropriate container.
+
+**Examples:**
+
+- ✅ **Good:** Backend command → `docker compose exec backend uv run pytest tests/` or `docker compose exec backend prisma migrate deploy`.
+- ✅ **Good:** Frontend command → `docker compose exec frontend npm run build` or `docker compose exec frontend npm run dev`.
+- ✅ **Good:** One-off in backend → `docker compose run --rm backend uv run python scripts/seed_admin.py`.
+- ✅ **Good:** Add backend dependency → `docker compose exec backend uv add <package>`.
+- ❌ **Bad:** Running `npm run build` or `npm run dev` in the host shell (user's machine); run inside the **frontend** container.
+- ❌ **Bad:** Running `uvicorn app.main:app` or `python -m pytest` on the host; run inside the **backend** container.
+- ❌ **Bad:** Running `prisma generate` or `prisma migrate` on the host; run inside the **backend** container.
+- ❌ **Bad:** Using `pip install` on the backend; use `uv add` instead.
+- ✅ **Good:** Telling the user: "To run the backend tests, use: `docker compose exec backend uv run pytest tests/`" (or the project's actual test command).
+- ❌ **Bad:** Telling the user: "Run `npm run build` in the frontend directory"; instead: "Run `docker compose exec frontend npm run build`."
+
+---
+
+## 4. Secrets and Environment Variables
+
+### Never hardcode secrets
+
+- **Never hardcode secrets, API keys, or credentials** in source code, docker-compose.yml, or any committed file. All secrets must come from environment variables.
+- Use **`.env` files for local development**. These files are gitignored and never committed. docker-compose.yml should use `env_file:` to load them.
+- Use **GitHub Secrets for CI/CD**. Production secrets are stored in GitHub repository secrets and injected during deployment via GitHub Actions.
+- Provide **`.env.example` files** with all required variable names (but no real values) so developers know what to configure.
+- **Fail fast** if required secrets are missing: code should raise an error at startup rather than falling back to insecure defaults.
+
+**Examples:**
+
+- ✅ **Good:** `SECRET_KEY = os.getenv("JWT_SECRET_KEY")` followed by a check that raises if missing.
+- ❌ **Bad:** `SECRET_KEY = os.getenv("JWT_SECRET_KEY", "default-secret")` — insecure fallback that would be used in production if env var is missing.
+- ✅ **Good:** `docker-compose.yml` uses `env_file: ./backend/.env` to load environment variables.
+- ❌ **Bad:** `docker-compose.yml` with `DATABASE_URL: "postgresql://user:pass@host/db"` hardcoded.
+- ✅ **Good:** GitHub Actions workflow uses `${{ secrets.JWT_SECRET }}` and passes it as env var to the deployed service.
+- ❌ **Bad:** Secrets stored in committed config files, even if "for local development only".
+- ✅ **Good:** `.env.example` documents all required variables: `JWT_SECRET_KEY=`, `DATABASE_URL=`, etc.
+- ❌ **Bad:** New developer has to guess which env vars are needed; document them in `.env.example`.
+
+---
+
+## 5. Version Control and Commits
+
+### Do not commit unless asked
+
+- **Never commit, push, or amend** unless the user **explicitly requests** a commit (e.g. "commit this", "commit and push", "create a commit for these changes").
+- Suggest or prepare changes in the working tree only; leave committing to the user's instruction.
+
+**Examples:**
+
+- ✅ **Good:** User says "commit these changes" or "create a commit for the auth fix" → you run `git status`, group changes, and create one or more commits as below.
+- ❌ **Bad:** After implementing a feature, automatically running `git add` and `git commit` without the user asking; only suggest or show the diff.
+- ✅ **Good:** User says "just make the edits" or "fix the bug" → you only edit files; you do not run `git commit` or `git push`.
+- ❌ **Bad:** Interpreting "done" or "thanks" as a request to commit; wait for an explicit request to commit.
+
+### When the user requests a commit
+
+1. **Analyze the working tree**
+   - Run `git status` (and if needed `git diff`) to see all modified, added, and deleted files.
+   - Group changes by **scope** (e.g. "auth", "BHSA API", "frontend login", "config", "docs").
+
+2. **Create small, focused commits**
+   - Prefer **several small commits**, each covering one logical change or scope, over a single large commit.
+   - Each commit should be **independently understandable** and, if possible, buildable/testable.
+   - Avoid "one commit per file" when multiple files form one logical change; combine them. Conversely, avoid one commit that mixes unrelated features or fixes.
+
+3. **Use semantic commit messages**
+   - Follow the **Conventional Commits** style: `type(scope): short description`.
+   - **Types** (examples): `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `style`.
+   - **Scope** (optional): area of the codebase (e.g. `auth`, `bhsa`, `frontend`, `api`).
+   - **Description**: imperative, concise summary (e.g. "add login validation", "fix pericope export").
+
+**Examples (when to commit vs not):**
+
+- ✅ **Good:** User says "commit this" → run `git status` first; then create commits grouped by scope (see below).
+- ❌ **Bad:** User says "commit this" → one giant commit with message "updates"; instead, split by scope and use semantic messages.
+
+**Examples (grouping and splitting commits):**
+
+- ✅ **Good:** `git status` shows: `backend/app/api/auth.py`, `backend/app/core/auth_middleware.py`, `frontend/src/contexts/AuthContext.tsx`, `frontend/src/components/pages/LoginPage.tsx`, `AGENTS.md`. Split into e.g.: (1) `feat(auth): add JWT refresh endpoint` for backend auth files, (2) `feat(frontend): add login refresh in AuthContext` for frontend auth, (3) `docs: add examples to AGENTS.md` for AGENTS.md.
+- ❌ **Bad:** One commit "Update auth and frontend and docs" containing all of the above; or three commits that are "auth.py", "auth_middleware.py", "AuthContext.tsx" with no logical grouping (e.g. backend auth together, frontend auth together).
+- ✅ **Good:** One logical feature touches API + service + schema → one commit: `feat(events): add patch endpoint for partial event update` with all related files.
+- ❌ **Bad:** Same feature split into "commit 1: api", "commit 2: service", "commit 3: schema" when they are not useful in isolation; prefer one commit per *logical* change.
+
+**Examples (semantic commit messages):**
+
+- ✅ **Good:** `feat(auth): add JWT refresh endpoint` | `fix(bhsa): handle missing clause ids in event export` | `refactor(api): extract passage validation into shared function` | `docs: update DATA_STORAGE_EXPLAINED for GCS setup` | `chore(deps): bump frontend deps for security`.
+- ❌ **Bad:** `Fixed stuff` | `Updates` | `WIP` | `asdf`; use `type(scope): imperative description` instead.
+- ✅ **Good:** Description is imperative and concise: "add …", "fix …", "extract …", "update …".
+- ❌ **Bad:** "Added …" (past tense) or long sentences; keep the description short and imperative.
+
+---
+
+## 6. Summary Checklist for Agents
+
+**Quick decision reference:**
+
+- **Paradigm:** Prefer functions, composition, and pure helpers. Avoid classes unless justified (e.g. schema, existing service pattern).
+- **Comments:** Prefer no comments for "what"; only for non-obvious "why". Avoid comments that restate the code.
+- **Architecture:** Prefer thin API → service → domain with dependencies inward. Avoid business logic in the API layer or HTTP/DB in domain.
+- **Patterns:** Prefer small functions, composition, and domain names. Avoid god classes, deep inheritance, and generic names.
+- **Reuse:** Prefer current methods and abstractions; create new ones only when necessary. Avoid overengineering: no extra layers or speculative generality for the current scope.
+- **Build / run:** Prefer running commands inside Docker (`docker compose exec backend …` or `docker compose exec frontend …`). Avoid running npm, uvicorn, pytest, prisma, etc. on the host.
+- **Secrets:** Prefer loading secrets from `.env` files (local) or GitHub Secrets (CI/CD). Avoid hardcoded credentials in docker-compose.yml or source code; fail fast if required secrets are missing.
+- **Commits:** Prefer committing only when the user explicitly asks. Avoid auto-commit after edits.
+- **Commit shape:** Prefer running `git status`, grouping by scope, and creating small logical commits. Avoid one giant commit or one commit per file.
+- **Message format:** Prefer `type(scope): imperative description` (e.g. `feat(auth): add refresh`). Avoid "Fixed stuff", "Updates", "WIP".
+
+- [ ] Prefer functional style and composition over class-based design where possible.
+- [ ] Write self-documenting code; avoid comments except for non-obvious "why".
+- [ ] Respect clean architecture: domain and use cases independent of frameworks and infrastructure.
+- [ ] Use design patterns only when they simplify or clarify the design.
+- [ ] Prefer existing methods and abstractions; create new ones only when necessary; avoid overengineering.
+- [ ] Do not run build/dev/tests/migrations on the host; run them inside the backend or frontend Docker container.
+- [ ] Never hardcode secrets; use `.env` files locally and GitHub Secrets for CI/CD; fail fast if missing.
+- [ ] Do not commit unless the user explicitly asks.
+- [ ] When committing: run `git status`, group by scope, create small logical commits, use semantic commit messages (`type(scope): description`).
+
+---
+
+## 7. Context-Specific Guidelines
+
+When working in a specific part of the repo, follow the corresponding file in addition to this document:
+
+- **Backend** (`backend/`): See [BACKEND.md](https://github.com/shemaobt/reference-agents-md/blob/main/BACKEND.md) for stack (FastAPI, Prisma, Pydantic), structure (api / services / core / models), and backend conventions.
+- **Frontend** (`frontend/`): See [FRONTEND.md](https://github.com/shemaobt/reference-agents-md/blob/main/FRONTEND.md) for stack (React, TypeScript, Tailwind, Zustand, Vite), component structure, styling (Tailwind only, no inline styles), and state management.
+- **Design System** (`frontend/design-system/`): The authoritative source for all visual design decisions, color palettes, typography (Montserrat/Merriweather), spacing, components, and UI patterns. See `frontend/design-system/DESIGN.md` for the complete design system documentation.
+
+---
+
+*This file is the reference copy from [mm_poc_v2](https://github.com/shemaobt/mm_poc_v2). Use it as a template; place in your repo root as `AGENTS.md` or `GENERAL-WEB-APP.md`. Built using [agents.md](https://agents.md/) as reference.*
diff --git a/BACKEND.md b/backend/AGENTS.md
similarity index 100%
rename from BACKEND.md
rename to backend/AGENTS.md
diff --git a/FRONTEND.md b/frontend/AGENTS.md
similarity index 87%
rename from FRONTEND.md
rename to frontend/AGENTS.md
index 23c5f47..2ec8092 100644
--- a/FRONTEND.md
+++ b/frontend/AGENTS.md
@@ -1,5 +1,19 @@
 # Frontend Agent Guidelines (mm_poc_v2)
 
+## Design System Authority
+
+All UI, styling, layout, spacing, colors, typography, and visual decisions
+MUST strictly follow the Design System defined in:
+
+- **[./design-system/AGENTS.md](./design-system/AGENTS.md)** - Brand authority and core principles
+- **[./design-system/DESIGN.md](./design-system/DESIGN.md)** - Design system overview and complete index
+- **[./design-system/tokens/](./design-system/tokens/)** - Authoritative design tokens (colors, typography, spacing, etc.)
+- **[./design-system/*.md](./design-system/)** - Complete implementation guides
+
+This AGENT must not override, reinterpret, or invent visual rules.
+If a visual decision is missing, consult the design system documentation or request clarification.
+Failure to follow the Design System must be treated as a defect, not a stylistic preference.
+
 This file defines **frontend-specific** conventions for LLM agents working in `frontend/`. It extends the repository-wide [GENERAL-WEB-APP.md](https://github.com/shemaobt/reference-agents-md/blob/main/GENERAL-WEB-APP.md): follow those global guidelines first, then apply what is below.
 
 ---
@@ -85,8 +99,12 @@ frontend/src/
 ## 3. Styling and Tailwind
 
 - **Use Tailwind only** for layout, spacing, colors, typography, and responsive behavior.
-- **Avoid inline styles** for things Tailwind can do (e.g. `className="flex items-center gap-2"` instead of `style={{ display: 'flex', alignItems: 'center' }}`). Use inline `style` only when necessary (e.g. dynamic values, third-party integration).
-- **Use the design tokens** from `tailwind.config.js`: `branco`, `areia`, `azul`, `telha`, `verde`, `verde-claro`, `preto`, and semantic tokens (`primary`, `background`, `border`, `ring`, etc.). Do not introduce arbitrary hex values in JSX; extend the theme if new tokens are needed.
+- **Avoid inline styles** for things Tailwind can handle (e.g. `className="flex items-center gap-2"` instead of `style={{ display: 'flex', alignItems: 'center' }}`).  
+  Use inline `style` **only when strictly necessary** (e.g. dynamic values or third-party integrations).
+- **Always use the design tokens** defined in `tailwind.config.js` for colors and semantics  
+  (`branco`, `areia`, `azul`, `telha`, `verde`, `verde-claro`, `preto`, and semantic tokens like `primary`, `background`, `border`, `ring`).
+- `tailwind.config.js` **must stay in sync** with `design-system/tokens/*.json`.  
+  Do **not** introduce arbitrary hex values in JSX; extend the theme if new tokens are required.
 
 ### Centralized style constants
 
diff --git a/frontend/design-system/AGENTS.md b/frontend/design-system/AGENTS.md
new file mode 100644
index 0000000..ad35b3d
--- /dev/null
+++ b/frontend/design-system/AGENTS.md
@@ -0,0 +1,246 @@
+# Shema Design System — AI Agents Guide
+
+## 1. Purpose
+This Design System defines the visual and behavioral rules for creating interfaces for the **Shema** platform, covering **Web** and **Mobile App (Flutter)**.
+
+The Shema brand operates in the context of biblical translation and sacred text reading. Its visual identity must reflect the following values:
+
+- Simple  
+- Accessible  
+- Lively  
+- Friendly  
+- Human  
+
+This document acts as a **mandatory contract** for designers, developers, and AI agents.
+
+---
+
+## 2. Visual Principles
+
+### Natural Feel
+- Avoid pure white (#FFFFFF) as the main background.
+- Use **Shema White / Cream (#F6F5EB)** to simulate paper and provide visual comfort.
+- Pure white is reserved only for elevated surfaces (cards, inputs).
+
+### Soft Contrast
+- Text uses **Shema Black (#0A0703)**, never absolute black.
+- Subtitles and secondary text use **Shema Dark Green (#3F3E20)**.
+
+### Typography
+- **Montserrat**: entire interface (UI, buttons, navigation).
+- **Merriweather**: long-form texts, biblical content, and continuous reading.
+- Fonts observed in screenshots should be ignored if they conflict with this guide.
+
+### Color Hierarchy
+- **Tile / Clay (#BE4A01)** is exclusive to:
+  - CTAs
+  - Primary actions
+  - Active icons
+- Never use Tile as a neutral decorative color.
+
+---
+
+## 3. UI Generation Rules
+
+### What TO DO
+
+#### Mobile (Flutter)
+- Use **Elevation** to separate surfaces.
+- Buttons and cards with generously rounded corners (16px+).
+- Large touch areas.
+- Components compatible with `ColorScheme` and `TextTheme`.
+
+#### Web
+- Wider, more breathable layouts.
+- Cards with corner radius between 8px and 12px.
+- Hover and focus states using opacity, never new colors.
+
+#### Colors
+- Use only the defined design tokens.
+- Variations only through **opacity** or **state**.
+
+---
+
+## Color Modes Governance
+
+The Shema Design System officially supports two visual modes.
+
+---
+
+### ☀️ Light Mode — “Paper & Ink”
+
+**Metaphor:** Printed paper.
+
+- Background: Cream Shema (#F6F5EB)
+- Surface: Pure White (#FFFFFF)
+- Primary Text: Black Shema (#0A0703)
+- Secondary Text: Dark Green (#3F3E20)
+- Borders: Sand (#C5C29F)
+
+Pure white must never be used as a page background.
+
+---
+
+### 🌙 Dark Mode — “Night & Earth”
+
+**Metaphor:** Organic night environment.
+
+- Background: Black Shema (#0A0703)
+- Surface: Black Shema with visible borders
+- Highlight Surface: Dark Green (#3F3E20)
+- Primary Text: Cream Shema (#F6F5EB)
+- Secondary Text: Sand (#C5C29F)
+
+---
+
+### Strict Restrictions
+
+- Do NOT use generic neutral greys.
+- Do NOT approximate Material Design dark palettes.
+- Dark interfaces must be composed only using Shema palette colors.
+
+Failure to follow these rules must be treated as a design defect, not a stylistic preference.
+
+### What NOT TO DO
+- Do not create complex gradients.
+- Do not invent new semantic colors outside the earthy palette.
+- Do not use Merriweather for buttons, menus, or navigation.
+- Do not mix Web and App patterns without explicit documentation.
+
+---
+
+## Visual Rationale
+
+When generating or evaluating user interfaces:
+- Always compare decisions with visual references in `assets/references/`.
+- If there is a conflict between written rules and visual references, follow the written design tokens.
+- Visual references define *intent*, not pixel-perfect layouts.
+
+---
+
+### Spacing and Layout
+- **Generous breathing room**: Use the 4px base spacing scale (Tailwind).
+- **Card padding**: 16px minimum (mobile), 24px recommended (desktop).
+- **Section gaps**: Space-y-6 or space-y-8 for vertical rhythm.
+- **Grid systems**: Responsive grids that adapt from single column (mobile) to multi-column (desktop).
+
+### Component Guidelines
+
+#### Buttons
+- **Primary (Tile)**: Reserved for main CTAs only.
+- **Rounded corners**: 8px+ for buttons (Web), 16px+ for mobile.
+- **Touch targets**: Minimum 44px height for mobile buttons.
+- **States**: Use opacity for hover/focus, never introduce new colors.
+
+#### Cards
+- **Background**: White (#FFFFFF) for elevated surfaces.
+- **Borders**: Subtle with `border-areia/30`.
+- **Corner radius**: 8-12px (Web), 16px+ (Mobile).
+- **Shadows**: Soft shadows for elevation (`shadow-sm`, `shadow-md`).
+- **Hover states**: Increase shadow and adjust border opacity.
+
+#### Forms
+- **Inputs**: White background with `border-areia`.
+- **Focus states**: Ring with telha color (`ring-telha`).
+- **Labels**: Montserrat medium, text-sm.
+- **Validation**: Use verde-claro for success, red for errors.
+
+#### Badges
+- **Rounded**: Full rounded (`rounded-full`) for pill-shaped badges.
+- **Category colors**: Predefined color combinations for participants, events, discourse.
+- **Size**: text-xs with medium weight for clarity.
+
+---
+
+## 4. Animation Principles
+
+### Transitions
+- **Duration**: 200ms default for most interactions.
+- **Easing**: Use `ease-out` for entrances, `ease-in-out` for state changes.
+- **Properties**: Prefer `transform` and `opacity` (GPU-accelerated).
+
+### Keyframes
+- **fade-in**: Subtle entrance with vertical movement.
+- **slide-in**: Horizontal entrance for modals/sheets.
+- **pulse-soft**: Gentle attention grabber.
+- **celebrate**: Success feedback animation.
+
+### Best Practices
+- Avoid animating layout properties (width, height, top, left).
+- Respect `prefers-reduced-motion` user preference.
+- Keep animations subtle and non-distracting.
+
+For complete animation specifications, see [animations.md](./animations.md).
+
+---
+
+## 5. Detailed Color Usage
+
+### Primary Colors
+- **Telha (#BE4A01)**: Exclusive to CTAs, primary actions, active states.
+  - **Variations**: `telha-light`, `telha-dark`, `telha-muted` for different contexts.
+  - **Never** use telha as neutral decoration or background.
+
+- **Shema White / Cream (#F6F5EB)**: Main background color.
+  - Provides paper-like warmth and reduces eye strain.
+  - Pure white (#FFFFFF) is reserved for elevated surfaces (cards, inputs).
+
+- **Shema Black (#0A0703)**: Primary text color.
+  - Softer than absolute black, better for long reading sessions.
+
+- **Shema Dark Green (#3F3E20)**: Secondary text, subtitles, descriptions.
+
+### Supporting Colors
+- **Blue (#89AAA3)**: Supporting elements, subtle backgrounds.
+- **Light Green (#777D45)**: Success states, positive indicators, validation.
+- **Sand (#C5C29F)**: Borders, muted elements, warnings.
+
+### Opacity Patterns
+- `/10`: Very subtle backgrounds
+- `/20`: Soft backgrounds for badges/highlights
+- `/30`: Borders and subtle separators
+- `/50`: Medium overlays
+- `/90`: Strong hover states
+
+For complete color specifications, see [colors.md](./colors.md).
+
+---
+
+## 6. Governance
+
+The single source of truth consists of:
+
+### Design Tokens (Authoritative)
+- [colors.json](./tokens/colors.json) - Color palette and semantic tokens
+- [typography.json](./tokens/typography.json) - Font families, scales, weights
+- [spacing.json](./tokens/spacing.json) - Spacing scale and layout tokens
+- [animations.json](./tokens/animations.json) - Animation keyframes and timings
+- [borders.json](./tokens/borders.json) - Border widths and radius values
+- [shadows.json](./tokens/shadows.json) - Shadow scales for elevation
+
+### Visual References
+- Visual examples in [assets/references/](./assets/references/)
+- Figma links in [figma-links.md](./figma-links.md)
+
+### Implementation Documentation
+- [DESIGN.md](./DESIGN.md) - Design system overview and quick start
+- [colors.md](./colors.md) - Complete color system with usage examples
+- [typography.md](./typography.md) - Typography hierarchy and usage
+- [spacing.md](./spacing.md) - Spacing scale and layout patterns
+- [animations.md](./animations.md) - Animation and transition patterns
+- [components.md](./components.md) - UI component specifications
+- [cards.md](./cards.md) - Card variants and patterns
+- [badges.md](./badges.md) - Badge system and categories
+- [states.md](./states.md) - Loading, error, success states
+- [layout.md](./layout.md) - Grid systems and containers
+- [border-radius.md](./border-radius.md) - Corner radius system
+- [sections.md](./sections.md) - Section patterns
+- [themes.md](./themes.md) - Light/dark theme specifications
+
+### Conflict Resolution
+1. **Token files** override visual references
+2. **This AGENTS.md** defines brand authority and principles
+3. **Implementation docs** provide detailed usage patterns
+4. When in doubt, consult token files first, then this document
+
+Any exception must be documented.
diff --git a/frontend/design-system/DESIGN.md b/frontend/design-system/DESIGN.md
new file mode 100644
index 0000000..26f9c18
--- /dev/null
+++ b/frontend/design-system/DESIGN.md
@@ -0,0 +1,303 @@
+# Shema Design System
+
+## 📖 Overview
+
+The She design system for the **Shema** platform provides a comprehensive visual language and component library for creating consistent, accessible, and beautiful interfaces across Web and Mobile applications.
+
+### Brand Values
+
+Shema operates in the context of biblical translation and sacred text reading. The design system reflects these core values:
+
+- **Simple** - Clean interfaces that don't overwhelm
+- **Accessible** - Usable by all, with proper contrast and semantic HTML
+- **Lively** - Warm, engaging colors that invite interaction
+- **Friendly** - Approachable components and gentle animations
+- **Human** - Natural feel with paper-like backgrounds and soft contrasts
+
+---
+
+## 🎨 Quick Start
+
+### Color Palette (Earthy Tones)
+
+| Color | Hex | Usage |
+|-------|-----|-------|
+| **Telha** (Clay/Tile) | `#BE4A01` | CTAs, primary actions, active states |
+| **Shema White** (Cream) | `#F6F5EB` | Main background |
+| **Shema Black** | `#0A0703` | Primary text |
+| **Shema Dark Green** | `#3F3E20` | Secondary text |
+| **Blue** | `#89AAA3` | Supporting elements |
+| **Light Green** | `#777D45` | Success, validation |
+| **Sand** | `#C5C29F` | Borders, muted elements |
+
+### Typography
+
+- **Montserrat**: Entire UI (buttons, navigation, labels, headings)
+- **Merriweather**: Long-form text, biblical content, continuous reading
+
+### Spacing Scale
+
+Based on **4px base unit** (Tailwind default):
+- `space-2` (8px) - Tight spacing
+- `space-4` (16px) - Default spacing
+- `space-6` (24px) - Section spacing
+- `space-8` (32px) - Large gaps
+
+### Component Basics
+
+```tsx
+import { Button, Card, Badge } from '@/components/ui'
+import { cardStyles } from '@/styles'
+
+// Primary button
+<Button variant="default">Save Changes</Button>
+
+// Card with content
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+</Card>
+
+// Category badge
+<Badge className={participantCategoryColors['person']}>
+  Person
+</Badge>
+```
+
+---
+
+## 📚 Complete Documentation
+
+### Design Tokens (Authoritative Source)
+
+Tokens are the single source of truth. All implementation must align with these files:
+
+- **[colors.json](./tokens/colors.json)** - Color palette, semantic tokens, category colors
+- **[typography.json](./tokens/typography.json)** - Font families, scales, weights, line heights
+- **[spacing.json](./tokens/spacing.json)** - Spacing scale, semantic spacing values
+- **[animations.json](./tokens/animations.json)** - Keyframes, durations, easing functions
+- **[borders.json](./tokens/borders.json)** - Border widths, corner radius values
+- **[shadows.json](./tokens/shadows.json)** - Shadow scales for elevation
+
+### Implementation Guides
+
+Detailed usage patterns and code examples for each design system element:
+
+1. **[colors.md](./colors.md)** - Complete color system
+   - Base palette and semantic tokens
+   - Category colors (participants, events, discourse)
+   - Validation and state colors
+   - Opacity patterns and usage examples
+
+2. **[typography.md](typography.md)** - Typography hierarchy
+   - Font families (Montserrat, Merriweather)
+   - Type scale (headings, body, captions)
+   - Font weights, line heights, letter spacing
+   - Hebrew text specifications
+
+3. **[spacing.md](./spacing.md)** - Spacing and layout
+   - Spacing scale (4px base)
+   - Layout patterns (grids, containers)
+   - Padding and margin conventions
+   - Label → Input/Select spacing (mb-2 default)
+   - Dropdown spacing and icon positioning
+
+4. **[animations.md](./animations.md)** - Motion design
+   - Keyframes (fade-in, slide-in, pulse, celebrate)
+   - Transition patterns and durations
+   - Performance best practices
+
+5. **[components.md](./components.md)** - UI components
+   - Progress Step (preferred option for progress indicators)
+   - Button, Card, Input, Select, Dialog
+   - Component variants and sizes
+   - Usage patterns and examples
+
+6. **[cards.md](./cards.md)** - Card system
+   - Card variants (base, hover, selected, dashed)
+   - Specialized cards (clause, event, participant)
+   - States and interactions
+
+7. **[badges.md](./badges.md)** - Badge system
+   - Badge variants and sizes
+   - Category colors and semantic badges
+   - Validation and status badges
+
+8. **[states.md](./states.md)** - UI states
+   - Loading states and spinners
+   - Error, success, warning banners
+   - Empty states and placeholders
+
+9. **[layout.md](./layout.md)** - Layout patterns
+   - Grid systems (responsive)
+   - Page templates and containers
+   - Modal and dialog layouts
+
+10. **[border-radius.md](./border-radius.md)** - Corner radius
+    - Radius scale (sm, md, lg)
+    - Component-specific radius values
+    - Platform differences (Web vs Mobile)
+
+11. **[sections.md](./sections.md)** - Section patterns
+    - Collapsible sections
+    - Section variants (roles, emotions, etc.)
+    - Header patterns
+
+12. **[themes.md](./themes.md)** - Theme system
+    - Light theme (current)
+    - Dark theme (future)
+    - Theme switching implementation
+
+---
+
+## 🎯 Design Principles
+
+### 1. Natural Feel
+
+Avoid stark, clinical interfaces. Use **Shema White / Cream (#F6F5EB)** as the main background to simulate paper texture and provide visual comfort. Reserve pure white (#FFFFFF) for elevated surfaces like cards and inputs.
+
+### 2. Soft Contrast
+
+Text uses **Shema Black (#0A0703)** instead of absolute black. Secondary text uses **Shema Dark Green (#3F3E20)**. This creates legible but gentle contrast suitable for long reading sessions.
+
+### 3. Intentional Color
+
+**Telha / Clay (#BE4A01)** is exclusive to primary actions, CTAs, and active states. Never use Telha as neutral decoration. This preserves its visual weight and guides users to key actions.
+
+### 4 Responsive Typography
+
+Use **Montserrat** for all UI elements (navigation, buttons, labels). Use **Merriweather** exclusively for long-form biblical text and continuous reading contexts.
+
+### 5. Elevation Through Shadow
+
+Create depth with subtle shadows (`shadow-sm`, `shadow-md`), not heavy outlines or thick borders. Hover states should increase shadow intensity.
+
+### 6. Gentle Motion
+
+Animations are subtle and non-distracting. Default duration is 200ms. Prefer `transform` and `opacity` for smooth, GPU-accelerated transitions.
+
+---
+
+## 🛠️ Using the Design System
+
+### In React Components
+
+```tsx
+import { Button, Card, Badge, Input } from '@/components/ui'
+import { cardStyles, participantCategoryColors } from '@/styles'
+import { cn } from '@/utils/cn'
+
+export function ExampleComponent() {
+  return (
+    <Card className={cn(cardStyles.base, cardStyles.hover)}>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Icon className="w-5 h-5 text-telha" />
+          Passage Details
+        </CardTitle>
+        <CardDescription>Genesis 1:1-3</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="space-y-4">
+          <Input placeholder="Add notes..." />
+          <Badge className={participantCategoryColors['divine']}>
+            Divine
+          </Badge>
+        </div>
+      </CardContent>
+      <CardFooter>
+        <Button variant="default">Save</Button>
+        <Button variant="outline">Cancel</Button>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+### With Tailwind Classes
+
+```tsx
+// Background and text colors
+<div className="bg-branco text-preto">
+  <h1 className="text-2xl font-bold text-preto">Heading</h1>
+  <p className="text-sm text-verde">Description</p>
+</div>
+
+// Spacing and layout
+<div className="p-6 space-y-4">
+  <div className="flex items-center gap-2">
+    ...
+  </div>
+</div>
+
+// Transitions and hover
+<button className="bg-telha hover:bg-telha-dark transition-all duration-200 shadow-sm hover:shadow-md">
+  Click me
+</button>
+```
+
+---
+
+## 📱 Platform Differences
+
+### Web
+- Border radius: 8-12px for cards, 8px for buttons
+- Hover states: Use opacity and shadow changes
+- Layouts: Wider, more breathable spacing
+
+### Mobile (Flutter)
+- Border radius: 16px+ for generous rounded corners
+- Touch targets: Minimum 44px height
+- Elevation: Use Material elevation for depth
+- Large touch areas for accessibility
+
+---
+
+## 🔄 Governance and Authority
+
+### Hierarchy of Truth
+
+1. **Token files** (`/tokens/*.json`) are authoritative. If there's a conflict between code and tokens, tokens win.
+2. **[AGENTS.md](./AGENTS.md)** defines brand values and core principles.
+3. **Implementation docs** (this file and others) provide detailed usage patterns.
+
+### When to Update
+
+- **Tokens**: Only update with design team approval.
+- **Implementation docs**: Update when patterns evolve or new use cases emerge.
+- **Visual references**: Update when major visual changes occur.
+
+### Requesting Changes
+
+Document any exceptions or deviations. Propose token changes through design review process. Never introduce arbitrary colors or typography outside the defined system.
+
+---
+
+## 📖 Additional Resources
+
+- **[AGENTS.md](./AGENTS.md)** - AI agent guidelines and brand authority
+- **[README.md](./README.md)** - Visual references and conflict resolution
+- **[figma-links.md](./figma-links.md)** - Links to Figma design files
+- **[assets/references/](./assets/references/)** - Visual examples and screenshots
+
+---
+
+## ✅ Checklist for Contributors
+
+Before creating or modifying UI:
+
+- [ ] Use colors from `colors.json` only
+- [ ] Use Montserrat for UI, Merriweather for reading content
+- [ ] Follow spacing scale (4px base)
+- [ ] Use existing components from `/components/ui`
+- [ ] Apply centralized styles from `/styles`
+- [ ] Test hover and focus states
+- [ ] Verify accessibility (contrast, keyboard navigation)
+- [ ] Respect `prefers-reduced-motion` for animations
+- [ ] Check responsive behavior (mobile, tablet, desktop)
+
+---
+
+*This design system is maintained by the Shema design team. For questions or contributions, consult the governance section above.*
diff --git a/frontend/design-system/README.md b/frontend/design-system/README.md
new file mode 100644
index 0000000..c0e305c
--- /dev/null
+++ b/frontend/design-system/README.md
@@ -0,0 +1,67 @@
+# Shema Design System
+
+This folder contains the complete visual ground truth for the Shema Design System.
+
+## Quick Navigation
+
+### 🎨 Start Here
+- **[DESIGN.md](./DESIGN.md)** - Design system overview, quick start, and complete index
+- **[AGENTS.md](./AGENTS.md)** - Brand authority, AI agent guidelines, and core principles
+
+### 🔧 Design Tokens (Authoritative)
+- [colors.json](./tokens/colors.json) - Color palette and semantic tokens
+- [typography.json](./tokens/typography.json) - Font families (Montserrat/Merriweather), scales, weights
+- [spacing.json](./tokens/spacing.json) - Spacing scale and layout tokens
+- [animations.json](./tokens/animations.json) - Keyframes and animation timings
+- [borders.json](./tokens/borders.json) - Border widths and radius values
+- [shadows.json](./tokens/shadows.json) - Shadow scales for elevation
+
+### 📚 Implementation Guides
+- [colors.md](./colors.md) - Complete color system with usage examples
+- [typography.md](./typography.md) - Typography hierarchy and font usage
+- [spacing.md](./spacing.md) - Spacing scale and layout patterns
+- [animations.md](./animations.md) - Motion design and transitions
+- [components.md](./components.md) - UI component specifications
+- [cards.md](./cards.md) - Card variants and patterns
+- [badges.md](./badges.md) - Badge system and categories
+- [states.md](./states.md) - Loading, error, success states
+- [layout.md](./layout.md) - Grid systems and containers
+- [border-radius.md](./border-radius.md) - Corner radius system
+-[sections.md](./sections.md) - Section patterns
+- [themes.md](./themes.md) - Light/dark theme specifications
+
+### 🎯 Visual References
+- [assets/references/](./assets/references/) - Visual examples and screenshots
+- [figma-links.md](./figma-links.md) - Links to Figma design files
+
+## Rules
+
+### Conflict Resolution
+1. **Token files** override visual references
+2. **AGENTS.md** defines brand authority and principles  
+3. **Implementation docs** provide detailed usage patterns
+4. Images define visual intent, not pixel-perfect specs
+5. Web and App references must not be mixed without justification
+
+### Making Changes
+- Token files require design team approval
+- Document all exceptions
+- Never introduce arbitrary colors or typography
+- Follow the governance guidelines in [AGENTS.md](./AGENTS.md)
+
+## Brand Essentials
+
+### Colors
+- **Telha (#BE4A01)**: Exclusive to CTAs and primary actions
+- **Shema White (#F6F5EB)**: Main background (not pure white)
+- **Pure White (#FFFFFF)**: Elevated surfaces only (cards, inputs)
+
+### Typography
+- **Montserrat**: All UI elements (buttons, navigation, labels)
+- **Merriweather**: Long-form text and biblical content
+
+### Key Principles
+- Natural feel (paper-like backgrounds)
+- Soft contrast (Shema Black, not absolute black)
+- Intentional color (Telha for actions only)
+- Gentle motion (200ms default, subtle)
diff --git a/frontend/design-system/animations.md b/frontend/design-system/animations.md
new file mode 100644
index 0000000..b66596b
--- /dev/null
+++ b/frontend/design-system/animations.md
@@ -0,0 +1,461 @@
+# Animations and Transitions — Shema Design System
+
+## Animation System
+
+The application uses smooth animations and consistent transitions to improve user experience.
+
+## Keyframes
+
+### Fade In
+
+Fade in animation with vertical movement.
+
+```css
+@keyframes fade-in {
+  0% {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+#### Tailwind Configuration
+
+```javascript
+keyframes: {
+  'fade-in': {
+    '0%': { opacity: '0', transform: 'translateY(10px)' },
+    '100%': { opacity: '1', transform: 'translateY(0)' },
+  },
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-fade-in">...</div>
+```
+
+### Slide In
+
+Slide in animation from the left.
+
+```css
+@keyframes slide-in {
+  0% {
+    opacity: 0;
+    transform: translateX(-10px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+```
+
+#### Tailwind Configuration
+
+```javascript
+keyframes: {
+  'slide-in': {
+    '0%': { opacity: '0', transform: 'translateX(-10px)' },
+    '100%': { opacity: '1', transform: 'translateX(0)' },
+  },
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-slide-in">...</div>
+```
+
+### Pulse Soft
+
+Soft pulse animation.
+
+```css
+@keyframes pulse-soft {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.7;
+  }
+}
+```
+
+#### Tailwind Configuration
+
+```javascript
+keyframes: {
+  'pulse-soft': {
+    '0%, 100%': { opacity: '1' },
+    '50%': { opacity: '0.7' },
+  },
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-pulse-soft">...</div>
+```
+
+### Bounce Subtle
+
+Subtle bounce animation.
+
+```css
+@keyframes bounce-subtle {
+  0%, 100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-3px);
+  }
+}
+```
+
+#### Tailwind Configuration
+
+```javascript
+keyframes: {
+  'bounce-subtle': {
+    '0%, 100%': { transform: 'translateY(0)' },
+    '50%': { transform: 'translateY(-3px)' },
+  },
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-bounce-subtle">...</div>
+```
+
+### Celebrate
+
+Celebration animation (scale).
+
+```css
+@keyframes celebrate {
+  0% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.1);
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+```
+
+#### Tailwind Configuration
+
+```javascript
+keyframes: {
+  'celebrate': {
+    '0%': { transform: 'scale(1)' },
+    '50%': { transform: 'scale(1.1)' },
+    '100%': { transform: 'scale(1)' },
+  },
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-celebrate">...</div>
+```
+
+## Configured Animations
+
+### Fade In
+
+```javascript
+animation: {
+  'fade-in': 'fade-in 0.3s ease-out',
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-fade-in">...</div>
+```
+
+### Slide In
+
+```javascript
+animation: {
+  'slide-in': 'slide-in 0.3s ease-out',
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-slide-in">...</div>
+```
+
+### Pulse Soft
+
+```javascript
+animation: {
+  'pulse-soft': 'pulse-soft 2s ease-in-out infinite',
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-pulse-soft">...</div>
+```
+
+### Bounce Subtle
+
+```javascript
+animation: {
+  'bounce-subtle': 'bounce-subtle 0.5s ease-in-out',
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-bounce-subtle">...</div>
+```
+
+### Celebrate
+
+```javascript
+animation: {
+  'celebrate': 'celebrate 0.4s ease-in-out',
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-celebrate">...</div>
+```
+
+## Transitions
+
+### Default Duration
+
+The application uses a default duration of **200ms** for most transitions.
+
+### Hover Transitions
+
+```tsx
+// Card with hover
+<div className="transition-all duration-200 hover:shadow-md hover:border-telha/30">
+  ...
+</div>
+
+// Button with hover
+<button className="transition-all duration-200 hover:bg-telha-dark">
+  ...
+</button>
+```
+
+### State Transitions
+
+```tsx
+// Element with color transition
+<div className="transition-colors duration-200 hover:bg-areia/20">
+  ...
+</div>
+
+// Element with scale transition
+<button className="transition-transform duration-200 active:scale-[0.98]">
+  ...
+</button>
+```
+
+### Opacity Transitions
+
+```tsx
+// Element with fade
+<div className="transition-opacity duration-200 hover:opacity-80">
+  ...
+</div>
+```
+
+## Loading Animations
+
+### Spinner
+
+```tsx
+<div className="animate-spin w-8 h-8 border-4 border-telha border-t-transparent rounded-full" />
+```
+
+### Small Spinner
+
+```tsx
+<div className="animate-spin w-4 h-4 border-2 border-telha border-t-transparent rounded-full" />
+```
+
+### Spinner with Text
+
+```tsx
+<div className="flex items-center gap-2">
+  <div className="animate-spin w-4 h-4 border-2 border-telha border-t-transparent rounded-full" />
+  <span>Loading...</span>
+</div>
+```
+
+## Entrance Animations
+
+### Fade In in List
+
+```tsx
+{items.map((item, index) => (
+  <div 
+    key={item.id}
+    className="animate-fade-in"
+    style={{ animationDelay: `${index * 0.1}s` }}
+  >
+    ...
+  </div>
+))}
+```
+
+### Slide In in Modal
+
+```tsx
+<Dialog>
+  <DialogContent className="animate-slide-in">
+    ...
+  </DialogContent>
+</Dialog>
+```
+
+## Interaction Animations
+
+### Button with Scale
+
+```tsx
+<Button className="active:scale-[0.98]">
+  Button
+</Button>
+```
+
+### Card with Hover
+
+```tsx
+<Card className="transition-all duration-200 hover:shadow-md hover:border-telha/30">
+  ...
+</Card>
+```
+
+### Badge with Pulse
+
+```tsx
+<Badge className="animate-pulse-soft">
+  New
+</Badge>
+```
+
+## Validation Animations
+
+### Celebration on Validation
+
+```tsx
+{isValidated && (
+  <div className="animate-celebrate">
+    <CheckCircle2 className="w-5 h-5 text-verde-claro" />
+  </div>
+)}
+```
+
+### Bounce on Completion
+
+```tsx
+{isCompleted && (
+  <div className="animate-bounce-subtle">
+    <CheckCircle2 className="w-5 h-5 text-verde-claro" />
+  </div>
+)}
+```
+
+## Custom CSS Classes
+
+### Animate In
+
+```css
+.animate-in {
+  animation: fade-in 0.3s ease-out;
+}
+```
+
+#### Usage
+
+```tsx
+<div className="animate-in">...</div>
+```
+
+### Slide In Left
+
+```css
+.slide-in-left {
+  animation: slide-in 0.3s ease-out;
+}
+```
+
+#### Usage
+
+```tsx
+<div className="slide-in-left">...</div>
+```
+
+## Performance
+
+### Optimizations
+
+- Use `transform` and `opacity` for animations (GPU-accelerated)
+- Avoid animating `width`, `height`, `top`, `left` (causes reflow)
+- Use `will-change` carefully (only when necessary)
+
+### Optimized Example
+
+```tsx
+// ✅ Good - uses transform
+<div className="transition-transform duration-200 hover:scale-105">
+  ...
+</div>
+
+// ❌ Avoid - animates width
+<div className="transition-all duration-200 hover:w-full">
+  ...
+</div>
+```
+
+## User Preferences
+
+### Reduce Motion
+
+Respect the user preference for reduced animations:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## References
+
+- Tailwind configuration: `frontend/tailwind.config.js`
+- CSS styles: `frontend/src/styles/main.css`
+
diff --git a/frontend/design-system/assets/references/app/components/buttons.md b/frontend/design-system/assets/references/app/components/buttons.md
new file mode 100644
index 0000000..c04a0f0
--- /dev/null
+++ b/frontend/design-system/assets/references/app/components/buttons.md
@@ -0,0 +1,19 @@
+# Mobile Buttons (Flutter)
+
+## Primary Action
+- Shape: Circular or Capsule
+- Color: Telha
+- Content: White
+- Elevation: 4–6
+
+## Input Fields
+- Background: White
+- Border Radius: 12px
+- Border:
+  - Inactive: Sand
+  - Focused: Telha
+
+## List Item Button
+- Clickable card
+- Left icon
+- Centered text
diff --git a/frontend/design-system/assets/references/app/components/cards.md b/frontend/design-system/assets/references/app/components/cards.md
new file mode 100644
index 0000000..3f21e62
--- /dev/null
+++ b/frontend/design-system/assets/references/app/components/cards.md
@@ -0,0 +1,12 @@
+# Mobile Cards
+
+## Project Card
+- Surface: Branco
+- Radius: 16–20px
+- Elevation: 2
+- Centered circular avatar
+
+## List Item Card
+- Horizontal layout
+- Radius: 12px
+- Border: Areia
diff --git a/frontend/design-system/assets/references/app/components/themes/README.md b/frontend/design-system/assets/references/app/components/themes/README.md
new file mode 100644
index 0000000..82f2730
--- /dev/null
+++ b/frontend/design-system/assets/references/app/components/themes/README.md
@@ -0,0 +1,3 @@
+These files are implementation examples for Flutter.
+They are not the source of truth.
+Tokens in /tokens override any discrepancy.
diff --git a/frontend/design-system/assets/references/app/components/themes/night-and-earth.dart b/frontend/design-system/assets/references/app/components/themes/night-and-earth.dart
new file mode 100644
index 0000000..4d21970
--- /dev/null
+++ b/frontend/design-system/assets/references/app/components/themes/night-and-earth.dart
@@ -0,0 +1,46 @@
+final shemaDarkTheme = ThemeData(
+  useMaterial3: true,
+  brightness: Brightness.dark,
+  fontFamily: 'Montserrat',
+  scaffoldBackgroundColor: colorShemaBlack,
+
+  colorScheme: const ColorScheme.dark(
+    primary: colorShemaTile,
+    secondary: colorShemaBlue,
+    tertiary: colorShemaGreenLight,
+    surface: colorShemaBlack,
+    background: colorShemaBlack,
+    onPrimary: colorShemaCream,
+    onSurface: colorShemaCream,
+    onSurfaceVariant: colorShemaSand,
+    outline: colorShemaGreenDark,
+  ),
+
+  appBarTheme: const AppBarTheme(
+    backgroundColor: colorShemaBlack,
+    foregroundColor: colorShemaCream,
+    elevation: 0,
+  ),
+
+  cardTheme: CardTheme(
+    color: colorShemaBlack,
+    elevation: 0,
+    shape: RoundedRectangleBorder(
+      borderRadius: BorderRadius.circular(16),
+      side: const BorderSide(
+        color: colorShemaGreenDark,
+        width: 1.5,
+      ),
+    ),
+  ),
+
+  inputDecorationTheme: InputDecorationTheme(
+    filled: true,
+    fillColor: colorShemaGreenDark.withOpacity(0.2),
+    border: OutlineInputBorder(
+      borderRadius: BorderRadius.circular(12),
+      borderSide: const BorderSide(color: colorShemaGreenDark),
+    ),
+    hintStyle: const TextStyle(color: colorShemaSand),
+  ),
+);
diff --git a/frontend/design-system/assets/references/app/components/themes/paper-and-ink.dart b/frontend/design-system/assets/references/app/components/themes/paper-and-ink.dart
new file mode 100644
index 0000000..5fe3bf7
--- /dev/null
+++ b/frontend/design-system/assets/references/app/components/themes/paper-and-ink.dart
@@ -0,0 +1,33 @@
+final shemaLightTheme = ThemeData(
+  useMaterial3: true,
+  brightness: Brightness.light,
+  fontFamily: 'Montserrat',
+  scaffoldBackgroundColor: colorShemaCream,
+
+  colorScheme: const ColorScheme.light(
+    primary: colorShemaTile,
+    secondary: colorShemaBlue,
+    tertiary: colorShemaGreenLight,
+    surface: colorWhite,
+    background: colorShemaCream,
+    onPrimary: colorShemaCream,
+    onSurface: colorShemaBlack,
+    outline: colorShemaSand,
+  ),
+
+  appBarTheme: const AppBarTheme(
+    backgroundColor: colorShemaCream,
+    foregroundColor: colorShemaBlack,
+    elevation: 0,
+  ),
+
+  cardTheme: CardTheme(
+    color: colorWhite,
+    elevation: 2,
+    shadowColor: colorShemaBlack.withOpacity(0.1),
+    shape: RoundedRectangleBorder(
+      borderRadius: BorderRadius.circular(16),
+      side: const BorderSide(color: colorShemaSand, width: 0.5),
+    ),
+  ),
+);
diff --git a/frontend/design-system/assets/references/icons.md b/frontend/design-system/assets/references/icons.md
new file mode 100644
index 0000000..192965f
--- /dev/null
+++ b/frontend/design-system/assets/references/icons.md
@@ -0,0 +1,14 @@
+# Iconography
+
+## Style
+- Web: Outline (1.5px–2px stroke)
+- App: Solid for active states / Outline for inactive states
+
+## Colors
+- Primary: Telha
+- Neutral: Dark Green or grey
+
+## References
+- Player: Simple musical note
+- Files: Minimal folder
+- Navigation: Chevron
\ No newline at end of file
diff --git a/frontend/design-system/assets/references/platforms/mobile-flutter.md b/frontend/design-system/assets/references/platforms/mobile-flutter.md
new file mode 100644
index 0000000..dac8623
--- /dev/null
+++ b/frontend/design-system/assets/references/platforms/mobile-flutter.md
@@ -0,0 +1,21 @@
+# Mobile Guidelines (Flutter) — Theming
+
+This document defines the official Light and Dark themes for the Shema mobile application,
+derived strictly from the brand color system.
+
+Flutter automatically switches between `theme` and `darkTheme`
+based on system preferences.
+
+---
+
+## Base Palette (from tokens/colors.json)
+
+```dart
+const colorShemaTile = Color(0xFFBE4A01);
+const colorShemaBlue = Color(0xFF89AAA3);
+const colorShemaGreenLight = Color(0xFF777D45);
+const colorShemaGreenDark = Color(0xFF3F3E20);
+const colorShemaSand = Color(0xFFC5C29F);
+const colorShemaBlack = Color(0xFF0A0703);
+const colorShemaCream = Color(0xFFF6F5EB);
+const colorWhite = Color(0xFFFFFFFF);
\ No newline at end of file
diff --git a/frontend/design-system/assets/references/web/components/buttons.md b/frontend/design-system/assets/references/web/components/buttons.md
new file mode 100644
index 0000000..ba58d0d
--- /dev/null
+++ b/frontend/design-system/assets/references/web/components/buttons.md
@@ -0,0 +1,31 @@
+{
+  "fontFamilies": {
+    "primary": "Montserrat",
+    "secondary": "Merriweather"
+  },
+  "weights": {
+    "regular": 400,
+    "medium": 500,
+    "bold": 700
+  },
+  "web_scale": {
+    "h1": { "fontFamily": "Montserrat", "weight": 700, "size": "32px", "lineHeight": 1.2 },
+    "h2": { "fontFamily": "Montserrat", "weight": 700, "size": "24px", "lineHeight": 1.3 },
+    "h3": { "fontFamily": "Montserrat", "weight": 600, "size": "20px", "lineHeight": 1.4 },
+    "body": { "fontFamily": "Montserrat", "weight": 400, "size": "16px", "lineHeight": 1.5 },
+    "body_serif": {
+      "fontFamily": "Merriweather",
+      "weight": 400,
+      "size": "16px",
+      "lineHeight": 1.6,
+      "usage": "Reading contexts"
+    },
+    "caption": { "fontFamily": "Montserrat", "weight": 500, "size": "12px", "lineHeight": 1.5 }
+  },
+  "app_scale": {
+    "display": { "fontFamily": "Montserrat", "weight": 700, "size": "28px", "flutter_style": "headlineMedium" },
+    "title": { "fontFamily": "Montserrat", "weight": 700, "size": "20px", "flutter_style": "titleLarge" },
+    "body": { "fontFamily": "Montserrat", "weight": 400, "size": "16px", "flutter_style": "bodyMedium" },
+    "label": { "fontFamily": "Montserrat", "weight": 500, "size": "14px", "flutter_style": "labelLarge" }
+  }
+}
diff --git a/frontend/design-system/assets/references/web/components/cards.md b/frontend/design-system/assets/references/web/components/cards.md
new file mode 100644
index 0000000..c576e6d
--- /dev/null
+++ b/frontend/design-system/assets/references/web/components/cards.md
@@ -0,0 +1,13 @@
+# Web Cards
+
+## Standard Card
+- Surface: White (`#FFFFFF`)
+- Page background: Cream (`#F6F5EB`)
+- Shadow: `0 4px 12px rgba(10, 7, 3, 0.05)`
+- Radius: 12px
+- Clear content hierarchy
+
+## Progress Section
+- Horizontal steps
+- Active: Telha
+- Inactive: Sand or light grey
diff --git a/frontend/design-system/badges.md b/frontend/design-system/badges.md
new file mode 100644
index 0000000..a4d5549
--- /dev/null
+++ b/frontend/design-system/badges.md
@@ -0,0 +1,363 @@
+# Badges — Shema Design System
+
+## Badge System
+
+The application uses badges to categorize and identify different types of elements, especially participants, events, and discourse relations.
+
+## Badge Base
+
+### Badge Component
+
+```tsx
+import { Badge } from '@/components/ui/badge'
+
+<Badge variant="default">Badge</Badge>
+```
+
+### Base Styles
+
+```typescript
+// frontend/src/components/ui/badge.tsx
+Badge: "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium border transition-colors"
+```
+
+## Badge Variants
+
+### Default Variants
+
+```typescript
+const variantClasses = {
+  default: 'bg-areia/30 text-preto border-areia',
+  success: 'bg-verde-claro/20 text-verde-claro border-verde-claro/30',
+  warning: 'bg-telha/10 text-telha border-telha/20',
+  secondary: 'bg-gray-100 text-gray-800 border-gray-200',
+  outline: 'bg-transparent border-gray-200 text-gray-800',
+}
+```
+
+### Usage
+
+```tsx
+<Badge variant="default">Default</Badge>
+<Badge variant="success">Success</Badge>
+<Badge variant="warning">Warning</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+## Badges by Category
+
+### Participants
+
+Specific colors for different participant categories:
+
+```typescript
+// frontend/src/styles/badges.ts
+export const participantCategoryColors: Record<ParticipantCategory, string> = {
+  divine: 'bg-amber-100 text-amber-800 border-amber-200',
+  person: 'bg-telha/10 text-telha-dark border-telha/20',
+  place: 'bg-azul/20 text-verde border-azul/30',
+  time: 'bg-verde-claro/20 text-verde border-verde-claro/30',
+  object: 'bg-gray-100 text-gray-800 border-gray-200',
+  abstract: 'bg-areia/30 text-preto border-areia',
+  group: 'bg-indigo-100 text-indigo-800 border-indigo-200',
+  animal: 'bg-emerald-100 text-emerald-800 border-emerald-200',
+}
+```
+
+#### Usage
+
+```tsx
+import { participantCategoryColors } from '@/styles'
+
+<Badge 
+  variant="person"
+  className={participantCategoryColors[participant.category]}
+>
+  {participant.category}
+</Badge>
+```
+
+#### Badge Variants for Participants
+
+```tsx
+<Badge variant="divine">Divine</Badge>
+<Badge variant="person">Person</Badge>
+<Badge variant="place">Place</Badge>
+<Badge variant="time">Time</Badge>
+<Badge variant="object">Object</Badge>
+<Badge variant="abstract">Abstract</Badge>
+<Badge variant="group">Group</Badge>
+```
+
+### Events
+
+Colors for event categories:
+
+```typescript
+export const eventCategoryColors: Record<EventCategory, string> = {
+  ACTION: 'bg-telha/10 text-telha border-telha/20',
+  SPEECH: 'bg-azul/20 text-verde border-azul/30',
+  MOTION: 'bg-verde-claro/20 text-verde border-verde-claro/30',
+  STATE: 'bg-areia/30 text-verde border-areia',
+  PROCESS: 'bg-purple-100 text-purple-800 border-purple-200',
+  TRANSFER: 'bg-blue-100 text-blue-800 border-blue-200',
+  INTERNAL: 'bg-pink-100 text-pink-800 border-pink-200',
+  RITUAL: 'bg-amber-100 text-amber-800 border-amber-200',
+  META: 'bg-gray-100 text-gray-800 border-gray-200',
+}
+```
+
+#### Usage
+
+```tsx
+import { eventCategoryColors } from '@/styles'
+
+<Badge className={eventCategoryColors[event.category]}>
+  {event.category}
+</Badge>
+```
+
+### Discourse
+
+Colors for discourse relations:
+
+```typescript
+export const discourseCategoryColors: Record<DiscourseCategory, string> = {
+  temporal: 'bg-blue-100 text-blue-800',
+  logical: 'bg-purple-100 text-purple-800',
+  rhetorical: 'bg-orange-100 text-orange-800',
+  narrative: 'bg-emerald-100 text-emerald-800',
+}
+```
+
+#### Usage
+
+```tsx
+import { discourseCategoryColors } from '@/styles'
+
+<Badge className={discourseCategoryColors[relation.category]}>
+  {relation.category}
+</Badge>
+```
+
+## Validation Badges
+
+### Validation States
+
+```typescript
+export const validationBadgeStyles = {
+  validated: 'bg-verde-claro/20 text-verde-claro border-verde-claro/30',
+  pending: 'bg-areia/30 text-verde border-areia',
+  error: 'bg-red-100 text-red-800 border-red-200',
+}
+```
+
+#### Usage
+
+```tsx
+import { validationBadgeStyles } from '@/styles'
+
+<Badge className={validationBadgeStyles.validated}>
+  Validated
+</Badge>
+
+<Badge className={validationBadgeStyles.pending}>
+  Pending
+</Badge>
+
+<Badge className={validationBadgeStyles.error}>
+  Error
+</Badge>
+```
+
+## Role Badges
+
+### Semantic Roles
+
+```typescript
+export const roleBadgeStyles = {
+  agent: 'bg-amber-100 text-amber-800',
+  patient: 'bg-blue-100 text-blue-800',
+  experiencer: 'bg-purple-100 text-purple-800',
+  instrument: 'bg-gray-100 text-gray-800',
+  beneficiary: 'bg-green-100 text-green-800',
+  location: 'bg-cyan-100 text-cyan-800',
+  source: 'bg-orange-100 text-orange-800',
+  goal: 'bg-pink-100 text-pink-800',
+}
+```
+
+#### Usage
+
+```tsx
+import { roleBadgeStyles } from '@/styles'
+
+  <Badge className={roleBadgeStyles.agent}>
+    Agent
+  </Badge>
+```
+
+## Badges with Icons
+
+### Badge with Icon on Left
+
+```tsx
+<Badge variant="success" className="flex items-center gap-1">
+  <CheckCircle2 className="w-3 h-3" />
+  Validated
+</Badge>
+```
+
+### Badge with Icon on Right
+
+```tsx
+<Badge variant="warning" className="flex items-center gap-1">
+  Pending
+  <Clock className="w-3 h-3" />
+</Badge>
+```
+
+### Badge with Icon Only
+
+```tsx
+<Badge variant="outline" className="p-1">
+  <Icon className="w-3 h-3" />
+</Badge>
+```
+
+## Status Badges
+
+### Progress Status
+
+```tsx
+<Badge variant="success">Complete</Badge>
+<Badge variant="warning">In Progress</Badge>
+<Badge variant="secondary">Pending</Badge>
+```
+
+### Approval Status
+
+```tsx
+{user.role === 'admin' && (
+  <Badge variant="default" className="text-xs">
+    Admin
+  </Badge>
+)}
+```
+
+## Interactive Badges
+
+### Clickable Badge
+
+```tsx
+<button
+  className={cn(
+    "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium border transition-colors",
+    "cursor-pointer hover:opacity-80",
+    participantCategoryColors[category]
+  )}
+  onClick={handleClick}
+>
+  {category}
+</button>
+```
+
+### Removable Badge
+
+```tsx
+<Badge className="flex items-center gap-1">
+  {label}
+  <button
+    onClick={onRemove}
+    className="ml-1 hover:opacity-70"
+  >
+    <X className="w-3 h-3" />
+  </button>
+</Badge>
+```
+
+## Badges in Lists
+
+### Badge List
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {categories.map(category => (
+    <Badge key={category} variant="default">
+      {category}
+    </Badge>
+  ))}
+</div>
+```
+
+### Badges in Grid
+
+```tsx
+<div className="grid grid-cols-2 md:grid-cols-4 gap-2">
+  {items.map(item => (
+    <Badge key={item.id} variant="default">
+      {item.label}
+    </Badge>
+  ))}
+</div>
+```
+
+## Custom Badges
+
+### Badge with Custom Background
+
+```tsx
+<Badge className="bg-telha/10 text-telha border-telha/20">
+  Custom
+</Badge>
+```
+
+### Badge with Custom Size
+
+```tsx
+<Badge className="px-3 py-1 text-sm">
+  Large Badge
+</Badge>
+```
+
+## Custom CSS Classes
+
+### Badge Classes in CSS
+
+```css
+.badge {
+  @apply inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium;
+}
+
+.badge-divine {
+  @apply bg-amber-100 text-amber-800 border border-amber-200;
+}
+
+.badge-place {
+  @apply bg-azul/20 text-verde border border-azul/30;
+}
+
+.badge-time {
+  @apply bg-verde-claro/20 text-verde border border-verde-claro/30;
+}
+
+.badge-person {
+  @apply bg-telha/10 text-telha-dark border border-telha/20;
+}
+
+.badge-abstract {
+  @apply bg-areia/30 text-preto border border-areia;
+}
+
+.badge-object {
+  @apply bg-gray-100 text-gray-800 border border-gray-200;
+}
+```
+
+## References
+
+- Badge component: `frontend/src/components/ui/badge.tsx`
+- Badge colors: `frontend/src/styles/badges.ts`
+- CSS styles: `frontend/src/styles/main.css`
+
diff --git a/frontend/design-system/border-radius.md b/frontend/design-system/border-radius.md
new file mode 100644
index 0000000..694ea2a
--- /dev/null
+++ b/frontend/design-system/border-radius.md
@@ -0,0 +1,300 @@
+# Border Radius — Shema Design System
+
+## Border Radius System
+
+The application uses a consistent border radius system based on rounded values.
+
+## Default Values
+
+### Tailwind Configuration
+
+```javascript
+borderRadius: {
+  sm: '0.25rem',   // 4px
+  md: '0.5rem',    // 8px
+  lg: '0.75rem',   // 12px
+}
+```
+
+### CSS Variable
+
+```css
+:root {
+  --radius: 0.5rem; /* 8px - default value */
+}
+```
+
+## Border Radius Scale
+
+| Class | Value | Pixels | Usage |
+|--------|-------|--------|-----|
+| `rounded-none` | 0 | 0px | No rounding |
+| `rounded-sm` | 0.25rem | 4px | Small rounding |
+| `rounded` | 0.5rem | 8px | Default rounding |
+| `rounded-md` | 0.5rem | 8px | Medium rounding (same as default) |
+| `rounded-lg` | 0.75rem | 12px | Large rounding |
+| `rounded-xl` | 1rem | 16px | Extra large rounding |
+| `rounded-2xl` | 1.5rem | 24px | Very large rounding |
+| `rounded-full` | 9999px | - | Full circle |
+
+## Usage by Component
+
+### Cards
+
+```tsx
+// Default card
+<Card className="rounded-xl">...</Card>
+
+// Stage card
+<div className="stage-card rounded-lg">...</div>
+
+// Clause card
+<div className="clause-card rounded-lg">...</div>
+
+// Event card
+<div className="event-card rounded-lg">...</div>
+```
+
+### Buttons
+
+```tsx
+// Default button
+<Button className="rounded-lg">...</Button>
+
+// Small button
+<Button size="sm" className="rounded-md">...</Button>
+
+// Large button
+<Button size="lg" className="rounded-lg">...</Button>
+```
+
+### Inputs
+
+```tsx
+// Default input
+<Input className="rounded-lg">...</Input>
+
+// Textarea
+<Textarea className="rounded-lg">...</Textarea>
+```
+
+### Badges
+
+```tsx
+// Default badge (full circle)
+<Badge className="rounded-full">...</Badge>
+```
+
+### Modals and Dialogs
+
+```tsx
+// Dialog
+<DialogContent className="rounded-xl">...</DialogContent>
+
+// Sheet
+<SheetContent className="rounded-l-xl">...</SheetContent>
+```
+
+## Specific Border Radius
+
+### Individual Corners
+
+```tsx
+// Top left
+<div className="rounded-tl-lg">...</div>
+
+// Top right
+<div className="rounded-tr-lg">...</div>
+
+// Bottom left
+<div className="rounded-bl-lg">...</div>
+
+// Bottom right
+<div className="rounded-br-lg">...</div>
+
+// Top (both)
+<div className="rounded-t-lg">...</div>
+
+// Bottom (both)
+<div className="rounded-b-lg">...</div>
+
+// Left (both)
+<div className="rounded-l-lg">...</div>
+
+// Right (both)
+<div className="rounded-r-lg">...</div>
+```
+
+## Usage Patterns
+
+### Cards with Border Radius
+
+```tsx
+// Default card
+<Card className="rounded-xl border border-areia/30">
+  ...
+</Card>
+
+// Card with hover
+<Card className="rounded-lg hover:shadow-md">
+  ...
+</Card>
+```
+
+### Buttons with Border Radius
+
+```tsx
+// Primary button
+<Button className="rounded-lg">
+  Button
+</Button>
+
+// Outline button
+<Button variant="outline" className="rounded-lg">
+  Button
+</Button>
+```
+
+### Inputs with Border Radius
+
+```tsx
+// Default input
+<Input className="rounded-lg border border-areia" />
+
+// Input with focus
+<Input className="rounded-lg focus-visible:ring-2 focus-visible:ring-telha" />
+```
+
+### Badges with Border Radius
+
+```tsx
+// Default badge (always rounded-full)
+<Badge className="rounded-full px-2.5 py-0.5">
+  Badge
+</Badge>
+```
+
+## Border Radius in States
+
+### Selected Cards
+
+```tsx
+<div className={cn(
+  "rounded-lg",
+  isSelected && "ring-2 ring-telha/50"
+)}>
+  ...
+</div>
+```
+
+### Cards with Hover
+
+```tsx
+<div className="rounded-lg transition-all hover:shadow-md">
+  ...
+</div>
+```
+
+## Responsive Border Radius
+
+Although uncommon, responsive border radius can be used:
+
+```tsx
+// Mobile: rounded-md, Desktop: rounded-lg
+<div className="rounded-md md:rounded-lg">...</div>
+```
+
+## Special Shapes
+
+### Circles
+
+```tsx
+// Circular avatar
+<div className="w-10 h-10 rounded-full bg-telha/20">
+  ...
+</div>
+
+// Circular icon
+<button className="w-10 h-10 rounded-full bg-areia/20">
+  <Icon />
+</button>
+```
+
+### Pills
+
+```tsx
+// Pill-shaped badge
+<Badge className="rounded-full px-3 py-1">
+  Badge
+</Badge>
+
+// Pill-shaped button
+<Button className="rounded-full px-6">
+  Pill Button
+</Button>
+```
+
+## Border Radius in Sections
+
+### Collapsible Sections
+
+```tsx
+<div className="rounded-lg border border-areia/30 overflow-hidden">
+  <div className="bg-areia/10 p-4">
+    Header
+  </div>
+  <div className="bg-white p-4">
+    Content
+  </div>
+</div>
+```
+
+### Cards with Border Left
+
+```tsx
+// Card with highlighted left border
+<div className="rounded-lg border-l-4 border-l-telha">
+  ...
+</div>
+
+// Mainline clause card
+<div className="clause-card-mainline rounded-lg border-l-4 border-l-telha">
+  ...
+</div>
+
+// Background clause card
+<div className="clause-card-background rounded-lg border-l-4 border-l-azul">
+  ...
+</div>
+```
+
+## Visual Consistency
+
+### Border Radius Hierarchy
+
+1. **Small elements** (badges, tags): `rounded-full`
+2. **Medium elements** (buttons, inputs): `rounded-lg`
+3. **Large elements** (cards, modals): `rounded-xl`
+4. **Very large elements** (containers): `rounded-2xl`
+
+### Hierarchy Examples
+
+```tsx
+// Large container
+<div className="rounded-2xl bg-white p-8">
+  {/* Medium card */}
+  <Card className="rounded-xl">
+    {/* Small button */}
+    <Button className="rounded-lg">...</Button>
+    {/* Badge */}
+    <Badge className="rounded-full">...</Badge>
+  </Card>
+</div>
+```
+
+## References
+
+- Tailwind configuration: `frontend/tailwind.config.js`
+- CSS variable: `frontend/src/styles/main.css`
+- UI components: `frontend/src/components/ui/`
+
diff --git a/frontend/design-system/cards.md b/frontend/design-system/cards.md
new file mode 100644
index 0000000..3bd16cf
--- /dev/null
+++ b/frontend/design-system/cards.md
@@ -0,0 +1,436 @@
+# Cards — Shema Design System
+
+## Card System
+
+The application uses a consistent card system with different variants and styles.
+
+## Card Base
+
+### Card Component
+
+The base `Card` component provides the default structure:
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'
+
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Card content
+  </CardContent>
+  <CardFooter>
+    Card actions
+  </CardFooter>
+</Card>
+```
+
+### Base Styles
+
+```typescript
+// frontend/src/components/ui/card.tsx
+Card: "rounded-xl border border-areia/30 bg-white shadow-sm transition-all duration-200 hover:shadow-md"
+
+CardHeader: "flex flex-col space-y-1.5 p-6"
+CardTitle: "text-xl font-semibold leading-none tracking-tight text-preto"
+CardDescription: "text-sm text-verde"
+CardContent: "p-6 pt-0"
+CardFooter: "flex items-center p-6 pt-0"
+```
+
+### Border
+
+All cards **must** include a visible border for visual separation:
+
+```css
+border: 1.5px solid var(--border-color);
+```
+
+> **Note:** This applies to every card variant (default, clause, event, participant, etc.). The `--border-color` CSS variable adapts automatically between light and dark themes.
+
+## Centralized Styles
+
+### Card Styles
+
+```typescript
+// frontend/src/styles/cards.ts
+export const cardStyles = {
+  base: 'bg-white rounded-lg border border-areia/30 shadow-sm',
+  hover: 'transition-all duration-200 hover:shadow-md hover:border-telha/30',
+  dashed: 'border-dashed',
+  selected: 'ring-2 ring-telha/50 border-telha',
+}
+```
+
+### Usage
+
+```tsx
+import { cardStyles } from '@/styles'
+import { cn } from '@/utils/cn'
+
+<div className={cn(cardStyles.base, cardStyles.hover)}>
+  ...
+</div>
+```
+
+## Card Variants
+
+### 1. Default Card
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Content
+  </CardContent>
+</Card>
+```
+
+### 2. Card with Hover
+
+```tsx
+<div className={cn(cardStyles.base, cardStyles.hover)}>
+  ...
+</div>
+```
+
+### 3. Selected Card
+
+```tsx
+<div className={cn(
+  cardStyles.base,
+  isSelected && cardStyles.selected
+)}>
+  ...
+</div>
+```
+
+### 4. Card with Dashed Border
+
+```tsx
+<div className={cn(cardStyles.base, cardStyles.dashed)}>
+  ...
+</div>
+```
+
+## Specific Cards
+
+### Stage Card
+
+Card used in application stages:
+
+```tsx
+<div className="stage-card">
+  {/* bg-white rounded-lg shadow-md border border-areia/30 p-6 */}
+  ...
+</div>
+```
+
+### Clause Card
+
+Card for displaying clauses:
+
+```typescript
+export const clauseCardStyles = {
+  base: 'bg-white rounded-lg border border-areia/30 p-4 transition-all duration-200 hover:shadow-md hover:border-telha/30',
+  mainline: 'border-l-4 border-l-telha',
+  background: 'border-l-4 border-l-azul',
+}
+```
+
+#### Usage
+
+```tsx
+import { clauseCardStyles } from '@/styles'
+
+// Default clause card
+<div className={clauseCardStyles.base}>
+  ...
+</div>
+
+// Mainline clause card
+<div className={cn(clauseCardStyles.base, clauseCardStyles.mainline)}>
+  ...
+</div>
+
+// Background clause card
+<div className={cn(clauseCardStyles.base, clauseCardStyles.background)}>
+  ...
+</div>
+```
+
+### Event Card
+
+Card for displaying events:
+
+```typescript
+export const eventCardStyles = {
+  base: 'bg-white rounded-lg border border-areia/30 p-4',
+  validated: 'border-verde-claro/50 bg-verde-claro/5',
+  error: 'border-red-300 bg-red-50',
+}
+```
+
+#### Usage
+
+```tsx
+import { eventCardStyles } from '@/styles'
+
+// Default event card
+<div className={eventCardStyles.base}>
+  ...
+</div>
+
+// Validated event card
+<div className={cn(eventCardStyles.base, eventCardStyles.validated)}>
+  ...
+</div>
+
+// Event card with error
+<div className={cn(eventCardStyles.base, eventCardStyles.error)}>
+  ...
+</div>
+```
+
+### Participant Card
+
+Card for displaying participants:
+
+```typescript
+export const participantCardStyles = {
+  base: 'bg-white rounded-lg border border-areia/30 p-4 transition-all duration-200',
+  validated: 'border-verde-claro/50 bg-verde-claro/5',
+  hover: 'hover:shadow-md hover:border-telha/30',
+}
+```
+
+#### Usage
+
+```tsx
+import { participantCardStyles } from '@/styles'
+
+// Default participant card
+<div className={cn(participantCardStyles.base, participantCardStyles.hover)}>
+  ...
+</div>
+
+// Validated participant card
+<div className={cn(
+  participantCardStyles.base,
+  participantCardStyles.validated
+)}>
+  ...
+</div>
+```
+
+## Card States
+
+### Card with Loading
+
+```tsx
+<Card>
+  <CardContent className="py-12">
+    <div className="flex items-center justify-center">
+      <div className="animate-spin w-8 h-8 border-4 border-telha border-t-transparent rounded-full" />
+    </div>
+  </CardContent>
+</Card>
+```
+
+### Card with Error
+
+```tsx
+<Card>
+  <CardContent className="py-8 text-center">
+    <div className="bg-red-50 border border-red-200 text-red-700 px-4 py-3 rounded-lg">
+      Error loading
+    </div>
+  </CardContent>
+</Card>
+```
+
+### Empty Card
+
+```tsx
+<Card>
+  <CardContent className="py-12 text-center text-verde/60">
+    <Icon className="w-12 h-12 mx-auto mb-4 opacity-30" />
+    <p className="text-sm">No items found</p>
+  </CardContent>
+</Card>
+```
+
+## Interactive Cards
+
+### Clickable Card
+
+```tsx
+<button
+  className={cn(
+    cardStyles.base,
+    cardStyles.hover,
+    "cursor-pointer text-left w-full"
+  )}
+  onClick={handleClick}
+>
+  ...
+</button>
+```
+
+### Expandable Card
+
+```tsx
+const [isExpanded, setIsExpanded] = useState(false)
+
+<Card>
+  <CardHeader>
+    <button
+      onClick={() => setIsExpanded(!isExpanded)}
+      className="flex items-center justify-between w-full"
+    >
+      <CardTitle>Title</CardTitle>
+      {isExpanded ? <ChevronUp /> : <ChevronDown />}
+    </button>
+  </CardHeader>
+  {isExpanded && (
+    <CardContent>
+      Expanded content
+    </CardContent>
+  )}
+</Card>
+```
+
+## Cards in Grid
+
+### Card Grid
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+  {items.map(item => (
+    <Card key={item.id}>
+      ...
+    </Card>
+  ))}
+</div>
+```
+
+### 2-Column Grid
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <Card>...</Card>
+  <Card>...</Card>
+</div>
+```
+
+### 4-Column Grid
+
+```tsx
+<div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+  <Card>...</Card>
+  <Card>...</Card>
+  <Card>...</Card>
+  <Card>...</Card>
+</div>
+```
+
+## Cards with Icons
+
+### Card with Icon in Title
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle className="flex items-center gap-2">
+      <Icon className="w-5 h-5 text-telha" />
+      Card Title
+    </CardTitle>
+  </CardHeader>
+  <CardContent>
+    ...
+  </CardContent>
+</Card>
+```
+
+### Card with Status Icon
+
+```tsx
+<Card>
+  <CardHeader>
+    <div className="flex items-center justify-between">
+      <CardTitle>Title</CardTitle>
+      <div className="flex items-center gap-2">
+        {isValidated && (
+          <CheckCircle2 className="w-5 h-5 text-verde-claro" />
+        )}
+      </div>
+    </div>
+  </CardHeader>
+  ...
+</Card>
+```
+
+## Cards with Actions
+
+### Card with Buttons
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>
+    Content
+  </CardContent>
+  <CardFooter className="flex justify-end gap-2">
+    <Button variant="outline">Cancel</Button>
+    <Button>Confirm</Button>
+  </CardFooter>
+</Card>
+```
+
+### Card with Actions in Header
+
+```tsx
+<Card>
+  <CardHeader>
+    <div className="flex items-center justify-between">
+      <div>
+        <CardTitle>Title</CardTitle>
+        <CardDescription>Description</CardDescription>
+      </div>
+      <Button variant="ghost" size="icon">
+        <MoreVertical />
+      </Button>
+    </div>
+  </CardHeader>
+  ...
+</Card>
+```
+
+## Responsive Cards
+
+### Adaptive Card
+
+```tsx
+<Card className="w-full">
+  <CardHeader className="p-4 md:p-6">
+    ...
+  </CardHeader>
+  <CardContent className="p-4 md:p-6 pt-0">
+    ...
+  </CardContent>
+</Card>
+```
+
+## References
+
+- Card component: `frontend/src/components/ui/card.tsx`
+- Card styles: `frontend/src/styles/cards.ts`
+- CSS styles: `frontend/src/styles/main.css`
+
diff --git a/frontend/design-system/colors.md b/frontend/design-system/colors.md
new file mode 100644
index 0000000..f28f35b
--- /dev/null
+++ b/frontend/design-system/colors.md
@@ -0,0 +1,247 @@
+# Color System — Shema Design System
+
+## Overview
+
+The Shema Design System uses an earthy color palette inspired by natural tones, reflecting the brand values: simple, accessible, lively, friendly, and human.
+
+## Base Palette
+
+The color system is defined in [tokens/colors.json](./tokens/colors.json), which is the authoritative source.
+
+| Name | Hex | Token | Usage |
+|------|-----|-------|-----|
+| **Telha (Clay/Tile)** | `#BE4A01` | `telha` | Primary color, CTAs, primary actions, active states |
+| **Shema White (Cream)** | `#F6F5EB` | `branco` | Main background, simulates paper |
+| **Sand** | `#C5C29F` | `areia` | Borders, secondary elements, muted |
+| **Blue** | `#89AAA3` | `azul` | Supporting elements, subtle backgrounds |
+| **Light Green** | `#777D45` | `verde-claro` | Success, validation, positive states |
+| **Dark Green** | `#3F3E20` | `verde` | Secondary text, descriptions |
+| **Shema Black** | `#0A0703` | `preto` | Primary text, foreground |
+| **Pure White** | `#FFFFFF` | `white` | Elevated surfaces (cards, inputs) |
+
+> [!IMPORTANT]
+> **Shema Brand Rule**: Never use pure white (#FFFFFF) as the main background. Use **Shema White / Cream (#F6F5EB)** to simulate paper and provide visual comfort. Pure white is reserved exclusively for elevated surfaces (cards, inputs).
+
+## Primary Colors
+
+### Telha (#BE4A01)
+
+**Exclusive to CTAs, primary actions, and active icons.**
+
+- **Never** use Telha as neutral decoration or background.
+- Variations are created through opacity or state changes.
+- Hover states use opacity, never new colors.
+
+### Shema White / Cream (#F6F5EB)
+
+**Main background color.**
+
+- Provides paper-like warmth and reduces eye strain.
+- Pure white (#FFFFFF) is reserved for elevated surfaces (cards, inputs).
+
+### Shema Black (#0A0703)
+
+**Primary text color.**
+
+- Softer than absolute black, better for long reading sessions.
+- Never use absolute black (#000000).
+
+### Shema Dark Green (#3F3E20)
+
+**Secondary text, subtitles, descriptions.**
+
+## Supporting Colors
+
+### Blue (#89AAA3)
+
+Supporting elements and subtle backgrounds.
+
+### Light Green (#777D45)
+
+Success states, positive indicators, validation.
+
+### Sand (#C5C29F)
+
+Borders, muted elements, warnings.
+
+## Semantic Tokens
+
+The system defines semantic tokens that map to base colors:
+
+```typescript
+primary: {
+  DEFAULT: '#BE4A01',      // telha
+  foreground: '#F6F5EB',   // branco
+}
+
+secondary: {
+  DEFAULT: '#89AAA3',      // azul
+  foreground: '#0A0703',   // preto
+}
+
+success: {
+  DEFAULT: '#777D45',      // verde-claro
+  foreground: '#F6F5EB',  // branco
+}
+
+background: '#F6F5EB'     // branco (Shema Cream)
+foreground: '#0A0703'     // preto (Shema Black)
+
+card: {
+  DEFAULT: '#FFFFFF',      // white
+  foreground: '#0A0703',  // preto
+}
+
+border: '#C5C29F'         // areia
+input: '#C5C29F'          // areia
+ring: '#BE4A01'           // telha (focus rings)
+
+muted: {
+  DEFAULT: '#C5C29F',     // areia
+  foreground: '#3F3E20', // verde
+}
+
+accent: {
+  DEFAULT: '#89AAA3',     // azul
+  foreground: '#0A0703', // preto
+}
+
+destructive: {
+  DEFAULT: '#BE4A01',     // telha (same as primary)
+  foreground: '#F6F5EB', // branco
+}
+```
+
+## Opacity Patterns
+
+The system uses opacity to create subtle variations:
+
+- `/10` - Very subtle backgrounds (e.g., `bg-telha/10`)
+- `/20` - Soft backgrounds for badges/highlights (e.g., `bg-verde-claro/20`)
+- `/30` - Borders and subtle separators (e.g., `border-areia/30`)
+- `/50` - Medium overlays
+- `/90` - Strong hover states
+
+### Examples
+
+```tsx
+// Soft background
+<div className="bg-verde-claro/10">...</div>
+
+// Border with opacity
+<div className="border border-areia/30">...</div>
+
+// Hover with opacity
+<button className="hover:bg-telha/20">...</button>
+```
+
+## Category Colors
+
+### Participants
+
+Colors for different participant categories:
+
+```typescript
+participantCategoryColors = {
+  divine: 'bg-amber-100 text-amber-800 border-amber-200',
+  person: 'bg-telha/10 text-telha-dark border-telha/20',
+  place: 'bg-azul/20 text-verde border-azul/30',
+  time: 'bg-verde-claro/20 text-verde border-verde-claro/30',
+  object: 'bg-gray-100 text-gray-800 border-gray-200',
+  abstract: 'bg-areia/30 text-preto border-areia',
+  group: 'bg-indigo-100 text-indigo-800 border-indigo-200',
+  animal: 'bg-emerald-100 text-emerald-800 border-emerald-200',
+}
+```
+
+### Events
+
+Colors for event categories:
+
+```typescript
+eventCategoryColors = {
+  ACTION: 'bg-telha/10 text-telha border-telha/20',
+  SPEECH: 'bg-azul/20 text-verde border-azul/30',
+  MOTION: 'bg-verde-claro/20 text-verde border-verde-claro/30',
+  STATE: 'bg-areia/30 text-verde border-areia',
+  PROCESS: 'bg-purple-100 text-purple-800 border-purple-200',
+  TRANSFER: 'bg-blue-100 text-blue-800 border-blue-200',
+  INTERNAL: 'bg-pink-100 text-pink-800 border-pink-200',
+  RITUAL: 'bg-amber-100 text-amber-800 border-amber-200',
+  META: 'bg-gray-100 text-gray-800 border-gray-200',
+}
+```
+
+### Discourse
+
+Colors for discourse relations:
+
+```typescript
+discourseCategoryColors = {
+  temporal: 'bg-blue-100 text-blue-800',
+  logical: 'bg-purple-100 text-purple-800',
+  rhetorical: 'bg-orange-100 text-orange-800',
+  narrative: 'bg-emerald-100 text-emerald-800',
+}
+```
+
+## Validation States
+
+Colors for validation states:
+
+```typescript
+validationBadgeStyles = {
+  validated: 'bg-verde-claro/20 text-verde-claro border-verde-claro/30',
+  pending: 'bg-areia/30 text-verde border-areia',
+  error: 'bg-red-100 text-red-800 border-red-200',
+}
+```
+
+## Accessibility
+
+### Contrast
+
+All color combinations follow WCAG standards:
+
+- **Normal text**: Minimum contrast of 4.5:1
+- **Large text**: Minimum contrast of 3:1
+- **Interactive elements**: Minimum contrast of 3:1
+
+### Contrast Examples
+
+- `preto` on `branco`: ✅ 21:1 (Excellent)
+- `telha` on `branco`: ✅ 4.8:1 (Adequate)
+- `verde` on `branco`: ✅ 8.2:1 (Excellent)
+- `telha` on `areia`: ⚠️ 2.1:1 (Not adequate - avoid)
+
+## Usage in Code
+
+### Tailwind Classes
+
+```tsx
+// Direct colors
+<div className="bg-telha text-white">...</div>
+<div className="text-verde">...</div>
+
+// With opacity
+<div className="bg-verde-claro/10 border-verde-claro/30">...</div>
+
+// Semantic tokens
+<div className="bg-primary text-primary-foreground">...</div>
+```
+
+### TypeScript/JavaScript
+
+```typescript
+import { participantCategoryColors } from '@/styles'
+
+const categoryColor = participantCategoryColors[participant.category]
+```
+
+## References
+
+- Design tokens: [tokens/colors.json](./tokens/colors.json)
+- Brand guidelines: [AGENTS.md](./AGENTS.md)
+- Tailwind config: `frontend/tailwind.config.js`
+- Styles: `frontend/src/styles/main.css`
+- Badge colors: `frontend/src/styles/badges.ts`
diff --git a/frontend/design-system/components.md b/frontend/design-system/components.md
new file mode 100644
index 0000000..ead1394
--- /dev/null
+++ b/frontend/design-system/components.md
@@ -0,0 +1,630 @@
+# UI Components — Shema Design System
+
+## Component System
+
+The application uses base components built with Radix UI, Tailwind CSS, and class-variance-authority (cva).
+
+## Component Structure
+
+All components follow this pattern:
+
+```tsx
+import * as React from "react"
+import { cn } from "@/utils/cn"
+import { cva, type VariantProps } from "class-variance-authority"
+
+// Variants using cva
+const componentVariants = cva(
+  "base-classes",
+  {
+    variants: {
+      variant: { ... },
+      size: { ... },
+    },
+    defaultVariants: { ... }
+  }
+)
+
+// Props interface
+export interface ComponentProps
+  extends React.HTMLAttributes<HTMLElement>,
+    VariantProps<typeof componentVariants> {
+  // additional props
+}
+
+// Component
+const Component = React.forwardRef<HTMLElement, ComponentProps>(
+  ({ className, variant, size, ...props }, ref) => {
+    return (
+      <element
+        ref={ref}
+        className={cn(componentVariants({ variant, size, className }))}
+        {...props}
+      />
+    )
+  }
+)
+
+Component.displayName = "Component"
+
+export { Component, componentVariants }
+```
+
+## Progress Step
+
+Component for displaying step progress in a process or flow. Supports horizontal (desktop) and vertical (mobile) layouts.
+
+### States
+
+- **completed**: Completed step (light green with checkmark)
+- **current**: Current step (telha with number and pulse animation)
+- **pending**: Pending step (areia/30 with number)
+
+### Base Styles
+
+#### Progress Step Container
+
+```typescript
+ProgressStepContainer: "bg-white rounded-xl border border-areia/30 shadow-sm p-6 md:p-8"
+ProgressStepTitle: "text-xl font-semibold text-preto mb-6 flex items-center gap-2"
+```
+
+#### Step Circle (Step Icon)
+
+**Mobile (w-10 h-10):**
+```typescript
+// Completed
+"w-10 h-10 rounded-full bg-verde-claro flex items-center justify-center text-white"
+
+// Current
+"w-10 h-10 rounded-full bg-telha flex items-center justify-center text-white font-semibold animate-pulse"
+
+// Pending
+"w-10 h-10 rounded-full bg-areia/30 flex items-center justify-center text-verde font-semibold"
+```
+
+**Desktop (w-12 h-12):**
+```typescript
+// Completed
+"w-12 h-12 rounded-full bg-verde-claro flex items-center justify-center text-white mb-3"
+
+// Current
+"w-12 h-12 rounded-full bg-telha flex items-center justify-center text-white font-semibold mb-3 animate-pulse"
+
+// Pending
+"w-12 h-12 rounded-full bg-areia/30 flex items-center justify-center text-verde font-semibold mb-3"
+```
+
+#### Connectors (Lines between steps)
+
+**Mobile (vertical):**
+```typescript
+// Completed connector
+"w-0.5 h-12 bg-verde-claro mt-2"
+
+// Pending connector
+"w-0.5 h-12 bg-areia/50 mt-2"
+```
+
+**Desktop (horizontal):**
+```typescript
+// Completed connector
+"flex-1 h-1 bg-verde-claro mx-2 -mt-8"
+
+// Pending connector
+"flex-1 h-1 bg-areia/50 mx-2 -mt-8"
+```
+
+#### Step Texts
+
+**Mobile:**
+```typescript
+StepTitle: "font-semibold text-preto"
+StepTitlePending: "font-semibold text-verde/60"
+StepStatus: "text-sm text-verde mt-1"
+StepStatusCurrent: "text-sm text-telha mt-1"
+StepStatusPending: "text-sm text-verde/50 mt-1"
+```
+
+**Desktop:**
+```typescript
+StepTitle: "font-semibold text-preto text-center"
+StepTitlePending: "font-semibold text-verde/60 text-center"
+StepStatus: "text-sm text-verde mt-1 text-center"
+StepStatusCurrent: "text-sm text-telha mt-1 text-center"
+StepStatusPending: "text-sm text-verde/50 mt-1 text-center"
+```
+
+### Layout Mobile (Vertical)
+
+```tsx
+<div className="flex flex-col md:hidden space-y-4">
+  {steps.map((step, index) => (
+    <div key={index} className="flex items-start gap-4">
+      <div className="flex flex-col items-center">
+        <div className={stepCircleClasses[step.status]}>
+          {step.status === 'completed' ? (
+            <CheckIcon className="w-5 h-5" />
+          ) : (
+            <span>{step.number}</span>
+          )}
+        </div>
+        {index < steps.length - 1 && (
+          <div className={connectorClasses[step.status]} />
+        )}
+      </div>
+      <div className="flex-1 pt-2">
+        <p className={stepTitleClasses[step.status]}>
+          {step.title}
+        </p>
+        <p className={stepStatusClasses[step.status]}>
+          {step.statusText}
+        </p>
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+### Layout Desktop (Horizontal)
+
+```tsx
+<div className="hidden md:flex items-center justify-between">
+  {steps.map((step, index) => (
+    <>
+      <div key={index} className="flex flex-col items-center flex-1">
+        <div className={stepCircleClasses[step.status]}>
+          {step.status === 'completed' ? (
+            <CheckIcon className="w-6 h-6" />
+          ) : (
+            <span>{step.number}</span>
+          )}
+        </div>
+        <p className={stepTitleClasses[step.status]}>
+          {step.title}
+        </p>
+        <p className={stepStatusClasses[step.status]}>
+          {step.statusText}
+        </p>
+      </div>
+      {index < steps.length - 1 && (
+        <div className={connectorClasses[step.status]} />
+      )}
+    </>
+  ))}
+</div>
+```
+
+### Spacing
+
+- **Container padding**: `p-6 md:p-8` (24px mobile, 32px desktop)
+- **Gap between steps (mobile)**: `space-y-4` (16px vertical)
+- **Gap between step and content (mobile)**: `gap-4` (16px horizontal)
+- **Title margin bottom**: `mb-6` (24px)
+- **Status margin top**: `mt-1` (4px)
+- **Content padding top (mobile)**: `pt-2` (8px)
+- **Circle margin bottom (desktop)**: `mb-3` (12px)
+- **Connector horizontal margin (desktop)**: `mx-2` (8px)
+- **Connector negative top margin (desktop)**: `-mt-8` (-32px to align with circle)
+
+### Full Usage
+
+```tsx
+<section className="bg-white rounded-xl border border-areia/30 shadow-sm p-6 md:p-8">
+  <h2 className="text-xl font-semibold text-preto mb-6 flex items-center gap-2">
+    <ListChecksIcon className="w-5 h-5 text-telha" />
+    Project Progress
+  </h2>
+  
+  <div className="relative">
+    {/* Mobile Layout */}
+    <div className="flex flex-col md:hidden space-y-4">
+      {/* Steps here */}
+    </div>
+    
+    {/* Desktop Layout */}
+    <div className="hidden md:flex items-center justify-between">
+      {/* Steps here */}
+    </div>
+  </div>
+</section>
+```
+
+## Button
+
+### Variants
+
+```typescript
+variant: {
+  default: "bg-telha text-white hover:bg-telha-dark shadow-md hover:shadow-lg",
+  secondary: "bg-azul text-white hover:bg-azul/90",
+  outline: "border-2 border-areia bg-transparent hover:bg-areia/20 text-preto",
+  ghost: "hover:bg-areia/20 text-preto",
+  success: "bg-verde-claro text-white hover:bg-verde",
+  destructive: "bg-red-500 text-white hover:bg-red-600",
+  link: "text-telha underline-offset-4 hover:underline",
+}
+```
+
+### Sizes
+
+```typescript
+size: {
+  default: "h-10 px-4 py-2",
+  sm: "h-9 rounded-md px-3",
+  lg: "h-12 rounded-lg px-8 text-base",
+  icon: "h-10 w-10",
+}
+```
+
+### Usage
+
+```tsx
+import { Button } from '@/components/ui/button'
+
+// Default button
+<Button>Click here</Button>
+
+// Secondary button
+<Button variant="secondary">Secondary</Button>
+
+// Outline button
+<Button variant="outline">Outline</Button>
+
+// Ghost button
+<Button variant="ghost">Ghost</Button>
+
+// Success button
+<Button variant="success">Success</Button>
+
+// Destructive button
+<Button variant="destructive">Delete</Button>
+
+// Link button
+<Button variant="link">Link</Button>
+
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="default">Default</Button>
+<Button size="lg">Large</Button>
+<Button size="icon"><Icon /></Button>
+
+// With icon
+<Button>
+  <Icon className="w-4 h-4 mr-2" />
+  Text
+</Button>
+```
+
+## Card
+
+### Structure
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'
+
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Content
+  </CardContent>
+  <CardFooter>
+    Footer
+  </CardFooter>
+</Card>
+```
+
+### Styles
+
+```typescript
+Card: "rounded-xl border border-areia/30 bg-white shadow-sm transition-all duration-200 hover:shadow-md"
+CardHeader: "flex flex-col space-y-1.5 p-6"
+CardTitle: "text-xl font-semibold leading-none tracking-tight text-preto"
+CardDescription: "text-sm text-verde"
+CardContent: "p-6 pt-0"
+CardFooter: "flex items-center p-6 pt-0"
+```
+
+### Usage
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card content</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+## Input
+
+### Styles
+
+```typescript
+Input: "flex h-10 w-full rounded-lg border border-areia bg-white px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-verde/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-telha focus-visible:ring-offset-2 focus-visible:border-telha disabled:cursor-not-allowed disabled:opacity-50 transition-all duration-200"
+```
+
+### Usage
+
+```tsx
+import { Input } from '@/components/ui/input'
+
+<Input type="text" placeholder="Type here..." />
+
+<Input type="email" placeholder="email@example.com" />
+
+<Input type="password" placeholder="Password" />
+
+<Input disabled placeholder="Disabled" />
+```
+
+## Textarea
+
+### Styles
+
+Similar to Input, but with adjustable height.
+
+### Usage
+
+```tsx
+import { Textarea } from '@/components/ui/textarea'
+
+<Textarea placeholder="Type your message..." />
+
+<Textarea rows={5} placeholder="Long text..." />
+```
+
+## Badge
+
+See complete documentation in [Badges](./badges.md).
+
+### Basic Usage
+
+```tsx
+import { Badge } from '@/components/ui/badge'
+
+<Badge variant="default">Badge</Badge>
+<Badge variant="success">Success</Badge>
+<Badge variant="warning">Warning</Badge>
+```
+
+## Select / Dropdown
+
+### Select Styles
+
+```typescript
+SelectContainer: "relative"
+SelectTrigger: "w-full h-10 px-3 pr-8 rounded-lg border border-areia bg-white text-sm appearance-none focus:outline-none focus:ring-2 focus:ring-telha focus:border-telha transition-all duration-200"
+SelectIcon: "w-4 h-4 absolute right-3 top-1/2 transform -translate-y-1/2 text-verde/50 pointer-events-none"
+```
+
+### Label with Default Spacing
+
+```typescript
+Label: "text-sm font-medium text-preto block mb-2"
+```
+
+The default spacing between label and input/select is **`mb-2`** (8px).
+
+### Usage with Label
+
+```tsx
+<div className="w-full md:w-48">
+  <label className="text-sm font-medium text-preto block mb-2">
+    Period
+  </label>
+  <div className="relative">
+    <select className="w-full h-10 px-3 pr-8 rounded-lg border border-areia bg-white text-sm appearance-none focus:outline-none focus:ring-2 focus:ring-telha focus:border-telha transition-all duration-200">
+      <option>Last 7 days</option>
+      <option>Last 30 days</option>
+      <option>Last 90 days</option>
+    </select>
+    <ChevronDownIcon className="w-4 h-4 absolute right-3 top-1/2 transform -translate-y-1/2 text-verde/50 pointer-events-none" />
+  </div>
+</div>
+```
+
+### Usage with Radix UI Select
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+
+<div className="space-y-2">
+  <label className="text-sm font-medium text-preto block mb-2">
+    Select an option
+  </label>
+  <Select>
+    <SelectTrigger className="w-full h-10">
+      <SelectValue placeholder="Select..." />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="option1">Option 1</SelectItem>
+      <SelectItem value="option2">Option 2</SelectItem>
+      <SelectItem value="option3">Option 3</SelectItem>
+    </SelectContent>
+  </Select>
+</div>
+```
+
+### Sizes and Spacing
+
+- **Select height**: `h-10` (40px)
+- **Horizontal padding**: `px-3` (12px)
+- **Right padding (for icon)**: `pr-8` (32px)
+- **Label → select spacing**: `mb-2` (8px)
+- **Chevron icon**: `w-4 h-4` (16px)
+- **Icon position**: `right-3` (12px from right)
+
+## Dialog
+
+### Usage
+
+```tsx
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog'
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Dialog Title</DialogTitle>
+      <DialogDescription>
+        Dialog description
+      </DialogDescription>
+    </DialogHeader>
+    <div>
+      Dialog content
+    </div>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Alert Dialog
+
+### Usage
+
+```tsx
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger } from '@/components/ui/alert-dialog'
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Confirm deletion</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Confirm</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Sheet
+
+### Usage
+
+```tsx
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger } from '@/components/ui/sheet'
+
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>Open Sheet</Button>
+  </SheetTrigger>
+  <SheetContent>
+    <SheetHeader>
+      <SheetTitle>Title</SheetTitle>
+      <SheetDescription>
+        Description
+      </SheetDescription>
+    </SheetHeader>
+    <div>
+      Content
+    </div>
+  </SheetContent>
+</Sheet>
+```
+
+## Progress
+
+### Usage
+
+```tsx
+import { Progress } from '@/components/ui/progress'
+
+<Progress value={33} />
+
+<Progress value={66} className="h-2" />
+```
+
+## Usage Patterns
+
+### Complete Form
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Form</CardTitle>
+    <CardDescription>Fill in the fields below</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <form className="space-y-4">
+      <div className="space-y-2">
+        <label className="text-sm font-medium">Name</label>
+        <Input placeholder="Enter your name" />
+      </div>
+      <div className="space-y-2">
+        <label className="text-sm font-medium">Email</label>
+        <Input type="email" placeholder="email@example.com" />
+      </div>
+      <div className="space-y-2">
+        <label className="text-sm font-medium">Message</label>
+        <Textarea placeholder="Type your message..." />
+      </div>
+    </form>
+  </CardContent>
+  <CardFooter>
+    <Button variant="outline">Cancel</Button>
+    <Button>Send</Button>
+  </CardFooter>
+</Card>
+```
+
+### List with Actions
+
+```tsx
+<Card>
+  <CardHeader>
+    <div className="flex items-center justify-between">
+      <CardTitle>Items</CardTitle>
+      <Button size="sm">
+        <Plus className="w-4 h-4 mr-2" />
+        Add
+      </Button>
+    </div>
+  </CardHeader>
+  <CardContent>
+    <div className="space-y-2">
+      {items.map(item => (
+        <div key={item.id} className="flex items-center justify-between p-2 border rounded">
+          <span>{item.name}</span>
+          <div className="flex items-center gap-2">
+            <Button variant="ghost" size="icon">
+              <Edit className="w-4 h-4" />
+            </Button>
+            <Button variant="ghost" size="icon">
+              <Trash className="w-4 h-4" />
+            </Button>
+          </div>
+        </div>
+      ))}
+    </div>
+  </CardContent>
+</Card>
+```
+
+## References
+
+- UI components: `frontend/src/components/ui/`
+- Utilities: `frontend/src/utils/cn.ts`
+- class-variance-authority: https://cva.style/
+
diff --git a/frontend/design-system/figma-links.md b/frontend/design-system/figma-links.md
new file mode 100644
index 0000000..8bb2d55
--- /dev/null
+++ b/frontend/design-system/figma-links.md
@@ -0,0 +1,22 @@
+# Figma Structure
+
+## Foundations
+- Colors
+- Typography
+- Shadows & Elevation
+
+## Components
+- Buttons
+- Inputs
+- Avatars
+
+## Patterns
+- Web Cards
+- Mobile Cards
+- Navigation Bars
+
+## Naming Convention
+Use "/" to define hierarchy:
+
+- Button/Primary/Default  
+- Card/Mobile/Project
diff --git a/frontend/design-system/layout.md b/frontend/design-system/layout.md
new file mode 100644
index 0000000..5ea6d2b
--- /dev/null
+++ b/frontend/design-system/layout.md
@@ -0,0 +1,346 @@
+# Layout — Shema Design System
+
+## Layout System
+
+The application uses a consistent layout system based on containers, grids, and spacing patterns.
+
+## Containers
+
+### Default Container
+
+```tsx
+<div className="container mx-auto p-6">
+  ...
+</div>
+```
+
+### Responsive Container
+
+```tsx
+<div className="container mx-auto p-4 md:p-6 lg:p-8">
+  ...
+</div>
+```
+
+## Grids
+
+### 2-Column Grid
+
+```typescript
+// frontend/src/styles/layout.ts
+export const gridStyles = {
+  twoColumn: 'grid grid-cols-1 md:grid-cols-2 gap-4',
+  threeColumn: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4',
+  fourColumn: 'grid grid-cols-2 md:grid-cols-4 gap-4',
+}
+```
+
+#### Usage
+
+```tsx
+import { gridStyles } from '@/styles'
+
+<div className={gridStyles.twoColumn}>
+  <Card>...</Card>
+  <Card>...</Card>
+</div>
+```
+
+### Custom Grid
+
+```tsx
+// 1 column on mobile, 2 on tablet, 3 on desktop
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+  ...
+</div>
+
+// 2 columns on mobile, 4 on desktop
+<div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+  ...
+</div>
+```
+
+## Pages
+
+### Page Structure
+
+```typescript
+export const pageStyles = {
+  container: 'space-y-6',
+  header: 'flex items-start justify-between',
+  title: 'text-2xl font-bold text-preto flex items-center gap-2',
+  subtitle: 'text-verde mt-1',
+  actions: 'flex items-center gap-2',
+}
+```
+
+#### Usage
+
+```tsx
+import { pageStyles } from '@/styles'
+
+<div className={pageStyles.container}>
+  <div className={pageStyles.header}>
+    <div>
+      <h1 className={pageStyles.title}>
+        <Icon className="w-5 h-5 text-telha" />
+        Page Title
+      </h1>
+      <p className={pageStyles.subtitle}>
+        Subtitle or description
+      </p>
+    </div>
+    <div className={pageStyles.actions}>
+      <Button>Action</Button>
+    </div>
+  </div>
+  <div>
+    Page content
+  </div>
+</div>
+```
+
+### Complete Page
+
+```tsx
+<div className="container mx-auto p-6 space-y-8">
+  <div className="flex items-start justify-between">
+    <div>
+      <h1 className="text-2xl font-bold text-preto flex items-center gap-2">
+        <Icon className="w-5 h-5 text-telha" />
+        Title
+      </h1>
+      <p className="text-verde mt-1">Description</p>
+    </div>
+    <div className="flex items-center gap-2">
+      <Button variant="outline">Action 1</Button>
+      <Button>Action 2</Button>
+    </div>
+  </div>
+  
+  <div className="space-y-6">
+    {/* Content */}
+  </div>
+</div>
+```
+
+## Headers
+
+### Stage Header
+
+```typescript
+export const stageHeaderStyles = {
+  icon: 'w-6 h-6 text-telha',
+  title: 'text-2xl font-bold text-preto flex items-center gap-2',
+  description: 'text-verde mt-1',
+}
+```
+
+#### Usage
+
+```tsx
+import { stageHeaderStyles } from '@/styles'
+
+<div>
+  <h1 className={stageHeaderStyles.title}>
+    <Icon className={stageHeaderStyles.icon} />
+    Stage Title
+  </h1>
+  <p className={stageHeaderStyles.description}>
+    Stage description
+  </p>
+</div>
+```
+
+## Forms
+
+### Form Group
+
+```typescript
+export const formStyles = {
+  group: 'space-y-2',
+  label: 'text-sm font-medium text-preto',
+  hint: 'text-xs text-verde/60',
+  error: 'text-xs text-red-600',
+}
+```
+
+#### Usage
+
+```tsx
+import { formStyles } from '@/styles'
+
+<div className={formStyles.group}>
+  <label className={formStyles.label}>
+    Field Name
+  </label>
+  <Input placeholder="Type..." />
+  <span className={formStyles.hint}>
+    Hint or help
+  </span>
+  {error && (
+    <span className={formStyles.error}>
+      {error}
+    </span>
+  )}
+</div>
+```
+
+### Complete Form
+
+```tsx
+<form className="space-y-4">
+  <div className={formStyles.group}>
+    <label className={formStyles.label}>Name</label>
+    <Input />
+    <span className={formStyles.hint}>Enter your full name</span>
+  </div>
+  
+  <div className={formStyles.group}>
+    <label className={formStyles.label}>Email</label>
+    <Input type="email" />
+    {errors.email && (
+      <span className={formStyles.error}>{errors.email}</span>
+    )}
+  </div>
+  
+  <div className="flex justify-end gap-2">
+    <Button variant="outline">Cancel</Button>
+    <Button>Save</Button>
+  </div>
+</form>
+```
+
+## Modals
+
+### Modal Styles
+
+```typescript
+export const modalStyles = {
+  header: 'text-lg font-semibold text-preto',
+  description: 'text-sm text-verde',
+  footer: 'flex justify-end gap-2 pt-4',
+}
+```
+
+#### Usage
+
+```tsx
+import { modalStyles } from '@/styles'
+
+<Dialog>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle className={modalStyles.header}>
+        Title
+      </DialogTitle>
+      <DialogDescription className={modalStyles.description}>
+        Description
+      </DialogDescription>
+    </DialogHeader>
+    <div>
+      Content
+    </div>
+    <DialogFooter className={modalStyles.footer}>
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Flexbox
+
+### Flex Row
+
+```tsx
+<div className="flex items-center gap-2">
+  <Icon />
+  <span>Text</span>
+</div>
+```
+
+### Flex Column
+
+```tsx
+<div className="flex flex-col gap-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+### Flex with Spacing
+
+```tsx
+<div className="flex items-center justify-between">
+  <span>Left</span>
+  <span>Right</span>
+</div>
+```
+
+### Flex Wrap
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {items.map(item => (
+    <Badge key={item.id}>{item.label}</Badge>
+  ))}
+</div>
+```
+
+## Spacing
+
+See complete documentation in [Spacing](./spacing.md).
+
+### Vertical Spacing
+
+```tsx
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+### Horizontal Spacing
+
+```tsx
+<div className="flex space-x-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+## Responsiveness
+
+### Breakpoints
+
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+- `2xl`: 1536px
+
+### Responsive Layout
+
+```tsx
+// Mobile: 1 column, Desktop: 2 columns
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+  ...
+</div>
+
+// Mobile: stack, Desktop: row
+<div className="flex flex-col md:flex-row gap-4">
+  ...
+</div>
+
+// Responsive padding
+<div className="p-4 md:p-6 lg:p-8">
+  ...
+</div>
+```
+
+## References
+
+- Layout styles: `frontend/src/styles/layout.ts`
+- Layout components: `frontend/src/components/layout/`
+
diff --git a/frontend/design-system/sections.md b/frontend/design-system/sections.md
new file mode 100644
index 0000000..7607e10
--- /dev/null
+++ b/frontend/design-system/sections.md
@@ -0,0 +1,371 @@
+# Sections — Shema Design System
+
+## Section System
+
+The application uses collapsible sections with different visual variants to organize related content.
+
+## Base Section
+
+### Section Structure
+
+```tsx
+<div className="border border-areia/30 rounded-lg overflow-hidden">
+  <button className="bg-areia/10 hover:bg-areia/20 p-4 w-full text-left">
+    Section Header
+  </button>
+  <div className="bg-white p-4">
+    Section Content
+  </div>
+</div>
+```
+
+## Section Variants
+
+### Variant Types
+
+```typescript
+// frontend/src/styles/sections.ts
+export type SectionVariant = 
+  | 'default' 
+  | 'roles' 
+  | 'modifiers' 
+  | 'pragmatic' 
+  | 'emotion' 
+  | 'la-tags' 
+  | 'figurative' 
+  | 'key-terms' 
+  | 'speech'
+  | 'narrator'
+```
+
+### Style Interface
+
+```typescript
+export interface SectionStyle {
+  header: string
+  content: string
+  border: string
+}
+```
+
+## Styles by Variant
+
+### Default
+
+```typescript
+default: {
+  header: 'bg-areia/10 hover:bg-areia/20',
+  content: 'bg-white',
+  border: 'border-areia/30',
+}
+```
+
+#### Usage
+
+```tsx
+import { sectionStyles } from '@/styles'
+
+<div className={cn("border rounded-lg overflow-hidden", sectionStyles.default.border)}>
+  <button className={cn("p-4 w-full text-left", sectionStyles.default.header)}>
+    Default Section
+  </button>
+  <div className={sectionStyles.default.content}>
+    Content
+  </div>
+</div>
+```
+
+### Roles
+
+```typescript
+roles: {
+  header: 'bg-amber-50 hover:bg-amber-100',
+  content: 'bg-amber-50/50',
+  border: 'border-l-4 border-l-amber-400 border-areia/30',
+}
+```
+
+#### Usage
+
+```tsx
+<div className={cn("border rounded-lg overflow-hidden", sectionStyles.roles.border)}>
+  <button className={cn("p-4 w-full text-left", sectionStyles.roles.header)}>
+    Roles
+  </button>
+  <div className={sectionStyles.roles.content}>
+    Roles content
+  </div>
+</div>
+```
+
+### Modifiers
+
+```typescript
+modifiers: {
+  header: 'bg-slate-50 hover:bg-slate-100',
+  content: 'bg-white',
+  border: 'border-areia/30',
+}
+```
+
+#### Usage
+
+```tsx
+<div className={cn("border rounded-lg overflow-hidden", sectionStyles.modifiers.border)}>
+  <button className={cn("p-4 w-full text-left", sectionStyles.modifiers.header)}>
+    Modifiers
+  </button>
+  <div className={sectionStyles.modifiers.content}>
+    Modifiers content
+  </div>
+</div>
+```
+
+### Pragmatic
+
+```typescript
+pragmatic: {
+  header: 'bg-yellow-50 hover:bg-yellow-100',
+  content: 'bg-yellow-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### Emotion
+
+```typescript
+emotion: {
+  header: 'bg-pink-50 hover:bg-pink-100',
+  content: 'bg-pink-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### LA Tags
+
+```typescript
+'la-tags': {
+  header: 'bg-emerald-50 hover:bg-emerald-100',
+  content: 'bg-emerald-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### Figurative
+
+```typescript
+figurative: {
+  header: 'bg-purple-50 hover:bg-purple-100',
+  content: 'bg-purple-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### Key Terms
+
+```typescript
+'key-terms': {
+  header: 'bg-orange-50 hover:bg-orange-100',
+  content: 'bg-orange-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### Speech
+
+```typescript
+speech: {
+  header: 'bg-blue-50 hover:bg-blue-100',
+  content: 'bg-blue-50/50',
+  border: 'border-areia/30',
+}
+```
+
+### Narrator
+
+```typescript
+narrator: {
+  header: 'bg-indigo-50 hover:bg-indigo-100',
+  content: 'bg-indigo-50/50',
+  border: 'border-areia/30',
+}
+```
+
+## Collapsible Section
+
+### Collapsible Section Component
+
+```tsx
+import { useState } from 'react'
+import { ChevronDown, ChevronUp } from 'lucide-react'
+import { sectionStyles } from '@/styles'
+import { cn } from '@/utils/cn'
+
+function CollapsibleSection({ variant = 'default', title, children }) {
+  const [isOpen, setIsOpen] = useState(false)
+  const styles = sectionStyles[variant]
+
+  return (
+    <div className={cn("border rounded-lg overflow-hidden", styles.border)}>
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className={cn("p-4 w-full text-left flex items-center justify-between", styles.header)}
+      >
+        <span className="font-medium">{title}</span>
+        {isOpen ? (
+          <ChevronUp className="w-4 h-4" />
+        ) : (
+          <ChevronDown className="w-4 h-4" />
+        )}
+      </button>
+      {isOpen && (
+        <div className={styles.content}>
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+### Usage
+
+```tsx
+<CollapsibleSection variant="roles" title="Roles">
+  <div className="space-y-2">
+    {/* Content */}
+  </div>
+</CollapsibleSection>
+```
+
+## Section with Icon
+
+### Header with Icon
+
+```tsx
+<button className={cn("p-4 w-full text-left flex items-center gap-2", sectionStyles.roles.header)}>
+  <Icon className="w-4 h-4" />
+  <span className="font-medium">Section Title</span>
+</button>
+```
+
+## Section with Badge
+
+### Header with Counter
+
+```tsx
+<button className={cn("p-4 w-full text-left flex items-center justify-between", sectionStyles.roles.header)}>
+  <div className="flex items-center gap-2">
+    <Icon className="w-4 h-4" />
+    <span className="font-medium">Title</span>
+  </div>
+  <Badge variant="default">{count}</Badge>
+</button>
+```
+
+## Section with Actions
+
+### Header with Buttons
+
+```tsx
+<button className={cn("p-4 w-full text-left flex items-center justify-between", sectionStyles.roles.header)}>
+  <span className="font-medium">Title</span>
+  <div className="flex items-center gap-2" onClick={(e) => e.stopPropagation()}>
+    <Button variant="ghost" size="sm">
+      <Plus className="w-4 h-4" />
+    </Button>
+  </div>
+</button>
+```
+
+## Multiple Sections
+
+### Section List
+
+```tsx
+<div className="space-y-4">
+  <CollapsibleSection variant="roles" title="Roles">
+    ...
+  </CollapsibleSection>
+  <CollapsibleSection variant="modifiers" title="Modifiers">
+    ...
+  </CollapsibleSection>
+  <CollapsibleSection variant="emotion" title="Emotions">
+    ...
+  </CollapsibleSection>
+</div>
+```
+
+## Section Expanded by Default
+
+### Initially Open Section
+
+```tsx
+function CollapsibleSection({ variant = 'default', title, children, defaultOpen = false }) {
+  const [isOpen, setIsOpen] = useState(defaultOpen)
+  // ...
+}
+```
+
+### Usage
+
+```tsx
+<CollapsibleSection variant="roles" title="Roles" defaultOpen={true}>
+  ...
+</CollapsibleSection>
+```
+
+## Section with Custom Content
+
+### Content with Custom Padding
+
+```tsx
+<div className={cn(sectionStyles.roles.content, "p-6")}>
+  {children}
+</div>
+```
+
+## Nested Section
+
+### Sections Within Sections
+
+```tsx
+<CollapsibleSection variant="default" title="Main Section">
+  <div className="space-y-2">
+    <CollapsibleSection variant="roles" title="Sub-section">
+      ...
+    </CollapsibleSection>
+  </div>
+</CollapsibleSection>
+```
+
+## Section with Validation State
+
+### Validated Section
+
+```tsx
+<div className={cn(
+  "border rounded-lg overflow-hidden",
+  sectionStyles.roles.border,
+  isValidated && "border-verde-claro/50"
+)}>
+  <button className={cn(
+    "p-4 w-full text-left flex items-center justify-between",
+    sectionStyles.roles.header
+  )}>
+    <div className="flex items-center gap-2">
+      <span className="font-medium">Title</span>
+      {isValidated && (
+        <CheckCircle2 className="w-4 h-4 text-verde-claro" />
+      )}
+    </div>
+  </button>
+  ...
+</div>
+```
+
+## References
+
+- Section styles: `frontend/src/styles/sections.ts`
+- Section components: `frontend/src/components/stages/Stage4Events/CollapsibleSection.tsx`
+
diff --git a/frontend/design-system/spacing.md b/frontend/design-system/spacing.md
new file mode 100644
index 0000000..db941e6
--- /dev/null
+++ b/frontend/design-system/spacing.md
@@ -0,0 +1,387 @@
+# Spacing — Shema Design System
+
+## Overview
+
+The application uses the Tailwind CSS spacing system, based on a 4px (0.25rem) scale. The spacing system is defined in [tokens/spacing.json](./tokens/spacing.json), which is the authoritative source.
+
+## Base Unit
+
+The spacing system uses a **4px base unit** (Tailwind default).
+
+## Spacing Scale
+
+| Class | Value | Pixels | Usage |
+|---------|-------|--------|-----|
+| `0` | 0 | 0px | No spacing |
+| `0.5` | 0.125rem | 2px | Minimum spacing |
+| `1` | 0.25rem | 4px | Very small spacing |
+| `1.5` | 0.375rem | 6px | Small spacing |
+| `2` | 0.5rem | 8px | Small spacing |
+| `2.5` | 0.625rem | 10px | Small-medium spacing |
+| `3` | 0.75rem | 12px | Medium spacing |
+| `4` | 1rem | 16px | Default spacing |
+| `5` | 1.25rem | 20px | Medium-large spacing |
+| `6` | 1.5rem | 24px | Large spacing |
+| `8` | 2rem | 32px | Very large spacing |
+| `10` | 2.5rem | 40px | Extra large spacing |
+| `12` | 3rem | 48px | Maximum common spacing |
+
+### Semantic Spacing Values
+
+From [tokens/spacing.json](./tokens/spacing.json):
+
+```json
+{
+  "base": 4,
+  "scale": {
+    "xs": { "value": "4px", "flutter": 4 },
+    "sm": { "value": "8px", "flutter": 8 },
+    "md": { "value": "16px", "flutter": 16 },
+    "lg": { "value": "24px", "flutter": 24 },
+    "xl": { "value": "32px", "flutter": 32 },
+    "xxl": { "value": "48px", "flutter": 48 }
+  }
+}
+```
+
+## Padding
+
+### Card Padding
+
+```tsx
+// Default card
+<Card className="p-6">...</Card>
+
+// Card header
+<CardHeader className="p-6">...</CardHeader>
+
+// Card content
+<CardContent className="p-6 pt-0">...</CardContent>
+
+// Card footer
+<CardFooter className="p-6 pt-0">...</CardFooter>
+```
+
+**Minimum**: 16px (mobile), **Recommended**: 24px (desktop)
+
+### Button Padding
+
+```tsx
+// Default button
+<Button className="px-4 py-2">...</Button>
+
+// Small button
+<Button size="sm" className="px-3">...</Button>
+
+// Large button
+<Button size="lg" className="px-8">...</Button>
+
+// Icon button
+<Button size="icon" className="w-10 h-10">...</Button>
+```
+
+### Input Padding
+
+```tsx
+<Input className="px-3 py-2">...</Input>
+```
+
+### Badge Padding
+
+```tsx
+<Badge className="px-2.5 py-0.5">...</Badge>
+```
+
+### Responsive Padding
+
+```tsx
+// Mobile: p-4, Desktop: p-6
+<div className="p-4 md:p-6">...</div>
+
+// Mobile: px-3, Desktop: px-6
+<div className="px-3 md:px-6">...</div>
+```
+
+## Margin
+
+### Vertical Spacing (space-y)
+
+```tsx
+// Default spacing between elements
+<div className="space-y-4">...</div>
+
+// Small spacing
+<div className="space-y-2">...</div>
+
+// Large spacing
+<div className="space-y-6">...</div>
+
+// Very large spacing
+<div className="space-y-8">...</div>
+```
+
+**Recommended**: `space-y-6` or `space-y-8` for vertical rhythm.
+
+### Horizontal Spacing (space-x)
+
+```tsx
+// Default horizontal spacing
+<div className="flex space-x-2">...</div>
+
+// Large horizontal spacing
+<div className="flex space-x-4">...</div>
+```
+
+### Individual Margin
+
+```tsx
+// Top
+<div className="mt-4">...</div>
+
+// Bottom
+<div className="mb-4">...</div>
+
+// Left
+<div className="ml-4">...</div>
+
+// Right
+<div className="mr-4">...</div>
+
+// All sides
+<div className="m-4">...</div>
+```
+
+### Negative Margin
+
+```tsx
+// Element overlap
+<div className="-mt-4">...</div>
+```
+
+## Gap (Flexbox/Grid)
+
+### Gap in Flex
+
+```tsx
+// Default gap
+<div className="flex gap-2">...</div>
+
+// Medium gap
+<div className="flex gap-4">...</div>
+
+// Large gap
+<div className="flex gap-6">...</div>
+```
+
+### Gap in Grid
+
+```tsx
+// Grid with gap
+<div className="grid grid-cols-2 gap-4">...</div>
+
+// Responsive grid
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">...</div>
+```
+
+## Layout Patterns
+
+### Container
+
+```tsx
+// Container with padding
+<div className="container mx-auto p-6">...</div>
+
+// Responsive container padding
+<div className="container mx-auto p-4 md:p-6">...</div>
+```
+
+**Max width**: 1200px (from tokens/spacing.json)
+
+### Page Layout
+
+```tsx
+// Default page
+<div className="container mx-auto p-6 space-y-8">...</div>
+
+// Page with smaller spacing
+<div className="container mx-auto p-6 space-y-6">...</div>
+```
+
+### Card Layout
+
+```tsx
+// Card with internal spacing
+<Card className="p-6">
+  <div className="space-y-4">...</div>
+</Card>
+```
+
+### Form Layout
+
+```tsx
+// Form group
+<div className="space-y-2">
+  <label>...</label>
+  <Input />
+  <span className="text-xs">Hint</span>
+</div>
+
+// Form with multiple groups
+<form className="space-y-4">
+  <div className="space-y-2">...</div>
+  <div className="space-y-2">...</div>
+</form>
+```
+
+### Modal Layout
+
+```tsx
+<Dialog>
+  <DialogHeader className="space-y-1.5">...</DialogHeader>
+  <DialogContent className="p-6">
+    <div className="space-y-4">...</div>
+  </DialogContent>
+  <DialogFooter className="pt-4">
+    <div className="flex gap-2">...</div>
+  </DialogFooter>
+</Dialog>
+```
+
+## Grids
+
+### 2-Column Grid
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4">...</div>
+```
+
+### 3-Column Grid
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">...</div>
+```
+
+### 4-Column Grid
+
+```tsx
+<div className="grid grid-cols-2 md:grid-cols-4 gap-4">...</div>
+```
+
+## Component-Specific Spacing
+
+### Stage Cards
+
+```tsx
+<div className="stage-card p-6">
+  <div className="space-y-6">...</div>
+</div>
+```
+
+### Clause Cards
+
+```tsx
+<div className="clause-card p-4">
+  <div className="space-y-2">...</div>
+</div>
+```
+
+### Event Cards
+
+```tsx
+<div className="event-card p-4">
+  <div className="space-y-3">...</div>
+</div>
+```
+
+### Participant Cards
+
+```tsx
+<div className="participant-card p-4">
+  <div className="space-y-2">...</div>
+</div>
+```
+
+## Icon Spacing
+
+### Icons with Text
+
+```tsx
+// Icon on the left
+<div className="flex items-center gap-2">
+  <Icon className="w-4 h-4" />
+  <span>Text</span>
+</div>
+
+// Icon on the right
+<div className="flex items-center gap-2">
+  <span>Text</span>
+  <Icon className="w-4 h-4" />
+</div>
+```
+
+### Icons in Titles
+
+```tsx
+<h1 className="flex items-center gap-2">
+  <Icon className="w-5 h-5" />
+  Title
+</h1>
+```
+
+## Responsive Spacing
+
+### Breakpoints
+
+```tsx
+// Mobile first
+<div className="p-4 md:p-6 lg:p-8">...</div>
+
+// Conditional spacing
+<div className="space-y-4 md:space-y-6">...</div>
+
+// Responsive gap
+<div className="grid gap-2 md:gap-4 lg:gap-6">...</div>
+```
+
+## Spacing Patterns by Context
+
+### Empty States
+
+```tsx
+<div className="py-12 text-center">...</div>
+```
+
+### Loading States
+
+```tsx
+<div className="flex items-center justify-center py-12">...</div>
+```
+
+### Error States
+
+```tsx
+<div className="p-8 text-center">...</div>
+```
+
+### Section Headers
+
+```tsx
+<div className="flex items-start justify-between mb-4">...</div>
+```
+
+## Generous Breathing Room
+
+The design system emphasizes **generous breathing room**:
+
+- Use the 4px base spacing scale consistently
+- Card padding: 16px minimum (mobile), 24px recommended (desktop)
+- Section gaps: `space-y-6` or `space-y-8` for vertical rhythm
+- Grid systems: Responsive grids that adapt from single column (mobile) to multi-column (desktop)
+
+## References
+
+- Design tokens: [tokens/spacing.json](./tokens/spacing.json)
+- Brand guidelines: [AGENTS.md](./AGENTS.md)
+- Tailwind config: `frontend/tailwind.config.js`
+- Layout styles: `frontend/src/styles/layout.ts`
+- UI components: `frontend/src/components/ui/`
diff --git a/frontend/design-system/states.md b/frontend/design-system/states.md
new file mode 100644
index 0000000..eef6dcd
--- /dev/null
+++ b/frontend/design-system/states.md
@@ -0,0 +1,460 @@
+# States — Shema Design System
+
+## State System
+
+The application uses consistent visual states to communicate different conditions: loading, error, success, warning, information, and empty states.
+
+## Available States
+
+### Empty State
+
+Used when there is no data to display.
+
+```typescript
+// frontend/src/styles/states.ts
+export const emptyStateStyles = {
+  container: 'py-12 text-center text-verde/60',
+  icon: 'w-12 h-12 mx-auto mb-4 opacity-30',
+  text: 'text-sm',
+}
+```
+
+#### Usage
+
+```tsx
+import { emptyStateStyles } from '@/styles'
+
+<div className={emptyStateStyles.container}>
+  <Icon className={emptyStateStyles.icon} />
+  <p className={emptyStateStyles.text}>
+    No items found
+  </p>
+</div>
+```
+
+#### Complete Example
+
+```tsx
+{items.length === 0 ? (
+  <div className="py-12 text-center text-verde/60">
+    <Icon className="w-12 h-12 mx-auto mb-4 opacity-30" />
+    <p className="text-sm">No items found</p>
+  </div>
+) : (
+  <div className="space-y-4">
+    {items.map(item => ...)}
+  </div>
+)}
+```
+
+### Loading State
+
+Used during asynchronous operations.
+
+```typescript
+export const loadingStateStyles = {
+  container: 'flex items-center justify-center py-12',
+  spinner: 'w-8 h-8 animate-spin text-telha',
+  smallSpinner: 'w-4 h-4 animate-spin text-telha',
+  text: 'text-verde ml-3',
+}
+```
+
+#### Default Spinner
+
+```tsx
+import { loadingStateStyles } from '@/styles'
+
+<div className={loadingStateStyles.container}>
+  <div className={loadingStateStyles.spinner}>
+    <div className="w-8 h-8 border-4 border-telha border-t-transparent rounded-full animate-spin" />
+  </div>
+</div>
+```
+
+#### Small Spinner
+
+```tsx
+<div className={loadingStateStyles.container}>
+  <div className={loadingStateStyles.smallSpinner}>
+    <div className="w-4 h-4 border-2 border-telha border-t-transparent rounded-full animate-spin" />
+  </div>
+</div>
+```
+
+#### Loading with Text
+
+```tsx
+<div className={loadingStateStyles.container}>
+  <div className={loadingStateStyles.spinner}>
+    <div className="w-8 h-8 border-4 border-telha border-t-transparent rounded-full animate-spin" />
+  </div>
+  <p className={loadingStateStyles.text}>Loading...</p>
+</div>
+```
+
+#### Loading in Card
+
+```tsx
+<Card>
+  <CardContent className="py-12">
+    <div className="flex items-center justify-center">
+      <div className="animate-spin w-8 h-8 border-4 border-telha border-t-transparent rounded-full" />
+    </div>
+  </CardContent>
+</Card>
+```
+
+### Error State
+
+Used to display error messages.
+
+```typescript
+export const errorStateStyles = {
+  banner: 'bg-red-50 border border-red-200 text-red-700 px-4 py-3 rounded-lg',
+  icon: 'w-4 h-4 text-red-600',
+  text: 'text-sm',
+}
+```
+
+#### Error Banner
+
+```tsx
+import { errorStateStyles } from '@/styles'
+
+<div className={errorStateStyles.banner}>
+  Error loading data
+</div>
+```
+
+#### Error with Icon
+
+```tsx
+<div className={errorStateStyles.banner}>
+  <div className="flex items-center gap-2">
+    <AlertCircle className={errorStateStyles.icon} />
+    <span>Error loading data</span>
+  </div>
+</div>
+```
+
+#### Error in Card
+
+```tsx
+<Card>
+  <CardContent className="py-8 text-center">
+    <div className={errorStateStyles.banner}>
+      {error}
+    </div>
+    <div className="mt-4">
+      <Button onClick={retry}>Try Again</Button>
+    </div>
+  </CardContent>
+</Card>
+```
+
+#### Error in Form
+
+```tsx
+<div className="space-y-2">
+  <Input />
+  {error && (
+    <p className="text-xs text-red-600">
+      {error}
+    </p>
+  )}
+</div>
+```
+
+### Success State
+
+Used to confirm successful actions.
+
+```typescript
+export const successStateStyles = {
+  banner: 'bg-verde-claro/10 border border-verde-claro/30 text-verde px-4 py-3 rounded-lg',
+  icon: 'w-4 h-4 text-verde-claro',
+  text: 'text-sm',
+}
+```
+
+#### Success Banner
+
+```tsx
+import { successStateStyles } from '@/styles'
+
+<div className={successStateStyles.banner}>
+  Operation completed successfully
+</div>
+```
+
+#### Success with Icon
+
+```tsx
+<div className={successStateStyles.banner}>
+  <div className="flex items-center gap-2">
+    <CheckCircle2 className={successStateStyles.icon} />
+    <span>Saved successfully</span>
+  </div>
+</div>
+```
+
+#### Success Toast
+
+```tsx
+import { toast } from 'sonner'
+
+toast.success('Operation completed successfully', {
+  description: 'The data was saved correctly'
+})
+```
+
+### Warning State
+
+Used for alerts and warnings.
+
+```typescript
+export const warningStateStyles = {
+  banner: 'bg-yellow-50 border border-yellow-200 text-yellow-800 px-4 py-3 rounded-lg',
+  icon: 'w-4 h-4 text-yellow-600',
+  text: 'text-sm',
+}
+```
+
+#### Warning Banner
+
+```tsx
+import { warningStateStyles } from '@/styles'
+
+<div className={warningStateStyles.banner}>
+  Warning: This action cannot be undone
+</div>
+```
+
+#### Warning with Icon
+
+```tsx
+<div className={warningStateStyles.banner}>
+  <div className="flex items-center gap-2">
+    <AlertTriangle className={warningStateStyles.icon} />
+    <span>Warning: This action cannot be undone</span>
+  </div>
+</div>
+```
+
+### Info State
+
+Used for informative messages.
+
+```typescript
+export const infoStateStyles = {
+  banner: 'bg-azul/10 border border-azul/30 text-verde px-4 py-3 rounded-lg',
+  icon: 'w-4 h-4 text-azul',
+  text: 'text-sm',
+}
+```
+
+#### Info Banner
+
+```tsx
+import { infoStateStyles } from '@/styles'
+
+<div className={infoStateStyles.banner}>
+  Important information about this feature
+</div>
+```
+
+#### Info with Icon
+
+```tsx
+<div className={infoStateStyles.banner}>
+  <div className="flex items-center gap-2">
+    <Info className={infoStateStyles.icon} />
+    <span>Important information</span>
+  </div>
+</div>
+```
+
+### Read-Only Banner
+
+Used to indicate that a resource is in read-only mode.
+
+```typescript
+export const readOnlyBannerStyles = {
+  container: 'bg-azul/10 border border-azul/30 text-verde px-4 py-3 rounded-lg flex items-center gap-2',
+  icon: 'w-4 h-4 text-azul',
+  text: 'text-sm font-medium',
+}
+```
+
+#### Usage
+
+```tsx
+import { readOnlyBannerStyles } from '@/styles'
+
+<div className={readOnlyBannerStyles.container}>
+  <Lock className={readOnlyBannerStyles.icon} />
+  <span className={readOnlyBannerStyles.text}>
+    This resource is in read-only mode
+  </span>
+</div>
+```
+
+## Validation States
+
+### Validation Progress
+
+Validation progress indicator.
+
+```typescript
+export const validationProgressStyles = {
+  container: 'flex items-center gap-4',
+  bar: 'flex-1 h-2 bg-areia/30 rounded-full overflow-hidden',
+  fill: 'h-full bg-verde-claro transition-all duration-300',
+  text: 'text-sm text-verde whitespace-nowrap',
+}
+```
+
+#### Usage
+
+```tsx
+import { validationProgressStyles } from '@/styles'
+
+<div className={validationProgressStyles.container}>
+  <div className={validationProgressStyles.bar}>
+    <div 
+      className={validationProgressStyles.fill}
+      style={{ width: `${progress}%` }}
+    />
+  </div>
+  <span className={validationProgressStyles.text}>
+    {validated}/{total} validated
+  </span>
+</div>
+```
+
+## Combined States
+
+### Loading with Empty State
+
+```tsx
+{loading ? (
+  <div className="flex items-center justify-center py-12">
+    <div className="animate-spin w-8 h-8 border-4 border-telha border-t-transparent rounded-full" />
+  </div>
+) : items.length === 0 ? (
+  <div className="py-12 text-center text-verde/60">
+    <Icon className="w-12 h-12 mx-auto mb-4 opacity-30" />
+    <p className="text-sm">No items found</p>
+  </div>
+) : (
+  <div className="space-y-4">
+    {items.map(item => ...)}
+  </div>
+)}
+```
+
+### Error with Retry
+
+```tsx
+{error ? (
+  <Card>
+    <CardContent className="py-8 text-center">
+      <div className={errorStateStyles.banner}>
+        {error}
+      </div>
+      <div className="mt-4">
+        <Button onClick={retry}>Try Again</Button>
+      </div>
+    </CardContent>
+  </Card>
+) : (
+  <div className="space-y-4">
+    {items.map(item => ...)}
+  </div>
+)}
+```
+
+## States in Specific Components
+
+### Clause State
+
+```tsx
+{clause.validated ? (
+  <div className="border-verde-claro/50 bg-verde-claro/5">
+    Validated clause
+  </div>
+) : (
+  <div className="border-areia/30">
+    Pending clause
+  </div>
+)}
+```
+
+### Event State
+
+```tsx
+{event.validated ? (
+  <div className="border-verde-claro/50 bg-verde-claro/5">
+    Validated event
+  </div>
+) : event.errors.length > 0 ? (
+  <div className="border-red-300 bg-red-50">
+    Event with errors
+  </div>
+) : (
+  <div className="border-areia/30">
+    Pending event
+  </div>
+)}
+```
+
+## Icons by State
+
+### Recommended Icons
+
+- **Loading**: `Loader2` (with spin animation)
+- **Error**: `AlertCircle`, `XCircle`
+- **Success**: `CheckCircle2`, `Check`
+- **Warning**: `AlertTriangle`, `AlertCircle`
+- **Info**: `Info`, `InfoCircle`
+- **Empty**: `Inbox`, `FileX`, `FolderOpen`
+- **Read-Only**: `Lock`
+
+### Icon Usage
+
+```tsx
+import { 
+  Loader2, 
+  AlertCircle, 
+  CheckCircle2, 
+  AlertTriangle, 
+  Info,
+  Lock 
+} from 'lucide-react'
+
+// Loading
+<Loader2 className="w-4 h-4 animate-spin" />
+
+// Error
+<AlertCircle className="w-4 h-4 text-red-600" />
+
+// Success
+<CheckCircle2 className="w-4 h-4 text-verde-claro" />
+
+// Warning
+<AlertTriangle className="w-4 h-4 text-yellow-600" />
+
+// Info
+<Info className="w-4 h-4 text-azul" />
+
+// Read-Only
+<Lock className="w-4 h-4 text-azul" />
+```
+
+## References
+
+- State styles: `frontend/src/styles/states.ts`
+- UI components: `frontend/src/components/ui/`
+- Icons: `lucide-react`
+
diff --git a/frontend/design-system/themes.md b/frontend/design-system/themes.md
new file mode 100644
index 0000000..0184fcb
--- /dev/null
+++ b/frontend/design-system/themes.md
@@ -0,0 +1,271 @@
+# Themes — Shema Design System
+
+## Overview
+
+The Shema Design System officially supports two visual modes: **Light Mode** ("Paper & Ink") and **Dark Mode** ("Night & Earth").
+
+## Light Mode — "Paper & Ink"
+
+**Metaphor:** Printed paper.
+
+### Colors
+
+```typescript
+// Base colors
+background: '#F6F5EB'        // Shema White (Cream) - Main background
+surface: '#FFFFFF'            // Pure White - Elevated surfaces
+primaryText: '#0A0703'        // Shema Black - Primary text
+secondaryText: '#3F3E20'     // Shema Dark Green - Secondary text
+borders: '#C5C29F'            // Sand - Borders
+```
+
+### CSS Variables
+
+```css
+:root {
+  --background: 48 29% 95%;      /* Shema White (Cream) */
+  --foreground: 30 43% 3%;       /* Shema Black */
+  --card: 0 0% 100%;             /* Pure White */
+  --card-foreground: 30 43% 3%;   /* Shema Black */
+  --primary: 22 97% 38%;         /* Telha */
+  --primary-foreground: 48 29% 95%; /* Shema White */
+  --secondary: 167 19% 60%;       /* Blue */
+  --secondary-foreground: 30 43% 3%; /* Shema Black */
+  --muted: 53 19% 70%;           /* Sand */
+  --muted-foreground: 60 34% 19%;  /* Dark Green */
+  --accent: 167 19% 60%;         /* Blue */
+  --accent-foreground: 30 43% 3%; /* Shema Black */
+  --destructive: 22 97% 38%;      /* Telha */
+  --destructive-foreground: 48 29% 95%; /* Shema White */
+  --border: 53 19% 70%;          /* Sand */
+  --input: 53 19% 70%;           /* Sand */
+  --ring: 22 97% 38%;            /* Telha */
+  --radius: 0.5rem;
+}
+```
+
+### Body Application
+
+```css
+body {
+  background: hsl(var(--background));  /* Shema Cream, not pure white */
+  color: hsl(var(--foreground));       /* Shema Black, softer than absolute black */
+  font-family: 'Montserrat', system-ui, sans-serif;
+}
+```
+
+> [!IMPORTANT]
+> Pure white must never be used as a page background. Use Shema White / Cream (#F6F5EB) to simulate paper and provide visual comfort.
+
+## Dark Mode — "Night & Earth"
+
+**Metaphor:** Organic night environment.
+
+### Colors
+
+```typescript
+// Base colors
+background: '#0A0703'        // Shema Black - Main background
+surface: '#0A0703'           // Shema Black with visible borders
+highlightSurface: '#3F3E20'  // Dark Green - Highlighted surfaces
+primaryText: '#F6F5EB'       // Shema White (Cream) - Primary text
+secondaryText: '#C5C29F'     // Sand - Secondary text
+borders: '#3F3E20'           // Dark Green - Borders
+```
+
+### Flutter Implementation Reference
+
+The dark theme is implemented in Flutter as follows (from `assets/references/app/components/themes/night-and-earth.dart`):
+
+```dart
+final shemaDarkTheme = ThemeData(
+  useMaterial3: true,
+  brightness: Brightness.dark,
+  fontFamily: 'Montserrat',
+  scaffoldBackgroundColor: colorShemaBlack,
+
+  colorScheme: const ColorScheme.dark(
+    primary: colorShemaTile,           // #BE4A01
+    secondary: colorShemaBlue,          // #89AAA3
+    tertiary: colorShemaGreenLight,     // #777D45
+    surface: colorShemaBlack,           // #0A0703
+    background: colorShemaBlack,        // #0A0703
+    onPrimary: colorShemaCream,         // #F6F5EB
+    onSurface: colorShemaCream,         // #F6F5EB
+    onSurfaceVariant: colorShemaSand,   // #C5C29F
+    outline: colorShemaGreenDark,       // #3F3E20
+  ),
+
+  cardTheme: CardTheme(
+    color: colorShemaBlack,
+    elevation: 0,
+    shape: RoundedRectangleBorder(
+      borderRadius: BorderRadius.circular(16),
+      side: const BorderSide(
+        color: colorShemaGreenDark,  // #3F3E20
+        width: 1.5,
+      ),
+    ),
+  ),
+
+  inputDecorationTheme: InputDecorationTheme(
+    filled: true,
+    fillColor: colorShemaGreenDark.withOpacity(0.2),
+    border: OutlineInputBorder(
+      borderRadius: BorderRadius.circular(12),
+      borderSide: const BorderSide(color: colorShemaGreenDark),
+    ),
+    hintStyle: const TextStyle(color: colorShemaSand),
+  ),
+);
+```
+
+### Web CSS Variables (Proposed)
+
+```css
+[data-theme="dark"] {
+  --background: 30 43% 3%;        /* Shema Black */
+  --foreground: 48 29% 95%;       /* Shema White (Cream) */
+  --card: 30 43% 3%;              /* Shema Black */
+  --card-foreground: 48 29% 95%;  /* Shema White */
+  --primary: 22 97% 38%;          /* Telha */
+  --primary-foreground: 48 29% 95%; /* Shema White */
+  --secondary: 167 19% 60%;       /* Blue */
+  --secondary-foreground: 48 29% 95%; /* Shema White */
+  --muted: 60 34% 19%;            /* Dark Green */
+  --muted-foreground: 53 19% 70%; /* Sand */
+  --border: 60 34% 19%;           /* Dark Green */
+  --input: 60 34% 19%;            /* Dark Green */
+  --ring: 22 97% 38%;             /* Telha */
+}
+```
+
+## Strict Restrictions
+
+- Do **NOT** use generic neutral greys.
+- Do **NOT** approximate Material Design dark palettes.
+- Dark interfaces must be composed **only** using Shema palette colors.
+
+Failure to follow these rules must be treated as a design defect, not a stylistic preference.
+
+## Theme Switching
+
+### Implementation (Future)
+
+#### 1. Add Theme Toggle
+
+```tsx
+import { useState, useEffect } from 'react'
+
+function ThemeToggle() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light')
+
+  useEffect(() => {
+    const root = document.documentElement
+    if (theme === 'dark') {
+      root.setAttribute('data-theme', 'dark')
+    } else {
+      root.removeAttribute('data-theme')
+    }
+  }, [theme])
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      {theme === 'light' ? <Moon /> : <Sun />}
+    </button>
+  )
+}
+```
+
+#### 2. Persist Preference
+
+```tsx
+useEffect(() => {
+  const savedTheme = localStorage.getItem('theme') as 'light' | 'dark' | null
+  if (savedTheme) {
+    setTheme(savedTheme)
+  } else {
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
+    setTheme(prefersDark ? 'dark' : 'light')
+  }
+}, [])
+
+useEffect(() => {
+  localStorage.setItem('theme', theme)
+}, [theme])
+```
+
+#### 3. Update Components
+
+All components should use CSS variables or Tailwind classes that support both themes:
+
+```tsx
+// ✅ Good - uses CSS variables
+<div className="bg-background text-foreground">
+  ...
+</div>
+
+// ✅ Good - uses Tailwind with dark:
+<div className="bg-white dark:bg-gray-900 text-preto dark:text-branco">
+  ...
+</div>
+
+// ❌ Avoid - hardcoded colors
+<div className="bg-[#F6F5EB] text-[#0A0703]">
+  ...
+</div>
+```
+
+## System Preference
+
+### Detect User Preference
+
+```tsx
+useEffect(() => {
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+  
+  const handleChange = (e: MediaQueryListEvent) => {
+    setTheme(e.matches ? 'dark' : 'light')
+  }
+  
+  mediaQuery.addEventListener('change', handleChange)
+  return () => mediaQuery.removeEventListener('change', handleChange)
+}, [])
+```
+
+## Theme Transitions
+
+### Smooth Animation
+
+```css
+* {
+  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+}
+```
+
+## Accessibility
+
+### Contrast in Both Themes
+
+- **Light Theme**: Minimum contrast of 4.5:1 for normal text
+- **Dark Theme**: Minimum contrast of 4.5:1 for normal text
+- Both themes must pass WCAG AA tests
+
+### Reduced Motion Preference
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    transition: none !important;
+  }
+}
+```
+
+## References
+
+- Brand guidelines: [AGENTS.md](./AGENTS.md)
+- Color system: [colors.md](./colors.md)
+- Flutter light theme: [assets/references/app/components/themes/paper-and-ink.dart](./assets/references/app/components/themes/paper-and-ink.dart)
+- Flutter dark theme: [assets/references/app/components/themes/night-and-earth.dart](./assets/references/app/components/themes/night-and-earth.dart)
+- Tailwind config: `frontend/tailwind.config.js`
+- CSS variables: `frontend/src/styles/main.css`
diff --git a/frontend/design-system/tokens/animations.json b/frontend/design-system/tokens/animations.json
new file mode 100644
index 0000000..8b1b5fa
--- /dev/null
+++ b/frontend/design-system/tokens/animations.json
@@ -0,0 +1,100 @@
+{
+    "keyframes": {
+        "fade_in": {
+            "name": "fade-in",
+            "keyframes": {
+                "0%": {
+                    "opacity": 0,
+                    "transform": "translateY(10px)"
+                },
+                "100%": {
+                    "opacity": 1,
+                    "transform": "translateY(0)"
+                }
+            }
+        },
+        "slide_in": {
+            "name": "slide-in",
+            "keyframes": {
+                "0%": {
+                    "opacity": 0,
+                    "transform": "translateX(-10px)"
+                },
+                "100%": {
+                    "opacity": 1,
+                    "transform": "translateX(0)"
+                }
+            }
+        },
+        "pulse_soft": {
+            "name": "pulse-soft",
+            "keyframes": {
+                "0%": {
+                    "opacity": 1
+                },
+                "50%": {
+                    "opacity": 0.7
+                },
+                "100%": {
+                    "opacity": 1
+                }
+            }
+        },
+        "bounce_subtle": {
+            "name": "bounce-subtle",
+            "keyframes": {
+                "0%": {
+                    "transform": "translateY(0)"
+                },
+                "50%": {
+                    "transform": "translateY(-3px)"
+                },
+                "100%": {
+                    "transform": "translateY(0)"
+                }
+            }
+        },
+        "celebrate": {
+            "name": "celebrate",
+            "keyframes": {
+                "0%": {
+                    "transform": "scale(1)"
+                },
+                "50%": {
+                    "transform": "scale(1.1)"
+                },
+                "100%": {
+                    "transform": "scale(1)"
+                }
+            }
+        }
+    },
+    "durations": {
+        "fast": "100ms",
+        "default": "200ms",
+        "medium": "300ms",
+        "slow": "500ms"
+    },
+    "easing": {
+        "ease_in": "ease-in",
+        "ease_out": "ease-out",
+        "ease_in_out": "ease-in-out"
+    },
+    "animations": {
+        "fade_in": {
+            "animation": "fade-in 0.3s ease-out"
+        },
+        "slide_in": {
+            "animation": "slide-in 0.3s ease-out"
+        },
+        "pulse_soft": {
+            "animation": "pulse-soft 2s ease-in-out infinite"
+        },
+        "bounce_subtle": {
+            "animation": "bounce-subtle 0.5s ease-in-out"
+        },
+        "celebrate": {
+            "animation": "celebrate 0.4s ease-in-out"
+        }
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/tokens/borders.json b/frontend/design-system/tokens/borders.json
new file mode 100644
index 0000000..3889f6f
--- /dev/null
+++ b/frontend/design-system/tokens/borders.json
@@ -0,0 +1,29 @@
+{
+    "width": {
+        "none": "0",
+        "default": "1px",
+        "md": "2px",
+        "lg": "4px"
+    },
+    "radius": {
+        "none": "0",
+        "sm": "0.375rem",
+        "md": "0.5rem",
+        "lg": "0.75rem",
+        "xl": "1rem",
+        "xxl": "1.5rem",
+        "full": "9999px"
+    },
+    "web": {
+        "button_radius": "0.5rem",
+        "card_radius": "0.75rem",
+        "input_radius": "0.5rem",
+        "badge_radius": "9999px"
+    },
+    "app": {
+        "button_radius": "16px",
+        "card_radius": "20px",
+        "input_radius": "12px",
+        "badge_radius": "9999px"
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/tokens/colors.json b/frontend/design-system/tokens/colors.json
new file mode 100644
index 0000000..9bf3bd9
--- /dev/null
+++ b/frontend/design-system/tokens/colors.json
@@ -0,0 +1,80 @@
+{
+    "brand": {
+        "primary": {
+            "name": "Telha",
+            "value": "#BE4A01",
+            "description": "CTAs, primary buttons, and active icons",
+            "usage": [
+                "shared"
+            ]
+        },
+        "secondary": {
+            "name": "Blue",
+            "value": "#89AAA3",
+            "description": "Supporting elements and subtle backgrounds",
+            "usage": [
+                "shared"
+            ]
+        },
+        "tertiary": {
+            "name": "Light Green",
+            "value": "#777D45",
+            "description": "Positive indicators and decorative elements",
+            "usage": [
+                "shared"
+            ]
+        }
+    },
+    "ui": {
+        "background": {
+            "name": "Shema White (Cream)",
+            "value": "#F6F5EB",
+            "description": "Default background for all screens",
+            "usage": [
+                "shared"
+            ]
+        },
+        "surface": {
+            "name": "White",
+            "value": "#FFFFFF",
+            "description": "Cards, inputs, and elevated surfaces",
+            "usage": [
+                "shared"
+            ]
+        },
+        "text": {
+            "primary": {
+                "name": "Shema Black",
+                "value": "#0A0703",
+                "usage": [
+                    "shared"
+                ]
+            },
+            "secondary": {
+                "name": "Shema Dark Green",
+                "value": "#3F3E20",
+                "usage": [
+                    "shared"
+                ]
+            }
+        }
+    },
+    "feedback": {
+        "success": {
+            "value": "#777D45",
+            "reference": "Derived from the Light Green brand color",
+            "usage": [
+                "web",
+                "app"
+            ]
+        },
+        "warning": {
+            "value": "#C5C29F",
+            "reference": "Sand",
+            "usage": [
+                "web",
+                "app"
+            ]
+        }
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/tokens/shadows.json b/frontend/design-system/tokens/shadows.json
new file mode 100644
index 0000000..39b4abc
--- /dev/null
+++ b/frontend/design-system/tokens/shadows.json
@@ -0,0 +1,17 @@
+{
+    "elevation": {
+        "none": "none",
+        "sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+        "md": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
+        "lg": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
+        "xl": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)",
+        "xxl": "0 25px 50px -12px rgb(0 0 0 / 0.25)"
+    },
+    "components": {
+        "card_default": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+        "card_hover": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
+        "button": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+        "button_hover": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
+        "modal": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)"
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/tokens/spacing.json b/frontend/design-system/tokens/spacing.json
new file mode 100644
index 0000000..2585535
--- /dev/null
+++ b/frontend/design-system/tokens/spacing.json
@@ -0,0 +1,35 @@
+{
+    "base": 4,
+    "scale": {
+        "xs": {
+            "value": "4px",
+            "flutter": 4
+        },
+        "sm": {
+            "value": "8px",
+            "flutter": 8
+        },
+        "md": {
+            "value": "16px",
+            "flutter": 16
+        },
+        "lg": {
+            "value": "24px",
+            "flutter": 24
+        },
+        "xl": {
+            "value": "32px",
+            "flutter": 32
+        },
+        "xxl": {
+            "value": "48px",
+            "flutter": 48
+        }
+    },
+    "layout": {
+        "web_container_max_width": "1200px",
+        "app_edge_padding": "20px",
+        "card_border_radius_web": "12px",
+        "card_border_radius_app": "20px"
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/tokens/typography.json b/frontend/design-system/tokens/typography.json
new file mode 100644
index 0000000..5d0a5df
--- /dev/null
+++ b/frontend/design-system/tokens/typography.json
@@ -0,0 +1,76 @@
+{
+    "fontFamilies": {
+        "primary": "Montserrat",
+        "secondary": "Merriweather"
+    },
+    "weights": {
+        "regular": 400,
+        "medium": 500,
+        "bold": 700
+    },
+    "web_scale": {
+        "h1": {
+            "fontFamily": "Montserrat",
+            "weight": 700,
+            "size": "32px",
+            "lineHeight": 1.2
+        },
+        "h2": {
+            "fontFamily": "Montserrat",
+            "weight": 700,
+            "size": "24px",
+            "lineHeight": 1.3
+        },
+        "h3": {
+            "fontFamily": "Montserrat",
+            "weight": 600,
+            "size": "20px",
+            "lineHeight": 1.4
+        },
+        "body": {
+            "fontFamily": "Montserrat",
+            "weight": 400,
+            "size": "16px",
+            "lineHeight": 1.5
+        },
+        "body_serif": {
+            "fontFamily": "Merriweather",
+            "weight": 400,
+            "size": "16px",
+            "lineHeight": 1.6,
+            "usage": "Reading contexts"
+        },
+        "caption": {
+            "fontFamily": "Montserrat",
+            "weight": 500,
+            "size": "12px",
+            "lineHeight": 1.5
+        }
+    },
+    "app_scale": {
+        "display": {
+            "fontFamily": "Montserrat",
+            "weight": 700,
+            "size": "28px",
+            "flutter_style": "headlineMedium"
+        },
+        "title": {
+            "fontFamily": "Montserrat",
+            "weight": 700,
+            "size": "20px",
+            "flutter_style": "titleLarge"
+        },
+        "body": {
+            "fontFamily": "Montserrat",
+            "weight": 400,
+            "size": "16px",
+            "flutter_style": "bodyMedium"
+        },
+        "label": {
+            "fontFamily": "Montserrat",
+            "weight": 500,
+            "size": "14px",
+            "flutter_style": "labelLarge"
+        }
+    }
+}
\ No newline at end of file
diff --git a/frontend/design-system/typography.md b/frontend/design-system/typography.md
new file mode 100644
index 0000000..4a67f14
--- /dev/null
+++ b/frontend/design-system/typography.md
@@ -0,0 +1,360 @@
+# Typography — Shema Design System
+
+## Font Families
+
+The typography system is defined in [tokens/typography.json](./tokens/typography.json), which is the authoritative source.
+
+### Montserrat — Primary Font (UI)
+
+**Usage**: Entire interface (buttons, navigation, labels, headings, forms)
+
+```css
+font-family: 'Montserrat', system-ui, -apple-system, sans-serif;
+```
+
+> [!IMPORTANT]
+> **Montserrat is exclusive for UI**. Use Montserrat for all interface elements: buttons, menus, navigation, card titles, form labels, badges, and any interactive element.
+
+### Merriweather — Secondary Font (Reading)
+
+**Usage**: Long-form text, biblical content, continuous reading
+
+```css
+font-family: 'Merriweather', Georgia, serif;
+```
+
+> [!IMPORTANT]
+> **Merriweather is exclusive for reading contexts**. Use Merriweather only for continuous reading text, especially biblical content and extensive passages.
+
+### Tailwind Configuration
+
+```javascript
+fontFamily: {
+  sans: ['Montserrat', 'system-ui', '-apple-system', 'sans-serif'],
+  serif: ['Merriweather', 'Georgia', 'serif'],
+}
+```
+
+### Hebrew Text Font
+
+For Hebrew text, use a serif font with RTL direction:
+
+```css
+.hebrew-text {
+  font-family: serif;
+  text-align: right;
+  direction: rtl;
+  font-size: 1.125rem; /* text-lg */
+  line-height: 1.75;    /* leading-relaxed */
+}
+```
+
+## Font Weights
+
+Available weights:
+
+| Class | Weight | Usage |
+|--------|------|-----|
+| `font-normal` | 400 | Default text, body, reading |
+| `font-medium` | 500 | Labels, badges, subtle emphasis |
+| `font-semibold` | 600 | Card titles, subtitles |
+| `font-bold` | 700 | Main headings, strong emphasis |
+
+## Type Scale
+
+### Web Scale
+
+| Style | Font Family | Weight | Size | Line Height | Usage |
+|-------|-------------|--------|------|-------------|-------|
+| `h1` | Montserrat | 700 | 32px | 1.2 | Main page titles |
+| `h2` | Montserrat | 700 | 24px | 1.3 | Section headings |
+| `h3` | Montserrat | 600 | 20px | 1.4 | Card titles, subsections |
+| `body` | Montserrat | 400 | 16px | 1.5 | Default UI text |
+| `body_serif` | Merriweather | 400 | 16px | 1.6 | Reading contexts |
+| `caption` | Montserrat | 500 | 12px | 1.5 | Labels, hints, badges |
+
+### App Scale (Flutter)
+
+| Style | Font Family | Weight | Size | Flutter Style |
+|-------|-------------|--------|------|---------------|
+| `display` | Montserrat | 700 | 28px | headlineMedium |
+| `title` | Montserrat | 700 | 20px | titleLarge |
+| `body` | Montserrat | 400 | 16px | bodyMedium |
+| `label` | Montserrat | 500 | 14px | labelLarge |
+
+## Tailwind Size Classes
+
+| Class | Size | Line Height | Usage |
+|--------|---------|-------------|-----|
+| `text-xs` | 0.75rem (12px) | 1rem | Small labels, badges, hints |
+| `text-sm` | 0.875rem (14px) | 1.25rem | Secondary text, descriptions, inputs |
+| `text-base` | 1rem (16px) | 1.5rem | Default body text |
+| `text-lg` | 1.125rem (18px) | 1.75rem | Hebrew text, highlights, subtitles |
+| `text-xl` | 1.25rem (20px) | 1.75rem | Card titles, section subtitles |
+| `text-2xl` | 1.5rem (24px) | 2rem | Page titles, main headers |
+| `text-3xl` | 1.875rem (30px) | 2.25rem | Hero titles, large titles |
+| `text-4xl` | 2.25rem (36px) | 2.5rem | Large headers (mobile hero) |
+
+## Line Height
+
+| Class | Value | Usage |
+|--------|-------|-----|
+| `leading-none` | 1 | Very compact headings |
+| `leading-tight` | 1.25 | Headings, headers |
+| `leading-snug` | 1.375 | Subtitles |
+| `leading-normal` | 1.5 | Default UI text |
+| `leading-relaxed` | 1.75 | Hebrew text, reading, long paragraphs |
+| `leading-loose` | 2 | Very spaced text |
+
+## Letter Spacing
+
+| Class | Value | Usage |
+|--------|-------|-----|
+| `tracking-tighter` | -0.05em | Large display headings |
+| `tracking-tight` | -0.025em | Normal headings |
+| `tracking-normal` | 0 | Default (most cases) |
+| `tracking-wide` | 0.025em | Labels, badges, uppercase |
+| `tracking-wider` | 0.05em | Spaced headers |
+| `tracking-widest` | 0.1em | Decorative headings |
+
+## Typography Hierarchy
+
+### Page Title
+
+```tsx
+<h1 className="text-2xl font-bold text-preto flex items-center gap-2">
+  <Icon className="w-5 h-5 text-telha" />
+  Page Title
+</h1>
+```
+
+**Font**: Montserrat Bold 24px, text-preto
+
+### Card Title
+
+```tsx
+<CardTitle className="text-xl font-semibold leading-none tracking-tight text-preto">
+  Card Title
+</CardTitle>
+```
+
+**Font**: Montserrat Semibold 20px, text-preto
+
+### Description
+
+```tsx
+<CardDescription className="text-sm text-verde">
+  Card or section description
+</CardDescription>
+```
+
+**Font**: Montserrat Regular 14px, text-verde
+
+### Body Text (UI)
+
+```tsx
+<p className="text-base text-preto leading-normal">
+  Application body text
+</p>
+```
+
+**Font**: Montserrat Regular 16px, text-preto
+
+### Reading Content (Biblical Content)
+
+```tsx
+<div className="font-serif text-base leading-relaxed text-preto">
+  <p>
+    In the beginning, God created the heavens and the earth...
+  </p>
+</div>
+```
+
+**Font**: Merriweather Regular 16px, leading-relaxed, text-preto
+
+### Secondary Text
+
+```tsx
+<p className="text-sm text-verde">
+  Secondary or descriptive text
+</p>
+```
+
+**Font**: Montserrat Regular 14px, text-verde
+
+### Labels and Hints
+
+```tsx
+<label className="text-sm font-medium text-preto">
+  Field Label
+</label>
+<span className="text-xs text-verde/60">
+  Hint or help
+</span>
+```
+
+**Font**: Montserrat Medium/Regular, text-xs or text-sm
+
+## Text Styles
+
+### Decoration
+
+```tsx
+// Underlined (links)
+<a className="underline underline-offset-4">Link</a>
+
+// Strikethrough
+<span className="line-through">Strikethrough text</span>
+
+// No decoration
+<span className="no-underline">No decoration text</span>
+```
+
+### Transformation
+
+```tsx
+// Uppercase
+<span className="uppercase">UPPERCASE TEXT</span>
+
+// Lowercase
+<span className="lowercase">lowercase text</span>
+
+// Capitalize
+<span className="capitalize">capitalized text</span>
+```
+
+### Alignment
+
+```tsx
+// Left (default)
+<p className="text-left">...</p>
+
+// Center
+<p className="text-center">...</p>
+
+// Right
+<p className="text-right">...</p>
+
+// Justified
+<p className="text-justify">...</p>
+```
+
+## Truncation and Overflow
+
+```tsx
+// Truncate with ellipsis
+<p className="truncate">Very long text that will be truncated...</p>
+
+// Break words
+<p className="break-words">Text that breaks long words</p>
+
+// Break all
+<p className="break-all">Text that breaks anywhere</p>
+```
+
+## Antialiasing
+
+The application uses antialiasing to improve font rendering:
+
+```css
+body {
+  font-smoothing: antialiased;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+## Font Features
+
+Advanced typographic features are enabled:
+
+```css
+body {
+  font-feature-settings: "rlig" 1, "calt" 1;
+}
+```
+
+- `rlig`: Required ligatures
+- `calt`: Contextual alternates
+
+## Text Colors
+
+### Primary Colors
+
+```tsx
+// Primary text (Shema Black)
+<p className="text-preto">Primary text</p>
+
+// Secondary text (Shema Dark Green)
+<p className="text-verde">Secondary text</p>
+
+// Muted text
+<p className="text-verde/60">Muted text</p>
+
+// Text on primary button
+<button className="text-white">Button</button>
+```
+
+### Semantic Colors
+
+```tsx
+// Success
+<p className="text-verde-claro">Success text</p>
+
+// Error
+<p className="text-red-600">Error text</p>
+
+// Warning
+<p className="text-yellow-600">Warning text</p>
+
+// Info
+<p className="text-azul">Informative text</p>
+```
+
+## Component Examples
+
+### CardTitle (Montserrat)
+
+```tsx
+<CardTitle className="text-xl font-semibold leading-none tracking-tight text-preto">
+  Card Title
+</CardTitle>
+```
+
+### CardDescription (Montserrat)
+
+```tsx
+<CardDescription className="text-sm text-verde">
+  Card description
+</CardDescription>
+```
+
+### Page Header (Montserrat)
+
+```tsx
+<div className="text-2xl font-bold text-preto flex items-center gap-2">
+  <Icon className="w-5 h-5 text-telha" />
+  Page Title
+</div>
+<p className="text-verde mt-1">Subtitle or description</p>
+```
+
+### Reading Content (Merriweather)
+
+```tsx
+<div className="prose prose-lg">
+  <p className="font-serif text-base leading-relaxed text-preto">
+    This is an example of long text for continuous reading. 
+    The Merriweather font is optimized for on-screen reading and 
+    provides a comfortable experience even with extensive texts.
+  </p>
+</div>
+```
+
+## References
+
+- Design tokens: [tokens/typography.json](./tokens/typography.json)
+- Brand guidelines: [AGENTS.md](./AGENTS.md)
+- Tailwind config: `frontend/tailwind.config.js`
+- Global styles: `frontend/src/styles/main.css`
+- UI components: `frontend/src/components/ui/`