Design craft

import type { ReactElement } from "react";
import { Button } from "@bosunkit/components/button";
import { Card } from "@bosunkit/components/card";
import { Inline } from "@bosunkit/components/inline";
import { Reading } from "@bosunkit/components/reading";
import { Stack } from "@bosunkit/components/stack";

export const description: string =
  "An anchor watch panel composed only of kit parts: readings with their units, a stale position marked with its " +
  "age, and one primary action.";

export default function Example(): ReactElement {
  return (
    <Card title="Anchor watch">
      <Stack space="md">
        <Inline wrap space="lg">
          <Reading label="Depth" value={8.4} unit="m" fractionDigits={1} />
          <Reading label="Wind" value={18} unit="kn" />
          <Reading label="Distance from anchor" value={36} unit="m" />
          <Reading label="Position" value="50°12.00'N 001°24.00'W" integrity="stale" ageSeconds={180} />
        </Inline>
        <Inline>
          <Button variant="primary">Set a new circle</Button>
          <Button>Show the track</Button>
        </Inline>
      </Stack>
    </Card>
  );
}

Modes

The mode names what success looks like on a surface. Choose it from the surface, not the product.

Operate is the default. A working screen fails by strangeness without purpose: a decorated button, a field that does not match the others, motion that tells nothing, an invented control for a standard task. The kit already holds the familiar controls.

The order of the rules

When two rules disagree, the earlier one holds:

1. The bridge-display rules. Red is the alarm's alone; orange the warning's, yellow the caution's; only an unacknowledged alarm flashes, on the shared clock; a priority carries its shape and word as well as its color; a stale reading is marked yellow and an invalid one red, with its last value and age; chrome stays quiet so the data can be loud; a live value never tweens. See Alarms and severity and Data integrity.
2. The foundations on this site. Every color, length, radius, duration, curve, layer and type size is a token; four themes; the default and helm size classes; the screen forms at 40em and 68.75em; touch targets of the touch size, larger at helm.
3. The kit's conventions: components that take their text from the caller, formatted quantities (depths floored, units as SN.1/Circ.243 writes them, positions in chart notation, times with their reference), every word in the six languages' catalog, crew-facing messages that say what happened and what to do.
4. Design judgment: hierarchy, rhythm, restraint, where nothing above speaks.

The craft floor

Every change passes these checks on the rendered screen, in one look across the themes and screen forms:

• Contrast at 4.5:1 for text and 3:1 for large text in every theme, with secondary text on a tinted surface in the hue's text step.
• Tokens only, read from the stylesheets; a value no token holds becomes a token first.
• Type from the type roles or in em, so the helm size class enlarges it; readings, units, codes and the small capital labels beside a value in IBM Plex Mono with tabular figures; prose and control labels in Plex Sans, prose at a reading measure.
• Spacing on the spacing scale: tight inside a group, wider between groups.
• Motion on the motion tokens: transform and opacity, interaction colors over the fast duration, fades kept under reduced motion, a live value that jumps.
• States: default, hover, focus, active, disabled, loading, empty and error; for a reading, fresh, stale, degraded and invalid.
• Touch: every control the crew press is the touch size on a phone, a tablet or under a finger, and its press area never covers a neighbor.
• Copy in the crew's language, a control named for its action, an error that names the problem and the way out.

What the kit refuses

These are habits rather than decisions; reaching for one means the choice was not made.

• Same-size cards of an icon, a heading and a line as a page's structure, and cards inside cards.
• A big number with a small label and an accent, with no reading behind it. A measured value goes through Reading, with its unit, integrity and age.
• A small label stacked over a heading as decoration. The page header's eyebrow names the page's section; nothing else does this.
• A colored edge on a card or a list item. The alert card's priority edge belongs to the alert system.
• Gradient text, decorative blur or glass, hard offset shadows, striped or textured backgrounds with nothing under them.
• A chart with no data behind it. Sparkline and trend chart draw real series, with gaps where samples are missing.
• Monospace as decoration, and emoji or Unicode glyphs standing in for icons, apart from the priority shapes.
• A dialog for a task that needs neither an interruption nor protected focus.

Related

• Alarms and severity: the priorities, their colors, shapes and flash.
• Motion: the durations, curves and what may move.
• Component API: how a kit component takes its props, text and actions.
• Accessibility: contrast, focus, touch targets and reflow.