# @lotics/ui

> The component kit for Lotics apps and the Lotics frontend — React DOM and plain CSS, one
> canonical entry per data role. Name the role, import the entry, read its `.d.ts` for props.

`import "@lotics/ui/styles.css"` once in the app entry: it carries every token the kit's
`var()`s read, and without it a screen renders unstyled but working.

Customize through TOKENS (the shadcn variables, the space rungs, the radius ladder, the type
family and ramp) and PROPS (`variant`, `size`, `tone`, `render`, slots); `className`/`style` on
an entry's root place it in your own layout. The DOM, the class names and the stylesheets are
private and carry no compatibility promise — a gap the props do not cover is closed by a kit
variant, never by CSS that reaches inside.

**A whole SCREEN is an entry too, and it is the one to reach for first.** The seven shapes a screen
plan names — `LifecycleDesk`, `PartyRegister`, `OfferingRegister`, `TransactionLedger`,
`MonitoredAssetSet`, `ObligationDesk`, `TrendDeepDive` — and the record their rows open,
`RecordPage` over `RecordFacts`, `RecordProgress`, `RecordExpectedSet`, `RecordChildren`
and `RecordFiles`. Each
takes its slots by the field ROLE the plan bound, and each has its row below with the question it
answers. `examples/` are for a screen none of them is.

**Which entry answers which role.** Each line reads *role → entry, its import, and the one
question that says where the entry does NOT go*. An indented line is a VARIANT of the role above
it, named by the prop the difference is or becomes; "folds into `X`" marks one the next major
absorbs, so write the call site as X. Props are the declaration beside the import:
`@lotics/ui/<module>` is `dist/<module>.d.ts`, carrying the source's own doc comments.

- a band of headline figures → `MetricStrip` `@lotics/ui/metric_strip` · Is the band over a REGISTER's rows?
- a board's pile → `BoardColumn` `@lotics/ui/board` · Is the count formatted into the heading?
- a board's record → `BoardCard` `@lotics/ui/board` · Does the card repeat the column it sits in?
- a body of pictures, scanned by where they belong → `MediaSet` `@lotics/ui/media_set` · Is the picture beside the row rather than the row itself?
- a bounded scroller → `ScrollArea` `@lotics/ui/scroll_area` · Is the page itself the scroller?
- a callout's body → `CalloutText` `@lotics/ui/callout` · Does the text carry a verb?
- a callout's headline → `CalloutTitle` `@lotics/ui/callout` · Is the headline the whole message?
- a callout's verbs → `CalloutActions` `@lotics/ui/callout` · Is the outcome one the reader does nothing about?
- a card's closing row → `CardFooter` `@lotics/ui/card` · Does the footer hold the primary act?
- a card's content → `CardBody` `@lotics/ui/card` · Is the content the whole card?
- a card's heading row → `CardHeader` `@lotics/ui/card` · Is the add verb elsewhere?
- a card's supporting heading detail → `CardHeaderMeta` `@lotics/ui/card` · Is the detail a status?
- a card's title → `CardHeaderTitle` `@lotics/ui/card` · Is the card a page section?
- a categorical cross-tab → `StateMatrix` `@lotics/ui/state_matrix` · Does a blank cell mean zero?
  - `StateMatrix axis="none"` · Are the positions named?
  - `StateMatrix mark="intensity"` · Does the reader need the NUMBER?
  - `StateMatrix onSelectState` · Is the legend informational?
- a centred overlay's body → `DialogScrollArea` `@lotics/ui/dialog` · Does the body swap content?
- a centred overlay's commit row → `DialogFooter` `@lotics/ui/dialog` · Is Save on the left?
- a centred overlay's heading row → `DialogHeader` `@lotics/ui/dialog` · Is there no title?
- a centred overlay's heading verbs → `DialogHeaderActions` `@lotics/ui/dialog` · Is the primary act here?
- a centred overlay's title → `DialogHeaderTitle` `@lotics/ui/dialog` · Is a size being passed?
- a change against a previous period → `Trend` `@lotics/ui/trend` · Is the direction meaningless?
- a checklist row's note → `ChecklistNote` `@lotics/ui/checklist` · Is the text a field's hint?
- a checklist row's verbs → `ChecklistActions` `@lotics/ui/checklist` · Is the verb about the whole list?
- a checklist's band of rows → `ChecklistGroup` `@lotics/ui/checklist` · Is the group a phase of a sequence?
- a child told its measured box → `AutoSizer` `@lotics/ui/auto_sizer` · Does the child already fill its parent?
- a chronological statement with a running balance → `RunningLedger` `@lotics/ui/running_ledger` · Is the balance supplied by the caller?
- a clarify wizard's action bar → `ClarifyWizardActions` `@lotics/ui/clarify_wizard` · Is there no `ClarifyWizardDialog` above it?
- a clarify wizard's dialog frame → `ClarifyWizardDialog` `@lotics/ui/clarify_wizard` · Is there a second wizard inside?
- a column's sort control → `SortHeader` `@lotics/ui/sort_header` · Does the set arrive sorted by the server?
- a cross-tab a reader FILLS → `EntryGrid` `@lotics/ui/entry_grid` · Is the cross-tab computed rather than filled in?
- a cross-tab's cells → `MatrixGrid` `@lotics/ui/matrix` · Are the totals inside it?
- a cross-tab's column headings → `MatrixHeader` `@lotics/ui/matrix` · Are the columns the subject?
- a cross-tab's heat legend → `MatrixLegend` `@lotics/ui/matrix` · Is there no wash behind the numbers?
- a cross-tab's totals → `MatrixTotals` `@lotics/ui/matrix` · Is the total computed off another array?
- a date field → `DatePicker` `@lotics/ui/date_picker` · Is the reader choosing a RANGE of days to report over?
  - `DatePicker format="time"` · Does the record keep the DAY as well?
