# The chrome audit

Which gradients, glows, glass, marks, thick borders and shadows convey a state
or a hierarchy, measured sideways against the siblings and outwards against the
container.

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

## Summary

- `src/chrome.ts`

| Entry point                   | Runtime class | Authorized by |
| ----------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/chrome` | `contract`    | S7.22.d       |

## Exports

| Symbol                                                  | Kind        | Summary                                                                         |
| ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- |
| [CHROME_EFFECTS](#chrome_effects)                       | enumeration | The six effects S7.22.d spells out.                                             |
| [CHROME_FAULTS](#chrome_faults)                         | enumeration | —                                                                               |
| [CHROME_VERDICTS](#chrome_verdicts)                     | enumeration | —                                                                               |
| [CHROME_WARRANTS](#chrome_warrants)                     | enumeration | The four things that justify an effect, each a comparison against a named set.  |
| [chromeAudit](#chromeaudit)                             | function    | —                                                                               |
| [ChromeEffect](#chromeeffect)                           | type        | —                                                                               |
| [ChromeFault](#chromefault)                             | type        | —                                                                               |
| [chromeFaults](#chromefaults)                           | function    | The chrome audit.                                                               |
| [ChromeFinding](#chromefinding)                         | interface   | The chrome audit: which decorative effects convey something (S7.22.d).          |
| [chromeHeadline](#chromeheadline)                       | function    | The sentence the audit reports.                                                 |
| [ChromeRow](#chromerow)                                 | interface   | —                                                                               |
| [chromeSummary](#chromesummary)                         | function    | —                                                                               |
| [ChromeSummary](#chromesummary)                         | interface   | —                                                                               |
| [chromeVerdict](#chromeverdict)                         | function    | —                                                                               |
| [ChromeVerdict](#chromeverdict)                         | type        | —                                                                               |
| [ChromeWarrant](#chromewarrant)                         | type        | —                                                                               |
| [conveysAState](#conveysastate)                         | function    | True when the effect distinguishes this thing from the things beside it.        |
| [conveysHierarchy](#conveyshierarchy)                   | function    | True when the effect distinguishes this thing from the thing around it.         |
| [EFFECT_CLAIMS](#effect_claims)                         | constant    | What each effect claims, so the finding can say what was claimed.               |
| [EFFECT_FAULTS](#effect_faults)                         | constant    | Which fault each effect is reported as when nothing justifies it.               |
| [EffectObservation](#effectobservation)                 | interface   | —                                                                               |
| [effectWarrants](#effectwarrants)                       | function    | The warrants this effect actually has, measured.                                |
| [GLOW_MAX_OFFSET_PX](#glow_max_offset_px)               | constant    | The offset below which a shadow is light from nowhere.                          |
| [GLOW_MIN_BLUR_PX](#glow_min_blur_px)                   | constant    | The blur above which a zero-offset shadow is a glow rather than a ring.         |
| [isGlow](#isglow)                                       | function    | True when a shadow is light from nowhere rather than a surface above another.   |
| [isRepeatedThickBorder](#isrepeatedthickborder)         | function    | True when a border is thick enough to read as a band and repeats identically.   |
| [REPEATED_BORDER_FLOOR](#repeated_border_floor)         | constant    | How many identical thick borders make a texture rather than a mark.             |
| [THICK_BORDER_PX](#thick_border_px)                     | constant    | How thick a border has to be before it stops being a line.                      |
| [WARRANTS_FOR_EFFECT](#warrants_for_effect)             | constant    | Which warrants can justify which effect.                                        |
| [WARRANTS_THE_PARENT_NAMES](#warrants_the_parent_names) | enumeration | The two the item's qualifier names, kept visible so the additions are arguable. |

## Shapes

#### CHROME_EFFECTS

The six effects S7.22.d spells out.

Values: `gradient`, `glow`, `glass`, `ornamental-icon`, `thick-border`,
`elevation`

#### CHROME_FAULTS

Values: `gradient-conveys-nothing`, `glow-conveys-nothing`,
`glass-conveys-nothing`, `ornamental-icon-states-nothing`,
`thick-border-repeated-until-it-marks-nothing`, `elevation-conveys-nothing`,
`elevation-matches-the-surface-it-claims-to-be-above`,
`effect-measured-with-no-comparison-set`

#### CHROME_VERDICTS

Values: `effect-conveys-something`, `effect-conveys-nothing`,
`effect-not-settled-by-this-run`

#### CHROME_WARRANTS

The four things that justify an effect, each a comparison against a named set.

Values: `conveys-a-state`, `conveys-hierarchy`, `carries-the-datum`,
`announces-itself`

#### chromeAudit

```ts
chromeAudit(observations: readonly EffectObservation[]): readonly ChromeRow[]
```

#### ChromeEffect

```ts
(typeof CHROME_EFFECTS)[number];
```

#### ChromeFault

```ts
(typeof CHROME_FAULTS)[number];
```

#### chromeFaults

The chrome audit.

```ts
chromeFaults(observations: readonly EffectObservation[]): readonly ChromeFinding[]
```

#### ChromeFinding

The chrome audit: which decorative effects convey something (S7.22.d).

| Field     | Type                        | Required | Notes |
| --------- | --------------------------- | -------- | ----- |
| `kind`    | [ChromeFault](#chromefault) | required | —     |
| `subject` | `string`                    | required | —     |
| `detail`  | `string`                    | required | —     |

#### chromeHeadline

The sentence the audit reports.

```ts
chromeHeadline(summary: ChromeSummary): string
```

#### ChromeRow

| Field                | Type                                                         | Required | Notes |
| -------------------- | ------------------------------------------------------------ | -------- | ----- |
| `elementId`          | `string`                                                     | required | —     |
| `hostId`             | `string`                                                     | required | —     |
| `effect`             | [ChromeEffect](#chromeeffect)                                | required | —     |
| `value`              | `string`                                                     | required | —     |
| `warrants`           | `readonly ChromeWarrant[]` — [ChromeWarrant](#chromewarrant) | required | —     |
| `identicalInstances` | `number`                                                     | required | —     |
| `verdict`            | [ChromeVerdict](#chromeverdict)                              | required | —     |

#### chromeSummary

```ts
chromeSummary(rows: readonly ChromeRow[]): ChromeSummary
```

#### ChromeSummary

| Field             | Type     | Required | Notes                                        |
| ----------------- | -------- | -------- | -------------------------------------------- |
| `effects`         | `number` | required | —                                            |
| `conveying`       | `number` | required | —                                            |
| `decorative`      | `number` | required | —                                            |
| `unsettled`       | `number` | required | —                                            |
| `effectKindsSeen` | `number` | required | How many of the six the run measured at all. |
| `byState`         | `number` | required | —                                            |
| `byHierarchy`     | `number` | required | —                                            |

#### chromeVerdict

```ts
chromeVerdict(observation: EffectObservation): ChromeVerdict
```

#### ChromeVerdict

```ts
(typeof CHROME_VERDICTS)[number];
```

#### ChromeWarrant

```ts
(typeof CHROME_WARRANTS)[number];
```

#### conveysAState

True when the effect distinguishes this thing from the things beside it.

```ts
conveysAState(observation: EffectObservation): boolean
```

#### conveysHierarchy

True when the effect distinguishes this thing from the thing around it.

```ts
conveysHierarchy(observation: EffectObservation): boolean
```

#### EFFECT_CLAIMS

What each effect claims, so the finding can say what was claimed.

#### EFFECT_FAULTS

Which fault each effect is reported as when nothing justifies it.

#### EffectObservation

| Field                | Type                          | Required | Notes                                                                                                             |
| -------------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `elementId`          | `string`                      | required | Stable within one run.                                                                                            |
| `hostId`             | `string`                      | required | —                                                                                                                 |
| `effect`             | [ChromeEffect](#chromeeffect) | required | —                                                                                                                 |
| `value`              | `string`                      | required | The effect's value as the engine computed it, normalised.                                                         |
| `siblingValues`      | `readonly string[]`           | required | The same effect's value on each of this element's siblings.                                                       |
| `containerValue`     | `string \| null`              | required | The same effect's value on the nearest enclosing box, or null where this element is not inside one.               |
| `identicalInstances` | `number`                      | required | Elements sharing this one's value and its drawing, for the repetition rule. One means the effect does not repeat. |
| `drawsAValue`        | `boolean`                     | required | Whether the element or an ancestor carries a value the effect could be drawn from.                                |
| `hasAccessibleName`  | `boolean`                     | required | Whether the element states an accessible name of its own.                                                         |
| `insideAControl`     | `boolean`                     | required | Whether the element is inside an interactive control.                                                             |
| `offsetPx`           | `number`                      | required | For an elevation or a glow: the largest absolute offset, in pixels.                                               |
| `blurPx`             | `number`                      | required | For an elevation or a glow: the blur radius, in pixels.                                                           |
| `widthPx`            | `number`                      | required | For a border: the largest side width, in pixels.                                                                  |

#### effectWarrants

The warrants this effect actually has, measured.

```ts
effectWarrants(observation: EffectObservation): readonly ChromeWarrant[]
```

#### GLOW_MAX_OFFSET_PX

The offset below which a shadow is light from nowhere.

Value: `1`

#### GLOW_MIN_BLUR_PX

The blur above which a zero-offset shadow is a glow rather than a ring.

Value: `8`

#### isGlow

True when a shadow is light from nowhere rather than a surface above another.

```ts
isGlow(offsetPx: number, blurPx: number): boolean
```

#### isRepeatedThickBorder

True when a border is thick enough to read as a band and repeats identically.

```ts
isRepeatedThickBorder(observation: EffectObservation): boolean
```

#### REPEATED_BORDER_FLOOR

How many identical thick borders make a texture rather than a mark.

Value: `3`

#### THICK_BORDER_PX

How thick a border has to be before it stops being a line.

Value: `3`

#### WARRANTS_FOR_EFFECT

Which warrants can justify which effect.

#### WARRANTS_THE_PARENT_NAMES

The two the item's qualifier names, kept visible so the additions are arguable.

Values: `conveys-a-state`, `conveys-hierarchy`

## 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

Not applicable: nothing on this page carries an actor, a grant, a scope or a
tenant, so authorization is decided entirely by the caller.

## Idempotency and concurrency

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

## Pagination

| Symbol                       | Type       | Notes                                                               |
| ---------------------------- | ---------- | ------------------------------------------------------------------- |
| `EffectObservation.offsetPx` | `number`   | For an elevation or a glow: the largest absolute offset, in pixels. |
| `GLOW_MAX_OFFSET_PX`         | `constant` | The offset below which a shadow is light from nowhere.              |

## State and failure

| Symbol                  | Type            | Notes                                                                    |
| ----------------------- | --------------- | ------------------------------------------------------------------------ |
| `CHROME_VERDICTS`       | `enumeration`   | —                                                                        |
| `ChromeRow.verdict`     | `ChromeVerdict` | —                                                                        |
| `ChromeSummary.byState` | `number`        | —                                                                        |
| `chromeVerdict`         | `function`      | —                                                                        |
| `ChromeVerdict`         | `type`          | —                                                                        |
| `conveysAState`         | `function`      | True when the effect distinguishes this thing from the things beside it. |

## 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/chrome.ts`
