@wallarm-org/design-system 1.25.0 → 1.26.0

package/README.md

@@ -37,6 +37,8 @@ export const App = () => {
 };
 ```
 
+`ThemeProvider` also controls the Frame style (`useTheme().setFrameStyle`, `'neutral' | 'branded'`) - see [Installation Guide](docs/installation.md) for details.
+
 ```css
 /* App.css */
 @import 'tailwindcss';

package/dist/components/AppShell/story-content/_storyAccountDropdown.d.ts

@@ -1,5 +1,5 @@
 import { type NavRailMode } from '../../NavRail';
-import type { Theme } from '../../ThemeProvider';
+import { type Theme } from '../../ThemeProvider';
 export type SidebarMode = 'adaptive' | 'expanded' | 'collapsed' | 'compact';
 /** Adaptive collapses the rail inside a product and expands it on Home; the other modes pin it. */
 export declare const railModeFor: (mode: SidebarMode, onHome: boolean) => NavRailMode;

package/dist/components/AppShell/story-content/_storyAccountDropdown.js

@@ -1,10 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Fragment } from "react";
 import { LogOut, PanelLeftDashed, PencilRuler, Settings, User, UserRound } from "../../../icons/index.js";
+import { cn } from "../../../utils/cn.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuItemContent, DropdownMenuItemIcon, DropdownMenuItemText, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger, DropdownMenuTriggerItem } from "../../DropdownMenu/index.js";
 import { NavRailItem } from "../../NavRail/index.js";
 import { HStack, VStack } from "../../Stack/index.js";
 import { Text } from "../../Text/index.js";
