Implement Increment Controls Question

Use this skill when creating questions where students:

• Adjust quantities using increment/decrement buttons
• See visual feedback (emoji displays, diagrams)
• Explain their reasoning about ratios, mixtures, or recipes

When to Use This Pattern

Perfect for:

• Drink mix ratio problems (🧂 salt, 🥛 water, 🍫 chocolate)
• Recipe scaling questions (🌾 flour, 🥚 eggs, 🧈 butter)
• Part-to-whole ratio explorations
• Comparing quantities/concentrations

Not suitable for:

• Questions requiring free-form numeric input → use implement-table-question
• Questions with complex graphs → use implement-graph-question
• Drag-and-drop categorization → use implement-drag-match-question

Components Required

Copy these from .claude/skills/question-types/snippets/:

Cards (Required)

• cards/standard-card.js → createStandardCard()

Cards (Optional)

• cards/explanation-card.js → createExplanationCard() - For student explanations
• cards/video-accordion.js → createVideoAccordion() - For help videos

Form Inputs (Required)

• form-inputs.js → Increment/decrement button pattern

Quick Start

1. Study the working example:

   cat courses/IM-8th-Grade/modules/Unit-3/assignments/117-Equivalent-Ratios/questions/01/attachments/chart.js
   

2. Customize the scenario data (emojis, names, colors, ranges)

3. Adjust the visualization (emoji grid or SVG)

4. Test locally with chart.html

Working Example

Reference this codebase file:

courses/IM-8th-Grade/modules/Unit-3/assignments/117-Equivalent-Ratios/questions/01/attachments/chart.js

This example includes:

• ✅ Scenario constants setup (🥤 drink, 💧 water)
• ✅ State management with default values
• ✅ Increment/decrement controls for 2 items
• ✅ Emoji grid visualization
• ✅ Explanation card
• ✅ Full message protocol
• ✅ Interactivity locking

Customization Points

1. Scenario Data

const SCENARIO = {
  item1: { emoji: "🧂", name: "Salt", color: "#FFD700" },
  item2: { emoji: "🥛", name: "Water", color: "#87CEEB" },
  minValue: 0,
  maxValue: 20,
  initialValue1: 2,
  initialValue2: 5
};

2. State Shape

function createDefaultState() {
  return {
    item1Count: SCENARIO.initialValue1,
    item2Count: SCENARIO.initialValue2,
    explanation: ""
  };
}

3. Visualization Style

• Emoji grid (simple, performant) - Most common
• SVG diagram (custom shapes) - For more complex visualizations

Common Variations

Two-Column Comparison

Display two mixtures side-by-side:

const layout = container.append("div")
  .style("display", "grid")
  .style("grid-template-columns", "1fr 1fr")
  .style("gap", "20px");

Fraction/Ratio Display

Show the relationship as a fraction:

fractionDiv.append("div").text(numerator);
fractionDiv.append("hr").style("width", "50px");
fractionDiv.append("div").text(denominator);

Range Validation

Disable buttons at limits:

.property("disabled", interactivityLocked || count <= MIN)
.style("opacity", count <= MIN ? 0.3 : 1);

Implementation Checklist

• Copied template to question directory
• Updated scenario constants (emojis, names, colors, ranges)
• Customized visualization (emoji grid or SVG)
• Added explanation card (if needed)
• Tested increment/decrement at min/max boundaries
• Verified state restoration with setInitialState
• Tested interactivity locking
• Checked message payload structure
• Tested locally with chart.html

Tips

1. Keep it simple - Emoji displays are faster and more accessible than complex SVG
2. Label clearly - Tell students what each button controls
3. Show the ratio - Display fractions, ratios, or percentages prominently
4. Add context - Use intro cards to set up the scenario
5. Validate ranges - Always check min/max before updating state

Related Skills

• implement-table-question - For ratio tables
• implement-slider-question - Alternative control style
• create-d3-question - Parent workflow skill