Amplify Activity Coding Standards
1. Computation Layer — JavaScript
Return format
All computation layer functions must return an object { correct, feedback }, not a plain string.
// ✅ Correct
function checkAnswer(input) {
return { correct: true, feedback: "✓ Correct! ..." };
}
// ❌ Wrong — old pattern, do not use
function checkAnswer(input) {
return "✓ Correct! ...";
}
Amplify handler pattern
var result = checkExpandedForm(studentInput, 4, 2);
displayText(result.feedback); // show explanation in text area
highlightCorrect(result.correct); // green if true, red if false
Function naming conventions
| Type | Pattern | Example |
|---|---|---|
| Generic type-in validator | check[Concept](input, ...params) | checkExpandedForm(input, base, exp) |
| Slide-specific MC | problem_[activity][slideNum](val) | problem_trans7(val) |
| Fill-in validators | check[Role](input, correct) | checkRootBoxes(input, 6) |
Type-in validation — normalization pattern
Always normalize student input before comparing. Strip whitespace, unify symbols.
function checkExpandedForm(input, base, exp) {
if (typeof input !== "string" || input.trim() === "") {
return { correct: false, feedback: "Please type your answer in the box." };
}
var normalized = input
.trim()
.replace(/\s*[×x\*]\s*/gi, "×") // unify ×, *, x → ×
.replace(/\s+/g, "");
// build expected, compare, return object
}
Multiple-choice validation pattern
Option values are always integers 1–4. Val 1 is always the correct answer. Pass the integer, not the label string.
function problem_trans7(val) {
var labels = { 1: "1/2 × 1/2 × 1/2", 2: "1/6", 3: "3/2", 4: "1/8" };
var hints = { 2: "...", 3: "...", 4: "..." };
if (val === 1) {
return { correct: true, feedback: "✓ Correct!\n\n..." };
}
return {
correct: false,
feedback: "✗ Not quite — you chose: " + (labels[val] || val)
+ "\n\n" + (hints[val] || "")
};
}
Numeric fill-in comparison
Use a small tolerance for floating point comparisons.
var studentNum = parseFloat(String(input).trim());
var correctNum = parseFloat(String(correct));
if (!isNaN(studentNum) && Math.abs(studentNum - correctNum) < 0.0001) {
// correct
}
JS feedback string math notation
In plain-text feedback strings (not rendered HTML):
- Fractions: write as
1/3— acceptable in text output - Exponents: write with
^— e.g.3^4(text context, not rendered math) - Multiplication: use
×(Unicode) — e.g."3 × 3 × 3"
2. HTML — Exponents (No Carets)
Never use ^ in rendered math content.
| Context | Wrong | Right |
|---|---|---|
| HTML text node | x^3 | x³ (Unicode superscript) |
| HTML element | x^3 | x<sup>3</sup> |
SVG <text> | x^3 | tspan dy pattern (see below) |
<code> blocks inside teacher notes may use ^ — they show Amplify syntax, not rendered math.Unicode superscript characters
⁰ ¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹
SVG tspan superscript pattern
<text x="150" y="50" font-family="Georgia,serif" font-size="24" fill="#1e3a5f">
x<tspan dy="-6" font-size="16">3</tspan>
</text>
SVG multi-term caption with repeated superscripts
Alternate up/down dy resets for each segment:
<text ...>
3<tspan dy="-4" font-size="10">⅓</tspan>
<tspan dy="4"> × 3</tspan>
<tspan dy="-4" font-size="10">⅓</tspan>
<tspan dy="4"> = 3 ✓</tspan>
</text>
3. HTML — Fractions (Always Vertical)
Use the .vfrac component. Never use horizontal slash notation (1/2) in rendered math.
CSS
.vfrac {
display: inline-flex;
flex-direction: column;
align-items: center;
vertical-align: middle;
line-height: 1.1;
font-size: 0.82em;
}
.vfrac-num { border-bottom: 2.5px solid currentColor; padding: 1px 7px 3px; line-height: 1; }
.vfrac-den { padding: 3px 7px 1px; line-height: 1; }
Usage
<!-- 1/3 -->
<span class="vfrac"><span class="vfrac-num">1</span><span class="vfrac-den">3</span></span>
<!-- (1/3)⁴ -->
(<span class="vfrac"><span class="vfrac-num">1</span><span class="vfrac-den">3</span></span>)⁴
<!-- 1/3⁴ — superscript in denominator -->
<span class="vfrac"><span class="vfrac-num">1</span><span class="vfrac-den">3⁴</span></span>
Buttons containing fractions
.mc-btn {
display: flex;
align-items: center;
justify-content: center;
gap: 6px;
}
4. HTML — Multiplication Symbol
| Situation | Symbol | Reason |
|---|---|---|
| Numeric factors | × (×) | Standard math notation |
| Any variable as base | * | Avoids visual confusion with variable names |
5. HTML — Blank / Fill-In Boxes
Inline answer blank (5² = ___)
.answer-blank {
display: inline-block;
min-width: 44px;
height: 34px;
border: 2px dashed #94a3b8;
border-radius: 6px;
vertical-align: middle;
}
5² = <span class="answer-blank"></span>
Exponent-position blank (3^□)
.exp-blank {
display: inline-block;
min-width: 26px;
height: 22px;
border: 2px dashed currentColor;
border-radius: 4px;
vertical-align: super;
margin-left: 2px;
font-size: 0.5em;
}
3<span class="exp-blank"></span>
SVG blank leaf box (factor trees)
<rect x="30" y="126" width="90" height="56" rx="10"
fill="white" stroke="#94a3b8" stroke-width="2.5" stroke-dasharray="7,4"/>
6. HTML — Color Coding
Colors encode semantic roles, not specific content. A color is assigned to a role at the start of an activity and used consistently for that role throughout — just as dashes (___) universally signal a fill-in-the-blank regardless of subject. Never use a color for two different roles within the same activity.
The four standard roles
| Role | What it signals | Background | Border | Text |
|---|---|---|---|---|
| Primary form | The form the lesson is introducing or asking students to produce | #dbeafe |
#3b82f6 |
#1e3a5f |
| Secondary / equivalent | A related or equivalent representation of the same value | #dcfce7 |
#22c55e |
#14532d |
| Equivalence callout | Highlights that two expressions name the same number; third notations | #fef3c7 |
#f59e0b |
#78350f |
| Student fill-in / blank | Where students write, recall, or produce an answer | #f5f3ff |
#7c3aed dashed |
#4c1d95 |
How roles map to content (examples)
| Topic | Primary — blue | Secondary — green | Equiv — amber | Fill-in — purple |
|---|---|---|---|---|
| Exponents | Exponent form (4²) | Expanded form (4×4) | Fractional exponent (4^½) | Blank to complete |
| Fractions | Fraction (¾) | Decimal (0.75) | Percent (75%) | Blank |
| Algebra | Factored form | Expanded / distributed | Graphical or table form | Blank |
| Geometry | Formula | Values substituted in | Computed result | Blank |
Rules
- Assign roles before building. Decide which form gets which color before writing any HTML. Add a comment at the top of the file documenting the mapping.
- Never reassign a color mid-activity. If blue means "exponent form" on slide 2, it must mean the same on slide 9.
- Student fill-in is always purple dashed. This is the universal signal for "student completes this," equivalent to ___ in print. Non-negotiable.
- Revealed answers stay purple, border goes solid. When a filled-in answer is shown or confirmed, keep purple but switch
border-stylefrom dashed to solid.
CSS
.box--primary { background: #dbeafe; border: 2px solid #3b82f6; color: #1e3a5f; }
.box--secondary { background: #dcfce7; border: 2px solid #22c55e; color: #14532d; }
.box--equiv { background: #fef3c7; border: 2px solid #f59e0b; color: #78350f; }
.box--blank { background: #f5f3ff; border: 2px dashed #7c3aed; color: #4c1d95; }
.box--blank.answered { border-style: solid; }
Form labels
When labeling a form above or beside its box, the label text color must match the box role.
| Role | Label text color | Note |
|---|---|---|
| Primary | #2563eb | Saturated blue — reads as blue on white |
| Secondary / equivalent | #16a34a | Saturated green |
| Equivalence callout | #d97706 | Saturated amber |
| Student fill-in | #7c3aed | Saturated purple |
#1e3a5f, #14532d, etc.) for labels on a white background — those are optimized for text inside the colored box and read as near-black on white.Inline form terms in question prompts
When a question prompt contains a word or phrase that names a form, that term is colored to match its role. The rest of the sentence stays black.
| Role | Vocabulary family |
|---|---|
| Primary — blue | exponent, exponent form, exponential form, exponential notation, power, index |
| Secondary — green | expanded form, expanded, repeated multiplication, factor, factors |
| Equivalence — amber | equivalent, equivalence, alternate notation, fractional exponent |
| Student fill-in — purple | fill in, complete, your answer |
7. SVG Factor Trees
Coordinate conventions
- ViewBox: sized to content —
0 0 300 190(2 leaves) up to0 0 500 190(5 leaves) - Top box: centered horizontally,
y = 12, height56 - Leaf boxes:
y = 126, height56, width90 - Branches: cubic bezier
M cx 68 C cx 95 leafX 100 leafX 126 - × symbols: between adjacent leaf centers at
y ≈ 162 - Leaf spacing: ~15px gap between boxes
Fill colors
| Box type | Fill | Stroke |
|---|---|---|
| Top (radicand) | #dbeafe | #3b82f6 |
| Filled leaf | #dcfce7 | #22c55e |
| Blank leaf | white | #94a3b8, stroke-dasharray="7,4" |
| Equivalence leaf | #fef3c7 | #f59e0b |
8. Slide Architecture
Full interactive HTML (teacher + student reference)
- Sticky TOC nav strip, color-coded by slide type
- Left border color by type: concept=blue, typein=purple, MC=orange, visual=teal
- Collapsible
<details>for teacher/Amplify setup notes - Collapsible answer keys for visual slides
- Per-slide print buttons using
data-print+ CSS pattern
Teaching-only HTML (classroom projection)
- Full-screen slides with JS slideshow (click or arrow keys)
- No inputs, no teacher notes, no interactive elements
- Font sizes ≥ 3.5rem for expressions, ≥ 1.7rem for notes
- Captions below trees state the equation correctly:
"9 = 3 × 3, so √9 = 3"— never"√9 = 3 × 3"
Slide type badge colors
| Type | Border | Badge background |
|---|---|---|
| Concept | #2563eb | #dbeafe |
| Type-in | #7c3aed | #ede9fe |
| Multiple choice | #ea580c | #ffedd5 |
| Visual | #0d9488 | #ccfbf1 |
8.4 Vocabulary Introduction Slides — "Math As A Second Language" Pattern
Include a Math As A Second Language (MASL) slide at the start of any activity that introduces new notation or terminology. The purpose is to teach students how to read the math aloud before they are asked to work with it.
Required elements
- Labeled generic form — Show the abstract, generalized notation (e.g.,
b^n) with annotated arrows naming each component. Labels use the established form-term color system. - Component definitions — Each labeled part names the mathematical term (e.g., "base", "exponent/power").
- Multiple concrete examples — At least three examples covering diverse types: an integer, a variable, and a fraction or compound expression. Display each in the primary-form blue box.
- Spoken English translation — Below each example, an italicized spoken phrase. Where multiple phrasings are valid, show both.
When to include a MASL slide
- Beginning of any activity introducing new notation (exponents, radicals, fractions, absolute value, etc.)
- Any time students are expected to use specific vocabulary in discussion or writing
- Before the first interactive problem of its type
Label placement rules for annotated SVGs
- Base / primary component label: neutral dark text (
#374151) — structural, not a form role - Exponent / power label: blue (
#2563eb) — names the primary form concept - Connector lines match the label color; arrowhead triangles reinforce directionality
- Maintain at least 30px horizontal separation between labels
- Total SVG height = bottom of last label + 4px buffer
MASL spoken-phrase card color
Spoken-phrase cards use teal across all slides and all decks. This color is reserved exclusively for the linguistic/spoken layer. Never use it for math content roles.
| Element | Background | Border | Text |
|---|---|---|---|
.masl-spoken |
#ccfbf1 |
#0d9488 solid |
#134e4a |
.masl-spoken-alt |
inherits | inherits | #0d9488 |
.masl-spoken {
background: #ccfbf1;
border: 2px solid #0d9488;
border-radius: 10px;
padding: 10px 20px;
font-family: Georgia, serif;
font-style: italic;
color: #134e4a;
text-align: center;
line-height: 1.55;
/* font-size: set per deck — 1.5rem in reference HTML, 2rem in teaching slides */
}
.masl-spoken-alt { color: #0d9488; }
The general spoken form above the annotated diagram (e.g., "b to the power of n") also uses .masl-spoken. Apply max-width: none via inline override when the card spans full width.
exponent_roots_visual.html → Slide 48.5 Minimum Text Sizes for Classroom Projection
Research basis
Two independent methods converge on the same answer. At 30 feet, for students with 20/40 vision (mild myopia):
- Optometry method (ISO 9241-303): ≥ 40 arc minutes → ~4.35 inches on screen
- AV industry standard (Extron / InfoComm): 2 × (30 ÷ 15) = 4 inches minimum
| Text role | Minimum | Notes |
|---|---|---|
| Absolute floor — no text ever smaller | 1.5 rem (24 px) | Applies to footnotes, debug labels, teacher-only text |
| Labels, captions, secondary text | 2 rem (32 px) | SVG annotation labels, .expr-label, slide descriptions |
| Problem prompts, body text | 2.5 rem (40 px) | Question text students read from seats |
| Math expressions in problems | 3.5 rem (56 px) | The expression being evaluated or answered |
| Featured / headline expressions | 4 rem+ (64 px) | Concept slides, single-focus displays |
| Full back-row legibility (mild myopia) | 9.25 rem (148 px) | Target for expressions on concept/intro slides |
Rules
- Never go below 1.5 rem for any text — not even SVG annotation labels. If a label cannot fit at 1.5 rem, redesign the layout.
- SVG text sizes are absolute CSS pixels. A
font-size="12"in SVG is 12px regardless of parent. Minimumfont-size="24", preferredfont-size="32"for classroom content. .masl-spokenand all spoken-phrase text: minimum 1.1 rem. Alternate phrasings minimum 1 rem.- The 9.25 rem target applies to the dominant expression on concept slides.
9. Amplify Platform — Best Practices
cl.desmos.com), community writeups, and observable patterns in this codebase. Official reference: classroom.amplify.com/computation-layer/documentation.9.1 What the Computation Layer actually is
The Desmos/Amplify Computation Layer (CL) is a proprietary DSL, not JavaScript. It uses a reactive, declarative when/otherwise syntax to wire "sources" (data emitted by components) to "sinks" (properties that components accept).
// CL syntax — this is NOT JavaScript
content: when mc1.isSelected(1) and button.timeSincePress > 0
"Correct!"
when button.timeSincePress > 0
"Try again."
otherwise ""
The existing activity files in this project use a JavaScript layer — a custom Amplify host environment that calls named JS functions and passes student-response values into them. JS conventions in sections 1–8 apply to that environment. CL DSL conventions below apply to native CL scripts in the Activity Builder.
9.2 CL language primitives
| Concept | Notes |
|---|---|
| Sinks | The property being assigned — always the first token on a line followed by : |
| Sources | Data emitted by named components — referenced as componentName.sourceName |
| Conditional | when <condition> <value> when <condition> <value> otherwise <default> |
| Data types | Number (float), Boolean, Text String (quoted), LaTeX String |
| Component naming | Components must be named for cross-component references to work |
| Logical operators | and, or, not() — not &&, ||, ! |
9.3 Key sources by component type
Math Response — use for all student type-in answers
| Source | Type | Description |
|---|---|---|
input.latex | LaTeX String | Raw math expression as typed by student |
input.numericValue | Number | Numeric value of the expression (if reducible) |
input.submitted | Boolean | True once student has submitted |
input.timeSinceSubmit | Number | Seconds since last submit (use > 0 as a trigger) |
numericValue(input.latex) | Number | Function form — parses numeric value from LaTeX |
isBlank(input.latex) | Boolean | True if student has not typed anything |
Choice (multiple choice)
| Source | Type | Description |
|---|---|---|
mc.isSelected(n) | Boolean | True if option n is currently selected (1-indexed) |
mc.submitted | Boolean | True after submit |
button.timeSincePress | Number | Seconds since action button was pressed |
Note component (for displaying feedback)
| Sink | Type | Description |
|---|---|---|
content: | Text String | The displayed feedback text — supports when/otherwise |
submitLabel: | Text String | Overrides the submit button label |
submitDisabled: | Boolean | Disables submit button when true |
hidden: | Boolean | Hides the note entirely |
9.5 Feedback display patterns
// Native CL pattern
content: when input.submitted and numericValue(input.latex) = 9
"Correct! 3² = 9"
when input.submitted
"Not quite. Remember: 3² means 3 × 3."
otherwise ""
Formatting constraints (both environments)
- Feedback text is plain text only — no HTML tags, no Markdown
- Line breaks in CL strings: not reliably supported; keep feedback to one or two sentences
- Math notation: write out symbols in Unicode (
×,÷, superscript digits) — do not embed LaTeX - Quote characters in CL: must be straight quotes — smart/curly quotes will cause syntax errors
9.7 Submission gating — preventing premature feedback
// Bad — feedback fires mid-typing
content: when numericValue(input.latex) = 25 "Correct!" otherwise "Try again."
// Good — feedback only after submit
content: when input.submitted and numericValue(input.latex) = 25
"Correct!"
when input.submitted
"Try again."
otherwise "Enter your answer and press Submit."
9.8 Cross-screen and cross-component references
- Components on the same screen can reference each other by name:
mc1.isSelected(2) - Components on different screens cannot directly reference each other
- The screen-level script supports only
title:,subtitle:, andcoverText:sinks - Workaround for cross-screen state: use a hidden table or graph to store values
9.9 Sandbox restrictions and known limitations
| Restriction | Status |
|---|---|
| No DOM access | CL is sandboxed — no document, window, or DOM APIs |
| No external network calls | No fetch, XMLHttpRequest, or external dependencies |
No console.log | Not available in CL or the JS layer |
| CL is declarative, not imperative | No loops, arrays, or imperative control flow in native CL |
choiceContent index must be a constant | Cannot pass a variable as the index — only literal numbers |
| LaTeX in MC options renders as raw string | Avoid embedding LaTeX option text in feedback strings |
| Quote pasting breaks scripts | Smart quotes from word processors break CL string literals |
JS layer specifics (this codebase)
- Use
varandfunctiondeclarations —let,const, and arrow functions may not be supported - No
class, no destructuring, no template literals — write ES5-compatible code
9.11 Where CL scripts go — the </> rule
All CL scripts belong in the Edit Computation Layer (</>) editor on the NOTE component, never in the Math Response or Multiple Choice component editors.
- Add a Note component to the slide
- Click the
</>icon on the Note component — this opens the Computation Layer editor - Paste or type the CL script there
</> editor. The visible text area is for static display text only.Debug technique for string matching
Add a temporary Note with only content: mathResponse1.latex. Submit an answer — the Note displays the exact LaTeX string Amplify produced. Copy that string into your isCorrect check, then delete the debug Note.
9.12 Resources
| Resource | URL |
|---|---|
| Amplify CL Documentation (auth required) | classroom.amplify.com/computation-layer/documentation |
| Desmos Help Center — Intro to CL | help.desmos.com/hc/en-us/articles/4405012401165 |
| CL Support Forum | cl.desmos.com |
| Desmos CL Blog | blog.desmos.com/articles/computation-layer-resources/ |
| Community CL collection | teacher.desmos.com/collection/5ca67826a3d26925716a11a5 |
10. Word Problem Language Standard
Math activities often serve multi-lingual learners who are simultaneously learning English and learning mathematics. Dense or idiomatic English in problem prompts creates a language barrier that obscures the math. These rules reduce that barrier.
Core rules
- No passive voice. Rewrite every passive construction as active.
- Avoid "is", "was", "be", "been", "being" as main verbs. These forms are ambiguous across tenses and difficult to parse. Prefer concrete action verbs.
- Present tense by default. Use present tense for all problem scenarios, definitions, and instructions. Past tense only when context requires it.
- No idioms. Every phrase must mean exactly what it says. Remove expressions whose meaning cannot be inferred from the individual words.
- Short sentences. Break compound sentences at conjunctions. Target one idea per sentence.
Examples
| ❌ Avoid | ✅ Use instead |
|---|---|
| "The answer is found by multiplying..." | "Multiply the base by itself..." |
| "How many times has the value been multiplied?" | "How many times does the base multiply?" |
| "It is important to remember that..." | "Remember: ..." |
| "The expression can be simplified to..." | "Simplify the expression to..." |
| "Once you get the hang of it..." | (remove — idiom) |
| "What would the answer be if..." | "What does the expression equal when..." |
| "There are 5 groups that were divided..." | "5 groups divide into..." |
Vocabulary in problem prompts
When a prompt uses a term students may not know, pair it with its plain-language meaning in the same sentence:
"Write the exponent — the small raised number — for this expression."
Do not assume students know the term from a previous slide. Repetition of the paired form reinforces both the vocabulary and the concept.
Scope
content: sink text, teacher notes visible to students, slide captions.<details> content, this standards document.10.1 Polysemous Words — Explicit Flagging Requirement
A polysemous word carries different meanings in everyday English and in mathematics. Multi-lingual learners often acquire the everyday meaning first. When they encounter the same word in a math context, the conflict is silent — students may appear to follow along while parsing the wrong meaning.
"Find the mean (average) of the data set."
"The volume (amount of space inside) of the box is 24 cm³."
Common polysemous math/everyday conflicts:
| Word | Everyday meaning | Math meaning |
|---|---|---|
| mean | unkind, or "intend to" | average of a data set |
| volume | loudness | amount of 3D space |
| odd | strange | not divisible by 2 |
| even | smooth, or "also" | divisible by 2 |
| table | furniture | organized grid of data |
| right | correct, or a direction | 90-degree angle |
| degree | academic credential, temperature | unit of angle measure |
| square | a shape | multiply a number by itself |
| ruler | a leader | measuring tool |
| principal | school administrator | original amount of money |
| interest | curiosity | money earned or owed |
| improper | rude | fraction where numerator ≥ denominator |
| irrational | unreasonable | number that cannot be expressed as a fraction |
| imaginary | not real | square root of a negative number |
10.2 Sentence Structure — One Subordinate Clause Cap
Rule 1 — One subordinate clause per sentence. A problem prompt may contain at most one subordinate clause (beginning with when, if, because, which, that, although, while, after, before, since, unless). When a sentence has two or more, split it.
| ❌ Avoid | ✅ Use instead |
|---|---|
| "If the base is 3 and the exponent is 4, which means the base repeats 4 times, what is the value?" | "The base is 3. The exponent is 4. What is the value?" |
| "Find the answer, which is the product of the two factors that you identified in the previous step." | "You identified two factors. Multiply them. What is the product?" |
Rule 2 — Pronouns require a named antecedent in the same sentence. Pronouns (it, they, this, that, these, those) must have their referent named in the same sentence — not in the previous sentence.
| ❌ Avoid | ✅ Use instead |
|---|---|
| "Look at the two factors. They multiply to give the original number." | "The two factors multiply to give the original number." |
| "The expression equals 81. Write it in exponent form." | "Write 81 in exponent form." |
| "This is called the expanded form." | "The expression 4 × 4 × 4 is called expanded form." |
10.3 Feedback String Language Standard
The §10 core rules apply to all feedback strings. The additional rules below are specific to feedback — the text a student reads after making an attempt.
- State what the student did before evaluating it. Begin incorrect feedback by naming the student's answer or action, then explain the issue.
- ❌ "Not quite — try again."
- ✅ "Not quite. 3 + 3 is addition, not repeated multiplication."
- Name the correct form. Do not say "try again" alone. Every incorrect feedback string must include the correct answer or a direct pointer to it.
- ❌ "That's not right. Try again."
- ✅ "Not quite. 3² means 3 × 3 = 9."
- No rhetorical questions. Rhetorical questions require students to parse indirect register. MLs may read them as literal questions.
- ❌ "Did you remember to multiply the base by itself?"
- ✅ "Multiply the base by itself: 3 × 3."
- Use "Correct" / "Not quite" as openers. Never open with "Wrong," "Incorrect," or "No."
- ❌ "Wrong. The answer is 9."
- ✅ "Not quite. The answer is 9."
Feedback string opener conventions:
| Situation | Opener |
|---|---|
| Correct answer | "Correct!" or "✓ Correct!" |
| Incorrect answer | "Not quite." or "✗ Not quite —" |
| Empty/blank submission | "Please type your answer." |
| Non-numeric input (expected number) | "Please enter a number." |
10.4 Concept-First Vocabulary Introduction (Slide Design Standard)
Rule: Any activity slide that introduces a new vocabulary term must present the concept or visual representation before the label. Students see and interact with the concept first. The vocabulary word is introduced after they have a referent for it.
Required ordering on vocabulary introduction slides:
- Visual or concrete representation of the concept
- The concept itself — what it does or how it behaves
- The vocabulary label — the word or symbol
- The definition — a plain-language statement
- Usage examples — the label applied in context
This sequencing prevents the confusion that arises when students encounter a word before they have a referent for it. For MLs who learned the concept under a different term in their home language, seeing the concept first provides a hook to prior knowledge.
Example (exponent activity)
- Show: A diagram of 4 × 4 × 4 = 64
- Ask: "How many times does 4 appear?"
- Introduce: "This count — how many times the base repeats — is the exponent."
- Define: "The exponent (also called the power) tells you how many times to multiply the base by itself."
- Apply: Multiple examples using the word "exponent" in context.
10.5 Sentence Frames for Type-In and Discourse Slides
Rule: Every type-in slide where students write an explanation (not just a number or expression) must include a sentence frame as a visible scaffold. The frame appears above or beside the input box, never below it.
Sentence frame library — organized by KLU:
| KLU | Frame pattern | CSS class |
|---|---|---|
| Recount | "First I ___, then I ___." | sentence-frame--recount |
| Recount | "To solve this, I ___, then ___." | sentence-frame--recount |
| Explain | "The answer is ___ because ___." | sentence-frame--explain |
| Explain | "___ means ___." | sentence-frame--explain |
| Describe | "I notice that ___." | sentence-frame--describe |
| Describe | "___ is [larger/smaller] than ___ because ___." | sentence-frame--describe |
| Argue | "I know this is correct because ___." | sentence-frame--argue |
| Argue | "I disagree because ___." | sentence-frame--argue |
For Discuss slides (verbal/social mode): no written sentence frame. Use a pair-talk prompt label — "Talk with your partner:" — without a frame card.
See §10.6 for the full KLU color palette and CSS class definitions.
10.6 KLU Color System
Each KLU directive verb and its matching sentence frame share a teal variant. The color is the visual link between the directive word in the prompt ("Explain why...") and the scaffold that helps the student respond. Over repeated encounters, the pairing internalizes — the color becomes the retrieval cue even in uncolored contexts like tests.
.klu-term class. The sentence frame on the same slide uses the matching .sentence-frame--[klu] class. The KLU category and color travel together — even when the frame wording is adapted for the specific problem.Palette
| KLU | Directive / border | Frame background | Deep text |
|---|---|---|---|
| Recount | #0a7a5e | #d1fce9 | #064033 |
| Explain | #0d7a6e | #cdfbf1 | #07403c |
| Describe | #0e7a8c | #c9f8fc | #073e4e |
| Argue | #1070a0 | #c8ecf8 | #093351 |
| MASL spoken phrase (existing, §8.4) | #0d9488 | #ccfbf1 | #134e4a |
CSS
/* KLU directive verb — inline span in problem prompts */
.klu-term { font-weight: 700; }
.klu-term--recount { color: #0a7a5e; }
.klu-term--explain { color: #0d7a6e; }
.klu-term--describe { color: #0e7a8c; }
.klu-term--argue { color: #1070a0; }
/* Sentence frame card — base layout (no color) */
.sentence-frame {
border-radius: 8px;
padding: 10px 16px;
margin-bottom: 12px;
font-size: 0.95rem;
border-width: 1.5px;
border-style: solid;
}
/* KLU color variants */
.sentence-frame--recount { background: #d1fce9; border-color: #0a7a5e; color: #064033; }
.sentence-frame--explain { background: #cdfbf1; border-color: #0d7a6e; color: #07403c; }
.sentence-frame--describe { background: #c9f8fc; border-color: #0e7a8c; color: #073e4e; }
.sentence-frame--argue { background: #c8ecf8; border-color: #1070a0; color: #093351; }
/* Frame label — uses the KLU's directive color */
.frame-label {
display: block;
font-size: 0.78rem;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.07em;
margin-bottom: 4px;
}
.sentence-frame--recount .frame-label { color: #0a7a5e; }
.sentence-frame--explain .frame-label { color: #0d7a6e; }
.sentence-frame--describe .frame-label { color: #0e7a8c; }
.sentence-frame--argue .frame-label { color: #1070a0; }
/* Frame text */
.frame-text { font-style: italic; }
HTML usage — directive verb + adapted frame
<!-- Explain: colored directive in prompt, problem-specific frame -->
<p class="problem-prompt">
<span class="klu-term klu-term--explain">Explain</span> why 3² is not the same as 3 × 2.
</p>
<div class="sentence-frame sentence-frame--explain">
<span class="frame-label">Use this sentence to help you:</span>
<span class="frame-text">3² is not the same as 3 × 2 because ___.</span>
</div>
<!-- Argue: colored directive in prompt, problem-specific frame -->
<p class="problem-prompt">
<span class="klu-term klu-term--argue">Argue</span>: is 64 a perfect square? How do you know?
</p>
<div class="sentence-frame sentence-frame--argue">
<span class="frame-label">Use this sentence to help you:</span>
<span class="frame-text">64 [is / is not] a perfect square because ___.</span>
</div>
The Argue frame above is adapted to the problem — not the generic library wording. The sky-teal color identifies it as Argue regardless of the wording.
11. Deliverable Standard — CL Text File
Every activity must produce a plain-text CL guide file alongside the other activity files. This file is the primary reference a teacher uses when building the activity in the Amplify Activity Builder.
File naming convention
[activity_name]_CL.txt
Examples: exponent_problems_CL.txt · exponent_intro_CL.txt
Required file structure
AMPLIFY COMPUTATION LAYER SCRIPTS — [ACTIVITY TITLE]
[one-line description]
================================================================
SETUP INSTRUCTIONS:
================================================================
For MULTIPLE CHOICE slides:
1. Add a Multiple Choice component and name it as shown below
2. Add a Note component on the same slide
3. Click the </> (Edit Computation Layer) icon on the Note
4. Paste the script into the computation layer editor
For TYPE-IN slides:
1. Add a Math Response component and name it as shown below
2. Add a Note component on the same slide
3. Click the </> (Edit Computation Layer) icon on the Note
4. Paste the script into the computation layer editor
================================================================
SLIDE [N]: [Slide description]
================================================================
[Component type] Component Name: [name]
Note Component — paste into the </> Computation Layer editor:
--------------------------------------------------
[CL script]
--------------------------------------------------
================================================================
END OF SCRIPTS
================================================================
Script block rules
- Each script block is delimited by
--------------------------------------------------lines - Scripts contain no inline comments — CL does not support them
- All explanatory text goes in the surrounding plain text, not inside the script block
- Component names in the script must exactly match the "Component Name:" line above that block
MC option order documentation
For every Multiple Choice slide, list the options explicitly with their position and which is correct:
Enter choices in THIS ORDER in Amplify:
- Choice 1: [label] (correct)
- Choice 2: [label]
- Choice 3: [label]
- Choice 4: [label]
String-matching slides
When a slide uses input.latex string comparison (not numeric), include a TESTING REQUIRED block:
TESTING REQUIRED:
After setup, submit the correct answer yourself and check whether
feedback fires. If it does not:
- Add a temporary Note to the slide
- Click its </> icon and enter: content: [componentName].latex
- Submit an answer — the Note shows the exact LaTeX string produced
- Add that string to the isCorrect line in your real Note's </> editor
- Delete the debug Note when done
10.8 Notation Convention Disclosure
When an activity uses notation that differs from international standards, include a Notation Note at the top of the CL Text File and as a teacher note at the start of the activity.
| Convention | Example used | Note for teacher |
|---|---|---|
| Decimal separator | . (period) | Some students use , (comma): 3,14 for 3.14 |
| Thousands separator | , (comma) | Some students use . (period): 1.000 for 1,000 |
| Division symbol | ÷ | Some regions use : as the division operator |
| Multiplication symbol | × | Some regions use · (center dot) |
Notation Note block format (for the CL Text File header):
NOTATION NOTE:
This activity uses:
- A period as the decimal separator (3.14, not 3,14)
- A comma as the thousands separator (1,000 not 1.000)
- ÷ as the division symbol (not :)
If students write answers using a different convention,
evaluate the math — not the notation.
Reference implementations
| File | Activity |
|---|---|
exponent_problems_CL.txt | Exponent equations (find the variable) |
exponent_intro_CL.txt | Exponent intro & roots |
Activity files: amplify_exponent_equations.js · amplify_exponent_intro.js · exponent_roots_visual.html · exponent_teaching_slides.html
12. Language Objectives in Activity Files
Every interactive activity slide asks students to perform a language function — not just a math operation. A student might recount a procedure, explain a decision, argue for an answer, or describe a pattern. Each function requires different language scaffolds. The current slide-type labels (Concept, Type-in, MC, Visual) describe the interaction format, not the language function.
Language objective comment format
For each slide in an activity HTML file, add an optional (but encouraged) HTML comment:
<!-- LANGUAGE OBJECTIVE: [WIDA Key Language Use] — [one-sentence description] -->
WIDA Key Language Uses (KLUs)
| KLU | Meaning in math context | Example prompt | CSS class |
|---|---|---|---|
| Recount | Reproduce steps or facts in sequence | "List the steps you took to find the prime factors." | klu-term--recount |
| Explain | Describe how or why something works | "Explain why 2³ is not the same as 2 × 3." | klu-term--explain |
| Argue | Justify or defend a claim with evidence | "Is 64 a perfect square? Explain how you know." | klu-term--argue |
| Discuss | Exchange ideas with a partner or class | Pair-talk slides; exit ticket conversations | bold only — no frame |
| Describe | Characterize a pattern, object, or relationship | "What do you notice about the exponent and the factor count?" | klu-term--describe |
Example usage in HTML
<!-- SLIDE 3 — Type-in -->
<!-- LANGUAGE OBJECTIVE: Explain — Students explain why the base repeats the number of times shown by the exponent -->
<section class="slide slide--typein" id="slide-3">
...
</section>
<!-- SLIDE 5 — Multiple choice -->
<!-- LANGUAGE OBJECTIVE: Argue — Students select and justify the correct exponent form -->
<section class="slide slide--mc" id="slide-5">
...
</section>
Language objectives in the CL Text File
Include the language objective in the CL Text File slide header:
================================================================
SLIDE 3: TYPE-IN — Write the exponent form
LANGUAGE OBJECTIVE: Explain — Students explain why the base repeats
================================================================
Why this matters for ML-inclusive design
A student asked to recount needs vocabulary and sequencing connectors ("first," "then," "finally"). A student asked to argue needs claim-and-evidence language ("I know this because..."). Without identifying the language function, it is impossible to select the right scaffold. WIDA's framework requires language objectives alongside content objectives for ML-inclusive lesson planning. Adding them as HTML comments costs nothing and creates a template for teachers who must write WIDA-aligned lesson plans.
Activity files: amplify_exponent_equations.js · amplify_exponent_intro.js · exponent_roots_visual.html · exponent_teaching_slides.html · Last updated: 2026-02-25