feat(stackflow): support custom background color for AppBar

- Add `bg` and `background` props to AppBar for custom background colors
- Create `BoxBackgroundProps` utility in stackflow package (minimal subset of StyleProps)
- Update app-bar recipe to use `--seed-box-background` CSS variable with fallback
- Add documentation and example for AppBar customization

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: te6-in

docs/content/react/stackflow/app-screen.mdx

@@ -151,6 +151,16 @@ Intersection Observer를 사용해 `AppBar`의 `tone` 속성을 동적으로 변
 
 ### Customizing App Bar
 
+`tone="layer"`인 경우 `AppBar`의 색상을 변경할 수 있습니다.
+
+`AppBarIconButton` 내에 `Icon` 컴포넌트를 사용하여 아이콘을 커스터마이징할 수 있습니다.
+
+<Card href="/react/components/iconography/composition#icon-컴포넌트" title="Icon" icon={<IconComponent />}>
+
+아이콘 컴포넌트에 대해 자세히 알아봅니다.
+
+</Card>
+
 <StackflowExample names={["react/app-screen/app-bar-customization"]}>
   ```json doc-gen:file
   {

docs/examples/react/app-screen/app-bar-customization.tsx

@@ -15,11 +15,11 @@ const AppScreenAppBarCustomizationActivity: ActivityComponentType<
 > = () => {
   return (
     <AppScreen theme="android">
-      <AppBar>
+      <AppBar bg="palette.blue200">
         <AppBarMain title="Preview" subtitle="This is a nice preview." />
         <AppBarRight>
           <AppBarIconButton aria-label="Notification">
-            <Icon svg={<IconBellFill />} color="fg.informative" size="x5" />
+            <Icon svg={<IconBellFill />} color="palette.blue500" size="x5" />
           </AppBarIconButton>
         </AppBarRight>
       </AppBar>

packages/css/all.css

@@ -1671,7 +1671,7 @@
 }
 
 .seed-app-bar__root--tone_layer:before {
-  background-color: var(--seed-color-bg-layer-default);
+  background: var(--seed-box-background, var(--seed-color-bg-layer-default));
 }
 
 .seed-app-bar__icon--tone_layer {

packages/css/all.min.css

@@ -267,7 +267,7 @@
     --seed-exit-scale: 1;
 }
 .seed-app-bar__root--tone_layer:before {
-    background-color: var(--seed-color-bg-layer-default);
+    background: var(--seed-box-background, var(--seed-color-bg-layer-default));
 }
 .seed-app-bar__icon--tone_layer {
     color: var(--seed-icon-color, var(--seed-color-fg-neutral));

packages/css/recipes/app-bar.css

@@ -292,7 +292,7 @@ export const appBar = defineSlotRecipe({
       layer: {
         root: {
           "&:before": {
-            backgroundColor: vars.toneLayer.enabled.root.color,
+            background: `var(--seed-box-background, ${vars.toneLayer.enabled.root.color})`,
           },
         },
         icon: {

packages/qvism-preset/src/stackflow/app-bar.ts

@@ -10,6 +10,7 @@ import { useAppBarContext } from "../../primitive/AppBar/useAppBarContext";
 import { createStyleContext } from "../../utils/createStyleContext";
 import { useTopActivity } from "../../primitive/private/useTopActivity";
 import { useActivity } from "@stackflow/react";
+import { useBoxBackgroundProps, type BoxBackgroundProps } from "../../utils/styled";
 
 const { PropsProvider, ClassNamesProvider, useProps, withContext, useClassNames } =
   createStyleContext(appBar);
@@ -21,11 +22,19 @@ const {
 
 export const AppBarPropsProvider = PropsProvider;
 
-export interface AppBarProps extends AppBarVariantProps, AppBarPrimitive.RootProps {}
+export interface AppBarProps
+  extends AppBarVariantProps,
+    AppBarPrimitive.RootProps,
+    BoxBackgroundProps {}
 
 export const AppBarRoot = forwardRef<HTMLDivElement, AppBarProps>((props, ref) => {
+  const { style: boxStyle, restProps: propsWithoutBoxProps } = useBoxBackgroundProps(props);
+
   const contextProps = useProps();
-  const [variantProps, otherProps] = appBar.splitVariantProps({ ...contextProps, ...props });
+  const [variantProps, otherProps] = appBar.splitVariantProps({
+    ...contextProps,
+    ...propsWithoutBoxProps,
+  });
 
   const topActivityTransitionStyle = useTopActivity().transitionStyle;
 
@@ -46,7 +55,7 @@ export const AppBarRoot = forwardRef<HTMLDivElement, AppBarProps>((props, ref) =
       <MainPropsProvider value={resolvedVariantProps}>
         <AppBarPrimitive.Root
           ref={ref}
-          {...mergeProps({ className: classNames.root }, otherProps)}
+          {...mergeProps({ className: classNames.root, style: boxStyle }, otherProps)}
         />
       </MainPropsProvider>
     </ClassNamesProvider>

packages/stackflow/src/components/AppBar/AppBar.tsx

@@ -0,0 +1,41 @@
+import type { ScopedColorBg, ScopedColorPalette, ScopedColorBanner } from "@seed-design/css/vars";
+import { vars } from "@seed-design/css/vars";
+
+/**
+ * A minimal subset of `StyleProps` from `@seed-design/react`.
+ * Copied here to avoid package dependency. May be extracted to a shared package later.
+ */
+export interface BoxBackgroundProps {
+  /**
+   * Shorthand for `background`.
+   */
+  bg?: ScopedColorBg | ScopedColorPalette | ScopedColorBanner | (string & {});
+
+  background?: ScopedColorBg | ScopedColorPalette | ScopedColorBanner | (string & {});
+}
+
+function handleColor(color: string | undefined) {
+  if (!color) {
+    return undefined;
+  }
+  const [type, value] = color.split(".");
+
+  // @ts-expect-error - dynamic access
+  return vars.$color[type]?.[value] ?? color;
+}
+
+export function useBoxBackgroundProps<T extends BoxBackgroundProps>(
+  props: T,
+): {
+  style: React.CSSProperties;
+  restProps: Omit<T, keyof BoxBackgroundProps>;
+} {
+  const { bg, background, ...restProps } = props;
+
+  return {
+    style: {
+      "--seed-box-background": handleColor(background ?? bg),
+    } as React.CSSProperties,
+    restProps: restProps as Omit<T, keyof BoxBackgroundProps>,
+  };
+}