navigation — wyrd.component.tabs

Tabs

Horizontal tab collection with index-matched content panels.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/tabs.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Tabs  tag: wyrd-tabs  package: wyrd.component.tabs  title: Tabs  summary: Horizontal tab collection with index-matched content panels.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: navigation  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled selected item value.    - name: default-value      type:        kind: string      required: false      serializable: true      summary: Initial uncontrolled selected item value; when absent, the first non-disabled item is selected.    - name: items      type:        kind: array        item:          kind: object          fields:            label:              kind: string            value:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Ordered tab items; disabled items render but are skipped by focus movement and activation.  slots:    - name: content      content: true      required: true      cardinality: one-or-many      accepts:        - component        - content      summary: Index-matched tab panels; the Nth slotted child is the panel for the Nth item. All panels stay mounted, and only the selected panel is visible and exposed to assistive technology.  events:    - name: value-change      payload:        value:          kind: string      bubbles: true      composed: true      cancelable: false      summary: Emitted when the user activates an enabled tab with a different value.  states:    - name: default      source: platform      summary: Horizontal tab collection.    - name: selected      source: property      summary: State derived from value, default-value, or the first enabled item.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state on a tab.    - name: disabled      source: property      summary: Disabled tab item state.  parts:    - name: root      summary: Tabs root.      slots:        - content    - name: list      summary: Tablist container.    - name: tab      summary: Repeated tab button.    - name: panel      summary: Repeated tab panel; only the selected panel is visible and exposed to assistive technology.      slots:        - content  tokens:    tab:      background: color.surface      foreground: color.on-surface      selected-background: color.primary      selected-foreground: color.on-primary      hover-background: color.secondary      indicator-color: color.primary      indicator-thickness: 2px      padding-x: spacing.md      padding-y: spacing.sm    gap: spacing.xsmessages: []obligations:  accessibility:    role: tablist    name: The surrounding content should provide context for the tab collection.    keyboard:      - Tab moves focus into the selected tab or focused tab.      - ArrowLeft and ArrowRight move focus between enabled tabs with wrap-around without selecting.      - Home and End move focus to the first and last enabled tabs.      - Enter and Space activate the focused enabled tab.    semantics:      - Web projections expose role=tablist on the list, role=tab on each tab, aria-selected on tabs, and role=tabpanel on every index-matched panel.      - Each panel is associated to its tab with aria-labelledby using stable per-instance ids.      - Non-selected panels stay mounted but are hidden from visual rendering and assistive technology.      - Disabled items are skipped by arrow-key focus movement and cannot be activated.      - Flutter exposes selected button semantics for tabs; arrow-key traversal is not implemented in v1.  behavior:    model: collection    interactions:      - value ?? default-value ?? first enabled item determines the effective selected tab.      - The Nth content child is the panel for the Nth item; items without a matching panel keep an empty mounted panel.      - All panels stay mounted so panel-local state survives tab switches; only the selected panel is visible and exposed.      - Arrow keys move focus only; click, Enter, and Space select.    hostEffects:      - Dispatch value-change when the user activates an enabled tab with a different value.      - Generate stable per-instance ids for web tab and panel association.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - value      - default-value      - items    serializableSlots:      - content    eventBindings:      - value-change    notes: Tabs serialize item records and index-matched panel content; the Nth serialized content child is the panel for the Nth item. Hosts must preserve order and keep all panels mounted while exposing only the selected panel visually and semantically.examples:  - name: overview    state: selected    properties:      default-value: overview      items:        - label: Overview          value: overview        - label: Details          value: details        - label: History          value: history    slots:      content:        - Project overview content.        - Detailed settings content.        - Change history content.  - name: disabled-item    state: disabled    properties:      default-value: overview      items:        - label: Overview          value: overview        - label: Details          value: details          disabled: true        - label: History          value: history    slots:      content:        - Project overview content.        - Detailed settings content.        - Change history content.overrides:  react:    slots:      content: children  flutter:    slots:      content: child

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

overview state: selected

Project overview content.

Usage

import { WyrdTabs } from "@wyrd-company/react";

<WyrdTabs defaultValue="overview" items={[{"label":"Overview","value":"overview"},{"label":"Details","value":"details"},{"label":"History","value":"history"}]}>
  Project overview content.
  Detailed settings content.
  Change history content.
</WyrdTabs>

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdTabs(
  initialValue: 'overview',
  items: [{"label":"Overview","value":"overview"},{"label":"Details","value":"details"},{"label":"History","value":"history"}],
  child: Text('Project overview content. Detailed settings content. Change history content.'),
)

// events: onChanged

disabled-item state: disabled

Project overview content.

Usage

import { WyrdTabs } from "@wyrd-company/react";

<WyrdTabs defaultValue="overview" items={[{"label":"Overview","value":"overview"},{"label":"Details","value":"details","disabled":true},{"label":"History","value":"history"}]}>
  Project overview content.
  Detailed settings content.
  Change history content.
</WyrdTabs>

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdTabs(
  initialValue: 'overview',
  items: [{"label":"Overview","value":"overview"},{"label":"Details","value":"details","disabled":true},{"label":"History","value":"history"}],
  child: Text('Project overview content. Detailed settings content. Change history content.'),
)

// events: onChanged

Properties

Name	Type	Default	Summary
`value`	`string`	`undefined`	Controlled selected item value.
`default-value`	`string`	`undefined`	Initial uncontrolled selected item value; when absent, the first non-disabled item is selected.
`items`	`array`		Ordered tab items; disabled items render but are skipped by focus movement and activation.

Slots & events

Slot	Cardinality	Accepts	Summary
`content`	one-or-many	`component, content`	Index-matched tab panels; the Nth slotted child is the panel for the Nth item. All panels stay mounted, and only the selected panel is visible and exposed to assistive technology.

Event	Payload	Summary
`value-change`	`value`	Emitted when the user activates an enabled tab with a different value.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`tab.background`	`color.surface`
`tab.foreground`	`color.on-surface`
`tab.selected-background`	`color.primary`
`tab.selected-foreground`	`color.on-primary`
`tab.hover-background`	`color.secondary`
`tab.indicator-color`	`color.primary`
`tab.indicator-thickness`	`2px`
`tab.padding-x`	`spacing.md`
`tab.padding-y`	`spacing.sm`
`gap`	`spacing.xs`

States

State	Source	Summary
`default`	platform	Horizontal tab collection.
`selected`	property	State derived from value, default-value, or the first enabled item.
`focus-visible`	platform	Keyboard-visible focus state on a tab.
`disabled`	property	Disabled tab item state.

SDUI

Status: serializable. Tabs serialize item records and index-matched panel content; the Nth serialized content child is the panel for the Nth item. Hosts must preserve order and keep all panels mounted while exposing only the selected panel visually and semantically.

Serializable	Members
Properties	`value, default-value, items`
Slots	`content`
Events	`value-change`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative