@persona/design-system 0.3.0 → 0.3.1

package/skills/ui-authoring/PATTERNS.md

@@ -0,0 +1,362 @@
+# Patterns
+
+Pre-built compositions of PDS components.
+
+Which pattern to use, and for what.
+
+
+| Pattern | Use for |
+| ------- | ------- |
+| Forms | A settings or config screen where fields need labels, helper text, and errors. Unlabeled controls (search, toolbars) stay as `Input` |
+| Stack / HStack | A heading above content, a cancel/save pair, a title next to an add button, or a wrapping row of tags |
+| EmptyStates | A list, table, or card has no items yet and you want to invite adding one |
+| Charting | Use `recharts` for all chart components. Always import colors from `ChartingColors` — never hardcode hex values. |
+| Indicators | A record’s open, pending, completed, or failed state next to other content. An in-page notice the user shouldn’t miss (success, warning, error). Use `Toast` if it can auto-dismiss |
+| PageLayout | Page shell |
+| LayoutLoadingSpinner | Centered 120px loading ring that fills its container. Use as the loading state for a page or embedded app when no layout-specific shimmer exists. |
+| LayoutLoadingShimmer | Filling space while content loads |
+
+
+## Forms
+
+### Form Configuration
+
+```tsx
+import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
+import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
+
+const [config, setConfig] = useState({ name: '', description: '', prompt: '' });
+
+<ConfigFormGroup>
+  <TextField
+    label="Name"
+    value={config.name}
+    onChange={(e) => setConfig({ ...config, name: e.target.value })}
+    configField={true}       // helperText becomes a tooltip
+    helperText="Unique identifier"
+    errorText={errors.name}
+    rightActions={<Button size="sm" variant="basic">Generate</Button>}
+  />
+  <TextAreaField
+    label="Prompt"
+    value={config.prompt}
+    onChange={(e) => setConfig({ ...config, prompt: e.target.value })}
+    configField={true}
+    warningText={warnings.prompt}
+  />
+</ConfigFormGroup>
+```
+
+- `configField={true}` → helper text becomes a tooltip instead of inline text
+- `ConfigFormGroup` provides consistent 20px spacing between fields
+- Use controlled inputs; clear `errorText` on change via `updateField` in form state hook
+
+### Form Pattern
+
+**Always use** `ConfigFormGroup` **+** `TextField` **/** `TextAreaField` **— never hand-roll** `styled.input` **or**
+`styled.label`**.** For a tooltip on a standalone label (not `helperText`), wrap the `Label` in
+`TextUnderlineTooltip` — see Tooltip on Labels.
+
+```tsx
+import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
+import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
+import Select, { Option } from '@persona/design-system/components/Select';
+import { Label } from '@persona/design-system/components/Text';
+import Stack from '@persona/design-system/components/Stack';
+import { Spacing } from '@persona/design-tokens';
+
+<ConfigFormGroup>
+  <TextField
+    label="Name"
+    value={config.name}
+    onChange={(e) => setConfig({ ...config, name: e.target.value })}
+    configField={true}
+    helperText="Unique identifier"
+    errorText={errors.name}
+    rightActions={<Button size="sm" variant="basic">Generate</Button>}
+  />
+
+  <TextAreaField
+    label="Description"
+    value={config.description}
+    onChange={(e) => setConfig({ ...config, description: e.target.value })}
+    configField={true}
+    helperText="Short summary shown in listings."
+    warningText={warnings.prompt}
+  />
+
+  <Stack spacing={Spacing[2]}>
+    <Label size="sm" color="secondary">Enforcement</Label>
+    <Select
+      value={config.enforcement}
+      onChange={(e) => setConfig({ ...config, enforcement: e.target.value })}
+    >
+      <Option value="strict">Strict</Option>
+      <Option value="lenient">Lenient</Option>
+      <Option value="disabled">Disabled</Option>
+    </Select>
+  </Stack>
+</ConfigFormGroup>
+```
+
+
+
+### TextField / TextAreaField props
+
+- `label` — field label
+- `value` / `onChange` — controlled input
+- `helperText` — help text (tooltip if `configField={true}`)
+- `errorText` — error message (red)
+- `warningText` — warning message (yellow)
+- `configField` — boolean, renders helper as tooltip
+- `rightActions` — ReactNode for buttons/icons next to label
+- `disabled` — boolean
+
+
+
+### Form state hook
+
+```tsx
+const useFormState = (initialConfig) => {
+  const [config, setConfig] = useState(initialConfig);
+  const [errors, setErrors] = useState({});
+
+  const updateField = useCallback((field, value) => {
+    setConfig(prev => ({ ...prev, [field]: value }));
+    setErrors(prev => { const next = { ...prev }; delete next[field]; return next; });
+  }, []);
+
+  const validate = useCallback(() => {
+    const newErrors = {};
+    if (!config.name) newErrors.name = 'Required';
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [config]);
+
+  return { config, errors, updateField, validate };
+};
+```
+
+
+
+### Form with footer buttons
+
+```tsx
+import Stack from '@persona/design-system/components/Stack';
+import { HStack } from '@persona/design-system/components/Stack';
+
+<Stack spacing={Spacing[5]}>
+  <ConfigFormGroup>
+    <TextField label="Name" value={config.name} onChange={...} />
+    <TextAreaField label="Description" value={config.description} onChange={...} />
+  </ConfigFormGroup>
+  <HStack spacing={Spacing[3]} justify="flex-end">
+    <Button variant="basic" onClick={onCancel}>Cancel</Button>
+    <Button variant="primary" onClick={handleSave} isPending={isSaving}>Save</Button>
+  </HStack>
+</Stack>
+```
+
+### Tooltip on Labels
+
+**Always use `TextUnderlineTooltip` — never place an info icon next to a label.**
+
+```tsx
+// ❌ Deprecated: icon trigger next to label
+<HStack spacing={Spacing[1]} align='center'>
+  <Label size='sm' color='secondary'>Review Type</Label>
+  <Tooltip iconTrigger={<CircleHelpIcon />} side='right'>…</Tooltip>
+</HStack>
+
+// ✅ Correct: dashed underline on the label itself
+import { TextUnderlineTooltip } from '@persona/design-system/components/Tooltip';
+
+<TextUnderlineTooltip tooltip='Explanation text.' side='right'>
+  <Label size='sm' color='secondary'>Review Type</Label>
+</TextUnderlineTooltip>
+```
+
+`iconTrigger` is only appropriate for standalone icon buttons with no adjacent label text.
+
+
+
+## Layout
+
+
+
+### Card with collapsible sections
+
+```tsx
+import { Card } from '@persona/design-system/components/CardV2';
+
+<Card>
+  <Card.Section heading={{ title: 'Basic Settings' }} collapsible={true} defaultCollapsed={false}>
+    <ConfigFormGroup>
+      <TextField label="Name" value={...} onChange={...} />
+    </ConfigFormGroup>
+  </Card.Section>
+  <Card.Section heading={{ title: 'Advanced' }} collapsible={true}>
+    {/* Advanced fields */}
+  </Card.Section>
+</Card>
+```
+
+- `collapsible` / `defaultCollapsed` — section disclosure
+- `heading` — `{ title }` section heading text
+- `loading` — boolean
+- `empty` — boolean
+
+
+
+## Indicators
+
+### Status Indicators
+
+Use `StatusIndicator` for a record’s named lifecycle state. Use `Sticker` for tags.
+
+
+| Business status                    | `status`       |
+| ---------------------------------- | -------------- |
+| open / initiated / inactive        | `open`         |
+| pending / processing               | `pending`      |
+| completed                          | `completed`    |
+| active / reviewed                  | `active`       |
+| failed / declined / error          | `failed`       |
+| needs review / flagged             | `needs_review` |
+| canceled                           | `canceled`     |
+| archived                           | `archived`     |
+
+
+```tsx
+import StatusIndicator from '@persona/design-system/components/StatusIndicator';
+
+<StatusIndicator status="open">Open</StatusIndicator>
+<StatusIndicator status="pending">Pending</StatusIndicator>
+<StatusIndicator status="completed">Completed</StatusIndicator>
+<StatusIndicator status="active">Active</StatusIndicator>
+<StatusIndicator status="failed">Failed</StatusIndicator>
+<StatusIndicator status="needs_review">Needs Review</StatusIndicator>
+<StatusIndicator status="canceled">Canceled</StatusIndicator>
+<StatusIndicator status="archived">Archived</StatusIndicator>
+
+<StatusIndicator type="success" background="filled">Approved</StatusIndicator>
+<StatusIndicator type="critical" background="none">Failed</StatusIndicator>
+```
+
+- `status` — `"open"` | `"pending"` | `"completed"` | `"active"` | `"failed"` | `"needs_review"` | `"canceled"` | `"archived"`
+- `type` — `"neutral"` | `"attention"` | `"warning"` | `"critical"` | `"success"` | `"feature"` | `"informational"` | `"miscellaneous"`. Overrides `status` when both are set.
+- `background` — `"filled"` (default) | `"none"`. `"none"` always shows the icon.
+- `leadingIcon` — optional 12px icon; overrides the preset icon (`null` hides it)
+- `showIcon` — `{false}` hides the icon on `"filled"` only; ignored when `background="none"`
+- `truncate` — ellipsis plus a title tooltip when the label overflows
+- `preserveCase` — keep authored casing (labels are capitalized by default)
+
+
+
+### Banner
+
+```tsx
+import Banner from '@persona/design-system/components/Banner';
+import { CircleInfoIcon, CheckCircleIcon, AlertTriangleIcon, XCircleIcon } from '@persona/icons';
+
+<Banner variant="informational"><CircleInfoIcon />This is an informational message.</Banner>
+<Banner variant="success"><CheckCircleIcon />Changes saved successfully!</Banner>
+<Banner variant="warning"><AlertTriangleIcon />Please review before submitting.</Banner>
+<Banner variant="alert"><XCircleIcon />There was an error processing your request.</Banner>
+
+<Banner variant="informational" onClose={() => setShowBanner(false)}>
+  <CircleInfoIcon />You can dismiss this message.
+</Banner>
+```
+
+
+
+## Feedback
+
+
+
+### Spinner
+
+```tsx
+import Spinner from '@persona/design-system/components/Spinner';
+
+<Stack align="center" spacing={Spacing[3]}>
+  <Spinner size="md" srText="Loading policies..." />
+</Stack>
+
+<Button variant="primary" isPending>Saving...</Button>
+```
+
+Prefer `Button isPending` for mutations. Prefer `Card.Section loading` when the content is inside a
+card. Never `isLoading && <div>Loading...</div>`.
+
+
+
+## Empty states
+
+For tables/lists when there is no data to show:
+
+```tsx
+// Inside a Card section or table container
+<Stack align="center" spacing={Spacing[3]} style={{ padding: Spacing[6] }}>
+  <Paragraph color="secondary">No policy rules yet.</Paragraph>
+  <Button variant="primary" size="sm" prefixIcon={<PlusIcon />}>Add Rule</Button>
+</Stack>
+```
+
+Message-only (no CTA):
+
+```tsx
+<Stack align="center" spacing={Spacing[3]} style={{ padding: Spacing[6] }}>
+  <Paragraph color="secondary">No items yet.</Paragraph>
+</Stack>
+```
+
+For `ListBox`, pass `emptyText="No items"` prop directly.
+For `Card.Section`, pass `empty={true}` to show the built-in empty state.
+
+
+
+## Charting
+
+Use `recharts` for all chart components. Always import colors from `ChartingColors` — never
+hardcode hex values.
+
+```tsx
+import { ChartingColors } from '@persona/design-tokens';
+
+// Sequential — 8 values; for ordered/numeric data (score bands, age ranges, percentages)
+// Use index 0 for the largest value on light backgrounds.
+ChartingColors.Sequential
+
+// Categorical — 14 values; for distinct unordered categories (status, type, country)
+// Light backgrounds only. If > 14 categories, bundle similar items or link to an export view.
+ChartingColors.Categorical
+```
+
+### Palette selection guide
+
+| Data type | Palette | Max series |
+|-----------|---------|-----------|
+| Numeric / ordered | `Sequential` | 8 |
+| Categorical / unordered | `Categorical` | 14 |
+
+### Recharts pattern
+
+```tsx
+import { ChartingColors } from '@persona/design-tokens';
+import { Cell, Pie, PieChart } from 'recharts';
+
+<PieChart>
+  <Pie data={data} dataKey="value">
+    {data.map((_, i) => (
+      <Cell key={i} fill={ChartingColors.Categorical[i % ChartingColors.Categorical.length]} />
+    ))}
+  </Pie>
+</PieChart>
+```
+
+**Anti-patterns:**
+- Hardcoding hex values instead of `ChartingColors`
+- Using `Categorical` on a dark background
+- Using `Sequential` for unordered categories

package/skills/ui-authoring/SKILL.md

@@ -3,7 +3,7 @@ name: ui-authoring
 description: Use when implementing UI, styling React components, working with design tokens, or making frontend changes, or when file paths include design-system/components/ or styled-components.
 metadata:
   library: '@persona/design-system'
-  library_version: '0.3.0'
+  library_version: '0.3.1'
 ---
 
 # UI Authoring
@@ -14,67 +14,24 @@ metadata:
 import { Color, Spacing, Typography } from '@persona/design-tokens';
 ```
 
