Eve library

The first screen of a working surface

Evidence

Revision 1

On this page

Who a route is addressed to, what each block above the fold offers a reader, and the five ways prime space gets spent on nothing.

Generated from libs/oshun/workbench-kit/src/first-screen.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S7.22.c. Do not edit by hand.

Summary#

  • src/first-screen.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/first-screen contract S7.22.c

Exports#

Symbol Kind Summary
AT_WORK_SCOPES enumeration The route scopes S1.8 defines, repeated here so the mapping is checkable.
AT_WORK_SHARE_SAFETY enumeration The share-safety words S1.8 defines that mean this link is not for a stranger.
BLOCK_OFFERS enumeration What a reader can do with a block, measured.
blockOffer function What this block offers, measured, in a stated precedence.
BlockOffer type —
deriveAudience function Who this route is addressed to, from what the descriptor already says.
FIRST_SCREEN_FAULTS enumeration —
firstScreenAudit function —
FirstScreenBlock interface —
firstScreenBudget function —
FirstScreenBudget interface —
FirstScreenFault type —
firstScreenFaults function The first-screen audit.
FirstScreenFinding interface What an operator's first screen is spent on (S7.22.c).
firstScreenHeadline function The sentence the audit reports.
firstScreenSummary function —
FirstScreenSummary interface —
FULL_WIDTH_SHARE constant How wide a block must be, as a share of the viewport, to be reaching across the surface rather than sitting in a column of it.
HERO_MIN_PRIME_SHARE constant How much of the first screen a block must take to be a hero rather than a heading.
isAspirationalBanner function A full-width block whose only control leaves the surface.
isCampaignHeadline function A heading above the surface's own name, or drawn larger than it.
isLogoCloud function Three or more marks in one block that carry no data of their own.
isMarketingHero function A full-width block taking a quarter of the first screen and offering nothing.
isStatStrip function Three or more identically drawn numeric tiles that a reader cannot act on.
LOGO_CLOUD_MIN_MARKS constant How many inert marks in one block make a cloud.
MAX_EMPTY_PRIME_SHARE constant The share of the first screen that may offer nothing.
namedPattern function The named pattern this block is an instance of, or null.
OFFERS_WORTH_PRIME_SPACE enumeration Offers that are worth prime space; nothing is the one that is not.
ORIENTATION_ROLES enumeration ARIA roles that say where the reader is rather than what is on the surface.
PATTERN_FAULTS constant Which fault each named pattern is reported as.
PATTERNS_THE_PARENT_NAMES enumeration The five patterns S7.22.c spells out.
Rect interface —
RefusedPattern type —
STANDING_ROLES enumeration ARIA roles that state something true at this instant.
STAT_STRIP_MIN_TILES constant How many identically-drawn numeric tiles make a strip.
SURFACE_AUDIENCES enumeration The two audiences this item's rule turns on, and the honest absence.
SURFACE_VERDICTS enumeration —
SurfaceAudience type —
SurfaceDescriptor interface What S1.8's route descriptor says about who is reading.
SurfaceObservation interface —
SurfaceRow interface —
surfaceVerdict function —
SurfaceVerdict type —
WORK_MEMBER_ROLES enumeration ARIA roles whose element is one member of the collection a surface is about.

Shapes#

AT_WORK_SCOPES#

The route scopes S1.8 defines, repeated here so the mapping is checkable.

Values: tenant, workspace

AT_WORK_SHARE_SAFETY#

The share-safety words S1.8 defines that mean this link is not for a stranger.

Values: tenant-only, never-share

BLOCK_OFFERS#

What a reader can do with a block, measured.

Values: the-work, a-control, where-you-are, what-is-true-now, what-you-may-not-do, nothing

blockOffer#

What this block offers, measured, in a stated precedence.

ts
blockOffer(block: FirstScreenBlock): BlockOffer

BlockOffer#

ts
(typeof BLOCK_OFFERS)[number];

deriveAudience#

Who this route is addressed to, from what the descriptor already says.

ts
deriveAudience(descriptor: SurfaceDescriptor): SurfaceAudience

FIRST_SCREEN_FAULTS#

