Menu
v0.10.1

Traits / MarkBar

MarkBar

Canonical rectangular mark for magnitude comparisons.

Generated from @oods/foundry 0.10.1

Group
viz.mark
Maturity
alpha
Contexts
dashboard, detail, form, list

Supports stacked or grouped categories and enforces RDS.7 accessibility requirements for redundant encodings.

Fields it adds

FieldTypeRequiredDescription
viz_mark_type string (bar) yes Normalized mark identifier consumed by renderer adapters.
viz_mark_orientation string (vertical, horizontal) yes Orientation flag for aligning axes and fallbacks.
viz_mark_band_padding number no Fractional padding between bars within a category.
viz_mark_corner_radius number no Corner radius applied to rendered bars.
viz_mark_stacking string (auto, normalize, none) no Stacking semantics applied to grouped series.
viz_mark_role string yes Semantic role used by heuristics, docs, and filtering.
viz_mark_a11y_label string yes Accessible description fragment for assistive tech fallbacks.

What it shows in each context

detail
VizMarkPreview
dashboard
VizMarkPreview
form
VizMarkControls
list
VizRoleBadge

dashboard isn't one of the 7 contexts screens are composed in, so it has no page of its own here.

Parameters

chart object
Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views.
title string
Title for the bound chart and its accessible figure.
description string
Description of the bound chart measurements and units.
renderIntent string
JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand.
previewSvg string
Static SVG returned by viz.render for the authored sample; omitted until a chart is rendered.
orientation string, required
Axis orientation used for laying out bar rectangles.
bandPadding number
Fractional padding between category bands (0-0.5).
cornerRadius number
Pixel radius applied to bar corners.
stacking string
Aggregation strategy when multiple series share the mark.

Objects that use it

The trait file

traits/viz/mark-bar.trait.yaml 
trait:
  name: MarkBar
  version: 0.2.0
  description: |
    Canonical rectangular mark for magnitude comparisons. Supports stacked
    or grouped categories and enforces RDS.7 accessibility requirements for
    redundant encodings.
  category: viz.mark
  tags:
    - viz
    - mark
    - bar
    - comparison

parameters:
  - {"name": "chart", "type": "object", "required": false, "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."}
  - {"name": "title", "type": "string", "required": false, "description": "Title for the bound chart and its accessible figure."}
  - {"name": "description", "type": "string", "required": false, "description": "Description of the bound chart measurements and units."}
  - {"name": "renderIntent", "type": "string", "required": false, "default": "{}", "description": "JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand."}
  - {"name": "previewSvg", "type": "string", "required": false, "description": "Static SVG returned by viz.render for the authored sample; omitted until a chart is rendered."}
  - name: orientation
    type: string
    required: true
    description: Axis orientation used for laying out bar rectangles.
    default: vertical
    validation:
      enum:
        - vertical
        - horizontal
  - name: bandPadding
    type: number
    required: false
    description: Fractional padding between category bands (0-0.5).
    default: 0.1
    validation:
      minimum: 0
      maximum: 0.5
  - name: cornerRadius
    type: number
    required: false
    description: Pixel radius applied to bar corners.
    default: 2
    validation:
      minimum: 0
      maximum: 12
  - name: stacking
    type: string
    required: false
    description: Aggregation strategy when multiple series share the mark.
    default: auto
    validation:
      enum:
        - auto
        - normalize
        - none

