{
  "schema_version": "qaz.expert.avds-system-contract.v1",
  "contract_id": "qaz-expert-avds-4-system",
  "product": "QAZ.EXPERT",
  "runtime_model": "static-first-compatible-adapter",
  "provenance": {
    "canonical_site": "https://avds.digital",
    "version": "4.7.0",
    "release_id": "5411a219f3b8f03d12c23bc1543e268fe355d0ec",
    "release_built_at": "2026-08-16T22:33:52.236Z",
    "synchronized_at": "2026-08-21T10:36:42.000Z",
    "catalog": "/avds-component-catalog.json",
    "integrated_files": [
      {
        "path": "assets/avds4-adapter.css",
        "sha256": "3308926ecb6d1c8ffadada14d1bfcdb6f8ea95463f0c94ff61807e6b1e5b1596"
      },
      {
        "path": "assets/avds-runtime.js",
        "sha256": "5cc74d39e0ca808145f6a6e2c5e21b9d3cefa29d70f1ea7fd58e9f5d2f629367"
      },
      {
        "path": "avds-consumer.json",
        "sha256": "b804081fd516a3e4927b6037b18f92758d269af60d0dcc0b95b6c21ce3d1d490"
      },
      {
        "path": "avds-static-adapter.json",
        "sha256": "5b12618e0b7cc714b6d8a0fdbf2523ece49c10e57eb8c4ad708660b903789d54"
      },
      {
        "path": "avds-component-catalog.json",
        "sha256": "d83b13b442b675ac2e6e8b7fef60c8716de1671d20fcd2631fdb490eae31e223"
      }
    ],
    "local_deviations": [
      {
        "id": "static-first",
        "decision": "AV DS React runtime is not shipped; compatible HTML/CSS contracts are used",
        "reason": "preserve static publishing, data provenance and deterministic fallbacks"
      },
      {
        "id": "fonts-system-fallback",
        "decision": "font files are not vendored; approved stacks fall back to system fonts",
        "reason": "no reviewed local font binaries or licenses are currently published"
      },
      {
        "id": "icons-inline-subset",
        "decision": "only a product-owned inline SVG subset is shipped",
        "reason": "the complete named AV DS icon package and license ledger are not integrated"
      },
      {
        "id": "institutional-default",
        "decision": "institutional remains the default public theme",
        "reason": "all six theme contracts are shipped, but QAZ.EXPERT does not persist a reader-selected theme preference"
      },
      {
        "id": "content-driven-density",
        "decision": "density follows the page task instead of a user preference",
        "reason": "data tables use compact density while editorial and evidence surfaces keep readable spacing"
      },
      {
        "id": "token-baseline-4-6",
        "decision": "the static adapter retains the reviewed 4.6 token baseline while catalog semantics track 4.7",
        "reason": "the upstream 4.7 release exposes catalog and artifact provenance but no reviewed token-diff; this boundary is explicit and must be removed after token review"
      },
      {
        "id": "qazgeo-boundary",
        "decision": "QazGeo owns map data and interaction behavior",
        "reason": "AV DS owns visual presentation, not geospatial provenance or routing"
      }
    ]
  },
  "tokens": {
    "source": "assets/avds4-adapter.css",
    "groups": {
      "colors": [
        "blue",
        "slate",
        "amber",
        "green",
        "red",
        "orange",
        "cyan",
        "violet",
        "teal",
        "semantic background/foreground/surface/card/muted/border/primary"
      ],
      "typography": [
        "body",
        "heading",
        "code"
      ],
      "spacing_px": [
        0,
        4,
        8,
        12,
        16,
        20,
        24,
        32,
        40,
        48
      ],
      "radii_px": [
        4,
        8,
        12,
        16,
        999
      ],
      "shadows": [
        "sm",
        "lg",
        "product aliases xs/md"
      ],
      "element_sizes": {
        "header_min_height_px": 64,
        "control_min_height_px": 32,
        "map_min_height_px": 320
      },
      "motion_ms": [
        80,
        120,
        180,
        280
      ],
      "easing": [
        "standard",
        "emphasized"
      ],
      "z_index": {
        "dropdown": 1000,
        "modal": 1300,
        "tooltip": 1400,
        "toast": 1500
      },
      "breakpoints_px": [
        320,
        390,
        768,
        820,
        1024,
        1440,
        1920
      ],
      "container_and_grid": {
        "line_length_ch": "60-75",
        "minimum_track_px": 220,
        "maximum_public_container_px": 1440
      }
    }
  },
  "fonts_and_icons": {
    "fonts": [
      {
        "role": "interface/data",
        "family": "Inter, IBM Plex Sans, system-ui, sans-serif",
        "weights": [
          400,
          600,
          700
        ],
        "local_files": [],
        "license": "not bundled; system/network availability only"
      },
      {
        "role": "editorial display",
        "family": "IBM Plex Serif, Georgia, serif",
        "weights": [
          600,
          700
        ],
        "local_files": [],
        "license": "not bundled; system/network availability only"
      },
      {
        "role": "code/evidence",
        "family": "IBM Plex Mono, ui-monospace, monospace",
        "weights": [
          400,
          600
        ],
        "local_files": [],
        "license": "not bundled; system/network availability only"
      }
    ],
    "icons": {
      "implementation": "inline SVG product subset in assets/workspace.js plus favicon/app icons",
      "default_box_px": 24,
      "stroke_width": 2,
      "available_names": [
        "home",
        "data",
        "map",
        "pulse",
        "explore",
        "state",
        "services",
        "media",
        "report",
        "entities",
        "timemachine",
        "datasets",
        "api",
        "sources",
        "search",
        "more",
        "close"
      ],
      "local_files": [
        "assets/favicon.svg",
        "assets/app-icon-180.png",
        "assets/app-icon-192.png",
        "assets/app-icon-512.png"
      ],
      "license": "product-owned inline paths; full AV DS icon license ledger not integrated"
    }
  },
  "themes": [
    {
      "id": "institutional",
      "status": "verified",
      "selector": "html[data-av-theme=\"institutional\"]"
    },
    {
      "id": "editorial",
      "status": "verified",
      "selector": "html[data-av-theme=\"editorial\"]"
    },
    {
      "id": "data-analytics",
      "status": "verified",
      "selector": "html[data-av-theme=\"data-analytics\"]"
    },
    {
      "id": "map",
      "status": "verified",
      "selector": "html[data-av-theme=\"map\"]"
    },
    {
      "id": "dark",
      "status": "verified",
      "selector": "html[data-av-theme=\"dark\"]"
    },
    {
      "id": "print",
      "status": "verified",
      "selector": "@media print in assets/avds4-adapter.css"
    }
  ],
  "component_contract": {
    "catalog_total": 118,
    "adopted": 104,
    "adoption_registry": "/avds-static-adapter.json#/catalog_coverage/components",
    "required_fields": [
      "canonical id",
      "HTML/CSS surface",
      "route scope",
      "variant/state contract",
      "keyboard behavior when interactive",
      "nesting constraints"
    ],
    "universal_rules": {
      "html": "semantic native element first; one stable root class and named child classes",
      "class_api": "av-* is the canonical primitive namespace; avds-* is a compatibility/composition namespace; is-* is state only",
      "attributes": [
        "data-* only for behavior/identity",
        "aria-* mirrors interactive state",
        "disabled uses the native attribute when available"
      ],
      "sizes": "compact, default and rich density must use token-backed spacing and minimum target sizes",
      "variants": [
        "outlined",
        "elevated",
        "compact",
        "rich",
        "neutral",
        "success",
        "warning",
        "danger",
        "info"
      ],
      "states": [
        "default",
        "hover",
        "focus-visible",
        "active",
        "selected",
        "disabled",
        "loading",
        "empty",
        "error",
        "degraded",
        "stale"
      ],
      "keyboard": "native controls preserve Enter/Space; roving or composite widgets document arrows, Home/End and Escape",
      "nesting": "interactive elements may not be nested; headings preserve hierarchy; cards do not hide tables or landmarks"
    },
    "profiles": [
      {
        "id": "card",
        "root": ".av-card",
        "children": [
          ".av-card__eyebrow",
          ".av-card__title",
          ".av-card__body",
          ".av-card__footer"
        ],
        "variants": [
          "compact",
          "rich",
          "elevated",
          "outlined"
        ],
        "keyboard": "only contained native actions receive focus"
      },
      {
        "id": "badge-chip",
        "root": ".av-badge or .av-chip",
        "children": [],
        "variants": [
          "neutral",
          "success",
          "warning",
          "danger",
          "info",
          "selected",
          "muted"
        ],
        "keyboard": "static badge is not focusable; filter chip uses button and aria-pressed"
      },
      {
        "id": "table",
        "root": ".av-table-wrapper",
        "children": [
          "table",
          "thead",
          "tbody",
          "th",
          "td"
        ],
        "variants": [
          "scrollable",
          "compact"
        ],
        "keyboard": "scroll container is reachable when content overflows"
      },
      {
        "id": "tabs",
        "root": ".avds-tabs",
        "children": [
          "[role=tablist]",
          "[role=tab]",
          "[role=tabpanel]"
        ],
        "variants": [
          "default",
          "compact"
        ],
        "keyboard": "ArrowLeft/ArrowRight, Home/End and focus-visible are required"
      },
      {
        "id": "select",
        "root": ".av-select",
        "children": [
          "label",
          "select"
        ],
        "variants": [
          "default",
          "compact",
          "disabled"
        ],
        "keyboard": "native select behavior is preserved"
      },
      {
        "id": "map-list",
        "root": ".av-geo-publication",
        "children": [
          ".av-geo-publication__map",
          ".av-geo-publication__summary",
          ".av-geo-signal-strip"
        ],
        "variants": [
          "desktop-split",
          "mobile-stacked",
          "loading",
          "error",
          "stale"
        ],
        "keyboard": "regions are buttons; Tab selects focus target and Enter/Space activates"
      },
      {
        "id": "provenance",
        "root": ".avds-provenance-card or .av-provenance-strip",
        "children": [
          "source",
          "period",
          "unit",
          "status",
          "canonical link"
        ],
        "variants": [
          "inline",
          "card",
          "disclosure"
        ],
        "keyboard": "disclosure uses button, aria-expanded and aria-controls"
      },
      {
        "id": "button",
        "root": "button.av-button",
        "children": [
          "optional inline icon",
          "label"
        ],
        "variants": [
          "default",
          "compact",
          "icon",
          "disabled"
        ],
        "keyboard": "native button preserves Enter and Space; no nested actions"
      },
      {
        "id": "form-controls",
        "root": ".av-input, .av-select, .av-checkbox",
        "children": [
          "associated label",
          "optional help or error text"
        ],
        "variants": [
          "default",
          "disabled",
          "invalid"
        ],
        "keyboard": "native form semantics and visible focus are preserved"
      },
      {
        "id": "alert",
        "root": ".av-alert",
        "children": [
          "short state title",
          "actionable follow-up"
        ],
        "variants": [
          "empty",
          "error",
          "degraded",
          "stale"
        ],
        "keyboard": "static status is not focusable; any recovery action remains a native control"
      },
      {
        "id": "chart",
        "root": ".av-bar-chart or .av-trend-sparkline",
        "children": [
          "label",
          "value",
          "unit",
          "period",
          "source/table alternative"
        ],
        "variants": [
          "bar",
          "trend",
          "loading",
          "empty"
        ],
        "keyboard": "interactive chart marks expose a button or equivalent tabular alternative"
      },
      {
        "id": "kazakhstan-echart",
        "root": ".av-kazakhstan-echart",
        "children": [
          "figcaption",
          "svg",
          "axis label",
          "source",
          "table alternative"
        ],
        "variants": [
          "bar",
          "compact",
          "scrollable"
        ],
        "keyboard": "the chart is summarized by an accessible figure and the scrollable table alternative is keyboard reachable"
      },
      {
        "id": "collector-run",
        "root": ".av-collector-run",
        "children": [
          "status indicator",
          "source link",
          "observation date",
          "status badge"
        ],
        "variants": [
          "success",
          "degraded",
          "fallback"
        ],
        "keyboard": "the source link uses native keyboard behavior; the status indicator is decorative"
      },
      {
        "id": "incident-response-surface",
        "root": ".av-incident-response-surface",
        "children": [
          "status summary",
          "reason",
          "next actions"
        ],
        "variants": [
          "success",
          "warning",
          "degraded"
        ],
        "keyboard": "next actions remain native links and the surface itself is not focusable"
      },
      {
        "id": "qazlake-ops-list",
        "root": ".av-qazlake-ops-list",
        "children": [
          "summary",
          ".av-kazakhstan-echart",
          ".av-collector-run",
          ".av-incident-response-surface"
        ],
        "variants": [
          "collapsed",
          "expanded",
          "mobile-stacked"
        ],
        "keyboard": "native details/summary preserves Enter and Space; nested actions are outside the summary"
      }
    ],
    "verification": "canonical ID, selector existence, public HTML/JS use, route declaration and inherited profile rules must all pass"
  },
  "states": [
    "hover",
    "focus",
    "active",
    "selected",
    "disabled",
    "loading",
    "skeleton",
    "empty",
    "error",
    "degraded",
    "success",
    "offline",
    "stale-data"
  ],
  "compositions": [
    {
      "id": "header-footer",
      "surfaces": [
        ".site-header",
        ".site-footer"
      ]
    },
    {
      "id": "object-passport",
      "surfaces": [
        ".institution-profile",
        ".av-provenance-strip"
      ]
    },
    {
      "id": "catalog",
      "surfaces": [
        ".collection-directory-toolbar",
        ".directory-entry-card"
      ]
    },
    {
      "id": "analytics-panel",
      "surfaces": [
        ".workbench-module",
        ".av-data-quality-scorecard"
      ]
    },
    {
      "id": "table",
      "surfaces": [
        ".av-table-wrapper",
        ".table-scroll"
      ]
    },
    {
      "id": "filters",
      "surfaces": [
        ".filter-chip-row",
        ".avds-filter-toolbar"
      ]
    },
    {
      "id": "map-with-list",
      "surfaces": [
        ".av-geo-publication",
        ".av-geo-signal-strip"
      ]
    },
    {
      "id": "chart-with-source",
      "surfaces": [
        ".regional-chart-card",
        ".chart-source"
      ]
    },
    {
      "id": "publication",
      "surfaces": [
        ".media-news-card",
        ".avds-document-card"
      ]
    },
    {
      "id": "evidence-card",
      "surfaces": [
        ".avds-provenance-card",
        ".data-provenance-details"
      ]
    },
    {
      "id": "methodology-provenance",
      "surfaces": [
        ".methodology-page",
        ".provenance-inline"
      ]
    }
  ],
  "responsive_model": {
    "viewports_px": [
      320,
      390,
      768,
      820,
      1024,
      1440,
      1920
    ],
    "ultra_wide": ">1920",
    "recomposition_order": [
      "primary task",
      "summary/evidence",
      "controls",
      "secondary rail",
      "supplementary panels"
    ],
    "density": "compact controls and tables use .av-card--compact and token-backed 32–40px controls; editorial reading surfaces remain relaxed",
    "rails": "collapse below 960px; supplementary panels move below primary content",
    "line_length": "60-75ch for prose; data labels may use shorter fixed tracks",
    "whitespace": "empty grid tracks and fixed-height spacers are prohibited"
  },
  "data_visualization": {
    "palette": "semantic AV DS colors; sequential map scales remain QazGeo-owned",
    "scales": "zero-aware bars unless the metric contract explicitly declares another baseline",
    "legends": "visible label, selected state and source/period context",
    "axes": "unit and period are required; the public QazLake operations chart renders a zero baseline, five labeled numeric ticks, an explicit unit label and per-stream observation dates",
    "units_precision": "registry-owned display unit and precision; no mixed-period comparison without disclosure",
    "missing_values": "missing is never rendered as zero",
    "period_comparison": "period, unit and geography must be compatible",
    "maps": "keyboard-selectable regions, explicit legend and QazGeo provenance",
    "table_alternative": "downloadable or visible tabular data must accompany non-trivial charts"
  },
  "accessibility": {
    "minimum": [
      "WCAG contrast",
      "visible focus",
      "logical tab order",
      "semantic landmarks",
      "ARIA names/states",
      "screen-reader status announcements",
      "reduced motion",
      "zoom/reflow",
      "keyboard control of complex elements"
    ],
    "automated_gates": [
      "scripts/check-html-a11y.mjs",
      "scripts/check-visual.mjs",
      "scripts/check-interactions.mjs"
    ]
  },
  "content_standard": {
    "languages": [
      "ru-KZ",
      "kk-KZ",
      "en"
    ],
    "rules": [
      "registry terminology",
      "task-oriented action labels",
      "locale-aware numbers and dates",
      "units beside values",
      "source language preserved",
      "safe wrapping",
      "actionable error and empty states"
    ]
  },
  "quality_control": {
    "reference_screenshots": "visual gate screenshot matrix",
    "visual_regression": "46 route contracts and 28 screenshot smokes",
    "route_ledger": "docs/uiux-route-state-matrix.json",
    "state_tests": "22 interaction scenarios plus explicit loading/skeleton, empty/error/stale and offline checks",
    "accessibility": "HTML a11y, runtime status-announcement and responsive browser audits",
    "untracked_local_styles": "forbidden by contract/hash/repository hygiene gates",
    "update_procedure": [
      "sync official release and catalog",
      "review source revision and licenses",
      "update integrated file hashes and deviations",
      "ratchet category controls",
      "run npm test and visual/interaction gates",
      "publish manifest",
      "verify public parity"
    ]
  },
  "measurement": {
    "status_values": {
      "verified": 1,
      "partial": 0.5,
      "missing": 0
    },
    "categories": [
      {
        "id": "routes",
        "label": "routes",
        "weight": 10,
        "metric": "route-contract"
      },
      {
        "id": "tokens-themes",
        "label": "tokens and themes",
        "weight": 15,
        "controls": [
          "colors:verified",
          "typography:verified",
          "spacing:verified",
          "radii:verified",
          "shadows:verified",
          "element-sizes:verified",
          "motion:verified",
          "z-index:verified",
          "breakpoints:verified",
          "containers-grid:verified",
          "institutional:verified",
          "editorial:verified",
          "data-analytics:verified",
          "map:verified",
          "dark:verified",
          "print:verified"
        ]
      },
      {
        "id": "components",
        "label": "components",
        "weight": 20,
        "metric": "component-catalog"
      },
      {
        "id": "compositions",
        "label": "compositions",
        "weight": 10,
        "controls": [
          "header-footer:verified",
          "object-passport:verified",
          "catalog:verified",
          "analytics-panel:verified",
          "table:verified",
          "filters:verified",
          "map-with-list:verified",
          "chart-with-source:verified",
          "publication:verified",
          "evidence-card:verified",
          "methodology-provenance:verified"
        ]
      },
      {
        "id": "states",
        "label": "states",
        "weight": 8,
        "controls": [
          "hover:verified",
          "focus:verified",
          "active:verified",
          "selected:verified",
          "disabled:verified",
          "loading:verified",
          "skeleton:verified",
          "empty:verified",
          "error:verified",
          "degraded:verified",
          "success:verified",
          "offline:verified",
          "stale-data:verified"
        ]
      },
      {
        "id": "adaptivity",
        "label": "adaptivity",
        "weight": 10,
        "controls": [
          "320:verified",
          "390:verified",
          "768:verified",
          "820:verified",
          "1024:verified",
          "1440:verified",
          "1920:verified",
          "ultra-wide:verified",
          "recomposition:verified",
          "density:verified",
          "rails:verified",
          "line-length:verified",
          "whitespace:verified"
        ]
      },
      {
        "id": "accessibility",
        "label": "accessibility",
        "weight": 10,
        "controls": [
          "contrast:verified",
          "focus:verified",
          "tab-order:verified",
          "landmarks:verified",
          "aria:verified",
          "screen-reader:verified",
          "reduced-motion:verified",
          "zoom:verified",
          "complex-keyboard:verified"
        ]
      },
      {
        "id": "localization",
        "label": "localization",
        "weight": 7,
        "controls": [
          "ru:verified",
          "kk:verified",
          "en:verified",
          "terminology:verified",
          "actions:verified",
          "numbers-dates-units:verified",
          "wrapping:verified",
          "errors-empty:verified"
        ]
      },
      {
        "id": "data-visualization",
        "label": "data visualization",
        "weight": 5,
        "controls": [
          "palette:verified",
          "scales:verified",
          "legends:verified",
          "axes:verified",
          "units:verified",
          "precision:verified",
          "missing-values:verified",
          "period-comparison:verified",
          "maps:verified",
          "table-alternatives:verified"
        ]
      },
      {
        "id": "version-discipline",
        "label": "version discipline",
        "weight": 5,
        "controls": [
          "exact-version:verified",
          "sync-date:verified",
          "release-id:verified",
          "file-hashes:verified",
          "local-deviations:verified",
          "update-procedure:verified",
          "public-parity:verified"
        ]
      }
    ]
  }
}