Skip to main content

Primitives

Choose a semantic building block and its failure state.

Use these rendered contracts to verify purpose, anatomy, keyboard behavior, and ownership before a component enters a product.

28 authoritative package contracts · @sanchika/primitives
Rendered example
Each index entry opens its rendered state proof.
Contract / API
@sanchika/primitives
Limit
Primitives ship CSS and metadata, not a hidden runtime.
Failure state
If a consumer cannot meet a required state or interaction, it must not present the primitive as complete.

Contract index

Command triggerButton

Triggers an action without implying navigation and preserves the v0.0.2 tone, size, class, and visible-state contract.

6 states · keyboard-operable · visible-focus · non-color-disabled-state
Grouped information surfaceCard

Preserves the v0.0.2 Card API as a specialized grouped-content plane built on Surface styling rather than the default wrapper for every section.

2 states · semantic-heading · non-color-status-text
Short status or classification labelBadge

Names a compact status or classification with visible text and supporting tone while preserving the v0.0.2 API.

1 states · visible-text-required · color-not-only-signal
Accessible label, control, hint, and error wrapperField

Groups visible form guidance and preserves the v0.0.2 class/state contract without implementing validation or input behavior.

4 states · label-required · error-associated · keyboard-operable
Bounded page or region measureContainer

Centers content, applies safe logical inline gutters, and selects an evidence-backed maximum measure without preventing full-bleed composition.

1 states · logical-inline-gutters · zoom-safe · no-horizontal-overflow
Vertical rhythm regionSection

Creates finite section-level block rhythm and an optional structural boundary without child-margin hacks.

1 states · heading-relationship · forced-colors-boundary · logical-block-rhythm
Vertical compositionStack

Arranges related children in one block-axis flow using gap rather than child margins.

1 states · source-order-preserved · long-content-safe
Wrapping inline compositionCluster

Wraps actions, metadata, and compact facts without turning them into decorative pills.

1 states · writing-mode-safe · wrap-safe · source-order-preserved
Repeated peer-item compositionGrid

Arranges repeated peers with one intrinsic mode and a restrained set of explicit column modes.

1 states · source-order-preserved · no-horizontal-overflow · semantic-list-compatible
Asymmetrical primary and supporting compositionSplit

Pairs a primary region with supporting context using evidence-backed ratios and a deliberate narrow-screen stack.

2 states · source-order-preserved · no-css-reordering · narrow-stack
Semantic visual planeSurface

Creates a restrained visual plane from package surface, border, radius, and elevation tokens while leaving content semantics to the chosen element.

2 states · forced-colors-boundary · semantic-element-owned-by-consumer · non-color-status
Thematic or structural separatorDivider

Marks a meaningful horizontal separation with border tokens and native semantics.

2 states · native-hr-preferred · not-focusable · forced-colors-visible
Assistive-technology-only textVisuallyHidden

Keeps essential text available to assistive technology while removing it from the visual flow without a zoom clipping defect.

1 states · assistive-technology-available · zoom-safe · not-display-none
Semantic presentation rolesText

Applies evidence-backed display, heading, body, lead, caption, eyebrow, data, or mono presentation without choosing document semantics for the consumer.

2 states · semantic-html-preserved · long-content-safe · not-size-utility
Navigation targetLink

Navigates to another document, route, fragment, or downloadable resource with a persistent non-color affordance.

4 states · persistent-link-affordance · visible-focus · native-anchor
Single navigation target with grouped contextLinkCard

Makes a bounded content group one accessible navigation target without nested interactive controls.

3 states · single-tab-stop · no-nested-interactive · whole-boundary-focus
Labelled local filtering controlSearchField

Defines a visible-label search field, accessible clear action, result-status region, no-results recovery, and error association without exporting filtering behavior.

8 states · visible-label-required · clear-name-required · focus-retained · result-status-associated · error-associated
Compact visible state with optional source metadataInlineStatus

Pairs a marker and visible state text using package status triads without replacing Badge or adding implicit live-region behavior.

3 states · visible-text-required · color-not-only-signal · no-implicit-live-region
Layout-preserving loading placeholderSkeleton

Preserves approximate layout during a truthful loading context without implying that content is loaded, verified, or complete.

3 states · owner-busy · shape-hidden · nonanimated-reduced-motion
Guided absence and next actionEmptyState

Explains why useful content is absent and provides an appropriate next action without an implicit alert.

3 states · clear-heading · explicit-next-action · no-implicit-alert
Recoverable failure explanationErrorState

Names a failure, preserves source or reference context, and exposes explicit recovery without blame or false certainty.

3 states · explicit-recovery · focus-not-stolen · contextual-announcement
Visible determinate or pending progressProgress

Styles native progress semantics and visible labels without adding runtime behavior or implying completion from motion.

4 states · native-progress · visible-value · non-color-state
Ordered process stateStepper

Presents process order and current/completed/upcoming state without implying navigation or beginning a product pattern.

4 states · ordered-list · current-step · non-color-completion
Native progressive disclosureDisclosure

Styles details and summary for FAQ or simple disclosure while preserving native open/closed and keyboard behavior.

4 states · native-details-summary · keyboard-operable · no-clipping-animation
Explicit copy command with visible feedbackCopyButton

Defines activation, success, reset, failure, disabled, and announcement obligations while leaving clipboard access in gallery or consumer code.

4 states · explicit-activation · focus-retained · visible-and-announced-feedback
Current-location navigation trailBreadcrumb

Provides a landmark and ordered route trail with decorative separators and an unlinked current page.

3 states · navigation-landmark · ordered-list · current-page · decorative-separator-hidden
Labelled operational valueStat

Presents a value with optional visible-direction delta, source/time metadata, and context without a chart or unsupported KPI certainty.

3 states · label-value-associated · non-color-delta · no-count-animation
Semantic responsive table wrapperTableShell

Styles native table content, density, numeric alignment, optional sticky header, and honest overflow affordance without providing data-grid behavior.

6 states · native-table · caption-and-headers · focus-visible-scroll-region · zoom-reachable