NE.Standard

Designing a page

The components draw themselves well on their own; what makes a page read well is which one stands where. These are the framework's own rules — the demo's screens follow them — gathered in one place, each with the API that carries it. None is enforced: a page that needs something else says so with a property. The other guides say how each piece works; this one says when to reach for it.

The page and the device

Start from the phone. Every responsive value — a width, a placement, a visibility, a spacing — starts at the base tier and changes from a breakpoint up (UIResponsive<T>, views): the narrow layout is the one written first, the wide one the exception. The breakpoints are 640, 768, 1280 and 1536 CSS pixels (Sm, Md, Xl, Xxl).

A page has five regions — a header, a left and a right side, the content and a footer — and they are its landmarks to a screen reader, so put things where they belong rather than building a header inside the content. UIViewOptions says how they stand:

  • Navigation goes on the left side, as a sidebar menu, or a navigation rail where there are a handful of destinations (UIMenuDisplay.Rail); on a phone a rail alone becomes the bottom navigation bar by itself (items).
  • The sides become drawers below a width (SideDrawers): below Md by default, which suits a phone. A page whose main device is a tablet — a chat, a reader — keeps the content's whole width there with BelowXl, and a reader who wants a side to stay pins it. A side the reader works in beside the content — generation settings beside a chat — is modeless (LeftDrawerModal = false), so the page stays usable while it is open.
  • A side is not a dialog. A side holds what belongs to the page — its navigation, its filters, its details — and is a landmark; a dialog holds a task that interrupts it — confirm, create, edit one thing — and goes when the task is done. A sheet (UIDialogPlacement.Left, Right, Bottom) is still a dialog: reach for it for a passing task, not for a panel the reader keeps returning to.
  • A page that fills the screen — a messenger, an editor beside its preview — says so with ScrollContentOnly and a content root of Fill() height, so its panes scroll inside themselves; any other page lets the document scroll, which on a phone lets the browser fold its toolbar away.
  • A list beside the thing chosen in it is UILayout.Panes — chats and a conversation, a tree and a note, mail and a message: side by side from Md with the list 280 px wide, one at a time below it, the detail in the list's place with a Back of its own and a placeholder (UIPage.Empty) while nothing is chosen. Its widths and breakpoint are the preset's; a copy built by hand drifts from the others.

Layout

Pick the simplest arrangement that says what you mean. A column of things is a stack (UILayout.Stack), a line of them a row (UILayout.Row), a set of like things that wraps a wrap panel with ItemMinWidth, so its lines stand in even columns. Something at a row's start and things at its far end — a title and its buttons, a line and its action — is UILayout.Ends, the end as wide as it is, never two equal halves; cards on two columns, each read top to bottom, are UILayout.Board. A container's 24-column grid is for a layout that really is a grid — a form of fields side by side, a dashboard — and its placements are responsive values like any other (views, The placement grid). A container starts with one star row: set it with SetRow(1, …) and add the rest with AddRow.

Let the container give the air. Space between children is the container's Spacing, on the page scale of 4, 8, 12, 16 and 24 pixels; a child's own margin is for the exception. Things that are one unit — a title and its description, a field and its message — stand close by themselves; never widen the gap inside a unit to separate it from its neighbour, widen the gap around it.

Defaults follow what a component is. Text, a paragraph and a link stand at the start of their line, as words do; a button, an icon and a badge are centred in their cell; a container, a table and a list stretch. Set an alignment only where the default is wrong for the place.

Draw a surface only where there is a thing. A card (UICard.Create) or a surface frames one object — a record, a summary, a settings group; a page of cards inside cards reads as noise. One card alone on a page — a sign-in, a refusal — stands in the middle at a form's width (UICard.Centered). A layout panel paints nothing by default. A band that should be noticed — the filters over a list, a question at a page's foot — is UIPage.Band, a tinted surface, or a message (Feedback, below).

