# How to Use `instruction_steps` for Step-by-Step UI Guidance in the Exercises Dataset

> Learn to use instruction_steps from exercises-dataset for seamless UI guidance. Integrate directly with steppers, accordions & voice interfaces.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-07-28

---

**The `hasaneyldrm/exercises-dataset` repository provides `instruction_steps` as a multilingual object of string arrays, enabling direct integration with stepper components, accordions, and voice-guided interfaces without parsing long-form text.**

The `hasaneyldrm/exercises-dataset` stores structured fitness data where each exercise includes both paragraph-style descriptions and atomic steps. The `instruction_steps` field contains language-coded arrays designed specifically for progressive UI disclosure, allowing you to build guided workout interfaces by consuming pre-split instruction arrays rather than tokenizing long strings.

## Understanding the Schema Structure

The data contract for these fields is defined in **[`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json)**. According to the schema (lines 90-97), both `instructions` and `instruction_steps` are required objects that must contain entries for ten supported languages.

The repository distinguishes between two complementary instruction formats:

- **`instructions`**: An object mapping language codes to single strings containing full paragraph-style descriptions. Use this for quick display or search functionality.
- **`instruction_steps`**: An object mapping language codes to ordered arrays of strings. Each array contains atomic steps ideal for sequential UI presentation.

Supported languages include **English**, **Spanish**, **Italian**, **Turkish**, **Russian**, **Chinese**, **Hindi**, **Polish**, **Korean**, and **French**. Because the field is language-coded at the root level, you can swap the entire `instruction_steps` object when changing locales, ensuring consistent formatting across all translations without additional parsing logic.

## UI Patterns for Step-by-Step Guidance

The array structure of `instruction_steps` supports several common interface patterns for fitness applications:

- **Stepper Components** – Render each array element as a discrete step in a progress bar, displaying the current index and allowing forward/backward navigation.

- **Accordion Panels** – Present each step as a collapsible section, letting users focus on one movement cue at a time while maintaining context of the overall sequence.

- **Voice-Guided Assistants** – Consume the array sequentially, speaking each step aloud while the user performs the movement, then advancing to the next index based on voice commands or timers.

- **Highlight-on-Tap Interfaces** – Synchronize the active step index with visual elements, such as highlighting specific muscle groups on an anatomical diagram as the user scrolls through the instruction array.

## Implementation Examples

The following snippets demonstrate how to load **[`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json)** and render `instruction_steps` for different platforms.

### Python Console Renderer

This example loads the dataset and prints numbered steps for a selected language:

```python
import json

# Load the full dataset

with open("data/exercises.json", "r", encoding="utf-8") as f:
    exercises = json.load(f)

# Choose an exercise (e.g., first record) and a language

exercise = exercises[0]                 # change index as needed

lang = "en"                             # could be "es", "it", etc.

steps = exercise["instruction_steps"][lang]

print(f"\n=== {exercise['name']} – {lang.upper()} Steps ===\n")
for i, step in enumerate(steps, start=1):
    print(f"{i}. {step}")

```

### Node.js Express Endpoint

Serve step data via a lightweight API endpoint:

```javascript
const express = require("express");
const fs = require("fs");
const app = express();

const data = JSON.parse(fs.readFileSync("./data/exercises.json", "utf-8"));

app.get("/exercise/:id/:lang", (req, res) => {
  const { id, lang } = req.params;
  const ex = data.find(e => e.id === id);
  if (!ex) return res.status(404).send("Exercise not found");
  const steps = ex.instruction_steps[lang];
  if (!steps) return res.status(400).send("Unsupported language");
  res.json({ name: ex.name, language: lang, steps });
});

app.listen(3000, () => console.log("Server listening on :3000"));

```

### React Stepper Component

A TypeScript React component that manages active step state:

```tsx
import React, { useState } from "react";
import exercises from "./data/exercises.json";

interface Props {
  exerciseId: string;
  lang: keyof typeof exercises[0]["instruction_steps"];
}

export const ExerciseStepper: React.FC<Props> = ({ exerciseId, lang }) => {
  const exercise = exercises.find(e => e.id === exerciseId);
  const steps = exercise?.instruction_steps[lang] ?? [];

  const [active, setActive] = useState(0);

  return (
    <div>
      <h2>{exercise?.name} – {lang.toUpperCase()}</h2>
      <ol>
        {steps.map((step, idx) => (
          <li key={idx} style={{ fontWeight: idx === active ? "bold" : "normal" }}>
            {step}
          </li>
        ))}
      </ol>
      <button disabled={active === 0} onClick={() => setActive(active - 1)}>Prev</button>
      <button disabled={active === steps.length - 1} onClick={() => setActive(active + 1)}>Next</button>
    </div>
  );
};

```

The repository includes **[`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html)**, which demonstrates an interactive browser implementation of this pattern, and **[`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html)**, which provides developer guidance for importing the data.

## Summary

- **`instruction_steps`** stores ordered arrays of strings keyed by language code in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), while `instructions` stores single paragraphs for the same content.
- The schema in **[`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json)** mandates ten languages (English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, French) and requires both fields as objects.
- Array structures enable direct binding to UI components like steppers, accordions, and voice assistants without string parsing or manual splitting.
- Reference implementations are available in **[`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html)** (interactive demo) and **[`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html)** (integration guide).

## Frequently Asked Questions

### What is the difference between `instructions` and `instruction_steps`?

The `instructions` field contains paragraph-style descriptions suitable for quick reading or search, while `instruction_steps` provides the same content split into ordered arrays. Use `instruction_steps` when your interface needs to present one movement cue at a time or support step-by-step navigation.

### Which languages are supported in `instruction_steps`?

According to the schema defined in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), the field must contain entries for English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, and French. Each language code maps to an array of instruction strings specific to that exercise.

### How do I validate my implementation against the official schema?

Validate your consumption logic against **[`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json)**, which explicitly defines `instruction_steps` as a required object containing language-coded string arrays. You can use JSON Schema validators in Python, JavaScript, or CI pipelines to ensure your code handles the ten mandatory language keys correctly.

### Can I use `instruction_steps` for voice-guided workout applications?

Yes, the sequential array structure is ideal for voice interfaces. Each array element represents a discrete instruction that can be spoken individually, allowing the application to advance to the next step based on voice commands, timers, or user confirmation without parsing complex text strings.