- a date field's panel → `DatePickerPanel` `@lotics/ui/date_picker` · Is there a field to anchor it?
- a date in a register row → `DateCell` `@lotics/ui/shape_frame` · Is the date the system's own stamp?
  - `DateCell due` · Is the date a RECORD rather than a promise — issued on, received on?
- a date the system recorded → `DateStamp` `@lotics/ui/date_stamp` · Is the date something a person ENTERS?
- a decision that blocks everything else → `Alert` `@lotics/ui/alert` · Is the act DESTRUCTIVE?
  - `Alert tone` · Is the act a delete?
- a destination outside this screen → `Link` `@lotics/ui/link` · Does the press stay here?
- a dialog's back affordance → `DialogNavigationProvider` `@lotics/ui/dialog` · Is the dialog the kit's?
- a drill-down onto a reference → `Peek` `@lotics/ui/peek` · Does the row already press?
- a facet the reader can dismiss → `Chip` `@lotics/ui/chip` · Is it a status?
- a file identified by its NAME → `FileRow` `@lotics/ui/file_row` · Is the file a photo, a scan or a drawing?
- a file identified by its PICTURE → `FileThumbnail` `@lotics/ui/file_thumbnail` · Is the file a document?
- a file rendered in place → `FilePreview` `@lotics/ui/file_preview` · Is the turn meant to stick?
- a file's type mark → `FileBadge` `@lotics/ui/file_badge` · Is the file an image?
- a filter pill hosting its own editor → `FilterChip` `@lotics/ui/filter_chip` · Does the editor commit on its own?
  - `FilterChip column` · Is the facet's editor the caller's own?
- a fixed gap between siblings → `Spacer` `@lotics/ui/spacer` · Is the gap between every child of one run?
- a flat screen stack → `ScreenRouter` `@lotics/ui/screen_router` · Does the surface bring dialog chrome?
  - `ScreenRouterContext` `@lotics/ui/screen_router` — the context object, for a container that publishes navigation of its own · Are you READING the stack?
- a fold's body → `AccordionContent` `@lotics/ui/accordion` · Is the body a whole screen?
- a fold's heading row → `AccordionHeader` `@lotics/ui/accordion` · Is the content always open?
- a fold's supporting heading detail → `AccordionMeta` `@lotics/ui/accordion` · Is the detail the reason to open?
- a fold's title → `AccordionTitle` `@lotics/ui/accordion` · Is the title the section's?
- a glyph from the kit's set → `Icon` `@lotics/ui/icon` · Is the glyph the whole of a press?
- a grid of measures you edit in view → `DataGrid` `@lotics/ui/data_grid` · Is the set thousands of rows?
- a group's heading row → `SubsectionHeading` `@lotics/ui/section_heading` · Is the group a page section?
- a group's title → `SubsectionHeadingTitle` `@lotics/ui/section_heading` · Is a weight being passed?
- a hairline between blocks → `Divider` `@lotics/ui/divider` · Is it separating the rows of a register?
- a headline figure → `Metric` `@lotics/ui/metric` · Is the figure one of a band?
- a hint on hover → `TooltipContent` `@lotics/ui/tooltip` · Is the hint needed to act?
- a hint's frame → `Tooltip` `@lotics/ui/tooltip` · Is the hint what the control is FOR?
- a keystroke printed where it applies → `ShortcutBadge` `@lotics/ui/shortcut_badge` · Is there a keyboard?
- a labelled field → `FormField` `@lotics/ui/form_field` · Is the field in a record's value column?
  - `FormField layout="control-first"` · Does the control READ as the value?
- a ledger's basis line → `LedgerBasis` `@lotics/ui/ledger` · Is the figure part of the sum?
- a ledger's closing figure → `LedgerTotal` `@lotics/ui/ledger` · Is it computed off a different array?
- a ledger's line → `LedgerRow` `@lotics/ui/ledger` · Does the line need editing?
- a ledger's side → `LedgerGroup` `@lotics/ui/ledger` · Is there one side?
- a level against the limit it is read against → `LevelCell` `@lotics/ui/shape_frame` · Is there no limit?
- a lifecycle stage in a register row → `StageCell` `@lotics/ui/shape_frame` · Is the stage SET here?
- a link to another record → `ReferenceField` `@lotics/ui/reference_field` · Are the other record's fields on this one?
- a list body you pick from → `OptionList` `@lotics/ui/option_list` · Is there a field above it?
- a list whose ORDER the reader sets → `ReorderList` `@lotics/ui/reorder_list` · Does the order survive a reload?
  - `ReorderList reorder="buttons"` · Is the number of positions FIXED?
- a log of things that happened → `Timeline` `@lotics/ui/timeline` · Is the run PROGRESS?
- a long authored surface's outline → `SectionNav` `@lotics/ui/section_nav` · Is the surface a RECORD?
- a measured width, published to a subtree as buckets → `ContainerSizeProvider` `@lotics/ui/container_size` · Are you measuring here?
  - `ContainerSizeContext` `@lotics/ui/container_size` — the context object, for a shell that computed the buckets itself · Are you READING the size?
- a menu's trigger → `MenuButton` `@lotics/ui/menu_button` · Does the press DO something?
- a named group inside a region → `Subsection` `@lotics/ui/section_heading` · Is it a top-level block?
- a number the reader ENTERS → `NumberInput` `@lotics/ui/number_input` · Is the quantity continuous, and is the SHAPE of the range what the reader is choosing from?
  - `NumberInput stepper` · Is the target more than a few steps away?
  - `NumberInput format` · Is the notation a unit `Intl` cannot write?