+import { useTheme } from "../../ThemeProvider/index.js";
 const railModeFor = (mode, onHome)=>{
     if ('adaptive' === mode) return onHome ? 'expanded' : 'collapsed';
     return mode;
@@ -32,13 +34,27 @@ const THEME_LABELS = {
     light: 'Light',
     dark: 'Dark'
 };
+const FRAME_STYLES = [
+    'neutral',
+    'branded'
+];
+const FRAME_STYLE_LABELS = {
+    neutral: 'Neutral',
+    branded: 'Branded'
+};
+const FRAME_STYLE_SWATCH = {
+    neutral: 'bg-icon-secondary',
+    branded: 'bg-icon-brand'
+};
 const SIDEBAR_MODE_LABELS = {
     adaptive: 'Adaptive',
     expanded: 'Always expanded',
     collapsed: 'Always collapsed',
     compact: 'Compact'
 };
-const AccountDropdown = ({ sidebarMode, onSidebarModeChange, theme, onThemeChange })=>/*#__PURE__*/ jsxs(DropdownMenu, {
+const AccountDropdown = ({ sidebarMode, onSidebarModeChange, theme, onThemeChange })=>{
+    const { frameStyle, setFrameStyle } = useTheme();
+    return /*#__PURE__*/ jsxs(DropdownMenu, {
         positioning: {
             placement: 'right-end',
             gutter: 6,
@@ -106,30 +122,60 @@ const AccountDropdown = ({ sidebarMode, onSidebarModeChange, theme, onThemeChang
                                             /*#__PURE__*/ jsx(DropdownMenuItemText, {
                                                 children: "Appearance"
                                             }),
-                                            /*#__PURE__*/ jsx(Text, {
+                                            /*#__PURE__*/ jsxs(Text, {
                                                 size: "xs",
                                                 color: "secondary",
-                                                children: THEME_LABELS[theme]
+                                                children: [
+                                                    THEME_LABELS[theme],
+                                                    " and ",
+                                                    FRAME_STYLE_LABELS[frameStyle].toLowerCase()
+                                                ]
                                             })
                                         ]
                                     })
                                 ]
                             }),
-                            /*#__PURE__*/ jsx(DropdownMenuContent, {
+                            /*#__PURE__*/ jsxs(DropdownMenuContent, {
                                 className: "w-132",
-                                children: /*#__PURE__*/ jsx(DropdownMenuRadioGroup, {
-                                    value: theme,
-                                    onValueChange: ({ value })=>{
-                                        const next = THEMES.find((t)=>t === value);
-                                        if (next) onThemeChange(next);
-                                    },
-                                    children: THEMES.map((t)=>/*#__PURE__*/ jsx(DropdownMenuRadioItem, {
-                                            value: t,
-                                            children: /*#__PURE__*/ jsx(DropdownMenuItemText, {
-                                                children: THEME_LABELS[t]
-                                            })
-                                        }, t))
-                                })
+                                children: [
+                                    /*#__PURE__*/ jsx(DropdownMenuRadioGroup, {
+                                        value: theme,
+                                        onValueChange: ({ value })=>{
+                                            const next = THEMES.find((t)=>t === value);
+                                            if (next) onThemeChange(next);
+                                        },
+                                        children: THEMES.map((t)=>/*#__PURE__*/ jsx(DropdownMenuRadioItem, {
+                                                value: t,
+                                                children: /*#__PURE__*/ jsx(DropdownMenuItemText, {
+                                                    children: THEME_LABELS[t]
+                                                })
+                                            }, t))
+                                    }),
+                                    /*#__PURE__*/ jsx(DropdownMenuSeparator, {}),
+                                    /*#__PURE__*/ jsx(DropdownMenuRadioGroup, {
+                                        value: frameStyle,
+                                        onValueChange: ({ value })=>{
+                                            const next = FRAME_STYLES.find((s)=>s === value);
+                                            if (next) setFrameStyle(next);
+                                        },
+                                        children: FRAME_STYLES.map((s)=>/*#__PURE__*/ jsxs(DropdownMenuRadioItem, {
+                                                value: s,
+                                                children: [
+                                                    /*#__PURE__*/ jsx(DropdownMenuItemIcon, {
+                                                        children: /*#__PURE__*/ jsx("span", {
+                                                            className: "flex size-16 items-center justify-center",
+                                                            children: /*#__PURE__*/ jsx("span", {
+                                                                className: cn('size-8 rounded-full', FRAME_STYLE_SWATCH[s])
+                                                            })
+                                                        })
+                                                    }),
+                                                    /*#__PURE__*/ jsx(DropdownMenuItemText, {
+                                                        children: FRAME_STYLE_LABELS[s]
+                                                    })
+                                                ]
+                                            }, s))
+                                    })
+                                ]
                             })
                         ]
                     }),
@@ -192,4 +238,5 @@ const AccountDropdown = ({ sidebarMode, onSidebarModeChange, theme, onThemeChang
             })
         ]
     });
+};
 export { AccountDropdown, railModeFor };

package/dist/components/NavPanel/NavPanelGroupItem.js

@@ -4,7 +4,7 @@ import { cn } from "../../utils/cn.js";
 import { useTestId } from "../../utils/testId.js";
 import { Text } from "../Text/index.js";
 import { navPanelGroupItemVariants } from "./classes.js";
-import { useNavPanelDepth, useNavPanelIndent } from "./NavPanelContext.js";
+import { NAV_PANEL_BASE_PADDING, useNavPanelDepth, useNavPanelIndent } from "./NavPanelContext.js";
 const NavPanelGroupItem = ({ ref, asChild = false, icon: Icon, active = false, className, children, ...props })=>{
     const testId = useTestId('group-item');
     const depth = useNavPanelDepth();
@@ -33,6 +33,13 @@ const NavPanelGroupItem = ({ ref, asChild = false, icon: Icon, active = false, c
                 size: "sm",
                 truncate: true,
                 children: children
+            }),
+            active && depth > 0 && /*#__PURE__*/ jsx("span", {
+                "aria-hidden": true,
+                className: "absolute top-0 bottom-0 hidden w-px bg-border-brand branded:block",
+                style: {
+                    left: depth * indent - NAV_PANEL_BASE_PADDING
+                }
             })
         ]
     });

