# Design System Document: Language Learning App This document describes the aesthetic look and feel of the language learning app's web interface. ## 1. Overview & Creative North Star **Creative North Star: The Digital Archivist** This design system rejects the frantic, "attention-economy" aesthetic of modern web apps. Instead, it draws inspiration from high-end printed journals and architectural minimalism. The goal is to create a "Digital Paper" experience that honours the act of reading. The app always writes in British, never American English. We break the standard "SaaS dashboard" template by using intentional asymmetry and high-contrast typographic scales. Consider classic, intention grid templates of print, and also the visual Bauhaus aesthetic. Layouts with multiple sources of information should feel like a well-composed magazine spread: large, sweeping areas of `surface` punctuated by tight, authoritative `label` groupings. We do not fill space; we curate it. Layouts which are focused on content, e.g. reading or listening, should feel focused and intentional. --- ## 2. Colours: The Palette of Focus Our palette is rooted in organic, desaturated tones that reduce eye strain and promote deep work. - **Primary (`#516356`)**: A muted Forest Green. This is our singular "Action" voice. Use it sparingly to guide the eye, not to shout. - **The "No-Line" Rule**: You are strictly prohibited from using 1px solid borders to define sections. Layout boundaries are created exclusively through background shifts. For example, a `surface-container-low` (`#f4f4ef`) sidebar sitting against a `surface` (`#faf9f5`) main body. - **Nesting & Layers**: Treat the UI as stacked sheets of fine vellum. Use `surface-container-lowest` (`#ffffff`) for the most elevated elements (like an active reading pane) and `surface-dim` (`#d6dcd2`) for recessed utility areas. - **The "Glass & Gradient" Rule**: To prevent the UI from feeling "dead," use subtle radial gradients on hero backgrounds (transitioning from `surface` to `surface-container-low`). For floating navigation, apply `surface` colors at 80% opacity with a `24px` backdrop-blur to create a "frosted glass" effect that lets the content bleed through softly. --- ## 3. Typography: The Editorial Engine Typography is the primary visual asset. We use a sophisticated pairing of **Archivo** (Sans-serif) for functional UI and **Newsreader** (Serif) for the reading experience. - **Display & Headline (Archivo)**: (`--font-display`) These are your "Wayfinders." Use `display-lg` (3.5rem) with tight letter-spacing for article titles to create an authoritative, architectural feel. - **Body (Newsreader)**: (`--font-body`) This is the soul of the system. `body-lg` (1rem) is the standard for long-form reading. It must have a line-height of at least 1.6 to ensure the "Digital Paper" feel. - **Labels (Inter)**: (`--font-label`) Use `label-md` in all-caps with a `0.05rem` letter-spacing for metadata (e.g., "READING TIME," "DATE SAVED"). This creates a stark, functional contrast to the fluid Serif body text. --- ## 4. Elevation & Depth: Tonal Layering We do not use shadows to mimic light; we use tone to mimic physical presence. - **The Layering Principle**: If a card needs to stand out, do not add a shadow. Instead, change its background to `surface-container-lowest` and place it on a `surface-container` background. The 2-step tonal shift provides all the clarity needed. - **Ambient Shadows**: If a component _must_ float (like a mobile action button), use a "Tonal Shadow": `color: on-surface` at 5% opacity, with a `32px` blur and `8px` Y-offset. It should look like a soft smudge of graphite, not a digital drop shadow. - **The "Ghost Border"**: If a button needs a stroke for accessibility, use `outline-variant` (`#afb3ac`) at 20% opacity. If you can see the line clearly, it’s too dark. --- ## 5. Components: Functional Minimalism ### Buttons - **Primary**: Background `primary` (`#516356`), text `on_primary` (`#e9fded`). Corner radius `md` (`0.375rem`). No border. - **Secondary**: Background `secondary_container` (`#dde4de`), text `on_secondary_container`. - **Tertiary/Ghost**: No background. Text `primary`. Use only `label-md` typography. ### Input Fields - **Style**: Forgo the "box" look. Use a `surface-container-high` background with a bottom-only "Ghost Border." - **States**: On focus, the bottom border transitions to `primary` (`#516356`) with a width of 2px. ### Cards & Lists - **The "No-Divider" Rule**: Forbid the use of horizontal rules (` `). Separate list items using the`3`(1rem) or`4` (1.4rem) spacing tokens. - **Structure**: Group items using subtle background shifts. An active list item should move from `surface` to `surface-container-lowest`. ### The "Reading Progress" Component (System Specific) - A thin, 2px bar using `primary` that sits at the very top of the viewport. As the user scrolls, it grows. No container or background for the bar—it should look like a thread laying on the paper. --- ## 6. Do’s and Don’ts ### Do - **Do** use asymmetrical margins. For example, give the main text column a 20% left margin and a 30% right margin to create a sophisticated, editorial layout. - **Do** use design tokens and CSS Custom Properties (variables) - **Do** extract re-usable components into `app.css` so that styles can be used in multiple page. - **Do** prioritize the `16` (5.5rem) spacing token for top-of-page "breathability." - **Do** use `primary_container` for subtle highlighting of text within an article. - **Do** create responsive layouts, preferably using @container queries. ### Don’t - **Don’t** use pure black `#000000`. Use `on_surface` (`#2f342e`) for all high-contrast text. - **Don’t** use icons unless absolutely necessary. Prefer text labels (`label-md`) to ensure the "Digital Paper" aesthetic remains unbroken. - **Don’t** use "Pop-up" modals that cover the whole screen. Use "Slide-over" panels that use the `surface-container-highest` tone to maintain the sense of a physical stack. - **Don't** Over-use utility classes.