- a numeric cross-tab → `Matrix` `@lotics/ui/matrix` · Is the cell a STATE rather than a number?
- a padded block → `Box` `@lotics/ui/box` · Is there more than one child to space?
- a page's content column → `SectionStack` `@lotics/ui/section_stack` · Are these the groups INSIDE one section?
  - `SubsectionStack` `@lotics/ui/section_stack` — the lower altitude — a section's own groups, at the 24px beat · Are these top-level page blocks?
- a period of the business, and what explains it → `TrendDeepDive` `@lotics/ui/trend_deep_dive` · Is the question about NOW rather than a period?
- a period the screen is filtered to → `DateFilter` `@lotics/ui/date_filter` · Does the reader NAVIGATE the period rather than choose it?
  - `DateFilter variant="field"` · Is the filter always on screen?
- a person shown inline → `MemberChip` `@lotics/ui/member_chip` · Is the member one field among columns?
- a pile of files browsed full-screen → `FileGalleryDialog` `@lotics/ui/file_gallery_dialog` · Is there one file?
- a pile of files read as a grid → `FileThumbnailGrid` `@lotics/ui/thumbnail_grid` · Are the files documents?
- a pile of files read as a list → `FileRows` `@lotics/ui/file_rows` · Is the pile mostly images?
- a placeholder in the shape of the content → `Skeleton` `@lotics/ui/skeleton` · Is the shape unknown?
- a plain value in a register row → `TextCell` `@lotics/ui/shape_frame` · Does the value have a KIND?
  - `TextCell grow` · Is the value in a REGISTER?
- a population with a level against a limit → `MonitoredAssetSet` `@lotics/ui/monitored_asset_set` · Is there no limit beside the level?
- a portal target for the subtree under it → `PortalHost` `@lotics/ui/portal` · Is the overlay the kit's?
- a post as one network would show it → `SocialPostPreview` `@lotics/ui/social_post_preview` · Is the network unstated?
- a quantity beside its subject → `Count` `@lotics/ui/count` · Is the number a STATUS?
- a quantity in a register row → `NumberCell` `@lotics/ui/shape_frame` · Is the quantity read against a limit?
- a raw payload, read → `RawPayload` `@lotics/ui/raw_payload` · Is the reader not a developer?
- a reachable contact in a register row → `ContactCell` `@lotics/ui/shape_frame` · Is the subject a person rather than a way to reach one?
- a receipt's outcome strip → `ResultHeader` `@lotics/ui/result_header` · Is the subject the record rather than what just happened to it?
- a recessed block inside a surface → `Well` `@lotics/ui/well` · Is the content a MESSAGE?
- a record ROW's attachments → `InlineFiles` `@lotics/ui/inline_files` · Are the files a whole SECTION?
- a record's fields, read at a glance → `RecordFacts` `@lotics/ui/record_facts` · Is the record a DRAFT the reader may abandon?
  - `RecordFacts onSave` · Is there an Edit mode to enter first?
- a record's files, pictures first → `RecordFiles` `@lotics/ui/record_files` · Is it ONE file, or does the section own a verb BAR?
  - `RecordFiles onRemove` · Is the removal wanted on the TILES?
- a record's identity band → `RecordSummary` `@lotics/ui/record_summary` · Is the subject the screen, or what just happened?
- a record's money, in two to four figures → `MoneyBand` `@lotics/ui/money_band` · Is there ONE figure?
- a region files can be dropped or pasted onto → `FileDropTarget` `@lotics/ui/file_drop_target` · Is the region a well?
- a region of a page → `Section` `@lotics/ui/section_heading` · Is the region INSIDE another section?
- a region with nothing to show yet → `RegionState` `@lotics/ui/region_state` · Is there still content in the region?
- a region's heading row → `SectionHeading` `@lotics/ui/section_heading` · Is the rung picked at the call site?
- a region's supporting heading detail → `SectionHeadingMeta` `@lotics/ui/section_heading` · Is the act in the meta slot?
- a region's title → `SectionHeadingTitle` `@lotics/ui/section_heading` · Is a size being passed?
- a register of records → `Table` `@lotics/ui/table` · Are all the columns measures you came to COMPARE?
  - `Table priority="never"` · Is the column merely important?
- a register row's subject → `IdentityCell` `@lotics/ui/shape_frame` · Is the mark the whole cell?
  - `IdentityCell lines` · Is the name the same length on every row — a code, a reference?
- a register's cell → `TableCell` `@lotics/ui/table` · Is the column hidden on narrow screens?
- a register's group band → `TableGroup` `@lotics/ui/table` · Does the register PAGE?
- a register's pager → `Pagination` `@lotics/ui/pagination` · Is there a second pager below the rows?
- a register's row → `TableRow` `@lotics/ui/table` · Is the extra fact needed by EVERY row?
- a register's rows as a list → `ListRows` `@lotics/ui/list_rows` · Do the rows carry three or more figures the reader compares ACROSS them?
- a register's rows as cards or picture tiles → `CardGrid` `@lotics/ui/card_grid` · Do the rows have nothing to be recognised BY?
  - `CardGrid variant="tile"` · Is the card carrying facts?
- a repeating weekly pattern → `Timetable` `@lotics/ui/timetable` · Do the slots fall on DATES?
- a required set against what a row holds → `ExpectedSetCell` `@lotics/ui/shape_frame` · Is the row's set the whole SECTION?
- a routed popover's stack → `PopoverNavContext` `@lotics/ui/popover_nav` · Are you reading the route?
- a row in a list you pick from → `ListItem` `@lotics/ui/list_item` · Is the row a RECORD in a register?
  - `ListItem variant="option"` · Does the right slot hold a CONTROL?
  - `ListItem overline` · Is the line the subject's STATE?
