Components

Component family index

Initial TCRN component families and the spec/usage/state pattern each component should grow into.

Recommended component families

Component familyRecommended componentsScopeComponent status

ActionsButton, IconButton, LinkButton, ClipboardCopyButtonCommands, blocked owner actions, and explicit clipboard writesComponent library available

IconographyIcon, tcrnIconNamesFunctional iconography routed through the TCRN wrapperComponent library available; not brand marks

FormsField, Input, Textarea, SearchInput, Select, CheckboxPersistent labels, hint/error wiring, disabled reasons, and localized input ergonomicsComponent library available

NavigationTopBar, SideNav, NavGroup, NavItem, Breadcrumb, ModuleTabs, SectionTabs, SegmentedNav, ProductSwitcher, Pagination, SkipLinkProduct orientation, side navigation, local section movement, and skip accessComponent library available; full shells remain prototypes

OverlaysDetailDrawer, ActionDrawer, Tooltip, Popover, Dialog, ConfirmActionDialogLayered surfaces, supplemental descriptions, anchored popovers, focus entry, and close/return contractsComponent library available; Tooltip is non-interactive only

Data displayTableShell, WorkIndex, StatusBadge, KeyValueListDense scanning, readable state, and empty/error distinctionComponent library available; DataGrid not included

Feedback and readinessBadge, InlineAlert, LiveRegion, Skeleton, StateSurface, EmptyState, ErrorState, EnvironmentBanner, GateReadinessPanel, EvidenceStrip, ReadbackPanel, StateViewLoading, blocked, unknown, empty, error, and proof-dependent statesComponent library available

Layout and textText, Heading, Highlight, Surface, Divider, CollapsibleRegion, DisclosurePanel, FilterBarSpacing floor, headings, inline highlighting, sections, dividers, controlled disclosure, and filter groupingComponent library available

Brand and identityTcrnBrandMark, ProductLockup, ShellBrandLockupTCRN mother brand and product suffix treatmentStorybook prototypes; not reusable component exports

Package-backed component API

Public exportSource packageLibrary status

Button@tcrn/ui-reactLocal proof only

Icon@tcrn/ui-reactLocal proof only

IconButton@tcrn/ui-reactLocal proof only

LinkButton@tcrn/ui-reactLocal proof only

ClipboardCopyButton@tcrn/ui-reactLocal proof only

Field@tcrn/ui-reactLocal proof only

Input@tcrn/ui-reactLocal proof only

Textarea@tcrn/ui-reactLocal proof only

SearchInput@tcrn/ui-reactLocal proof only

Select@tcrn/ui-reactLocal proof only

Checkbox@tcrn/ui-reactLocal proof only

Badge@tcrn/ui-reactLocal proof only

EmptyState@tcrn/ui-reactLocal proof only

ErrorState@tcrn/ui-reactLocal proof only

Highlight@tcrn/ui-reactLocal proof only

StatusBadge@tcrn/ui-reactLocal proof only

StateSurface@tcrn/ui-reactLocal proof only

StateView@tcrn/ui-reactLocal proof only

InlineAlert@tcrn/ui-reactLocal proof only

LiveRegion@tcrn/ui-reactLocal proof only

Skeleton@tcrn/ui-reactLocal proof only

EnvironmentBanner@tcrn/ui-reactLocal proof only

GateReadinessPanel@tcrn/ui-reactLocal proof only

EvidenceStrip@tcrn/ui-reactLocal proof only

ReadbackPanel@tcrn/ui-reactLocal proof only

Text@tcrn/ui-reactLocal proof only

Heading@tcrn/ui-reactLocal proof only

Surface@tcrn/ui-reactLocal proof only

Divider@tcrn/ui-reactLocal proof only

CollapsibleRegion@tcrn/ui-reactLocal proof only

DisclosurePanel@tcrn/ui-reactLocal proof only

KeyValueList@tcrn/ui-reactLocal proof only

FilterBar@tcrn/ui-reactLocal proof only

TableShell@tcrn/ui-reactLocal proof only

