{ "$schema_version": 1, "$canonical_source": "design-system/Swivel Component Library.html", "$notes": [ "Machine-readable inventory of components in the Swivel component library.", "Each component lists the categories it belongs to, the anchor on the showcase page,", "and its documented variants / sizes / states. State and variant names match the", "CSS class hooks used in the showcase so a linter or codegen can map directly.", "SOURCE OF TRUTH ORDER: components.css defines what exists; a component's .d.ts defines its", "typed React API; this file indexes both. Variant, size and tone ids here are identical to the", "string-literal unions in the .d.ts, so no alias table is needed to go between them.", "Components with a 'react' block ship real code under components// (.jsx + .d.ts).", "Components without one are CSS class hooks only — style them from class_root.", "When you add a new component or variant, update this file in the same commit.", "CSS-only patterns are flagged with \"css_only\": true; entries with a \"react\" block ship a typed component in components//.", "Every component carries a \"state_matrix\": state id → { trigger, selector, changes } so a linter or generator can resolve what each state actually changes. Shared rules live under \"state_conventions\".", "Usage rules (severity, detection, fix) live in design-system/adherence.rules.yaml.", "Start at selection_cheat_sheet if you know the intent but not the component. It covers the confusable pairs (Checkbox vs Switch, ButtonGroup vs SelectField, Badge vs Chip, Modal vs Drawer) and names what NOT to use in each case.", "The compiled bundle exposes only capitalised exports on window.. A lowercase export (a hook, a helper) is reachable through the ESM barrel index.js only — see Toast.react.window_access.", "Data-viz components implement design-system/charts.rules.yaml. Read that file before building any chart the components do not cover (heatmap, scatter, small multiples).", "Date and time components inherit Material Design 3 structure, interaction, and a11y wholesale and override colour only, through the --md-* bridge in tokens.css. design-system/Date and Time.html §01 is the policy.", "The button family — .btn, .btn-icon, .bg-btn, .bs-action — shares one colour ramp (--slate-100 / --slate-110 / --slate-120) and one label type contract (--font-body 500 at --fs-ui-caps). --slate-base is NOT part of it: it holds in light mode but shifts to #7B9BBF in dark, so any button using it diverges from its neighbours in dark mode only.", "Building a whole screen? Start from a template, not from components — design-system/templates.json start_here names the default (templates/app-shell) and the decision that picks another.", "Table columns have KINDS. components.json Table.cell_kinds is the registry: each kind names its header class, body class, content, and what to avoid. Read it before adding a column — it is why numeric headers take .cell-num while their values take .cell-metric.", "Before adding a class contract to components.css, grep for an existing one. A \"Beacon chat thread\" vocabulary was built twice — once as a showcase demo swept into the shared stylesheet, once as the real .as-* contract — and neither referenced the other." ], "components": [ { "id": "button", "name": "Button", "category": "actions", "anchor": "Swivel Component Library.html#c-buttons", "class_root": ".btn", "react": { "module": "components/Button/Button.jsx", "types": "components/Button/Button.d.ts", "export": "Button", "variant_prop": "variant", "size_prop": "size", "default_variant": "primary", "default_size": "md" }, "variants": [ { "id": "primary", "class": "btn-primary", "purpose": "Primary action on a surface" }, { "id": "secondary", "class": "btn-secondary", "purpose": "Secondary action paired with primary" }, { "id": "tertiary", "class": "btn-tertiary", "purpose": "Low-emphasis text-only action" }, { "id": "tonal", "class": "btn-tonal", "purpose": "Mid-emphasis filled action" }, { "id": "accent", "class": "btn-accent", "purpose": "Switch-cyan call-to-action" }, { "id": "danger", "class": "btn-danger", "purpose": "Destructive action" }, { "id": "tonal-error", "class": "btn-tonal-error", "purpose": "Mid-emphasis filled destructive — distinct from danger (outlined); use for inline delete in a tonal context" } ], "sizes": [ { "id": "sm", "class": "btn-sm", "height_var": "--control-h-sm", "height_px": 24 }, { "id": "md", "class": null, "height_var": "--control-h", "height_px": 34 }, { "id": "lg", "class": "btn-lg", "height_var": "--control-h-lg", "height_px": 40 } ], "states": [ "default", "hover", "pressed", "focused", "disabled" ], "supports_icon": true, "icon_positions": [ "leading", "trailing" ], "css_only": false, "state_matrix": { "default": { "selector": ".btn.btn-", "changes": { "height": "--control-h (34px)", "border-radius": "--radius-sm" } }, "hover": { "trigger": ":hover", "selector": ".btn-primary:hover", "changes": { "background": "--slate-110 (primary)" }, "siblings": { "btn-secondary/tertiary": "--graphite-10", "btn-tonal": "#CDDCEC", "btn-accent": "#C2FBFF", "btn-danger": "#B71C1C", "btn-tonal-error": "#FFD4D1" } }, "pressed": { "trigger": ":active", "changes": { "transform": "scale(0.98)", "transition-duration": "80ms" } }, "focused": { "trigger": ":focus-visible", "changes": { "box-shadow": "--focus-ring" } }, "disabled": { "trigger": ":disabled | .is-disabled", "selector": ".btn:disabled, .btn.is-disabled", "changes": { "opacity": "0.4", "pointer-events": "none" } } } }, { "id": "button_group", "name": "ButtonGroup", "category": "inputs", "anchor": "Swivel Component Library.html#c-button-groups", "class_root": ".btn-group", "variants": [ { "id": "text", "purpose": "Text labels only" }, { "id": "icon-only", "class": "icon-only", "purpose": "Icon-only segmented control" }, { "id": "icon-and-text", "purpose": "Icon + text per segment" } ], "selection_modes": [ "single" ], "states": [ "default", "hover", "selected", "selected-hover", "disabled" ], "css_only": false, "note": "Unselected segments sit in --slate-100 with a --surface-muted hover fill; the selected segment takes the --slate-bg fill and deepens fill + label together on hover. Segment glyphs may carry .is-success / .is-warning / .is-error / .is-neutral for status tones. Filtering and segmented single-selection only — never actions.", "react": { "module": "components/ButtonGroup/ButtonGroup.jsx", "types": "components/ButtonGroup/ButtonGroup.d.ts", "export": "ButtonGroup", "items_prop": "items", "value_prop": "value", "multi_prop": "multi" }, "state_matrix": { "default": { "selector": ".bg-btn", "changes": { "background": "transparent", "color": "--slate-100", "border": "1px solid --graphite-20", "height": "34px" } }, "hover": { "trigger": ":hover:not(.is-selected)", "selector": ".bg-btn:hover:not(.is-selected)", "changes": { "background": "--surface-muted", "color": "--slate-contrast" } }, "selected": { "selector": ".bg-btn.is-selected", "changes": { "background": "--slate-bg", "color": "--slate-100", "border-color": "--slate-100", "z-index": "1" } }, "selected-hover": { "trigger": ".is-selected:hover", "selector": ".bg-btn.is-selected:hover", "changes": { "background": "color-mix(in srgb, var(--slate-bg) 82%, var(--slate-100))", "color": "--slate-contrast" }, "note": "Fill and label deepen together so the label keeps contrast in both themes — never change the fill alone." }, "disabled": { "selector": ".btn-group.is-disabled", "changes": { "pointer-events": "none", "background": "--surface-muted", "color": "--graphite-40", "selected-background": "--graphite-20", "selected-color": "--graphite-50" } } } }, { "id": "tooltip", "name": "Tooltip", "category": "feedback", "anchor": "Swivel Component Library.html#c-tooltips", "class_root": ".tooltip", "note": "Fill contrasts page background (graphite/base). Typography: UI/Small (12px Avantt SemiBold). Two usage patterns: [data-tooltip] attribute for pure-CSS auto-tooltip; .tooltip class for JS-positioned overlays.", "variants": [ { "id": "no-tail", "class": "tooltip", "purpose": "No directional context; centered above group or truncation label" }, { "id": "top", "class": "tooltip tooltip-top", "purpose": "Tooltip above anchor, tail points down" }, { "id": "bottom", "class": "tooltip tooltip-bottom", "purpose": "Tooltip below anchor, tail points up" }, { "id": "right", "class": "tooltip tooltip-right", "purpose": "Tooltip right of anchor, tail points left" }, { "id": "left", "class": "tooltip tooltip-left", "purpose": "Tooltip left of anchor, tail points right" } ], "auto_css": { "attribute": "data-tooltip", "placement_attribute": "data-tooltip-placement", "values": [ "top", "bottom", "left", "right" ] }, "copy_rule": "Verb phrase describing what clicking/hovering does. Never just the element name.", "accessibility": "Pair with aria-label or aria-describedby on the trigger so the tooltip copy is available to screen readers.", "states": [ "hidden", "visible" ], "css_only": false, "react": { "module": "components/Tooltip/Tooltip.jsx", "types": "components/Tooltip/Tooltip.d.ts", "export": "Tooltip", "label_prop": "label" }, "state_matrix": { "hidden": { "selector": "[data-tip]::after", "changes": { "opacity": "0", "pointer-events": "none" } }, "visible": { "trigger": ":hover | :focus-visible", "changes": { "opacity": "1", "background": "--graphite-base", "color": "--surface-canvas", "font-size": "--fs-ui-small" } } } }, { "id": "split_button", "name": "SplitButton", "category": "actions", "anchor": "Swivel Component Library.html#c-split-buttons", "class_root": ".btn-split", "react": { "module": "components/SplitButton/SplitButton.jsx", "types": "components/SplitButton/SplitButton.d.ts", "export": "SplitButton", "variant_prop": "variant", "default_variant": "primary" }, "note": "Two-segment control: left fires the primary action, right opens a dropdown of related options. Use when 2-4 closely related actions share a surface and one is a clear default. Not for unrelated actions.", "variants": [ { "id": "primary", "class": "btn-split-primary", "purpose": "Filled action segment — text only, or leading icon + text when the icon prop is set" }, { "id": "compact", "class": "btn-split-primary btn-split-compact", "purpose": "Filled, icon-only action — space-premium contexts. Needs icon + label; label becomes the aria-label" }, { "id": "ghost", "class": "btn-split-ghost", "purpose": "No fill or stroke; dropdown arrow hidden until hover" } ], "segments": [ { "id": "action", "class": ".bs-action", "note": "Fires the primary action on click" }, { "id": "trigger", "class": ".bs-trigger", "note": "Opens the dropdown menu. Must have data-tooltip describing the options available." } ], "tooltip": { "required_on": "bs-trigger", "required_on_compact_action": true, "copy_rule": "Describe the options available, e.g. 'More save options'" }, "states": [ "default", "hover", "open", "disabled" ], "css_only": false, "state_matrix": { "default": { "selector": ".btn-split.btn-split-" }, "hover": { "trigger": ":hover", "changes": { "background": "--slate-110 (primary) | --graphite-10 (ghost)" } }, "open": { "selector": ".btn-split.is-open", "changes": { "trigger-background": "--slate-120", "menu-display": "block", "chevron-opacity": "1" } }, "disabled": { "trigger": ":disabled", "changes": { "opacity": "0.4", "pointer-events": "none" } } }, "token_parity": { "rule": "A split button must be indistinguishable from the Button beside it. Fill, hover, and pressed all come from the same slate ramp as .btn-primary and the selected .bg-btn: --slate-100 / --slate-110 / --slate-120.", "not": "--slate-base. It resolves to the same hex as --slate-100 in light mode but shifts to #7B9BBF in dark, so a split button and a primary button diverged in dark mode only.", "type": "Label type is one contract across .btn, .bg-btn and .bs-action — --font-body 500 at --fs-ui-caps, 0.04em, uppercase. The ghost variant drops the caps treatment by design but still sizes from --fs-ui-caps, never a literal 13px.", "divider": "The primary variant's segment divider is color-mix(--white 25%, transparent), routed through the token rather than a raw rgba." } }, { "id": "icon_button", "name": "IconButton", "react": { "module": "components/IconButton/IconButton.jsx", "types": "components/IconButton/IconButton.d.ts", "export": "IconButton", "variant_prop": "variant", "size_prop": "size", "default_variant": "secondary", "default_size": "md", "required_props": [ "icon", "tooltip" ] }, "category": "actions", "anchor": "Swivel Component Library.html#c-buttons", "class_root": ".btn-icon", "note": "Standalone square icon-only button. Shares variant/size tokens with Button — do not use ButtonGroup's .bg-btn.icon-only for standalone actions.", "variants": [ { "id": "primary", "class": "btn-icon btn-primary", "purpose": "Primary action" }, { "id": "secondary", "class": "btn-icon btn-secondary", "purpose": "Secondary action" }, { "id": "tertiary", "class": "btn-icon btn-tertiary", "purpose": "Low-emphasis ghost" }, { "id": "tonal", "class": "btn-icon btn-tonal", "purpose": "Mid-emphasis filled" }, { "id": "danger", "class": "btn-icon btn-danger", "purpose": "Destructive" } ], "sizes": [ { "id": "sm", "class": "btn-sm", "height_var": "--control-h-sm", "height_px": 24 }, { "id": "md", "class": null, "height_var": "--control-h", "height_px": 34 }, { "id": "lg", "class": "btn-lg", "height_var": "--control-h-lg", "height_px": 40 } ], "states": [ "default", "hover", "focused", "disabled" ], "tooltip": { "required": true, "attribute": "data-tooltip", "copy_rule": "Verb phrase describing what clicking does — e.g. 'Add rule', 'Delete campaign', 'Export CSV'. Never the icon name or a noun.", "note": "Every IconButton must carry data-tooltip. Omitting it is an accessibility failure — the tooltip is the only label for the action. A dashed red outline and console warning appear when the attribute is missing." }, "css_only": false, "state_matrix": { "default": { "selector": ".btn-icon.btn-", "changes": { "aspect-ratio": "1 / 1", "icon-size": "18px" } }, "hover": { "trigger": ":hover", "changes": { "background": "--slate-110 (primary) | --graphite-10 (secondary, tertiary, tonal) | #B71C1C (danger)" } }, "focused": { "trigger": ":focus-visible", "changes": { "box-shadow": "--focus-ring", "tooltip-opacity": "1" } }, "disabled": { "trigger": ":disabled | .is-disabled", "changes": { "opacity": "0.4", "cursor": "not-allowed", "pointer-events": "none" } } }, "token_parity": "Variant colours are the same contract as .btn — primary fills --slate-100, hovers --slate-110. Not --slate-base, which diverges in dark mode." }, { "id": "text_field", "name": "TextField", "category": "inputs", "anchor": "Swivel Component Library.html#c-text-fields", "class_root": ".field", "react": { "module": "components/TextField/TextField.jsx", "types": "components/TextField/TextField.d.ts", "export": "TextField", "variant_prop": "variant", "default_variant": "default", "controlled_props": { "value": "defaultValue" } }, "note": "The icon adornment is not a variant — set the icon / iconRight props on either variant. Fields floor at min-width:240px. Wrap a field in .field-narrow to opt out of that floor (popover rows, packed toolbars); the modifier also clears the floor on .field-inset and .tag-input. An unlabelled field (a min/max pair under one group heading, a toolbar filter) takes ariaLabel — without a visible label or ariaLabel the input has no accessible name.", "variants": [ { "id": "default", "class": null, "purpose": "Label stacked above the input" }, { "id": "inset-label", "class": "field-inset", "purpose": "Compact field with the label notched into the top stroke" } ], "adornment_class": "field-input-icon", "states": [ "default", "focused", "required", "error", "error-focused", "disabled" ], "adornments": [ "leading-icon", "trailing-icon", "prefix", "suffix", { "id": "prefix", "class": "field-prefix", "prop": "prefix", "purpose": "Static text before the value — a currency symbol or unit. Shares the leading-icon slot and its 32px padding, so a field takes prefix or icon, not both" } ], "css_only": false, "state_matrix": { "default": { "selector": ".field-input | .field-inset", "changes": { "border": "1px solid --graphite-20", "background": "--surface-input", "height": "34px" } }, "focused": { "trigger": ":focus | :focus-within", "selector": ".field-input:focus, .field-inset:focus-within", "changes": { "border-width": "2px", "border-color": "--switch-contrast", "box-shadow": "--focus-ring", "padding": "compensated 1px to hold layout" } }, "required": { "selector": ".field-label .req", "changes": { "color": "--error", "content": "*" } }, "error": { "selector": ".field.is-error, .field-inset.is-error", "changes": { "border-color": "--error", "label-color": "--error", "help-color": "--error" } }, "error-focused": { "selector": ".field.is-error .field-input:focus", "changes": { "border-color": "--error", "box-shadow": "0 0 0 3px color-mix(in srgb, var(--error) 32%, transparent)" } }, "disabled": { "selector": ".field-inset.is-disabled, .field-input:disabled", "changes": { "background": "--graphite-10", "border-color": "--graphite-20", "color": "--graphite-50" } } } }, { "id": "textarea", "name": "Textarea", "category": "inputs", "anchor": "Swivel Component Library.html#c-forms", "class_root": "textarea.field-input", "note": "Multi-line sibling of TextField — the same .field / .field-input / .field-help contract, so stroke, focus, and error treatment are shared. The one difference that matters: height is a row count, never --control-h. A textarea must not resolve to the 34px control height. Use it whenever the answer is prose (a note, a description, a pause reason) rather than a value.", "variants": [ { "id": "default", "class": null, "purpose": "Label stacked above the field" }, { "id": "inset-label", "class": "field-inset", "purpose": "Label notched into the top stroke, matching the inset TextField" } ], "slots": [ { "id": "foot", "class": "field-foot", "purpose": "Row under the field holding help text and the counter — the counter is right-aligned" }, { "id": "count", "class": "field-count", "purpose": "Mono, tabular-nums character counter; .is-over turns it --error" } ], "density": { "min_height": "76px (default) / 62px (inset)", "rows_default": 3, "resize": "vertical — removed when autosize is on, because JS owns the height" }, "states": [ "default", "focus", "error", "disabled", "readonly", "over-limit" ], "css_only": false, "react": { "module": "components/Textarea/Textarea.jsx", "types": "components/Textarea/Textarea.d.ts", "export": "Textarea", "controlled_props": [ "value" ], "props": [ "label", "required", "variant", "value", "defaultValue", "onChange", "placeholder", "rows", "autosize", "maxRows", "help", "error", "maxLength", "focused", "disabled", "readOnly", "id", "name", "textareaRef" ] }, "state_matrix": { "default": { "selector": "textarea.field-input", "changes": { "min-height": "76px", "height": "auto", "padding": "8px --space-lg", "line-height": "1.5", "resize": "vertical" }, "note": "In the inset variant the wrapper drops its horizontal padding and the textarea carries it instead (11px 14px 7px) — the control fills the field box edge to edge while the text keeps the same 14px gutter. A large scrollable region inset by the wrapper reads as a box inside a box. The top padding also clears the notch label, which straddles the top border; a single-line inset field is centred in its row and needs neither." }, "focus": { "trigger": ":focus", "changes": { "border-width": "2px", "border-color": "--switch-contrast", "box-shadow": "--focus-ring" }, "note": "Inherited from .field-input — identical to TextField." }, "error": { "trigger": ".field.is-error / error prop", "changes": { "border-color": "--error", "help-color": "--error" } }, "disabled": { "trigger": ":disabled", "changes": { "color": "--graphite-50" } }, "readonly": { "trigger": "[readonly]", "changes": { "note": "No visual change — the value stays selectable and copyable." } }, "over-limit": { "trigger": ".field-count.is-over", "changes": { "color": "--error" }, "note": "Only reachable when maxLength is absent from the DOM but enforced in state; maxLength normally blocks the overflow." } }, "guidance": { "maxLength": "Only where the backend actually enforces a limit. A decorative counter invites the user to plan around a rule that does not exist.", "autosize": "For fields whose length is unpredictable and worth seeing at once (a change log, a note). Pair with maxRows so one long entry cannot push the save footer off screen." } }, { "id": "date-field", "name": "DateField", "category": "inputs", "anchor": "Date and Time.html#date-input-field", "class_root": ".md-input", "note": "Date input with a calendar affordance, in both label treatments. A text input, not a masked control — the host owns parsing and validation. Pair with DatePicker on the trailing glyph (see docked_pairing).", "slots": [ { "id": "label-stacked", "class": "field-label", "purpose": "Above the field in the default variant, identical to TextField" }, { "id": "label-inset", "class": "label", "purpose": "On the top border in the inset variant — Avantt SemiBold at --fs-ui-small. This is .label, not .field-label, so the required marker carries its own rule (.md-input .label .req); the shared .field-label .req does not reach it." }, { "id": "trailing", "class": "trailing icon-r", "purpose": "calendar_today glyph, 18px; a button with a focus ring only when onTrailingClick is passed" }, { "id": "supporting", "class": "supporting / field-help", "purpose": "Line below the field — .supporting when inset, .field-help when stacked. --error when invalid" } ], "states": [ "default", "hover", "focus", "error", "error-focus", "disabled" ], "css_only": false, "react": { "module": "components/DatePicker/DatePicker.jsx", "types": "components/DatePicker/DatePicker.d.ts", "export": "DateField", "controlled_props": [ "value" ], "props": [ "label", "variant", "required", "value", "onChange", "placeholder", "help", "error", "disabled", "focused", "onTrailingClick", "id", "name" ] }, "state_matrix": { "default": { "selector": ".md-input", "changes": { "height": "--control-h", "border": "1px solid --md-outline", "border-radius": "--radius-sm", "background": "--md-surface" } }, "hover": { "trigger": ":hover", "changes": { "border-color": "--md-on-surface" } }, "focus": { "trigger": ":focus-within", "changes": { "border": "2px solid --switch-contrast", "padding": "0 13px", "box-shadow": "--focus-ring", "label-color": "--md-primary" }, "note": "Padding drops 1px so the 2px stroke does not shift the text." }, "error": { "trigger": ".is-error", "changes": { "border-color": "--error", "label-color": "--error", "supporting-color": "--error" } }, "error-focus": { "trigger": ".is-error:focus-within", "changes": { "border": "2px solid --error", "box-shadow": "0 0 0 3px color-mix(--error 32%)" }, "note": "Keeps the halo but in the error palette, so the field still reads invalid rather than merely selected." }, "disabled": { "trigger": "[disabled]", "changes": { "note": "Inherits the input disabled colour." } } }, "m3_policy": { "inherits_from": "Material Design 3", "inherited": [ "component structure — modal and docked pickers, single and range, dial and numeric time", "interaction model — arrow-key navigation, type-to-jump, year/month dropdowns, drag range selection, dial drag", "accessibility — ARIA roles, focus rings, landmarks, RTL, locale-aware day-of-week order", "layout dimensions — header height, 40x40 cells single / 36x36 range, elevation, motion timings" ], "overridden": [ "colour, through the --md-* bridge in tokens.css", "type — faces AND sizes both come from the Swivel scale; M3's Roboto recommendation is not used", "radius follows the Swivel scale — M3's 16px container becomes --radius-xl (12px)" ], "why": "Pickers are deceptively expensive to build well. M3 already solves keyboard nav, locale, range selection, year jumps, and a11y. Visually a picker reads as Swivel; structurally and behaviourally it reads as M3.", "canonical_source": "design-system/Date and Time.html" }, "type_contract": { "faces": "Avantt (--font-display) for headlines, month labels, day-of-week, text buttons, and the time readout. Antarctica (--font-body) for day cells, the input value, eyebrows, and supporting lines. M3's Roboto recommendation does not apply.", "sizes": "Every size resolves from the Swivel type scale — no literal px. --fs-h3 headline, --fs-h4 range headline, --fs-ui-default month/dow-adjacent, --fs-ui-caps day cells and text buttons, --fs-ui-small eyebrows and supporting, --fs-ui-metric time readout, --fs-ui-small inset label.", "what_is_m3": "Only the layout dimensions are M3 — cell box 40x40 single / 36x36 range, header height, elevation, motion. Type and colour are both Swivel.", "note": "The time readout was 40px, which sits between --fs-h2 and --fs-ui-metric with no token behind it; it now uses --fs-ui-metric (32px), the same token as a KPI readout, which is what it is." }, "docked_pairing": { "rule": "onTrailingClick opens a DatePicker docked under the field. Without it the calendar glyph is decorative and should not be shown as interactive.", "markup": "Wrap the field in a position: relative container and absolutely position the picker at top: calc(100% + 8px), z-index above the form.", "picker_props": "actions={false} — a docked picker commits on selection, so a Cancel/OK row would be a second, redundant commit. Pass defaultView so it opens on the current value's month.", "dismissal": "Outside click and Escape both close it. The field keeps ownership of the value." }, "variants": [ { "id": "default", "class": "field", "purpose": "Stacked label — the same .field contract as TextField, for a date that is one of an object's properties" }, { "id": "inset-label", "class": "md-input", "purpose": "Label notched into the top stroke, at --control-h, for a control that changes what a table shows" } ], "variant_choice": { "question": "What does the date belong to?", "stacked": "A property of the object being edited — flight start, contract date, a field in a create or edit form. It sits among TextFields and SelectFields and must be indistinguishable from them.", "inset": "A control over what is displayed — a table toolbar filter, a date range above a list, anything in a dense row of controls at --control-h.", "why": "The two treatments are not interchangeable styling. A stacked label reads as a form field the user is filling in; an inset label reads as a control acting on the view." } }, { "id": "date-picker", "name": "DatePicker", "category": "inputs", "anchor": "Date and Time.html#date-picker", "class_root": ".md-datepicker", "note": "Calendar for one date or a range. Single is 360px with 40x40 cells; range is 680px showing two months with a ribbon fill and 36x36 cells — an ad-ops flight is almost always read across a month boundary. Six week rows always render, so the grid height never jumps between months.", "variants": [ { "id": "single", "class": "md-datepicker", "purpose": "One date. 360px, 40x40 cells" }, { "id": "range", "class": "md-range", "purpose": "Two months side by side. 680px, 36x36 cells, ribbon fill between endpoints" }, { "id": "range + presets", "class": "md-range has-presets", "purpose": "Range with a left rail of relative-range chips. The dialog becomes a two-column grid; the rail spans both month rows" } ], "slots": [ { "id": "header", "class": "md-dp-header", "purpose": "--md-surface-container band holding the eyebrow and the headline date" }, { "id": "eyebrow", "class": "md-dp-eyebrow", "purpose": "Caps line naming what is being picked" }, { "id": "nav", "class": "md-dp-nav", "purpose": "Prev/next .md-icon-btn pair with the month label. In range mode the label spans both months (\"August – September 2026\") — never the first month alone, which the per-month .md-range-month-label already names." }, { "id": "cell", "class": "md-dp-cell", "purpose": "Day button. .is-today outlines in --md-primary, .is-selected fills it, .is-muted dims adjacent months" }, { "id": "ribbon", "class": "in-range", "purpose": "::before fill between endpoints; .range-start / .range-end round the ends. A 3-layer stack — ribbon, endpoint circle, then .md-day-num on top" }, { "id": "actions", "class": "md-dp-actions", "purpose": ".md-text-btn pair; omit with actions={false} for a docked picker" }, { "id": "inert-cell", "class": "is-inert", "purpose": "Range mode only — an adjacent-month cell. Disabled, aria-hidden, pointer-events none, and both pseudo-elements suppressed so no ribbon or endpoint paints. The same date is a real cell in the other grid." }, { "id": "presets", "class": "md-range-presets", "purpose": "Optional left rail of relative ranges, shown only when `presets` is passed. Chips hug their text (align-items: flex-start) — a stretched chip reads as a list of buttons. Separated by a --md-outline border that reaches the full dialog height (align-self: stretch, since the grid is align-items: start for the content column). The rail takes grid-row: 1 / span 99 rather than 1 / -1 — the latter resolves against the explicit grid and collapses to row 1 — and every non-rail child is pinned to grid-column 2, or auto-placement drops the month nav and action row into the rail." }, { "id": "preset", "class": "md-preset", "purpose": "One chip, hugging its label. --md-surface-container at rest; .is-active takes --switch-bg with a --md-primary border, the same tonal fill as the range ribbon, so the chip and the span it produced read as one thing rather than competing with the solid selected endpoints. .is-reset clears rather than selects, so it sits apart with a transparent fill and an outline." } ], "states": [ "default", "hover", "today", "selected", "in-range", "outside-month", "keyboard", "preset-active" ], "css_only": false, "react": { "module": "components/DatePicker/DatePicker.jsx", "types": "components/DatePicker/DatePicker.d.ts", "export": "DatePicker", "controlled_props": [ "value" ], "required_props": [], "props": [ "mode", "value", "onChange", "onCancel", "onConfirm", "eyebrow", "defaultView", "actions", "confirmLabel", "cancelLabel", "presets", "today" ], "exports": [ "DatePicker", "RANGE_PRESETS" ] }, "state_matrix": { "default": { "selector": ".md-dp-cell", "changes": { "width": "40px", "height": "40px", "border-radius": "50%", "font-weight": "500" } }, "hover": { "trigger": ":hover", "changes": { "background": "--md-state-hover" } }, "today": { "trigger": ".is-today", "changes": { "border": "1px solid --md-primary", "color": "--md-primary" }, "note": "Also carries aria-current=\"date\"." }, "selected": { "trigger": ".is-selected", "changes": { "background": "--md-primary", "color": "--md-on-primary (= --graphite-contrast, near-black in both themes)" } }, "in-range": { "trigger": ".in-range", "changes": { "::before": "--md-primary-container ribbon, inset 4px -4px" }, "note": "Range cells isolate their own stacking context so the ribbon sits under the endpoint circle and both sit under the day number." }, "outside-month": { "trigger": ".is-muted", "changes": { "color": "--md-on-surface-variant", "opacity": "0.4", "note": "In range mode these also take .is-inert: M3 does not paint range fill on adjacent-month cells, and a click there would set an endpoint from the wrong grid." } }, "keyboard": { "trigger": "arrow keys", "changes": { "note": "Arrows move by day and week and pull the view to the new month; only the anchored cell is tabbable (roving tabindex)." } }, "preset-active": { "trigger": ".md-preset.is-active", "selector": ".md-preset.is-active", "changes": { "background": "--switch-bg", "color": "--md-on-primary-container", "border-color": "--md-primary" }, "note": "Tonal, matching the range ribbon rather than the solid selected endpoints. Derived by comparing the current selection to what each preset produces, not stored — so a preset stays lit after a reload or a programmatic set, and stops being lit the moment the user edits either end in the grid." } }, "range_behaviour": "First click sets the anchor and fires { start, end: null }. The second closes the range and fires the ordered pair, flipping it if the user picked backwards.", "m3_policy": { "inherits_from": "Material Design 3", "inherited": [ "component structure — modal and docked pickers, single and range, dial and numeric time", "interaction model — arrow-key navigation, type-to-jump, year/month dropdowns, drag range selection, dial drag", "accessibility — ARIA roles, focus rings, landmarks, RTL, locale-aware day-of-week order", "layout dimensions — header height, 40x40 cells single / 36x36 range, elevation, motion timings" ], "overridden": [ "colour, through the --md-* bridge in tokens.css", "type — faces AND sizes both come from the Swivel scale; M3's Roboto recommendation is not used", "radius follows the Swivel scale — M3's 16px container becomes --radius-xl (12px)" ], "why": "Pickers are deceptively expensive to build well. M3 already solves keyboard nav, locale, range selection, year jumps, and a11y. Visually a picker reads as Swivel; structurally and behaviourally it reads as M3.", "canonical_source": "design-system/Date and Time.html" }, "type_contract": { "faces": "Avantt (--font-display) for headlines, month labels, day-of-week, text buttons, and the time readout. Antarctica (--font-body) for day cells, the input value, eyebrows, and supporting lines. M3's Roboto recommendation does not apply.", "sizes": "Every size resolves from the Swivel type scale — no literal px. --fs-h3 headline, --fs-h4 range headline, --fs-ui-default month/dow-adjacent, --fs-ui-caps day cells and text buttons, --fs-ui-small eyebrows and supporting, --fs-ui-metric time readout, --fs-ui-small inset label.", "what_is_m3": "Only the layout dimensions are M3 — cell box 40x40 single / 36x36 range, header height, elevation, motion. Type and colour are both Swivel.", "note": "The time readout was 40px, which sits between --fs-h2 and --fs-ui-metric with no token behind it; it now uses --fs-ui-metric (32px), the same token as a KPI readout, which is what it is." }, "contrast": { "rule": "--md-on-primary is --graphite-contrast, near-black in both themes.", "not": "--white. --md-primary maps to --switch-contrast, which is bright in BOTH themes (#0097A7 light, #00E5FF dark), so white ink puts a selected date at ~3.4:1 in light and ~1.4:1 in dark.", "measured": "13.7:1 light / 11.9:1 dark on a selected day cell; 6.0:1 / 11.9:1 on a selected dial mark.", "precedent": "The same fix .btn-accent uses — any control filled with switch cyan needs ink that does not invert." }, "presets": { "default_set": [ "Today", "Yesterday", "This Week", "Last Week", "Last 7 Days", "Last 14 Days", "Last 30 Days" ], "export": "RANGE_PRESETS — import to extend rather than replace: presets={[...RANGE_PRESETS, mine]}", "inclusive": "Day counts include today, so \"Last 7 Days\" spans 7 cells, not 8.", "today_prop": "presets compute from the `today` prop, defaulting to the real date — pass a fixed one for a deterministic specimen or test.", "when": "Turn presets on for any operational range picker. Leave them off only when the span is inherently absolute — a flight, a contract term.", "optional": "Off by default. The rail renders only when `presets` is passed — the plain range picker is unchanged." } }, { "id": "time-picker", "name": "TimePicker", "category": "inputs", "anchor": "Date and Time.html#time-picker", "class_root": ".md-timepicker", "note": "M3 time picker in both spec'd modes. Dial is the default and is faster for round times (00, 15, 30, 45); input turns the hour and minute into text fields for sub-minute precision or a dense form. The M3 toggle sits on the action row and is preserved. 12-hour with an AM/PM stack; dial hours step 1, dial minutes step 5.", "slots": [ { "id": "field", "class": "md-tp-num", "purpose": "40px display-font hour and minute buttons; .is-active tints with --md-primary-container" }, { "id": "meridiem", "class": "md-tp-ampm", "purpose": "Stacked AM/PM pair, 56px wide" }, { "id": "dial", "class": "md-tp-dial", "purpose": "256px dial with .md-tp-num-mark buttons and a --md-primary hand" }, { "id": "mode-toggle", "class": "md-tp-mode", "purpose": "keyboard / schedule glyph on the action row, margin-right auto so it sits left of Cancel and OK — M3's placement" }, { "id": "labels", "class": "md-tp-labels", "purpose": "\"Hour\" / \"Minute\" captions under the fields, input mode only" } ], "states": [ "hour-active", "minute-active", "mark-selected", "mark-hover", "input-focus" ], "css_only": false, "react": { "module": "components/DatePicker/DatePicker.jsx", "types": "components/DatePicker/DatePicker.d.ts", "export": "TimePicker", "controlled_props": [ "value", "mode" ], "props": [ "value", "onChange", "onCancel", "onConfirm", "eyebrow", "mode", "defaultMode", "onModeChange", "actions" ] }, "state_matrix": { "hour-active": { "trigger": ".md-tp-num.is-active", "changes": { "background": "--md-primary-container", "color": "--md-on-primary-container", "border-color": "--md-primary" } }, "minute-active": { "trigger": ".md-tp-num.is-active", "changes": { "note": "Same treatment — only one field is active at a time." } }, "mark-selected": { "trigger": ".md-tp-num-mark.is-selected", "changes": { "background": "--md-primary", "color": "--md-on-primary (= --graphite-contrast)" } }, "mark-hover": { "trigger": "button.md-tp-num-mark:hover:not(.is-selected)", "changes": { "background": "--md-state-hover" } }, "input-focus": { "trigger": ".md-tp-num.is-input:focus-within", "changes": { "border-color": "--md-primary", "box-shadow": "--focus-ring" } } }, "m3_policy": { "inherits_from": "Material Design 3", "inherited": [ "component structure — modal and docked pickers, single and range, dial and numeric time", "interaction model — arrow-key navigation, type-to-jump, year/month dropdowns, drag range selection, dial drag", "accessibility — ARIA roles, focus rings, landmarks, RTL, locale-aware day-of-week order", "layout dimensions — header height, 40x40 cells single / 36x36 range, elevation, motion timings" ], "overridden": [ "colour, through the --md-* bridge in tokens.css", "type — faces AND sizes both come from the Swivel scale; M3's Roboto recommendation is not used", "radius follows the Swivel scale — M3's 16px container becomes --radius-xl (12px)" ], "why": "Pickers are deceptively expensive to build well. M3 already solves keyboard nav, locale, range selection, year jumps, and a11y. Visually a picker reads as Swivel; structurally and behaviourally it reads as M3.", "canonical_source": "design-system/Date and Time.html" }, "type_contract": { "faces": "Avantt (--font-display) for headlines, month labels, day-of-week, text buttons, and the time readout. Antarctica (--font-body) for day cells, the input value, eyebrows, and supporting lines. M3's Roboto recommendation does not apply.", "sizes": "Every size resolves from the Swivel type scale — no literal px. --fs-h3 headline, --fs-h4 range headline, --fs-ui-default month/dow-adjacent, --fs-ui-caps day cells and text buttons, --fs-ui-small eyebrows and supporting, --fs-ui-metric time readout, --fs-ui-small inset label.", "what_is_m3": "Only the layout dimensions are M3 — cell box 40x40 single / 36x36 range, header height, elevation, motion. Type and colour are both Swivel.", "note": "The time readout was 40px, which sits between --fs-h2 and --fs-ui-metric with no token behind it; it now uses --fs-ui-metric (32px), the same token as a KPI readout, which is what it is." }, "variants": [ { "id": "dial", "class": null, "purpose": "Default — 256px dial. Tapping the hour or minute field chooses which value the dial drives" }, { "id": "input", "class": "is-input", "purpose": "Typed entry. Same 72px field boxes so the toggle does not resize the card" } ], "typing_behaviour": "Keystrokes commit immediately when the partial value is already valid, but clamping happens on blur or Enter — so typing \"1\" on the way to \"11\" is never rewritten under the cursor. Non-digits are stripped and entry caps at two characters.", "contrast": { "rule": "--md-on-primary is --graphite-contrast, near-black in both themes.", "not": "--white. --md-primary maps to --switch-contrast, which is bright in BOTH themes (#0097A7 light, #00E5FF dark), so white ink puts a selected date at ~3.4:1 in light and ~1.4:1 in dark.", "measured": "13.7:1 light / 11.9:1 dark on a selected day cell; 6.0:1 / 11.9:1 on a selected dial mark.", "precedent": "The same fix .btn-accent uses — any control filled with switch cyan needs ink that does not invert." } }, { "id": "select_field", "name": "SelectField", "category": "inputs", "anchor": "Swivel Component Library.html#c-select-fields", "class_root": ".field", "react": { "module": "components/SelectField/SelectField.jsx", "types": "components/SelectField/SelectField.d.ts", "export": "SelectField", "variant_prop": "variant", "default_variant": "default", "controlled_props": { "value": "defaultValue", "open": "defaultOpen" }, "composes": [ "select_menu" ] }, "note": "Field-shaped trigger that owns a SelectMenu popover. Closes on outside click, Escape, and on choice when not multi. With multi + chips it renders the .tag-input box, showing each selection as a dismissible chip rather than an 'N selected' summary — prefer that when the user needs to see and remove individual values. Multi-select shows dismissible chips (chips prop), not an \"N selected\" summary. Inside .field-inset the chips trigger draws no box of its own.", "variants": [ { "id": "default", "class": null, "purpose": "Label stacked above the trigger" }, { "id": "inset-label", "class": "field-inset", "purpose": "Label notched into the top stroke" } ], "states": [ "default", "open", "selected", "error", "disabled" ], "css_only": false, "state_matrix": { "default": { "selector": ".field-inset", "changes": { "trigger": "readonly input + arrow_drop_down glyph" } }, "open": { "selector": ".field-inset.is-focused", "changes": { "border-width": "2px", "border-color": "--switch-contrast", "box-shadow": "--focus-ring", "menu-display": "block" } }, "selected": { "changes": { "trigger": "single: option label · multi: dismissible chips (never an N-selected summary)" } }, "error": { "selector": ".field-inset.is-error", "changes": { "border-color": "--error", "label-color": "--error" } }, "disabled": { "selector": ".field-inset.is-disabled", "changes": { "background": "--graphite-10", "color": "--graphite-50" } } } }, { "id": "select_menu", "name": "SelectMenu", "category": "inputs", "anchor": "Swivel Component Library.html#c-select-menus", "class_root": ".select-menu", "react": { "module": "components/SelectMenu/SelectMenu.jsx", "types": "components/SelectMenu/SelectMenu.d.ts", "export": "SelectMenu", "controlled_props": { "value": "defaultValue" } }, "note": "Popover dropdown — the surface SelectField opens, also usable on its own. Options are set by props, not variant classes: icons come from item.icon / item.iconUrl, sections from items with a header, search and multi from the search and multi props.", "variants": [ { "id": "default", "purpose": "Standard option list" }, { "id": "with-icons", "purpose": "Leading platform logo or glyph per option" }, { "id": "with-search", "purpose": "Filterable list with inline search field" }, { "id": "multi-select", "purpose": "Checkbox selection, multiple values" }, { "id": "with-sections", "purpose": "Options grouped under section headers" } ], "states": [ "closed", "open", "item-hover", "item-selected", "item-disabled", "loading", "empty" ], "css_only": false, "state_matrix": { "closed": { "changes": { "display": "none" } }, "open": { "selector": ".select-menu", "changes": { "background": "--surface-base", "border": "1px solid --surface-stroke", "box-shadow": "--elev-2", "border-radius": "--radius-md" } }, "item-hover": { "selector": ".sm-item:hover", "changes": { "background": "--graphite-10", "only-link-display": "inline-flex" } }, "item-selected": { "selector": ".sm-item.is-selected", "changes": { "background": "--slate-bg", "check-border-color": "--slate-100" } }, "item-disabled": { "selector": ".sm-item.is-disabled", "changes": { "color": "--graphite-40", "pointer-events": "none" } }, "loading": { "changes": { "body": "replaced by a loading row" } }, "empty": { "changes": { "body": "replaced by an empty row; offer onCreate when the query could become a value" } } }, "slots": [ { "id": "search", "class": "sm-search", "purpose": "Inline filter field pinned at the top of the list" }, { "id": "section", "class": "sm-header", "purpose": "Group header above a run of options" }, { "id": "check", "class": "sm-check", "purpose": "Multi-select box; .is-checked / .is-indeterminate. Same treatment as the standalone .checkbox" }, { "id": "icon", "class": "sm-icon-l", "purpose": "Leading platform logo or Material glyph" }, { "id": "only", "class": "sm-only", "purpose": "Hover-revealed pill on a multi-select row — replaces the selection with just that row" }, { "id": "create", "class": "sm-create", "purpose": "\"+ value\" creator pinned at the bottom" } ], "only_affordance": { "class": ".sm-only", "use_in": "Value menus — a filter's Values list, a Format or Status picker, any list where one value is a legitimate end state.", "never_in": "The table toolbar's column picker.", "why": "\"Only\" replaces the whole selection with one row. For a filter value that is a normal end state. For columns it never is — a table showing one metric with no ID or name column is not a state anyone asked for — and the chip sits exactly where the pointer travels to reach the checkbox, making the most destructive action in the menu the easiest misclick.", "instead": "Show/Hide All for the bulk move, Reset to return to the default column set." } }, { "id": "tag_input", "name": "TagInput", "category": "inputs", "anchor": "Swivel Component Library.html#c-tag-input", "class_root": ".tag-input", "react": { "module": "components/TagInput/TagInput.jsx", "types": "components/TagInput/TagInput.d.ts", "export": "TagInput", "variant_prop": "variant", "default_variant": "default", "controlled_props": { "value": "defaultValue" } }, "note": "Chips inside are the canonical .chip element. Enter and comma commit the draft; Backspace on an empty draft removes the last tag.", "variants": [ { "id": "default", "class": "tag-input", "purpose": "Label stacked above the field" }, { "id": "inset-label", "class": "field-inset tag-inset", "purpose": "Chips inside the notched-border field" } ], "states": [ "default", "hover", "focused", "with-values", "error", "disabled" ], "css_only": false, "state_matrix": { "default": { "selector": ".tag-input", "changes": { "border": "1px solid --graphite-20", "min-height": "34px" } }, "hover": { "trigger": ":hover", "changes": { "clear-icon-opacity": "1" } }, "focused": { "trigger": ":focus-within", "changes": { "border-width": "2px", "border-color": "--switch-contrast", "box-shadow": "--focus-ring" } }, "with-values": { "changes": { "chips": ".chip per value with .chip-dismiss", "inset-variant": ".field-inset .tag-input draws no box of its own" } }, "error": { "selector": ".field.is-error .tag-input", "changes": { "border-color": "--error", "clear-icon-color": "--error" } }, "disabled": { "selector": ".tag-input.is-disabled", "changes": { "background": "--graphite-10", "chip-background": "--graphite-20", "dismiss-display": "none" } } } }, { "id": "checkbox", "name": "Checkbox", "category": "inputs", "anchor": "Swivel Component Library.html#c-forms", "class_root": ".checkbox", "note": "A real , appearance:none, styled to match .sm-check so a menu row and a standalone box read identically. Table selection columns inherit the same rules via .table-card .cell-select input[type=\"checkbox\"] at 15px. For a setting that applies the moment it is flipped, use Switch. There is no Radio in this system — single-choice pickers are a ButtonGroup or a SelectField.", "variants": [ { "id": "md", "class": null, "size_px": 18, "purpose": "Default — forms and standalone opt-ins" }, { "id": "sm", "class": "checkbox-sm", "size_px": 15, "purpose": "Table selection columns and dense lists" } ], "slots": [ { "id": "row", "class": "checkbox-row", "purpose": "Label wraps the input so the whole row is the hit target" }, { "id": "help", "class": "cb-help", "purpose": "Secondary line under the label, inside .cb-text" } ], "states": [ "default", "hover", "checked", "indeterminate", "focus", "disabled" ], "css_only": false, "react": { "module": "components/Checkbox/Checkbox.jsx", "types": "components/Checkbox/Checkbox.d.ts", "export": "Checkbox", "controlled_props": [ "checked" ] }, "state_matrix": { "default": { "selector": ".checkbox", "changes": { "width": "18px", "height": "18px", "border": "2px solid --graphite-bg", "border-radius": "2px", "background": "transparent" } }, "hover": { "trigger": ":hover:not(:disabled)", "changes": { "border-color": "--slate-100" } }, "checked": { "trigger": ":checked", "changes": { "background-color": "--slate-100", "border-color": "--slate-100", "background-image": "inline SVG check, --white stroke" } }, "indeterminate": { "trigger": ":indeterminate", "changes": { "background-color": "--slate-100", "border-color": "--slate-100", "background-image": "inline SVG dash, --white fill" }, "note": "Set via the DOM property, not an attribute — the component syncs it on the ref." }, "focus": { "trigger": ":focus-visible", "changes": { "outline": "none", "box-shadow": "--focus-ring" } }, "disabled": { "trigger": ":disabled", "changes": { "opacity": "0.4", "cursor": "default", "row-color": "--graphite-30 (via .checkbox-row.is-disabled)" } } } }, { "id": "chip", "name": "Chip", "category": "data", "anchor": "Swivel Component Library.html#c-chips", "class_root": ".chip", "react": { "module": "components/Chip/Chip.jsx", "types": "components/Chip/Chip.d.ts", "export": "Chip", "size_prop": "size", "default_size": "md" }, "note": "Pill is the default shape; there is no round class. Style is set by boolean props, not a variant enum.", "variants": [ { "id": "selected", "prop": "selected", "class": "is-selected", "purpose": "Filled selected state" }, { "id": "outlined", "prop": "outlined", "class": "is-outlined", "purpose": "Outlined unselected style" }, { "id": "accent", "prop": "accent", "class": "is-accent", "purpose": "Switch-accent fill" }, { "id": "square", "prop": "square", "class": "chip-square", "purpose": "Square corners instead of pill" } ], "sizes": [ { "id": "sm", "class": "chip-sm" }, { "id": "md", "class": null }, { "id": "lg", "class": "chip-lg" } ], "supports_icon": true, "supports_dismiss": true, "states": [ "default", "selected", "dismiss-hover", "disabled" ], "css_only": false, "state_matrix": { "default": { "selector": ".chip", "changes": { "background": "--surface-muted", "border-radius": "--radius-full" } }, "selected": { "selector": ".chip.is-selected", "changes": { "background": "--graphite-90", "color": "--surface-base" } }, "dismiss-hover": { "selector": ".chip .chip-dismiss:hover", "changes": { "color": "--graphite-90" } }, "disabled": { "selector": ".chip.is-disabled", "changes": { "opacity": "0.4", "pointer-events": "none" } } } }, { "id": "badge", "name": "Badge", "category": "data", "anchor": "Swivel Component Library.html#c-status-badges", "class_root": ".badge", "react": { "module": "components/Badge/Badge.jsx", "types": "components/Badge/Badge.d.ts", "export": "Badge", "tone_prop": "tone", "default_tone": "neutral" }, "purpose": "A single prominent status callout — a header, a card, a summary line. NOT a repeated per-row status column: use the state cell kind (Table.cell_kinds) there instead.", "tones": [ { "id": "success", "class": "badge-success", "token": "--success" }, { "id": "warning", "class": "badge-warning", "token": "--warning" }, { "id": "info", "class": "badge-info", "token": "--info" }, { "id": "error", "class": "badge-error", "token": "--error" }, { "id": "neutral", "class": "badge-neutral", "token": "--graphite-70" }, { "id": "pending", "class": "badge-pending", "token": "--graphite-50" } ], "supports_dot": true, "supports_icon": true, "semantic_tokens": [ "--success", "--warning", "--info", "--error" ], "css_only": false, "state_matrix": { "default": { "selector": ".badge.badge-", "changes": { "background": "---bg", "color": "---fg", "border-radius": "--radius-sm" } } }, "states": [ "default" ], "avoid": "One per table row. A column of Badges is a wall of pills that makes the rest of the row harder to read — see the status-column-is-an-icon rule and Table.cell_kinds.kind \"state\"." }, { "id": "platform_icon", "name": "PlatformIcon", "category": "data", "anchor": "Swivel Component Library.html#c-platform-icons", "class_root": ".pf-tile", "note": "Third-party platform logos. Never recolor, restyle, or substitute. Always render on a neutral white plate. Assets in assets/partners/.", "sizes": [ { "id": "symbol", "plate_px": 64, "img_max_px": 40 }, { "id": "lockup", "plate_px": 116, "img_max_px": 92 } ], "platforms": [ "GAM", "DCM", "innovid", "operative", "springserve", "magnite", "freewheel", "salesforce", "publica", "slack" ], "missing_assets": [], "css_only": false, "react": { "module": "components/PlatformIcon/PlatformIcon.jsx", "types": "components/PlatformIcon/PlatformIcon.d.ts", "export": "PlatformIcon", "size_prop": "size", "default_size": "symbol" }, "state_matrix": { "default": { "selector": ".pf-plate", "changes": { "background": "white plate", "rule": "never recolor or restyle a partner mark" } } }, "states": [ "default" ] }, { "id": "chat_sticker", "name": "ChatSticker", "category": "brand", "anchor": "Swivel Component Library.html#c-brand-stickers", "note": "Animated brand GIF for use as a standalone chat message. Never embed inside a text bubble. Transparent background — no plate or shadow. The class sits on the itself, not a wrapper — target it as img.chat-sticker. basePath takes a prefix like \"../..\" and the component adds the separator. Its chat context is the .as-* agent workspace vocabulary — .as-working uses size=\"inline\" (32px) — a real ChatSticker size, not a caller-side override — sized to sit beside the working-state text without crowding it. A separate .beacon-* demo block used to exist in components.css and was removed: there is one chat contract, not two.", "sizes": [ { "id": "reaction", "px": 48, "use": "Reaction-style use" }, { "id": "thread", "px": 80, "use": "Standard thread message" }, { "id": "emphasis", "px": 128, "use": "Emphasis moments only" } ], "assets": [ "assets/brand/keep_swiveling.gif" ], "reduced_motion": "Substitute first frame as static when prefers-reduced-motion: reduce", "css_only": false, "react": { "module": "components/ChatSticker/ChatSticker.jsx", "types": "components/ChatSticker/ChatSticker.d.ts", "export": "ChatSticker", "size_prop": "size", "default_size": "thread" }, "class_root": ".chat-sticker", "variants": [ { "id": "reaction", "class": "chat-sticker-reaction" }, { "id": "thread", "class": "chat-sticker-thread" }, { "id": "emphasis", "class": "chat-sticker-emphasis" }, { "id": "inline", "class": "chat-sticker-inline", "purpose": "32px — beside a line of running text (a working-state label, a footer note) where reaction's 48px would crowd the text" } ], "state_matrix": { "default": { "selector": ".chat-sticker", "changes": { "background": "none", "box-shadow": "none" } }, "reduced-motion": { "trigger": "@media (prefers-reduced-motion: reduce)", "changes": { "src": "pass staticSrc (first frame)" } } }, "states": [ "default", "reduced-motion" ] }, { "id": "switch", "name": "Switch", "category": "inputs", "anchor": "Swivel Component Library.html#c-controls", "class_root": ".switch", "note": "Binary on/off for a single setting (dark mode, auto-pause, notifications). Not for choosing between options — that is a ButtonGroup. Track is .switch-track; the label sits beside it inside .switch. Add role=\"switch\" and aria-checked when the element is interactive.", "variants": [ { "id": "default", "class": null, "purpose": "Graphite fill when on" }, { "id": "accent", "class": "accent", "purpose": "Switch-cyan fill when on — for the one setting that matters most on a surface" } ], "states": [ "off", "on", "disabled" ], "state_class": "is-on", "css_only": false, "react": { "module": "components/Switch/Switch.jsx", "types": "components/Switch/Switch.d.ts", "export": "Switch", "value_prop": "checked" }, "state_matrix": { "off": { "selector": ".switch", "changes": { "track-background": "--graphite-30", "knob-left": "2px" } }, "on": { "selector": ".switch.is-on", "changes": { "track-background": "--graphite-90 (--switch-100 with .accent)", "knob-left": "16px" } }, "disabled": { "trigger": ":disabled", "changes": { "opacity": "0.4", "pointer-events": "none" } } } }, { "id": "theme_switch", "name": "ThemeSwitch", "category": "inputs", "anchor": "Swivel Component Library.html#c-controls", "class_root": ".theme-switch", "note": "THE canonical light/dark control. Sun icon, track, moon icon, no text label — the icon on the active side tints slate, the other stays muted. Drive it from aria-checked (true = dark), never from a button group. Track is .ts-track, icons are .ts-ico.ts-sun / .ts-ico.ts-moon. Add .is-fixed to pin it top-right on a specimen page. Persist the choice in localStorage under swivel-theme and apply it before first paint; first visit defaults to dark.", "variants": [ { "id": "inline", "class": null, "purpose": "Sits in a header or sidebar alongside other controls" }, { "id": "fixed", "class": "is-fixed", "purpose": "Pinned top-right on a showcase or specimen page" } ], "states": [ "light", "dark", "focus-visible" ], "state_attr": "aria-checked", "css_only": false, "react": { "module": "components/ThemeSwitch/ThemeSwitch.jsx", "types": "components/ThemeSwitch/ThemeSwitch.d.ts", "export": "ThemeSwitch", "value_prop": "theme", "default_value": "dark" }, "state_matrix": { "light": { "selector": ".theme-switch[aria-checked=\"false\"]", "changes": { "sun-color": "--slate-base", "moon-color": "--graphite-40", "knob-left": "-2px", "document-attr": "data-theme=\"light\"" } }, "dark": { "selector": ".theme-switch[aria-checked=\"true\"]", "changes": { "moon-color": "--slate-base", "sun-color": "--graphite-40", "knob-left": "18px", "document-attr": "data-theme=\"dark\" (or absent — dark is the default)" } }, "focus-visible": { "trigger": ":focus-visible", "changes": { "track-box-shadow": "--focus-ring", "outline": "none" } } } }, { "id": "activity-panel", "name": "ActivityPanel", "category": "feedback", "anchor": "components/ActivityPanel/activitypanel.html", "class_root": ".activity", "note": "A reverse-chronological stream of what users and agents did, each row expandable into the record it wrote. Use for any audit, history, or activity surface. Not a Table: a table cannot carry a nested before/after diff, and it would offer sorting and selection that an audit log does not have. Not a bare timeline either — the point is that each row opens.", "slots": [ { "id": "day", "class": "act-day", "purpose": "Day divider as a chip, left-aligned — a full-width rule across the stream reads as a section break rather than a date change" }, { "id": "event", "class": "act-event", "purpose": "One event card; .act-head is its 64px time / 36px avatar / body / toggle grid" }, { "id": "time", "class": "act-time", "purpose": "Time of day only, tabular-nums, right-aligned. The day belongs to the group" }, { "id": "avatar", "class": "act-avatar", "purpose": "Carries the ENTITY glyph in --slate-base on --slate-bg — account, creative, media buy, proposal, automation, script." }, { "id": "badge", "class": "act-badge", "purpose": "Carries the ACTION, as a 17px badge on the avatar with an outset --surface-base ring. Tonal, using the same --bg / --fg pairing as Badge and Alert: .is-create success, .is-update warning, .is-sync --switch-bg with --switch-contrast ink (the accent already means \"the system did this\"; there is no --switch-fg), .is-delete error, .is-neutral --graphite-10 with --graphite-90. At 17px a saturated fill is a bright dot that pulls the eye off the sentence, and the tonal pair inverts correctly per theme on its own. Two facts in one mark, so the sentence need not label either." }, { "id": "line", "class": "act-line", "purpose": "The sentence: actor, verb, entity type, ID chip, then the object name. .act-actor and .act-object take --graphite-90 600 because they are the two things scanned for; the verb and entity type stay --graphite-bg. The .id-chip sits BEFORE the object name so the ID reads as a prefix to it rather than trailing off the end of a long name." }, { "id": "meta", "class": "act-meta", "purpose": "Context values joined by .am-sep middots — principal, account, environment, token. Prefixed with a smart_toy glyph when the event is agent-initiated" }, { "id": "detail", "class": "act-detail", "purpose": "Field/Value or Field/Before/After table. tr.is-nested tints for depth; .ad-unset renders an absent value as italic \"Not Set\"; a row with no value at all is a group heading" }, { "id": "rail", "class": "filter-rail", "purpose": "The stream's filters, stacked in a card beside it — .fr-head holds the .fr-title and a right-aligned clear-filters IconButton (it acts on the whole rail, so it belongs to the rail rather than the toolbar over the content), then .fr-group with .fr-legend and an .fr-row per option. Each row reveals an .fr-only chip on hover or chip focus that narrows the facet to that one value; in a list of seven, the alternative is unchecking six. The row is a