ServiceVisual

A service’s figure, declared as data and drawn in a frame captioned by its title: a status list, bars, a decision matrix, headline tiles, a flow of steps, a stack of layers or a page wireframe. Every string is copy; the visuals write no words of their own.

import { ServiceVisual, type ServiceVisualData } from '@zitdevs/ui';

Examples

Environment status Illustrative

• Backups verified OK
• Accounts without MFA 3 to review
• Active licences 42
• Domains and DNS OK

Illustrative format.

<ServiceVisual
  visual={{
    type: 'list',
    title: 'Environment status',
    meta: 'Illustrative',
    rows: [
      ['Backups verified', 'OK', 'ok'],
      ['Accounts without MFA', '3', 'warn'],
    ],
    statusLabels: { warn: 'to review' },
    foot: 'Illustrative format.',
  }}
/>

The other types, each in the tone the design draws it in. Bars print their share, or the row’s own words where it gives them; locale sets how a share is printed (12,5% in Spanish):

Traffic sources 30 days · Illustrative

• Organic search 48%
• Direct 22%
• Campaigns 18%
• Referrals 12.5%

Team composition Illustrative allocation

• Full-stack engineer Full time
• QA engineer Part time
• Technical lead Oversight

Fuentes de tráfico 30 días · Ilustrativo

• Búsqueda orgánica 47,5%
• Directo 22%
• Campañas 18%
• Referidos 12,5%

Risk priority matrix Illustrative

	Low impact	Medium impact	High impact
Likely	Monitor	Schedule	Act now
Possible	Accept	Monitor	Schedule
Unlikely	Accept	Accept	Monitor

Indicators Monthly · Illustrative

Tickets resolved

128

92% within target

First response

1 h 40 m

Target: 4 h

Availability

99.9%

Last 30 days

Open requests

12

Down from 19

Delivery cycle 2-week sprints

1. 01 Plan Scope and priorities.
2. 02 Build Small releases.
3. 03 Review A demo with the client.
4. 04 Ship Release and monitoring.

Architecture Reference

1. Channels

   • Web
   • Mobile
   • Internal panel

2. Services

   • API
   • Authentication
   • Payments

3. Data

   • Database
   • Files
   • Analytics

Page structure Wireframe

1. Header
2. Hero
3. Services
4. Social proof
5. Call to action

A light visual on the inverse band, as the home page’s audit sits:

Risk priority matrix Illustrative

	Low impact	Medium impact	High impact
Likely	Monitor	Schedule	Act now
Possible	Accept	Monitor	Schedule
Unlikely	Accept	Accept	Monitor

In a narrow column

The grids measure the visual, not the page: the frame is a container, and its cells take a column count that fills every row, so four tiles go one, then two, then four across, and five stay in one column rather than leave an orphan. The same visuals, side by side:

Indicators Monthly · Illustrative

Tickets resolved

128

92% within target

First response

1 h 40 m

Target: 4 h

Availability

99.9%

Last 30 days

Open requests

12

Down from 19

Delivery cycle 2-week sprints

1. 01 Plan Scope and priorities.
2. 02 Build Small releases.
3. 03 Review A demo with the client.
4. 04 Ship Release and monitoring.

Props

Prop	Type	Default	Notes
visual	ServiceVisualData	required	The visual as data: its type picks the body. See below.
tone	'dark' | 'light'	'dark'	The visual’s own palette, chosen for the band it sits on.
locale	string	'en'	BCP 47. How bars print a share; never the runtime’s language.
className	string	—	Placement, on the <figure>.
ref	Ref<HTMLElement>	—	The <figure>.
anything else	<figure> attributes	—	Except title and children: the title is the caption, not a tooltip.

Every visual takes title, and optionally meta (set opposite the title: the period, the scale, or that the figures are illustrative) and foot (a caveat or a source under the body). Then:

type	Fields	Drawn as
list	rows: [label, value, status?][], statusLabels?	Rows marked ok, warn or info (the default); the word follows the value.
bars	rows: [label, share, value?][]	Bars 6–100% long; the share printed, or value instead.
matrix	cols, rows: { label, cells }[], levels: Record<word, 1 | 2 | 3>	A table; each word takes its level wherever it appears.
tiles	items: [label, value, note?][]	Figures side by side, in balanced rows.
flow	steps: [name, description][]	Numbered steps, in balanced rows.
nodes	layers: { label, items }[]	Layers top to bottom, each listing its parts.
wire	blocks: [label, height][]	Blocks 2.4px per unit, never under 38px.

A matrix cell whose word has no level, or a row that does not fill every column, throws while rendering: a server render or a static build stops instead of shipping a hole in the table.

Exported types: ServiceVisualProps, ServiceVisualData, VisualType, and each type’s data and rows: ListVisualData, ListRow, BarsVisualData, BarRow, MatrixVisualData, MatrixRow, TilesVisualData, Tile, FlowVisualData, FlowStep, NodesVisualData, NodesLayer, WireVisualData, WireBlock. VisualTone, VisualStatus and VisualLevel come from the shared vocabulary.

Accessibility

• A <figure> named natively by its <figcaption>, the title then the meta: no id, no aria-labelledby to keep unique on the page.
• Each body is the native element for what it shows: lists for the status rows, bars, steps, layers and blocks; a <table> with column and row headers for the matrix; a description list pairing each tile’s label with its figure and note.
• Words carry every meaning, colour only repeats it: a status is said by its value and, where the list gives one, its statusLabels word; a matrix cell states its decision; a bar prints its share. The bars’ drawing, the markers and the printed step numbers are hidden from assistive technology.
• Every word is measured at 4.5:1 or more on the field it sits on, in both tones: the status words, each matrix word on its own cell, and the frame’s text on its panel, header and boxes.
• The lists drop their bullets with list-none, which makes Safari with VoiceOver stop announcing them as lists; the website keeps no role="list", and the kit keeps that parity.
• Long single words in the matrix, the tiles and the layers hyphenate with hyphens-auto, which needs lang on the page or an ancestor.

Without JavaScript

It needs none. Every part renders on the server, and the layout is CSS alone: the frame is a container, and the grids switch columns with container queries as the visual, not the page, widens.

Theming

surface-inverse, on-inverse-quiet (with opacity for the header, cells, muted text and track), primary-inverse and success and accent in the dark tone; surface-raised, surface, ink, muted, primary, success, accent, accent-strong, border-default, border-subtle and --ui-border-subtle in the light one. warn is drawn in accent, the design’s orange, where StatusTag draws it in warning: the word carries the meaning. A matrix’s urgent level sets its word in ink on accent, because on-accent is too faint there. The grids switch at the container widths --container-visual-split (24rem) and --container-visual-row (36rem).