Values: marketing-hero-on-a-working-surface, campaign-headline-above-the-surface-name, stat-strip-nobody-can-act-on, logo-cloud-on-a-working-surface, aspirational-banner-on-a-working-surface, prime-space-offers-nothing, first-screen-budget-exceeded, work-not-on-the-first-screen, surface-audience-not-derivable, declared-audience-contradicts-what-the-surface-offers, surface-states-no-name, capture-and-measurement-disagree-about-the-viewport, surface-not-captured-by-this-run

firstScreenAudit#

ts
firstScreenAudit(observations: readonly SurfaceObservation[]): readonly SurfaceRow[]

FirstScreenBlock#

Field Type Required Notes
blockId string required —
frame Rect required Border box in document coordinates.
primePixels number required How many of this block's pixels fall inside the first viewport.
widthShare number required How wide the block is as a share of the viewport, 0..1.
controls number required Focusable descendants that act on this surface.
controlsLeaving number required Focusable descendants whose activation leaves this surface.
workMembers number required Descendants carrying a collection-member role.
editable boolean required Whether the block is, or contains, an editable region.
ownRole string | null required The block's own ARIA role, or null.
insideMain boolean required Whether the block is inside the surface's main landmark.
maxHeadingPx number | null required The computed font size of the largest heading in the block, or null.
maxHeadingText string | null required The text of the largest heading in the block, or null.
numericTiles number required Identically-drawn sibling tiles inside this block, each holding one numeral and a caption.
numericTilesActionable boolean required Whether any of those tiles is focusable, selectable or a link.
inertMarks number required Images and vector marks in the block that carry no data of their own.
words number required Words of running text in the block.

firstScreenBudget#

ts
firstScreenBudget(observation: SurfaceObservation): FirstScreenBudget

FirstScreenBudget#

Field Type Required Notes
screenPixels number required Pixels of the first viewport, its whole area.
measuredPixels number required Pixels of the first viewport covered by a measured block.
emptyPixels number required Of those, the pixels covered by blocks that offer nothing.
emptyShare number required emptyPixels as a share of the screen.
workOnTheFirstScreen boolean required Whether any block on the first screen offers the work.

FirstScreenFault#

ts
(typeof FIRST_SCREEN_FAULTS)[number];

firstScreenFaults#

The first-screen audit.

ts
firstScreenFaults(observations: readonly SurfaceObservation[]): readonly FirstScreenFinding[]

FirstScreenFinding#

What an operator's first screen is spent on (S7.22.c).

Field Type Required Notes
kind FirstScreenFault required —
subject string required —
detail string required —

firstScreenHeadline#

The sentence the audit reports.

ts
firstScreenHeadline(summary: FirstScreenSummary): string

firstScreenSummary#

ts
firstScreenSummary(rows: readonly SurfaceRow[]): FirstScreenSummary

FirstScreenSummary#

Field Type Required Notes
surfaces number required —
atWork number required —
outOfScope number required —
unknownAudience number required —
spendingPrimeSpace number required —
captured number required —
patternsFound number required —
worstEmptyShare number required —

FULL_WIDTH_SHARE#

How wide a block must be, as a share of the viewport, to be reaching across the surface rather than sitting in a column of it.

Value: 0.8

HERO_MIN_PRIME_SHARE#

How much of the first screen a block must take to be a hero rather than a heading.

Value: 0.25

isAspirationalBanner#

A full-width block whose only control leaves the surface.

ts
isAspirationalBanner(block: FirstScreenBlock): boolean

isCampaignHeadline#

A heading above the surface's own name, or drawn larger than it.

ts
isCampaignHeadline(block: FirstScreenBlock, observation: SurfaceObservation): boolean

isLogoCloud#

Three or more marks in one block that carry no data of their own.

ts
isLogoCloud(block: FirstScreenBlock): boolean

isMarketingHero#

A full-width block taking a quarter of the first screen and offering nothing.

ts
isMarketingHero(block: FirstScreenBlock, observation: SurfaceObservation): boolean

isStatStrip#

Three or more identically drawn numeric tiles that a reader cannot act on.

ts
isStatStrip(block: FirstScreenBlock): boolean

LOGO_CLOUD_MIN_MARKS#

How many inert marks in one block make a cloud.

Value: 3

MAX_EMPTY_PRIME_SHARE#

The share of the first screen that may offer nothing.

namedPattern#

The named pattern this block is an instance of, or null.

ts
namedPattern(block: FirstScreenBlock, observation: SurfaceObservation): RefusedPattern | null

