Specifications

Public per-product manifest declaring which accessibility features the product supports — screen-reader, keyboard-only, captions, dynamic-type, reduced-motion, color-blind-mode, high-contrast, voice-control. Renders as a badge row on every product page in KDS + Hub. Modeled after Apple's App Store accessibility nutrition labels.

accessibility/nutrition-labels

Inventory of 8 archetypal personas covering the four ability axes (vision / motor / cognition / hearing) in the three permanence states (permanent / temporary / situational). Pairs the WCAG line- item auditing of accessibility/* with a humanized constraint set so designers reason about WHO breaks when a check is missed, not just what fails. Owner curates final names, day-in-the-life copy, and illustrations; this spec ships the structural scaffold + design constraints.

accessibility/personas

Catalog of UX/UI specs for AI and MCP (Model Context Protocol) components in Koder Stack. Companion implementation lives in `engines/sdk/koder_kit/lib/src/ai/` (ticket koder_kit#034). Umbrella tracker: ticket #099.

ai-ui/README

Vertical step list + per-step expand (tool call, args, result, duration) + plan-and-execute (plan pre-render before run) + time-travel replay + branching for multi-step AI agents. Companion to OpenTelemetry trace export via services/ai/trace. Consumed by Kortex, Kode, Bot agents.

ai-ui/agent-step-trace

Risk-tiered disclaimer mechanism for AI-generated content in Koder surfaces. Three tiers (label / label+modal / label+banner+confirmation) governed by `risk` field from gateway. Compliance basis: EU AI Act (entrando em vigor 2026+), LGPD transparency requirements, Microsoft Teams AI label spec, MIT Sloan labeling research. Companion policy `ai-content-disclosure.kmd` define quando/onde aplicar.

ai-ui/ai-disclaimer

Side panel split-screen (desktop/web) or bottom sheet (mobile) for AI-generated artifacts: code, KVG, markdown, HTML, mermaid diagrams. Live edit with diff context to AI on next message. Plugin renderer registry via koder_kit/plugin_registry. Claude Artifacts pattern.

ai-ui/artifact-panel

Baseline message bubble for any AI chat surface in Koder Stack: user vs assistant variants, mandatory AI disclaimer chip on assistant messages, copy/edit/regenerate/branch actions, multi-modal content hosting (text, code, image, citations, tool invocations).

ai-ui/chat-message-bubble

Footnote-style inline citations + hover/long-press preview cards + source list sidebar for AI responses backed by RAG or web search. Mandatory in any RAG/search-backed surface; compliance basis for EU AI Act transparency requirements on source disclosure.

ai-ui/citations

AI-generated code rendering with language detection, syntax highlight, copy button, optional run button, diff view, and defer-until-fence contract during streaming. Hosted by chat-message-bubble (#105) and artifact panel (#110). Shares syntax token vocabulary with themes/color-schemes.kmd.

ai-ui/code-block

Sidebar of past AI conversations: date-grouped (Today / Yesterday / Last 7 days / Older), search (literal + semantic), pin/archive/delete, auto-titulation, cross-device sync. Standard pattern in ChatGPT/Claude/ Gemini desktop apps.

ai-ui/conversation-history

Per-message badge + session header total + breakdown drawer for AI cost tracking. Token counts (in/out), monetary cost (configurable currency or Koder credits), model attribution, threshold alerts. Backend: services/ai/billing/.

ai-ui/cost-display

Copilot-style ghost text autocomplete in any Koder editor surface. Dimmed inline suggestion + Tab/→ to accept + Esc to discard + partial-accept (word/line). Debounce 300ms. Sandbox-isolated streaming from services/ai/gateway. Required for Kode editor, Kortex notebook, future Kanvas.

ai-ui/inline-suggest

UI for MCP server-initiated user input requests mid-tool-execution. Form mode (schema-driven) for inline fields; URL mode for external credentials. Completes MCP client capability surface alongside tool-invocation (#100), permission-prompt (#101), server-state (#104), and sampling-approval (#103).

ai-ui/mcp-elicitation

Consent gate UI before invoking MCP tools with side effects. Implements the SHOULD-level requirement from MCP spec (Tools Security): "Clients SHOULD prompt for user confirmation on sensitive operations." Required to ship any MCP-aware Koder client safely.

ai-ui/mcp-permission-prompt

UI for MCP server-initiated LLM completion requests delegated to the client (which has model + credentials + cost tracking). Two-step approval: pre-LLM (prompt) + post-LLM (response). Audit-logged. Closes MCP Section A of umbrella #099.

ai-ui/mcp-sampling-approval

Connection state visibility for every MCP server attached to a Koder client. Status chip (color-coded) + capabilities drawer + auto-reconnect + error-clear-on-success. Required for any debuggable MCP-aware product.

ai-ui/mcp-server-state

Visual indicator + arguments preview + result rendering for every MCP tool call executed by a Koder client. Implements the SHOULD-level UI requirement from MCP spec 2025-11-25 (Tools section): "Applications SHOULD provide UI that makes clear which tools are being exposed to the AI model, insert clear visual indicators when tools are invoked, and present confirmation prompts."

ai-ui/mcp-tool-invocation

Drawer to edit AI persistent memory: list/search/edit/delete items; audit log per item ("added by AI/user on X"); 4 categories matching Claude memory model (user/project/feedback/reference); export/import as markdown bundle. Right-to-erasure compliant. Required for any product with memory-aware AI.

ai-ui/memory-drawer

Dropdown/menu for choosing AI model mid-conversation. Capability chips (vision/tools/reasoning/long-context/voice), cost tier, recent-used, "auto" mode delegating to Kode Relay. Source-of-truth: registries/ai-model-recommendations.md. Required for Kortex/Talk power-user surfaces.

ai-ui/model-selector

Unified composer for text + image + file + voice input. Drag-and-drop + paste hook + attach button + mic button. Upload preview chips with MIME validation gated by model capabilities. Voice mode transition to voice-mode.kmd (#121). Required for any AI chat surface.

ai-ui/multimodal-input

Grid filterable de prompt templates: categoria + tag + author + provider. Preview, variable fill dialog (JSON Schema-driven; compat MCP prompts/list), favorite/star, share via Hub. Reuses koder_kit prompt input field semantics.

ai-ui/prompt-gallery

Token-by-token reveal of AI-generated text with cursor, Stop button, Retry, autoscroll, and incremental markdown rendering. Hosted by chat-message-bubble (#105) and any surface that streams gateway responses (inline-suggest, agent step trace, etc.).

ai-ui/streaming-text

Advanced power-user editor for system prompts (Claude Projects style / ChatGPT Custom GPTs). Markdown editor + templating helpers (variables, conditions, includes) + test-run sandbox + version history + share workspaces. Builds on services/ai/kortex/rules/ backend.

ai-ui/system-prompt-editor

Collapsible "Thinking..." block for reasoning models (Claude extended thinking, DeepSeek R1, OpenAI o-family). Separates chain-of-thought from final response. Hosted by chat-message-bubble (#105) and agent-step-trace (#108).

ai-ui/thinking-state

Fullscreen voice conversation mode UI: waveform (input/output color-coded), push-to-talk + always-on toggle, barge-in visual, mute, end session. Extends voice/wake-word.kmd with conversational mode semantics. Required for Talk product + future Kortex voice mode.

ai-ui/voice-mode

ai/agent-stream

ai/skill-format

Compare N products from URLs and render a comparison table (HTML or Markdown)

ai/skill-format-examples/compare-products/SKILL

Daily morning digest of N news sources, filtered by topic, delivered by email

ai/skill-format-examples/daily-news-digest/SKILL

Generate a single-page landing site from a product brief, deployed via Koder Hub

ai/skill-format-examples/landing-page-from-brief/SKILL

api/README

api/kds-public-api

Three canonical responsive layouts — list-detail, supporting-pane, feed — that every Koder product surface SHOULD instantiate instead of inventing one-off two-pane / multi-column / scroll geometries. Modeled after Material 3 adaptive foundations; covers phone / foldable / tablet / desktop.

app-layout/adaptive-layouts

4 canonical layout templates that cover ~90% of Koder UI screens. Each defines element placement, behavior across window-size classes, and accessibility contract. Material parity (`/foundations/layout/canonical-layouts/{feed,list-detail,supporting-pane}`); composed via `KoderCanonicalLayout` in koder_kit (planned).

app-layout/canonical-layouts

Material 3 Adaptive pane scaffolds — concrete APIs that materialize the canonical layouts (Feed/List-detail/Supporting/Custom) from canonical-layouts.kmd. ListDetailPaneScaffold, SupportingPaneScaffold, ThreePaneScaffold, NavigationSuiteScaffold. Auto-switches per window size class (Compact/Medium/Expanded/Large).

app-layout/pane-scaffolds

Consumo obrigatório de window-insets (status bar, nav bar, display cutout, IME) em todos os apps Koder. Implementação canônica: KoderSafeScaffold / KoderApp(safeArea: true) em engines/sdk/koder_kit v0.3.0+, Modifier.safeDrawingPadding() no Android nativo Compose, env(safe-area- inset-*) no web.

app-layout/safe-area

Posição canônica do avatar (KoderUserBadge) e demais elementos primários da topbar em todos os apps Koder, per surface (web, desktop tradicional, desktop browser/IDE, mobile, TV, CLI/TUI). Spec extensível pra cobrir search bar, primary nav, contextual actions, breadcrumbs em §N futuro — v0.1 normativa apenas pra avatar.

app-layout/topbar-placement

4 canonical window-size classes (Compact / Medium / Expanded / Large) that Koder UIs adapt to. Defines breakpoints in dp, detection per surface (Flutter, Web, native Android), and the expected layout responses at each class. Material parity (`/foundations/layout/applying-layout/window-size-classes`).

app-layout/window-size-classes

architecture/README

Convenção do bloco `audit:` em frontmatter YAML de specs e policies. Permite que a engine `koder-spec-audit` descubra dinamicamente quais módulos auditar contra cada spec/policy, sem hardcoding em comando. Toda spec/policy auditável segue este schema.

audit/frontmatter

Normative contract for every Koder component that authenticates end-users. Defines the OAuth2/OIDC flow against Koder ID (the sole identity provider, per koder-app/behaviors.kmd §1), the routing invariants (anonymous → Koder ID → dashboard, never anonymous form inside the component), the session lifecycle, and per-surface obligations. Applies to all surfaces (backend, mobile, desktop, tv, web, cli, tui) in every product, service, engine, and tool that has a user-facing UI. Consumed by SDKs (koder_kit Dart, koder_web_kit JS, engines/sdk/go) and by direct integrations (Koder Flow / Gitea fork, third-party OIDC clients).

auth/oauth-flow

Test template normativo pra implementações da `specs/auth/oauth-flow.kmd`. T1-T8 baseline behavioral (R3-R9 do contrato) + I1-I3 integração com Koder ID staging + N1-N4 negativos. Cada surface (backend/mobile/ desktop/tv/web/cli/tui) localiza os tests no path canônico per- framework. Cobertura por componente × surface rastreada em `registries/koder-id-auth-coverage.md`. Sibling do `identity/login-resolution-test-template.kmd` (que cobre o tier abaixo: resolução de identificador textual → handle/email).

auth/oauth-flow-test-template

Numeração de tickets no monorepo é sequencial por backlog no disco (`NNN-titulo.md`) e Jira-style prefixed (`<PREFIX>-NNN`) em referências cross-stack — commit messages, conversas, memórias, docs, outros tickets. Cada módulo com backlog declara seu prefix em `[backlog] prefix` no `koder.toml` e fica registrado em `meta/docs/stack/registries/ticket-prefixes.md`.

backlog/numbering

Nomenclatura canônica para executáveis: binário k<slug>, dir /opt/koder/<slug>/, D-Bus ID dev.koder.<slug>, symlink em /usr/local/bin/, .desktop file, aliases de compatibilidade. Cobre Flutter desktop, CLIs, multi-binary tooling, packaging .deb/.rpm/.kpkg. Android applicationId §11: dev.koder.<short_slug>, source-of-truth em koder.toml [android] application_id, exposto via catálogo da Store — clients NUNCA derivam por heurística.

binaries-and-cli/naming

cache-purge/contract

Canonical feature surface that every Koder bot chat channel (Telegram, WhatsApp, WebChat, Signal, Google Chat, Koder Chat, and future) must declare via `Channel.Capabilities()`. The matrix in `meta/docs/stack/registries/chat-channels-parity.md` audits the current state across the implemented channels.

chat-channels/capability-matrix

code/README

Catálogo cross-language de anti-patterns proibidos: eval/dynamic exec sem audit, magic numbers, god classes, deep nesting, mutable global state, singleton sem DI, catching genérico, null propagation, premature optimization, boolean trap. Linter config canônica per linguagem. Code review checklist top-10. Cross-link com APs específicos das per-language style specs.

code/anti-patterns

Filosofia e regras de comentários cross-language: WHY-not-WHAT por default; comentário só quando o motivo é não-óbvio; doc comments per-lang com formato canônico; TODO/FIXME/HACK com handle + ticket; commented-out code proibido; license header quando aplicável; module docstring quando obrigatório. Anti-patterns enumerados.

code/comments

Padrões cross-language pra tratamento de erro internal: errors-as-values vs exceptions per-lang, error wrapping/chaining, panic/abort policy, recovery boundaries (top-level, request, goroutine), regra "log XOR throw" (não fazer ambos), sentinel/typed errors, resource cleanup on error. Distinto de errors/user-facing-messages.kmd que cobre só texto exibido ao usuário.

code/error-handling

Design de funções/métodos cross-language: length limits (soft 30 / hard 60), argument count ≤4, early-return preferred sobre nested, default values per-lang, pure vs impure marking, side effects documentadas, cyclomatic complexity (soft 10 / hard 15).

code/functions

Padrão cross-language pra organização de imports/use/require: ordem canônica (stdlib → third-party → local), grouping por origem com linha em branco, aliasing convention (canônicos `np`, `pd`, `tf`), wildcard imports proibidos por default, ciclos proibidos, re-export patterns (prelude/index/lib.rs), side-effect imports documentados via comentário.

code/imports

Indentação canônica da Koder Stack: **2 espaços** em todas as linguagens (exceto Makefiles onde a sintaxe exige tab). Tabs proibidos; trailing whitespace proibido; final newline obrigatório. Line length 100 cols soft / 120 hard. EditorConfig template canônico versionado. CI gate via `editorconfig-checker`.

code/indentation

code/languages/README

Style guide específico de Koder Koda (`engines/lang/koda`): token grammar (base pra syntax highlighting), order de imports/declarações, doc comment style (#: triple-line), anti-patterns recorrentes (array aliasing writeback #750, implicit globals). Cross-link com policies da Koda (full-oop, full-self-hosted) e color-schemes (render-side dos tokens).

code/languages/koda-style

Convenções de naming cross-linguagem da Koder Stack: variables/funcs per idiom da linguagem, classes/types sempre PascalCase, constantes SCREAMING_SNAKE_CASE, files snake_case (códigos) ou kebab-case (.kmd), acronyms tratados como palavra (HttpClient não HTTPClient), booleans com prefixo is_/has_/can_/should_. Cross-language exceptions documentadas.

code/naming

Layout intra-módulo per linguagem: source root, tests location, fixtures/testdata, resources/assets, build artifacts (gitignored), generated code, config files, docs, examples. Tabela canônica per linguagem. Distinto de RFC-006 que cobre layout inter-módulo (sector → backend/app/engine/landing).

code/project-layout

Estrutura canônica de um comando `/k-*` em `meta/context/commands/`: frontmatter obrigatório (name, type, category, inputs, outputs, requires), seções obrigatórias (descrição, sintaxe, fases numeradas, regras, exemplos), declaração de cada fase como `deterministic` ou `analytical` (Code First), audit block opcional. Toda comando novo segue este schema.

commands/structure

Horizontal bar anchored at the top or bottom of an application surface — holds page title, primary navigation actions, and contextual actions. Material parity (`/components/top-app-bar` and `/components/bottom-app-bar`). Covers center/small/medium/large top bar variants and the bottom bar with FAB integration.

components/app-bars

Small visual marker attached to another element, signalling presence of notifications, unread count, or status. Material parity (`/components/badges`). Covers small (dot) and large (numeric) variants, anchoring rules, and overflow formatting.

components/badges

Persistent informational bar at the top of a content region — carries a message and 1-2 actions. Material parity (`/components/banners`). Distinguished from snackbars (transient) and dialogs (modal); banners stay until dismissed and never block interaction.

components/banners

Material 3 Expressive extension to base button groups (specs/components/buttons.kmd §Button groups). Adds 5 sizes (XS-XL), connected appearance (no gap + shared corners), shape/motion transformations on hover/press via spring. Strictly extends; baseline buttons.kmd remains valid.

components/button-groups-expressive

Button system — 7 variants (filled, tonal, outlined, text, elevated, icon, FAB), button groups, segmented buttons. Material parity (`/components/all-buttons`, `/components/buttons`, `/components/button-groups`). Covers anatomy, hierarchy, states, accessibility, and per-preset shape variation.

components/buttons

Card — a container of related content + actions, typically clickable as a whole. Material parity (`/components/cards`). 3 variants (elevated, filled, outlined), uniform anatomy, and rules for composition with images, lists, and feeds.

components/cards

Horizontally scrolling stack of items, optimized for browsing a collection at a glance. Material parity (`/components/carousels`). Covers Hero, Multi-browse, and Contained layouts; snap behavior; swipe gestures; accessibility for sequential item navigation.

components/carousels

Material 3 Expressive extension to base Hero carousel (specs/components/ carousels.kmd). Adds shape morphing between selected/peek items (square ↔ pill ↔ squircle) and gesture inertia driven by spring physics (motion.kmd R9.1). Connected to shape-library.kmd morph contract.

components/carousels-expressive

Canonical chart primitives — line / bar / stacked-bar / area / scatter / pie / donut / sparkline / graph (node-edge). Behavior contract; library binding is impl detail. Replaces ad-hoc chart-lib picks in Koder admin tools (Forge metrics, Hub analytics, Talk stats). Modeled after Ant Design G2/G6 + PatternFly + Material 3.

components/charts

Binary toggle in a multi-select context — user marks 0..N options. Material parity (`/components/checkbox/overview`). 18×18 px tap target wrapped in 48 px hit zone; 3 states (unchecked, checked, indeterminate); WAI-ARIA-compliant.

components/checkbox

Compact element representing an entity, attribute, or action — smaller than a button and used in groups. Material parity (`/components/chips`). Covers four canonical variants (assist, filter, input, suggestion) and their behaviors.

components/chips

Typeahead input + dropdown of filtered options with optional async loading, custom-value support, and multi-select variant. Replaces ad-hoc native `<select>` + JS combinations that vary in a11y across Koder products. Modeled after Duet, Polaris, Spectrum.

components/combobox

Admin-grade tabular component — sortable columns, multi-select with bulk actions, sticky header, pagination or virtualization, saved column views, expandable rows, inline edit. Modeled after Polaris IndexTable, PatternFly Table+Toolbar, Material 3 DataTable.

components/data-table

Accessible date picker — typed ISO entry + calendar grid for single date / date range / date+time. Replaces native `<input type="date">` (inconsistent across browsers) and ad-hoc third-party widgets. Modeled after Duet (LocalTapiola), Polaris, Spectrum.

components/date-picker

Modal interruption surface — basic dialog (centered modal), full-screen dialog (mobile/onboarding), and alert dialog (destructive confirm). Material parity (`/components/dialogs`). Includes scrim, focus trap, ESC handling, and accessibility contract.

components/dialogs

Thin line separating content groups within a single surface. Material parity (`/components/dividers`). Covers full-width, inset, middle (with text), and sub-header dividers. Defines when to use vs whitespace alone.

components/dividers

Material 3 Expressive FAB menu — successor of legacy "speed-dial". ToggleFloatingActionButton + N FloatingActionButtonMenuItems with staggered spring expansion + shape morph (FAB → "X"). Max 6 items (above → migrate to Navigation drawer).

components/fab-menu

One-shot tooltip-style component with arrow + title + body + optional CTA, surfaces a single feature discovery, persists per-user so it never re-shows after dismissal. Modeled after MongoDB LeafyGreen GuideCue.

components/guide-cue

Composite search + filter chips + saved views companion of data-table — handles full-text search, faceted filtering, multi- condition combination, URL serialization, persisted named views. Modeled after Polaris IndexFilters.

components/index-filters

Lightweight inline help — small "i" icon next to a label that, on hover / focus / tap, surfaces a short tooltip. Mid-weight between no help and the larger guide-cue. Modeled after MongoDB LeafyGreen InfoSprinkle.

components/info-sprinkle

Underlined term that, on hover / focus / tap, surfaces its definition in a popover without navigating away. Useful in jargon-dense surfaces (Koda lang docs, AI surfaces explaining "context window" / "tokens"). Modeled after MongoDB LeafyGreen InlineDefinition.

components/inline-definition

Vertical stack of related items, each row showing a label and optional leading / trailing elements. Material parity (`/components/lists`). Covers single-line, two-line, three-line rows; leading elements (icon, avatar, image, checkbox); trailing elements (icon, switch, metadata); and selection / nav behavior.

components/lists

Material 3 Expressive Loading indicator — distinct from Progress indicators. Morphing shape (Cookie → Burst → Flower → Cookie cycle) via spring physics. Used for actions < 5s; replaces most indeterminate circular spinners. Integrates with pull-to-refresh.

components/loading-indicator

Floating list of choices anchored to a trigger — opens on demand, closes after a choice or dismiss. Material parity (`/components/menus`). Covers dropdown (anchor button), context (long-press / right-click), submenu (cascading), and exposed dropdown menu (text field with selection list).

components/menus

Primary navigation surfaces for switching between top-level destinations — Navigation bar (bottom, mobile), Navigation rail (side, tablet), and Navigation drawer (side, desktop / wide). Material parity (`/components/navigation-bar`, `/components/navigation-drawer`, `/components/navigation-rail`). These three are ONE adaptive component family, picked by window-size class.

components/navigation

Country-aware phone input — country selector + locale-aware mask + ISO E.164 normalization on storage. Common need in signup / profile / SMS-verification flows across Koder products. Modeled after Base Web PhoneInput.

components/phone-input

Compound controls for selecting a date, time, date range, or date-time. Material parity (`/components/date-pickers` and `/components/time-pickers`). Covers docked vs modal date pickers, dial vs input time pickers, date ranges, locale rules, and keyboard navigation.

components/pickers

Visual feedback that an operation is in progress — linear (bar) or circular (spinner), determinate (known %) or indeterminate (unknown duration). Material parity (`/components/progress-indicators`).

components/progress-indicators

Single-select from N mutually exclusive options. Material parity (`/components/radio`). Use radio when N ≤ 5 and all options should be visible; use a dropdown/select for N ≥ 6.

components/radio-buttons

Full-screen / overlay search experience triggered from a search field — shows suggestions, recent queries, and live results as the user types. Material parity (`/components/search`). Distinguished from the static inline search bar (a text field with leading 🔍 icon).

components/search-view

Surface anchored to an edge of the screen, slidable to reveal secondary content — bottom sheets (mobile primary) and side sheets (tablet/desktop). Material parity (`/components/bottom-sheets` and `/components/side-sheets`). Covers modal vs standard, drag gestures, scrim, focus trap, and snap points.

components/sheets

Skeleton placeholder primitives — block / line / circle / image — that mirror the final content shape during load. Reduces perceived load time and avoids cumulative layout shift on content swap. Modeled after Cedar (REI), Material 3, Polaris, Carbon.

components/skeleton

Single-handle or range-handle control for selecting a numeric value along a continuous or discrete scale. Material parity (`/components/sliders`). Covers continuous vs discrete, single vs range, value label, step marks, and accessibility.

components/sliders

Transient feedback message at the bottom of the screen — confirms an action, optionally offers a single action (undo, retry). Material parity (`/components/snackbars`). Distinguished from banner (persistent) and dialog (modal).

components/snackbars

Material 3 Expressive composite button: primary action + separate menu trigger side-by-side, divided. Trailing chevron rotates + shape morphs when menu opens. 5 sizes × 4 styles. Anchored to host `buttons.kmd`.

components/split-button

ON/OFF toggle with immediate effect. Material parity (`/components/switch`). Distinct from Checkbox — switch implies "this changes state right now"; checkbox implies "I'm submitting this value with the form."

components/switch

Horizontal navigation within a single context — primary tabs (top of content) and secondary tabs (filter within tab). Material parity (`/components/tabs`). Includes scrollable tabs, swipe gesture, and accessibility contract.

components/tabs

Text input control — 2 variants (filled, outlined), single-line and multi-line, with label, helper text, error state, leading/trailing icons, character counter. Material parity (`/components/text-fields`).

components/text-fields

Material 3 Expressive Toolbars — substituem o legado Bottom App Bar. Two variants: docked (anchored bottom, 56dp) and floating (horizontal bottom-center OR vertical side, hide-on-scroll). Companion to FAB. Bottom app bar marked deprecated-in-expressive.

components/toolbars

Brief contextual label revealing the name or description of a UI element on hover, focus, or long-press. Material parity (`/components/tooltips`). Covers plain tooltips (label-only) and rich tooltips (multi-line + optional action).

components/tooltips

Ratified mechanical rules: capitalization, punctuation, numbers, brand-name handling, abbreviations, Oxford comma. Removes the per-PR "should this title-case or sentence-case?" debate. Modeled after LeafyGreen, Polaris, Carbon mechanics specs.

content/grammar-and-mechanics

Reading-level target (Flesch-Kincaid ≤ grade 8 for body; ≤ 6 for primary actions and onboarding) + 5 mechanical rules that drop cognitive load for non-native speakers and cognitively diverse users. Mirrors USWDS plain-language mandate.

content/plain-language

Persistent voice across all Koder surfaces (4 traits) + tone matrix varying by context (success / error / first-run / marketing / AI-generated). Sets the baseline that grammar-and-mechanics.kmd and plain-language.kmd then refine. Modeled after LeafyGreen, Mailchimp, Pajamas, USWDS.

content/voice-and-tone

data/README

Como exibir o nome do produto na barra de título de apps desktop Koder (Linux/macOS/Windows). Define formato canônico, casos de tela, sufixos (Untitled, dirty marker), e proibições.

desktop-apps/title-bar

Como apps desktop Koder devem tratar arraste e duplo-clique na barra de título. Define o contrato cross-platform (Linux/Windows/macOS), proíbe o "gesture-arena hijack" do duplo-clique nos botões, e pinta os widgets canônicos do `engines/sdk/koder_kit` (`KoderTitleBar` + `KoderTitleBarFreeArea`).

desktop-apps/title-bar-double-click

Native Android Jetpack Compose surface for Koder Design — the set of `@Composable` widgets, theming primitives, and packaging artifacts that mirror Koder's canonical components 1:1 for apps that want a native Android build (not via Flutter). Material parity (`/develop/android/jetpack-compose`).

develop/android-compose

Published support contract for kds.koder.dev and every koder_web_kit consumer. Defines Tier 1 (full support, Lighthouse-tested in CI), Tier 2 (best-effort), and Tier 3 (not supported, upgrade banner). Mirrors Cedar, GOV.UK, USWDS, Mozilla Protocol practice.

develop/browser-support

Every component page on `kds.koder.dev` ships code samples for multiple platforms — Flutter, Compose, SwiftUI, Web (HTML+CSS) — with a single toggle that switches all samples on the page in unison. Material parity (`/develop` cross-cutting).

develop/code-samples-toggle

Audit + ongoing contract that every page on `kds.koder.dev` is usable on mobile screens (Compact width < 600 dp). Material parity (`/develop` cross-cutting concern). Distinct from `specs/web-apps/responsiveness.kmd` (which covers Koder web apps); this spec covers the docs site itself.

develop/docs-mobile-responsiveness

Cross-platform onboarding index para `kds.koder.dev/get-started/`. Lista 6 surfaces (Flutter / Compose / SwiftUI / Web / XR preview / Wear preview), decision tree "qual surface?", quickstart copy-paste por surface, cross-link com koder-app/behaviors.kmd.

develop/get-started

Explicit workflow for moving a design from "ratified" (spec PR merged, Figma file finalized) to "shipped in product" (component preview matches spec, a11y audit passes, consumer ticket closed). Mirrors Cedar (REI) and Anvil (ServiceTitan) governance.

develop/handoff-process

Contract for in-IDE Koder Design support — spec preview on hover, token autocomplete, drift detection lint, and live theme preview inside the editor. Materializes ticket #021 as a normative spec plus follow-up impl tickets per IDE (VSCode, Zed, JetBrains future).

develop/ide-integration

Native iOS SwiftUI surface for Koder Design — the set of SwiftUI Views, modifiers, and environment objects that mirror Koder's canonical components 1:1 for apps that want a native iOS build (not via Flutter). Material parity (`/develop/ios`).

develop/ios-swiftui

Defines the named-subpart Overrides API every KDS component MUST expose so consumers can swap subparts (Root, Title, Body, Icon, …) without forking the component. Inspired by Base Web's Overrides API. Three override modes per subpart: `style`, `component`, `props`. Owner sign-off required before ratification; this spec LAYS OUT the contract for review.

develop/overrides-api

Every Koder UI surface — web, Flutter (mobile/desktop), Android native, iOS native, TV — MUST ship visual-regression TDDs covering four categories: (1) viewport overflow, (2) chrome overlap (browser URL bar / OS nav bar / IME / notch), (3) decorative-element proportion, and (4) sibling decorative collision (intra-container shapes piling onto each other at narrow viewports). Companion to specs/develop/docs-mobile-responsiveness.kmd (which covers structural responsiveness) and specs/app-layout/safe-area.kmd (which covers system chrome insets). This spec formalizes the TDD contract — what to generate, what to assert, which viewports, when to run.

develop/visual-regression-tdds

Wear OS 6 surface contract: EdgeButton (arc-shaped), Primary Layout slot-based, round-display optimization, watch-face color derivation. Spec preview — no Koder product consumes Wear OS today. Companion impl tracker: projects/koder-stack#155. SDK target: koder_kit_wear (futuro).

develop/wear-os

Material 3 XR canonical composables: Orbiter, SpatialPanel, SpaceToggleButton, UserSubspace, SpatialRow/Column/Box, AlertDialog spatialized. Strict extension to specs/develop/xr-preview.kmd (which retains status `preview`). Defines Koder naming + auto- spatialize defaults (TopAppBar, NavigationRail).

develop/xr-composables

Forward-looking spec for Koder Design on XR surfaces (Vision Pro, Quest, Android XR). Material parity (`/develop/extended-reality`). Defines the **preview** stage: scope, target platforms, layout primitives, input model, accessibility — not yet a shipping product surface. Status: `preview`.

develop/xr-preview

Tipos de documento gerados por categoria de objeto (Stack, Area, Sector, Module, Flow, RFC), requisitos de capa, regras de identidade visual e templates CSS para PDFs. Consultado no início da Fase 3 do `/k-housekeep`.

docs/generation

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. Implementação: KoderErrorReporter + KoderReportButton (engines/sdk/koder_kit). Backend: foundation/reporter. Nunca implementar localmente.

errors/reporting

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. Aplica-se a apps mobile/desktop/web, landing pages e CLI.

errors/user-facing-messages

Closed vocabulary of typeface roles, canonical CSS variables, hosting rules, weights, scale, fallback chain, and tests for typography in every Koder surface (web/landing, Flutter mobile/desktop, CLI/TUI). Self-hosted-first: webfonts ship as `.woff2` from the consumer's own origin; Google Fonts / jsDelivr / unpkg are forbidden.

fonts/typography

foundations/README

Koder UI is adaptive by default — single codebase serves phones, tablets, foldables, desktops, TVs, and web. Defines the principles, the 4 window-size classes, and the rules each layout uses to reflow. Material parity (`/foundations/adaptive-design`); complement to `app-layout/safe-area.kmd` (which covers insets) and `window-size-classes.kmd` (which covers the canonical breakpoints).

foundations/adaptive-design

How users + developers personalize Koder UI without leaving the design system. Material parity (`/foundations/customization`). Covers the axes available (style × scheme × density × motion × i18n × layout density × accessibility prefs), where each persists, who the audience is, and what's NOT customizable per surface.

foundations/customization

Element-level guidance for every Koder UI. Defines the unit cells of the design system — surfaces, text, controls, containers, and affordances — and the rules that compose them into pages. Material parity (`/foundations/designing/elements`); ratified as part of the Koder Design Visual facet expansion (#049.1).

foundations/elements

Foundation guidance on applying Material 3 Expressive without sacrificing usability. Emphasis ladder (5 levels × 5 vectors), decision matrix for when to emphasize, accessibility constraints (Expressive cannot break AAA contrast or reduced-motion contract).

foundations/usability

Voice, tone, vocabulary, and pattern guide for every user-facing string in Koder products. Material parity (`/foundations/content-design/style-guide/ux-writing-best-practices`). Extends `errors/user-facing-messages.kmd` (which covers error copy only) to all UI text — buttons, labels, hints, empty states, success messages.

foundations/ux-writing

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. Estende `specs/koder-app/behaviors.kmd §9` e `policies/language.kmd` adicionando posicionamento de UI e cobertura cross-surface.

i18n/contract

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). Define os 6 casos canônicos (T1-T6) com snippets concretos por surface. Material consumido por `/k-test-gen-i18n`.

i18n/test-template

Regras de geração de variantes de ícone por plataforma (Android mipmaps, iOS app icons, Linux hicolor, macOS .icns, Windows .ico, web favicons, Store listing). Codificadas em `dev/kicon`. Nunca desenhar PNGs por densidade à mão — rodar `kicon generate` a partir do master SVG.

icons/generation-targets

Padrão de ícones dos produtos Koder: 3D, forma = conceito, sem fundo. Contrato da master SVG (cores, dimensões, viewport, segurança de recorte). Variantes PNG por plataforma são geradas via `kicon generate`, nunca à mão.

icons/products

identity/erasure-flow

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. Gmail-style behavior: accept a bare local part (no "@") for accounts hosted under the tenant default domain; require a full email for external domains and third-party workspaces. The contract is single and applies to every surface: server-side OAuth UI, Flutter sign-in, web sign-in, CLI auth, KoderAuthGate, etc.

identity/login-resolution

TDD test templates for the contract in `specs/identity/login-resolution.kmd`. Each implementing surface (S1–S6) must have T1–T8 passing before release. Templates are written in language-portable pseudo-code; every implementation adapts to its native test runner (Go testing, Dart flutter_test, JS vitest, Bash smoke).

identity/login-resolution-test-template

interaction/README

Material 3 Expressive pull-to-refresh pattern: drag from top ≥ threshold triggers refresh; spring-snap release; loading indicator morphs during drag and persists until completion. Mandatory binding to `loading-indicator.kmd` for visual consistency.

interaction/pull-to-refresh

How users mark/unmark items as selected — single-select, multi-select, range-select, and the visual + accessibility contract for each. Material parity (`/foundations/interaction/selection`). Used by lists, tables, file pickers, chips, and any UI where selection is a primary action.

interaction/selection

Visual + behavioral contract for the 8 interaction states every Koder control passes through: enabled, hovered, focused, pressed, dragged, selected, activated, disabled. Material parity (`/foundations/interaction/states`). Token-level recipes for applying state overlays without per-control duplication.

interaction/states

Protocolo de comunicação entre apps Koder (cross-process, cross-app IPC). Mensagens, descoberta, autenticação, contratos. Implementação: engines/sdk/koder_ipc. Aplicável em qualquer integração app↔app local.

ipc/protocol

Especificação do formato KMD (Koder Markdown) — extensão de CommonMark com frontmatter YAML, cross-refs validados e blocos Koder Koda inline. Formato canônico de documentação da Koder Stack; consumido pelos editores Koder Dok e pelo render web do Koder Flow.

kmd/format

kode/config-format

kode/hooks

kode/skill-format

Comportamentos obrigatórios para todo app Koder (qualquer linguagem/ plataforma/canal): auth (Koder ID), branding, telemetria, auto-update, IPC, error reporting, i18n. Apps não-conformes não podem usar marca Koder, listar na Store ou integrar ao ecossistema. SDKs (koder_kit, engines/sdk/go, etc.) implementam o "how"; este spec é o "what".

koder-app/behaviors

Top-level `category` field in `koder.toml` placing each module in one of six canonical buckets. Drives the anti-drift heuristic for `policies/self-hosted-first.kmd` and unlocks per-category audit rules. Defined by `policies-RFC-002-self-hosted-first.md` Phase 4.

koder-toml/category

Especificação do formato `.kpkg` (pacote universal da Koder Hub): estrutura ZIP+bootstrap, kpkg.toml, plataformas suportadas, assinatura, export targets. Status: Normative (v0.1.0 Draft). Consultar ao trabalhar com `platform/kpkg` ou ao gerar pacotes para a Koder Hub.

kpkg/format

Universal open vector format for the Koder Stack: 2D, animation, and 3D in a single self-contained document. Layered profile model (Core → Motion → Solid) lets renderers declare conformance progressively. Self-hosted-first: no external CDN refs, no proprietary dependencies, fully editable in Koder Dok and rasterizable by kicon. This document is the v0.1 proposal — scope and primitives are open for redesign before ratification.

kvg/format

Formato canônico de arquivos `.kz` gerados por `kzip`, o compactador da Koder Stack. Uma única extensão cobre todos os modos (single-file, multi-file tar, diretório); dispatch é por magic bytes, não por sufixo. Durante o bootstrap (v1), o formato é compatível byte-a-byte com o repositório restic v0.18.x — single source of truth. Divergências futuras requerem bump de versão major + ticket explícito + nota de incompatibilidade.

kzip/format

Estrutura, seções e deploy das landing pages das Áreas da Koder Stack (foundation/, suite/, dev/, vertical/ e demais Áreas L1). Distinto de landing de produto (specs/landing-pages/products.kmd).

landing-pages/areas

Estrutura e deploy de landing pages de **catálogo** (`platform.koder.dev`) — listagem filtrável de produtos. Distinto de landing institucional e landing de produto.

landing-pages/catalog

Botão Download em landings de produto Koder: sempre via `<koder-download-button slug="…">` do `engines/sdk/koder_web_kit` v0.2+. URL canônica do CTA: `hub.koder.dev/apps/<slug>`. Nunca hand-roll link direto pra Flow release, Store home ou hosted-file download.

landing-pages/download-button

Estrutura e deploy de landing pages **institucionais** (`www.koder.dev`, `company.koder.dev`) — marca Koder, não produto. Distinto de landing de produto, área, sector ou catálogo.

landing-pages/institutional

Estrutura, IA, pipeline de render, deploy e governança do portal público de documentação da Koder Stack em `meta.koder.dev`. Renderiza o conteúdo de `meta/docs/{stack,ia,cryptography,blockchain}/` como HTML estático navegável, com nav hierárquico por tipo de documento (RFC, spec, policy, registry, module, runbook, compendium), search client-side, theme light/dark, i18n EN/PT. Distinto de landings de produto, área, sector, institucional, catálogo, packages e specs — é um **portal-indexador de documentos**, não uma landing-vendedor.

landing-pages/meta

Estrutura, meta tags Open Graph + Twitter Card, e composição da OG image para páginas de pacote individual no Koder Hub (`hub.koder.dev/apps/{slug}`, `/skills/{slug}`, `/bundles/{slug}`). Garante que sharing via WhatsApp/Facebook/Twitter/etc. mostre ícone + nome + descrição do pacote, não thumbnail genérico.

landing-pages/packages

Estrutura, seções, OG image e deploy de landing pages de produtos Koder. HTML monolítico, sem deps externas, en-US. Inclui padrão canônico de URL para web apps (<produto>.koder.dev — nunca app.<produto>.koder.dev) e fluxo OAuth callback. Regra de privacidade: zero links pra código-fonte.

landing-pages/products

Estrutura e deploy de landing pages de **Sectors** (sub-divisões de Área que agrupam módulos relacionados). Distinto de landing de Área (mais alto) e landing de produto (mais granular).

landing-pages/sectors

Estrutura, seções, OG image e deploy de landing pages de specs ou formatos abertos da Koder Stack — KVG, KPKG, KMD, RFCs públicas, e análogos. Análogo das landings de produto, mas com seções apropriadas a documentação normativa (status, abstract, design philosophy, profiles, versioning) em vez de marketing (comparativo, FAQ, CTA de download). HTML monolítico, sem deps externas, en-US, sem links ao repositório de código.

landing-pages/specs

Contrato cross-surface para gravação e reprodução de áudio em apps Koder (não-voice). Toggles em Settings (`media.audio.mic`, `media.audio.playback_in_background`); defaults seguros; codecs canônicos (Opus/AAC/MP3 in; Opus out via kodec); widgets `KoderAudioPlayer` + `KoderAudioRecorder` em `engines/sdk/koder_kit`. Recording indicator obrigatório. Upload size cap 100 MB. `<APP>-AUDIO-*` error map. **Relação com voice:** `specs/voice/wake-word.kmd` cobre wake-word + Talk Mode (ouvir o usuário ativamente, sub-domínio). Este spec cobre áudio genérico (tocar/gravar como mídia). Mic permission é compartilhada; voice toggles continuam separados em Settings.

media/audio

Contrato cross-surface para seleção, preview, e OCR de documentos em apps Koder (PDF, DOCX, MD, KMD, TXT, ODT). Toggles em Settings (`media.document.ocr`); defaults seguros; widgets `KoderDocumentPicker` + `KoderDocumentPreview` + `KoderOcrButton` em `engines/sdk/koder_kit`. OCR roda local-first via tesseract ou serviço Koder (`services/ai/ocr` quando disponível) — terceiros proibidos. Upload size cap 50 MB. `<APP>-DOC-*` error map. **Bridge com `image.kmd`:** captura via câmera retorna `KoderImageRef`; OCR vira o passo seguinte (image → text) e o resultado é tratado como document.

media/document

Contrato cross-surface para captura, seleção e preview de imagens em apps Koder. Toggles de privacidade (`media.image.camera`, `media.image.gallery`) em Settings, defaults seguros (tudo OFF até o primeiro use ativar via prompt), formatos canônicos (JPEG/PNG/WebP/AVIF in; JPEG/PNG out), e widgets compartilhados `KoderImagePicker` + `KoderImagePreview` + `KoderImageCropper` em `engines/sdk/koder_kit`. EXIF stripping obrigatório em upload por default. `<APP>-IMAGE-*` error map. Cross-link com `specs/media/video.kmd` (camera permission compartilhada) e `specs/multi-tenancy/contract.kmd` (storage path prefix).

media/image

Contrato cross-surface para captura, playback e screen-capture de vídeo em apps Koder. Toggles de privacidade (`media.video.camera`, `media.video.screen`, `media.video.mic`) em Settings; defaults seguros (tudo OFF até prompt do SO); codecs canônicos (H.264/HEVC/AV1/VP9 in via kodec; H.264 + AAC out); widgets `KoderVideoPlayer` + `KoderVideoRecorder` + `KoderScreenCapture` em `engines/sdk/koder_kit`. Recording indicator obrigatório quando capture ativo. Upload size cap 500 MB. `<APP>-VIDEO-*` error map.

media/video

messaging/cross-service-events

multi-tenancy/contract

Fórmula do Brand score (Type/Pron/Son/Mem), bandas de rating, checklist de aplicação e alvos por categoria. Implementado em `tools/namer` (https://namer.koder.dev). Este spec é a fonte normativa da lógica.

naming/brand-score

Forms of reference for every Koder Stack component: type, display name, bare name, slug, path, and aliases array. Defines the regex per form, the prefix rule (Koder vs no-Koder), and global uniqueness. Registry lives at meta/docs/stack/registries/component-names.md and is CI-checked by `koder-spec-audit naming`.

naming/forms

Back (Android <, iOS swipe, ESC desktop, browser back) **sempre** volta tela por tela na pilha do Navigator; só minimiza/fecha no root. Implementação canônica: KoderBackScope(enableSystemExitAtRoot: true) em engines/sdk/koder_kit v0.4.0+.

navigation/back-behavior

DSL compacta para hierarquias organizacionais (pessoas, cargos, vagas, multi-empresa, vínculos de emprego). Formato canônico de import/export do `platform/kompass` (kompass-RFC-001).

orgml

Protocolo de handshake para pareamento peer-to-peer entre dispositivos do mesmo dono na Koder Stack (Kode CLI, Kanvas, Talk, Drive, etc.). Define discovery via mDNS/bluetooth, key exchange (Noise XX), confirmação visual cross-device e armazenamento da relação no Koder Keys.

pair/handshake

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.). Stacks the primitive `data-table` and `index-filters` together with a standard toolbar (density / column visibility / export) and page shell. Ratified by `rfcs/design-RFC-008-pro-opinionated-wrappers.kmd` as Option C (recipe pattern, not bundled Pro component) — every admin surface composes the primitives following this spec.

patterns/admin-data-table

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. Companion to patterns/ai-chat-surface.kmd (which ratifies the 6 primitives); this spec ratifies the state machine driving them. Modeled after Ant Design X `useXAgent` / `useXChat`.

patterns/ai-agent-state-hooks

Six composable primitives for assembling an AI chat surface in any Koder product — Bubble, Sender, Suggestion, Attachment, Conversations, ThoughtChain. Modeled after Ant Design X, GitLab Duo Chat, ChatGPT / Claude desktop apps. Pairs with the AI visual language spec for marks + colors.

patterns/ai-chat-surface

Canonical visual lexicon for distinguishing AI-driven surfaces from deterministic UI: AI mark (sparkle ⟡), AI accent token, animated border on AI-generated content, progressive-reveal cursor on streamed text, mandatory non-determinism disclosure microcopy. Modeled after MongoDB LeafyGreen AI branding, GitLab Pajamas Duo, Atlassian Rovo.

patterns/ai-feature-visual-language

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). Distinct from generic empty-state (#063) by anatomy and intent. Modeled after Ant Design X Welcome + ChatGPT / Claude / Gemini first-run.

patterns/ai-welcome-screen

Dismissible in-product nudge — illustration + heading + body + CTA — placed inside a primary surface (settings, dashboard) to surface a new capability without interrupting. Distinct from banners (status) and modals (interruption). Modeled after Polaris CalloutCard.

patterns/callout-card

Canonical pattern for communicating a feature's deprecation — in-app banner with sunset date, alternative path, migration guide link. Removes the "surprise removal" failure mode that erodes user trust. Modeled after MongoDB LeafyGreen end-of-life pattern.

patterns/deprecation

Purpose-built UI for "no data yet" surfaces — illustration + heading + body + primary action. Treats absence-of-data as a first-class UX moment, not a fallback. Modeled after Polaris (Shopify) EmptyState and Evergreen (Segment) empty-state catalogue.

patterns/empty-state

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. Modeled after MongoDB LeafyGreen FeatureWalls.

patterns/feature-paywall

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). Established 2026-05-24 in `engines/sdk/koder_kit_gtk` across three iterations (KKGTK-002 R1+R2+R3a, registries #647-#653). Companion to `specs/develop/visual-regression-tdds.kmd § R1 Category C` (the normative test category) — this pattern is the **how**.

patterns/visual-golden-widget

Linear or branching multi-step flow with per-step validation, step indicator, back-stack semantics, review step, and submit + error recovery. Common in onboarding, provisioning, data import. Modeled after PatternFly Wizard.

patterns/wizard-multistep

postgres-compat/kdb-gateway-v0.0.13-vs-pg17-pgdump

postgres-compat/perf-baseline-vs-pg17

postgres-compat/pg-dump-v17

privacy/posture-schema

Formato canônico de README dos produtos Koder: seções obrigatórias, ordem, badges, links, idioma (en-US), regras de privacidade. Aplicável a todo módulo com README público no monorepo.

readmes/products

Formatos canônicos de pacote por plataforma (.deb, .rpm, .apk, .AppImage, .kpkg, .msi, .dmg). Regras de publicação, naming dos assets com nome fixo, conteúdo mínimo. Distinto de `policies/releases.kmd` (workflow de release) e `specs/kpkg/format.kmd` (formato do .kpkg).

releases/packaging

Convention for declaring multi-phase migration plans in RFC frontmatter so that `koder-spec-audit rfc-phase-pickup` can open backlog tickets automatically when each phase becomes eligible. Defined by `policies-RFC-003-rfc-phase-pickup.md`; this spec is the normative schema reference for the field.

rfc-frontmatter/phases

Convenção mestre de tela Settings em apps Koder: hierarquia canônica de grupos, ordem fixa, registro de cross-cutting settings (qual grupo, qual posição, qual controle, default state, persistence key), estrutura do tile (label/control/helper/icon) e widget SDK obrigatório (`KoderSettingsTile` em Flutter, `<koder-settings-tile>` em Web). Toda spec de feature cross-cutting que precisa de toggle em Settings registra-se aqui em vez de inventar tile próprio.

settings/patterns

EU profile (`?jurisdiction=eu`) of the Koder Signer service per `rfcs/signing-RFC-001-multi-jurisdiction.kmd`. Covers eIDAS levels SES / AdES / QES, the EU LOTL trust source, qualified TSA selection, and per-level conformance checks. STUB — placeholder opened in signer#013 (wave C, 2026-05-23) so the spec slot exists in the registry; full normative content lands when wave D begins (see RFC §Phasing).

signing/eidas

US profile (`?jurisdiction=us`) of the Koder Signer service per `rfcs/signing-RFC-001-multi-jurisdiction.kmd`. Covers the two ESIGN levels (simple / AATL), Adobe AATL trust bundle, intent metadata requirement, and optional NIST 800-63 IAL/AAL declaration for federal interactions. STUB — placeholder opened in signer#013 (wave C, 2026-05-23); full normative content lands when wave F begins (see RFC §Phasing).

signing/esign

Normative contract for the Koder Signer service (`services/crypto/signer/`) covering ICP-Brasil digital signature: supported formats (PAdES, CAdES, XAdES), signature policies (AD-RB, AD-RT, AD-RV), hardware token integration (A3 via PKCS#11), file certificate (A1 PFX) loading, certificate chain validation, timestamp authority (TSA) interaction, and revocation checking (CRL + OCSP). Applies to every Koder component that needs digital signature with legal validity in Brazil (per MP 2.200-2/2001 art. 10 §1º). Other Koder components consume Signer via REST/gRPC, never reimplementing PKI primitives locally (per `policies/reuse-first.kmd`).

signing/icp-brasil

snapshots/manifest

Canonical 8-cue vocabulary for UI audio in Koder products (focus / hover / press / success / error / notify / voice-wake / voice-end), with timbre family, token format, and mute contract. Pairs with voice/wake-word.kmd (handles voice-channel sound) and errors/user-facing-messages.kmd (handles error-channel pairing). Owner curates final timbre + .wav samples; Web Audio API synthesized cues ship as slice 1.

sound/vocabulary

testing/auto-heal-selectors

Matriz de aplicabilidade — quais categorias de teste fazem sentido para cada tipo de componente (`app/`, `backend/`, `engine/`, `cli/`, `landing/`, `tui/`, `tv/`, `sdk/`). Consultada por `/k-test` na Fase 2 para decidir quais geradores acionar por padrão.

testing/coverage-matrix

Every KDS-spec'd component MUST emit Open UI Automation (OUIA) attributes (`data-ouia-component-type`, `data-ouia-component-id`, `data-ouia-safe`) on its root element so test frameworks (Playwright, Cypress, Selenium, Flutter integration tests) have a stable selector contract that survives DOM refactors and styling churn.

testing/ouia-test-hooks

Catálogo completo das categorias de teste reconhecidas na Koder Stack — vocabulário fechado, com sinônimos da indústria, escopo, output dir e comando `/k-test-gen-*` correspondente. Ponto de partida para `k-test`, `k-test-run`, `k-test-doc` e `coverage-matrix.md`.

testing/taxonomy

Two additional theme modes alongside Verge light/dark — `color-blind` (deuteranopia-safe palette swap) and `low-vision` (text size +20%, font-weight ≥500, contrast floor AAA). User opt-in via Settings; persisted in `koder.a11y_mode`. Mirrors Duet (LocalTapiola) practice.

themes/a11y-modes

Subset of design tokens flagged as brand-mandatory — must NEVER be overridden by a product preset or downstream consumer. Verge default tokens are overridable per product; brand-mandatory tokens (Koder logomark hue, primary brand-mark hex, official typography roles) are inherited from `meta/brand/koder-design/palette/mandatory/`. Modeled after NSW DS brand-compliance badge convention.

themes/brand-mandatory-tokens

How tenants + users customize the Koder color system beyond preset picking — per-role overrides, brand color injection, accessibility presets, custom error/warning hues. Material parity (`/styles/color/advanced/overview`). Read after `color-schemes.kmd` + `color-roles.kmd`; this spec covers the escape hatches.

themes/color-customization

Generate a complete Koder color scheme from a single seed color — user-supplied (brand) or extracted from a wallpaper / hero image. Material parity (`/styles/color/dynamic/user-generated-source`, aka "Material You"). Output: 12 canonical color-schemes presets' worth of tokens derived algorithmically from one input.

themes/color-dynamic

Catalog of color role exports per platform (CSS custom properties, Dart const, Compose ColorScheme, SwiftUI Color, Figma Variables). Material 3 parity (`m3.material.io/styles/color/resources`). Per-preset per-theme (light + dark) copy-paste blocks. Single source of truth for what `color-roles.kmd` semantic roles render as per surface.

themes/color-resources

Semantic color role taxonomy — the mapping from concrete tokens (bg, surface, accent, error, etc.) to the UI elements that use each. Material parity (`/styles/color/roles`). Companion to `themes/color-schemes.kmd` (which defines the actual colors) and `foundations/elements.kmd` (which says which family uses which role).

themes/color-roles

Catálogo canônico de **esquemas de cor** (paletas) da Koder Stack — terceiro eixo da matriz visual (`ui-style × light-dark × color-scheme`), ortogonal aos dois primeiros. Define vocabulário semântico de tokens (bg, fg, accent, error, syntax_*, ansi_*) e ≥10 presets canônicos (default Koder neutros + Solarized, Dracula, Nord, Gruvbox, Tokyo Night, Monokai, One, Catppuccin, High Contrast). Cada preset declara hex pra cada token semântico, AAA contrast validado, e variantes light/dark quando aplicável. Cross-render: o mesmo preset aplica em UI, syntax highlighting, e terminal palette.

themes/color-schemes

Three canonical page-level density modes (compact / default / comfortable) with token deltas, accessibility floor, persistence pattern, and multi-tenant override rules. Density scales Verge spacing + typography tokens uniformly through CSS custom property cascade, so consumers opt in through a single attribute on the document root.

themes/density

12-color expressive palette for Koder marketing, landing illustration, blog headers, and social posts — distinct from Verge UI palette (Adwaita 1:1) which governs in-product surfaces. Editorial primaries are HCL-rotated derivatives of Verge primaries so brand + product feel kin. Tracker: meta/brand/koder-design#001. Source-of-truth files live under meta/brand/koder-design/palette/editorial/.

themes/editorial-palette

Elevation system — 6 levels (0-5) expressed as shadows + tonal surface colors. Material parity (`/styles/elevation`). Defines WHEN to use which level (per element family) and HOW to render it (shadow + tonal overlay per theme mode).

themes/elevation

Companion to `specs/themes/verge.kmd`. Documents every design decision made for the Koder visual identity: palette, radius, spacing, typography, and per-component decisions from form elements through surfaces. Also tracks which decisions are still deferred. This is the "rationale" document; `verge.kmd` is the normative token spec.

themes/koder-style

Tema claro/escuro para todas as UIs Koder (web, Flutter mobile/desktop, TV, landing pages): comportamento padrão pós-instalação (ThemeMode.system), persistência da escolha do usuário, anti-flash, CSS vars.

themes/light-dark

Translucent surface tokens for floating UI (acrylic) and window-chrome backgrounds (mica). Adds depth via backdrop-filter blur with a documented opaque fallback for browsers/compositors without the API. Material parity gap (Fluent 2 ships these; Material 3 uses opaque elevation tokens — Koder offers both vocabularies).

themes/materials

Motion in Koder UI — index over 3 sub-specs: physics (principles + springs + reduced-motion), easing-duration (tokens), transitions (pattern catalog). Material parity broken into 3 discoverable pages.

themes/motion

Duration tokens (5) and easing curves (5) for every deterministic Koder UI animation. The "how long + what curve" half of Motion (physics, springs, and reduced-motion contract live in `physics.kmd`).

themes/motion/easing-duration

Motion physics for Koder UI — principles, performance budget, forbidden patterns, reduced-motion contract, and spring tokens (Material 3 Expressive). The "how it moves" half of Motion (the "how long" half lives in `easing-duration.kmd`).

themes/motion/physics

Cursor-tracking radial highlight on hoverable surfaces. Pointer-only signature interaction inherited from Fluent. Disabled by reduced-motion + skipped on touch surfaces (Koder mobile uses ripple per Material).

themes/motion/reveal

Transition pattern catalog for Koder UI — 7 canonical patterns (fade, scale, slide, container transform, shared axis, push/pop, cross-fade), per-state motion, and page-level transitions. Consumes duration + easing tokens from `easing-duration.kmd` and spring tokens from `physics.kmd`.

themes/motion/transitions

Taxonomy organizing the Koder Design UI Style presets into 5 families: **Era**, **Brand**, **Mood/Aesthetic**, **Cultural**, and **Domain**. Defines the canonical preset slug grammar, the family-tagged grouping shown in the preset picker, and the expansion roadmap from 19 (today) → ~35-45 (target). Companion spec for ticket #030.

themes/presets-families

Shape system — corner-radius scale, when to use which radius, and per-preset variation rules. Material parity (`/styles/shape/overview-principles`). Every UI element binds its corner radius to a role from this scale; per-preset overrides come from `ui-style.kmd`.

themes/shape

Catalog of 35 named shapes + morphing contract for Material 3 Expressive parity. Sibling of `shape.kmd` (radius scale) — this spec covers polygon shapes (Pill, Cookie, Burst, Flower, etc.) and the interpolation contract that animates between two shapes via spring physics (`motion.kmd` R9). Source-of-truth for shape paths: androidx.graphics.shapes (vendored per-surface).

themes/shape-library

Typography system for Koder UIs — font stacks, type scale, weights, leading/tracking tokens, and the 12 type roles every widget binds against. Material parity (`/styles/typography/fonts` + scale). Implementation: Inter (Latin) + JetBrains Mono (code) self-hosted per `#015`; per-preset overrides from `ui-style.kmd`.

themes/typography

Eixo "estilo de interface" ortogonal ao "esquema de cores" já existente (`themes/light-dark.kmd`). Define vocabulário abstrato em tokens (style, corner-radius, density, font-stack, elevation, motion) e 19 presets canônicos (Material 3, GNOME, macOS, Windows 11, etc.) que cada SDK Koder traduz pro idioma nativo (ThemeData no Flutter, CSS custom properties no Web). App Desktop/Web Koder expõe `KoderUIStylePicker` em Settings § Appearance.

themes/ui-style

Verge is the canonical visual language of the Koder Design System — Koder's equivalent to Google's Material or Microsoft's Fluent. Verge is registered as the **default preset** (`Default: true`) in `canonicalPresets`. v0 starts by copying the GNOME Adwaita tokens 1:1 (owner decision 2026-05-14); tokens diverge gradually as Koder products evolve.

themes/verge

HTML index page at `kds.koder.dev/blog/` that lists Koder Design releases as blog-style cards, ordered newest-first. Material parity (`/blog`). Backed by the same source data that powers the existing `feed.xml` RSS feed.

tools/blog-changelog-index

Strict extension to `tools/blog-changelog-index.kmd` (#049.59). Adds editorial post kind (long-form case studies, deep dives, design philosophy) alongside auto-generated changelog entries. Owner-curated content per feedback memory `kds_owner_curated_content`.

tools/blog-editorial-posts

In-browser tool at `kds.koder.dev/tools/contrast/` that validates foreground-background color pairs against WCAG 2.2 AA / AAA. Material parity (`/foundations/accessible-design/accessibility-basics` color tools). Used inline by Theme Builder; standalone for ad-hoc checks.

tools/contrast-checker

Exports the current Koder Design system into formats consumable by popular design tools — Figma Variables JSON, Sketch shared styles, Adobe XD libraries — so designers iterate in their tool while staying in sync with code. Material parity (`/develop/figma`).

tools/design-kit-export

tools/kds-sidebar-order

Auto-generated migration guides covering both (a) Material → Koder Design adoption and (b) version-to-version Koder Design upgrades. Material parity (`/develop/migration`). Driven by `design-gen make migrate` infrastructure already in place for inter-version diffs.

tools/migration-guides

Strict extension to `tools/migration-guides.kmd` (#049.58). Adds 3rd migration lane: Koder M3 baseline → Koder M3 Expressive uplift. Documents what changed when umbrella #062 specs ratified; provides per-area migration tables (motion, shape, components, typography); outlines future codemod strategy.

tools/migration-m3-expressive-uplift

Interactive in-browser tool at `kds.koder.dev/themer/` that turns a seed color into a full Material-3-style palette and exports tokens in every supported format. Replaces the legacy paste-JSON playground. Material parity (`/theme-builder`).

tools/theme-builder

Define o termo **variante** como instância executável de um componente Koder para uma combinação específica de superfície (UI/forma) × alvo (plataforma/SO) × fator de forma (dispositivo). Distingue de release (eixo temporal) e de artefato (build output). Codifica os três eixos como vocabulário fechado, lista combinações válidas, e define o naming canônico `<sector>-<surface>-<target>`.

variants/taxonomy

Toggles obrigatórios em Settings (`voice.enabled`, `voice.talkMode`, `voice.hotWord`, `voice.backend`, `voice.bargeIn`, `voice.debugRecord`), defaults seguros (tudo OFF na instalação fresca exceto `bargeIn` que é ON quando `talkMode` ativo), e contrato de privacidade — ring buffer pré-wake de 2 s **nunca** sai do dispositivo, post-wake só vai pro `services/ai/voice` configurado, nada é logado/persistido a menos que `debugRecord = true`. Surface compartilhada: `KodeVoiceSettingsTile` em `engines/sdk/koder_kit`.

voice/wake-word

Responsividade e conformidade mobile para web apps Koder (admin, dashboards, consoles SaaS): breakpoints, touch targets, iOS Safari, hover, tabelas, formulários. Distinto de landing pages (specs/ landing-pages/), que tem regras próprias.

web-apps/responsiveness