From 0c8c5c00e435fedff4f81e36d603424c153519a9 Mon Sep 17 00:00:00 2001 From: Breadway Date: Tue, 16 Jun 2026 17:07:03 +0800 Subject: [PATCH] docs: ecosystem overview, keybinds, shared-theming, design system README: add recommended keybinds and a Theming section documenting the bread-theme generator + live-reloaded shared stylesheet. Add BREAD_DESIGN_SYSTEM.md to the repo (the README links it) and update it to describe the single-source-of-truth architecture and the migrated apps (incl. bos-settings). Co-Authored-By: Claude Opus 4.8 --- BREAD_DESIGN_SYSTEM.md | 118 +++++++++++++++++++++++++++++++++++++++++ README.md | 30 +++++++++++ 2 files changed, 148 insertions(+) create mode 100644 BREAD_DESIGN_SYSTEM.md diff --git a/BREAD_DESIGN_SYSTEM.md b/BREAD_DESIGN_SYSTEM.md new file mode 100644 index 0000000..942f7a2 --- /dev/null +++ b/BREAD_DESIGN_SYSTEM.md @@ -0,0 +1,118 @@ +# Bread Design System + +Unified visual identity for breadbar, breadbox, breadpad/breadman, and +bos-settings. + +## Architecture (single source of truth) + +The tokens below are implemented once in the **`bread-theme`** crate as +`stylesheet(&Palette)` — the full component stylesheet (buttons, entries, +switches, lists/rows/sidebars, cards, chips, scrollbars, headings) over a +canonical `@define-color` palette (`surface`=color0, `overlay`=color7, +`accent`=color4). + +- The `bread-theme` **CLI** renders it from the live pywal palette to + `$XDG_RUNTIME_DIR/bread/theme.css` (run at login and from a pywal hook). +- Every GUI loads that file via `bread_theme::gtk::apply_shared()` and + **live-reloads** it, then layers on only its own app-specific rules. + +Result: one definition, no per-app drift, and palette changes recolour the +whole desktop with no rebuilds. Apps reference the shared `@define-color` +names rather than raw palette slots. + +## Typography + +- **Font Family**: Varela Round, sans-serif +- **Base Size**: 14px +- **Secondary**: 12px (metadata, helper text, secondary labels) +- **Font Weight**: Normal (400) for body, Bold (700) for emphasis + +## Spacing Scale (4px units) + +Use these values consistently across all projects: + +- **xs**: 4px (small gaps, internal padding) +- **sm**: 8px (default spacing between elements) +- **md**: 12px (medium spacing, main padding) +- **lg**: 16px (large padding, major spacing) +- **xl**: 20px (extra large spacing, section breaks) + +## Border Radius + +Establish a visual hierarchy with consistent rounding: + +- **Primary** (buttons, cards, main containers): **8px** +- **Secondary** (input fields, chips, entries): **6px** +- **Tertiary** (small interactive elements): **4px** +- **Pill** (fully rounded buttons, badges): **999px** + +## Color System + +All projects use **pywal dynamic theming** with **Catppuccin Mocha** as the fallback palette: + +- **Background**: `#1e1e2e` (Catppuccin) +- **Foreground**: `#cdd6f4` (Catppuccin) +- **Surface**: `#181825` (Catppuccin) +- **Accent**: Dynamic (from pywal) + +Color palette slots (via wal): +- color0–color7: ANSI colors +- Semantic: red, green, yellow, blue, pink, teal + +## Component Standards + +### Buttons +- Border Radius: 8px +- Padding: 8px 16px (primary), 4px 8px (secondary) +- Font Size: 14px +- Background: Theme accent color + +### Input Fields +- Border Radius: 6px +- Padding: 12px 16px +- Font Size: 14px +- Border: 1px or 2px solid (blue on focus) + +### Cards +- Border Radius: 8px +- Padding: 12px +- Margin: 8px +- Box Shadow: Optional, for depth + +### Stat Labels +- Font Size: 14px +- Margin Right (between icon/text): 5px +- Group Margin Right: 12px + +### Notification Cards +- Border Radius: 8px +- Padding: 12px +- Margin Bottom: 8px +- Font Size: 14px (summary), 12px (body) + +## Current Implementation + +All GUI apps load `bread_theme::stylesheet` (via the generated shared file) and +add only app-specific rules: + +- **breadbar** — shared base + bar window, workspace buttons, stats, notification + and OSD cards. +- **breadbox** — shared base + launcher panel, search entry, result rows. +- **breadpad / breadman** — shared base + capture popup, type chips, note cards, + reminder window, sidebar rows. +- **bos-settings** — shared base + content padding only (was previously a + hardcoded Nord palette; migrated to the shared stylesheet). +- **breadcrumbs** — CLI tool; ANSI colours only, no GUI styling. + +> Palette note: the fallback is Catppuccin Mocha, but installs (e.g. BOS) drive +> the real palette from pywal — BOS ships a black-base palette. + +## Future Consistency Checks + +When adding new components or updating existing ones: +1. Use Varela Round for all text +2. Set base font size to 14px (12px for secondary) +3. Use spacing scale (4px units: 4, 8, 12, 16, 20) +4. Use border radius from this system (8px default, 6px secondary) +5. Leverage pywal colors for dynamic theming +6. Keep margins/padding consistent across similar components diff --git a/README.md b/README.md index 405c193..1ec4cff 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,36 @@ bakery install breadbar | `breadcrumbs` | Profile-aware Wi-Fi state machine with Tailscale exit-node management and a self-healing watch daemon | | `breadpad` | Quick-capture scratchpad popup with AI-powered note classification, reminders, recurrence, and a full note viewer (`breadman`) | +## Recommended keybinds + +The ecosystem assumes a Hyprland setup with `SUPER` as the modifier. The +conventional bindings (used by BOS and recommended for any install): + +| Keys | Action | +|------|--------| +| `SUPER+Space` | `breadbox` — app launcher | +| `SUPER+U` | `breadpad` — quick-capture notes/reminders | +| `SUPER+M` | `breadman` — note viewer / manager | +| `SUPER+,` | settings (`bos-settings`, where installed) | + +`breadbar` and `breadd` are services started at login (`exec-once`), not bound +to keys. + +## Theming + +All GUIs share one look via `bread-theme`. The `bread-theme` CLI renders the +component stylesheet from your pywal palette (Catppuccin Mocha fallback) to +`$XDG_RUNTIME_DIR/bread/theme.css`; every app loads that file and **live-reloads** +it, so changing your wallpaper recolours the whole ecosystem with no rebuilds: + +```sh +wal -i ~/Pictures/wall.png # regenerate pywal palette +bread-theme generate # render the shared stylesheet (run from a wal hook) +``` + +See [`BREAD_DESIGN_SYSTEM.md`](BREAD_DESIGN_SYSTEM.md) for the tokens (fonts, +spacing, radii, colour roles) the stylesheet is built from. + ## Installing bakery `bakery` is the package manager for the ecosystem. Install it with the bootstrap script: