@veracity/vui
Version:
Veracity UI is a React component library crafted for use within Veracity applications and pages. Based on Styled Components and @xstyled.
297 lines (227 loc) • 10.5 kB
Markdown
---
name: build-with-vui
description: >
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.
sources:
- 'WEB-VUI:apps/docs/static/llms/foundations/introduction.md'
- 'WEB-VUI:apps/docs/static/llms/foundations/layout-primitives.md'
- 'WEB-VUI:apps/docs/static/llms/foundations/styling-conventions.md'
- 'WEB-VUI:apps/docs/static/llms/foundations/accessibility.md'
- 'WEB-VUI:apps/docs/static/llms/patterns/layout-patterns.md'
- 'WEB-VUI:apps/docs/static/llms/patterns/form-patterns.md'
- 'WEB-VUI:apps/docs/static/llms/patterns/feedback-patterns.md'
- 'WEB-VUI:apps/docs/static/llms/patterns/overlay-patterns.md'
- 'WEB-VUI:apps/docs/static/llms/patterns/data-display-patterns.md'
metadata:
type: lifecycle
library: '@veracity/vui'
library_version: '5.2.3'
---
# Build With VUI
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
1. Inspect the existing app before editing. Identify local page structure, routing, data fetching, state management, form handling, test style, and existing VUI usage.
2. Keep application architecture local. Follow the host app's existing data, API, routing, and state patterns instead of introducing new ones for the UI change.
3. Choose VUI components and patterns for the UI layer. Prefer documented VUI primitives, patterns, system props, and design tokens over custom components or ad hoc CSS.
4. Open the relevant VUI documentation for the task. Use `https://ui.veracity.com/llms.txt` or the package docs listed in this skill's sources to find component-specific guidance.
5. Implement the smallest coherent UI change. Preserve existing behavior unless the task explicitly asks for a product change.
6. Validate interaction states, responsive behavior, accessibility, and project checks.
## Documentation Routing
Use the task shape to decide which VUI docs to load:
- Layouts, page shells, panels, cards, spacing, and responsive composition: layout primitives and layout patterns.
- Forms, validation, labels, help text, and error messages: form patterns and component docs for `Input`, `Select`, `Checkbox`, `Radio`, `Range`, `Textarea`, `Label`, and `Message`.
- Dialogs, modals, drawers, popovers, tooltips, and focus handling: overlay patterns and the matching component docs.
- Tables, lists, cards, definitions, and dense information views: data display patterns and the matching component docs.
- Toasts, notifications, inline messages, loading, empty, and error states: feedback patterns and the matching component docs.
- Tokens, CSS variables, variants, and styling: styling conventions, design tokens, variants, and component docs.
If the needed component or pattern is not in the current context, load it before coding. Do not guess prop names when the docs are available.
## Implementation Rules
Use imports from the package root:
```tsx
import { Box, Button, Notification } from '@veracity/vui'
```
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:
- Use `Notification`, `Message`, and `useToast()` for feedback instead of custom alert boxes.
- Use `Dialog` for short blocking decisions and confirmations.
- Use `Modal` or `Drawer` for richer workflows.
- Use `Popover` for short contextual interactions and `Tooltip` for brief hints only.
Keep accessibility explicit:
- Icon-only actions need an accessible name through `title`, `aria-label`, or equivalent documented props.
- Form controls need labels and error/help text connections.
- Dialog, modal, drawer, and popover interactions must support keyboard use, focus management, and dismissal behavior.
- Loading, empty, success, warning, and error states should be perceivable without relying only on color.
## Validation Checklist
Before finishing, run the checks that match the host project and the touched code:
- TypeScript/typecheck.
- Lint.
- Unit, integration, or component tests for changed behavior.
- Storybook or visual review when changing layout, overlays, or component composition.
Also verify relevant UI states:
- Loading, empty, success, warning, and error states.
- Disabled, read-only, focused, hover, selected, and expanded states.
- Keyboard navigation and focus order.
- Accessible names, labels, descriptions, and live feedback.
- Mobile and desktop layouts.
## 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="subtle" color="green">Active</Badge>
```
Check component docs for exact variant values before coding.
### HIGH Inventing Local UI Primitives
Wrong:
```tsx
function AlertBox({ children }: { children: React.ReactNode }) {
return <div className="alert-box">{children}</div>
}
```
Correct:
```tsx
import { Notification } from '@veracity/vui'
<Notification variant="inline" intent="info" title="Information">
The operation is still running.
</Notification>
```
Prefer VUI primitives unless the app has an established local abstraction that wraps VUI.
### HIGH Changing App Architecture For A UI Task
Wrong:
```tsx
// Adds a new data client only for this page.
const result = useNewQueryClient('/api/assets')
```
Correct:
```tsx
// Follow the existing app data-fetching pattern found in nearby pages.
const result = useAssets()
```
This skill guides the UI layer. Host app architecture should remain consistent with the existing app.
### MEDIUM Guessing Component Props
Wrong:
```tsx
<Button color="primary" leftIcon="uiPlus">
Add
</Button>
```
Correct:
```tsx
<Button variant="primary" intent="brand" startIcon="uiPlus">
Add
</Button>
```
Load the relevant component docs before using uncertain props.
### MEDIUM Styling With Raw Colors
Wrong:
```css
.status {
color: #005e6e;
}
```
Correct:
```css
.status {
color: var(--vui-foreground-brand-primary);
}
```
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>
)
}
```