etaf-playground/DESIGN.md

# Design

## Source of truth
- Status: Active
- Last refreshed: 2026-08-05
- Primary product surfaces: `etaf-playground-open`, `etaf-playground-open-ui`, and the interactive `etaf-playground-open-showcase` application.
- Evidence reviewed: `etaf-playground.el`, `tests/etaf-playground-tests.el`, `README.md`, `README.zh-CN.md`, the rendered current Showcase, and `../emacs-box/examples/playground/flex-reference.ebox` rendered fullscreen in GUI Emacs.

## Brand
- Personality: Precise, calm, modern, technical, and intentionally crafted rather than framework-generic.
- Trust signals: Exact alignment, readable contrast, stable geometry during updates, consistent semantic colors, and examples that visibly exercise the public ETAF model.
- Avoid: Default-Emacs-looking unstyled text, saturated dashboard colors, pastel text on tinted backgrounds, decorative noise, huge empty regions, and controls that look indistinguishable from ordinary copy.

## Product goals
- Goals: Make ETAF feel capable through a polished runnable application; teach View, Component, Context, Data, Grid, retained state, and events through visible structure; keep every example usable through public APIs only.
- Non-goals: Browser imitation, bitmap artwork, a separate styling framework, hidden example-only rendering paths, or pretending the small current `etaf-ui` catalog is feature-complete.
- Success signals: The first frame reads as a deliberate application; navigation, data changes, and theme changes preserve hierarchy and geometry; screenshots show no clipping, continuation indicators, unintended wrapping, or low-contrast text.

## Personas and jobs
- Primary personas: ETAF application authors, Ebox/ETAF maintainers, and evaluators deciding whether the new architecture is usable.
- User jobs: Understand the framework quickly, copy public patterns, inspect a realistic interactive flow, and verify that updates remain visually stable.
- Key contexts of use: GUI Emacs in a single application buffer, fullscreen demonstrations, and batch/ERT verification.

## Information architecture
- Primary navigation: A persistent horizontal command strip with Overview, Work items, and Theme destinations.
- Core routes/screens: Overview dashboard, interactive Work items table, Theme and semantics gallery, compact core counter example, and optional `etaf-ui` catalog example.
- Content hierarchy: Branded application header, persistent navigation, page title and supporting copy, primary cards/table, contextual action strip, and a quiet status bar.

## Design principles
- Principle 1: Teach through visible grouping; every capability receives a labeled, bounded surface instead of becoming an undifferentiated text stream.
- Principle 2: Use the Flex reference's warm restrained palette and one-pixel borders to create hierarchy without relying on shadows or browser-only effects.
- Principle 3: Geometry is part of correctness; viewport-sized owners contain their borders, children fit the owner's content box, and updates must not introduce wrapping or truncation markers.
- Tradeoffs: Prefer a dense desktop Emacs composition over excessive whitespace; prefer fixed readable card widths inside a responsive outer shell over fragile full-viewport arithmetic on every child.

## Visual language
- Color: Warm canvas `#F8F5EE`; paper `#FFFDF8`; ink `#252A2E`; muted ink `#66706A`; active terracotta `#B84F35`; tinted terracotta `#F1D4C9`; sage `#DCEBDD`; blue `#D9EAF2`; violet `#E7E2F1`; dark mode uses deep neutral surfaces with lighter versions of the same semantic accents.
- Typography: Emacs' configured monospace face; bold is reserved for titles, labels, key values, and active controls.
- Spacing/layout rhythm: One-line vertical section rhythm, 12–16 px horizontal gaps, 16–24 px section padding, and aligned card/table edges.
- Shape/radius/elevation: Square text-native surfaces, one-pixel borders, no fake radius or shadow.
- Motion: State changes publish directly and remain stable after redisplay; no decorative animation.
- Imagery/iconography: Text and restrained semantic glyphs only; no logos, emoji decoration, or bitmap chrome.

## Components
- Existing components to reuse: ETAF core Hosts, retained Components, Grid, Context theme values, Data Controller, and public event dispatch.
- New/changed components: Showcase section headers, metric cards, navigation items, task rows, action buttons, color swatches, compact status bar, and polished wrappers for the core/UI examples.
- Variants and states: Active navigation, selected task, enabled/disabled action, light/dark theme, success/review/open status, loading, empty, and error.
- Token/component ownership: Palette tokens live in `etaf-playground--showcase-palette`; each helper owns the surfaces it renders; ETAF/Ebox remain the layout and rendering owners.

## Accessibility
- Target standard: High-contrast keyboard-operable Emacs UI with explicit semantic roles and refs.
- Keyboard/focus behavior: Every actionable surface keeps `:role 'button`, `:tab-index 0`, stable refs, and visible active/selected styling.
- Contrast/readability: Every tinted surface has an explicit foreground; muted text remains readable on both canvas and paper; active controls use both color and border/background changes.
- Screen-reader semantics: Preserve labels, roles, refs, and `aria-label` where the framework exposes them.
- Reduced motion and sensory considerations: No animation is required; updates must remain usable with ordinary redisplay.

## Responsive behavior
- Supported breakpoints/devices: GUI Emacs windows from approximately 900 px wide through fullscreen desktop widths.
- Layout adaptations: The host measures the window body and reserves one character cell at the right edge; the outer shell owns viewport width; direct header/main/status surfaces stretch inside it; nested responsive containers omit width and let Ebox Flex allocate or wrap content.
- Touch/hover differences: None; keyboard and mouse press paths share the public event model.

## Interaction states
- Loading: Labeled bounded surface with visible status.
- Empty: Quiet explanatory surface with the next useful action when available.
- Error: High-contrast danger surface; errors remain visible instead of falling back silently.
- Success: Sage accent and explicit feedback text.
- Disabled: Muted foreground plus missing callback/tab stop.
- Offline/slow network, if applicable: Not currently applicable because the example uses the synchronous memory source.

## Content voice
- Tone: Direct, technical, concise, and self-explaining.
- Terminology: Use the canonical ETAF vocabulary: View, Component, Host, Context, Data Controller, Runtime, event, and public API.
- Microcopy rules: Name the capability being demonstrated, state the visible effect of actions, and avoid promotional filler.

## Implementation constraints
- Framework/styling system: Emacs 29.1+, ETAF public View/Component APIs, and Ebox public layout/style properties only.
- Design-token constraints: Reuse the palette helper and semantic token keys; do not add a parallel theme or CSS layer.
- Performance constraints: Interactive actions remain synchronous and bounded; visual polish must not add hidden full-tree work or timers beyond the existing viewport sync.
- Compatibility constraints: `etaf-playground` must remain independent from `ebox-playground` and must not call `ebox--*` private APIs.
- Test/screenshot expectations: `make check` passes; fullscreen GUI screenshots use one target buffer window; dynamic checks cover navigation, selection, insertion, theme toggle, and return to Overview; no visible truncation/continuation indicators or accidental wrapping are accepted.

## Open questions
- [ ] Expand the official `etaf-ui` catalog before presenting the catalog example as a migration-complete component gallery / maintainer / blocks parity claims.