docs: plan presentation scene composition
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,236 @@
|
||||
# Presentation Scene Composition Design
|
||||
|
||||
## Purpose
|
||||
|
||||
The presentation route now has readable side-surfaces, Q&A panels, and a usable
|
||||
architecture figure. The weakest remaining slides are not primarily contrast
|
||||
problems. Scenes 3, 4, and 5 underuse the 720p stage: their content sits in a
|
||||
thin strip near the top while the rest of the canvas is empty. Scene 10 has a
|
||||
working demo composition, but important graph and interrupt-contract details
|
||||
are still too dim.
|
||||
|
||||
This slice improves composition before doing any deeper visual craft pass. The
|
||||
goal is to make the slides understandable from the back of a room at 1280x720
|
||||
without changing storyboard content, transport behavior, chat architecture, or
|
||||
demo state.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Scene 3, Positioning and Related Systems.
|
||||
- Scene 4, Planner and Runtime.
|
||||
- Scene 5, Workflow Lifecycle.
|
||||
- Light Scene 10 readability/proportion tuning for the graph and interrupt
|
||||
contract.
|
||||
- Scene-specific tests that assert the new structural roles and beat-driven
|
||||
emphasis.
|
||||
- Screenshot smoke for the affected scenes at 1280x720.
|
||||
- Roadmap update and implementation-plan archival after execution.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Chat framework replacement.
|
||||
- Q&A content rewrites.
|
||||
- Evidence inspector redesign.
|
||||
- New presentation routes or presenter companion controls.
|
||||
- Replacing the architecture recursive figure system.
|
||||
- General motion polish. Motion should remain simple and state-driven.
|
||||
|
||||
## Design Direction
|
||||
|
||||
Use bespoke scene compositions, not a new generic diagram framework. The current
|
||||
problem is concrete: three scenes lack enough spatial structure. Abstraction can
|
||||
wait until multiple scenes prove they share the same durable shape.
|
||||
|
||||
The stage should feel like an editorial product walkthrough:
|
||||
|
||||
- A large visual object carries the scene.
|
||||
- Beat changes emphasize different regions of that object.
|
||||
- Discussion chips stay available but do not compete with the central diagram.
|
||||
- Evidence labels remain small and supportive.
|
||||
- Typography stays readable and restrained; no extra display fonts or decorative
|
||||
visual effects are needed.
|
||||
|
||||
## Scene 3: Positioning Map
|
||||
|
||||
Scene 3 should become a wide positioning map rather than five equal cards.
|
||||
|
||||
Structure:
|
||||
|
||||
- Left column: direct action patterns.
|
||||
- Tool loops.
|
||||
- Generated scripts.
|
||||
- Center: `lda.chat` as the workflow substrate.
|
||||
- Larger than the surrounding entries.
|
||||
- Uses the language "typed lifecycle substrate" or equivalent.
|
||||
- Shows three owned responsibilities: lifecycle, validation, persisted
|
||||
records.
|
||||
- Right column: adjacent orchestration ecosystems.
|
||||
- Hosted automation.
|
||||
- Agent graphs.
|
||||
- MCP / capability protocols.
|
||||
|
||||
Beat behavior:
|
||||
|
||||
- `landscape`: show the full map with no one region overpowering the others.
|
||||
- `lda-position`: emphasize the center substrate and dim surrounding entries
|
||||
slightly.
|
||||
|
||||
Testing expectations:
|
||||
|
||||
- The positioning scene exposes an accessible region such as
|
||||
`aria-label="positioning map"`.
|
||||
- The `lda-position` beat marks the center node active, for example through
|
||||
`data-positioning-active="true"`.
|
||||
- The map contains the labels `Tool loops`, `Generated scripts`, `lda.chat`,
|
||||
`Agent graphs`, and `MCP`.
|
||||
|
||||
## Scene 4: Planner Runtime Boundary
|
||||
|
||||
Scene 4 should make the boundary itself the main visual object.
|
||||
|
||||
Structure:
|
||||
|
||||
- Two large panes fill the stage width:
|
||||
- Planner pane: "proposes", "revises", "chooses tools".
|
||||
- Runtime pane: "validates", "executes", "records", "resumes".
|
||||
- A central boundary seam separates them.
|
||||
- A small handoff strip or arrow names the interface: CLI / JSON-RPC / workflow
|
||||
operations.
|
||||
|
||||
Beat behavior:
|
||||
|
||||
- `planner`: planner pane is active, runtime pane stays visible but reduced.
|
||||
- `runtime`: runtime pane is active, planner pane stays visible but reduced.
|
||||
- `boundary`: both sides are active and the seam/interface is emphasized.
|
||||
|
||||
Testing expectations:
|
||||
|
||||
- The scene exposes an accessible region such as
|
||||
`aria-label="planner runtime boundary"`.
|
||||
- The active beat is reflected in a stable attribute, for example
|
||||
`data-boundary-active="planner" | "runtime" | "boundary"`.
|
||||
- The boundary interface text includes both `CLI` and `JSON-RPC`.
|
||||
|
||||
## Scene 5: Lifecycle Rail
|
||||
|
||||
Scene 5 should become a full-width lifecycle rail with large state blocks and a
|
||||
small explanation panel for the current beat.
|
||||
|
||||
Structure:
|
||||
|
||||
- Four large lifecycle blocks:
|
||||
- Draft.
|
||||
- Artifact.
|
||||
- Deployment.
|
||||
- Run.
|
||||
- Directional connectors between blocks.
|
||||
- A current-state explanation panel below or beside the rail.
|
||||
- Each block has one concise responsibility:
|
||||
- Draft: mutable authoring state.
|
||||
- Artifact: immutable workflow definition.
|
||||
- Deployment: source binding.
|
||||
- Run: execution record and trace.
|
||||
|
||||
Beat behavior:
|
||||
|
||||
- Each beat activates its matching block and explanation panel.
|
||||
- Previous blocks can be marked as completed, but inactive future blocks must
|
||||
remain readable.
|
||||
- Raw-plan bypass should be mentioned only in discussion/Q&A, not in the core
|
||||
rail, to avoid crowding the scene.
|
||||
|
||||
Testing expectations:
|
||||
|
||||
- The lifecycle scene exposes `aria-label="workflow lifecycle rail"`.
|
||||
- The active block has `data-lifecycle-active="true"` or equivalent.
|
||||
- The current explanation text changes across at least two beats.
|
||||
|
||||
## Scene 10: Demo Graph And Contract Tuning
|
||||
|
||||
Scene 10 already has a working demo composition. This slice should only tune
|
||||
proportions and readability.
|
||||
|
||||
Changes:
|
||||
|
||||
- Increase graph node text contrast.
|
||||
- Ensure completed/current/interrupt labels are readable at 1280x720.
|
||||
- Keep graph and contract panel balanced; neither should collapse into a tiny
|
||||
subpanel.
|
||||
- In interrupt/approval beats, the interrupt contract must be visually
|
||||
available without forcing the viewer to inspect tiny JSON.
|
||||
|
||||
Testing expectations:
|
||||
|
||||
- Existing demo scene tests should continue to pass.
|
||||
- Add or update a test that asserts the approval beat exposes a readable
|
||||
contract panel label.
|
||||
- Do not add new demo state, new RPC calls, or new recording data in this slice.
|
||||
|
||||
## CSS And Component Boundaries
|
||||
|
||||
Expected files:
|
||||
|
||||
- `web/apps/console/src/presentation/SceneBody.tsx`
|
||||
- Rewrite the positioning, planner-runtime, and lifecycle scene renderers.
|
||||
- `web/apps/console/src/presentation/SceneBody.test.tsx`
|
||||
- Add structure and beat-state tests.
|
||||
- `web/apps/console/src/presentation/presentation.css`
|
||||
- Replace the old small-card rules for these scenes.
|
||||
- `web/apps/console/src/presentation/DemoWorkflowScene.tsx`
|
||||
- Only modify if a small structural hook is needed for Scene 10 tuning.
|
||||
- `web/apps/console/src/presentation/styles/demo-workflow.css`
|
||||
- Tune Scene 10 graph/contract readability.
|
||||
|
||||
Avoid creating a new generic component library in this slice unless the helper
|
||||
is tiny and scene-local. The implementation should remain easy for the next
|
||||
agent to reason about.
|
||||
|
||||
## Visual Acceptance Criteria
|
||||
|
||||
At 1280x720:
|
||||
|
||||
- Scene 3 uses the middle of the canvas and reads as a map, not a row of cards.
|
||||
- Scene 4 clearly communicates the planner/runtime division without reading the
|
||||
slide text.
|
||||
- Scene 5 clearly communicates Draft -> Artifact -> Deployment -> Run.
|
||||
- Scene 10's graph labels and interrupt-contract area are readable without
|
||||
zooming.
|
||||
- Discussion chips remain visible but secondary.
|
||||
- No horizontal or vertical stage scrollbars appear.
|
||||
|
||||
At 1024x768:
|
||||
|
||||
- Scene content may become denser, but labels must not overlap.
|
||||
- The lifecycle rail may wrap only if needed; if it wraps, direction must remain
|
||||
understandable.
|
||||
|
||||
## Verification
|
||||
|
||||
Required focused commands:
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/presentation/SceneBody.test.tsx src/presentation/DemoWorkflowScene.test.tsx
|
||||
pnpm --dir web --filter @lda/console typecheck
|
||||
pnpm --dir web --filter @lda/console build
|
||||
```
|
||||
|
||||
Required screenshot smoke:
|
||||
|
||||
- `/present#scene/positioning/landscape`
|
||||
- `/present#scene/positioning/lda-position`
|
||||
- `/present#scene/planner-runtime/planner`
|
||||
- `/present#scene/planner-runtime/boundary`
|
||||
- `/present#scene/lifecycle/draft`
|
||||
- `/present#scene/lifecycle/run`
|
||||
- `/present#scene/workflow-demo/approval`
|
||||
|
||||
Save screenshots under `web/apps/console/.visual-smoke/`, which is ignored.
|
||||
|
||||
## Self-Review
|
||||
|
||||
- No placeholders remain.
|
||||
- The slice is intentionally limited to composition and readability.
|
||||
- Scene 10 is a tune-up, not a demo-system rewrite.
|
||||
- The spec does not require a new shared component framework.
|
||||
@@ -0,0 +1,108 @@
|
||||
# Presentation Surface Theme Normalization Design
|
||||
|
||||
## Purpose
|
||||
|
||||
The previous contrast pass fixed dark-on-dark text, but it did not make the
|
||||
presentation side-surfaces feel coherent. Chat can become too white, while
|
||||
discussion/Q&A panels still use a dark modal interior. This slice normalizes
|
||||
those surfaces so `/present` reads as one editorial product walkthrough instead
|
||||
of multiple unrelated UI skins.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Chat rail and chat message surface styling.
|
||||
- Discussion panel and Q&A branch styling.
|
||||
- Presenter-note styling inside discussion panels.
|
||||
- Shared presentation-only CSS hooks for editorial and night side-surfaces.
|
||||
- Screenshot smoke for representative scenes and direct discussion hashes.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Replacing chat with AI Elements or another chat framework.
|
||||
- Scene 6/7/10 composition changes.
|
||||
- Schema form approval UI.
|
||||
- Guided run beat gates.
|
||||
- Presenter companion.
|
||||
- Global `/console` theme changes.
|
||||
|
||||
## Design Direction
|
||||
|
||||
Use one restrained editorial surface vocabulary for presentation side-surfaces:
|
||||
|
||||
- **Editorial surface**: off-paper, slightly tinted, readable dark ink, subtle
|
||||
border, used for light chat and discussion panels.
|
||||
- **Night surface**: dark, readable text, restrained cyan/amber accents, used
|
||||
only when a beat intentionally lives on the dark workflow stage.
|
||||
|
||||
Do not let chat become pure white cards floating on paper. Do not let discussion
|
||||
modals look like old dark dashboard cards when opened from paper scenes. The
|
||||
modal should feel like a focused editorial note: readable, calm, and connected
|
||||
to the presentation canvas.
|
||||
|
||||
## Surface Contract
|
||||
|
||||
Components that render side-surfaces should expose a semantic surface attribute:
|
||||
|
||||
```tsx
|
||||
data-presentation-surface="editorial" | "night"
|
||||
```
|
||||
|
||||
This is not a full theme system. It is a small CSS contract for presentation
|
||||
side-surfaces. It should live on:
|
||||
|
||||
- `OperatorChat`
|
||||
- `DiscussionPanel`
|
||||
|
||||
Existing `data-chat-theme` may remain for compatibility, but CSS should prefer
|
||||
the semantic surface attribute for visual styling.
|
||||
|
||||
## Chat
|
||||
|
||||
Light chat should use the editorial surface, not white cards. The chat rail
|
||||
should be readable but secondary to the graph/evidence surfaces.
|
||||
|
||||
Required:
|
||||
|
||||
- `OperatorChat` maps `chatTheme === "light"` to
|
||||
`data-presentation-surface="editorial"`.
|
||||
- Chat cards on the editorial surface use off-paper background and dark ink.
|
||||
- Tool-call parts inside chat use the same surface, border, and text rules.
|
||||
- Night chat stays readable with dark cards and light text.
|
||||
|
||||
## Discussion/Q&A
|
||||
|
||||
All direct `#discuss/...` routes should use the editorial surface by default.
|
||||
This keeps Q&A readable and avoids dark modal interiors on paper scenes.
|
||||
|
||||
Required:
|
||||
|
||||
- `DiscussionPanel` root uses `data-presentation-surface="editorial"`.
|
||||
- Title, badge, evidence pointer, summary, Q&A answer, details, links, return
|
||||
button, and presenter note all have explicit readable colors.
|
||||
- Presenter notes stay demoted: visible to presenter, not styled as the main
|
||||
answer.
|
||||
|
||||
## Testing And Smoke
|
||||
|
||||
Automated tests should pin the surface attributes and representative content.
|
||||
CSS color correctness is confirmed through screenshot smoke, not jsdom computed
|
||||
color assertions.
|
||||
|
||||
Screenshot smoke targets:
|
||||
|
||||
- `#scene/positioning/landscape`
|
||||
- `#scene/planner-runtime/planner`
|
||||
- `#scene/lifecycle/draft`
|
||||
- `#discuss/where-is-ai-agent`
|
||||
- `#discuss/evaluation-validity`
|
||||
- `#scene/interrupt-evidence/approval`
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Chat is not pure white unless intentionally inside a full paper scene.
|
||||
- Discussion panels are readable and editorial.
|
||||
- Q&A panels do not look like old dashboard modals.
|
||||
- Presenter notes are demoted but legible.
|
||||
- `/console` remains unaffected.
|
||||
Reference in New Issue
Block a user