manifest.json

{
  "schemaVersion": 1,
  "component": "education-quiz",
  "template": "quiz_template_skeleton",
  "files": {
    "html": "education/quiz_template_skeleton.html",
    "cssBase": "education/quiz.css",
    "cssTemplate": "education/quiz_template_skeleton.css",
    "jsTemplate": "education/quiz_template_skeleton.js"
  },
  "contentAuthoring": {
    "purpose": {
      "primary": "Help developers build durable engineering skill in an AI-first era.",
      "notGoals": [
        "Certification / exam prep",
        "Rote memorization of commands, flags, or options"
      ],
      "intent": "When developers use AI to implement or review a related theme, this quiz organizes the prerequisite concepts, keywords, frameworks, and pitfalls they should already understand."
    },
    "inputs": {
      "theme": "Given by the quiz author (required)",
      "language": {
        "primary": "en",
        "supported": [
          "en",
          "ja"
        ],
        "japaneseStyle": "Japanese content should NOT be a literal translation. Translate the intent, then rewrite into natural Japanese.",
        "japanesePunctuation": "For Japanese text, use '.' and ',' (period/comma). Do NOT use Japanese punctuation '。' or '、'.",
        "note": "If a quiz is provided in two pages (EN/JA), language switching may be implemented as a page redirect with a persistent localStorage preference."
      },
      "difficulty": {
        "levels": {
          "L0": "Beginner (初心者)",
          "L1": "Novice/Intro (初級者)",
          "L2": "Intermediate (中級)",
          "L3": "Advanced (上級)",
          "L4": "Guru/Expert (グルとして)"
        },
        "defaultFocus": "If not specified, focus primarily on L0–L2."
      },
      "questionCount": {
        "default": 10,
        "rules": {
          "newReferenceUrlOrSmallTheme": 10,
          "largeTheme": 25
        },
        "note": "Default is 10. If adding a new reference URL or a new small theme, generate 10 questions. For a large theme, generate 25 questions."
      },
      "referenceUrls": [
        "Given by the quiz author (optional; use when provided)"
      ]
    },
    "questionPhilosophy": {
      "aiEraFocus": "Prefer questions that build framework-level skill: writing/reviewing specs, handling exceptions/trade-offs, making requirements testable, and collaborating with AI (e.g., asking for a spec rewrite or review).",
      "policy": [
        "Do not primarily test memorization of commands/flags/options; AI can look these up.",
        "Instead test: concepts, design philosophy, thinking frameworks, key terms, metric meanings, common misconceptions, and typical errors that appear in real development.",
        "Assume the explanation is part of the curriculum: optimize for learning-by-reading."
      ],
      "avoid": [
        "Pure memorization of definitions without application",
        "Questions whose correctness depends mainly on subjective preference",
        "Normative language questions that omit definitions and leave key terms ambiguous"
      ]
    },
    "requirements": [
      "Follow the given theme and reference URLs when writing answers/explanations; do not introduce contradictions.",
      "Include the key words/terms that appear in the question statement inside the explanation text (not only in the prompt).",
      "Include a short 'Context (why chosen)' / '問題を出した背景' in the explanation.",
      "Include a short real-world scenario: when/where the developer would encounter this and what decision it supports.",
      "For multiple-choice and multi-select questions, provide explanations for every option word/phrase: define what it means and why it is correct/incorrect.",
      "For Japanese text, use '.' and ',' instead of Japanese punctuation '。' and '、'.",
      "Choices must not end with sentence-final punctuation (., 。).",
      "If there are related topics that help learning, give concrete examples (briefly) to connect the concept to adjacent topics.",
      "Important keywords that the learner should remember must be emphasized with **bold**.",
      "Explanations must not be one-line summaries; they should be detailed enough to follow and learn from."
    ],
    "explanationBlock": {
      "selector": ".explain",
      "expectedStructure": [
        "Definition/meaning of the question terms",
        "Context (why chosen) / 問題を出した背景",
        "Real-world usage: when/where you encounter this",
        "Why the correct answer is correct",
        "Why each distractor/incorrect option is incorrect",
        "Terms / word explanations (mini glossary when needed)",
        "Related topics/examples (when relevant)"
      ],
      "readability": {
        "formatting": "Use line breaks and (when helpful) bullet lists to keep explanations scannable.",
        "emphasis": "Make definitions explicit before reasoning (definition-first).",
        "depth": "Prefer learning-first explanations: explain each option carefully (not a single line) so the reader can follow the reasoning.",
        "markdown": "Author explanations with Markdown-like syntax that the template can safely normalize (e.g., **bold**, `inline code`). Avoid unsupported constructs that would break HTML."
      }
    },
    "visualAids": {
      "scope": "Applies to diagrams embedded in education/ quiz questions and explanations.",
      "optionalUse": "Add diagrams only when they materially improve understanding of flows, responsibility boundaries, protocol layers, request/response sequences, or dependency structure.",
      "preferredFormat": "Inline SVG with box-and-arrow diagrams.",
      "boxLayout": {
        "textAlignment": "Text inside each box must be centered horizontally and vertically.",
        "padding": "Boxes should include comfortable inner padding so text does not touch the border.",
        "wrapping": "If a label is long, insert explicit line breaks at natural phrase boundaries so the text stays inside the box.",
        "sizing": "Choose box width/height after wrapping so the full label fits with extra room and never overflows."
      },
      "rules": [
        "Do not add decorative graphs. Use diagrams only when the question becomes easier to reason about visually.",
        "Do not force diagrams into every quiz. Adopt a diagram only when it is genuinely effective for that specific question.",
        "Use boxes and arrows as the default visual language unless the theme clearly needs another structure.",
        "Text inside each box must be centered both horizontally and vertically.",
        "When a box label is long, wrap it into multiple short lines rather than shrinking the font until it becomes hard to read.",
        "Size each box to fit its wrapped text with visible padding on all sides.",
        "Arrow thickness and arrowhead size must stay proportionate to the overall figure so they remain visible without dominating the diagram.",
        "Arrow length and marker size must remain natural relative to the distance between boxes; avoid oversized arrows that dominate the figure.",
        "Leave enough spacing between boxes, arrows, and labels so that text never overlaps arrows or other text.",
        "Keep labels short. If a longer explanation is needed, put it in a figcaption or the explanation block rather than inside the arrow path.",
        "Provide an accessible figcaption or aria-label that explains what the diagram shows.",
        "Make diagrams responsive so they scale cleanly on mobile without text collisions."
      ]
    }
  },
  "ui": {
    "toggles": [
      {
        "id": "toggleExplainOnAnswer",
        "label": "回答直後に解説を表示 / Show explanation immediately",
        "default": true,
        "storage": {
          "type": "localStorage",
          "key": "quizExplainOnAnswer"
        },
        "behavior": "When enabled, show the .explain block for questions that have been answered."
      },
      {
        "id": "toggleShowAllAnswers",
        "label": "すべての回答を表示 / Show all answers",
        "default": false,
        "storage": {
          "type": "localStorage",
          "key": "quizShowAllAnswers"
        },
        "behavior": "When enabled, show explanations for all questions and render/update the results table (answers + score) in the results panel."
      }
    ],
    "resultsPanel": {
      "defaultId": "results-bottom",
      "buttonId": "bottomShowAnswers",
      "buttonBehavior": "Clicking the button turns on 'Show all answers' and renders the results panel."
    }
  },
  "events": {
    "answerChange": "Recomputes live score; updates reveal state; refreshes results panel if 'Show all answers' is enabled."
  }
}