@xferops/design-guide 0.2.1

package/guides/forms-field-input.md

@@ -0,0 +1,124 @@
+---
+id: forms/field-input
+title: Field and Input Setup
+summary: Wire Field, Input, Select, Textarea, Checkbox, Radio, and Switch into labeled form controls.
+category: forms
+slug: field-input
+tags:
+  - forms
+  - field
+  - input
+  - accessibility
+  - react
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Field
+  - packages/ui/src/components/Input
+  - packages/ui/src/components/Select
+  - packages/ui/src/components/Textarea
+  - packages/ui/src/components/Checkbox
+  - packages/ui/src/components/Radio
+  - packages/ui/src/components/Switch
+---
+
+# Field and Input Setup
+
+This guide covers the form control pattern used in the docs app for labeled inputs and selection controls.
+
+## Import the Form Primitives
+
+```tsx
+import {
+  Checkbox,
+  Field,
+  Input,
+  Radio,
+  Select,
+  Stack,
+  Switch,
+  Textarea
+} from "@xferops/ui";
+```
+
+## Use `Field` for Labels and Support Text
+
+Wrap text-entry controls with `Field` so labels, hint text, and error text stay aligned.
+
+```tsx
+<Field
+  labelText="Organization name"
+  htmlFor="orgName"
+  hintText="Shown in invoices and account settings."
+  required
+>
+  <Input id="orgName" placeholder="XferOps LLC" />
+</Field>
+
+<Field
+  labelText="Billing email"
+  htmlFor="billingEmail"
+  errorText="Enter a valid email address."
+>
+  <Input id="billingEmail" type="email" defaultValue="finance@" />
+</Field>
+```
+
+## Keep Control State in React When Needed
+
+Simple toggles and radio groups can use local state.
+
+```tsx
+const [selectedContactMethod, setSelectedContactMethod] = React.useState("email");
+const [notificationsEnabled, setNotificationsEnabled] = React.useState(true);
+```
+
+## Compose Selection Controls in Stacks
+
+Use `Stack` to group related controls without introducing custom layout wrappers.
+
+```tsx
+<Stack gap="md">
+  <Select
+    labelText="Billing cycle"
+    options={[
+      { label: "Monthly", value: "monthly" },
+      { label: "Quarterly", value: "quarterly" }
+    ]}
+    defaultValue="monthly"
+  />
+
+  <Textarea
+    labelText="Internal note"
+    placeholder="Add context for the finance team"
+  />
+
+  <Switch
+    labelText="Enable notifications"
+    checked={notificationsEnabled}
+    onChange={(event) => setNotificationsEnabled(event.currentTarget.checked)}
+  />
+
+  <Checkbox labelText="Send a copy to the account owner" defaultChecked />
+
+  <Stack direction="row" gap="md">
+    <Radio
+      name="contactMethod"
+      labelText="Email"
+      checked={selectedContactMethod === "email"}
+      onChange={() => setSelectedContactMethod("email")}
+    />
+    <Radio
+      name="contactMethod"
+      labelText="Phone"
+      checked={selectedContactMethod === "phone"}
+      onChange={() => setSelectedContactMethod("phone")}
+    />
+  </Stack>
+</Stack>
+```
+
+## Notes
+
+- Use `Field` when a control needs label, hint, or validation messaging.
+- Let `Switch`, `Checkbox`, and `Radio` own their accessible label through `labelText`.
+- Keep layout concerns in `Stack` instead of adding form-specific wrappers.

package/guides/foundations-app-setup.md