-- `Spacing[0–9]` = 0/4/8/12/16/24/32/40/48/56px; hardcode px with a comment for larger values.
+- `Spacing[0–9]` = 0/4/8/12/16/24/32/40/48/56px. If you hardcode a value, use a multiple of 4 and comment what it's doing.
 - Always use complete `Typography` styles (e.g. `Typography.TextMedium`), never individual font properties.
-- See [REFERENCE.md](REFERENCE.md) for the full `Color` / `Spacing` / `Typography` catalog.
-
-## Component-First — check this before creating any `styled` component
-
-| Need | Component | Import |
-|------|-----------|--------|
-| Flex column | `Stack` | `@persona/design-system/components/Stack` |
-| Flex row | `HStack` | `@persona/design-system/components/Stack` |
-| Heading text | `Heading` | `@persona/design-system/components/Text` |
-| Body text | `Paragraph` | `@persona/design-system/components/Text` |
-| Form label | `Label` | `@persona/design-system/components/Text` |
-| Button | `Button` | `@persona/design-system/components/Button` |
-| Form fields | `ConfigFormGroup` + `TextField`/`TextAreaField` | `@persona/design-system/components/ConfigFormGroup`, `FormField` |
-| Text input | `Input`, `TextArea` | `@persona/design-system/components/Input`, `TextArea` |
-| Dropdown | `Select` | `@persona/design-system/components/Select` |
-| Dynamic list | `ListBox` | `@persona/design-system/components/ListBox` |
-| Collapsible sections | `Card` + `Card.Section` | `@persona/design-system/components/CardV2` |
-| Modal | `Modal` | `@persona/design-system/components/Modal` |
-| Floating panel | `Popover` | `@persona/design-system/components/Popover` |
-| Status badge | `Sticker` | `@persona/design-system/components/Sticker` |
-| Count badge | `Badge` | `@persona/design-system/components/Badge` |
-| Tabs | `TabBar`, `Tab` | `@persona/design-system/components/TabBar` |
-| Spinner | `Spinner` | `@persona/design-system/components/Spinner` |
-| Alert / notification | `Banner` | `@persona/design-system/components/Banner` |
-| Standalone tooltip | `Tooltip` | `@persona/design-system/components/Tooltip` |
-| Tooltip on a label | `TextUnderlineTooltip` | `@persona/design-system/components/Tooltip` |
-| Page title bar | `PageHeader` | `@persona/design-system/components/PageHeader` |
-| Page shell | `Container`, `Section`, `Backdrop` | `@persona/design-system/patterns/PageLayout` |
-| Data table | `DataTable` | `@persona/design-system/components/DataTable` |
-| Table with loading/empty states | `TableLayout` + `Table` primitives | `@persona/design-system/components/Table` |
-| Editable / form table | `TableBox`, `TableBoxField` | `@persona/design-system/components/TableBox`, `FormField` |
-
-## Tooltip on Labels
-
-**Always use `TextUnderlineTooltip` — never place an info icon next to a label.**
+- See [TOKENS.md](TOKENS.md) for selection rules.
 
