Patterns

errors/README.kmd

Índice navegável (não-autoritativo) das specs de erro da Koder Stack. Cada conceito de erro — classes, severidade, identificadores, envelope, texto humano, captura, retenção, padrões de código — tem UMA spec dona. Este README mapeia "conceito → dono" para que ninguém reimplemente nem duplique.

errors/model.kmd

O envelope canônico, máquina-legível, de um erro na Koder Stack: os campos obrigatórios (dados mínimos exigíveis) e opcionais (dados complementares) de um objeto de erro, as regras para preencher os complementares, e o mapeamento para resposta HTTP (problem+json) que todo backend Koder emite e todo cliente parseia.

errors/reporting.kmd

Relatório de erros para todos os módulos Koder: toggle "Relatório automático" obrigatório em Settings (default OFF, ausência = desabilitado), botão "Reportar problema" sempre visível, grupos de dados A–G, contrato de privacidade (o que nunca capturar), retenção e acesso.

errors/taxonomy.kmd

Vocabulário canônico de erros da Koder Stack: o enum fechado de CLASSES (categorias funcionais — `DL`, `UP`, `AU`, `NW`, `DB`, `UI`, `IO`, `PM`, `VL`, `XX`), a definição semântica + regra de desempate de cada classe, a escala de SEVERIDADE (`fatal`/`error`/`warning`/`info`) e a classificação de RETRYABILITY.

errors/user-facing-messages.kmd

Toda mensagem de erro exibida a usuário final deve ter (1) texto humanizado em pt-BR/en-US, (2) botão "Ver detalhes" expandindo o erro técnico bruto, (3) ID único `<PRODUCT>-<CAT>-<CODE>-<SEQ>` para correlação com logs e suporte.

i18n/contract.kmd

Contrato cross-surface de internacionalização da Koder Stack: idioma padrão = locale do dispositivo, seletor de idioma em local canônico por surface (Flutter app, Web/landing, CLI, TUI, TV, Server-rendered HTML), persistência, fallback chain en-US, key-naming, validação por testes TDD.

i18n/leak-detection.kmd

Detection contract for "i18n leaks" — user-facing string literals

i18n/test-template.kmd

Template normativo de testes TDD pra validar conformidade com `specs/i18n/contract.kmd` em qualquer módulo Koder, qualquer surface (Flutter mobile/desktop/TV, Web, Server-rendered HTML, CLI, TUI).

identity/consent.kmd

Koder ID issues, validates, and revokes signed, scoped consent tokens.

identity/erasure-flow.kmd

identity/login-resolution-test-template.kmd

TDD test templates for the contract in `specs/identity/login-resolution.kmd`.

identity/login-resolution.kmd

How Koder ID (and any SDK or library that performs client-side pre-validation) resolves what the user typed in the "Email" field to the target user record.

identity/password-policy.kmd

The NCSC/NIST-aligned password rules for Koder ID — the ONLY surface in the Stack that accepts a user password, since Koder ID is the sole identity provider (auth/oauth-flow.kmd R1).

navigation/back-behavior.kmd

Back (Android <, iOS swipe, ESC desktop, browser back) **sempre** volta

patterns/admin-data-table.kmd

Canonical composition pattern for Koder admin tools that list typed records (Forge repo list, Kdrive folder browser, Hub publisher catalog, future Koder ID admin, etc.).

patterns/ai-agent-state-hooks.kmd

Framework-neutral state-machine contract for any AI chat / agent surface in a Koder product — message list, streaming state, append handlers, abort, retry, tool-call lifecycle.

patterns/ai-chat-surface.kmd

Six composable primitives for assembling an AI chat surface in any Koder product — Bubble, Sender, Suggestion, Attachment, Conversations, ThoughtChain.

patterns/ai-feature-visual-language.kmd

Canonical visual lexicon for distinguishing AI-driven surfaces from

patterns/ai-welcome-screen.kmd

First-message hero an AI chat surface renders when the user hasn't sent anything yet — mark + greeting + capability hint + 3-4 starter prompts that pre-fill the composer (do NOT auto-send).

patterns/approval-gate.kmd

A paused step that waits for an authorized human to approve or reject a pending action — a deploy/release gate, a content-moderation hold, a sensitive-operation sign-off.