WorkIndex@tcrn/ui-reactLocal proof only

DetailInspector@tcrn/ui-reactLocal proof only

Breadcrumb@tcrn/ui-reactLocal proof only

ModuleTabs@tcrn/ui-reactLocal proof only

SectionTabs@tcrn/ui-reactLocal proof only

SegmentedNav@tcrn/ui-reactLocal proof only

Pagination@tcrn/ui-reactLocal proof only

TopBar@tcrn/ui-reactLocal proof only

SideNav@tcrn/ui-reactLocal proof only

NavGroup@tcrn/ui-reactLocal proof only

NavItem@tcrn/ui-reactLocal proof only

ProductLauncher@tcrn/ui-reactLocal proof only

ProductSwitcher@tcrn/ui-reactLocal proof only

SkipLink@tcrn/ui-reactLocal proof only

DetailDrawer@tcrn/ui-reactLocal proof only

ActionDrawer@tcrn/ui-reactLocal proof only

Tooltip@tcrn/ui-reactLocal proof only

Popover@tcrn/ui-reactLocal proof only

Dialog@tcrn/ui-reactLocal proof only

ConfirmActionDialog@tcrn/ui-reactLocal proof only

Package utility exports

Public exportSource packageLibrary status

tcrnIconNames@tcrn/ui-reactLocal proof only

Storybook-only prototypes

PrototypeScopeDisposition

TcrnBrandMarkSynthetic brand review visualsStorybook prototype; not a component library export

ProductLockupSynthetic brand review visualsStorybook prototype; not a component library export

ShellBrandLockupSynthetic brand review visualsStorybook prototype; not a component library export

TmsDenseShellDemoDense product shell IA comparisonStorybook prototype; full shell deferred

KnowledgeBaseShellDemoDocumentation shell IA comparisonStorybook prototype; full shell deferred

CompactToolShellDemoFocused tool shell comparisonStorybook prototype; shell framework deferred

Current local story coverage

Work itemStateOwner

Button and clipboard actionLocal proof onlyui-react

Display primitivesLocal proof onlyui-react

Interaction disclosure primitivesLocal proof onlyui-react

FieldProof requiredui-react

Navigation shellProof requiredui-react

DialogProof requiredui-react

WorkIndexFixture onlyui-react

Brand lockupNot claimedStorybook prototype

Story template

Spec: purpose, anatomy, states, accessibility expectation
Usage: props, disabled behavior, empty/error examples, proof notes
Copy: localized labels, blocked terms, disabled reasons

Navigation shell components are first-class component contracts, not only page patterns.

Display primitives spec

Owner-approved foundational display primitives for highlighting, loading skeletons, and state surfaces.

Owner-approved first batch

This contract story documents only the first approved Gemini candidate batch: inline highlight text, loading skeletons, and presentation-only state surfaces. Interaction disclosure and clipboard primitives are documented separately; masking, animated counters, DataGrid, query builder, and command palette remain deferred or rejected.

owner review completedpackage-backed primitivesStorybook evidence onlyconsumer adoption separate

Highlight

Search proof highlights proof matches without changing the source text.

RuleProof

Renders inline semantic marksUses <mark> for matched substrings

No HTML injectionSource text stays React-escaped text nodes

No search engine claimProduct owns query state and result ranking

Skeleton

Skeletons are decorative placeholders. Loading announcements stay with the owning product surface through aria-busy or LiveRegion.

State surfaces

Proof route needed

The owner must route verification before downstream claims.

No local rows

Clear filters or add a synthetic fixture.

Panel unavailable

Products must sanitize error copy before passing it into this presentation primitive.

These primitives do not implement React ErrorBoundary wrappers, telemetry, product error policy, publication, package release, or product adoption.

Interaction disclosure spec

Owner-approved second-batch primitives for supplemental tooltips and controlled disclosure regions.

Owner-approved second batch

This contract story documents only the second approved Gemini candidate batch: supplemental, non-interactive Tooltip and controlled DisclosurePanel/CollapsibleRegion primitives. Clipboard is documented in the button/action story; form shake validation, masking, animated counters, DataGrid, query builder, and command palette remain deferred or rejected.

