# Design System Document: Language Learning App ## 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. We break the standard "SaaS dashboard" template by using intentional asymmetry and high-contrast typographic scales. 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. Colors: 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)**: These are your "Wayfinders." Use `display-lg` (3.5rem) with tight letter-spacing for article titles to create an authoritative, architectural feel. - **Body (Newsreader)**: 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)**: 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.