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 the3(1rem) or4` (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.

6 KiB Raw Permalink Blame History Unescape Escape