component-catalog.json

{
  "lumui_component_catalog": "1.0",
  "compatible_surface": "1.0",
  "status": "stable",
  "common_required": [
    "id",
    "kind"
  ],
  "common_optional": [
    "label",
    "description",
    "help",
    "enabled",
    "visible",
    "priority",
    "sensitive",
    "live",
    "required",
    "readonly",
    "value",
    "default_value",
    "action",
    "actions",
    "error",
    "validation",
    "fallback",
    "metadata"
  ],
  "action_reference_fields": [
    "action",
    "actions",
    "clear_action",
    "copy_action",
    "primary_action",
    "reset_action",
    "secondary_actions",
    "submit_action"
  ],
  "component_reference_fields": [
    "content",
    "empty",
    "fallback",
    "illustration"
  ],
  "component_collection_fields": [
    "children",
    "items",
    "nodes",
    "regions",
    "tabs"
  ],
  "semantic_hints": {
    "content_extent": {
      "values": [
        "tiny",
        "small",
        "medium",
        "large"
      ],
      "meaning": "Expected content volume for renderer planning."
    },
    "intrinsic_aspect_ratio": {
      "meaning": "The natural proportion of media content."
    }
  },
  "families": {
    "structure": [
      "page",
      "section",
      "form",
      "list",
      "optionBar",
      "grid",
      "table",
      "tree",
      "tabs",
      "toolbar",
      "menu",
      "breadcrumb"
    ],
    "content": [
      "text",
      "valueDisplay",
      "richText",
      "codeBlock",
      "link",
      "quote",
      "image",
      "figure",
      "imageCollection",
      "icon",
      "badge",
      "status",
      "clock",
      "chart"
    ],
    "action_and_choice": [
      "button",
      "toggle",
      "checkOption",
      "imageOption",
      "detailOption",
      "checkBox",
      "radioGroup",
      "choice",
      "multiSelect",
      "comboBox",
      "slider",
      "stepper",
      "rating"
    ],
    "input": [
      "textField",
      "textArea",
      "passwordField",
      "searchField",
      "numberField",
      "dateField",
      "timeField",
      "dateTimeField",
      "dateRangeField",
      "colorField",
      "otpField"
    ],
    "feedback": [
      "progress",
      "meter",
      "activity",
      "alert",
      "toast",
      "error",
      "emptyState"
    ],
    "media_and_capability": [
      "audio",
      "audioPlayer",
      "video",
      "videoPlayer",
      "calendar",
      "mediaPicker",
      "map",
      "navigation",
      "locationPicker",
      "dialer",
      "contactPicker",
      "filePicker",
      "dialog",
      "notification",
      "graphic"
    ],
    "preview": [
      "preview"
    ]
  },
  "component_specification": "lumui-components.md",
  "components": {
    "page": {
      "purpose": "A page or step in a task.",
      "required": [
        "id",
        "title",
        "regions"
      ],
      "optional": [
        "role",
        "description",
        "primary_action",
        "secondary_actions",
        "back_behavior",
        "priority"
      ],
      "presentation": "Show one page at a time with a clear title and logical reading order. Keep navigation to other pages available."
    },
    "section": {
      "purpose": "A group of related content.",
      "required": [
        "id",
        "items"
      ],
      "optional": [
        "label",
        "description",
        "role",
        "collapsible",
        "priority"
      ],
      "presentation": "Group the items under the label when one is supplied. Keep their order and collapsed state clear."
    },
    "form": {
      "purpose": "Fields submitted together.",
      "required": [
        "id",
        "items",
        "actions"
      ],
      "optional": [
        "submit_action",
        "reset_action",
        "validation_mode",
        "dirty"
      ],
      "presentation": "Keep the fields, validation messages and form actions together. Submit only through the declared action."
    },
    "list": {
      "purpose": "An ordered collection of items.",
      "required": [
        "id",
        "items"
      ],
      "optional": [
        "selection_mode",
        "empty",
        "estimated_count",
        "pagination",
        "reorderable"
      ],
      "presentation": "Keep the declared item order. Selection, reordering, paging and the empty state MUST remain usable without relying on position alone."
    },
    "optionBar": {
      "purpose": "Commands for the current page.",
      "required": [
        "id",
        "options"
      ],
      "optional": [
        "action",
        "label",
        "description"
      ],
      "presentation": "Place page commands in a consistent and keyboard-reachable area. Overflow menus are allowed, but commands MUST remain available."
    },
    "grid": {
      "purpose": "Items arranged for visual scanning.",
      "required": [
        "id",
        "items"
      ],
      "optional": [
        "selection_mode"
      ],
      "fallback": "list",
      "presentation": "Use a grid when space allows and it helps scanning. Keep reading and focus order logical, and use a list when a grid is unsuitable."
    },
    "table": {
      "purpose": "Data organized in rows and columns.",
      "required": [
        "id",
        "columns",
        "rows"
      ],
      "optional": [
        "caption",
        "sortable",
        "filterable",
        "selection_mode",
        "pagination"
      ],
      "fallback": "list or summary",
      "presentation": "Keep the caption, headers and cell relationships clear. On narrow screens, reflow, scroll or use the stated fallback without losing those relationships."
    },
    "tree": {
      "purpose": "Hierarchical data.",
      "required": [
        "id",
        "nodes"
      ],
      "optional": [
        "expanded_node_ids",
        "selection_mode"
      ],
      "presentation": "Show an expandable hierarchy with level, selection and expanded state. Use normal keyboard tree behavior where the platform provides it."
    },
    "tabs": {
      "purpose": "A choice between related views.",
      "required": [
        "id",
        "tabs",
        "selected"
      ],
      "optional": [],
      "presentation": "Show one selected tab and its related panel. Expose selection, focus and panel relationships to assistive technology."
    },
    "toolbar": {
      "purpose": "A group of related commands.",
      "required": [
        "id",
        "actions"
      ],
      "optional": [
        "label"
      ],
      "presentation": "Keep related commands together in a labelled toolbar. Preserve their order and make every command keyboard reachable."
    },
    "menu": {
      "purpose": "Commands or local navigation.",
      "required": [
        "id",
        "items"
      ],
      "optional": [
        "trigger",
        "selection_mode"
      ],
      "presentation": "Use normal menu behavior for commands or local navigation. Follow platform rules for focus, selection and dismissal."
    },
    "breadcrumb": {
      "purpose": "The path to the current page.",
      "required": [
        "id",
        "items"
      ],
      "optional": [],
      "presentation": "Show the ordered path to the current page. Identify the current destination and avoid making it a redundant link."
    },
    "text": {
      "purpose": "Read-only text or a heading.",
      "required": [
        "id",
        "text"
      ],
      "optional": [
        "text_role",
        "selectable"
      ],
      "presentation": "Use the declared text role. A requested heading MUST be a real heading, not only larger text."
    },
    "valueDisplay": {
      "purpose": "A prominent value, time or measurement.",
      "required": [
        "id",
        "text|value"
      ],
      "optional": [
        "label",
        "description",
        "unit",
        "source",
        "live",
        "format"
      ],
      "presentation": "Give the value suitable emphasis while retaining its label, unit and source. Spoken output MUST include enough context to understand it."
    },
    "richText": {
      "purpose": "Text with limited formatting.",
      "required": [
        "id",
        "content"
      ],
      "optional": [
        "format",
        "language"
      ],
      "presentation": "Render only the supported formatting. Do not execute embedded HTML, script, style or unsafe links."
    },
    "codeBlock": {
      "purpose": "Code, logs or command output.",
      "required": [
        "id",
        "text"
      ],
      "optional": [
        "language",
        "copy_action"
      ],
      "presentation": "Preserve whitespace and identify the content as code or preformatted output. Wrap or scroll long lines, and provide the declared copy action."
    },
    "link": {
      "purpose": "A link to another resource.",
      "required": [
        "id",
        "label",
        "href"
      ],
      "optional": [
        "description",
        "rel",
        "type",
        "external",
        "download"
      ],
      "presentation": "Show a focusable link with a clear destination. It MUST work from the keyboard and follow viewer policy for external destinations."
    },
    "quote": {
      "purpose": "A quotation and optional source.",
      "required": [
        "id",
        "text"
      ],
      "optional": [
        "attribution",
        "cite",
        "language"
      ],
      "presentation": "Keep the quotation separate from surrounding text and associate its attribution and source when supplied."
    },
    "image": {
      "purpose": "One image.",
      "required": [
        "id",
        "source",
        "alt"
      ],
      "optional": [
        "caption",
        "intrinsic_aspect_ratio",
        "action",
        "sensitive",
        "decorative",
        "variants"
      ],
      "presentation": "Preserve the image's aspect ratio. Provide alt text for meaningful images, omit decorative images from accessibility output and protect sensitive images."
    },
    "figure": {
      "purpose": "Content with a caption.",
      "required": [
        "id",
        "content"
      ],
      "optional": [
        "caption",
        "credit",
        "source_link"
      ],
      "presentation": "Keep the content, caption, credit and source together when the layout changes."
    },
    "imageCollection": {
      "purpose": "A group of related images.",
      "required": [
        "id",
        "images"
      ],
      "optional": [
        "selection_mode",
        "current_index",
        "caption"
      ],
      "fallback": "sequential image or captions",
      "presentation": "Show a gallery, carousel or sequence with a stable order and clear current position. Every item and action MUST work without pointer-only gestures."
    },
    "icon": {
      "purpose": "A small symbol.",
      "required": [
        "id",
        "symbol|source",
        "meaning"
      ],
      "optional": [
        "decorative"
      ],
      "presentation": "Use the registered symbol or image. A meaningful icon needs an accessible name and MUST NOT be the only label for an action or state."
    },
    "badge": {
      "purpose": "A compact count or state.",
      "required": [
        "id",
        "label"
      ],
      "optional": [
        "value",
        "tone"
      ],
      "presentation": "Show the label and optional value as a compact annotation. Do not rely on color alone."
    },
    "status": {
      "purpose": "A current state.",
      "required": [
        "id",
        "label",
        "state"
      ],
      "optional": [
        "state_description",
        "tone",
        "live"
      ],
      "presentation": "Show the label, state and description together. Do not rely on color alone, and follow the declared announcement setting."
    },
    "chart": {
      "purpose": "A visual presentation of data.",
      "required": [
        "id",
        "chart_type",
        "data",
        "summary"
      ],
      "optional": [
        "table_fallback",
        "axes",
        "series",
        "actions"
      ],
      "fallback": "table or summary",
      "presentation": "Show the chart with its summary and data fallback. Do not rely on color, shape or position alone to distinguish data series."
    },
    "button": {
      "purpose": "A command started by the user.",
      "required": [
        "id",
        "label",
        "action"
      ],
      "optional": [
        "confirmation",
        "icon"
      ],
      "presentation": "Use a normal command control with a visible label and focus indication. Run only the declared action and apply its confirmation rule."
    },
    "toggle": {
      "purpose": "An immediate on or off setting.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [],
      "presentation": "Use a switch or equivalent control and announce its label and current state. Change the setting only through the declared action."
    },
    "checkOption": {
      "purpose": "Membership in a set.",
      "required": [
        "id",
        "label",
        "value"
      ],
      "optional": [
        "description",
        "action",
        "enabled"
      ],
      "presentation": "Use a checkbox-like control, normally with related options. Expose its label, checked state and disabled state."
    },
    "imageOption": {
      "purpose": "A selectable image, tile or swatch.",
      "required": [
        "id",
        "label",
        "value",
        "source"
      ],
      "optional": [
        "description",
        "selected",
        "action",
        "enabled"
      ],
      "presentation": "Show a selectable tile or swatch with a text label and selected state. The image or color MUST NOT be its only identifier."
    },
    "detailOption": {
      "purpose": "A selectable item with supporting details.",
      "required": [
        "id",
        "label"
      ],
      "optional": [
        "description",
        "text",
        "value",
        "selected",
        "action",
        "enabled"
      ],
      "presentation": "Show the label, supporting description and trailing value as one selectable item. It MUST remain understandable after reflow."
    },
    "checkBox": {
      "purpose": "A yes or no form value.",
      "required": [
        "id",
        "label",
        "value"
      ],
      "optional": [
        "action",
        "required"
      ],
      "presentation": "Use a labelled checkbox. Expose its checked, required and validation states."
    },
    "radioGroup": {
      "purpose": "One selection from visible options.",
      "required": [
        "id",
        "label",
        "options",
        "value"
      ],
      "optional": [
        "action"
      ],
      "presentation": "Show one labelled single-selection group. Use normal radio-button keyboard behavior where available."
    },
    "choice": {
      "purpose": "One selection from several options.",
      "required": [
        "id",
        "label",
        "options",
        "value",
        "action"
      ],
      "optional": [],
      "presentation": "Use radios, a picker or another suitable single-selection control. Keep the selected value and declared action explicit."
    },
    "multiSelect": {
      "purpose": "Several selections from a set.",
      "required": [
        "id",
        "label",
        "options",
        "values"
      ],
      "optional": [
        "min_selected",
        "max_selected",
        "action"
      ],
      "presentation": "Show a labelled multiple-selection control. Explain minimum and maximum selection limits before submission."
    },
    "comboBox": {
      "purpose": "A searchable or editable selection.",
      "required": [
        "id",
        "label",
        "options",
        "value"
      ],
      "optional": [
        "editable",
        "preview",
        "filter_mode",
        "allow_empty",
        "action"
      ],
      "presentation": "Use normal combobox behavior with an associated option list. Previewing an option MUST NOT commit it."
    },
    "slider": {
      "purpose": "A value within a numeric range.",
      "required": [
        "id",
        "label",
        "value",
        "min",
        "max",
        "action"
      ],
      "optional": [
        "step",
        "unit",
        "display_value",
        "marks"
      ],
      "fallback": "stepper or numeric input",
      "presentation": "Expose the label, value, minimum, maximum, step and unit. Keyboard changes and a stepper or numeric fallback MUST be available."
    },
    "stepper": {
      "purpose": "A number changed in steps.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "step",
        "unit"
      ],
      "presentation": "Show the value with increase and decrease commands and direct entry where possible. Disable a command at its limit."
    },
    "rating": {
      "purpose": "An ordinal rating.",
      "required": [
        "id",
        "label",
        "value",
        "max"
      ],
      "optional": [
        "min",
        "allow_half",
        "action"
      ],
      "presentation": "Show an understandable ordinal scale. Symbols may support the display, but the value and range MUST also be available as text."
    },
    "textField": {
      "purpose": "Single-line text input.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "placeholder",
        "content_type",
        "keyboard",
        "autocomplete",
        "min_length",
        "max_length",
        "pattern",
        "spellcheck",
        "autocapitalize"
      ],
      "presentation": "Use a labelled single-line field. Associate its help, placeholder and validation message correctly."
    },
    "textArea": {
      "purpose": "Multi-line text input.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "placeholder",
        "content_extent",
        "max_length",
        "spellcheck"
      ],
      "presentation": "Use a labelled multi-line field. Resize, reflow or scroll rather than clipping entered text."
    },
    "passwordField": {
      "purpose": "Secret text input.",
      "required": [
        "id",
        "label",
        "value_present",
        "action"
      ],
      "optional": [
        "placeholder",
        "min_length",
        "max_length",
        "rules",
        "allow_reveal",
        "password_manager",
        "autocomplete"
      ],
      "forbidden": [
        "value",
        "default_value"
      ],
      "presentation": "Mask entered characters by default. Keep the real value out of the surface, logs, history and previews. A temporary reveal is allowed only when requested by the component and MUST clearly announce its state."
    },
    "searchField": {
      "purpose": "A search query.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "placeholder",
        "suggestions",
        "submit_action",
        "clear_action",
        "debounce_ms",
        "result_count"
      ],
      "presentation": "Use a search field with reachable submit and clear commands and an associated suggestion list. Updates MUST NOT steal focus."
    },
    "numberField": {
      "purpose": "A numeric value.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "step",
        "unit",
        "precision",
        "format",
        "allow_negative"
      ],
      "presentation": "Use a locale-appropriate numeric field while preserving the exact numeric value. Show limits, precision, step, unit and errors."
    },
    "dateField": {
      "purpose": "A date.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "calendar",
        "format"
      ],
      "presentation": "Use a native date control or an accessible equivalent. The display may be localized, but the submitted date and limits MUST remain clear."
    },
    "timeField": {
      "purpose": "A time.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "format",
        "step_minutes"
      ],
      "presentation": "Use a native time control or an accessible equivalent. Apply the declared format and minute step."
    },
    "dateTimeField": {
      "purpose": "A date and time.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "timezone"
      ],
      "presentation": "Show date and time as one value or two clearly related controls. Show the time zone whenever it affects meaning."
    },
    "dateRangeField": {
      "purpose": "A start and end date.",
      "required": [
        "id",
        "label",
        "start",
        "end",
        "action"
      ],
      "optional": [
        "min",
        "max",
        "allow_open_end"
      ],
      "presentation": "Present start and end as one labelled range and explain errors between them. Allow an open end only when declared."
    },
    "colorField": {
      "purpose": "A color used as data.",
      "required": [
        "id",
        "label",
        "value",
        "action"
      ],
      "optional": [
        "format",
        "palette",
        "allow_custom"
      ],
      "presentation": "Provide a picker or palette with a text value or name. Color MUST NOT be the only way to identify the choice."
    },
    "otpField": {
      "purpose": "A one-time code.",
      "required": [
        "id",
        "label",
        "length",
        "action"
      ],
      "optional": [
        "value_present",
        "content_type",
        "auto_submit"
      ],
      "forbidden": [
        "value",
        "default_value"
      ],
      "presentation": "Show the expected code length and current entry position. Keep the code out of the surface, logs, history and previews, and announce automatic submission before it occurs."
    },
    "progress": {
      "purpose": "Progress of a task.",
      "required": [
        "id",
        "label",
        "value|indeterminate"
      ],
      "optional": [
        "min",
        "max",
        "unit",
        "live"
      ],
      "presentation": "Use determinate progress when a value is known and an activity indicator otherwise. Provide a text label and accessible progress state."
    },
    "meter": {
      "purpose": "A measurement within a range.",
      "required": [
        "id",
        "label",
        "value",
        "min",
        "max"
      ],
      "optional": [
        "low",
        "high",
        "optimum",
        "unit"
      ],
      "presentation": "Expose the value, range, thresholds and optimum. Color may support the ranges but MUST NOT define them alone."
    },
    "activity": {
      "purpose": "Work with no known completion value.",
      "required": [
        "id",
        "label"
      ],
      "optional": [
        "description",
        "live"
      ],
      "presentation": "Show ongoing work with a readable status label. Respect reduced-motion settings."
    },
    "alert": {
      "purpose": "An important persistent message.",
      "required": [
        "id",
        "title",
        "message"
      ],
      "optional": [
        "severity",
        "actions",
        "live"
      ],
      "presentation": "Show a persistent message with its severity and actions. Use the declared announcement urgency without repeating the message unnecessarily."
    },
    "toast": {
      "purpose": "A short non-modal message.",
      "required": [
        "id",
        "message"
      ],
      "optional": [
        "duration_ms",
        "action"
      ],
      "presentation": "Show a temporary message without moving focus. Leave it visible long enough to read and use, and do not use it as the only place for critical information."
    },
    "error": {
      "purpose": "An error that requires attention.",
      "required": [
        "id",
        "title",
        "message"
      ],
      "optional": [
        "severity",
        "actions",
        "correlation_id"
      ],
      "presentation": "Show a persistent heading, message and recovery actions. Link related invalid fields and keep the support reference available when supplied."
    },
    "emptyState": {
      "purpose": "A clear state for an empty collection.",
      "required": [
        "id",
        "title"
      ],
      "optional": [
        "message",
        "actions",
        "illustration"
      ],
      "presentation": "Show an explicit empty state instead of a blank area. Keep its title, message, illustration and actions together."
    },
    "audio": {
      "purpose": "Embedded audio.",
      "required": [
        "id",
        "label",
        "source"
      ],
      "optional": [
        "description",
        "transcript",
        "duration_ms",
        "preload",
        "download"
      ],
      "fallback": "transcript or download",
      "presentation": "Provide play, pause, seek and volume controls when supported. Keep the transcript and download fallbacks available and make every control keyboard operable."
    },
    "audioPlayer": {
      "purpose": "An audio playback session.",
      "required": [
        "id",
        "label"
      ],
      "optional": [
        "artist",
        "album",
        "artwork",
        "duration_ms",
        "position_ms",
        "state",
        "source",
        "actions"
      ],
      "presentation": "Show a recognizable player with play or pause, stop, position, duration and relevant details. Keep state and declared actions synchronized."
    },
    "video": {
      "purpose": "Embedded video.",
      "required": [
        "id",
        "title",
        "source"
      ],
      "optional": [
        "poster",
        "captions",
        "transcript",
        "audio_description",
        "intrinsic_aspect_ratio",
        "variants"
      ],
      "fallback": "poster, transcript or link",
      "presentation": "Provide video controls and expose supplied captions, transcript and audio description. Preserve aspect ratio and keep the poster, transcript or link fallback usable."
    },
    "videoPlayer": {
      "purpose": "A video playback session.",
      "required": [
        "id",
        "session_id",
        "title",
        "source|session"
      ],
      "optional": [
        "captions",
        "audio_description",
        "poster",
        "duration_ms",
        "position_ms",
        "state"
      ],
      "presentation": "Show a recognizable player with play or pause, stop, seek, elapsed and total time, captions and fullscreen where supported. Keep its state synchronized with declared actions."
    },
    "calendar": {
      "purpose": "Dates and events supplied by the application.",
      "required": [
        "id",
        "children"
      ],
      "optional": [
        "label",
        "options"
      ],
      "fallback": "date list",
      "presentation": "Use an accessible calendar grid with clear dates, selection and keyboard movement. Also provide a chronological date-list fallback."
    },
    "mediaPicker": {
      "purpose": "Media selection through the operating system.",
      "required": [
        "id",
        "label",
        "action"
      ],
      "optional": [
        "media_types",
        "selection_mode"
      ],
      "presentation": "Open the trusted operating-system media picker and explain the requested types and selection mode. Application content MUST NOT imitate system permission controls."
    },
    "map": {
      "purpose": "Geographic content or selection.",
      "required": [
        "id",
        "mode"
      ],
      "optional": [
        "center",
        "markers",
        "route",
        "current_location",
        "action"
      ],
      "fallback": "navigationSummary or location list",
      "presentation": "Show geographic content with keyboard controls and a text list or route summary. Locations, markers and selection MUST remain usable without the map."
    },
    "navigation": {
      "purpose": "Route guidance.",
      "required": [
        "id",
        "destination",
        "route_summary"
      ],
      "optional": [
        "current_step",
        "distance_remaining",
        "eta",
        "maneuvers"
      ],
      "presentation": "Show the current direction, remaining distance, estimated arrival and route context. Do not rely on the map alone."
    },
    "locationPicker": {
      "purpose": "Location selection through a trusted system control.",
      "required": [
        "id",
        "label",
        "action"
      ],
      "optional": [
        "mode",
        "requires_capabilities"
      ],
      "presentation": "Use a trusted system permission and location control. Show the selected location as text and require an explicit action before sharing it."
    },
    "dialer": {
      "purpose": "Telephone keypad and call controls.",
      "required": [
        "id",
        "mode"
      ],
      "optional": [
        "number",
        "contact",
        "call_state",
        "actions"
      ],
      "presentation": "Show a recognizable keypad or call-control view with large controls and an announced call state. Starting and ending a call require explicit actions."
    },
    "contactPicker": {
      "purpose": "Contact selection through the operating system.",
      "required": [
        "id",
        "label",
        "action"
      ],
      "optional": [],
      "presentation": "Use the trusted operating-system contact picker. Explain what will be returned and request only the fields needed by the action."
    },
    "filePicker": {
      "purpose": "File selection through the operating system.",
      "required": [
        "id",
        "label",
        "action"
      ],
      "optional": [
        "accept",
        "selection_mode",
        "intent",
        "target",
        "copy_policy"
      ],
      "presentation": "Use the trusted operating-system file picker and enforce accepted types and selection mode. Show selected file names and any copy or upload consequence before submission."
    },
    "dialog": {
      "purpose": "A modal decision.",
      "required": [
        "id",
        "title",
        "message|items",
        "actions"
      ],
      "optional": [],
      "presentation": "Show a modal view with a title, content and clearly ordered actions. Keep focus inside it and return focus to the invoking control after dismissal."
    },
    "notification": {
      "purpose": "A system notification.",
      "required": [
        "id",
        "title",
        "body"
      ],
      "optional": [
        "category",
        "actions",
        "priority",
        "expires_at",
        "sensitive"
      ],
      "presentation": "Use the trusted system notification area with accessible actions. Hide sensitive content according to user and lock-screen privacy settings."
    },
    "graphic": {
      "purpose": "Specialized graphics in a sandbox.",
      "required": [
        "id",
        "label",
        "purpose",
        "renderer",
        "source",
        "fallback"
      ],
      "optional": [
        "state_schema",
        "actions",
        "integrity",
        "capabilities"
      ],
      "presentation": "Run only a registered sandboxed renderer with its declared permissions and integrity policy. Provide an equivalent standard fallback."
    },
    "preview": {
      "purpose": "One component shown in a dedicated preview area.",
      "required": [
        "id",
        "content"
      ],
      "optional": [
        "label",
        "description"
      ],
      "fallback": "render content without the preview layout",
      "presentation": "Place the contained component in a separate preview area. Keep its normal state and actions. Do not load another surface or change the viewer context."
    },
    "clock": {
      "purpose": "A time value or live clock.",
      "required": [
        "id",
        "label"
      ],
      "optional": [
        "timezone"
      ],
      "fallback": "valueDisplay",
      "presentation": "Show the stated time, or the viewer's current time when no value is given. Keep the label, time zone and exact value available without disruptive updates."
    }
  }
}