@persona/design-system 0.7.1 → 0.8.0

package/skills/ui-authoring/PATTERNS.md

@@ -8,124 +8,102 @@ Which pattern to use, and for what. Patterns with a dedicated doc link to
 
 | Pattern | Use for |
 | ------- | ------- |
-| Forms | A settings or config screen where fields need labels, helper text, and errors. Unlabeled controls (search, toolbars) stay as `Input` |
+| [Forms](../../patterns/Forms/Forms.mdx) | Labeled fields in a `Modal`, `RightPanel`, or page. 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 |
+| [SingleColumnLayout](../../patterns/PageLayout/SingleColumnLayout.mdx) | One page column under `PageHeader`, with optional tabs and a page notice. `width="wide"` uses the fluid grid |
+| [SplitColumnLayout](../../patterns/PageLayout/SplitColumnLayout.mdx) | An 8:4 main and aside page. Same optional regions. Stacks main then aside below 768px |
 | 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 |
 | [Panels](../../patterns/Panels/Panels.mdx) | Use `RightPanel` when the page should stay visible. Use `Modal` when the task needs full attention. Never a custom drawer. |
 
 
-## Forms
+## Page layouts
 
-### Form Configuration
+New pages render `PageHeader`, then `SingleColumnLayout` or `SplitColumnLayout`. Do not wrap the
+template in `Container` or `Section`.
 
 ```tsx
-import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
-import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
+import Header from '@persona/design-system/components/PageHeader';
+import { SingleColumnLayout, SplitColumnLayout } from '@persona/design-system/patterns/PageLayout';
 
-const [config, setConfig] = useState({ name: '', description: '', prompt: '' });
+<Header title="Home" />
+<SingleColumnLayout main={<PageContent />} />
 
-<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>
+<SplitColumnLayout main={<MainContent />} aside={<AsideContent />} />
 ```
 
-- `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
+- `width="wide"` fills the fluid grid. The default `standard` width uses the fixed grid.
+- `tabs` and `pageNotice` are optional and scroll with the page. Omit a region and its gap is omitted too.
+- `SplitColumnLayout` is an 8:4 main/aside split, stacking main then aside below 768px.
 
-### Form Pattern
+## Forms
 
-**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.
+Follow [Forms.mdx](../../patterns/Forms/Forms.mdx). Never hand-roll `styled.input` or
+`styled.label`. Compose `FormField` helpers inside an existing surface (`Modal`, `RightPanel`, or a
+page with `PageHeader`); do not invent a Form component.
 
-```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';
+### Size
 
-<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>}
-  />
+Pass `size` only on boxed inputs (`TextField`, `SelectField`, `ComboboxField`, `TextAreaField`).
+Omit it (`md` default) for modals, page forms, and create/edit. Use `size="sm"` only in dense UI:
+editor side panels, configuration forms, filter bars, and `DataTable` cells. Never pass `size` on
+`CheckboxGroupField` or `RadioGroupField`.
 
-  <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}
-  />
+### Stacked vs config
 
-  <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>
-```
+Do not mix stacked and inline fields in one group.
 
+**Stacked** (modal and page forms, radio/checkbox groups): put fields in one wrapping element. Do
+not add `Stack` or `gap` — each field's `Spacing[3]` bottom margin is the gap, and a fragment inside
+`Modal` or `Card` stacks their gap on that margin.
 
+```tsx
+import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
 
-### TextField / TextAreaField props
+<div>
+  <TextField label='Name' value={config.name} onChange={...} helperText='Unique identifier' errorText={errors.name} />
+  <TextAreaField label='Description' value={config.description} onChange={...} />
+</div>;
+```
 
-- `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
+**Config** (editor experiences where the page stays visible): wrap in `ConfigFormGroup`, which sets
+`configField` for children. `helperText` becomes a label tooltip; `warningText` / `errorText` mark
+the field but do not render under it. `rightActions` sits next to the label.
 
+```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) => updateField('name', e.target.value)}
+    rightActions={<Button size='sm' variant='basic'>Generate</Button>}
+  />
+  <TextAreaField label='Prompt' value={config.prompt} onChange={...} warningText={warnings.prompt} />
+</ConfigFormGroup>;
+```
 
 ### Form state hook
 
+Clear `errorText` on change via `updateField`.
+
 ```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; });
+    setConfig((prev) => ({ ...prev, [field]: value }));
+    setErrors((prev) => {
+      const next = { ...prev };
+      delete next[field];
+      return next;
+    });
   }, []);
 
   const validate = useCallback(() => {
@@ -139,48 +117,27 @@ const useFormState = (initialConfig) => {
 };
 ```
 
+### Tooltip on labels
 
-
-### 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.**
+**Always use `TextUnderlineTooltip` — never place an info icon next to a label.** `iconTrigger` is
+only for standalone icon buttons with no adjacent label text.
 
 ```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>
+</TextUnderlineTooltip>;
 ```
 
-`iconTrigger` is only appropriate for standalone icon buttons with no adjacent label text.
-
+### Choosing a surface
 
+- `Modal`: create, confirm, or one-shot tasks where losing page context is fine. Actions go in
+  `footer`. Not for long config forms (use `WizardModal` or a page) or frequently reopened forms.
+- `RightPanel`: editing the selected item; dense, repeatable forms. No footer prop — right-align
+  actions in the body with `HStack`.
+- Page: long or multi-section forms users may leave and return to. `PageHeader` holds actions; put
+  field groups in `Card` (`CardV2`).
 
 ## Layout
 
@@ -188,14 +145,16 @@ import { TextUnderlineTooltip } from '@persona/design-system/components/Tooltip'
 
 ### Card with collapsible sections
 
+Stacked field spacing: [Forms](../../patterns/Forms/Forms.mdx).
+
 ```tsx
 import { Card } from '@persona/design-system/components/CardV2';
 
 <Card>
   <Card.Section heading={{ title: 'Basic Settings' }} collapsible={true} defaultCollapsed={false}>
-    <ConfigFormGroup>
+    <div>
       <TextField label="Name" value={...} onChange={...} />
-    </ConfigFormGroup>
+    </div>
   </Card.Section>
   <Card.Section heading={{ title: 'Advanced' }} collapsible={true}>
     {/* Advanced fields */}