110 lines
5.7 KiB
Markdown
110 lines
5.7 KiB
Markdown
|
# 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.
|