- a row that opens its record → `PressableRow` `@lotics/ui/pressable_row` · Does the row carry its own controls?
- a run of children on one axis → `Stack` `@lotics/ui/stack` · Is the run a screen's whole body?
  - `Stack columns` · Are the children unequal?
- a run of days, one row each, where the DAY is the record → `DaySheet` `@lotics/ui/day_sheet` · Are the rows the ENTRIES rather than the days?
- a run of language → `Text` `@lotics/ui/text` · Does the surface decide its size?
- a run of rows → `List` `@lotics/ui/list` · Are the rows columnar?
- a run of steps with a current position → `Stepper` `@lotics/ui/stepper` · Do the rows get MARKED by the reader?
- a screen stack's route registry → `ScreenRouterInternalContext` `@lotics/ui/screen_router` · Is a screen being registered?
- a screen's body → `PageContent` `@lotics/ui/page_content` · Is this inside an overlay?
  - `PageContent size` · Is the cap a number of your own?
- a screen's identity band → `PageHeader` `@lotics/ui/page_header` · Is the subject a RECORD?
- a scroller pinned to its newest content → `FollowScroll` `@lotics/ui/follow_scroll` · Is the reader browsing rather than watching?
  - `FollowScroll showJumpToLatest` · Does the feed grow at the TOP?
- a section's attachment surface → `FilesEditor` `@lotics/ui/files_editor` · Are the files one record ROW's, or a RECORD's own pile?
- a self-contained item → `Card` `@lotics/ui/card` · Is the card a GROUPING device?
- a semantic region of the page → `Landmark` `@lotics/ui/landmark` · Is the region already one?
- a series over time → `LineChart` `@lotics/ui/line_chart` · Is the last bucket partial?
- a set folded by one key, each row an aggregate over what that key holds → `GroupRegister` `@lotics/ui/group_register` · Is the row a RECORD?
- a set's shape → `Summary` `@lotics/ui/summary` · Do the buckets overlap?
  - `Summary total` · Is the figure a literal?
  - `Summary metrics` · Is the figure a slice of the set?
  - `Summary distribution=false` · Do the buckets add up to the whole?
- a setting that takes effect at once → `Switch` `@lotics/ui/switch` · Does the change need saving?
- a settings row that toggles → `SwitchRow` `@lotics/ui/switch_row` · Does the row hold a second control?
- a shape over time, at cell size → `Sparkline` `@lotics/ui/sparkline` · Are the values to be read?
- a side panel over the screen → `Drawer` `@lotics/ui/drawer` · Is the detail light?
- a side panel's body → `DrawerScrollArea` `@lotics/ui/drawer` · Does the panel step between records?
- a side panel's commit row → `DrawerFooter` `@lotics/ui/drawer` · Do the edits save on their own?
- a small overlay anchored to a control → `PopoverContent` `@lotics/ui/popover` · Is the content a form?
- a stack of labelled fields → `DetailTable` `@lotics/ui/detail_row` · Are the fields compared DOWN columns?
- a state with no second reading to contradict it → `Callout` `@lotics/ui/callout` · Did a CHECK produce it?
- a status a record wears → `Status` `@lotics/ui/status` · Is it a type, a category or a count?
- a subject over one qualifying line → `CellStack` `@lotics/ui/cell_stack` · Is the second line a SENTENCE?
- a text field → `TextInput` `@lotics/ui/text_input` · Is the value a number?
  - `TextInput type="search"` · Does the field hold a value the record keeps?
  - `TextInput font="mono"` · Is the value language a person wrote?
  - `TextInput reading="struck"` · Is the value ITSELF struck, or is the ROW done?
- a thread of comments → `CommentThread` `@lotics/ui/comments_thread` · Is the feed the agent's?
  - `CommentThread answer` · Is the mark a per-entry yes/no — read, flagged, pinned?
- a tile's remove → `RemoveButton` `@lotics/ui/file_thumbnail` · Is the tile in a selection surface?
- a titled fold → `Accordion` `@lotics/ui/accordion` · Is the fold inside prose?
- a trip read a day at a time → `Itinerary` `@lotics/ui/itinerary` · Does every stop answer the same facts?
- a typed pick's frame → `Combobox` `@lotics/ui/combobox` · Is the set small and fixed?
- a typed pick's no-matches row → `ComboboxEmpty` `@lotics/ui/combobox` · Is the field still empty?
- a typed pick's result list → `ComboboxContent` `@lotics/ui/combobox` · Are the rows the caller's own JSX?
  - `ComboboxContent footer` · Is the content pickable?
- a value against its maximum → `Progress` `@lotics/ui/progress` · Is there no maximum?
  - `Progress shape="ring"` · Is the reading taken as a LENGTH — down a column of them, or across a band?