owner review completeda11y constrainedpackage-backed primitivesconsumer adoption separate

Tooltip

RuleBlocked

Adds supplemental aria-describedby copyTooltip as the only label

Text-only, non-interactive contentButtons, links, forms, or menus inside tooltip

Hover and focus reveal onlyMobile long-press or tap interaction claim

Disclosure

Expanded controlled region

Products own the trigger and state. The package primitive owns the region animation and hidden-content semantics.

Collapsed controlled region

Low-level collapsible regions may be used when a visible title is owned by surrounding product copy.

RuleBlocked

Controlled by expanded propPackage-owned route state

Collapsed content records aria-hidden and inertTabbable hidden controls

Reduced motion snaps open or closedMotion as comprehension requirement

These primitives do not implement Accordion semantics, drawers, clipboard, sensitive-data masking, product filtering, log viewing, publication, package release, or product adoption.

Button spec and usage

Button variants, disabled reason behavior, and accessible blocked actions.

Spec

Disabled usage

Visible button labels stay clean; disabled reasons are exposed through title and assistive text.

Clipboard copy action

ClipboardCopyButton is a package-backed button action for explicitly copying product-approved values without exposing the copied payload through callbacks, DOM attributes, logs, or Storybook claims.

RuleBlocked

Uses native button semantics and explicit click or keyboard activationWrapper spans, hover, mount, timer, or implicit copying

Writes with navigator.clipboard.writeText when availableClipboard reads or document.execCommand fallback

Reports only idle/copying/copied/failed/unsupported statesCallbacks, DOM attributes, or telemetry that include copied text

Field spec and usage

Field labeling, hints, errors, disabled controls, and aria relationships.

Search fixtureHint text stays visible in weak emphasis; ordinary search fields keep the search icon but do not show a keyboard shortcut.Navigation shell search fixtureShortcut labels are allowed only for navigation or shell search with a real focus target and visible result list.StateDisabled controls keep visible labels clean.NotesTextarea follows the same disabled reason contract as other form controls.Text inputShort codeShort fields keep measured width for codes, counts, and compact filters.Invalid stateHint text is visible and retained in the DOM.Synthetic validation message

Field width rules

PatternWidthUsage

Search inputFull widthSearch and prose-like filters keep the row width.

Short inputMeasured widthCodes, counts, compact filters, and bounded values stay short.

Search shortcut rules

SurfaceShortcutUsage

Ordinary search fieldNo shortcut labelUse inside forms, filters, and local field groups; keep the search icon only.

Navigation or shell searchShortcut allowedShow Control/Command+K only when the shell owns focus behavior and visible search results.

Navigation and shell spec

Multi-navigation shell selection contracts for dense operations products, knowledge bases, and focused tools.

Shell selection matrix

Navigation shell choice follows product information architecture, not a single shared layout.

SurfacePatternRuleBoundary

TMS dense operationsTop bar, menu button, compact search, and expanded mega menuUse when a product has 10+ primary navigation items or 30+ secondary directories.The expanded menu must show grouped primary areas and their secondary options together.

Design System knowledge baseHigh-contrast collapsible side navigation with multi-level bookmark linksUse for documentation, standards, governance, and proof receipts.The side navigation follows scroll position, supports collapse, and does not replace page headings.

Focused tool surfaceTop bar with local segmented navigationUse for a narrow tool with five or fewer peer views.Segmented navigation must not pretend to be product-wide navigation.

Mobile or narrow product shellTop bar, drawer menu, and compact searchUse when primary navigation cannot fit without wrapping or crowding.The drawer preserves the same grouping, search, focus, and close behavior.

TMS dense operations shell

Large operational products need a top navigation surface with a menu button, compact search, and an expanded menu that exposes grouped primary and secondary options together.

DensityTriggerPatternBoundary

HubUse when the selected primary area has 3-8 secondary routes and no overflow.Show a visual entry hub with action tiles, a short selected-area summary, and a compact utility rail.Do not force sparse secondary routes into the command-center or dense directory layout.