package/dist/components/NavPanel/classes.js

@@ -2,7 +2,7 @@ import { cva } from "class-variance-authority";
 const navPanelItemVariants = cva('overlay flex h-32 shrink-0 w-full cursor-pointer items-center gap-8 rounded-10 p-8 text-sm text-text-primary transition-colors outline-none', {
     variants: {
         active: {
-            true: 'overlay-states-primary-active font-semibold',
+            true: 'overlay-states-primary-active font-semibold branded:overlay-states-brand-active branded:text-text-brand',
             false: 'hover:overlay-states-primary-hover focus-visible:overlay-states-primary-hover active:overlay-states-primary-pressed'
         }
     },
@@ -13,7 +13,7 @@ const navPanelItemVariants = cva('overlay flex h-32 shrink-0 w-full cursor-point
 const navPanelGroupItemVariants = cva('overlay flex h-32 shrink-0 w-full cursor-pointer items-center gap-8 rounded-10 py-8 pr-8 text-sm text-text-primary transition-colors outline-none', {
     variants: {
         active: {
-            true: 'overlay-states-primary-active font-semibold',
+            true: 'overlay-states-primary-active font-semibold branded:overlay-states-brand-active branded:text-text-brand',
             false: 'hover:overlay-states-primary-hover focus-visible:overlay-states-primary-hover active:overlay-states-primary-pressed'
         }
     },

package/dist/components/NavRail/NavRailItem.js

@@ -31,14 +31,15 @@ const NavRailItem = ({ ref, asChild = false, icon: Icon, label, shortcut, active
         "data-testid": testId,
         className: cn(navRailItemVariants({
             mode,
-            active
+            active,
+            avatar: hasPlate
         }), className),
         children: [
             /*#__PURE__*/ jsx("span", {
                 className: "flex shrink-0 items-center justify-center",
                 children: hasPlate ? /*#__PURE__*/ jsxs("span", {
                     "data-slot": "nav-rail-item-avatar",
-                    className: cn('-m-4 grid size-24 place-items-center overflow-hidden rounded-8 bg-states-primary-hover *:col-start-1 *:row-start-1', !photo && 'border border-border-primary'),
+                    className: cn('-m-4 grid size-24 place-items-center overflow-hidden rounded-8 bg-states-primary-hover branded:bg-states-brand-hover branded:text-icon-brand *:col-start-1 *:row-start-1', !photo && 'border border-border-primary branded:border-border-brand'),
                     children: [
                         /*#__PURE__*/ jsx(Icon, {
                             size: "md"

package/dist/components/NavRail/classes.d.ts

@@ -13,5 +13,6 @@ export declare const navRailSkeletonVariants: (props?: ({
 export declare const navRailItemVariants: (props?: ({
     mode?: "collapsed" | "compact" | "expanded" | null | undefined;
     active?: boolean | null | undefined;
+    avatar?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const navRailItemCompactLabelClassName = "line-clamp-2 w-56 shrink-0 text-center text-2xs font-medium text-ellipsis break-normal";

package/dist/components/NavRail/classes.js

@@ -52,13 +52,18 @@ const navRailItemVariants = cva('overlay flex w-full cursor-pointer items-center
             compact: 'min-h-42 flex-col justify-center gap-2 px-8 py-6'
         },
         active: {
-            true: 'overlay-states-primary-active',
+            true: 'overlay-states-primary-active branded:overlay-states-brand-active branded:data-[state=open]:overlay-states-brand-active branded:text-text-brand',
             false: 'hover:overlay-states-primary-hover focus-visible:overlay-states-primary-hover active:overlay-states-primary-pressed'
+        },
+        avatar: {
+            true: 'branded:hover:overlay-states-brand-hover branded:focus-visible:overlay-states-brand-hover branded:active:overlay-states-brand-pressed branded:data-[state=open]:overlay-states-brand-active',
+            false: ''
         }
     },
     defaultVariants: {
         mode: 'expanded',
-        active: false
+        active: false,
+        avatar: false
     }
 });
 const navRailItemCompactLabelClassName = 'line-clamp-2 w-56 shrink-0 text-center text-2xs font-medium text-ellipsis break-normal';

package/dist/components/ThemeProvider/ThemeProvider.d.ts

@@ -1,9 +1,12 @@
 import { type FC, type ReactNode } from 'react';
-import type { Theme } from './types';
+import type { FrameStyle, Theme } from './types';
 interface ThemeProviderProps {
     children: ReactNode;
     defaultTheme?: Theme;
     storageKey?: string;
+    /** Frame style used until the user picks one. */
+    defaultFrameStyle?: FrameStyle;
+    frameStyleStorageKey?: string;
 }
 export declare const ThemeProvider: FC<ThemeProviderProps>;
 export {};

package/dist/components/ThemeProvider/ThemeProvider.js

@@ -1,23 +1,39 @@
 import { jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useState } from "react";
 import { ThemeProviderContext } from "./ThemeProviderContext.js";
-const ThemeProvider = ({ children, defaultTheme = 'light', storageKey = 'wasd-theme', ...props })=>{
+const ThemeProvider = ({ children, defaultTheme = 'light', storageKey = 'wasd-theme', defaultFrameStyle = 'neutral', frameStyleStorageKey = 'wasd-frame-style', ...props })=>{
     const [theme, setTheme] = useState(()=>localStorage.getItem(storageKey) || defaultTheme);
+    const [frameStyle, setFrameStyle] = useState(()=>{
+        const stored = localStorage.getItem(frameStyleStorageKey);
+        return 'neutral' === stored || 'branded' === stored ? stored : defaultFrameStyle;
+    });
     useEffect(()=>{
         const root = window.document.documentElement;
         root.setAttribute('data-theme', theme);
     }, [
         theme
     ]);
+    useEffect(()=>{
+        window.document.documentElement.setAttribute('data-frame-style', frameStyle);
+    }, [
+        frameStyle
+    ]);
     const value = useMemo(()=>({
             theme,
             setTheme: (theme)=>{
                 localStorage.setItem(storageKey, theme);
                 setTheme(theme);
+            },
+            frameStyle,
+            setFrameStyle: (frameStyle)=>{
+                localStorage.setItem(frameStyleStorageKey, frameStyle);
+                setFrameStyle(frameStyle);
             }
         }), [
         theme,
-        storageKey
+        storageKey,
+        frameStyle,
+        frameStyleStorageKey
     ]);
     return /*#__PURE__*/ jsx(ThemeProviderContext.Provider, {
         ...props,

package/dist/components/ThemeProvider/ThemeProviderContext.d.ts

@@ -1,6 +1,8 @@
-import type { Theme } from './types';
+import type { FrameStyle, Theme } from './types';
 export interface ThemeProviderState {
     theme: Theme;
     setTheme: (theme: Theme) => void;
+    frameStyle: FrameStyle;
+    setFrameStyle: (frameStyle: FrameStyle) => void;
 }
 export declare const ThemeProviderContext: import("react").Context<ThemeProviderState>;

package/dist/components/ThemeProvider/ThemeProviderContext.js

@@ -1,6 +1,8 @@
 import { createContext } from "react";
 const ThemeProviderContext = createContext({
     theme: 'light',
-    setTheme: ()=>null
+    setTheme: ()=>null,
+    frameStyle: 'neutral',
+    setFrameStyle: ()=>null
 });
 export { ThemeProviderContext };

package/dist/components/ThemeProvider/index.d.ts

@@ -1,3 +1,3 @@
 export { ThemeProvider } from './ThemeProvider';
-export type { Theme } from './types';
+export type { FrameStyle, Theme } from './types';
 export { useTheme } from './useTheme';

package/dist/components/ThemeProvider/types.d.ts

@@ -1 +1,3 @@
 export type Theme = 'dark' | 'light';
+/** The Frame's look inside a theme: the neutral gray surround, or the warm branded one. */
+export type FrameStyle = 'neutral' | 'branded';

package/dist/index.d.ts

@@ -87,7 +87,7 @@ export { Tabs, TabsButton, TabsContent, TabsLineActions, TabsList, TabsSeparator
 export { Tag, TagClose, type TagProps } from './components/Tag';
 export { Text, type TextProps } from './components/Text';
 export { Textarea, type TextareaProps } from './components/Textarea';
-export { type Theme, ThemeProvider, useTheme, } from './components/ThemeProvider';
+export { type FrameStyle, type Theme, ThemeProvider, useTheme, } from './components/ThemeProvider';
 export { TimeInput, type TimeInputProps } from './components/TimeInput';
 export { Timeline, TimelineConnector, type TimelineConnectorProps, TimelineContent, type TimelineContentProps, TimelineDescription, type TimelineDescriptionProps, TimelineIndicator, type TimelineIndicatorProps, TimelineItem, type TimelineItemProps, type TimelineProps, TimelineSeparator, type TimelineSeparatorProps, TimelineTitle, type TimelineTitleProps, } from './components/Timeline';
 export { Toast, ToastActions, Toaster, toaster } from './components/Toast';

package/dist/metadata/components.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.24.0",
-  "generatedAt": "2026-09-28T08:13:10.040Z",
+  "version": "1.25.0",
+  "generatedAt": "2026-09-28T09:09:05.490Z",
   "components": [
     {
       "name": "Accordion",
@@ -45049,6 +45049,14 @@
             "false"
           ],
           "defaultValue": "false"
+        },
+        {
+          "name": "avatar",
+          "options": [
+            "true",
+            "false"
+          ],
+          "defaultValue": "false"
         }
       ],
       "subComponents": [
@@ -102204,6 +102212,10 @@
           "name": "--color-component-app-shell-bg",
           "value": "var(--color-slate-100)"
         },
+        {
+          "name": "--color-component-app-shell-bg-branded",
+          "value": "var(--color-w-orange-50)"
+        },
         {
           "name": "--color-component-app-shell-ambient-dot",
           "value": "--alpha(var(--color-slate-500) / 28%)"
@@ -103282,6 +103294,10 @@
           "name": "--color-component-app-shell-bg",
           "value": "var(--color-slate-975)"
         },
+        {
+          "name": "--color-component-app-shell-bg-branded",
+          "value": "#160e1a"
+        },
         {
           "name": "--color-component-app-shell-ambient-dot",
           "value": "--alpha(var(--color-slate-50) / 15%)"

package/dist/theme/components/app-shell.css

@@ -40,6 +40,17 @@
     --app-shell-ambient-grain-blend: screen;
 }
 
+/* Branded Frame (WDS-182): multiplying or screening gray noise over the warm base dulls it
+   toward gray. Soft-light adds the same texture and keeps the orange. */
+:root[data-frame-style='branded'] {
+    --app-shell-ambient-grain-opacity: 0.6;
+    --app-shell-ambient-grain-blend: soft-light;
+}
+
+:root[data-theme='dark'][data-frame-style='branded'] {
+    --app-shell-ambient-grain-opacity: 0.35;
+}
+
 @utility app-shell-ambient {
     position: absolute;
     inset: 0;

package/dist/theme/index.css

@@ -31,6 +31,10 @@
 @import './components/app-shell.css';
 @import './components/chart.css';
 
+/* Frame style (WDS-182): styles that apply only while the user has picked the Branded Frame.
+   ThemeProvider writes `data-frame-style` on <html>, so this reaches every micro-frontend. */
+@custom-variant branded (&:where([data-frame-style='branded'] *));
+
 [data-scope='scroll-area'][data-part='viewport'] {
     scrollbar-width: none;
     &::-webkit-scrollbar {

package/dist/theme/semantic.css

@@ -215,6 +215,11 @@
     --color-component-toast-ic-success: var(--color-green-400);
     --color-component-toast-ic-info: var(--color-blue-400);
     --color-component-app-shell-bg: var(--color-slate-100);
+    /* Branded Frame (WDS-182): the Frame fill when the user picks the Branded Frame style.
+     * Swapped in for the token above under `[data-frame-style='branded']` (end of file), so
+     * AppShell follows with no component change; the Ambient tones below get their own
+     * Branded recipe at the end of the file. */
+    --color-component-app-shell-bg-branded: var(--color-w-orange-50);
 
     /* AppShell Frame ambient — the soft spots and dot raster painted into the
      * Frame (header + rail). Every tone derives from the Frame token above, so
@@ -661,6 +666,7 @@
     --color-component-toast-ic-success: var(--color-green-600);
     --color-component-toast-ic-info: var(--color-blue-600);
     --color-component-app-shell-bg: var(--color-slate-975);
+    --color-component-app-shell-bg-branded: #160e1a;
 
     /* AppShell Frame ambient (dark) — on a near-black base only lifts read, so
      * every spot mixes toward white. */
@@ -876,3 +882,76 @@
     --color-data-viz-1: #ffffff;
     --temp-token: #ffffff;
 }
+
+/* ========================================
+ * FRAME STYLE: BRANDED (WDS-182)
+ * ThemeProvider writes `data-frame-style` on <html>. Branded is not a value swap like
+ * dark: components switch to the existing brand tokens through the `branded:` variant
+ * (index.css). Only the Frame base and the Ambient tones change here. These rules are
+ * unlayered, so they beat the light theme values in `@layer theme`; the doubled
+ * specificity of `:root[...]` beats `[data-theme='dark']`.
+ *
+ * The neutral Ambient recipe mixes the base toward white/black in oklch. The achromatic
+ * end has no hue, so on a pale orange base the tones lose theirs and read gray. Branded
+ * tints the spots toward the brand oranges in oklab instead, which keeps the hue, and
+ * lifts only part-way to white so they stay warm. The grain's blend lives in app-shell.css.
+ * ======================================== */
+:root[data-frame-style='branded'] {
+    --color-component-app-shell-bg: var(--color-component-app-shell-bg-branded);
+    --color-component-app-shell-ambient-lift: color-mix(
+        in oklab,
+        var(--color-component-app-shell-bg),
+        white 40%
+    );
+    --color-component-app-shell-ambient-lift-soft: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), white 25%) 70%,
+        transparent
+    );
+    --color-component-app-shell-ambient-shade: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-300) 30%) 70%,
+        transparent
+    );
+    --color-component-app-shell-ambient-shade-soft: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-200) 30%) 65%,
+        transparent
+    );
+    --color-component-app-shell-ambient-header: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-300) 25%) 22%,
+        transparent
+    );
+    --color-component-app-shell-ambient-dot: --alpha(var(--color-w-orange-500) / 28%);
+}
+
+/* Dark: only a faint warm glow toward the deepest brand oranges, as quiet as the neutral lifts. */
+:root[data-theme='dark'][data-frame-style='branded'] {
+    --color-component-app-shell-ambient-lift: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-900) 10%) 95%,
+        transparent
+    );
+    --color-component-app-shell-ambient-lift-soft: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-900) 14%) 70%,
+        transparent
+    );
+    --color-component-app-shell-ambient-shade: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-900) 12%) 60%,
+        transparent
+    );
+    --color-component-app-shell-ambient-shade-soft: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-950) 18%) 95%,
+        transparent
+    );
+    --color-component-app-shell-ambient-header: color-mix(
+        in srgb,
+        color-mix(in oklab, var(--color-component-app-shell-bg), var(--color-w-orange-900) 10%) 30%,
+        transparent
+    );
+    --color-component-app-shell-ambient-dot: --alpha(var(--color-w-orange-300) / 15%);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wallarm-org/design-system",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Core design system library with React components and Storybook documentation",
   "publishConfig": {
     "access": "public",