Eve library

Frontend convention for this flow, and what is missing from it

Guide

Revision 1

On this page

Phase 182, 182.C.23.13 (and the same clause in 182.C.29.08). The item asks to follow the frontend-skill design convention — confirming it resolves in the working environment, or linking the guidance it encodes — before implementation.

The skill does not resolve here#

frontend-skill is not available in this environment. AGENTS.md §"Skill Usage Requirements" requires it for any user-facing UI work and then says what to do when it is missing: "If a relevant skill or tool is unavailable in the active environment, agents must explicitly note that limitation, use the strongest available equivalent workflow, and still run or extend the applicable Playwright automation in the repository."

This is that note. What follows is the strongest available equivalent, which is not a substitute: it is the in-repo convention the skill would otherwise carry.

The guidance it encodes, in this repository#

The design system: apps/oshun/web/src/design-system/lilith. Its edge-states.tsx already defines the register — calm under stress — and the primitives:

Primitive Register
LSkeleton dotted rule, no shimmer
LEmpty editorial: a sentence and a single action
LError a stamped notice — never alarming, always specific
LOffline full-bleed banner plus a cached badge
LPartialFailure keeps what loaded, names what did not
LPwaUpdate "a new edition" ribbon

The verification harness: the repo's Playwright inspect suite under apps/oshun/web/e2e-inspect/, which is where the accessibility batteries for the existing surfaces live.

Two primitives this flow needs and the set does not have#

1. Waiting on somebody else#

182.C.23.01 establishes that this flow has a gate the creator cannot close: the subject has to enrol, and that may take days. None of the six primitives fits.

  • It is not LSkeleton — nothing is loading.
  • It is not LEmpty — the project is full.
  • It is not LError — nothing failed.
  • It is closest to LPartialFailure, and that is the wrong word in the most damaging place: nothing has failed, and a creator told their project partially failed will try to fix it.

What it needs to say is "this is correct, complete, and resting", plus who it is waiting on and since when. Call it a pending-consent state; its register is patient rather than apologetic.

2. A measured review#

The Takes region shows candidates with their measurements and the windows nobody could measure (182.C.17.06). There is no review primitive today, and the accessibility requirement bites hardest exactly here:

Pass and fail must not be carried by colour. A green tick and a red cross are the default, and they are the one encoding this flow cannot use, because the third state — unmeasured — has no natural colour and is the state that matters most. Three outcomes, three shapes, three words: measured-pass, measured-fail, not measurable, each labelled in text.

The four states, per region#

182.C.23.01's five regions each need all four, and the empty state carries the most weight, because a new project is empty in four different ways and each has a different next action:

Empty because Next action
no cast invite somebody
cast without consent nothing — it is pending (see above)
consent without script write the words
script without approved audio record or synthesise, then approve
no presets on the service set the shot yourself in Direction

"Nothing here yet" in all five places is the failure this list exists to prevent.

Without fine pointer input#

182.C.24.01 already excludes the storyboard timeline from mobile on this ground. On the web surface the same requirement means every control has a keyboard path and a target a trackpad can hit: the timeline's shot handles need arrow-key nudging with a stated step, and the visible-speech window boundaries need numeric entry as well as dragging. A control that exists only as a drag is a control some people cannot use.

Status#

This item stays unchecked, and one of its three parts is now done.

The confirmation half was always done: the skill does not resolve, and the guidance it encodes is linked above.

The two missing primitives now exist, in apps/oshun/web/src/design-system/lilith/waiting-and-measured.tsx, exported from the design system and rendered in the /system/edge-states gallery:

  • LPending — names who it is waiting on and since when, says "Nothing has failed" outright every time, and is a status rather than an alert, because an alert announces something wrong.
  • LMeasured / LMeasuredReview — three outcomes, three CSS-drawn shapes, three words in the text layer. evaluated and notMeasured are required props, so a caller cannot render a take nobody looked at the same way as one with no findings, and the could-not-be-measured section renders even when it is empty.

Both were verified in a real chromium and not only in jsdom: the three marks measure as three distinct computed shapes, and with every colour flattened to one value both the words and the shapes survive. That is the "without colour alone" requirement stated as a measurement rather than as an intention.

The surface now exists, and building it corrected this document twice#

apps/oshun/web/src/app/studio/human-video is the route; HumanVideoStudio.tsx renders the five regions and projectState.ts derives what each one is doing. Two things written above turned out to be wrong once they were built.

There are five states per region, not four. Direction before the audio is approved is none of the four: nothing is loading, nothing failed, there is nothing to review, and it is not empty — calling it empty is the damaging choice, because an empty state's job is to hand over the next action and the next action is in another region. The fifth is blocked: it names the region that holds the next step and links there. It is rendered locally rather than as a seventh Lilith primitive, because unlike LPending it is about this flow's own ordering rather than about waiting on a person.

And a project is empty in seven ways, not four. The table above lists the four at project level. Rendering region by region found three more, and one of them is sharp: a subject nobody has asked yet is not a wait. A project can sit for days showing "waiting for Ama" when Ama was never sent anything, and nobody is waiting on a request that does not exist. The other two are a cast member with no references (the cast is authorized, the images an identity check would run against are not) and an approved plan with no shots.