- a value checked against an expected one → `VerifyField` `@lotics/ui/verify_field` · Is there nothing to match against?
- a value picked along a range → `Slider` `@lotics/ui/slider` · Does the exact number matter?
- a value put on the clipboard → `CopyButton` `@lotics/ui/copy_button` · Is the verb about the ROW?
- a value that changed → `DiffValue` `@lotics/ui/diff_value` · Is the row's own change the point?
- a value that is not an editor, on the inline-control grid → `InlineValue` `@lotics/ui/inline_value` · Does the value edit?
- a well that asks for files → `FileDropzone` `@lotics/ui/file_dropzone` · Does the surface already hold files?
- a whole ranked by share → `Breakdown` `@lotics/ui/breakdown` · Is the tail long?
- a yes-or-no answer in a register row → `VerdictCell` `@lotics/ui/shape_frame` · Is the answer a STATE rather than a verdict?
- an act INSIDE a field's own box — auto-fill, open the link, call the number → `InlineButton` `@lotics/ui/inline_button` · Is the act outside a field?
- an act with a glyph and no name → `IconButton` `@lotics/ui/icon_button` · Would a word fit?
- an act with a name → `Button` `@lotics/ui/button` · Is the control icon-only?
- an agent run's action bar → `AgentRunActions` `@lotics/ui/agent_run` · Is the bar inside the feed?
- an agent run's dialog frame → `AgentRunDialog` `@lotics/ui/agent_run` · Does the surface have no footer?
- an agent's work, live → `AgentRun` `@lotics/ui/agent_run` · Is the run finished?
  - `AgentRun variant="pane"` · Is the run incidental to the screen?
  - `AgentRun variant="pill"` · Is the run the screen's subject?
- an amount in a register row → `MoneyCell` `@lotics/ui/shape_frame` · Is the amount TYPED here?
- an anchored overlay's back row → `PopoverNavHeader` `@lotics/ui/popover_nav` · Can the reader go back?
- an anchored overlay's commit row → `PopoverFooter` `@lotics/ui/popover` · Does the editor commit on its own?
- an anchored overlay's frame → `Popover` `@lotics/ui/popover` · Is the panel anchored to nothing?
- an anchored overlay's heading row → `PopoverHeader` `@lotics/ui/popover` · Is the popover one line?
- an anchored overlay's trigger → `PopoverTrigger` `@lotics/ui/popover` · Does the child install an `onClick` of its own?
- an app's own mark → `AppIcon` `@lotics/ui/app_icon` · Is the subject a record rather than an app?
- an attachment surface's verb band → `FilesEditorBar` `@lotics/ui/files_editor` · Is the Add elsewhere?
  - `FilesEditorBar verbs` · Is the act yours rather than the editor's?
- an exclusive choice, all options visible → `ChoiceStrip` `@lotics/ui/choice_strip` · Are there more than a few options?
  - `ChoiceStrip variant="chips"` · Do the positions have to stay fixed?
  - `ChoiceStrip overflow="scroll"` · Is this a required select in a form?
- an explainer behind a ⓘ → `InfoPopover` `@lotics/ui/info_popover` · Is there more here than a sentence?
- an identity mark → `Avatar` `@lotics/ui/avatar` · Is the subject a THING?
- an ordered sequence carried out a step at a time → `GuidedRun` `@lotics/ui/guided_run` · Are the rows a SET the reader works in any order?
- an outside channel's logo → `BrandMark` `@lotics/ui/brand_mark` · Is the glyph the app's own language?
- an overlay over the page → `Dialog` `@lotics/ui/dialog` · Is it mounted while closed?
- audio or video played in place → `MediaPlayer` `@lotics/ui/media_player` · Is the file an image?
- categories compared → `BarChart` `@lotics/ui/bar_chart` · Do the parts make a whole?
- content rendered into the nearest portal host → `Portal` `@lotics/ui/portal` · Is there no host above it?
- dated movements in a book → `TransactionLedger` `@lotics/ui/transaction_ledger` · Is the money PRICED here rather than read?
- how a figure got from one level to another → `WaterfallChart` `@lotics/ui/waterfall_chart` · Are the steps independent?
- how sure a judgement is → `ConfidenceCallout` `@lotics/ui/confidence_callout` · Are the reasons missing?
- incoming columns, each assigned to one of a known set → `ColumnMap` `@lotics/ui/column_map` · Is the reader picking ONE thing?
- inked text inside a run that navigates → `TextLink` `@lotics/ui/text_link` · Is it the row's own destination?
- money you are PRICING → `ChargeLines` `@lotics/ui/charge_lines` · Is the money already settled?
- money you are READING → `Ledger` `@lotics/ui/ledger` · Is anything typed into it?
- N independent booleans across fixed positions → `ToggleStrip` `@lotics/ui/toggle_strip` · Is the choice exclusive?
- named destinations within one screen → `Tabs` `@lotics/ui/tabs` · Do the tabs have an ORDER the work follows?
- nested cohorts that shrink → `Funnel` `@lotics/ui/funnel` · Do the stages partition one set?
- one boolean → `Checkbox` `@lotics/ui/checkbox` · Is the whole row the control?
  - `Checkbox without onChange` · Can the reader change it?
  - `Checkbox shape="ring"` · Does ticking mean CHOSEN?
- one figure read against a reference figure → `ComparisonBar` `@lotics/ui/comparison_bar` · Is the second number a CEILING?
- one labelled field → `DetailRow` `@lotics/ui/detail_row` · Is the label a column heading?
- one of N, each with a description → `ChoiceList` `@lotics/ui/choice_list` · Do the options need no description?
  - `ChoiceList allowCustom` · Is the option set the whole answer?
- one pane of a split row → `SplitPane` `@lotics/ui/split_row` · Is it standing alone?
- one priced line → `ChargeLine` `@lotics/ui/charge_lines` · Is the derived amount on a second line?
- one ranked discrepancy → `Finding` `@lotics/ui/finding` · Is there only one reading?
- one record type walking ordered stages → `LifecycleDesk` `@lotics/ui/lifecycle_desk` · Does the record have no stages?
- one record, whole → `RecordPage` `@lotics/ui/record_page` · Is the subject the LIST?
  - `RecordPage danger` · Is the delete a `danger` `Button` handed in?
