@persona/design-system 0.3.0 → 0.3.1

package/skills/ui-authoring/EXAMPLES.md

@@ -1,370 +0,0 @@
-# PDS UI Examples
-
-Common patterns for building UI with the Persona design system.
-
-## Table of Contents
-
-- [Buttons](#buttons)
-- [Forms](#forms)
-- [Modals](#modals)
-- [Data Tables](#data-tables)
-- [Status Indicators](#status-indicators)
-- [Layout](#layout)
-- [Navigation — Tabs](#navigation--tabs)
-- [Text Components](#text-components)
-- [Feedback Components](#feedback-components)
-- [Empty States](#empty-states)
-
-## Buttons
-
-```tsx
-import Button from '@persona/design-system/components/Button';
-import { PlusIcon, ArrowRightIcon } from '@persona/icons';
-
-// Variants
-<Button variant="primary" size="md">Save Changes</Button>
-<Button variant="basic" size="md">Cancel</Button>
-<Button variant="danger" size="md">Delete Account</Button>
-<Button variant="outline" size="md">Learn More</Button>
-<Button variant="text" size="md">Skip</Button>
-
-// States
-<Button variant="primary" disabled>Submit</Button>
-<Button variant="primary" isPending>Saving...</Button>
-
-// With icons
-<Button variant="primary" prefixIcon={<PlusIcon />}>Add Item</Button>
-<Button variant="basic" suffixIcon={<ArrowRightIcon />}>Next</Button>
-
-// Icon-only (must include aria-label)
-<Button variant="basic" width="icon" aria-label="Add"><PlusIcon /></Button>
-
-// Widths
-<Button variant="primary" width="full">Full Width</Button>
-<Button variant="primary" width="auto">Auto Width</Button>
-```
-
-## Forms
-
-**Always use `ConfigFormGroup` + `TextField`/`TextAreaField` — never hand-roll `styled.input` or `styled.label`.**
-
-### Basic form
-
-```tsx
-import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
-import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
-import { Select } from '@persona/design-system/components/Select';
-import { TextUnderlineTooltip } from '@persona/design-system/components/Tooltip';
-import { Label } from '@persona/design-system/components/Text';
-import Stack from '@persona/design-system/components/Stack';
-import { Spacing } from '@persona/design-tokens';
-
-<ConfigFormGroup>
-  {/* Field with tooltip: use TextUnderlineTooltip, never an info icon */}
-  <TextUnderlineTooltip tooltip="Must be unique." side="right">
-    <TextField
-      label="Name"
-      value={config.name}
-      onChange={(e) => setConfig({ ...config, name: e.target.value })}
-      configField={true}
-      errorText={errors.name}
-    />
-  </TextUnderlineTooltip>
-
-  <TextAreaField
-    label="Description"
-    value={config.description}
-    onChange={(e) => setConfig({ ...config, description: e.target.value })}
-    configField={true}
-    helperText="Short summary shown in listings."
-  />
-
-  {/* Dropdown */}
-  <Stack spacing={Spacing[2]}>
-    <Label size="sm" color="secondary">Enforcement</Label>
-    <Select
-      value={config.enforcement}
-      onChange={(val) => setConfig({ ...config, enforcement: val })}
-      options={[
-        { label: 'Strict', value: 'strict' },
-        { label: 'Lenient', value: 'lenient' },
-        { label: 'Disabled', value: 'disabled' },
-      ]}
-    />
-  </Stack>
-</ConfigFormGroup>
-```
-
-### 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>
-```
-
-## Modals
-
-**Always use the `Modal` component — never hand-roll `ModalOverlay`/`ModalContainer` styled divs.**
-
-```tsx
-import { Modal } from '@persona/design-system/components/Modal';
-
-const [isOpen, setIsOpen] = useState(false);
-
-<Modal
-  isOpen={isOpen}
-  onClose={() => setIsOpen(false)}
-  title="Confirm Delete"
-  footer={
-    <>
-      <Button variant="basic" onClick={() => setIsOpen(false)}>Cancel</Button>
-      <Button variant="danger" onClick={handleDelete} isPending={isDeleting}>Delete</Button>
-    </>
-  }
->
-  <Paragraph>Are you sure you want to delete this rule? This action cannot be undone.</Paragraph>
-</Modal>
-```
-
-## Data Tables
-
-Use **`DataTable`** for data views (pagination, sorting, server-side data). For small, form-adjacent editable tables, use **`TableBox`** — see [COMPONENTS.md — Editable Table (TableBox)](COMPONENTS.md#editable-table-tablebox). Never hand-roll `<table>`.
-
-```tsx
-import DataTable from '@persona/design-system/components/DataTable';
-
-const columns = [
-  'name',
-  {
-    accessor: 'enforcement',
-    header: 'Enforcement',
-    format: {
-      type: 'sticker',
-      config: { colors: { strict: 'danger', lenient: 'caution', disabled: 'basic' } },
-    },
-  },
-  { accessor: 'lastModified', header: 'Last Modified', format: { type: 'datetime' } },
-];
-
-<DataTable
-  columns={columns}
-  data={rules}
-  rowActions={[
-    { label: 'Edit', onClick: (rowId) => handleEdit(rowId) },
-    { label: 'Delete', onClick: (rowId) => setDeleteTarget(rowId) },
-  ]}
-  pagination={{ clientPagination: true, pageSize: 10, pageSizeOptions: [10, 25, 50] }}
-/>
-```
-
-## Status Indicators
-
-### Sticker (Status Labels)
-
-```tsx
-import Sticker from '@persona/design-system/components/Sticker';
-import { CheckCircleIcon } from '@persona/icons/12px'; // 12px for sticker icons
-
-// Semantic variants — match business status to variant:
-// approved/active/verified  → success
-// declined/failed/error     → danger
-// pending/in-review/flagged → caution
-// inactive/archived         → basic
-<Sticker variant="success">Approved</Sticker>
-<Sticker variant="danger">Failed</Sticker>
-<Sticker variant="caution">Pending</Sticker>
-<Sticker variant="basic">Inactive</Sticker>
-
-// Color variants for categorization
-<Sticker variant="purple">New</Sticker>
-<Sticker variant="blue">In Progress</Sticker>
-
-// With icon (use 12px icons)
-<Sticker variant="success" icon={<CheckCircleIcon />}>Verified</Sticker>
-
-// Dismissible
-<Sticker variant="purple" onDismiss={() => handleRemove()}>Removable Tag</Sticker>
-```
-
-### Banner (Alert / Notification)
-
-```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>
-
-// With dismiss
-<Banner variant="informational" onClose={() => setShowBanner(false)}>
-  <CircleInfoIcon />You can dismiss this message.
-</Banner>
-```
-
-## Layout
-
-### Stack / HStack
-
-```tsx
-import Stack from '@persona/design-system/components/Stack';
-import { HStack } from '@persona/design-system/components/Stack';
-
-// Vertical layout
-<Stack spacing={Spacing[4]}>
-  <Heading size="sm">Section Title</Heading>
-  <Paragraph>Content...</Paragraph>
-</Stack>
-
-// Horizontal layout
-<HStack spacing={Spacing[3]} justify="flex-end">
-  <Button variant="basic">Cancel</Button>
-  <Button variant="primary">Save</Button>
-</HStack>
-
-// Space between header + action
-<HStack spacing={Spacing[4]} justify="space-between" align="center">
-  <Heading size="sm">Policy Rules</Heading>
-  <Button variant="primary" size="sm" prefixIcon={<PlusIcon />}>Add Rule</Button>
-</HStack>
-
-// Wrapping tags/stickers
-<HStack spacing={Spacing[2]} wrap>
-  <Sticker variant="purple">Tag 1</Sticker>
-  <Sticker variant="blue">Tag 2</Sticker>
-</HStack>
-```
-
-### Card with collapsible sections
-
-```tsx
-import { Card } from '@persona/design-system/components/CardV2';
-
-<Card>
-  <Card.Section header="Basic Settings" collapsible={true} defaultCollapsed={false}>
-    <ConfigFormGroup>
-      <TextField label="Name" value={...} onChange={...} />
-    </ConfigFormGroup>
-  </Card.Section>
-  <Card.Section header="Advanced" collapsible={true}>
-    {/* Advanced fields */}
-  </Card.Section>
-</Card>
-```
-
-## Navigation — Tabs
-
-```tsx
-import TabBar, { Tab } from '@persona/design-system/components/TabBar';
-import Badge from '@persona/design-system/components/Badge';
-import { useState } from 'react';
-
-const [selectedTab, setSelectedTab] = useState(0);
-
-<TabBar aria-label="Policy tabs" title="Policy Configuration">
-  <Tab selected={selectedTab === 0} onClick={() => setSelectedTab(0)}>Overview</Tab>
-  <Tab selected={selectedTab === 1} onClick={() => setSelectedTab(1)} badge={<Badge variant="active">5</Badge>}>
-    Pending
-  </Tab>
-  <Tab selected={selectedTab === 2} onClick={() => setSelectedTab(2)} badge={<Badge variant="alert">2</Badge>}>
-    Alerts
-  </Tab>
-</TabBar>
-```
-
-## Text Components
-
-```tsx
-import { Heading, Paragraph, Label } from '@persona/design-system/components/Text';
-
-// Headings
-<Heading size="lg" color="primary">Page Title</Heading>
-<Heading size="md" color="primary">Section Title</Heading>
-<Heading size="sm" color="primary">Subsection</Heading>
-
-// Body text — defaults to color="secondary" (grey); use color="primary" for black
-<Paragraph size="md" color="primary">Black body text</Paragraph>
-<Paragraph size="md">Secondary (grey) body text</Paragraph>
-<Paragraph size="sm" color="tertiary">Helper / caption text</Paragraph>
-
-// Form labels
-<Label size="sm" color="secondary">Field Name</Label>
-```
-
-## Feedback Components
-
-### Spinner
-
-```tsx
-import Spinner from '@persona/design-system/components/Spinner';
-
-// Centered loading state
-<Stack align="center" spacing={Spacing[3]}>
-  <Spinner size="md" srText="Loading policies..." />
-</Stack>
-
-// Inline in button (use isPending prop on Button instead when possible)
-<Button variant="primary" isPending>Saving...</Button>
-```
-
-### Tooltip (standalone, no label)
-
-```tsx
-import Tooltip from '@persona/design-system/components/Tooltip';
-import { HelpCircleIcon } from '@persona/icons';
-
-// Standalone icon trigger (only when there's no adjacent label)
-<Tooltip iconTrigger={<HelpCircleIcon />} side="right">
-  Additional help text appears here.
-</Tooltip>
-```
-
-## 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>
-```
-
-For `ListBox`, pass `emptyText="No items"` prop directly.
-For `Card.Section`, pass `empty={true}` to show the built-in empty state.

package/skills/ui-authoring/REFERENCE.md

@@ -1,293 +0,0 @@
-# Design Tokens Reference
-
-Complete reference for `@persona/design-tokens` package.
-
-## Import
-
-```tsx
-import { Color, Spacing, Typography } from '@persona/design-tokens';
-```
-
-## Color
-
-`Color` is an enum with semantic color names organized by purpose.
-
-### Core Color Palette
-
-Each core color has shades from 50 (lightest) to 1100 (darkest):
-
-```tsx
-// Purple
-Color.CorePurple50     // #F4F5FF (lightest)
-Color.CorePurple100
-Color.CorePurple500    // Mid-range purple
-Color.CorePurple700
-Color.CorePurple1100   // #010334 (darkest)
-
-// Other core colors follow same pattern:
-// CoreRed, CoreOrange, CoreYellow, CoreGreen, CoreTeal, CoreBlue, CoreSlate
-```
-
-### Primary Colors
-
-```tsx
-Color.PrimaryBlack    // #000000
-Color.PrimaryWhite    // #FFFFFF
-Color.PrimaryPurple   // #3F48FD (brand purple)
-Color.PrimaryRed      // #F04B38
-Color.PrimaryOrange   // #F59602
-Color.PrimaryYellow   // #DFFD2F
-Color.PrimaryGreen    // #41D49D
-Color.PrimaryTeal     // #36EBFD
-Color.PrimaryBlue     // #2B7FFD
-```
-
-### Background Colors
-
-```tsx
-Color.BackgroundPrimary      // #FFFFFF (main background)
-Color.BackgroundSecondary    // #F5F5F6
-
-// Button backgrounds
-Color.BackgroundButtonDefault
-Color.BackgroundButtonDefaultHover
-Color.BackgroundButtonPrimary
-Color.BackgroundButtonPrimaryHover
-Color.BackgroundButtonDanger
-Color.BackgroundButtonDangerHover
-
-// Input backgrounds
-Color.BackgroundInputDefault
-Color.BackgroundInputActive
-Color.BackgroundInputDisabled
-
-// Label backgrounds
-Color.BackgroundLabelGrey
-Color.BackgroundLabelPurple
-Color.BackgroundLabelRed
-Color.BackgroundLabelGreen
-// ... and more label variants
-
-// Status indicator backgrounds
-Color.BackgroundStatusIndicatorSuccess
-Color.BackgroundStatusIndicatorWarning
-Color.BackgroundStatusIndicatorCritical
-Color.BackgroundStatusIndicatorFeature
-```
-
-### Text Colors
-
-```tsx
-Color.TextPrimary      // #313131 (main text)
-Color.TextSecondary    // #707070 (secondary text)
-Color.TextInverse      // #FFFFFF (text on dark backgrounds)
-Color.TextActive       // #3F48FD (active/link text)
-Color.TextDanger       // #B81F0E (error text)
-Color.TextDisabled     // #BDBDBD (disabled text)
-
-// Status indicator text colors
-Color.TextStatusIndicatorSuccess
-Color.TextStatusIndicatorWarning
-Color.TextStatusIndicatorCritical
-```
-
-### Border Colors
-
-```tsx
-Color.BorderHairline     // #F1F1F2 (subtle border)
-Color.BorderDivider      // #E2E2E3 (section divider)
-Color.BorderFocus        // #2B7FFD (focus state)
-
-// Input borders
-Color.BorderInputDefault
-Color.BorderInputHover
-Color.BorderInputActive
-Color.BorderInputWarning
-Color.BorderInputDanger
-Color.BorderInputDisabled
-
-// Icon borders
-Color.BorderIconPrimary
-Color.BorderIconSecondary
-Color.BorderIconActive
-Color.BorderIconSuccess
-Color.BorderIconWarning
-Color.BorderIconDanger
-```
-
-### Usage Example
-
-```tsx
-const StyledCard = styled.div`
-  background-color: ${Color.BackgroundPrimary};
-  border: 1px solid ${Color.BorderDivider};
-  color: ${Color.TextPrimary};
-
-  &:hover {
-    background-color: ${Color.BackgroundSecondary};
-  }
-`;
-```
-
-## Spacing
-
-`Spacing` is an enum with numeric indices 0-9:
-
-```tsx
-Spacing[0]   // "0px"
-Spacing[1]   // "4px"
-Spacing[2]   // "8px"
-Spacing[3]   // "12px"
-Spacing[4]   // "16px"
-Spacing[5]   // "24px"
-Spacing[6]   // "32px"
-Spacing[7]   // "40px"
-Spacing[8]   // "48px"
-Spacing[9]   // "56px"
-```
-
-### Common Usage
-
-- **Micro spacing** (1-2): Icon-to-text, tight groupings
-- **Small spacing** (3-4): Form field padding, button padding
-- **Medium spacing** (5): Section margins, card padding
-- **Large spacing** (6-7): Component spacing, page sections
-- **Extra large** (8-9): Hero sections, major divisions
-
-### Usage Example
-
-```tsx
-const Container = styled.div`
-  padding: ${Spacing[5]};
-  margin-bottom: ${Spacing[4]};
-  gap: ${Spacing[3]};
-`;
-```
-
-**For values >56px**: Use hardcoded pixels with a comment explaining the custom value.
-
-## Typography
-
-`Typography` provides complete type styles (font family, size, weight, line height, decoration).
-
-### Display Styles
-
-Large, prominent text for headers and hero sections:
-
-```tsx
-Typography.DisplayLarge    // 64px, bold
-Typography.DisplayMedium   // 48px, bold
-Typography.DisplaySmall    // 36px, bold
-```
-
-### Heading Styles
-
-For section headers and sub-headers:
-
-```tsx
-Typography.HeadingLarge       // 28px
-Typography.HeadingMedium      // 24px
-Typography.HeadingSmall       // 20px
-Typography.HeadingExtraSmall  // 16px
-```
-
-### Text/Paragraph Styles
-
-For body copy and UI text:
-
-```tsx
-// Large text variants
-Typography.TextLarge          // 16px, regular
-Typography.TextLargeBold      // 16px, bold
-Typography.TextLargeLight     // 16px, light
-
-// Medium text variants (most common for body)
-Typography.TextMedium         // 14px, regular
-Typography.TextMediumBold     // 14px, bold
-Typography.TextMediumLight    // 14px, light
-Typography.TextMediumLink     // 14px, regular, underlined
-
-// Small text variants
-Typography.TextSmall          // 12px, regular
-Typography.TextSmallBold      // 12px, bold
-Typography.TextSmallLink      // 12px, regular, underlined
-Typography.TextExtraSmall     // 10px
-
-// Monospace
-Typography.TextMono           // 14px, monospace
-```
-
-### Typography Usage
-
-**IMPORTANT**: Always use complete `Typography` styles. Do not use individual typography tokens like `FontSize`, `FontWeight`, or `FontFamily` directly.
-
-Each `Typography` style is a complete `PDSTypeStyle` object containing:
-
-```tsx
-type PDSTypeStyle = {
-  fontFamily: FontFamily;
-  fontWeight: FontWeight;
-  lineHeight: LineHeight;
-  fontSize: FontSize;
-  textDecoration: TextDecoration;
-};
-```
-
-**Styled components usage:**
-
-```tsx
-const Heading = styled.h1`
-  ${Typography.HeadingLarge}
-  color: ${Color.TextPrimary};
-`;
-
-const BodyText = styled.p`
-  ${Typography.TextMedium}
-  color: ${Color.TextSecondary};
-`;
-
-const SmallLabel = styled.span`
-  ${Typography.TextSmall}
-  color: ${Color.TextSecondary};
-`;
-```
-
-## Finding Colors
-
-When you need a color:
-
-1. **For semantic purposes**, use purpose-named colors:
-   - Buttons: `Color.BackgroundButtonPrimary`
-   - Text: `Color.TextPrimary`, `Color.TextSecondary`
-   - Borders: `Color.BorderDivider`, `Color.BorderInputDefault`
-
-2. **For specific shades**, use core colors with shade numbers:
-   - Light purple: `Color.CorePurple200`
-   - Mid purple: `Color.CorePurple500`
-   - Dark purple: `Color.CorePurple900`
-
-3. **If exact color doesn't exist**: Use the closest available color with a comment explaining the choice.
-
-## Token Verification
-
-To explore available tokens in your project:
-
-```bash
-# Search for color definitions
-grep -r "Color\." node_modules/@persona/design-tokens/dist/js/colors.d.ts
-
-# Check spacing values
-cat node_modules/@persona/design-tokens/dist/js/spacing.d.ts
-
-# See typography styles
-cat node_modules/@persona/design-tokens/dist/js/typography.d.ts
-```
-
-Or check programmatically:
-
-```tsx
-import * as DesignTokens from '@persona/design-tokens';
-console.log(DesignTokens.Color);
-console.log(DesignTokens.Spacing);
-console.log(DesignTokens.Typography);
-```