@@ -0,0 +1,83 @@
+---
+id: foundations/app-setup
+title: App Setup with Themes and Base Styles
+summary: Bootstrap an app with @xferops/tokens theme classes and the @xferops/ui base layer.
+category: foundations
+slug: app-setup
+tags:
+  - foundations
+  - setup
+  - theming
+  - tokens
+  - ui
+  - vanilla-extract
+sourcePath: apps/docs/src/main.tsx
+relatedPaths:
+  - packages/tokens/src/index.ts
+  - packages/tokens/src/themes/baseTheme.css.ts
+  - packages/tokens/src/themes/partnerTheme.css.ts
+  - packages/tokens/src/themes/darkTheme.css.ts
+  - packages/tokens/src/themes/ventureTheme.css.ts
+  - packages/ui/src/styles/baseLayer.css.ts
+  - packages/ui/src/styles/reset.css.ts
+---
+
+# App Setup with Themes and Base Styles
+
+Use `@xferops/tokens` to provide a theme class and `@xferops/ui` to apply the shared base layer. This is the minimum setup expected before rendering UI primitives.
+
+## Import Theme Classes and the Base Layer
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import {
+  baseThemeClass,
+  darkThemeClass,
+  partnerThemeClass,
+  ventureThemeClass
+} from "@xferops/tokens";
+import { uiBaseLayerClass } from "@xferops/ui";
+import { App } from "./App";
+```
+
+## Wrap the App in Both Classes
+
+`uiBaseLayerClass` handles the shared reset and base typography. The theme class provides the semantic values consumed by UI components.
+
+```tsx
+function Root() {
+  const [theme, setTheme] = React.useState("base");
+
+  const themeClass =
+    theme === "base"
+      ? baseThemeClass
+      : theme === "partner"
+        ? partnerThemeClass
+        : theme === "dark"
+          ? darkThemeClass
+          : ventureThemeClass;
+
+  return (
+    <div className={`${themeClass} ${uiBaseLayerClass}`}>
+      <App activeTheme={theme} onThemeChange={setTheme} />
+    </div>
+  );
+}
+```
+
+## Render Once at the App Boundary
+
+```tsx
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <Root />
+  </React.StrictMode>
+);
+```
+
+## Notes
+
+- Always apply a theme class before rendering `@xferops/ui` components, otherwise semantic token lookups from `vars` will be unset.
+- Apply `uiBaseLayerClass` once near the root instead of per component subtree.
+- Keep theme switching outside shared UI components. Brand or tenant changes should happen by swapping token theme classes.

package/guides/foundations-token-theming.md

@@ -0,0 +1,125 @@
+---
+id: foundations/token-theming
+title: Token Consumption and Theme Authoring
+summary: Use semantic token vars in styles and implement brand differences through theme classes.
+category: foundations
+slug: token-theming
+tags:
+  - foundations
+  - tokens
+  - theming
+  - vanilla-extract
+  - semantic-tokens
+sourcePath: packages/tokens/src/themes/baseTheme.css.ts
+relatedPaths:
+  - packages/tokens/src/index.ts
+  - packages/tokens/src/themeContract.css.ts
+  - packages/tokens/src/themes/baseTheme.css.ts
+  - packages/tokens/src/themes/partnerTheme.css.ts
+  - packages/tokens/src/themes/darkTheme.css.ts
+  - packages/tokens/src/themes/ventureTheme.css.ts
+  - packages/tokens/src/primitives/colors.ts
+  - packages/tokens/src/primitives/spacing.ts
+  - packages/tokens/src/primitives/radii.ts
+  - packages/tokens/src/primitives/typography.ts
+  - packages/tokens/src/primitives/shadows.ts
+---
+
+# Token Consumption and Theme Authoring
+
+`@xferops/tokens` exposes two layers:
+
+- primitive scales such as `colors`, `spacing`, `radii`, `typography`, and `shadows`
+- semantic theme variables through `vars`
+
+Use primitives when authoring themes. Use `vars` when authoring component styles.
+
+## Import the Public Token API
+
+```ts
+import {
+  baseThemeClass,
+  colors,
+  radii,
+  shadows,
+  spacing,
+  typography,
+  vars
+} from "@xferops/tokens";
+```
+
+## Use `vars` Inside Component Styles
+
+Reference semantic values from the theme contract instead of hardcoded colors or spacing.
+
+```ts
+import { style } from "@vanilla-extract/css";
+import { vars } from "@xferops/tokens";
+
+export const section = style({
+  background: vars.color.bg.surface,
+  color: vars.color.text.default,
+  border: `1px solid ${vars.color.border.subtle}`,
+  borderRadius: vars.radius.lg,
+  padding: vars.space.lg,
+  boxShadow: vars.shadow.sm
+});
+```
+
+## Use Primitive Tokens When Defining a Theme
+
+Theme files map primitives into the semantic contract.
+
+```ts
+import { createTheme } from "@vanilla-extract/css";
+import { colors, radii, shadows, spacing, typography, vars } from "@xferops/tokens";
+
+export const customThemeClass = createTheme(vars, {
+  color: {
+    bg: {
+      page: colors.neutral[50],
+      surface: colors.neutral[0],
+      surfaceElevated: colors.neutral[0]
+    },
+    text: {
+      default: colors.neutral[900],
+      muted: colors.neutral[500],
+      inverse: colors.neutral[0],
+      danger: colors.red[600]
+    },
+    border: {
+      subtle: colors.neutral[200],
+      strong: colors.neutral[300],
+      focus: colors.blue[500]
+    },
+    action: {
+      primary: {
+        bg: colors.blue[600],
+        bgHover: colors.blue[700],
+        text: colors.neutral[0]
+      },
+      secondary: {
+        bg: colors.neutral[0],
+        bgHover: colors.neutral[100],
+        text: colors.neutral[900],
+        border: colors.neutral[300]
+      }
+    }
+  },
+  space: spacing,
+  radius: radii,
+  shadow: shadows,
+  font: {
+    family: typography.fontFamily,
+    size: typography.fontSize,
+    weight: typography.fontWeight,
+    lineHeight: typography.lineHeight
+  }
+});
+```
+
+## Notes
+
+- Keep brand-specific decisions in `packages/tokens/src/themes/*`, not in `@xferops/ui` components.
+- Prefer `vars.color.*`, `vars.space.*`, and `vars.font.*` in component styles so all themes stay compatible.
+- Reuse the existing semantic contract unless a real cross-brand need requires adding a new token.

package/guides/navigation-shell.md

@@ -0,0 +1,124 @@
+---
+id: navigation/shell
+title: Navigation Shell Setup
+summary: Assemble HeaderBar, HeaderNav, Breadcrumbs, Tabs, and Pagination into a cohesive app shell.
+category: navigation
+slug: shell
+tags:
+  - navigation
+  - header
+  - breadcrumbs
+  - tabs
+  - pagination
+  - layout
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Header
+  - packages/ui/src/components/Breadcrumbs
+  - packages/ui/src/components/Tabs
+  - packages/ui/src/components/Pagination
+---
+
+# Navigation Shell Setup
+
+This guide shows the navigation composition used in the docs app preview.
+
+## Import the Navigation Primitives
+
+```tsx
+import {
+  Avatar,
+  Badge,
+  Breadcrumbs,
+  Button,
+  HeaderActions,
+  HeaderBar,
+  HeaderBrand,
+  HeaderNav,
+  HeaderNavItem,
+  HeaderNavList,
+  Pagination,
+  Stack,
+  Tabs,
+  Text
+} from "@xferops/ui";
+```
+
+## 1. Build the Header
+
+Use `HeaderBar` as the top-level container, with brand content on the left, navigation in the center, and actions on the right.
+
+```tsx
+<HeaderBar>
+  <HeaderBrand>
+    <Badge tone="accent">XO</Badge>
+    <Stack gap="none">
+      <Text as="span" size="sm" weight="semibold">
+        XferOps
+      </Text>
+      <Text as="span" size="sm" tone="muted">
+        Tenant console
+      </Text>
+    </Stack>
+  </HeaderBrand>
+
+  <HeaderNav aria-label="Primary">
+    <HeaderNavList>
+      <li>
+        <HeaderNavItem href="#" current>
+          Overview
+        </HeaderNavItem>
+      </li>
+      <li>
+        <HeaderNavItem href="#">Invoices</HeaderNavItem>
+      </li>
+      <li>
+        <HeaderNavItem href="#">Workflows</HeaderNavItem>
+      </li>
+    </HeaderNavList>
+  </HeaderNav>
+
+  <HeaderActions>
+    <Button size="sm" variant="secondary">
+      Contact sales
+    </Button>
+    <Avatar name="Ada Lovelace" />
+  </HeaderActions>
+</HeaderBar>
+```
+
+## 2. Add Secondary Wayfinding
+
+Use `Breadcrumbs` for location context and `Tabs` for section switching inside a page.
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Dashboard", href: "#" },
+    { label: "Billing", href: "#" },
+    { label: "Invoices" }
+  ]}
+/>
+
+<Tabs
+  value={activeTab}
+  onValueChange={setActiveTab}
+  items={[
+    { value: "overview", label: "Overview", content: <Text>Overview content</Text> },
+    { value: "activity", label: "Activity", content: <Text>Activity content</Text> },
+    { value: "settings", label: "Settings", content: <Text>Settings content</Text> }
+  ]}
+/>
+```
+
+## 3. Add Pagination for Datasets
+
+```tsx
+<Pagination totalPages={5} page={activePage} onPageChange={setActivePage} />
+```
+
+## Notes
+
+- `HeaderNavItem` carries the current-page state with `current`.
+- `Tabs` is controlled through `value` and `onValueChange`.
+- `Pagination` is also controlled, so keep the page in React state.

package/guides/overlays-actions.md

@@ -0,0 +1,134 @@
+---
+id: overlays/actions
+title: Overlay Actions Setup
+summary: Use Dialog, Drawer, Tooltip, and Popover for focused actions and contextual UI.
+category: overlays
+slug: actions
+tags:
+  - overlays
+  - dialog
+  - drawer
+  - tooltip
+  - popover
+  - interactions
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Dialog
+  - packages/ui/src/components/Drawer
+  - packages/ui/src/components/Tooltip
+  - packages/ui/src/components/Popover
+---
+
+# Overlay Actions Setup
+
+This guide follows the same overlay pattern used in the docs app.
+
+## Import the Overlay Primitives
+
+```tsx
+import {
+  Button,
+  Dialog,
+  Drawer,
+  Field,
+  Input,
+  Popover,
+  Stack,
+  Switch,
+  Text,
+  Tooltip
+} from "@xferops/ui";
+```
+
+## 1. Keep Open State in React
+
+```tsx
+const [isDialogOpen, setIsDialogOpen] = React.useState(false);
+const [isDrawerOpen, setIsDrawerOpen] = React.useState(false);
+const [notificationsEnabled, setNotificationsEnabled] = React.useState(true);
+```
+
+## 2. Use Lightweight Triggers for Small Interactions
+
+```tsx
+<Stack direction="row" gap="sm" wrap align="center">
+  <Button onClick={() => setIsDialogOpen(true)}>Open dialog</Button>
+  <Button variant="secondary" onClick={() => setIsDrawerOpen(true)}>
+    Open drawer
+  </Button>
+  <Tooltip contentText="This action syncs your workspace" side="top">
+    <Button variant="secondary">Tooltip trigger</Button>
+  </Tooltip>
+  <Popover trigger={<Button variant="secondary">Open popover</Button>} side="bottom">
+    <Stack gap="xs">
+      <Text as="span" weight="semibold">
+        Quick actions
+      </Text>
+      <Button size="sm">Create workspace</Button>
+      <Button size="sm" variant="secondary">
+        Invite teammate
+      </Button>
+    </Stack>
+  </Popover>
+</Stack>
+```
+
+## 3. Use `Dialog` for Confirmation
+
+```tsx
+<Dialog
+  open={isDialogOpen}
+  onOpenChange={setIsDialogOpen}
+  titleText="Confirm publish"
+  descriptionText="Publishing will make this brand theme available to all tenants."
+  footerContent={
+    <>
+      <Button variant="secondary" onClick={() => setIsDialogOpen(false)}>
+        Cancel
+      </Button>
+      <Button onClick={() => setIsDialogOpen(false)}>Publish</Button>
+    </>
+  }
+>
+  <Text size="sm" tone="muted">
+    You can still edit token values later, but tenant apps will pick up this version.
+  </Text>
+</Dialog>
+```
+
+## 4. Use `Drawer` for Side-Panel Forms
+
+```tsx
+<Drawer
+  open={isDrawerOpen}
+  onOpenChange={setIsDrawerOpen}
+  titleText="Tenant settings"
+  descriptionText="Adjust workspace-level controls."
+  side="right"
+  footerContent={
+    <>
+      <Button variant="secondary" onClick={() => setIsDrawerOpen(false)}>
+        Close
+      </Button>
+      <Button onClick={() => setIsDrawerOpen(false)}>Save changes</Button>
+    </>
+  }
+>
+  <Stack gap="md">
+    <Field labelText="Tenant name" htmlFor="drawerTenantName">
+      <Input id="drawerTenantName" defaultValue="Acme Corp" />
+    </Field>
+    <Switch
+      labelText="Enable partner override"
+      checked={notificationsEnabled}
+      onChange={(event) => setNotificationsEnabled(event.currentTarget.checked)}
+    />
+  </Stack>
+</Drawer>
+```
+
+## Notes
+
+- `Dialog` and `Drawer` are controlled through `open` and `onOpenChange`.
+- `Tooltip` is best for non-critical supporting context.
+- `Popover` is useful for grouped actions that should remain lightweight.

package/guides/primitives-icons-actions.md

@@ -0,0 +1,77 @@
+---
+id: primitives/icons-actions
+title: Icons and IconButton
+summary: Use the shared SVG icon primitives for inline affordances and icon-only actions.
+category: primitives
+slug: icons-actions
+tags:
+  - icons
+  - svg
+  - actions
+  - button
+  - accessibility
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Icon
+  - packages/ui/src/components/IconButton
+---
+
+# Icons and IconButton
+
+This guide covers the starter icon surface exposed from `@xferops/ui`.
+
+## Import the Icon Primitives
+
+```tsx
+import {
+  Icon,
+  IconButton,
+  LogOutIcon,
+  MenuIcon,
+  SaveIcon,
+  SearchIcon
+} from "@xferops/ui";
+```
+
+## Use Named Icons for Common Actions
+
+Named icons keep common affordances consistent across apps while still inheriting text color.
+
+```tsx
+<Stack direction="row" gap="md" align="center">
+  <SearchIcon />
+  <SaveIcon size="lg" />
+  <LogOutIcon aria-label="Sign out" />
+</Stack>
+```
+
+## Use `Icon` for Custom SVG Paths
+
+Use the base `Icon` component when a product-specific glyph is needed but you still want the shared sizing and accessibility behavior.
+
+```tsx
+<Icon aria-label="Workspace exit" size={18}>
+  <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+  <path d="M16 17l5-5-5-5" />
+  <path d="M21 12H9" />
+</Icon>
+```
+
+## Pair Icons with `IconButton` for Icon-Only Actions
+
+Use the `icon` and `label` props for the common icon-only case. The label is mapped to the button's accessible name.
+
+```tsx
+<Stack direction="row" gap="sm">
+  <IconButton icon={<SaveIcon size="sm" />} label="Save item" variant="primary" />
+  <IconButton icon={<MenuIcon size="sm" />} label="Open menu" />
+  <IconButton icon={<LogOutIcon size="sm" />} label="Sign out" size="sm" />
+</Stack>
+```
+
+## Notes
+
+- Icons default to decorative output unless `title`, `aria-label`, or `aria-labelledby` is supplied.
+- All icons use SVG and inherit color through `currentColor`.
+- `IconButton` also supports the lower-level `children` plus `aria-label` pattern when you need custom content.
+- Prefer named exports from `@xferops/ui` for shared actions, and reserve raw `Icon` usage for genuinely custom shapes.