@veracity/vui 5.1.0 → 5.1.1-alpha.manual.2605200745

package/skills/{build-vui-ui → build-with-vui}/SKILL.md

@@ -1,13 +1,15 @@
 ---
-name: build-vui-ui
+name: build-with-vui
 description: >
-  Build or change UI in an existing React application that already uses
-  @veracity/vui. Use when adding screens, forms, dialogs, tables, navigation,
-  feedback states, responsive layouts, or other product UI with VUI components,
-  system props, design tokens, and accessibility patterns.
+  Build application UI with @veracity/vui in a React app that already has VUI
+  installed and configured. Use when adding or changing product screens, forms,
+  dialogs, tables, navigation, feedback states, and responsive layouts. This is
+  for app developers composing UI with VUI components, system props, design
+  tokens, and accessibility patterns; it is not for editing VUI's internal
+  component source.
 type: lifecycle
 library: '@veracity/vui'
-library_version: '5.1.0'
+library_version: '5.1.1'
 sources:
   - 'WEB-VUI:apps/docs/static/llms/foundations/introduction.md'
   - 'WEB-VUI:apps/docs/static/llms/foundations/layout-primitives.md'
@@ -20,9 +22,9 @@ sources:
   - 'WEB-VUI:apps/docs/static/llms/patterns/data-display-patterns.md'
 ---
 
-# Build UI With VUI
+# Build With VUI
 
-Use this skill for day-to-day UI implementation in apps that already have `@veracity/vui` installed and configured. Do not use it for first-time setup or VUI 4 to VUI 5 migrations; use the dedicated skills for those workflows.
+Use this skill when building or changing product UI in an application that already uses `@veracity/vui`. It is for composing app screens with VUI components, tokens, layout primitives, and accessibility patterns. Do not use it for first-time setup, VUI 4 to VUI 5 migrations, or changes to VUI's own component internals; use the dedicated setup or migration skills for those workflows.
 
 ## Workflow
 
@@ -59,10 +61,16 @@ Avoid deep imports from `@veracity/vui/dist` or internal source paths.
 Prefer VUI layout and styling tools:
 
 - Use `Box`, `Grid`, `Panel`, `Card`, and system props for structure and spacing.
+- Remember that `Box` defaults to horizontal flex layout. Use `Box column` or `Card column` whenever children should stack like normal document flow.
 - Use `gap` inside flex and grid layouts instead of child margins when possible.
 - Use responsive prop values instead of custom media queries when VUI supports the layout.
 - Use semantic `--vui-*` CSS variables for custom CSS in touched code.
 - Use primitive color tokens only when no semantic token fits.
+- Wrap wide tables in `Box overflowX="auto"` instead of squeezing columns below readable widths.
+
+Use VUI system props for layout, spacing, color, sizing, and simple responsive changes. Use local CSS for complex page-specific grids, table overflow wrappers, sticky local regions, scroll shadows, or pseudo-element/selectors not exposed through system props. Keep local CSS shallow and use semantic `--vui-*` CSS variables.
+
+For status labels, use real component variant values from the docs. For example, `Badge` uses color-named variants such as `subtleGreen`, `subtleYellow`, `subtleRed`, `solidGreen`, and `solidRed`; do not invent generic values like `success`, `warning`, or `danger`.
 
 Prefer VUI feedback and overlay primitives:
 
@@ -97,6 +105,46 @@ Also verify relevant UI states:
 
 ## Common Mistakes
 
+### HIGH Treating Card Like A Plain Div
+
+Wrong:
+
+```tsx
+<Card p={4}>
+  <Heading level={2}>Assets</Heading>
+  <Table>{/* rows */}</Table>
+</Card>
+```
+
+Correct:
+
+```tsx
+<Card column p={4} gap={3}>
+  <Heading level={2}>Assets</Heading>
+  <Box overflowX="auto">
+    <Table>{/* rows */}</Table>
+  </Box>
+</Card>
+```
+
+`Card` and `Box` are flex-first layout primitives. Set `column` for block-like containers.
+
+### HIGH Using Semantic Badge Variant Names
+
+Wrong:
+
+```tsx
+<Badge variant="success">Active</Badge>
+```
+
+Correct:
+
+```tsx
+<Badge variant="subtleGreen">Active</Badge>
+```
+
+Check component docs for exact variant values before coding.
+
 ### HIGH Inventing Local UI Primitives
 
 Wrong:
@@ -176,3 +224,72 @@ Correct:
 ```
 
 Use semantic VUI tokens in touched CSS.
+
+## Data Display Example
+
+```tsx
+import { Badge, Box, Button, Card, Grid, Heading, P, Table } from '@veracity/vui'
+
+const assets = [
+  { name: 'Alpha', owner: 'Operations', status: 'Active', variant: 'subtleGreen' },
+  { name: 'Bravo', owner: 'Finance', status: 'Pending', variant: 'subtleYellow' },
+  { name: 'Charlie', owner: 'Security', status: 'Blocked', variant: 'subtleRed' },
+] as const
+
+export function AssetDashboard() {
+  return (
+    <Box column minH="100vh" gap={4} p={{ sm: 3, md: 5 }} bg="var(--vui-background-default)">
+      <Box centerV justifyContent="space-between" gap={3}>
+        <Box column gap={1}>
+          <Heading level={1}>Assets</Heading>
+          <P>Operational overview for active assets.</P>
+        </Box>
+        <Button variant="primary" intent="brand" startIcon="uiPlus">
+          Add asset
+        </Button>
+      </Box>
+
+      <Grid gap={3} gridTemplateColumns={{ sm: '1fr', lg: 'repeat(3, minmax(0, 1fr))' }}>
+        <Card column p={4} gap={1}>
+          <P>Total</P>
+          <Heading level={2}>128</Heading>
+        </Card>
+        <Card column p={4} gap={1}>
+          <P>Healthy</P>
+          <Heading level={2}>116</Heading>
+        </Card>
+        <Card column p={4} gap={1}>
+          <P>Needs attention</P>
+          <Heading level={2}>12</Heading>
+        </Card>
+      </Grid>
+
+      <Card column p={4} gap={3}>
+        <Heading level={2}>Recent assets</Heading>
+        <Box overflowX="auto">
+          <Table>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th scope="col">Name</Table.Th>
+                <Table.Th scope="col">Status</Table.Th>
+                <Table.Th scope="col">Owner</Table.Th>
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>
+              {assets.map(asset => (
+                <Table.Tr key={asset.name}>
+                  <Table.Td>{asset.name}</Table.Td>
+                  <Table.Td>
+                    <Badge variant={asset.variant}>{asset.status}</Badge>
+                  </Table.Td>
+                  <Table.Td>{asset.owner}</Table.Td>
+                </Table.Tr>
+              ))}
+            </Table.Tbody>
+          </Table>
+        </Box>
+      </Card>
+    </Box>
+  )
+}
+```

package/skills/setup-vui/SKILL.md

@@ -7,7 +7,7 @@ description: >
   wiring toast/offline support.
 type: lifecycle
 library: '@veracity/vui'
-library_version: '5.1.0'
+library_version: '5.1.1'
 sources:
   - 'WEB-VUI:apps/docs/stories/guides/overview/GettingStarted.mdx'
   - 'WEB-VUI:apps/docs/stories/guides/foundations/VuiProvider.mdx'
@@ -29,7 +29,61 @@ Install VUI in a React 18 or React 19 app:
 npm install @veracity/vui
 ```
 
-`@veracity/vui` declares `react` and `react-dom` as peer dependencies. Do not install React 17 for new VUI projects.
+`@veracity/vui@5.1.1` declares these peer dependencies:
+
+- `react`: `^18.0.0 || ^19.0.0`
+- `react-dom`: `^18.0.0 || ^19.0.0`
+
+Do not install React 17 for new VUI projects. The repository's Vite + React + TypeScript example uses React 19, Vite 8, and TypeScript 6. Fresh Vite projects on React 18 or 19 are supported as long as the peer dependency range is satisfied.
+
+## Vite + React + TypeScript Bootstrap
+
+For a new Vite app:
+
+```bash
+npm create vite@latest my-vui-app -- --template react-ts
+cd my-vui-app
+npm install
+npm install @veracity/vui
+```
+
+Configure `src/main.tsx`:
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { VuiProvider } from '@veracity/vui'
+
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <VuiProvider>
+      <App />
+    </VuiProvider>
+  </StrictMode>,
+)
+```
+
+Start with a block-like VUI surface in `src/App.tsx`:
+
+```tsx
+import { Box, Button, Card, Heading, P } from '@veracity/vui'
+
+export default function App() {
+  return (
+    <Box column minH="100vh" p={4} gap={4} bg="var(--vui-background-default)">
+      <Card column p={4} gap={3}>
+        <Heading level={1}>VUI app</Heading>
+        <P>VUI is ready.</P>
+        <Button variant="primary" intent="brand">
+          Continue
+        </Button>
+      </Card>
+    </Box>
+  )
+}
+```
 
 ## Provider Setup
 

package/skills/upgrade-vui-v4-to-v5/SKILL.md

@@ -7,7 +7,7 @@ description: >
   caused by VUI 5 spacing and token changes.
 type: lifecycle
 library: '@veracity/vui'
-library_version: '5.1.0'
+library_version: '5.1.1'
 sources:
   - 'WEB-VUI:apps/docs/stories/guides/overview/ReleaseNotes.mdx'
   - 'WEB-VUI:apps/docs/stories/guides/overview/MigrationGuide.mdx'