OFFERS_WORTH_PRIME_SPACE#

Offers that are worth prime space; nothing is the one that is not.

Values: the-work, a-control, where-you-are, what-is-true-now, what-you-may-not-do

ORIENTATION_ROLES#

ARIA roles that say where the reader is rather than what is on the surface.

Values: banner, navigation, search

PATTERN_FAULTS#

Which fault each named pattern is reported as.

PATTERNS_THE_PARENT_NAMES#

The five patterns S7.22.c spells out.

Values: marketing-hero, campaign-headline, stat-strip, logo-cloud, aspirational-banner

Rect#

Field Type Required Notes
top number required —
right number required —
bottom number required —
left number required —

RefusedPattern#

ts
(typeof PATTERNS_THE_PARENT_NAMES)[number];

STANDING_ROLES#

ARIA roles that state something true at this instant.

Values: status, alert, log, progressbar, timer

STAT_STRIP_MIN_TILES#

How many identically-drawn numeric tiles make a strip.

Value: 3

SURFACE_AUDIENCES#

The two audiences this item's rule turns on, and the honest absence.

Values: at-work, addressed-to-a-stranger, not-derivable

SURFACE_VERDICTS#

Values: first-screen-is-the-work, first-screen-spends-prime-space, surface-not-in-this-item-scope, surface-audience-unknown

SurfaceAudience#

ts
(typeof SURFACE_AUDIENCES)[number];

SurfaceDescriptor#

What S1.8's route descriptor says about who is reading.

Field Type Required Notes
routeId string required —
path string required —
scope string | null required S1.8 ROUTE_SCOPES: platform, tenant, workspace.
roles readonly string[] required S1.8 role requirements; empty means anybody who can reach it may read it.
shareSafety string | null required S1.8 SHARE_SAFETY: public, tenant-only, never-share.
discoverability string | null required S1.8 DISCOVERABILITY: listed, search-only, hidden.

SurfaceObservation#

Field Type Required Notes
surfaceId string required —
origin string required The route or host this surface was rendered from.
viewport { readonly width: number; readonly height: number } required —
descriptor SurfaceDescriptor | null — SurfaceDescriptor required The declared route facts, or null where the surface has no descriptor.
surfaceName string | null required The name the surface states for itself — its main landmark's name or its title.
surfaceNameIsAHeading boolean required Whether that name is stated by a HEADING a reader can see, rather than only by an attribute.
surfaceNamePx number | null required The computed font size of the heading stating that name, or null.
nameIsFirstHeading boolean required Whether the name heading comes before every other heading on the surface.
blocks readonly FirstScreenBlock[] — FirstScreenBlock required —
capture { readonly path: string; readonly width: number; readonly height: number } | null required Where the capture was written, and at what viewport.
hasMain boolean required Whether the run found a main landmark at all.

SurfaceRow#

Field Type Required Notes
surfaceId string required —
origin string required —
audience SurfaceAudience required —
viewport string required —
emptyShare number required —
workOnTheFirstScreen boolean required —
patterns readonly RefusedPattern[] — RefusedPattern required —
capture string | null required —
verdict SurfaceVerdict required —

surfaceVerdict#

ts
surfaceVerdict(observation: SurfaceObservation): SurfaceVerdict

SurfaceVerdict#

ts
(typeof SURFACE_VERDICTS)[number];

WORK_MEMBER_ROLES#

ARIA roles whose element is one member of the collection a surface is about.

Values: row, listitem, option, treeitem, gridcell, article, tab

Valid examples#

No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.

Invalid examples#

No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.

Authorization and scope#

| Symbol | Type | Notes | | ------------------------------- | ------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | | AT_WORK_SCOPES | enumeration | The route scopes S1.8 defines, repeated here so the mapping is checkable. | | FirstScreenSummary.outOfScope | number | — | | SurfaceDescriptor.scope | string | null | S1.8 ROUTE_SCOPES: platform, tenant, workspace. |

Idempotency and concurrency#

Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
RefusedPattern type —
SURFACE_VERDICTS enumeration —
SurfaceRow.verdict SurfaceVerdict —
surfaceVerdict function —
SurfaceVerdict type —

Compatibility#

Not applicable: nothing on this page is versioned independently of the package.

Deprecation#

Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.

Evidence#

  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/first-screen.ts