schema:
  viz_mark_type:
    type: string
    required: true
    description: Normalized mark identifier consumed by renderer adapters.
    default: bar
    validation:
      enum:
        - bar
  viz_mark_orientation:
    type: string
    required: true
    description: Orientation flag for aligning axes and fallbacks.
    defaultFromParameter: orientation
    validation:
      enum:
        - vertical
        - horizontal
  viz_mark_band_padding:
    type: number
    required: false
    description: Fractional padding between bars within a category.
    defaultFromParameter: bandPadding
    validation:
      minimum: 0
      maximum: 0.5
  viz_mark_corner_radius:
    type: number
    required: false
    description: Corner radius applied to rendered bars.
    defaultFromParameter: cornerRadius
    validation:
      minimum: 0
      maximum: 12
  viz_mark_stacking:
    type: string
    required: false
    description: Stacking semantics applied to grouped series.
    defaultFromParameter: stacking
    validation:
      enum:
        - auto
        - normalize
        - none
  viz_mark_role:
    type: string
    required: true
    description: Semantic role used by heuristics, docs, and filtering.
    default: comparison
  viz_mark_a11y_label:
    type: string
    required: true
    description: Accessible description fragment for assistive tech fallbacks.
    default: Bar mark showing magnitude per category.

semantics:
  viz_mark_type:
    semantic_type: viz.mark.type
    token_mapping: tokenMap(viz.mark.type)
    ui_hints:
      component: VizMarkSummary
  viz_mark_orientation:
    semantic_type: viz.mark.orientation
    token_mapping: tokenMap(viz.mark.orientation)
    ui_hints:
      component: VizOrientationBadge
  viz_mark_band_padding:
    semantic_type: viz.mark.spacing
    token_mapping: tokenMap(viz.mark.spacing)
    ui_hints:
      component: NumericPreview
      unit: fraction
  viz_mark_corner_radius:
    semantic_type: viz.mark.corner_radius
    token_mapping: tokenMap(viz.mark.corner_radius)
    ui_hints:
      component: NumericPreview
      unit: px
  viz_mark_stacking:
    semantic_type: viz.mark.stacking
    token_mapping: tokenMap(viz.mark.stacking)
    ui_hints:
      component: VizStackingHint
  viz_mark_a11y_label:
    semantic_type: a11y.description
    token_mapping: tokenMap(a11y.chart.description)
    ui_hints:
      component: ScreenReaderHint

view_extensions:
  detail:
    - component: VizMarkPreview
      position: top
      priority: 60
      props:
        svgParameter: previewSvg
        typeField: viz_mark_type
        orientationField: viz_mark_orientation
        stackingField: viz_mark_stacking
  dashboard:
    - component: VizMarkPreview
      position: top
      priority: 60
      props:
        svgParameter: previewSvg
        typeField: viz_mark_type
        orientationField: viz_mark_orientation
        stackingField: viz_mark_stacking
  form:
    - component: VizMarkControls
      position: top
      props:
        intentParameter: renderIntent
        orientationField: viz_mark_orientation
        paddingField: viz_mark_band_padding
        stackingField: viz_mark_stacking
        cornerRadiusField: viz_mark_corner_radius
  list:
    - component: VizRoleBadge
      props:
        intentParameter: renderIntent
        labelField: viz_mark_role

tokens:
  # Primary fill color for bar rectangles — maps to the active palette
  viz.mark.bar.fill.default: "var(--cmp-viz-mark-bar-fill)"
  # Stroke outline for bar edges — provides contrast against adjacent bars
  viz.mark.bar.stroke.default: "var(--cmp-viz-mark-bar-stroke)"
  # Spacing token governing gap between category bands
  viz.mark.bar.spacing: "var(--cmp-viz-mark-spacing)"

events:
  mark.hovered:
    description: Fired when a bar is hovered. Payload includes datum values and bar index.
    payload: [datum, index, tone]
  mark.selected:
    description: Fired when a bar is clicked/tapped. Used by InteractionHighlight.
    payload: [datum, index]
  mark.focused:
    description: Fired when a bar receives keyboard focus for accessibility navigation.
    payload: [datum, index]

dependencies:
  - EncodingPositionX
  - EncodingPositionY

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - design@oods.systems
  maturity: alpha
  conflicts_with:
    - MarkLine
    - MarkPoint
    - MarkArea
  accessibility:
    rule_reference: A11Y-R-04
    notes: Requires redundant text/table fallback in paired specs.
  regionsUsed:
    - detail
    - dashboard
    - form
    - list
  examples:
    - RevenueByRegion
    - TicketVolumeByQueue
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)