- one row of a reorderable list → `ReorderItem` `@lotics/ui/reorder_item` · Is the position stored on the row?
- one screen of a navigation stack → `Screen` `@lotics/ui/screen_router` · Is there only one screen?
- one screen of a routed popover → `PopoverScreen` `@lotics/ui/popover_nav` · Is there one panel?
- one step of a run → `Step` `@lotics/ui/stepper` · Is the step a task?
- one tab → `TabItem` `@lotics/ui/tabs` · Are you rendering a strip the kit ships?
- one thing the reader marks → `ChecklistItem` `@lotics/ui/checklist` · Did an inspection SETTLE it?
- one value per subject and period, filled in → `EntryMatrix` `@lotics/ui/entry_matrix` · Does the row stand for one record?
- parts of one whole → `PieChart` `@lotics/ui/pie_chart` · Are there many slices?
- pick a person → `MemberSelect` `@lotics/ui/member_select` · Is the filter meant to match UNASSIGNED rows too?
- pick by typing → `ComboboxInput` `@lotics/ui/combobox` · Is the set small and fixed?
- pick one from a list → `Select` `@lotics/ui/select` · Does the reader type to find the value?
  - `Select native` · Does an option need a colour or a face?
  - `Select size="md"` · Is this a form field, a value column or an option list?
- piles you MOVE records between → `Board` `@lotics/ui/board` · Are the columns bands of rows?
- priced lines being decided, footed part by part → `Worksheet` `@lotics/ui/worksheet` · Has the money already moved?
- prose the reader writes → `MarkdownEditor` `@lotics/ui/markdown_editor` · Is the prose read-only here?
  - `MarkdownEditor surface="field"` · Is the whole surface the document?
- several images browsed in place → `ImageGallery` `@lotics/ui/image_gallery` · Is the surface an overlay?
- several marks capped in one cell → `MarkStack` `@lotics/ui/mark_stack` · Is the stack the row's door?
- several wholes compared → `StackedBarChart` `@lotics/ui/stacked_bar_chart` · Is there ONE whole?
- stored prose, rendered → `Markdown` `@lotics/ui/markdown` · Is the prose editable here?
- text that unfolds more text → `TextDisclosure` `@lotics/ui/text_disclosure` · Does the reveal need a heading and a body?
- the agent asking back → `ClarifyWizard` `@lotics/ui/clarify_wizard` · Is the question a CONFIRMATION of an act?
  - `ClarifyWizard questions` · Is there one question?
- the app root's hint timing → `TooltipProvider` `@lotics/ui/tooltip` · Is a `Tooltip` missing without it?
- the app root's string pack → `LoticsLocaleProvider` `@lotics/ui/locale` · Is one instance the odd one out?
- the app root's toast host → `ToastProvider` `@lotics/ui/toast` · Is the strip meant to sit inside the page?
- the box around a field that saves itself → `FieldSurface` `@lotics/ui/field_surface` · Is the control a plain one?
- the deadlines a set of records owe, one row each → `ObligationDesk` `@lotics/ui/obligation_desk` · Is the row the RECORD?
- the destructive section → `DangerSection` `@lotics/ui/danger_section` · Is the act reversible?
  - `DangerSection actions` · Is the act a `danger` `Button` passed as a child?
- the element a hint describes → `TooltipTrigger` `@lotics/ui/tooltip` · Does the child drop the props it is handed?
- the heading rung a pane publishes → `HeadingSurfaceContext` `@lotics/ui/heading_surface` · Is the pane one the kit renders?
- the keyboard's shortcut past the chrome → `SkipLink` `@lotics/ui/skip_link` · Is there a landmark to skip TO?
- the keyboard's way into a row that holds controls → `RowFocusEntry` `@lotics/ui/row_focus_entry` · Does the row hold nothing but text?
- the operation's units and what state each is in, right now → `LiveBoard` `@lotics/ui/live_board` · Is the reader asking about a PERIOD?
- the overflow menu on a row or a header → `ActionMenu` `@lotics/ui/action_menu` · Is there one act?
- the people and organisations you have a relationship with → `PartyRegister` `@lotics/ui/party_register` · Is the subject sold rather than dealt with?
- the record's headline figure, alone → `RecordFigure` `@lotics/ui/record_summary` · Does the surface also draw the record's NAME?
- the register anatomy every screen shape configures → `ShapeFrame` `@lotics/ui/shape_frame` · Is the screen one the registry names?
  - `ShapeFrame rowActions` · Is the row's verb a glyph in a column of its own?
  - `ShapeFrame danger` · Is the bulk delete inside `selection.actions`?
- the registers that NAME a record, counted → `RecordRelated` `@lotics/ui/record_related` · Do the rows BELONG to the record?
- the rows that belong to one record → `RecordChildren` `@lotics/ui/record_children` · Are the rows the record's SIBLINGS?
  - `RecordChildren rowActions` · Is the drawer the row's only door?
  - `RecordChildren group` · Can the reader already read the key down a COLUMN?
- the scope the screen is showing → `ScopeSwitcher` `@lotics/ui/scope_switcher` · Is there one scope?
- the small word that names something else → `Label` `@lotics/ui/label` · Is it a heading?
  - `Label over="block"` · Is the thing labelled a VALUE?
- the surface that starts agent work → `Composer` `@lotics/ui/composer` · Is the field a record's?
- the toolbar above a list → `FilterBand` `@lotics/ui/filter_band` · Is a facet empty?
- the verbs for a selection → `SelectionBar` `@lotics/ui/selection_bar` · Is nothing selected?
  - `SelectionBar danger` · Is the bulk delete one of the `children`?
- the way into a thread → `CommentsButton` `@lotics/ui/comments_button` · Are there no comments?
- the way out of a pushed screen → `BackButton` `@lotics/ui/back_button` · Can the reader go back?
- the width a region measures itself against → `SizeBoundary` `@lotics/ui/size_boundary` · Is the question about the DEVICE?
- things scheduled, days on the axis → `CalendarView` `@lotics/ui/calendar` · Are RESOURCES the axis — a vehicle, an owner, a channel?
  - `CalendarView renderEvent` · Is the replacement a `Chip`?
- things scheduled, resources on the axis → `GanttView` `@lotics/ui/gantt` · Is time the only axis?
- things the reader MARKS → `Checklist` `@lotics/ui/checklist` · Are the same four values compared across twenty rows?
- two panes side by side → `SplitRow` `@lotics/ui/split_row` · Is the pair meaningless apart — a value and its unit, a control and its field?
- two sources that must agree, and what is left over → `ReconciliationDesk` `@lotics/ui/reconciliation_desk` · Is the row one book's line?
- what a filtered register adds up to → `TotalsLine` `@lotics/ui/totals_line` · Does it describe the UNFILTERED set?
- what a record is required to hold, against what it has → `RecordExpectedSet` `@lotics/ui/record_expected_set` · Is the list what was FILED?
  - `RecordExpectedSet kind` · Are the required things DOCUMENTS?
  - `RecordExpectedSet onRemove` · Can a document filed against the wrong slot stay there?
- what happened to a row → `DiffMark` `@lotics/ui/diff_mark` · Is the row unchanged and unremarkable?
- what you sell, at a price, with what is available → `OfferingRegister` `@lotics/ui/offering_register` · Is the row a counterparty?
- where a record is in its lifecycle → `RecordProgress` `@lotics/ui/record_progress` · Is the stage PICKED here?
  - `RecordProgress confirm` · Is every stage move worth stopping for?
- where a value came from → `Sources` `@lotics/ui/sources` · Are the sources already the content?
- which side of a form's fields is marked → `FormMarksContext` `@lotics/ui/form_field` · Is the question whether THIS field may be empty?
- who a person IS → `MemberPeek` `@lotics/ui/member_peek` · Does the row already press?
- whose move it is, and how long they have → `Awaiting` `@lotics/ui/awaiting` · Is nobody owed anything by that date?
- work in flight, with no known duration → `ActivityIndicator` `@lotics/ui/activity_indicator` · Is the progress known?
  - `ActivityIndicator variant="dots"` · Is this the only thing on screen saying so?
- work put on a resource, in order, under a ceiling → `ResourceSchedule` `@lotics/ui/resource_schedule` · Is the register the WORK rather than the resources it is put on?

## Hooks, helpers, stylesheets