Command centerUse when primary navigation is 10+ items or secondary routes need task grouping.Group primary areas by business domain, then expose task lanes and quick entries.Keep the selected primary area and its secondary options visible together.

Dense directoryUse only when secondary routes are numerous, zoom is large, or the menu would overflow.Switch to a compact grouped directory optimized for scanning and scrolling.Density is a fallback for capacity, not the default visual treatment for sparse menus.

TCRNTMSOperations workspace

Local proof only

TCRNTMSOperations workspace

Local proof only

Operations

Commercial

Control tower

System

Daily operations

Creators Channels Availability Campaign requests

Review and exceptions

Agreements Risk flags Blocked handoffs Owner routing

Records and proof

Profiles Evidence queue Audit trail SLA watch

Knowledge base bookmark shell

Design System and other knowledge-base products need side navigation with multi-level bookmarks because the reader path is nested and scroll-driven.

TCRNDesign SystemPrivate local scaffold proof

Online documentation shellTop bar, attached side navigation, content column, and chapter navigation stay one shell.

Local proof only

Private local scaffold proof

Navigation and shell spec

The knowledge-base shell standard mirrors the active TCRN documentation shell: one top bar, attached side navigation, one content column, and bottom chapter navigation.

Components

Selected section and subsection remain visible while readers move through nested documentation.

scroll-awaremulti-leveldocumentation-first

Compact tool shell

Small tools may use local segmented navigation, but only when the number of peer views stays small and stable.

Focused tool

Local proof only

Stable peer viewsReview queue

Use compact segmented navigation only when the route has a small, stable set of peer views.

QueueReady to review

Needs proofOwner route pending

HistoryLocal changes only

Navigation component contracts

PrimitiveRuleBoundary

TopBarNames the product surface and active module without replacing page headings.No tenant, RBAC, or readiness truth.

SideNavOwns primary product navigation, grouped sections, stable source order, scroll-aware document navigation, and collapsed navigation state.Current location may scroll into view and highlight, but must not reorder sections.

NavGroup and NavItemSupport section hierarchy with selected, focus, hover, disabled, and child item states.Selected styling must scale beyond two levels.

SearchInputProvides search affordance for fields, filters, documentation shells, and product navigation.Control/Command+K shortcut labels belong only to navigation or shell search with a real focus target and result behavior.

BreadcrumbShows location inside a product route or documentation trail.Not a substitute for primary navigation.

Tabs and SegmentedNavSwitch related local views with honest segmented navigation semantics.Do not claim role=tab unless keyboard tab behavior is implemented.

ProductSwitcherMoves between TCRN product surfaces when a consumer route owns that capability.Storybook examples remain synthetic.

PaginationSeparates long indexed lists without losing current filter or proof context.No remote count claim without product data.

SkipLinkProvides keyboard access past repeated shell navigation.Must remain visible on focus.

Pagination and skip-link boundary

Pagination and skip links belong to shared navigation primitives because they preserve orientation, keyboard access, and proof context across long surfaces.

Dialog spec and usage

Dialog capability metadata, focus entry, Escape close, and focus-return boundaries.

Capability metadata

CapabilityStatusProof

Focus entryLocal proof onlyImplemented in Dialog

Tab containmentNot claimedNot claimed until implemented

Escape closeLocal proof onlyRequires onOpenChange

Focus returnLocal proof onlyRequires triggerRef

Overlay mode matrix

Choose the smallest layer that fits the task: anchored popovers for local context, dialogs for modal confirmation, and drawers for structural panels.

Dialog

Modal confirmation with focus entry, Escape close, and focus return when the owning route wires those props.

Popover

Anchored, non-modal surface for nearby context or lightweight choices; it must not pretend to be a blocking dialog.

Drawer

Structural side panel for inspection or action groups; it is complementary, not aria-modal.

Confirm action dialog

Table and work index spec

Dense desktop scanning and mobile stacked rows for synthetic work items.

Table shell rules

SurfaceDesktop behaviorMobile behaviorBoundary