Keep reading to a column. Text and a page of cards do not run to a wide screen's edges: UIPage.Column holds them to one of three widths — Reading (720 px), Form (440 px), Wide (1080 px, a form beside its summary) — never one of the page's own. A row a list jumps to is an ActionComponent; where it needs content of its own — a glyph before a time, two lines laid out by hand — it is a clickable SurfaceComponent on UISurfaceStyle.Surface, the surface ground (#222222 on dark, #E4E4E4 on light).

Text

Use a role, not a size. A text's TitleType — Display, Title, Subtitle, Body, Caption, Overline — is a role of the theme, and UIText.Title(…), UIText.Body(…) and their kin set it in one call. A page has one Display or Title at most; a group under it a Subtitle. A person — a list's row, a byline — is UIText.Person: the round picture and the name over a muted line, at one of three sizes (Small, Medium, Large).

A title keeps one line; words that run on are a description or a paragraph. A title is cut short with an ellipsis rather than pushing the layout down, so say it in a few words. A text's description keeps one line too unless it asks to wrap (SetWrapMode(UITextWrapMode.Wrap)); a card's and an expander's header wrap theirs by default. Prose is a ParagraphComponent (UIText.Paragraph), which wraps and may clamp to a number of lines (MaxLines); a document — help, a release note, a model's reply — is a Markdown display (CodeInput), which may also draw its own runs in colours of the theme.

Only words meant to be read can be selected. Reading words — a paragraph, a table's cells, a Markdown document — select as on any page; a control's label does not, so a press never starts a selection. TextSelectable changes it where a page needs to.

Forms

One field, one job, its caption above it. A field's Title is its caption and its name to a screen reader; a field with no visible caption still takes an AccessibleName. A caption beside the value inside the field (UIInputTitlePlacement.Inside) suits a single row — a filter bar, a settings line — not a form.

Pick the appearance by the form. Filled, the default, almost everywhere: a field in a card or a row, a lone field beside its own button (a search, a promo code with Apply), a short centred form (a sign-in), a long form whose fields stack, or a field that edits a value in place. Outline or Underline where an explicit border or rule is wanted. Ghost for a field inside a list row. One form keeps one appearance — a code input too, which starts as Ghost (an editor is read, not filled in) and takes the form's appearance where it stands among fields.

Explain under the field, not in its caption. What may be typed, what it is for, how much is left: a hint under the field, UIForm.Field(input, hint), which wraps. A longer explanation a reader opens on demand is the field's help badge (SetHelp(phrase)).

A toggle's words are a short phrase. A checkbox's and a switch's title and description keep one line each beside the box, cut short past it; a choice that needs a sentence to explain takes that sentence as the field's hint, which starts under the toggle's words rather than under the box — never a margin of your own:

UIForm.Field(
    new SwitchComponent()
        .SetTitle("Thinking")
        .BindValue(nameof(SettingsController.Thinking)),
    "The model thinks before it answers. Off, it answers at once and spends no tokens on it."
)

Let the validation speak where the value is. A field's own rules run in the browser and show under the field; what only the server can judge comes from the controller (BindValidation) and stands in the same place. Keep the submit button enabled: a press on it shows every error and takes the reader to the first (binding, Validation).

Actions

One primary action per area. A form's submit, a dialog's confirm, an empty list's "Create" is Primary (UIButtons.Primary); the alternatives beside it are Ghost; Outline (UIButtons.Outline) is for where a bare button would read as words — an action on a message's colour, an alternative stretched under a stretched primary, a choice drawn as a card, a filter chip. A destructive one is Danger, and asks first in a dialog when it cannot be undone. A form's foot is UIButtons.Pair — the safe answer first, the committing one last, at the far edge — and a row of commands UIButtons.Toolbar.

An icon alone needs a tooltip. A button with no title is named by its tooltip, for a screen reader and a pointer alike; without one it is unnamed. Use icon-only buttons where the icon is unmistakable — close, search, more — and words elsewhere.

Show that a press is being worked on. A command that takes more than a moment runs from OnClickShowingLoading, which keeps the button's spinner until it answers and refuses a second press — a form's button from OnSubmitShowingLoading, a change's or a search's with ShowLoadingDuring(eventName); one that takes minutes and should go on while the reader is away is a job the runtime owns (Context.Runtime.Start, controllers).

Put the actions of a thing on the thing. A row's or a card's own actions are its context menu (SetContextMenu), which a press-and-hold on a phone opens too, and its action bar shows the common ones in place (views, Context menu).

Colour

Spend colour by role. UIThemeColor.Primary, Accent, Success, Warning, Danger, Info and Muted follow the theme in both modes and stay readable on every ground; a raw colour (UIThemeColor.FromColorVariant) is for content that is a colour — a label's colour the reader picked, a chart's series — not for a page's chrome. A word in colour is used sparingly: one accent in a line reads, five do not.

Check the dark theme. Both modes are first-class and a reader may switch at any time; a page tried only in one mode is half tried. A surface or a field takes its ground from where it stands, so the same component reads on the page, on a card and in a dialog without a colour of its own.

A status is a badge, a tone a message. A short state on an item — "Draft", "3 new" — is a badge (Fill filled, tinted or outlined by how loud it should be); a sentence about the page is a message.

Feedback

Say it where it belongs and as long as it is true. A sentence that stays true while the page is open — a quota reached, a form saved with warnings — is an in-page message (UIMessage.Warning, UIPage.Banner across the page). A confirmation that something happened — saved, sent, deleted — is a toast (ShowNotificationEffect), with a way back where there is one (Undo, Open). A question the reader must answer before going on is a dialog. Something that happened while the page is not on screen is the system's notification (ShowSystemNotificationEffect) (dialogs and notifications).

An empty list says what goes there. A list with nothing in it shows its empty template rather than a blank region: what would be here, worded with ConfigureDefaultEmptyTemplate, or with the action that adds the first one under the words, SetEmptyTemplate(UIPage.Empty(...)) — the built-in template is words alone. A region with nothing in it outside a list — a pane before a row is chosen — says it the same way, with the same component: UIPage.Empty.

What a submit came to replaces its form. "Check your inbox", "Order placed", "Not for this account": UIPage.Outcome, the tone's mark before the title, the line, the ways on — in the form's place, read out as it appears.

Expect the update mid-way. A value the server pushes lands while the reader is reading, typing or selecting: a value changes in place rather than redrawing its page, and a reply streamed into a Markdown display keeps what the reader selected in the paragraphs already written. A page that rebuilds a whole list or panel on every change loses that — change the item, not the collection.