-```tsx
-// ❌ Deprecated: icon trigger next to label
-<HStack spacing={Spacing[1]} align='center'>
-  <Label size='sm' color='secondary'>Review Type</Label>
-  <Tooltip iconTrigger={<HelpCircleIcon />} side='right'>…</Tooltip>
-</HStack>
-
-// ✅ Correct: dashed underline on the label itself
-import { TextUnderlineTooltip } from '@persona/design-system/components/Tooltip';
-
-<TextUnderlineTooltip tooltip='Explanation text.' side='right'>
-  <Label size='sm' color='secondary'>Review Type</Label>
-</TextUnderlineTooltip>
-```
+## PDS implementation guidelines
 
-`iconTrigger` is only appropriate for standalone icon buttons with no adjacent label text.
+Start with [PATTERNS.md](PATTERNS.md) and use an existing pattern whenever one fits the use
+case. If no pattern applies, review the component table in [COMPONENTS.md](COMPONENTS.md) to
+select the appropriate component and import path. Only create a `styled` component or wrapper
+when existing components cannot meet the need, and use tokens from [TOKENS.md](TOKENS.md) for
+any custom styling.
 
 ## Table Guidelines
 
 Never hand-roll `<table>`, `<thead>`, `<th>`, or `<td>`. Pick the component by use case:
 
 - **`DataTable`** (`@persona/design-system/components/DataTable`) — data views with pagination, sorting, and server-side data.