patterns/audit-log.kmd

The immutable, filterable trail of "who did what, when" for a tenant — security/compliance events rendered as a sortable, searchable, exportable events table with a stable event model and tamper-evidence.

patterns/callout-card.kmd

Dismissible in-product nudge — illustration + heading + body + CTA — placed inside a primary surface (settings, dashboard) to surface a new capability without interrupting.

patterns/code-review.kmd

The pull-request review surface: a diff (diff-viewer) overlaid with threaded line comments, a review-decision flow (comment / approve / request changes), per-thread resolved/unresolved state, and a batched "pending review" submission.

patterns/confirmation-page.kmd

The receipt surface shown AFTER a user successfully completes a transaction or submission: a prominent success panel with a reference number, an explicit "what happens next" section, and confirmation that any follow-up (email/SMS) was sent.

patterns/content-overflow.kmd

What to do when content exceeds its container: truncate with an ellipsis + a way to see the full value (tooltip / expand), scroll a bounded region, or a "show more" reveal — and the wrap rules that decide which.

patterns/crud-page.kmd

The list → detail → edit scaffold for managing records of one entity: an admin data-table list with create/row actions, a read detail view, and a form-page editor with validation — plus the create and delete (confirmed) flows that connect them.

patterns/dashboard-page.kmd

The analytics/overview page scaffold: a scoped filter bar, a row of metric cards (the KPIs), and a grid of charts and small tables — read- first, with drill-downs to the detail surfaces.

patterns/deprecation.kmd

Canonical pattern for communicating a feature's deprecation — in-app

patterns/empty-state.kmd

Purpose-built UI for "no data yet" surfaces — illustration + heading + body + primary action.

patterns/error-page.kmd

The full-page error template (404 / 500 / permission / expired session): a plain-language message stating what happened, why, and how to recover, with an **embedded search** and recovery links so the user can get back on task instead of hitting a dead end.

patterns/feature-paywall.kmd

Two sibling sub-patterns: (a) **paywall** — what surfaces when a feature is gated by a paid tier the user hasn't subscribed to; (b) **permission restriction** — what surfaces when the user lacks the required role / scope.

patterns/form-page.kmd

A single editing surface with section-grouped fields and a sticky save/discard bar that appears when the form is dirty — the edit-a-record / settings page (as opposed to a step-by-step wizard).

patterns/form-validation.kmd

How a form tells the user what is wrong and how to fix it: inline validation on blur, a top-of-form error summary that links to each offending field with a *corrective* message (not just "invalid"), required/optional marking on the label, two-tier helper text, progress on long forms, and an explicit success confirmation.

patterns/inline-edit.kmd

Edit a single value in place — a click-to-edit field that swaps its read view for an input, commits on Enter/blur, and reverts on Esc — without navigating to a separate form.

patterns/onboarding.kmd

First-run guidance: a progressive product tour of chained coach-marks that introduces a surface the first time a user reaches it, always skippable and never-again-dismissable, with its seen-state persisted so it does not repeat.

patterns/one-thing-per-page.kmd

A form-design constraint: each page in a flow asks the user for ONE thing — one decision or one logically-grouped piece of information — with a single primary action.

patterns/report-page.kmd

The parameterized-report scaffold: a filter/parameter panel, a Run action, and a tabular and/or graphical result the user reads or exports (CSV/PDF/print).

patterns/task-list.kmd

Section-level overview for LONG, multi-part journeys split into named tasks, each carrying an explicit completion status and dependency gating.

patterns/vcs-activity-timeline.kmd

The chronological event stream on a code-hosting issue or pull request: comments interleaved with typed activity events (committed, labeled, assigned, referenced, closed, merged, reviewed), each with a semantic event icon/color, actor avatar, and relative timestamp.

patterns/visual-golden-widget.kmd

Canonical recipe for shipping byte-exact visual regression goldens for any single widget in any Koder UI surface (GTK4/Adwaita today; Flutter / web / Android extensions follow the same shape).

patterns/wizard-multistep.kmd

Linear or branching multi-step flow with per-step validation, step indicator, back-stack semantics, review step, and submit + error recovery.