106 lines
6.5 KiB
Markdown
106 lines
6.5 KiB
Markdown
# Design
|
||
|
||
## Source of truth
|
||
|
||
- Status: Active draft for the sole reviewed pair
|
||
- Last refreshed: 2026-08-20
|
||
- Primary product surface: `examples/operations-console.etaf` + `examples/operations-console.el`
|
||
- Visual reference: `design/operations-console.html`
|
||
- Evidence reviewed: current pair loader/manifest, `etaf-ui.el`, Ebox viewport contract, and the current GUI/performance evidence.
|
||
|
||
## Brand
|
||
|
||
- Personality: calm operations cockpit; precise, warm, and quietly technical.
|
||
- Trust signals: explicit status chips, visible last-updated time, deterministic counts, clear success/error feedback.
|
||
- Avoid: generic toy dashboard, rainbow gradients, dense ungrouped controls, decorative widgets with no semantic state.
|
||
|
||
## Product goals
|
||
|
||
- Make one attractive app prove ETAF's Component, composition, reactive, Context/Theme, Behavior, event/Action, Data, Resource, error-boundary, focus, and lifecycle contracts.
|
||
- Do not add another Playground scenario or hide framework limitations behind fake animation.
|
||
- Keep the HTML prototype and ETAF rendering aligned in hierarchy, state labels, interaction outcomes, and compact/fullscreen geometry.
|
||
|
||
## Personas and jobs
|
||
|
||
- Primary personas: ETAF framework reviewer and application author learning the public API.
|
||
- User jobs: understand the layout model, trigger each capability, inspect visible state changes, and verify recovery/cleanup behavior.
|
||
- Key contexts: 900–940 px compact GUI, fullscreen GUI, keyboard-only review, and batch semantic tests.
|
||
|
||
## Information architecture
|
||
|
||
- Shell: brand/header -> navigation tabs -> page surface -> persistent status footer.
|
||
- Overview: hero/status strip, KPI cards, activity/control workspace, capability cards, and event timeline.
|
||
- Data: query/selection summary, interactive DataGrid, and selection detail panel.
|
||
- Resource: resource status, reload/fail-next controls, boundary result, and cleanup counter.
|
||
- Content hierarchy: page title and status first; primary action second; diagnostics/details third.
|
||
|
||
## Design principles
|
||
|
||
1. One visual hierarchy: every control belongs to a named surface and every surface has a visible status.
|
||
2. State before decoration: theme, loading, error, selected, disabled, and success states are readable as text as well as color.
|
||
3. Stable geometry: controls remain single-line at compact width; page changes replace only the page surface.
|
||
4. Public API truth: the prototype may use ordinary HTML/JS, but the ETAF port uses only public ETAF/ETAF-UI APIs.
|
||
|
||
## Visual language
|
||
|
||
- Color: ink navy `#142235`, paper `#F6F1E8`, slate `#526174`, teal `#2E8B83`, coral `#E26D5A`, amber `#D99A3D`, success `#3E9B72`.
|
||
- Typography: readable sans body, compact monospace labels/metrics, bold page titles.
|
||
- Spacing/layout rhythm: one-line outer rhythm, two-column workspace, fixed gaps, full-width shell, deliberate card padding.
|
||
- Shape/elevation: thin dark borders and restrained card elevation; no floating overlay is required by the ETAF port.
|
||
- Motion: no animation is required; state changes are immediate and reduced-motion safe.
|
||
- Imagery/iconography: text marks and Unicode status glyphs only; no external asset dependency.
|
||
|
||
## Components
|
||
|
||
- Existing components to reuse: public `button`, `checkbox`, `label`, `panel`, and `data-grid` from `etaf-ui`.
|
||
- New/changed components: `operations-console-shell`, `hero-status`, `metric-strip`, `activity-card`, `capability-card`, `timeline`, `data-page`, and `resource-page` in the companion.
|
||
- Variants/states: active/inactive nav, light/dark theme, selected/unselected row, Behavior on/off, resource ready/loading/error, boundary handled, compact/fullscreen.
|
||
- Ownership: `.etaf` owns static composition and section names; `.el` owns tokens, props, refs, resources, handlers, and state.
|
||
|
||
## Accessibility
|
||
|
||
- Target: keyboard-complete, high-contrast text, semantic roles through public UI components.
|
||
- Keyboard/focus: Tab and Shift-Tab traverse nav/actions/data rows; RET dispatches the focused ref; focus clears when a target is removed.
|
||
- Every state has text feedback; color is never the only signal. No hover-only behavior.
|
||
- Ebox Theme carries inherited Ebox defaults; application palette lookups remain
|
||
in the companion, while the Renderer filters unknown token names before they
|
||
reach Ebox geometry.
|
||
|
||
## Responsive behavior
|
||
|
||
- Supported surfaces: compact 900–940 px GUI body and fullscreen desktop GUI.
|
||
- Metric cards remain in one row when possible; workspace falls back from two columns to stacked sections; controls keep intrinsic single-line widths.
|
||
- Use `flex` for rows that distribute remaining width; reserve `row` for fixed
|
||
intrinsic control groups. The navigation control group is max-content so
|
||
each hover/active range remains an independent control.
|
||
- Mouse-1 and keyboard activation use the same public refs.
|
||
|
||
## Interaction states
|
||
|
||
- Loading: resource card reports `Loading…` without moving the shell.
|
||
- Empty: DataGrid reports an explicit empty state and keeps selection controls available.
|
||
- Error: resource reload can fail once; the boundary card reports the handled error and recovery remains available.
|
||
- Success: action/status and timestamp update visibly.
|
||
- Disabled: unavailable actions expose disabled semantics rather than silently ignoring input.
|
||
|
||
## Content voice
|
||
|
||
- Tone: concise, operational, and explanatory; labels name the framework capability being demonstrated.
|
||
- Terminology: use `Component`, `Context`, `Theme`, `Behavior`, `Action`, `Data`, `Resource`, and `Boundary` consistently.
|
||
- Microcopy: prefer a visible verb + result (`Reload resource`, `Handled: …`, `Selected Beacon`) over generic `Done`.
|
||
|
||
## Implementation constraints
|
||
|
||
- Framework/styling: ETAF public View DSL in `.etaf`/`.el`; Ebox renders the result; no HTML/CSS runtime dependency.
|
||
- Design tokens: keep palette/spacing tokens in one companion source and reuse them; no scattered ad-hoc colors.
|
||
- Performance: ordinary warm p50 <=100 ms, counter/resource p50 <=150 ms, every measured max <=250 ms; one publication per logical action.
|
||
- Compatibility: preserve one same-basename `operations-console` pair, safe static reader, public API boundary, mount twice/unmount cleanup, and manifest refs.
|
||
- Navigation: the stable page ref is read by the retained router Component; its
|
||
page Host is the single semantic Range anchor, so page switches replace one
|
||
Range payload instead of rebuilding the shell root.
|
||
- Review: HTML is the visual reference; ETAF needs compact/fullscreen screenshots and dynamic keyboard/mouse checkpoints.
|
||
|
||
## Open questions
|
||
|
||
- [ ] User review may adjust palette or page naming after the first HTML/ETAF comparison; behavior and public-ref coverage remain fixed.
|