@fragment-build/ui 3.2.3 → 3.3.0

package/README.md

@@ -28,6 +28,8 @@ Fragment UI is a design system and React component library which provides alread
 - [🔧 Configuration](#-configuration)
     - [`linkComponent`](#linkcomponent)
   - [Next.js 13+](#nextjs-13)
+- [🎨 Theming](#-theming)
+  - [Fragment surfaces](#fragment-surfaces)
 - [🤝 Contributing](#-contributing)
 - [👨‍💻 Development](#-development)
 - [🤝 Community support](#-community-support)
@@ -179,6 +181,77 @@ import { ThemeSwitch } from '@fragment-build/ui';
 <ThemeSwitch />
 ```
 
+## 🎨 Theming
+
+Fragment UI builds on the [HeroUI theme tokens](https://v3.heroui.com/docs/react/getting-started/theming).
+Override any of them in your own stylesheet — see [`theme.example.css`](src/theme.example.css)
+for the full list. Import Fragment UI first, then declare your overrides: both blocks are
+unlayered and equally specific, so the later one wins.
+
+```css
+@import 'tailwindcss';
+@import "@heroui/styles";
+@import "@fragment-build/ui";
+
+:root,
+.light,
+[data-theme="light"] {
+  --accent: #F56460;
+}
+```
+
+### Fragment surfaces
+
+The `Sidebar` and `Navbar` fragments paint their own surface so they can be themed
+independently of the page. Each defaults to the page surface, so a theme that declares none of
+these renders exactly as it did before.
+
+| Token | Default | Applies to |
+| --- | --- | --- |
+| `--sidebar` | `var(--background)` | Sidebar rail (collapsed + expanded) and its mobile bottom nav |
+| `--sidebar-foreground` | `var(--foreground)` | Text, icons and tree guides inside the rail |
+| `--navbar` | `var(--background)` | Navbar topbar and its mobile bottom nav |
+| `--navbar-foreground` | `var(--foreground)` | Text and icons inside the navbar |
+
+A tinted rail on a white page:
+
+```css
+:root,
+.light,
+[data-theme="light"] {
+  --sidebar: #F7F5F0;
+}
+```
+
+They are also available as Tailwind utilities — `bg-sidebar`, `text-sidebar-foreground`,
+`bg-navbar`, `text-navbar-foreground` — so you can reuse the same surface in your own markup.
+
+#### Contrasting rails
+
+The interactive states inside the rail are page-level palette roles, not sidebar roles, and
+they do **not** follow `--sidebar` on their own. The active nav pill (`--accent-soft`) is
+translucent, so it composites over whatever the rail is painted and needs nothing. The other
+two do, once the rail contrasts noticeably with the page:
+
+| Token | Default | Controls |
+| --- | --- | --- |
+| `--sidebar-default` | `var(--default)` | Hover ground of collapsible nav groups |
+| `--sidebar-accent-soft-foreground` | `var(--accent-soft-foreground)` | Ink of the active nav item and active group |
+
+A dark rail on a light page:
+
+```css
+:root,
+.light,
+[data-theme="light"] {
+  --sidebar: oklch(21% 0.006 285.89);
+  --sidebar-foreground: oklch(99.11% 0 0);
+
+  --sidebar-default: rgba(255, 255, 255, 0.08);
+  --sidebar-accent-soft-foreground: color-mix(in oklab, var(--accent) 70%, var(--sidebar-foreground) 30%);
+}
+```
+
 ## 🤝 Contributing
 
 Feel free to fork and make a Pull Request to this project. All the input is warmly welcome!

package/fragments/navbar/navbar.css

@@ -1,6 +1,6 @@
 @layer components {
   .fragment-navbar__topbar {
-    @apply flex gap-6 items-center px-8 py-5;
+    @apply flex gap-6 items-center px-8 py-5 bg-navbar text-navbar-foreground;
   }
 
   .fragment-navbar__tabs {
@@ -12,7 +12,7 @@
   }
 
   .fragment-navbar__bottom-nav {
-    @apply fixed md:hidden z-50 bottom-0 bg-background flex w-full gap-2 px-2 py-1 border-t border-border;
+    @apply fixed md:hidden z-50 bottom-0 bg-navbar text-navbar-foreground flex w-full gap-2 px-2 py-1 border-t border-border;
     & > *,
     & > * > * {
       @apply h-12 flex-1;

package/fragments/sidebar/sidebar.css

@@ -4,7 +4,8 @@
   }
 
   .fragment-sidebar__collapsed {
-    @apply fixed top-0 left-0 border-r border-border flex flex-col h-screen gap-8 transition-all;
+    @apply fixed top-0 left-0 border-r border-border bg-sidebar text-sidebar-foreground
+           flex flex-col h-screen gap-8 transition-all;
   }
 
   .fragment-sidebar__collapsed-body {
@@ -16,7 +17,8 @@
   }
 
   .fragment-sidebar__expanded {
-    @apply fixed top-0 left-0 border-r border-border flex flex-col h-screen gap-8 overflow-hidden transition-all;
+    @apply fixed top-0 left-0 border-r border-border bg-sidebar text-sidebar-foreground
+           flex flex-col h-screen gap-8 overflow-hidden transition-all;
   }
 
   .fragment-sidebar__expanded-body {
@@ -40,7 +42,7 @@
   }
 
   .fragment-sidebar__bottom-nav {
-    @apply fixed md:hidden z-50 bottom-0 bg-background flex w-full gap-2 px-2 py-1 border-t border-border;
+    @apply fixed md:hidden z-50 bottom-0 bg-sidebar text-sidebar-foreground flex w-full gap-2 px-2 py-1 border-t border-border;
     & > *:nth-child(n+5):not(:last-child) {
       @apply hidden;
     }
@@ -121,9 +123,10 @@
 
   .fragment-sidebar__accordion-trigger {
     @apply w-full flex items-center gap-3 h-10 px-3 pr-1 py-1 rounded-2xl text-sm font-normal cursor-pointer
-           text-foreground transition-colors;
+           text-sidebar-foreground transition-colors;
     &:hover, &[data-hovered="true"] {
-      @apply bg-default!;
+      /* `--default` is a page-level palette colour; opt out per-rail with `--sidebar-default`. */
+      background-color: var(--sidebar-default, var(--default)) !important;
     }
     & > .fragment-sidebar__accordion-label {
       @apply flex-1 text-left;
@@ -131,7 +134,7 @@
   }
 
   .fragment-sidebar__accordion-trigger--active {
-    @apply text-accent-soft-foreground;
+    color: var(--sidebar-accent-soft-foreground, var(--accent-soft-foreground));
   }
 
   .fragment-sidebar__accordion-trigger .accordion__indicator {
@@ -149,7 +152,7 @@
     @apply relative pl-7;
     &::before {
       content: '';
-      @apply absolute top-0 bottom-0 w-px bg-foreground opacity-15 rounded-full left-5;
+      @apply absolute top-0 bottom-0 w-px bg-sidebar-foreground opacity-15 rounded-full left-5;
     }
     .list-box {
       @apply overflow-visible;
@@ -157,14 +160,16 @@
   }
 
   .fragment-sidebar__nav-item--active {
-    @apply bg-accent-soft! text-accent-soft-foreground!;
+    /* `--accent-soft` is translucent, so it composites over the rail, not the page. */
+    @apply bg-accent-soft!;
+    color: var(--sidebar-accent-soft-foreground, var(--accent-soft-foreground)) !important;
   }
 
   .fragment-sidebar__sub-item {
     @apply pl-8! relative;
     &::before {
       content: '';
-      @apply absolute -left-3 ml-px top-1/2 -translate-y-1/2 w-3 h-px bg-foreground opacity-15;
+      @apply absolute -left-3 ml-px top-1/2 -translate-y-1/2 w-3 h-px bg-sidebar-foreground opacity-15;
     }
   }
 

package/index.css

@@ -3,6 +3,21 @@
   --text-sm: 15px;
 }
 
+/*
+ * Fragment surface roles.
+ *
+ * `inline` so the utilities compile to `var(--sidebar)` / `var(--navbar)` and are
+ * therefore resolved on the element, not frozen at `:root`. Each falls back to the
+ * page role, so a theme that never declares them renders exactly as before.
+ */
+@theme inline {
+  --color-sidebar: var(--sidebar, var(--background));
+  --color-sidebar-foreground: var(--sidebar-foreground, var(--foreground));
+
+  --color-navbar: var(--navbar, var(--background));
+  --color-navbar-foreground: var(--navbar-foreground, var(--foreground));
+}
+
 @layer base {
   body {
     @apply bg-background text-foreground;
@@ -137,6 +152,12 @@
   --background: #fff;
   --border: rgba(0, 0, 0, 0.07);
   --surface-secondary: rgba(0, 0, 0, 0.02);
+
+  /* Fragment surfaces: default to the page surface */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
 }
 
 .dark,
@@ -146,6 +167,12 @@
   --foreground: var(--snow);
   --border: rgba(255, 255, 255, 0.07);
   --surface-secondary: rgba(255, 255, 255, 0.02);
+
+  /* Fragment surfaces: default to the page surface */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
 }
 
 /* @import "./theme.example.css"; */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragment-build/ui",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/fragments/navbar/navbar.css

@@ -1,6 +1,6 @@
 @layer components {
   .fragment-navbar__topbar {
-    @apply flex gap-6 items-center px-8 py-5;
+    @apply flex gap-6 items-center px-8 py-5 bg-navbar text-navbar-foreground;
   }
 
   .fragment-navbar__tabs {
@@ -12,7 +12,7 @@
   }
 
   .fragment-navbar__bottom-nav {
-    @apply fixed md:hidden z-50 bottom-0 bg-background flex w-full gap-2 px-2 py-1 border-t border-border;
+    @apply fixed md:hidden z-50 bottom-0 bg-navbar text-navbar-foreground flex w-full gap-2 px-2 py-1 border-t border-border;
     & > *,
     & > * > * {
       @apply h-12 flex-1;

package/src/fragments/sidebar/sidebar.css

@@ -4,7 +4,8 @@
   }
 
   .fragment-sidebar__collapsed {
-    @apply fixed top-0 left-0 border-r border-border flex flex-col h-screen gap-8 transition-all;
+    @apply fixed top-0 left-0 border-r border-border bg-sidebar text-sidebar-foreground
+           flex flex-col h-screen gap-8 transition-all;
   }
 
   .fragment-sidebar__collapsed-body {
@@ -16,7 +17,8 @@
   }
 
   .fragment-sidebar__expanded {
-    @apply fixed top-0 left-0 border-r border-border flex flex-col h-screen gap-8 overflow-hidden transition-all;
+    @apply fixed top-0 left-0 border-r border-border bg-sidebar text-sidebar-foreground
+           flex flex-col h-screen gap-8 overflow-hidden transition-all;
   }
 
   .fragment-sidebar__expanded-body {
@@ -40,7 +42,7 @@
   }
 
   .fragment-sidebar__bottom-nav {
-    @apply fixed md:hidden z-50 bottom-0 bg-background flex w-full gap-2 px-2 py-1 border-t border-border;
+    @apply fixed md:hidden z-50 bottom-0 bg-sidebar text-sidebar-foreground flex w-full gap-2 px-2 py-1 border-t border-border;
     & > *:nth-child(n+5):not(:last-child) {
       @apply hidden;
     }
@@ -121,9 +123,10 @@
 
   .fragment-sidebar__accordion-trigger {
     @apply w-full flex items-center gap-3 h-10 px-3 pr-1 py-1 rounded-2xl text-sm font-normal cursor-pointer
-           text-foreground transition-colors;
+           text-sidebar-foreground transition-colors;
     &:hover, &[data-hovered="true"] {
-      @apply bg-default!;
+      /* `--default` is a page-level palette colour; opt out per-rail with `--sidebar-default`. */
+      background-color: var(--sidebar-default, var(--default)) !important;
     }
     & > .fragment-sidebar__accordion-label {
       @apply flex-1 text-left;
@@ -131,7 +134,7 @@
   }
 
   .fragment-sidebar__accordion-trigger--active {
-    @apply text-accent-soft-foreground;
+    color: var(--sidebar-accent-soft-foreground, var(--accent-soft-foreground));
   }
 
   .fragment-sidebar__accordion-trigger .accordion__indicator {
@@ -149,7 +152,7 @@
     @apply relative pl-7;
     &::before {
       content: '';
-      @apply absolute top-0 bottom-0 w-px bg-foreground opacity-15 rounded-full left-5;
+      @apply absolute top-0 bottom-0 w-px bg-sidebar-foreground opacity-15 rounded-full left-5;
     }
     .list-box {
       @apply overflow-visible;
@@ -157,14 +160,16 @@
   }
 
   .fragment-sidebar__nav-item--active {
-    @apply bg-accent-soft! text-accent-soft-foreground!;
+    /* `--accent-soft` is translucent, so it composites over the rail, not the page. */
+    @apply bg-accent-soft!;
+    color: var(--sidebar-accent-soft-foreground, var(--accent-soft-foreground)) !important;
   }
 
   .fragment-sidebar__sub-item {
     @apply pl-8! relative;
     &::before {
       content: '';
-      @apply absolute -left-3 ml-px top-1/2 -translate-y-1/2 w-3 h-px bg-foreground opacity-15;
+      @apply absolute -left-3 ml-px top-1/2 -translate-y-1/2 w-3 h-px bg-sidebar-foreground opacity-15;
     }
   }
 

package/src/index.css

@@ -3,6 +3,21 @@
   --text-sm: 15px;
 }
 
+/*
+ * Fragment surface roles.
+ *
+ * `inline` so the utilities compile to `var(--sidebar)` / `var(--navbar)` and are
+ * therefore resolved on the element, not frozen at `:root`. Each falls back to the
+ * page role, so a theme that never declares them renders exactly as before.
+ */
+@theme inline {
+  --color-sidebar: var(--sidebar, var(--background));
+  --color-sidebar-foreground: var(--sidebar-foreground, var(--foreground));
+
+  --color-navbar: var(--navbar, var(--background));
+  --color-navbar-foreground: var(--navbar-foreground, var(--foreground));
+}
+
 @layer base {
   body {
     @apply bg-background text-foreground;
@@ -137,6 +152,12 @@
   --background: #fff;
   --border: rgba(0, 0, 0, 0.07);
   --surface-secondary: rgba(0, 0, 0, 0.02);
+
+  /* Fragment surfaces: default to the page surface */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
 }
 
 .dark,
@@ -146,6 +167,12 @@
   --foreground: var(--snow);
   --border: rgba(255, 255, 255, 0.07);
   --surface-secondary: rgba(255, 255, 255, 0.02);
+
+  /* Fragment surfaces: default to the page surface */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
 }
 
 /* @import "./theme.example.css"; */

package/src/theme.example.css

@@ -43,6 +43,23 @@
   --surface-tertiary: rgba(0, 0, 0, 0.9);
   --surface-tertiary-foreground: #FCFAF6;
 
+  /*
+   * Fragment surfaces — Sidebar / Navbar.
+   * Omit them and each fragment stays on the page surface, exactly as before.
+   * Set --sidebar to give the rail its own ground; --sidebar-foreground moves the ink with it.
+   */
+  --sidebar: #F7F5F0;
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
+
+  /*
+   * Optional. The states inside the rail are page-level palette roles, so they do not
+   * follow --sidebar on their own. Set these when the rail contrasts with the page.
+   */
+  /* --sidebar-default: rgba(0, 0, 0, 0.04); */
+  /* --sidebar-accent-soft-foreground: color-mix(in oklab, var(--accent) 70%, var(--sidebar-foreground) 30%); */
+
   --success: oklch(73.29% 0.1968 123.30);
   --success-foreground: rgba(0, 0, 0, 0.9);
   --warning: oklch(78.19% 0.1612 44.82);
@@ -91,6 +108,15 @@
   --surface-secondary-foreground: oklch(99.11% 0.0000 24.57);
   --surface-tertiary: oklch(27.21% 0.0000 24.57);
   --surface-tertiary-foreground: oklch(99.11% 0.0000 24.57);
+
+  /* Fragment surfaces — Sidebar / Navbar */
+  --sidebar: oklch(16.00% 0.0000 24.57);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
+
+  /* --sidebar-default: rgba(255, 255, 255, 0.06); */
+  /* --sidebar-accent-soft-foreground: color-mix(in oklab, var(--accent) 80%, var(--sidebar-foreground) 30%); */
   --warning: oklch(82.03% 0.1388 48.83);
   --warning-foreground: oklch(21.03% 0.0059 48.83);
 }

package/theme.example.css

@@ -43,6 +43,23 @@
   --surface-tertiary: rgba(0, 0, 0, 0.9);
   --surface-tertiary-foreground: #FCFAF6;
 
+  /*
+   * Fragment surfaces — Sidebar / Navbar.
+   * Omit them and each fragment stays on the page surface, exactly as before.
+   * Set --sidebar to give the rail its own ground; --sidebar-foreground moves the ink with it.
+   */
+  --sidebar: #F7F5F0;
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
+
+  /*
+   * Optional. The states inside the rail are page-level palette roles, so they do not
+   * follow --sidebar on their own. Set these when the rail contrasts with the page.
+   */
+  /* --sidebar-default: rgba(0, 0, 0, 0.04); */
+  /* --sidebar-accent-soft-foreground: color-mix(in oklab, var(--accent) 70%, var(--sidebar-foreground) 30%); */
+
   --success: oklch(73.29% 0.1968 123.30);
   --success-foreground: rgba(0, 0, 0, 0.9);
   --warning: oklch(78.19% 0.1612 44.82);
@@ -91,6 +108,15 @@
   --surface-secondary-foreground: oklch(99.11% 0.0000 24.57);
   --surface-tertiary: oklch(27.21% 0.0000 24.57);
   --surface-tertiary-foreground: oklch(99.11% 0.0000 24.57);
+
+  /* Fragment surfaces — Sidebar / Navbar */
+  --sidebar: oklch(16.00% 0.0000 24.57);
+  --sidebar-foreground: var(--foreground);
+  --navbar: var(--background);
+  --navbar-foreground: var(--foreground);
+
+  /* --sidebar-default: rgba(255, 255, 255, 0.06); */
+  /* --sidebar-accent-soft-foreground: color-mix(in oklab, var(--accent) 80%, var(--sidebar-foreground) 30%); */
   --warning: oklch(82.03% 0.1388 48.83);
   --warning-foreground: oklch(21.03% 0.0059 48.83);
 }