TableShellUse readable dense rows with visible headers and package-backed status cells.Stack each row into labeled fields without dropping labels or state text.Do not render unlabeled text blocks or claim remote counts from local examples.

WorkIndexUse for finite review queues where status and owner scanning matter.Preserve source order and show the same labels before each value.Do not treat WorkIndex as DataGrid, virtualized search, or bulk editing.

Empty stateKeep the empty state inside the table frame and name what is absent.Keep the same empty message visible without inventing rows.Do not use empty state when loading or source errors are unresolved.

Accessibility receiptEvery table needs an accessible name and legal row/cell structure, including empty states.Stacked mobile rows keep data-label text before each value.Never place headings or arbitrary blocks directly under role=table.

Sorting and filteringShow sort or filter controls only after aria-sort, active filter readback, and empty/error states are implemented.Keep the current sort/filter summary visible before stacked rows.TableShell does not imply remote filtering, column configuration, or persisted sort state.

Row actionsKeep row actions visible, focusable, and separated from status text.Actions wrap under the row label with the same disabled reason text.Do not hide blocked actions or append disabled reasons to visible labels.

Bulk selectionBatch selection requires selected counts, all/none boundaries, and keyboard behavior.Show selected state per row; do not rely on color alone.WorkIndex does not include bulk selection by default.

Work index scanning

Use WorkIndex for finite synthetic queues that need compact status and owner scanning.

Work itemStateOwner

Button and clipboard actionLocal proof onlyui-react

Display primitivesLocal proof onlyui-react

Interaction disclosure primitivesLocal proof onlyui-react

FieldProof requiredui-react

Navigation shellProof requiredui-react

DialogProof requiredui-react

WorkIndexFixture onlyui-react

Brand lockupNot claimedStorybook prototype

Empty state distinction

Empty states stay inside the table frame and name what is absent without claiming remote counts.

ItemState

No release candidate

No product or external integration is configured.

DataGrid escalation boundary

Escalate from TableShell or WorkIndex when the surface needs editing, virtualization, remote state, column controls, or batch operations.

CapabilityTableShell dispositionEscalationRequired proof

Editable cellsDo not keep TableShellUse DataGrid or a detail form with persistent field labels.Keyboard editing, validation, save/cancel, and error recovery.

Remote pagination or filteringDo not keep TableShellUse DataGrid or a route-owned workbench.Loading, empty, error, current query, and total-count ownership.

Virtual scrollingDo not keep TableShellUse DataGrid with explicit viewport and row-count proof.Keyboard position, screen-reader row context, and scroll restoration.

Column resize or frozen columnsDo not keep TableShellUse DataGrid with column-state controls.Resize handles, focus order, persistence, and responsive fallback.

Bulk operationsDo not keep WorkIndexUse a selection list or DataGrid with batch-action proof.Selected count, all/none behavior, disabled reasons, and undo or confirmation.

Empty, loading, and error states must stay distinct; do not render an empty table when source loading failed.

TCRN Design System Contract Stories

Components

Component family index

Recommended component families

Package-backed component API

Package utility exports

Storybook-only prototypes

Current local story coverage

Story template

Display primitives spec

Owner-approved first batch

Highlight

Skeleton

State surfaces

Proof route needed

No local rows

Panel unavailable

Interaction disclosure spec

Owner-approved second batch

Tooltip

Disclosure

Expanded controlled region

Collapsed controlled region

Button spec and usage

Spec

Disabled usage

Clipboard copy action

Field spec and usage

Field width rules

Search shortcut rules

Navigation and shell spec

Shell selection matrix

TMS dense operations shell

Knowledge base bookmark shell

Navigation and shell spec

Components

Compact tool shell

Navigation component contracts

Pagination and skip-link boundary

Dialog spec and usage

Capability metadata

Overlay mode matrix

Dialog

Popover

Drawer

Interactive proof fixture

Popover proof fixture

Confirm action dialog

Table and work index spec

Table shell rules

Work index scanning

Empty state distinction

No release candidate

DataGrid escalation boundary