[Traits](https://oods-foundry.com/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

| Field | Type | Required | Description |
| - | - | - | - |
| `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](https://oods-foundry.com/contexts/detail)

  `VizSizeSummary`

- [form](https://oods-foundry.com/contexts/form)

  `VizSizeControls`

- [list](https://oods-foundry.com/contexts/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)
```