schema: ai-cjm-component-contract/v1
id: faq
version: 1.0.0
status: stable
owner: AI CJM Design
purpose: Раскрывает ответы на частые вопросы без нарушения reading order.
use_when:
- Есть повторяющиеся вопросы, полезные после основного объяснения.
evidence:
- id: production-style
  url: https://aicjm.ru/edu/styles.css?v=20260811-edu-canon
  locator: .faq-list details, .faq-list summary, .faq-list details[open] summary span, .faq-list details p
  supports:
  - anatomy
  - variant:accordion
  - size:default
  - state:default
  - state:open
- id: production-dom
  url: https://aicjm.ru/edu/
  locator: .faq-list > details > summary + panel content
  supports:
  - approved-example
  - content
anatomy:
- id: list
  required: true
  role: Список вопросов.
- id: trigger
  required: true
  role: Кнопка с вопросом.
- id: indicator
  required: false
  role: Дополнительный open cue.
- id: panel
  required: true
  role: Ответ.
variants:
- id: accordion
  status: stable
  description: Один или несколько раскрытых ответов.
  evidence_refs:
  - production-style
- id: static
  status: candidate
  description: Все ответы открыты для print/reduced JS.
sizes:
- id: default
  status: stable
  description: Размер определяется содержимым и перечисленными semantic/component tokens; raw dimensions запрещены.
  evidence_refs:
  - production-style
states:
  default:
    status: stable
    basis: observed
    description: default is observed at the exact production locator in evidence_refs.
    evidence_refs:
    - production-style
  hover:
    status: candidate
    basis: normative-gap
    description: Proposed hover contract for faq; approval is required before production use.
    behavior: Apply a nonessential semantic-token cue while the pointer is over the owned interactive target.
    semantics: No ARIA change; hover never exposes hidden required content.
    token_refs:
    - surface.page
    - text.primary
    - text.secondary
    transition: Enter on pointer hover and return to default on pointer exit.
    acceptance:
    - hover behavior, semantics, token refs and transition pass the faq manual state check.
  focus-visible:
    status: candidate
    basis: normative-gap
    description: Proposed focus-visible contract for faq; approval is required before production use.
    behavior: Render focus.ring without changing layout or relying on hover.
    semantics: Keep the native element in DOM order and expose keyboard focus visibly.
    token_refs:
    - surface.page
    - text.primary
    - text.secondary
    transition: Enter for keyboard-origin focus and return to default on blur.
    acceptance:
    - focus-visible behavior, semantics, token refs and transition pass the faq manual state check.
  active:
    status: not-applicable
    basis: not-applicable
    description: active is not owned by faq.
  selected:
    status: not-applicable
    basis: not-applicable
    description: selected is not owned by faq.
  open:
    status: stable
    basis: observed
    description: open is observed at the exact production locator in evidence_refs.
    evidence_refs:
    - production-style
  disabled:
    status: not-applicable
    basis: not-applicable
    description: FAQ disclosure is either available or omitted; disabled is not owned.
  loading:
    status: not-applicable
    basis: not-applicable
    description: loading is not owned by faq.
  success:
    status: not-applicable
    basis: not-applicable
    description: success is not owned by faq.
  error:
    status: not-applicable
    basis: not-applicable
    description: error is not owned by faq.
  empty:
    status: not-applicable
    basis: not-applicable
    description: empty is not owned by faq.
responsive:
  mode: full-width-disclosure-list
  reading_order: DOM order remains authoritative in every mode.
  rules:
  - Keep every summary immediately before its panel.
  - Allow question text to wrap while the indicator remains aligned to the first line.
  - Open panels remain in normal flow and never become overlays.
accessibility:
  pattern: native-details-disclosure
  semantics:
  - Use details/summary or button with aria-expanded and an immediately associated panel.
  keyboard:
  - Enter and Space toggle the focused summary; Tab continues to links inside an open panel.
  focus:
  - Opening does not move focus; closing preserves focus on its summary.
  motion:
  - Indicator rotation uses motion.duration.state and is removed under reduced motion.
tokens:
- surface.page
- text.primary
- text.secondary
- border.default
- focus.ring
- motion.duration.state
- motion.easing.standard
content:
  required:
  - Реальный вопрос.
  - Краткий прямой ответ.
  constraints:
  - Вопрос заканчивается знаком вопроса.
  - Ответ не скрывает обязательные legal terms.
do:
- Использовать button и aria-expanded.
dont:
- Не делать heading кликабельным div.
examples:
  approved:
    status: stable
    description: Компонент faq в указанном scoped production locator.
    evidence: https://aicjm.ru/edu/
  prohibited:
    description: Не делать heading кликабельным div.
acceptance:
- id: faq-1
  criterion: Enter и Space раскрывают ответ.
  method: manual
- id: faq-2
  criterion: Скрытая panel не попадает в tab order.
  method: manual