Empty because Next action
no cast invite somebody
cast without references add reference images
cast without consent nothing — it is pending, not empty
references nobody asked about send the enrolment request
consent without script write the words
script without approved audio record or synthesise, then approve
approved audio without shots add the first shot
nothing generated review the pre-submission summary

A sixth state, found by wiring the route to the service#

partial. The project is assembled from several reads and any of them can be missing — the draft carries no consent, no reference quality, no audio take and no candidates, deliberately, because a draft that copied them would let an autosave write back a consent withdrawn this morning. The tempting shape is an empty array per absent read, and it makes the surface lie in the calmest possible voice: no consent state reads as "not covered yet", no audio take reads as "nothing recorded", no candidates read as "nothing generated".

So the project carries notRead, every region prefers it to a default, and the audio region with an unread take renders LPartialFailure — what loaded, and what did not — rather than LEmpty. Per reference, consent reads not read here, quality is not measurable with the read that would answer it named, and eligibility says nothing has been routed. None of those is a state the subject is in.

A region with no upstream, found by serving the presets (182.C.23.05)#

Every other region on this surface waits for the one before it: Direction is blocked until an approved audio duration exists, because a timeline placed against a duration nobody has is a timeline that moves under the creator. The preset panel was a panel INSIDE that region, so it inherited the block — and a preset is the first thing somebody picks, not the last. On the screen a creator actually sees first, the simple path was invisible, gated on an upstream it does not depend on.

So the rule is: a region's dependencies are the reads its content needs, and nothing about where it sits on the page. Presets is its own region now, between Voice and Direction, derived from the catalogue read alone. It is ready on a project with no cast, no script and no audio, because there is nothing about a preset that requires any of them.

The catalogue arrives as its own prop rather than as a field on the project, and that is the second thing this found. When the presets WERE project fields, a catalogue that landed a beat after the project counted as a newer version of the project — and the draft reducer refuses a reseed over unsent edits, so a creator who had started typing was told their work had blocked a refresh they never asked for, by a read that had nothing to do with their work. Ambient product facts and one creator's work are different things and cannot share a snapshot.

The admin half (182.C.29.08)#

apps/oshun/admin/src/app/isis/human-video/page.tsx follows the admin app's own template — session, workspace check, loader, AdminShell — rather than the Lilith design system, because that is the convention the surface it lives in encodes. Three decisions carried over from the member side and one that is the admin's own:

  • A failed read never renders as an empty queue. "Nothing is waiting for a human" is what somebody acts on by going home.
  • An artifact the service refused is not on the page at all. Not greyed, not behind a "request access" affordance that already holds the URL — absence is the enforcement, and what is rendered instead is the refusal's sentence so the next ask goes through the case system rather than a support ticket.
  • The operator actions ship refused. 182.C.29.08 requires this coverage before admin mutations are enabled, so quarantine, cancel and invalidate appear as a sentence naming what is missing. A button that quietly does nothing is worse; a hidden capability teaches an operator it does not exist.
  • The role comes from the session's scopes, on the server, and the queue endpoint decides access from it. A role a client could name is a role a client could claim, and role is half of what unlocks the most sensitive artifact in the system.

The browser found one real defect on this surface too: the panel's first version hardcoded a light-theme muted grey that measured 2.47:1 on the admin's dark canvas. It uses the admin tokens now.

What the browser said#

Measured in chromium against the real stylesheet, on five surfaces covering all five region states (ready, review, pending, empty, blocked, error, loading):

  • 0 axe violations (wcag2a, wcag2aa, wcag21a, wcag21aa) at 1280, 768 and 400 px, and no horizontal overflow at any of them — re-measured after the partial state and the unknown-consent rendering were added.
  • Each of the 30 region frames renders its state as a word, and the three measured outcomes keep three distinct computed shapes with every colour flattened to one value.
  • The route's data flow, in the real app. With the dev server serving and a stub standing in for the BFF (this worktree cannot boot the real one), a browser drove the whole loop: the local draft shows empty then four blocked; creating a project loads it to ready / ready / partial / blocked / blocked — partial because the audio take exists and was not read, which is the distinction the whole notRead design exists for; the consent line reads "did not load the authorization"; three edit bursts produced exactly three PATCHes (the debounce holds); and a concurrent change came back as a conflict with the creator's typing intact and "Nothing of yours was overwritten" on screen. That is routing and data flow, which bundling a component into chromium cannot check.
  • Fifteen controls measured under 24 px in their short dimension — the contents-list links at 22, the "go to" links at 17, the speaker select at 19, the nudge and reorder buttons at 22 and 23. That is WCAG 2.2 SC 2.5.8, it is exactly the "without fine pointer input" clause above, and jsdom cannot see it: a 13 px field with 3 px of padding passes every unit test and measures 22 px. MIN_TARGET_PX in the Lilith tokens is now the floor and the re-measure reports none.