- `@lotics/ui/colors` — `colors`, `labelTone`, `withAlpha`, `solid`, `tint`, `ramp`, …
- `@lotics/ui/column_filter` — `columnFilterToConditions`, `isColumnFilterActive`, `columnFilterSummary`
- `@lotics/ui/commit_mode` — types only
- `@lotics/ui/control_surface` — `CONTROL_HEIGHT`, `CONTROL_CONTENT_HEIGHT`, `CONTROL_PADDING_V`, `MIN_CONTROL_WIDTH`, `MIN_VALUE_WIDTH`, `CONTROL_RADIUS`, …
- `@lotics/ui/copy_text` — `copyText`
- `@lotics/ui/date_picker_value` — `isRangeFormat`, `hasTimeFormat`, `pad`, `parsePart`, `partsToIso`, `isoToDate`, …
- `@lotics/ui/deadline` — `daysUntil`, `deadlineTone`, `deadlineColor`, `countdownLabel`, `deadlineAnnotation`, `nearestDeadline`, …
- `@lotics/ui/download` — `downloadFileFromUrl`, `canShareFiles`, `prepareShareFiles`, `shareFiles`, `shareOrDownloadFiles`
- `@lotics/ui/file_badge_fit` — `FILE_BADGE_DEFAULT_WIDTH`, `FILE_BADGE_BOX`, `fileBadgeHeight`, `fileBadgeWidthForBox`
- `@lotics/ui/file_picker` — `pickFiles`
- `@lotics/ui/fonts.css` — THE DEFAULT FACE — one family, three weights, which is what makes an ordinary numeric `font-weight` select a real face.
- `@lotics/ui/format_date` — `parseDate`, `toISODate`, `formatDate`
- `@lotics/ui/format_money` — `formatCompactNumber`, `formatMoney`
- `@lotics/ui/just_arrived` — `arrivalsSince`, `useJustArrived`
- `@lotics/ui/live_board_rank` — `BOARD_CONDITIONS`, `boardCondition`, `rankUnits`
- `@lotics/ui/remark_gfm_safe` — `remarkGfmSafe`
- `@lotics/ui/matrix_totals` — `matrixHeatScale`, `matrixTotals`
- `@lotics/ui/mime` — `isImageMimeType`, `isVideoMimeType`, `isAudioMimeType`, `isPdfMimeType`, `isExcelMimeType`, `isCsvMimeType`, …
- `@lotics/ui/option_picker` — `fieldPicker`, `optionPicker`
- `@lotics/ui/organization_name` — `stripLegalForm`
- `@lotics/ui/overlay_layer` — `OVERLAY_Z`, `OVERLAY_Z_ABOVE`, `NOTIFICATION_Z`, `SKIP_LINK_Z`
- `@lotics/ui/overlay_scope` — `isOverlayScopeActive`, `pushOverlayScope`, `useOverlayScope`, `useOverlayOpenChange`
- `@lotics/ui/overlay_sheet` — `useSheetPresentation`, `SHEET_POSITIONER_STYLE`
- `@lotics/ui/register_band` — `REGISTER_ROW`, `REGISTER_HEAD`, `REGISTER_INSET`, `REGISTER_CELL_GAP`, `columnsShareSlack`
- `@lotics/ui/rotate_image` — `rotateImageToBlob`
- `@lotics/ui/route_matching` — `routeMatches`, `parseRouteParams`, `findBestPattern`, `shouldRouteMatch`
- `@lotics/ui/search_match` — `normalizeForSearch`, `codeKey`, `codeMatches`
- `@lotics/ui/social_post_rules` — `SOCIAL_NETWORKS`, `SOCIAL_NETWORK_RULES`, `SOCIAL_NETWORK_LABELS`, `countSocialChars`, `socialPostIssues`, `socialPostIssueText`
- `@lotics/ui/spacing` — `SPACE_RUNGS`
- `@lotics/ui/style_props` — `assignRef`, `composeRefs`, `cn`, `styleParts`
- `@lotics/ui/styles.css` — THE ONE ENTRY POINT — layer order, the tokens and the reset.
- `@lotics/ui/system-dark.css` — OS-FOLLOWS DARK MODE — opt in with `@import "@lotics/ui/system-dark.css"`.
- `@lotics/ui/table_fit` — `ROW_HEIGHT`, `ROW_GUTTER`, `FLEX_MIN_WIDTH`, `fixedColumnWidth`, `columnFloor`, `columnBasis`, …
- `@lotics/ui/tailwind-type.css` — TAILWIND PRESET — type and radius.
- `@lotics/ui/tailwind.css` — TAILWIND PRESET — colour.
- `@lotics/ui/text_ink` — `TEXT_INK`, `TEXT_COLORS`, `getTextColor`, `getInkColor`, `textInkTokens`, `blendInk`
- `@lotics/ui/trend_buckets` — `startOfDay`, `daySpan`, `dayAfter`, `bucketUnit`, `bucketsOf`, `parseWhen`, …
- `@lotics/ui/type_ramp` — `TYPE_RAMP_MOBILE`, `TYPE_RAMP_DESKTOP`, `TYPE_LEADING_TIGHT_MOBILE`, `TYPE_LEADING_TIGHT_DESKTOP`, `TYPE_TRACKING`, `trackingPx`
- `@lotics/ui/use_async_fn` — `useAsyncFn`
- `@lotics/ui/use_change_set` — `useChangeSet`
- `@lotics/ui/use_copy_feedback` — `useCopyFeedback`
- `@lotics/ui/use_debounced_callback` — `useDebouncedCallback`
- `@lotics/ui/use_form` — `useForm`
- `@lotics/ui/use_image_rotation` — `useImageRotation`
- `@lotics/ui/use_long_press` — `useLongPress`
- `@lotics/ui/use_persisted_state` — `usePersistedState`, `oneOf`, `asText`, `asStringSet`, `asSortState`
- `@lotics/ui/use_screen_size` — `useScreenSize`
- `@lotics/ui/use_section_nav` — `useSectionNav`
- `@lotics/ui/use_selection` — `useSelection`
- `@lotics/ui/use_selection_mode` — `useSelectionMode`
- `@lotics/ui/vite` — `loticsResolve`, `loticsFsAllow`, `loticsOptimizeDeps`

## Example screens — copy one, never import it

- [tpl_allocate](examples/tpl_allocate.tsx): The split — one amount spread across targets until the remainder is zero.
- [tpl_attendance](examples/tpl_attendance.tsx): The attendance desk — presence per person per day, corrected in place.
- [tpl_board](examples/tpl_board.tsx): The column board — records as cards in stage columns, moved by drag or menu.
- [tpl_calendar](examples/tpl_calendar.tsx): The week desk — a calendar whose events are records, moved in place.
- [tpl_dashboard](examples/tpl_dashboard.tsx): The trend deep-dive — a period of the business and what explains it.
- [tpl_item_list](examples/tpl_item_list.tsx): THE canonical register — search, filters, a table, a drawer onto one row.
- [tpl_lookup](examples/tpl_lookup.tsx): The answer desk — a question, the answer, and the sources behind it.
- [tpl_money](examples/tpl_money.tsx): THE money surface for one record — charges, tax, payments, what is owed.
- [tpl_pick](examples/tpl_pick.tsx): The guided queue — one task at a time, scanned and confirmed, no skipping.
- [tpl_pivot](examples/tpl_pivot.tsx): The cross-tab desk — one measure by two dimensions, totals at both edges.
- [tpl_record](examples/tpl_record.tsx): The HISTORY-heavy record — a handoff chain, a comment thread and an activity trail under an outline rail; `RecordPage` is the record surface itself.
- [tpl_rollup](examples/tpl_rollup.tsx): Hierarchical totals — a tree of groups whose figures roll up to the parent.

## Reference

- [AGENTS.md](AGENTS.md): @lotics/ui — the UI reference index
- [docs/ai_patterns.md](docs/ai_patterns.md): AI patterns — AI proposes, the human decides
- [docs/catalog.md](docs/catalog.md): @lotics/ui — where each entry does NOT go
- [docs/composition.md](docs/composition.md): Composition grammar
- [docs/constitution.md](docs/constitution.md): The constitution
- [docs/data_entry.md](docs/data_entry.md): Data entry — which pattern for which job
- [docs/hierarchy.md](docs/hierarchy.md): Hierarchy — what a screen shows, and at what weight
- [docs/reviewing.md](docs/reviewing.md): Reviewing a screen you built
- [docs/templates.md](docs/templates.md): Templates — the worked example screens
- [docs/testing.md](docs/testing.md): Testing the kit
- [docs/theming.md](docs/theming.md): Theming