etaf/DESIGN.md

# Design

## Source of truth
- Status: Active
- Last refreshed: 2026-08-05
- Primary product surfaces: Executable applications under `examples/`, especially the buffers opened by the three `etaf-*-example-open` commands.
- Evidence reviewed: ETAF public source and user guide, core/Data/Resource tests, `../etaf-playground/DESIGN.md`, the polished ETAF Showcase, and the original Ebox Flex reference.

## Brand
- Personality: Precise, calm, modern, technical, and intentionally composed.
- Trust signals: Stable geometry, readable contrast, explicit state ownership, public-only construction, and visible success/error/selection states.
- Avoid: Bare fixture text, low-contrast pastel text, decorative emoji, fake browser chrome, huge empty surfaces, and controls indistinguishable from copy.

## Product goals
- Goals: Make core ETAF practices copyable from small executable files; prove the installed Runtime interaction path; keep examples visually consistent with the Flex reference and ETAF Showcase.
- Non-goals: Replacing `etaf-playground`, simulating the missing `etaf-ui` catalog, introducing a second theme system, or demonstrating every public symbol in one application.
- Success signals: Each example teaches one ownership boundary, opens without side effects at load time, reacts through public events, cleans up its resources, and remains unclipped in a compact GUI frame.

## Personas and jobs
- Primary personas: ETAF application authors and framework maintainers.
- User jobs: Copy a correct state/data/resource pattern, inspect a real mounted application, and verify the visible result of an event.
- Key contexts of use: Source reading, GUI Emacs exploration, automated ERT, and framework regression review.

## Information architecture
- Primary navigation: No shared launcher; every file owns one explicit open and close command.
- Core routes/screens: Retained counter, task Data Controller, and Resource health.
- Content hierarchy: Capability eyebrow, application title and explanation, primary state surface, actions, then an ownership rule footer.

## Design principles
- Principle 1: One example teaches one lifecycle owner; avoid a mega-demo that hides where state and cleanup belong.
- Principle 2: Writes happen at Event, Action, lifecycle, Data, or Resource boundaries; render functions remain read-only.
- Principle 3: Use warm restrained semantic color families and one-pixel borders to make structure obvious without adding a design-system dependency.
- Tradeoffs: Prefer a fixed compact teaching canvas over viewport arithmetic in each standalone example; keep the responsive full-application showcase in `etaf-playground`.

## Visual language
- Color: Warm canvas `#F8F5EE`, paper `#FFFDF8`, ink `#252A2E`, muted ink `#66706A`, terracotta `#F1D4C9`, sage `#DCEBDD`, blue `#D9EAF2`, and violet `#E7E2F1`, always with explicit dark text.
- Typography: The configured Emacs monospace face; bold only for titles, actions, statuses, and important values.
- Spacing/layout rhythm: One-line vertical gaps, 10–12 px horizontal gaps, and 12–18 px surface padding.
- Shape/radius/elevation: Square text-native blocks and one-pixel borders; no shadows or fake radius.
- Motion: None; synchronous commits must settle without geometry shifts.
- Imagery/iconography: Text and restrained semantic marks such as selection circles only.

## Components
- Existing components to reuse: Core Hosts, retained Components, refs, computed values, Actions, focusable Behaviors, Data Controllers, Resources, and Runtime lifecycle callbacks.
- New/changed components: Example-specific shell, metric, action, row, status, and footer Components/Hosts.
- Variants and states: Ready/active counter, selected/unselected task, open/done filter, idle/loading/success/error Resource.
- Token/component ownership: Each example owns its small static palette and composition; ETAF/Ebox own semantics, layout, and rendering.

## Accessibility
- Target standard: High-contrast, keyboard-addressable text UI.
- Keyboard/focus behavior: Every action has a stable ref, button role, and `etaf-focusable` Behavior.
- Contrast/readability: Tinted surfaces always set explicit foregrounds; status is expressed in text as well as color.
- Screen-reader semantics: Preserve textual labels and semantic roles; do not encode meaning only in decoration.
- Reduced motion and sensory considerations: No animation or flashing state.

## Responsive behavior
- Supported breakpoints/devices: GUI Emacs body widths of approximately 760 px and above.
- Layout adaptations: Examples use 680–720 px teaching canvases; action groups use wrapping Flex; the full viewport-responsive pattern remains in `etaf-playground`.
- Touch/hover differences: None; interaction uses the Runtime event boundary.

## Interaction states
- Loading: Explicit Resource/Data status rather than an invented fallback.
- Empty: Bounded explanatory row with no hidden placeholder data.
- Error: High-contrast visible error message that persists until the next action.
- Success: Explicit status text on a sage surface.
- Disabled: Remove the event/tab stop instead of presenting a misleading active control.
- Offline/slow network, if applicable: Not applicable to the synchronous core examples.

## Content voice
- Tone: Direct, technical, concise, and instructional.
- Terminology: Use the canonical names View, Component, Host, Runtime, Data Controller, Resource, Event, Action, Scope, and public API.
- Microcopy rules: Name the demonstrated ownership boundary and describe the visible effect; avoid promotional filler.

## Implementation constraints
- Framework/styling system: Emacs 29.1+, the public `etaf` facade, and public Ebox properties lowered through ETAF Hosts.
- Design-token constraints: Reuse the established warm palette directly; do not add a token framework for three examples.
- Performance constraints: Synchronous bounded data only; no timers, background work, or hidden repeated mounts.
- Compatibility constraints: Core examples must not require `etaf-ui`, `etaf-sqlite`, `etaf-playground`, or private `etaf--*` / `ebox--*` APIs.
- Test/screenshot expectations: `make check` byte-compiles examples and drives their mounted public event paths; GUI verification uses one target buffer window and rejects clipping or continuation indicators.

## Open questions
- [ ] Add an asynchronous Resource example only after ETAF defines a public asynchronous completion contract / maintainer / avoids teaching a speculative API.