Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ElthonJohan/comunitea/llms.txt

Use this file to discover all available pages before exploring further.

ComuniTEA’s exercise system gives children a structured, gamified path for practicing AAC communication skills beyond free-form use of the tablero. Exercises are organized into two groups — G2 (moderate support needs) and G3 (high support needs) — each containing five levels of progressively increasing complexity. Every level is composed of discrete exercises with clear visual instructions, immediate audio feedback, and a star reward based on accuracy. Progress is persisted across sessions so children can always pick up exactly where they left off.

​
Exercise groups overview

Group 2 (G2)

Designed for children with moderate TEA support needs who have emerging communicative intent. G2 exercises focus on emotion recognition, requesting help, category navigation, and turn-based response. The visual theme uses a soft blue background (#F0F4FF).

Group 3 (G3)

Designed for children with high support needs who are beginning to use single pictograms functionally. G3 exercises focus on basic symbol recognition, discrimination between two pictograms, expressing needs, and building a first two-pictogram phrase. The visual theme uses a warm linen background (#F8F4E3).

​
Group 2 levels (G2)

​
Level navigation path

1

Level 1 — Reconocer y Pedir 👋

Three exercises presenting 2–3 pictogram options. The child is given a spoken instruction (e.g., “¿Qué quieres? Toca lo que quieres”, “Toca el auto”) and must tap the correct item. Exercises introduce concrete vocabulary: food and toys. A hint (pista) is spoken after an incorrect attempt.Exercises:
  • E1: Two options (Manzana / Jugo) — free choice request
  • E2: Three options (Galleta / Auto / Oso) — identify the auto
  • E3: Three options (Manzana / Plátano / Naranja) — identify the naranja
2

Level 2 — Mis emociones 💜

Three sub-exercises accessible via tab navigation, each targeting a different emotion recognition skill. The level intro voice says: “Nivel dos. Mis emociones. Mira las escenas y dime cómo se siente.”
Sub-exerciseNameDescription
E1ReconocerTap the pictogram matching the emotion shown in a scene
E2UnirMatch emotion pictograms to their corresponding faces
E3IdentificarIdentify which emotion the child in the scene is feeling
3

Level 3 — Pedir ayuda 🙋

Three sub-exercises teaching the child to communicate help requests. The level intro says: “Nivel tres. Pedir ayuda. Aprende qué necesitas y a quién se lo dices.”
Sub-exerciseNameDescription
E1¿Qué necesito?Identify what object or resource is needed from the scene
E2¿Cómo lo digo?Select the correct pictogram phrase to express the need
E3¿A quién le pido?Tap the correct person (Mamá / Profe / Nico) to ask for help
4

Level 4 — Las Categorías 🗂️

Two-phase navigation exercises. In Phase A, the child taps the correct category tile for a given target. In Phase B, the full pictogram grid for that category is shown and the child picks the specific item. A third exercise uses the full live tablero in free-play mode.
  • E1: Find jugo — navigate Comida → Jugo (voice: “¿Dónde está el jugo? Toca la categoría.”)
  • E2: Find feliz — navigate Emociones → Feliz (voice: “Quieres decir que estás feliz. ¿En qué categoría está?”)
  • E3: Open-ended: “Ahora tú decides. Dime algo usando la app.”
5

Level 5 — Turno y Respuesta 💬

Conversational-turn exercises where a teacher character asks a question and the child responds with a pictogram. Responses trigger personalized voice feedback.
  • E1: “¿Qué quieres merendar?” → child picks from 5 food pictograms (Manzana, Galleta, Jugo, Pan, Queso)
  • E2: “¿Cómo estás hoy?” → child picks from 4 emotion pictograms; app responds warmly
  • E3: “¿Qué quieres hacer ahora?” → open activity selection; final voice: “¡Muy bien! Ya sabes usar ComuniTEA para hablar con los demás.”

​
Group 3 levels (G3)

G3 levels are designed to build communication from the ground up, following the PECS Phase I–V progression. Each level name has an evocative Spanish title to give the child a sense of narrative progression.
LevelNameEmojiFocus
1El Despertar☀️Tap a single large pictogram shown on screen
2La Elección🔀Tap the named pictogram from two side-by-side options
3Mis Necesidades💭Choose the correct pictogram from a two-option discrimination
4Pedir Ayuda🤝Tap the contextually correct need-expression pictogram (Me duele / Quiero agua / Ayuda)
5Mi Primera Frase✨Build a two-pictogram phrase: tap “Quiero” + the target object

​
G3 Level 5 — My First Sentence

Level 5 is the culminating exercise: the child uses FormadorFrase (sentence builder) to tap two pictograms in sequence — the Quiero petición card and then the target object. The three exercises use Manzana, Galleta, and Juguete. Successfully completing this level unlocks the full tablero experience. 
export const G3_NIVEL_5: G3L5[] = [
  { emoji: '🍎', label: 'Manzana', instruccion: 'Dime: yo quiero manzana. Toca los dos.', palabraFrase: 'manzana' },
  { emoji: '🍪', label: 'Galleta', instruccion: 'Pide la galleta. Toca los dibujos.',       palabraFrase: 'galleta' },
  { emoji: '🧸', label: 'Juguete', instruccion: 'Pide el juguete.',                          palabraFrase: 'juguete' },
];

​
Star reward system

Stars are awarded at the end of each exercise based on the number of incorrect attempts made. G2 and G3 each define their own star helper: 
// G2 — starsFromFailsG2 (features/ejercicios/data/grupo2.ts)
export function starsFromFailsG2(totalFails: number): 1 | 2 | 3 {
  if (totalFails === 0) return 3;
  if (totalFails <= 2) return 2;
  return 1;
}

// G3 — starsFromFails (features/ejercicios/data/grupo3.ts)
export function starsFromFails(totalFails: number): 1 | 2 | 3 {
  if (totalFails === 0) return 3;
  if (totalFails <= 2) return 2;
  return 1;
}
Both functions use the same thresholds:
ErrorsStars awarded
0⭐⭐⭐ (3 stars)
1–2⭐⭐ (2 stars)
3+⭐ (1 star)
Stars are stored per-exercise key (e.g. "2-E1", "3-1") in Zustand’s persisted stores and displayed in the level map as badge indicators.

​
Progress persistence

Both groups use Zustand stores with AsyncStorage persistence: 
// G2 — useEjerciciosG2()
export function useEjerciciosG2() {
  return useG2ProgressStore(
    useShallow((st) => ({
      completados: st.completados,
      fallosPorEjercicio: st.fallosPorEjercicio,
      estrellasPorNivel: st.estrellasPorNivel,
      emocionesRegistradas: st.emocionesRegistradas,
      fallosPorSubEjercicio: st.fallosPorSubEjercicio,
      estrellasPorEjercicio: st.estrellasPorEjercicio,
      ayudasRegistradas: st.ayudasRegistradas,
      hydrated: st.hydrated,
      isExerciseDone: st.isExerciseDone,
      isLevelComplete: st.isLevelComplete,
      isLevelUnlocked: st.isLevelUnlocked,
      nivelBadgeState: st.nivelBadgeState,
      firstIncompleteIndex: st.firstIncompleteIndex,
      registerFail: st.registerFail,
      registerSubFail: st.registerSubFail,
      completeSubExercise: st.completeSubExercise,
      completeExercise: st.completeExercise,
      registerEmocion: st.registerEmocion,
      registerAyudaRegistro: st.registerAyudaRegistro,
      estrellasNivel: st.estrellasNivel,
      estrellasSubEjercicio: st.estrellasSubEjercicio,
      resetAllProgress: st.resetAllProgress,
    }))
  );
}

// G3 — useEjerciciosG3()
export function useEjerciciosG3() {
  return useG3ProgressStore(
    useShallow((st) => ({
      completados: st.completados,
      fallosPorEjercicio: st.fallosPorEjercicio,
      estrellasPorNivel: st.estrellasPorNivel,
      caminoCompleto: st.caminoCompleto,
      hydrated: st.hydrated,
      isExerciseDone: st.isExerciseDone,
      isLevelComplete: st.isLevelComplete,
      isLevelUnlocked: st.isLevelUnlocked,
      nivelBadgeState: st.nivelBadgeState,
      firstIncompleteIndex: st.firstIncompleteIndex,
      registerFail: st.registerFail,
      completeExercise: st.completeExercise,
      setCaminoCompleto: st.setCaminoCompleto,
      estrellasNivel: st.estrellasNivel,
      segmentBetweenCompleted: st.segmentBetweenCompleted,
      resetAllProgress: st.resetAllProgress,
    }))
  );
}
isLevelUnlocked(nivel) gates access to each level: a level only unlocks once the previous one is marked complete via completeExercise(). The nivelBadgeState computed value drives the visual lock/unlock/active indicator on each level tile in the map screen.

​
Gamification: XP and levels

Completing exercises awards XP points. The XP system uses a scaling threshold defined in lib/gamification/xpLevel.ts: 
const XP_PER_LEVEL_BASE = 80;

/** XP required to advance from level L to L+1. */
export function xpRequiredForCurrentLevel(level: number): number {
  return XP_PER_LEVEL_BASE + (level - 1) * 40;
}

/** Normalized 0–1 progress bar value for the current level. */
export function xpProgress01(xp: number, level: number): number {
  const need = xpRequiredForCurrentLevel(level);
  return Math.max(0, Math.min(1, xp / need));
}

/** Add delta XP; automatically advances level if the threshold is crossed. */
export function addXpAndLevel(
  xp: number,
  level: number,
  delta: number
): { xp: number; level: number }
XP thresholds by level:
LevelXP required to advance
180 XP
2120 XP
3160 XP
4200 XP
n80 + (n−1) × 40 XP
The child’s level and XP are stored in their Supabase profile and unlocked achievements are evaluated on each session via evaluateNewAchievementIds().
XP and star counts are visible to caregivers in the Profile & Reports screen, giving therapists a quick overview of the child’s engagement and accuracy trends.

Build docs developers (and LLMs) love

Get started for freeTalk to us