lda.chat/lda-wf
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: plan presentation visual scale pass

Browse Source
This commit is contained in:
lda
2026-07-12 20:47:34 +07:00 Verified
parent 24e471d0e6
commit 6ee1318a05
5 changed files with 405 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/current_roadmap.md
+9 -1
View File
@@ -306,11 +306,19 @@ separate activity after these surfaces are stable.
7. **Visual scale and color pass:** remove unwanted blue from Scenes 2 and 14,
shorten Scene 2's two-column composition, enlarge the focal diagrams in
Scenes 7, 9, 13, and 14, separate Scene 7 Validate from Repair visuals, and
improve Scene 1 title-box padding and contrast.
improve Scene 1 title-box padding and contrast. Design:
[`presentation visual scale and color pass`](superpowers/specs/2026-07-12-presentation-visual-scale-color-pass-design.md).
Implementation:
[`presentation visual scale and color pass plan`](superpowers/plans/2026-07-12-presentation-visual-scale-color-pass.md).
8. **Rehearsal gate:** run all 14 scenes at 16:9 and 4:3, verify the Scene 8 →
Scene 11 → Scene 12 path in live and replay modes, then review the story
flow, coverage, and ordering separately.
9. **Deferred: factual input file browser:** replace the Scene 10 input
manifest-only view with a read-only browser backed by canonical prepared or
live run facts. Distinguish declared, selected, read, and produced files;
do not imply file reads without evidence.
Presentation wishlist / defense readiness:
- Completed: visual pass for Scenes 6, 7, and 10 fixed architecture figure
docs/historical/superpowers/plans/2026-07-08-defense-presentation-visual-pass.md
+1 -1
View File
@@ -10,7 +10,7 @@
## Global Constraints
- Follow design spec: `docs/superpowers/specs/2026-07-08-defense-presentation-visual-pass-design.md`.
- Follow design spec: `docs/historical/superpowers/specs/2026-07-08-defense-presentation-visual-pass-design.md`.
- Do not change the 12-scene storyboard order.
- Do not replace chat UI in this slice.
- Do not add new dependencies.
docs/superpowers/specs/2026-07-08-defense-presentation-visual-pass-design.md → docs/historical/superpowers/specs/2026-07-08-defense-presentation-visual-pass-design.md
View File
docs/superpowers/plans/2026-07-12-presentation-visual-scale-color-pass.md
+221
View File
@@ -0,0 +1,221 @@
# Presentation Visual Scale And Color Pass Plan
> **Execution note:** Work from the repository root. The implementation lives
> under `web/`; do not stop or restart the user's running `pnpm dev` servers.
## Goal
Implement the current visual scale and color design for the 14-scene
presentation without changing behavior, facts, transport, or live/replay
semantics.
## Required Reading
- `docs/AGENTS.md`
- `docs/superpowers/specs/2026-07-12-presentation-visual-scale-color-pass-design.md`
- `docs/current_roadmap.md`
- `web/README.md`
- `web/apps/console/src/presentation/storyboard.ts`
- `web/apps/console/src/presentation/SceneBody.tsx`
- `web/apps/console/src/presentation/presentation.css`
Before editing, inspect the current DOM and screenshots for these routes:
- `#scene/thesis/title`
- `#scene/problem/direct-actions`
- `#scene/authoring/discover`
- `#scene/authoring/diagnose`
- `#scene/authoring/repair`
- `#scene/prepared-lifecycle/discover`
- `#scene/evaluation/cohort`
- `#scene/conclusion/limits`
Use the existing Playwright tooling or browser skill to capture screenshots at
`1280x720` and `1024x768`. Do not infer visual problems from CSS alone.
## Task 1: Lock The Visual Contracts
**Ownership:** presentation tests and scene-level data contracts.
Files likely involved:
- `web/apps/console/src/presentation/SceneBody.test.tsx`
- `web/apps/console/src/presentation/opening/*.test.tsx`
- `web/apps/console/src/presentation/presentation-css.test.ts`
- scene-specific tests discovered during inspection
Steps:
- [ ] Add focused failing assertions for the title, problem, authoring,
lifecycle, evaluation, and conclusion surfaces.
- [ ] Assert semantic markers for the dominant visual and active beat rather
than fragile CSS pixel values.
- [ ] Add regression assertions that these editorial scenes do not gain demo
footer controls, live target badges, or unexpected chat chrome.
- [ ] Add CSS contract checks only for durable selectors/tokens that must not
regress, such as the neutral editorial surface and scene-specific layout
markers.
- [ ] Run the focused tests and confirm the new assertions fail for the
intended reasons.
Do not encode exact color strings or arbitrary pixel coordinates in tests.
## Task 2: Recompose Scene 1 And Scene 2
**Ownership:** opening scene components and their presentation CSS.
Likely files:
- `web/apps/console/src/presentation/opening/OpeningThesisScene.tsx`
- `web/apps/console/src/presentation/opening/ProblemLoopScene.tsx`
- `web/apps/console/src/presentation/presentation.css`
- corresponding tests
Steps:
- [ ] Make the Scene 1 title beat title-first: one primary title treatment,
more internal padding, stronger text contrast, and no duplicate framing.
- [ ] Preserve the later Scene 1 substrate/decomposition content without
forcing it into the title beat's dimensions.
- [ ] Keep Scene 2's transcript in normal chat reading order: user request,
agent/tool activity, observation, and answer.
- [ ] Shorten the two Scene 2 columns so the right automation explanation does
not become a tall dashboard card.
- [ ] Remove decorative blue from the editorial Scene 2 surface. Keep only
state or focus colors that communicate something specific.
- [ ] Verify both Scene 2 beats and the narrow canvas before moving on.
If the opening components need shared layout, extract a small semantic wrapper;
do not create another generic card primitive.
## Task 3: Enlarge And Differentiate Scene 7
**Ownership:** authoring scene visual projection and CSS.
Likely files:
- `web/apps/console/src/presentation/SceneBody.tsx`
- `web/apps/console/src/presentation/authoring/*`
- `web/apps/console/src/presentation/presentation.css`
- authoring scene tests
Steps:
- [ ] Identify the existing authoring loop and its active beat mapping before
changing markup.
- [ ] Give the active phase a larger, readable visual while keeping the full
loop as a compact orientation rail.
- [ ] Make `validate` show a diagnostic/contract-checking visual.
- [ ] Make `repair` show a correction/revision visual that is structurally
distinct from `validate`.
- [ ] Preserve factual command labels and existing icons; do not add invented
tool output.
- [ ] Add tests proving the active phase and the Validate/Repair visual
distinction.
Avoid adding five equally sized cards. The point is a dominant phase plus a
small map of the surrounding loop.
## Task 4: Enlarge Scene 9 Without Crowding It
**Ownership:** prepared lifecycle scene composition and CSS.
Likely files:
- `web/apps/console/src/presentation/authoring/PreparedAuthoringLifecycleScene.tsx`
- `web/apps/console/src/presentation/authoring/*`
- `web/apps/console/src/presentation/presentation.css`
- lifecycle scene tests
Steps:
- [ ] Identify which surface is primary for each lifecycle beat: discovery,
draft, validate, artifact, and deployment.
- [ ] Give the lifecycle visual most of the available stage area.
- [ ] Keep the prepared assistant as supporting context, not a second equal
hero surface.
- [ ] Preserve the current footer rail ownership and avoid adding another run
or live-status control.
- [ ] Add layout/beat tests that verify the primary surface remains present and
the scene does not regress to the old crowded composition.
Do not fold Scene 9 into the real live execution slice. This task is visual
composition only.
## Task 5: Enlarge Scenes 13 And 14
**Ownership:** evaluation and conclusion scene components/CSS.
Likely files:
- `web/apps/console/src/presentation/SceneBody.tsx`
- evaluation/conclusion scene components discovered during inspection
- `web/apps/console/src/presentation/presentation.css`
- corresponding tests
Steps:
- [ ] Choose one dominant evaluation visual per beat: cohort, validity, and
findings should not be three near-identical text panels.
- [ ] Increase the scale of the relevant diagram/stat treatment while keeping
methodology limits legible as support.
- [ ] Give the conclusion one clear contribution/limits visual rather than a
dense summary wall.
- [ ] Remove unnecessary blue from Scene 14 while preserving readable contrast.
- [ ] Keep the Questions beat usable and free of accidental demo chrome.
- [ ] Add tests for dominant-beat markers and conclusion surface behavior.
Do not invent new evaluation numbers or claims. All visual labels must come
from the storyboard or existing factual projections.
## Task 6: Responsive And Visual Verification
**Ownership:** route-level tests, screenshots, docs, and final review.
Steps:
- [ ] Run focused presentation tests after each task.
- [ ] Run the full web test suite:
`pnpm --dir web test`.
- [ ] Run typecheck:
`pnpm --dir web typecheck`.
- [ ] Run build:
`pnpm --dir web build`.
- [ ] Capture screenshots for the representative routes at `1280x720` and
`1024x768`.
- [ ] Confirm no accidental outer scroll, clipped title text, unreadable
diagram labels, or duplicate chrome.
- [ ] Re-run `git diff --check`.
- [ ] Run the two-axis review before declaring completion.
- [ ] Update `docs/current_roadmap.md` with the completed plan link.
- [ ] Move this plan to
`docs/historical/superpowers/plans/2026-07-12-presentation-visual-scale-color-pass.md`
only after implementation and review are complete.
## Troubleshooting Guidance
- If a diagram looks small, inspect the rendered bounding boxes and grid
allocation before changing font sizes.
- If React Flow edges drift, do not reintroduce CSS transforms. Preserve the
adaptive canvas geometry and use the existing React Flow viewport/layout
path.
- If a screenshot has a blue panel on a white scene, trace the selector and
token source before adding an override. Prefer fixing the editorial surface
contract rather than adding another specificity layer.
- If a beat appears unchanged, verify the beat ID reaches the component and
that the active-state marker is attached to the visual that actually changes.
- If 4:3 clips content, reduce surrounding chrome or allow an inner figure
scroll region; do not shrink all text until it becomes unreadable.
- If the live target badge appears outside Scenes 8-12, stop and fix the demo
chrome projection rather than hiding it with a broad CSS rule.
## Deferred File Browser Slice
Do not implement the real file browser in this plan. Track it separately as a
follow-up for `#scene/run-from-deployment/input`:
- read-only file tree/list from canonical prepared input facts;
- explicit distinction between declared, selected, read, and produced files;
- optional content preview only when backed by live/replay evidence;
- clear unavailable/empty states;
- tests for replay and live projections.
docs/superpowers/specs/2026-07-12-presentation-visual-scale-color-pass-design.md
+174
View File
@@ -0,0 +1,174 @@
# Presentation Visual Scale And Color Pass Design
## Purpose
This slice improves the remaining weak presentation scenes without changing the
storyboard, RPC transport, live/replay behavior, chat framework, or workflow
facts. The target is a readable defense deck at both the adaptive 16:9 and 4:3
canvas shapes already supported by `/present`.
The presentation should feel like an intentional product explanation: one
dominant visual per beat, enough space to understand it, and restrained color
used to communicate state rather than decorate every surface.
## Current Problem
The current deck is functional but uneven. Some scenes still use too much
framing, too much blue on editorial surfaces, or too many small elements at
once. The main targets are:
- Scene 1 has weak title hierarchy, excess framing, and insufficient title-box
padding/contrast.
- Scene 2 is taller and more card-like than a normal conversation/problem
explanation should be; its editorial surface also carries unnecessary blue.
- Scene 7's authoring visuals are too small and Validate/Repair are not
visually distinct enough across beats.
- Scene 9's lifecycle visuals lose scale when supporting chat and proof content
compete with them.
- Scenes 13 and 14 rely on small diagrams or text blocks where one larger focal
visual would carry the argument better.
## Scope
### In scope
- Scene 1 title hierarchy, padding, contrast, and removal of duplicate framing.
- Scene 2 composition height, visual balance, and non-demo color reduction.
- Scene 7 authoring visual scale and Validate/Repair distinction.
- Scene 9 prepared-lifecycle focal visual scale and supporting-surface balance.
- Scene 13 evaluation visual scale and information hierarchy.
- Scene 14 conclusion visual scale and removal of unnecessary blue.
- Screenshot smoke checks at `1280x720` and `1024x768`.
- Tests for stable structure, beat emphasis, and presentation-surface contracts.
### Out of scope
- Changing scene order, storyboard claims, or speaker script.
- Adding live workflow operations or changing replay truth.
- Replacing assistant-ui/shadcn chat components.
- Adding a real file browser to the Scene 10 input beat.
- Introducing a theme toggle or a third presentation theme.
- Rewriting the adaptive canvas or reintroducing `transform: scale(...)`.
- Reworking Scenes 3-6, 8, 10-12 unless a targeted regression is required.
## Design Rules
1. **One focal artifact per beat.** Supporting text, chat, receipts, and
discussion affordances must not compete with the beat's main visual.
2. **Editorial surfaces are neutral.** Paper/editorial scenes may use cyan for
a selected state or link, but should not be blue panels on white backgrounds.
3. **Demo surfaces keep operational color.** Scenes 8-12 may retain their
darker operational treatment and state colors because they are the product
demonstration. This is not a reason to recolor the rest of the deck.
4. **Scale before decoration.** Increase usable diagram area and reduce
surrounding chrome before adding new labels, badges, or cards.
5. **Beat changes must be legible.** A changed beat should change emphasis,
content, or position; do not rely on a tiny border or a nearly invisible
opacity change.
6. **Use existing tokens and primitives.** Prefer existing editorial tokens,
scene components, icons, figure layouts, and chat surfaces. Do not add a new
generic card system for this pass.
7. **Protect the canvas.** Validate both supported aspect-ratio extremes. A
diagram may scroll inside its own frame, but the presentation page must not
acquire accidental outer scroll.
## Scene Targets
### Scene 1: Thesis
The title beat should read as a title page, not as a generic content card.
Keep the title, subtitle, and planner/tool/platform decomposition available
across beats, but establish a clear title-first hierarchy.
Acceptance points:
- One primary title treatment is visible; duplicate boxes do not frame the same
content.
- Title padding is visibly generous at `1280x720`.
- Text contrast remains readable on the editorial surface.
- The decomposition can enter on later beats without shrinking the title beat.
### Scene 2: Problem
The scene should read left-to-right as a conversation/problem explanation, not
as two tall dashboard cards. Keep the transcript and reusable-automation
contrast, but make both blocks shorter and better balanced.
Acceptance points:
- The transcript reads as a chat/tool loop in normal reading order.
- The durable automation side is shorter and does not dominate by height.
- Blue is removed from the editorial background, borders, and decorative fills;
only meaningful emphasis remains.
- The two sides remain understandable at `1024x768`.
### Scene 7: Author, Validate, Repair
The authoring loop is the visual argument. The active phase must become large
enough to explain while the rest of the loop remains a readable map.
Acceptance points:
- The loop has a clear primary visual and a compact phase rail.
- Validate shows diagnostics or contract checking as its own visual state.
- Repair shows a correction/revision state, not the same Validate card with a
different label.
- Existing icons and factual commands remain available without turning the
scene into a wall of CLI text.
### Scene 9: Prepared Workflow Lifecycle
The lifecycle scene should explain Draft, Artifact, Deployment, and Run with a
large lifecycle visual. The authoring assistant remains a supporting surface;
it must not compress the lifecycle into unreadable cards.
Acceptance points:
- The lifecycle rail or active phase occupies the dominant area.
- The active phase is readable at both canvas shapes.
- Chat and proof support remain present only where the beat calls for them.
- The scene does not duplicate the demo footer rail or live target badge.
### Scenes 13-14: Evaluation And Conclusion
These scenes should close with evidence and a clear contribution, not a dense
summary wall.
Acceptance points:
- Scene 13 gives the evaluation numbers one dominant visual treatment, with
methodology limits as supporting content.
- Scene 14 gives the contribution/limits relationship one dominant visual
treatment and removes unnecessary blue from the editorial surface.
- Icons or existing visual primitives may carry categories, but must not replace
the factual labels needed for the defense.
- The final beat remains readable without opening a discussion panel.
## Verification Contract
- Existing presentation tests remain green.
- Add or update focused tests for Scene 1, Scene 2, Scene 7, Scene 9, Scene 13,
and Scene 14 structure and beat emphasis.
- Verify no presentation route gets accidental outer scroll at `1280x720` and
`1024x768`.
- Capture representative screenshots for the title, problem, authoring,
lifecycle, evaluation, and conclusion scenes.
- Run `pnpm --dir web test`, `pnpm --dir web typecheck`, and
`pnpm --dir web build` before completion.
## Deferred Follow-up: Real Input File Browser
The current Scene 10 input beat intentionally says `included in prepared run`.
That wording is factual, but it is not a file browser. A later slice may add a
real, read-only file browser for `#scene/run-from-deployment/input` backed by
the prepared recording and live run facts.
That follow-up must define what is actually known before showing it:
- canonical file paths and file count;
- whether a file was merely declared, selected, read, or produced;
- whether content preview is available from the live or replay source;
- how missing or unavailable previews are represented.
Until those facts exist, do not imply that the presentation selected or read
files merely because they appear in the prepared input manifest.