@xferops/design-guide 0.2.1

package/guides/primitives-layout-content.md

@@ -0,0 +1,96 @@
+---
+id: primitives/layout-content
+title: Layout and Content Primitives
+summary: Compose Box, Stack, Text, Card, List, and Avatar into token-driven page sections.
+category: primitives
+slug: layout-content
+tags:
+  - primitives
+  - layout
+  - content
+  - box
+  - stack
+  - text
+  - card
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Box
+  - packages/ui/src/components/Stack
+  - packages/ui/src/components/Text
+  - packages/ui/src/components/Card
+  - packages/ui/src/components/List
+  - packages/ui/src/components/Avatar
+---
+
+# Layout and Content Primitives
+
+Use the low-level primitives in `@xferops/ui` to build structure before introducing more specialized components.
+
+## Import the Core Primitives
+
+```tsx
+import { Avatar, Box, Card, List, Stack, Text } from "@xferops/ui";
+```
+
+## Use `Box` for Token-Aligned Containers
+
+`Box` is the base surface primitive for padding, border, radius, background, and shadow.
+
+```tsx
+<Box padding="lg" background="surface" border="subtle" radius="lg">
+  <Stack gap="sm">
+    <Text as="span" weight="semibold">
+      Tenant summary
+    </Text>
+    <Text as="span" size="sm" tone="muted">
+      Shared shell container with semantic surface styling.
+    </Text>
+  </Stack>
+</Box>
+```
+
+## Use `Stack` for Spacing and Alignment
+
+Keep layout logic in `Stack` rather than custom wrappers for every screen.
+
+```tsx
+<Stack gap="lg">
+  <Stack direction="row" gap="sm" align="center" wrap>
+    <Avatar name="Ada Lovelace" />
+    <Avatar name="Grace Hopper" />
+    <Avatar fallbackText="+4" />
+  </Stack>
+
+  <Card padding="md" tone="elevated">
+    <Stack gap="xs">
+      <Text as="span" size="sm" weight="semibold">
+        Elevated card
+      </Text>
+      <Text as="span" size="sm" tone="muted">
+        Use cards for grouped content and secondary emphasis.
+      </Text>
+    </Stack>
+  </Card>
+</Stack>
+```
+
+## Use `Text` and `List` for Readable Content
+
+```tsx
+<Stack gap="xs">
+  <Text as="span" size="sm" weight="medium">
+    Feature checklist
+  </Text>
+  <List size="sm" spacing="sm">
+    <li>Export invoices as CSV</li>
+    <li>Apply partner theme overrides</li>
+    <li>Invite finance teammates</li>
+  </List>
+</Stack>
+```
+
+## Notes
+
+- `Box` is polymorphic, so switch the `as` prop when the container should be a `section`, `article`, or `aside`.
+- `Text` should carry semantic meaning through `as`, while size, weight, and tone stay visual.
+- `Stack` is the default spacing primitive for rows, columns, and wrapped action groups.

package/guides/table-sorting.md

@@ -0,0 +1,156 @@
+---
+id: table/sorting
+title: Sortable Table Setup
+summary: Set up a sortable table using TableSortButton and useTableSort.
+category: table
+slug: sorting
+tags:
+  - table
+  - sorting
+  - accessibility
+  - react
+  - docs
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Table
+  - packages/ui/src/hooks/useTableSort.ts
+---
+
+# Sortable Table Setup
+
+This guide shows how to build a sortable table using the same pattern used in `apps/docs/src/App.tsx`.
+
+## Imports
+
+Import the table primitives and the sorting hook from `@xferops/ui`.
+
+```tsx
+import {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeaderCell,
+  TableRow,
+  TableSortButton,
+  useTableSort
+} from "@xferops/ui";
+```
+
+## 1. Define Your Row Type
+
+Your row type should describe the raw data in the table. Define a separate union for the columns you want to sort.
+
+```tsx
+type InvoiceRow = {
+  customer: string;
+  status: string;
+  totalCents: number;
+};
+
+type SortColumn = "customer" | "status" | "totalCents";
+
+const rows: InvoiceRow[] = [
+  { customer: "Northwind", status: "Paid", totalCents: 120000 },
+  { customer: "Stark Industries", status: "Overdue", totalCents: 489000 },
+  { customer: "Wayne Enterprises", status: "Draft", totalCents: 53000 }
+];
+```
+
+## 2. Initialize `useTableSort`
+
+The hook stores the current sort state and returns a sorted copy of your rows.
+
+```tsx
+const {
+  sort,
+  sortedRows,
+  requestSort,
+  getAriaSort
+} = useTableSort<InvoiceRow, SortColumn>({
+  rows,
+  initialSort: {
+    column: "customer",
+    direction: "asc"
+  }
+});
+```
+
+What it gives you:
+
+- `sort`: the active sort state, including `column` and `direction`
+- `sortedRows`: a sorted copy of the input rows
+- `requestSort(column)`: toggles sort direction when clicking the active column, or switches to a new column in ascending order
+- `getAriaSort(column)`: returns `"ascending"`, `"descending"`, or `"none"` for accessibility
+
+## 3. Build the Table Header
+
+Put `aria-sort` on each `TableHeaderCell`. Inside each header cell, render a `TableSortButton`.
+
+```tsx
+<Table striped>
+  <TableCaption>Recent invoices</TableCaption>
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell aria-sort={getAriaSort("customer")}>
+        <TableSortButton
+          active={sort.column === "customer"}
+          direction={sort.direction}
+          onClick={() => requestSort("customer")}
+        >
+          Customer
+        </TableSortButton>
+      </TableHeaderCell>
+
+      <TableHeaderCell aria-sort={getAriaSort("status")}>
+        <TableSortButton
+          active={sort.column === "status"}
+          direction={sort.direction}
+          onClick={() => requestSort("status")}
+        >
+          Status
+        </TableSortButton>
+      </TableHeaderCell>
+
+      <TableHeaderCell aria-sort={getAriaSort("totalCents")}>
+        <TableSortButton
+          active={sort.column === "totalCents"}
+          direction={sort.direction}
+          onClick={() => requestSort("totalCents")}
+        >
+          Total
+        </TableSortButton>
+      </TableHeaderCell>
+    </TableRow>
+  </TableHead>
+```
+
+`TableSortButton` displays:
+
+- `↕` when the column is not active
+- `↑` when the active column is ascending
+- `↓` when the active column is descending
+
+## 4. Render `sortedRows`
+
+Render the rows returned by the hook instead of the original array.
+
+```tsx
+  <TableBody>
+    {sortedRows.map((invoice) => (
+      <TableRow key={invoice.customer}>
+        <TableCell>{invoice.customer}</TableCell>
+        <TableCell>{invoice.status}</TableCell>
+        <TableCell>{formatCurrency(invoice.totalCents)}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Notes
+
+- `useTableSort` supports `string`, `number`, `boolean`, `Date`, `null`, and `undefined`.
+- When values are `null` or `undefined`, they sort to the bottom in ascending order.
+- If your displayed value differs from the value you want to sort on, use the hook's `getSortValue` option.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xferops/design-guide",
+  "version": "0.2.1",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "xferops-design-guide-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "guides"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "zod": "^4.1.11"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.6"
+  }
+}