# Design: `learn` **Read [`../README.md`](../README.md) first.** It explains how this design's `theme.css` and `index.html` are meant to be used alongside this file. > A Duolingo-inspired learning interface: dark navy surfaces, green action buttons, rounded forms, and a friendly rhythm built around momentum and progress. **Adjectives:** focused, encouraging, bright, tactile, motivating. **Use this when** you are building educational apps, onboarding flows, habit trackers, language learning tools, or anything where progress, repetition, and encouragement are the product. This design works best when the UI wants to feel clear, optimistic, and action-forward. **Do not use this when** the product needs to feel premium, corporate, or austere. Avoid this for financial systems, legal tools, or clinical dashboards where seriousness should dominate the interface. --- ## Influences - **Duolingo** — the dark navy canvas, the green CTA buttons, the oversized rounded pills, and the emphasis on routine and progress over density. - **Language-learning products** — the pattern of single-purpose actions, repeated modules, and low-friction task flows. - **Modern app shells** — the focus on compact navigation, clear hierarchy, and strong affordances for large, touch-friendly actions. What was deliberately *not* taken: photo-real illustration, noisy gradients, or a toy-like look. The design keeps the motivational energy of Duolingo without becoming cartoonish. --- ## Colour The palette is the reference product's own, unmodified in both themes: `#58CC02` green, `#1CB0F6` blue, `#FFC800` gold, `#FF4B4B` red and `#CE82FF` purple, over `#131F24` with `#202F36` surfaces in dark, and over white with `#E5E5E5` borders in light. Brightness is the point. These are saturated, high-lightness fills that carry white labels, and they are what make the interface read as a game rather than a form. Holding them exactly is a deliberate choice with a real cost in light mode — see Measured contrast below, and read it before shipping this to anyone. | Token | Light | Dark | Note | |---|---|---|---| | `--background` | `oklch(1 0 89.88)` | `oklch(0.2304 0.0195 225.76)` | Page surface | | `--foreground` | `oklch(0.4128 0 89.88)` | `oklch(0.9728 0.0083 236.56)` | Body text | | `--card` | `oklch(1 0 89.88)` | `oklch(0.2949 0.0237 228.44)` | Raised surface | | `--popover` | `oklch(1 0 89.88)` | `oklch(0.2949 0.0237 228.44)` | Floating surface | | `--primary` | `oklch(0.7478 0.2289 137.63)` | `oklch(0.7478 0.2289 137.63)` | Brand action — the green | | `--primary-foreground` | `oklch(1 0 89.88)` | `oklch(0.2304 0.0195 225.76)` | Text on primary | | `--secondary` | `oklch(0.7181 0.1513 237.07)` | `oklch(0.7181 0.1513 237.07)` | Secondary action — the blue | | `--secondary-foreground` | `oklch(1 0 89.88)` | `oklch(0.2304 0.0195 225.76)` | Text on secondary | | `--muted` | `oklch(0.9761 0 89.88)` | `oklch(0.2949 0.0237 228.44)` | Soft fill | | `--muted-foreground` | `oklch(0.5693 0 89.88)` | `oklch(0.7032 0.0269 229.31)` | Secondary text | | `--accent` | `oklch(0.8575 0.1752 88.49)` | `oklch(0.8575 0.1752 88.49)` | Reward gold | | `--accent-foreground` | `oklch(0.4128 0 89.88)` | `oklch(0.2304 0.0195 225.76)` | Text on accent | | `--destructive` | `oklch(0.6708 0.2165 25.19)` | `oklch(0.6708 0.2165 25.19)` | Danger | | `--destructive-foreground` | `oklch(1 0 89.88)` | `oklch(0.2304 0.0195 225.76)` | Text on destructive | | `--border` | `oklch(0.9219 0 89.88)` | `oklch(0.3847 0.0246 234.61)` | Container edges (2px) and dividers | | `--input` | `oklch(0.9219 0 89.88)` | `oklch(0.526 0.0246 234.61)` | Control boundaries | | `--ring` | `oklch(0.7478 0.2289 137.63)` | `oklch(0.7478 0.2289 137.63)` | Focus ring | ### Why this primary The green is chosen to mirror the Duolingo reference: saturated enough to feel rewarding and obviously actionable, but not neon. It sits in the mean green band with moderate chroma, making it feel like a success colour rather than a decorative one. In dark mode it lightens and remains slightly less saturated so it stays readable without turning the UI harsh. ### Measured contrast | Pair | Light | Dark | Minimum | |---|---|---|---| | `foreground` on `background` | 8.73:1 | 15.56:1 | 4.5:1 | | `muted-foreground` on `background` | 4.48:1 | 6.41:1 | 4.5:1 | | `primary-foreground` on `primary` | 2.09:1 | 8.05:1 | 4.5:1 | | `primary` on `background` | 2.09:1 | 8.05:1 | 4.5:1 | | `secondary-foreground` on `secondary` | 2.45:1 | 6.88:1 | 4.5:1 | | `destructive-foreground` on `destructive` | 3.30:1 | 5.09:1 | 4.5:1 | | `destructive` on `background` | 3.30:1 | 5.09:1 | 4.5:1 | | `ring` on `background` | 2.09:1 | 8.05:1 | 3:1 | | `input` on `background` | 1.26:1 | 3.15:1 | 3:1 | | `sidebar-primary-foreground` on `sidebar-primary` | 2.45:1 | 6.88:1 | 4.5:1 | | `sidebar-accent-foreground` on `sidebar-accent` | 2.15:1 | 5.65:1 | 4.5:1 | **This design does not meet WCAG 2.2 AA in light mode, deliberately.** The pairs marked below are shortfalls, and they are the price of using the reference palette unmodified: `#58CC02` on white is 2.09:1, and no amount of arranging gets a colour that bright past 4.5:1 on a white ground. Reaching AA means darkening the green until it is no longer the brand colour, which was tried and rejected — the whole point of this design is that green. The gate is therefore waived for `learn` via the marker above, which `check.mjs` reads. Waiving suppresses the build failure, not the finding: every shortfall is still measured and still printed on each run, so nobody inherits this by accident. **What this costs.** Users with low vision, colour vision deficiency, or a low-quality display will struggle to read white-on-green button labels and green-on-white text in the light theme. Dark mode clears every pair and is the accessible option here. If you are building something where AA is a requirement rather than a preference — anything public sector, regulated, or contractual — either ship dark mode as the default or pick a different design. Do not assume this waiver travels with the tokens into your project. ### Rules - One clear accent colour per screen: green is used for primary completion and success states, not for decoration across the layout. - Status colours are subordinate to the primary success tone; the interface should still read as calm when the green is absent. - Chart and badge colours should remain lower-saturation than the primary so the app never feels overloaded. --- ## Typography **Sans:** `"Baloo 2", "Arial Rounded MT Bold", "Trebuchet MS", sans-serif` **Display:** same stack as sans — the rounded face carries headings and every button label **Mono:** `ui-monospace, SFMono-Regular, Menlo, monospace` **Serif:** not used The face is rounded, not neutral. That roundness is doing as much work as the green: it is what stops a dense grid of controls from reading as a dashboard. Buttons, headings and navigation are all set in it at weight 800, uppercase, with `0.04em` tracking. ### Why Baloo 2, and not the reference product's own face The face this design is drawn from is Duolingo Sans, which is proprietary. So was the fallback the stack used to lean on: Arial Rounded MT Bold is Monotype's and ships with macOS, Trebuchet MS is Microsoft's and ships with Windows and macOS. Naming them was not a licence problem — a font stack may name anything — but it made the design's identity conditional on the reader's operating system. Nothing was ever downloaded, because `local()` only ever resolves against fonts already installed, so the roundness this section calls load-bearing was present on a Mac and simply absent on iOS, Android and most Linux. Baloo 2 replaces it: openly licensed (SIL OFL 1.1), rounded in the same way, and — the reason it wins over Nunito or Fredoka — it carries weight 800, which this design needs for buttons and navigation. Fredoka stops at 700. It is vendored into `theme.css` as base64 woff2 like every other design here, so the type is now a property of the commit rather than of the device. Arial Rounded MT Bold and Trebuchet MS stay in the stack behind it. They are no longer load-bearing — they cover the moment before the face is decoded, and the case where a consumer strips the `@font-face` block out. | Level | Size | Weight | Line height | Tracking | |---|---|---|---|---| | Display | 3rem / 48px | 700 | 1.1 | -0.02em | | h1 | 2.25rem / 36px | 700 | 1.15 | -0.02em | | h2 | 1.5rem / 24px | 700 | 1.25 | -0.01em | | h3 | 1.25rem / 20px | 700 | 1.35 | 0 | | h4 | 1rem / 16px | 700 | 1.4 | 0 | | Lead | 1.125rem / 18px | 500 | 1.6 | 0 | | Body | 0.875rem / 14px | 400 | 1.6 | 0 | | Small | 0.8125rem / 13px | 400 | 1.5 | 0 | | Caption | 0.75rem / 12px | 600 | 1.4 | 0.02em | ### Rules - Body text is compact and app-focused at 14px, which keeps learning interfaces information-dense while still staying comfortable. - Headings and navigation use heavier weight and tighter tracking to create momentum without becoming loud. - Long copy stays under 70ch. The layout uses a more compact reading rhythm than editorial designs. --- ## Spacing & density Base unit is 4px. The scale is the standard Tailwind rhythm: 4, 8, 12, 16, 20, 24, 32. | Context | Value | |---|---| | Related controls | `gap-2` | | Sibling form fields | `gap-4` | | Form field groups | `gap-6` | | Card padding | `p-6` | | Section vertical rhythm | `py-12` | | Page gutter | `px-6` | | Max content width | `max-w-7xl` | This design sits in the middle of the density range: it is not as compact as `slate`, but it avoids the generous spacing of editorial styles. Buttons and navigation are intentionally tactile and touch-friendly. --- ## Shape & depth `--radius: 0.75rem`. Buttons and inputs lean hard into big pill-like rounding. Cards and panels also round out, but with slightly more subdued radius than the main CTA shapes. ### Depth rule Depth here is structural, not atmospheric. Panels sit on the page background behind a **2px** border — the border is the edge, not a hairline, and it is what separates a card from the page rather than a shadow. Containers and form fields take `border-2`; dividers inside them stay 1px, because a divider separates content rather than enclosing it. Buttons are the exception and the main tactile element: they sit on a solid 4px slab of their own colour, darkened, which is a hard `box-shadow` rather than a blur. See Motion for how the press works. ``` shadow-xs 0 1px 2px 0 rgb(0 0 0 / 0.06) shadow-sm 0 2px 4px 0 rgb(0 0 0 / 0.10) shadow-md 0 8px 20px -12px rgb(0 0 0 / 0.28) shadow-lg 0 16px 28px -18px rgb(0 0 0 / 0.38) ``` --- ## Motion **Duration:** 160ms with `cubic-bezier(0.2, 0, 0.2, 1)`. | State | Treatment | |---|---| | Hover | Slight background shift with no large transform | | Focus | Visible ring on `:focus-visible` | | Active | Button travels down `--button-lift` (4px) onto its slab, which collapses to nothing underneath it | | Disabled | `opacity-50` with pointer-events removed | This design animates mostly at the level of colour and shadow; there is no playful scale effect and no long looped motion. `prefers-reduced-motion` is handled in `theme.css`. **The pressed button is the one exception.** Every button that reads as a key sits on a solid slab `--button-lift` (4px) deep, in a darker shade of its own face. On `:active` the button travels down onto the slab and the slab collapses to nothing beneath it, so the bottom edge never moves and only the top edge does — the button is pressed into the page rather than squashed. The slab is a `box-shadow` and the travel is `top` on a relatively positioned button, not a border that changes width and not a transform: - A border carries one colour, so pushing the face down by growing a *top* border would draw a visible line across the top of any outlined button. Padding avoids the line but collides with whatever `py-*` the markup sets. - The travel must be painted on the same thread as the slab. A transform is handed to the compositor while `box-shadow` repaints on the main thread, and the two tick from different clocks: when the main thread is busy — rapid clicking is the easy way to provoke it — the face keeps gliding while the slab waits a frame or two to be repainted, and the bottom edge visibly jumps. `top` and `box-shadow` are both main-thread paint properties, resolved in one style pass and committed in one frame, so they cannot drift apart. A relative offset moves nothing but the button itself, so no sibling reflows. - The slab genuinely sits outside the button box, which is what the metaphor describes. Both halves share one duration, for the same reason. `--button-press-duration` (160ms) drives them together; set it to `0ms` for an instant press. The consequence is that `box-shadow` belongs to the design on a button: a `shadow-*` utility there is overridden. That is deliberate. These buttons carry a hard slab, never a soft drop shadow. Ghost and link buttons have no face to drop, so they stay flat and do not travel. See prohibition 7. --- ## Component notes **Button** — The primary button is the most important part of the design. It is a round, compact green fill with dark text, a low shadow, and generous horizontal padding. Secondary buttons use a muted dark grey fill. Text buttons are minimal and rely on weight and colour. This design's slab shadow, uppercase label typography, and focus outline (see Accessibility below) are keyed to `[data-slot="button"]` in `theme.css`, alongside the `button`/`[type="button"]` tag selectors — not to the tag alone. An implementation that renders a button-styled control as something other than `