# Duolingo — DESIGN.md

A cheerful, game-like learning app where a mascot talks you through every step and chunky buttons reward each tap.

Independent reference guide from browser captures and computed styles. Not an official brand guide. Values describe the captured desktop states; responsive rules below are implementation recommendations.

Captured: 2026-09-24

## Agent task
Build an original interface using this visual language. Inspect the existing stack and conventions first. Use the included screenshots to understand hierarchy, composition and density. Keep your own branding and content.

## Font
Observed family: **duolingo-sans**, with marketing display headlines in **feather**. A family name is not a bundled font licence. Use an available, licensed installation or a system sans-serif fallback.

## Marketing — Bright illustrated, light with a dark Super variant

### Observed palette
- Canvas: `#ffffff`
- Brand green (headlines, primary button, footer): `#58cc02`
- Button lip: `#58a700`
- Hero text: `#4b4b4b`
- Body text: `#777777`
- Link / secondary accent: `#1cb0f6`
- Footer heading on green: `#d7ffb8`
- Footer link on green: `#a5ed6e`
- Super page background: `#000437`

### Observed typography
| Role | Size / line height | Weight | Tracking |
|---|---|---|---|
| Super hero and section heading (feather) | 62px / 66.96px | 700 | normal |
| Section headline (feather) | 48px / normal | 700 | normal |
| Math hero heading | 40px / 44px | 700 | normal |
| Home hero heading | 32px / normal | 700 | normal |
| Feature heading (Math) | 28px / 32px | 700 | normal |
| Footer column heading | 19px / 26.6px | 700 | normal |
| Body | 17px / 24px | 500 | normal |
| Button label (uppercase) | 15px / normal | 700 | 0.8px |

### Layout & hierarchy
- Centred 1440px pages with content held to roughly the middle 1000px; bands alternate illustration left / text left down the page.
- Headlines are short and lowercase in a rounded display face (feather), in brand green on white or white on navy.
- Every page ends in a closing call-to-action band; the homepage closes into a full-bleed green footer with five link columns and a site-language list.

### Components & behavior
- Primary button: 50px high, 12px radius, #58cc02 fill with a 4px #58a700 bottom lip (box-shadow 0 4px 0), white uppercase 15px / 700 label with 0.8px tracking.
- Secondary button: white fill, 2px #e5e5e5 border with a 2px bottom lip, blue #1cb0f6 uppercase label.
- Course strip: a horizontally scrolling row of flag icons with uppercase grey labels and arrow controls, repeated on the homepage and Super page.
- Plan comparison (Super): three columns with check / cross rows; the paid column is raised, gradient-headed and marked with a check badge.

## Product — White, playful, colour-coded feedback

### Observed palette
- Canvas: `#ffffff`
- Heading text: `#3c3c3c`
- Body text: `#4b4b4b`
- Muted text: `#777777`
- Disabled / hint: `#afafaf`
- Border: `#e5e5e5`
- Primary green: `#58cc02`
- Green lip / correct text: `#58a700`
- Blue action: `#1cb0f6`
- Blue lip: `#1899d6`
- Selected fill: `#ddf4ff`
- Selected border (nav item): `#84d8ff`
- Error red: `#ff4b4b`
- Error text: `#ea2b2b`
- Correct banner (sampled, matches --color-sea-sponge): `#d7ffb8`
- Incorrect banner (sampled, matches --color-walking-fish): `#ffdfe0`
- XP yellow: `#ffc800`
- Streak orange: `#ff9600`
- New-word purple: `#ce82ff`

### Observed typography
| Role | Size / line height | Weight | Tracking |
|---|---|---|---|
| Exercise prompt / page title | 32px / 40px | 700 | normal |
| Feedback title | 24px / 30px | 700 | normal |
| Guidebook title | 25px / 30px | 700 | normal |
| Unit title | 22px / 28px | 700 | normal |
| Choice card label | 19px / 20px | 500 | normal |
| Rail card heading | 19px / 28px | 700 | normal |
| Body and sidebar nav | 17px / 25px | 500 | normal |
| Lesson footer button | 17px / 20.4px | 700 | 0.8px |
| Rail button | 15px / 18px | 700 | 0.8px |

### Layout & hierarchy
- Onboarding and lessons are full-screen with no navigation: a top row (back or close, a rounded green progress bar, hearts) and a fixed footer bar with a top rule holding Skip on the left and one primary action on the right.
- Onboarding questions put Duo and a speech bubble top-left and the answers in a centred one- or two-column card list; the bubble reacts to each answer.
- The learn path uses a fixed 256px left sidebar with a 2px #e5e5e5 right border, a central winding node path under a coloured unit banner, and a right rail of 2px-bordered, 16px-radius cards.

