Menu
v0.10.1

Traits / EncodingSize

EncodingSize

Maps a quantitative field to glyph size (radius or area) with governed ranges that can be validated for perceptual correctness and accessibility.

Generated from @oods/foundry 0.10.1

Group
viz.encoding
Maturity
alpha
Contexts
detail, form, list

Fields it adds

FieldTypeRequiredDescription
viz_encoding_size_field string yes Data field bound to glyph size.
viz_encoding_size_strategy string (area, radius) yes Defines whether size is derived from area or radius.
viz_encoding_size_range_min number yes Minimum rendered size in pixels.
viz_encoding_size_range_max number yes Maximum rendered size in pixels.
viz_encoding_size_min_area number no Minimum accessible area to prevent underflow.
viz_encoding_size_max_area number no Maximum accessible area to prevent overflow.
viz_encoding_size_description string no Narrative summary for fallback text/table output.

What it shows in each context

detail
VizSizeSummary
form
VizSizeControls
list
VizEncodingBadge

Parameters

renderIntent string
JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand.
rangeMin number, required
Minimum rendered size in device-independent pixels.
rangeMax number, required
Maximum rendered size in device-independent pixels.
strategy string, required
Interprets values as area or radius for perceptual scaling.
minPixelArea number
Minimum accessible area to avoid disappearing glyphs.
maxPixelArea number
Maximum accessible area to avoid dominating layout.

Objects that use it

No shipped object uses this trait.

The trait file

traits/viz/encoding-size.trait.yaml 
trait:
  name: EncodingSize
  version: 0.2.0
  description: |
    Maps a quantitative field to glyph size (radius or area) with governed
    ranges that can be validated for perceptual correctness and accessibility.
  category: viz.encoding
  tags:
    - viz
    - encoding
    - size

parameters:
  - {"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: rangeMin
    type: number
    required: true
    description: Minimum rendered size in device-independent pixels.
    default: 6
    validation:
      minimum: 2
      maximum: 32
  - name: rangeMax
    type: number
    required: true
    description: Maximum rendered size in device-independent pixels.
    default: 36
    validation:
      minimum: 12
      maximum: 96
  - name: strategy
    type: string
    required: true
    description: Interprets values as area or radius for perceptual scaling.
    default: area
    validation:
      enum:
        - area
        - radius
  - name: minPixelArea
    type: number
    required: false
    description: Minimum accessible area to avoid disappearing glyphs.
    default: 36
  - name: maxPixelArea
    type: number
    required: false
    description: Maximum accessible area to avoid dominating layout.
    default: 576

schema:
  viz_encoding_size_field:
    type: string
    required: true
    description: Data field bound to glyph size.
  viz_encoding_size_strategy:
    type: string
    required: true
    description: Defines whether size is derived from area or radius.
    defaultFromParameter: strategy
    validation:
      enum:
        - area
        - radius
  viz_encoding_size_range_min:
    type: number
    required: true
    description: Minimum rendered size in pixels.
    defaultFromParameter: rangeMin
  viz_encoding_size_range_max:
    type: number
    required: true
    description: Maximum rendered size in pixels.
    defaultFromParameter: rangeMax
  viz_encoding_size_min_area:
    type: number
    required: false
    description: Minimum accessible area to prevent underflow.
    defaultFromParameter: minPixelArea
  viz_encoding_size_max_area:
    type: number
    required: false
    description: Maximum accessible area to prevent overflow.
    defaultFromParameter: maxPixelArea
  viz_encoding_size_description:
    type: string
    required: false
    description: Narrative summary for fallback text/table output.
    default: Size encodes magnitude using governed perceptual scaling.

semantics:
  viz_encoding_size_field:
    semantic_type: viz.encoding.field
    token_mapping: tokenMap(viz.encoding.field)
    ui_hints:
      component: FieldReference
  viz_encoding_size_strategy:
    semantic_type: viz.encoding.size_strategy
    token_mapping: tokenMap(viz.encoding.size_strategy)
    ui_hints:
      component: TextBadge
  viz_encoding_size_range_min:
    semantic_type: viz.encoding.size_range
    token_mapping: tokenMap(viz.encoding.size_range)
    ui_hints:
      component: NumericPreview
      unit: px
  viz_encoding_size_range_max:
    semantic_type: viz.encoding.size_range
    token_mapping: tokenMap(viz.encoding.size_range)
    ui_hints:
      component: NumericPreview
      unit: px
  viz_encoding_size_min_area:
    semantic_type: viz.encoding.a11y_min
    token_mapping: tokenMap(viz.a11y.min_target)
    ui_hints:
      component: NumericPreview
      unit: px^2

view_extensions:
  detail:
    - component: VizSizeSummary
      position: sidebar
      props:
        intentParameter: renderIntent
        field: viz_encoding_size_field
        strategyField: viz_encoding_size_strategy
        minField: viz_encoding_size_range_min
        maxField: viz_encoding_size_range_max
  form:
    - component: VizSizeControls
      position: top
      props:
        intentParameter: renderIntent
        strategyField: viz_encoding_size_strategy
        minField: viz_encoding_size_range_min
        maxField: viz_encoding_size_range_max
        minAreaField: viz_encoding_size_min_area
        maxAreaField: viz_encoding_size_max_area
  list:
    - component: VizEncodingBadge
      props:
        intentParameter: renderIntent
        channel: size
        axis: size
        fieldField: viz_encoding_size_field

tokens:
  viz.encoding.size.range.min: "var(--cmp-viz-size-min)"
  viz.encoding.size.range.max: "var(--cmp-viz-size-max)"
  viz.encoding.size.stroke: "var(--cmp-viz-size-stroke)"

dependencies:
  - ScaleLinear

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - research@oods.systems
  maturity: alpha
  accessibility:
    rule_reference: A11Y-R-02
    notes: Ensures glyphs remain perceivable within governed range.
  regionsUsed:
    - detail
    - form
    - list
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)