-- **`TableBox`** (`@persona/design-system/components/TableBox`) / **`TableBoxField`** (`FormField`) — small, form-adjacent tables in config editors: inline editing, row add/delete, drag-drop reorder. See [COMPONENTS.md — Editable Table (TableBox)](COMPONENTS.md#editable-table-tablebox).
+- **`TableBox`** (`@persona/design-system/components/TableBox`) / **`TableBoxField`** (`FormField`) — small, form-adjacent tables in config editors: inline editing, row add/delete, drag-drop reorder. See `TableBox.mdx`.
 - **`TableLayout`** (`@persona/design-system/components/Table`, named export `TableLayout`) — lower-level table shell with built-in loading and empty states; use it when composing rows manually from `Table` primitives (`TableRow`, `TableCell`, `TableHeaderCell`).
 
 ### DataTable
@@ -117,61 +74,16 @@ const ModalOverlay = styled.div`position: fixed; ...`;  // use <Modal> instead
 // ✅ Use design system components
 <Heading size="sm">Title</Heading>
 <Stack spacing={Spacing[1]}><Label>Field</Label><Input /></Stack>
-<Modal isOpen={isOpen} onClose={onClose} title="..." footer={...}>...</Modal>
+<Modal open={isOpen} onOpenChange={onOpenChange} title="..." footer={...}>...</Modal>
 ```
 
 - `Paragraph` defaults to `color="secondary"` (grey) — use `color="primary"` for black text.
 - Field values in detail/metadata layouts: do not add `weight="bold"` unless the design explicitly calls it out.
 
-## Form Pattern
-
-```tsx
-import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
-import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
-
-<ConfigFormGroup>
-  <TextField
-    label="Name"
-    value={config.name}
-    onChange={(e) => setConfig({ ...config, name: e.target.value })}
-    configField={true}    // helperText becomes a tooltip
-    helperText="Must be unique"
-    errorText={errors.name}
-  />
-  <TextAreaField
-    label="Description"
-    value={config.description}
-    onChange={(e) => setConfig({ ...config, description: e.target.value })}
-    configField={true}
-  />
-</ConfigFormGroup>
-```
-
-`ConfigFormGroup` provides consistent 20px spacing between fields. See [COMPONENTS.md](COMPONENTS.md) for form state hook, `ListBox`, `TableBox`, `Card`, `Modal`, `Select` patterns and full props reference.
-
-## Sticker Status Mapping
-
-| Business status | Sticker variant |
-|----------------|----------------|
-| approved / active / verified / success | `success` |
-| declined / failed / error | `danger` |
-| pending / in-review / flagged | `caution` |
-| inactive / archived / disabled | `basic` |
-
 ## Icon Sizes
 
 - `@persona/icons` — 16px default; use for buttons and standalone icons.
-- `@persona/icons/12px` — use for `Sticker` icons and inline text icons.
-
-## Empty State
-
-```tsx
-<Stack align="center" spacing={Spacing[3]} style={{ padding: Spacing[6] }}>
-  <Paragraph color="secondary">No items yet.</Paragraph>
-</Stack>
-```
-
-For tables/lists, also pass `emptyText` prop where supported (e.g. `ListBox`).
+- `@persona/icons/12px` — use for `StatusIndicator` / `Sticker` icons and inline text icons.
 
 ## Loading States
 
@@ -212,52 +124,8 @@ export const WithErrors: StoryObj<typeof MyComponent> = { args: { errors: { name
 
 Add `ComponentName.stories.tsx` for every new component or visual variant.
 
-## Data Visualization (Charts)
-
-Use `recharts` for all chart components. Always import colors from `ChartingColors` — never
-hardcode hex values.
-
-```tsx
-import { ChartingColors } from '@persona/design-tokens';
-
-// Sequential — 8 values; for ordered/numeric data (score bands, age ranges, percentages)
-// Use index 0 for the largest value on light backgrounds.
-ChartingColors.Sequential
-
-// Categorical — 14 values; for distinct unordered categories (status, type, country)
-// Light backgrounds only. If > 14 categories, bundle similar items or link to an export view.
-ChartingColors.Categorical
-```
-
-### Palette selection guide
-
-| Data type | Palette | Max series |
-|-----------|---------|-----------|
-| Numeric / ordered | `Sequential` | 8 |
-| Categorical / unordered | `Categorical` | 14 |
-
-### Recharts pattern
-
-```tsx
-import { ChartingColors } from '@persona/design-tokens';
-import { Cell, Pie, PieChart } from 'recharts';
-
-<PieChart>
-  <Pie data={data} dataKey="value">
-    {data.map((_, i) => (
-      <Cell key={i} fill={ChartingColors.Categorical[i % ChartingColors.Categorical.length]} />
-    ))}
-  </Pie>
-</PieChart>
-```
-
-**Anti-patterns:**
-- Hardcoding hex values instead of `ChartingColors`
-- Using `Categorical` on a dark background
-- Using `Sequential` for unordered categories
-
 ## Resources
 
-- [EXAMPLES.md](EXAMPLES.md) — copy-paste patterns (Buttons, Forms, Modals, DataTable, TabBar, Tooltip, Spinner, Banner, Sticker, Stack, Text)
-- [REFERENCE.md](REFERENCE.md) — full `Color` / `Spacing` / `Typography` token catalog
-- [COMPONENTS.md](COMPONENTS.md) — props reference + patterns for `ConfigFormGroup`, `ListBox`, `TableBox`, `Card`, `Modal`, form state hook
+- [TOKENS.md](TOKENS.md) — Color / Spacing / Typography selection and catalog, radius, charts
+- [PATTERNS.md](PATTERNS.md) — forms, layout, indicators, feedback, empty states
+- [COMPONENTS.md](COMPONENTS.md) — which PDS component to use, and its import path; APIs live in each component's `.mdx`