lashman/driftwood
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
7e55d5796f2b332a2abcbcbf4e5f29a844c82170
driftwood/docs/plans/2026-02-27-beginner-friendly-copy-design.md
lashman c9c9c0341b Rewrite detail view copy for beginners, add tab transitions and lightbox fixes 
- Replace technical jargon with plain language across all 4 detail tabs
- Friendly titles/subtitles with technical details available in tooltips
- Soften terminal commands ("Install with one command" instead of raw commands)
- Rename sections: Desktop Integration -> App Menu, Sandboxing -> App Isolation,
  Vulnerability Scanning -> Security Check, Capabilities -> Features
- Rewrite Wayland/FUSE explanations to avoid acronyms and dev terminology
- Update security report page with beginner-friendly descriptions
- Enable libadwaita 1.7 ViewStack crossfade transitions between detail tabs
- Rewrite screenshot lightbox as separate gtk::Window (fixes scroll jump on
  close, adds click-outside-to-close, rounded corners via CSS)
- Add prev/next navigation arrows and keyboard support to lightbox
2026-02-27 19:48:59 +02:00

8.6 KiB
Raw Blame History

Beginner-Friendly Copy Overhaul - Design

Goal: Rewrite all technical jargon in the detail view into plain language that newcomers can understand, while keeping technical details available in tooltips.

Approach: Friendly titles/subtitles for everyone, technical details on hover. Terminal commands stay copyable but with softer framing ("Install with one command" instead of showing the raw command as a subtitle).

Scope: detail_view.rs (all 4 tabs), security_report.rs, fuse_user_explanation(), wayland_user_explanation()

Overview Tab

About section

  • "SPDX license identifier for this application" tooltip -> "The license that governs how this app can be used and shared."
  • "Project group" title -> "Project"
  • "Bug tracker" link label -> "Report a problem"

File Information section

  • "AppImage format" title -> "Package format"
  • "Type 1 (ISO 9660) - older format, still widely supported" -> "Type 1 - older format, still widely supported"
  • "Type 2 (SquashFS) - modern format, most common today" -> "Type 2 - modern, compressed format"
  • Tooltip rewrite: "AppImages come in two formats. Type 1 is the older format. Type 2 is the current standard - it uses compression for smaller files and faster loading."
  • "Executable" title -> "Ready to run"
  • "Yes - this file has execute permission" -> "Yes - this file is ready to launch"
  • "No - execute permission is missing. It will be set automatically when launched." -> "No - will be fixed automatically when launched"
  • Tooltip: "Whether the file has the permissions needed to run. If not, Driftwood sets this up automatically the first time you launch it."
  • "This AppImage contains a GPG signature" subtitle -> "Signed by the developer"
  • Signature tooltip: "This app was signed by its developer, which helps verify it hasn't been tampered with since it was published."
  • "Last scanned" -> "Last checked"

Capabilities section

  • Section title: "Capabilities" -> "Features"
  • "Desktop actions" -> "Quick actions"
  • Tooltip: "Additional actions available from the right-click menu when this app is added to your app menu."
  • Content rating tooltip: "An age rating for the app's content, similar to game ratings."

Updates section

  • Tooltip about zsync/delta updates -> "Driftwood can check for newer versions of this app automatically. The developer has included information about where updates are published."

System Tab

Desktop Integration section

  • Section title: "Desktop Integration" -> "App Menu"
  • Description -> "Add this app to your launcher so you can find it like any other installed app."
  • Switch subtitle: "Creates a .desktop entry and installs the app icon" -> "Creates a shortcut and installs the app icon"
  • Switch tooltip: "This makes the app appear in your Activities menu and app launcher, just like a regular installed app. It creates a shortcut file and copies the app's icon to your system."
  • "Desktop file" row title -> "Shortcut file"

Compatibility section

  • Description -> "How well this app works with your system. Most issues can be fixed with a quick install."
  • "Wayland display" -> "Display compatibility"
  • Wayland tooltip: "Wayland is the modern display system on Linux. Apps built for the older system (X11) still work, but native Wayland apps look sharper, especially on high-resolution screens."
  • "Analyze toolkit" -> "Detect app framework"
  • Subtitle: "Inspect bundled libraries to detect which UI toolkit this app uses" -> "Check which technology this app is built with"
  • Tooltip: "Apps are built with different frameworks (like GTK, Qt, or Electron). Knowing the framework helps predict how well the app works with your display system."
  • Post-analysis subtitle: "Detected: {toolkit} ({count} libraries scanned)" -> "Built with: {toolkit}"
  • Error subtitle: "Analysis failed - the AppImage may not be mountable" -> "Analysis failed - could not read the app's contents"
  • "Last observed protocol" -> "Last display mode"
  • Tooltip: "How the app connected to your display the last time it was launched."
  • "FUSE (filesystem)" -> "App mounting"
  • FUSE tooltip: "FUSE lets apps like AppImages run directly without unpacking first. Without it, apps still work but take a little longer to start."
  • "Launch method" -> "Startup method"
  • Launch tooltip: "AppImages can start two ways: mounting (fast, instant startup) or unpacking to a temporary folder first (slower, but works everywhere). The method is chosen automatically based on your system."