### Components & behavior
- Buttons are 'juicy': a ::before fill with a 0 4px 0 darker lip (#58cc02 over #58a700, #1cb0f6 over #1899d6), 16px radius, uppercase bold labels; disabled buttons turn flat grey.
- Answer cards: 12px radius, grey border with a bottom lip and a number-key badge; selected cards turn light blue, correct green, and matched pairs grey out.
- Feedback banner: a full-width footer sheet in light green or light red with an icon, a 24px title, Too easy / Too difficult / Report links and a Continue button recoloured to match.
- Celebration screens (lesson complete, streak, quests, gems) are single centred illustrations with a large number or stat cards and one Continue.

## Implementation recommendations
- Use your own name, logo, mascot, copy and sample data. Recreate the visual principles and interaction structure, not Duolingo's characters or illustrations.
- Use semantic HTML, visible focus states, labelled controls and accessible contrast; do not rely on colour alone to signal correct and incorrect answers.
- Recommended: use a 4px spacing base, collapse the sidebar and right rail on small screens, and keep the lesson footer action reachable.
- Recommended: implement loading, validation, error, success, empty and disabled states; do not infer unobserved backend behavior.
- Use the supplied font only when available and appropriately licensed; otherwise use a rounded system sans-serif fallback.
- Treat desktop measurements as reference values, not a complete responsive specification.

## Interaction inventory
- Learn path (guest): Reached with Later on the create-profile prompt, still without an account. A fixed left sidebar (Learn, Leaderboards, Quests, Shop, Profile, More) with Learn active in a light-blue pill; a green unit banner (Section 1, Unit 1, Order at a café) with a Guidebook button; a winding path of round lesson nodes (the active one has a progress ring and a START tooltip, the rest are grey, with a chest and a trophy); and a right rail with course, streak, gems and hearts counters, Unlock Leaderboards, Daily Quests and a Create a profile card. Screenshot: `captures/duolingo-product-learn.jpg`.
- Lesson start popover: Clicking the active node opens a green popover under it: "Order at a café", "Lesson 2 of 3" and a white START +10 XP button. The rest of the page is unchanged and not dimmed. Screenshot: `captures/duolingo-product-lesson-start.jpg`.
- Unit guidebook: "Unit 1 Guidebook" with "Explore grammar tips and key phrases for this unit", then a KEY PHRASES list of speech-bubble cards: a blue speaker icon, the Spanish phrase with dotted underlines on hint words, and the English translation in grey. The sidebar and right rail stay in place. Screenshot: `captures/duolingo-product-guidebook.jpg`.
- Match pairs exercise: "Select the matching pairs": two columns of five word tiles (English left, Spanish right), each with a number key badge. Two pairs are already matched and greyed out; "water" is selected in light blue, waiting for its partner. CHECK stays disabled because matching is judged per pair. Captured in the first lesson; the lesson opened from the popover starts with a different exercise. Screenshot: `captures/duolingo-product-match.jpg`.
- Correct answer feedback: After Check on the "cat" question, the chosen gato card turns green and a light-green banner rises across the footer: a green check in a white circle, "Nice job!", Too easy / Too difficult / Report links and a green CONTINUE. The progress bar has advanced. Same exercise as the flow's first-exercise step, in its answered state. Screenshot: `captures/duolingo-product-correct.jpg`.
- Incorrect answer feedback: A deliberately wrong pick (agua for "dog"): the banner turns light red with a red X, "Correct solution:" and "perro", and CONTINUE turns red. The heart counter drops from 5 to 4. The same question returned later in the lesson tagged PREVIOUS MISTAKE. Screenshot: `captures/duolingo-product-incorrect.jpg`.
- Lesson complete: Duo and a character at DJ decks with a looping sparkle, a yellow "Lesson Complete!" and two stat cards with coloured header strips: TOTAL XP 15 (yellow) and GREAT! 92% (green). REVIEW LESSON and CONTINUE sit in the footer. Captured after the count-up animation finished; the sparkles loop continuously. Screenshot: `captures/duolingo-product-lesson-complete.jpg`.
- Day streak: An orange flame, a large "1" and "day streak" in orange, then a card with a Th to M week row (Thursday checked) and "But your streak will reset if you don't practice tomorrow. Watch out!". CONTINUE is blue here. Screenshot: `captures/duolingo-product-streak.jpg`.

## Avoid
- Do not apply the lowercase marketing display headlines to lesson and learn-path screens, which use duolingo-sans throughout.
- Do not present sampled or unmeasured values as exact; the feedback banner fills are sampled from screenshots (they match Duolingo's own colour variables) and several marketing line heights computed as `normal`.
- Do not copy the mascot, characters or illustrations; they carry most of the brand and are not a pattern to reuse.
- Do not treat screenshots as editable components or original source code.
- Do not assume uncaptured hover states, mobile layouts, signed-in behavior, leaderboards, the shop or paid flows.

## Reference pages
- Homepage: https://www.duolingo.com/
- Super Duolingo: https://www.duolingo.com/super
- Duolingo Math: https://www.duolingo.com/math

## Capture scope
Logged-out desktop onboarding for Spanish from English: home, course picker, the Duo questionnaire (source, reason, level, daily goal, placement), the first lesson played to completion without an account, the create-profile prompt and the empty age step of sign-up. No account was created and nothing was entered into the sign-up form. Choosing Later opened the learn path, guidebook and lesson popover as a guest; leaderboards, quests, shop, profile, the Find my level placement test and every signed-in or paid screen are not captured. Learner counts, lesson content and exercise order can change over time.

## Format inspiration
- https://github.com/voltagent/awesome-design-md
- https://getdesign.md/

The structure is inspired by these resources. The guide text and values come from this independent capture pass. No proprietary source code or font files are included.