ebox-playground/DESIGN.md

# Design

## Source of truth
- Status: Active
- Last refreshed: 2026-09-11
- Primary product surfaces: The `.ebox` files under `examples/`, the buffer opened by `ebox-playground-open`, and the generic file mode.
- Evidence reviewed: `ebox-playground.el`, the `.ebox` fixtures under `examples/`, `tests/ebox-playground-tests.el`, `README.md`, `README.zh-CN.md`, and rendered gallery/reference previews.

## Brand
- Personality: Precise, modern, restrained, and educational.
- Trust signals: Pixel-aligned sections, exact Grid placement, explicit text contrast, public-only construction, and a layout that remains legible without theme-specific faces.
- Avoid: Bare unstyled fixture text, low-contrast pastel typography, arbitrary rainbow colors, oversized blank canvas, and private diagnostic internals.

## Product goals
- Goals: Demonstrate Ebox Grid and composition in a polished standalone example; give the low-level package a visual quality bar consistent with the Flex reference.
- Non-goals: ETAF Components, a general application framework, or a second Playground runner. Interactive examples keep their own small state in a same-basename companion.
- Success signals: The first frame clearly communicates hierarchy and Grid behavior; every tinted block has readable text; no content crosses the visible viewport.

## Personas and jobs
- Primary personas: Ebox authors and maintainers.
- User jobs: Open one buffer, understand the public node contract, and see the complete supported Grid property/value set rendered attractively.
- Key contexts of use: GUI Emacs, fullscreen demonstrations, and ERT rendering checks.

## Information architecture
- Primary navigation: None; this is one self-contained reference surface.
- Core routes/screens: One header, grouped property sections, and one public-contract footer.
- Content hierarchy: Title and description, labeled capability bands, then small contrasting examples.

## Design principles
- Principle 1: Mirror the Flex reference's title—explanation—example rhythm.
- Principle 2: Use one restrained semantic accent per capability section.
- Principle 3: Keep the runner generic; put each concrete layout in a readable `.ebox` source file.
- Tradeoffs: Cover the complete public Grid property/value surface while keeping each example compact and grouped by responsibility.

## Visual language
- Color: Warm paper canvas with terracotta, sage, slate blue, and violet section families; explicit dark ink or white text according to contrast.
- Typography: Configured monospace, bold only for titles and short labels.
- Spacing/layout rhythm: One-line vertical gaps, 12 px horizontal gaps, 16–24 px section padding.
- Shape/radius/elevation: Square one-pixel borders; no shadows or fake radius.
- Motion: None.
- Imagery/iconography: Text-only.

## Components
- Author forms to reuse: String, `text`, `box`, `row`, `column`, `flex`, and `grid`. Empty `box` nodes express spacing directly without another public form.
- New/changed components: Header band, property section bands, track-function cards, implicit-track/flow cards, gap/placement cards, alignment cards, and public-contract footer.
- Variants and states: Static semantic color families only.
- Token/component ownership: Palette values and example composition live in `.ebox` fixtures; the runner reads and evaluates one ordinary Elisp expression with lexical bindings, then passes the resulting DSL data to public `ebox-build` and renders it. Adding a layout does not add a fixture-specific runner branch.
- Source contract: A static layout quotes the whole list; dynamic layouts use normal Elisp such as `let`, backquote, comma, and comma splicing. The expression is identical to the argument of `ebox-build` in an `.el` file. The runner does not evaluate properties separately or auto-detect the old unquoted structural format.
- Size contract: Use Ebox's explicit `(unit number)` values (`px`, `%`, `vw`, `vh`, `ch`, `lh`) and `calc`/`min`/`max`/`clamp` data. Bare `fit-content` is a keyword, never a function. Ebox owns resolution and vertical line quantization; the Playground adds no unit parser or alternate semantics.

## Accessibility
- Target standard: High contrast and readable labels in ordinary GUI Emacs themes.
- Keyboard/focus behavior: No interactive controls in this static example.
- Contrast/readability: Explicit foreground on every tinted surface.
- Screen-reader semantics: Plain descriptive text remains present in the buffer.
- Reduced motion and sensory considerations: No motion.

## Responsive behavior
- Supported breakpoints/devices: GUI Emacs windows from compact split previews to fullscreen desktop widths.
- Layout adaptations: Standalone gallery entry points default to a 720 px content canvas; split-window `.ebox` previews resolve `(vw 100)` against the preview pane's display-safe width and `(vh 100)` against its body height so viewport-based sections fit the active pane.
- Touch/hover differences: None.

## Interaction states
- Loading: Not applicable.
- Empty: Not applicable.
- Error: Public Ebox errors surface normally.
- Success: The rendered gallery itself is the success state.
- Disabled: Not applicable.
- Offline/slow network, if applicable: Not applicable.

## Content voice
- Tone: Concise, factual, and self-explaining.
- Terminology: Ebox, node, Grid, fixed track, fractional track, placement, public API.
- Microcopy rules: Explain what a visible section proves in one sentence.

## Implementation constraints
- Framework/styling system: Emacs 29.1+ and public Ebox constructors/properties only.
- Design-token constraints: Reuse the Flex reference's restrained color families without introducing a theme package.
- Performance constraints: One synchronous initial render; window resizing delegates to Ebox's single bounded viewport controller and incremental update path.
- Compatibility constraints: No ETAF dependency and no `ebox--*` calls.
- Test/screenshot expectations: `make check` passes and a fullscreen one-window screenshot shows complete, unclipped labeled sections.

## Open questions
- [ ] Add more standalone `.ebox` fixtures only when each teaches a distinct public Ebox responsibility / maintainer / prevents fixture sprawl.

## Parallax desktop example

- Surface: `examples/desktop-reference.ebox` and its companion. This dedicated
  direct-manipulation example complements the existing static/property-oriented
  layer reference; it does not replace it.
- Job: move five overlapping text windows, reveal covered content, and bring any
  window forward by clicking its exposed body/title or its persistent dock entry.
- Visual direction: midnight blue workspace, cool readable ink, violet Studio,
  cyan Signal, amber Notes, mint Terminal and rose Palette accents. One configured
  font size throughout. Use contrasting title bars and compact pane content,
  rather than fake close controls, images or additional font packages.
- Structure: compact identity/utility bar, clipped desktop with five independent
  sibling windows, then persistent dock and status. Keep the workspace dominant;
  each pane contains a distinct editorial/code/task/signal composition.
- Interaction: raise on press, preserve grab offset, repaint changed positions
  during native mouse tracking, apply the final release position, and retain the
  last accepted position after interruption. No inertial or decorative animation.
  The current Ebox layer contract uses pixel X and host-text-row Y coordinates.
- Keyboard: RET/SPC activates a pane or dock entry; title-bar Alt+arrows move it.
  Reset restores the original arrangement. No changes to global Emacs bindings.
- Responsive behavior: use viewport-relative positions and bounded pane widths;
  overflow is clipped at the desktop boundary. Dock entries remain available for
  covered panes. Target at least 40 columns and 20 text rows; smaller workspaces
  prioritize the dock, and reopening/resetting restores the initial arrangement.
- State and failure: one independent companion state per preview. Commit state
  only after public Ebox publication succeeds. Mouse tracking owns no persistent
  timer, advice or global map and releases its transient state on exit/error/quit.
- Verification: real commands retrieved from rendered native keymaps, synthetic
  motion/release streams with intermediate-publication checks, stacking/covered
  ownership and committed-input render parity, plus compact and wide renders.
  The standing restriction on operating the user's GUI Emacs remains in force;
  batch checks do not establish native redisplay latency or screenshot fidelity.