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 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.

5.7 KiB Raw Blame History Unescape Escape