Wayland explanations (wayland_user_explanation)

  • Native: "Fully compatible - the best experience on your system."
  • XWayland: "Works through a compatibility layer. May appear slightly blurry on high-resolution screens."
  • Possible: "Might work well. Try launching it to find out."
  • X11Only: "Built for an older display system. It will run automatically, but you may notice minor visual quirks."
  • Unknown: "Not yet determined. Launch the app or use 'Detect app framework' to check."

FUSE explanations (fuse_user_explanation)

  • FullyFunctional: "Everything is set up - apps start instantly."
  • Fuse3Only: "A small system component is missing. Most apps will still work, but some may need it. Copy the install command to fix this."
  • NoFusermount: "A system component is missing, so apps will take a little longer to start. They'll still work fine."
  • NoDevFuse: "Your system doesn't support instant app mounting. Apps will unpack before starting, which takes a bit longer."
  • MissingLibfuse2: "A small system component is needed for fast startup. Copy the install command to fix this."

Sandboxing section

  • Section title: "Sandboxing" -> "App Isolation"
  • Description -> "Restrict what this app can access on your system for extra security."
  • Switch title: "Firejail sandbox" -> "Isolate this app"
  • Switch tooltip: "Sandboxing restricts what an app can access - files, network, devices, etc. Even if an app has a security issue, it can't freely access your personal data."
  • Subtitle when available: "Isolate this app using Firejail. Current mode: {mode}" -> "Currently: {mode}"
  • Subtitle when missing: "Firejail is not installed. Use the row below to copy the install command." -> "Not available yet. Install with one command using the button below."
  • Install row: "Install Firejail" / "sudo apt install firejail" -> "Install app isolation" / "Install with one command"

Security Tab

Vulnerability Scanning section

  • Section title: "Vulnerability Scanning" -> "Security Check"
  • Description -> "Check this app for known security issues."
  • "Bundled libraries" -> "Included components"
  • Subtitle: "{N} libraries detected inside this AppImage" -> "{N} components found inside this app"
  • Tooltip: "Apps bundle their own copies of system components (libraries). These can sometimes contain known security issues if they're outdated."
  • Clean subtitle: "No known security issues found in the bundled libraries." -> "No known security issues found."
  • Scan row: "Run security scan" / "Check bundled libraries against known CVE databases" -> "Run security check" / "Check for known security issues in this app"
  • Scan tooltip: "This checks the components inside this app against a public database of known security issues to see if any are outdated or vulnerable."
  • Error: "Scan failed - the AppImage may not be mountable" -> "Check failed - could not read the app's contents"

Integrity section

  • "SHA256 checksum" -> "File fingerprint"
  • Tooltip: "A unique code (SHA256 checksum) generated from the file's contents. If the file changes in any way, this code changes too. You can compare it against the developer's published fingerprint to verify nothing was altered."

Storage Tab

  • Group description: "Config, cache, and data directories this app may have created." -> "Settings, cache, and data this app may have saved to your system."
  • Search subtitle: "Search for config, cache, and data directories" -> "Search for files this app has saved"
  • Empty result: "No associated data directories found" -> "No saved data found"
  • "Path" -> "File location"

Security Report page (security_report.rs)

  • "Run a security scan to check bundled libraries for known vulnerabilities." -> "Run a security check to look for known issues in your apps."
  • "No known vulnerabilities found in any bundled libraries." -> "No known security issues found in any of your apps."
  • "Overall security status across all AppImages" -> "Overall security status across all your apps"
  • Tooltip: "Common Vulnerabilities and Exposures found in bundled libraries" -> "Known security issues found in the components bundled inside your apps."
  • Per-app description: "{N} CVE (vulnerability) records found" -> "{N} known security issues found"
  • Individual CVE/library expander titles: keep as-is (technical detail layer)
Reference in New Issue View Git Blame Copy Permalink