@hailer/mcp 1.3.14 → 1.3.23

package/.claude/skills/hailer-design-system/SKILL.md

@@ -1,112 +1,42 @@
 ---
 name: hailer-design-system
-description: Chakra UI v2 theme, colors, icons, and component patterns for Hailer apps. Includes layout, spacing, visual hierarchy, responsive design, empty/loading states.
-version: 2.0.0
-triggers: Build app, UI components, styling, theme, colors, icons, buttons, forms, layout, spacing, hierarchy, responsive, empty state, loading state, design, UI, UX, mockup, dashboard, grid
+description: Chakra UI v2 theme, colors, icons, and component patterns for Hailer apps — load when building any app UI, choosing component variants, styling for dark/light mode, or using icons
+version: 2.4.0
+triggers:
+  - build app
+  - UI components
+  - styling
+  - theme
+  - colors
+  - icons
+  - buttons
+  - forms
 ---
 
 # Hailer Design System
 
-Chakra UI v2 with custom Hailer theme.
-
-**Full reference:** Read `docs/design-system/HAILER_DESIGN_SYSTEM.md` for comprehensive documentation (all icons, all components, full examples).
-
----
-
-## Design Principles
-
-### Layout
-
-Common layout patterns (use Chakra Flex/Grid to implement):
-
-```
-Dashboard:    [Sidebar 240px] [Main Content flex-1]
-List View:    [Filters 280px] [Table/Cards flex-1]
-Detail View:  [Main 2/3] [Sidebar 1/3]
-Form:         [Labels 1/3] [Inputs 2/3] or stacked on mobile
-```
-
-Grid: 12-column, 1200–1400px max-width, centered. Gutters 16–24px.
-
-### Spacing Scale
-
-| Token | px | Use |
-|-------|----|-----|
-| 1 | 4px | Icon padding |
-| 2 | 8px | Compact (button padding) |
-| 4 | 16px | Default (card padding, list gaps) |
-| 6 | 24px | Section gaps |
-| 8 | 32px | Page sections |
-| 12 | 48px | Major sections |
-
-### Visual Hierarchy
-
-**Size scale:**
-
-| Level | Size | Weight |
-|-------|------|--------|
-| Page title | 32–48px (`2xl`) | Bold |
-| Section header | 24–28px (`xl`) | Semibold |
-| Card title | 18–20px (`lg`/`md`) | Medium |
-| Body | 14–16px | Regular |
-| Caption/label | 12–13px (`sm`) | Regular/Medium |
-
-**Emphasis:** size > weight > color > whitespace > position (F-pattern: top-left reads first).
-
-**Density:** Bold labels + regular values for scannability. Group related info in cards. Show summary first, details on demand.
-
-### Responsive Breakpoints
-
-| Breakpoint | Width | Layout |
-|------------|-------|--------|
-| Mobile | < 640px | 1 column, stacked |
-| Tablet | 640–1024px | 2 columns, sidebar hidden |
-| Desktop | > 1024px | Full layout |
-| Wide | > 1440px | max-width container |
-
-Mobile adaptations: stack layouts vertically, hamburger menu, 44px min touch targets, bottom sheets over modals.
-
-### Empty States
-
-Always design for empty — never leave a blank panel:
-
-```
-[Illustration / Icon]
-  No items yet
-  Add your first item
-    [+ Add Item]
-```
-
-Use `VStack` centered in the container with muted icon, `Text` heading, helper text, and a primary action button.
-
-### Loading States
-
-- **Skeleton** — gray boxes mimicking content shape (initial page loads)
-- **Spinner** — for triggered actions, not initial loads
-- **Progress** — multi-step or long operations
-- **Optimistic** — show expected result immediately, revert on error
-
----
+Chakra UI v2 with the Hailer custom theme. The scaffold wires `<ChakraProvider theme={hailerTheme}>` in `main.tsx` — every stock Chakra component is already on Hailer brand out of the box.
 
 ## Setup
 
-The `react-ts` scaffold template already includes the design system at `src/hailer/theme/`. **Do NOT copy from other projects.**
-
 ```tsx
-// Already set up by scaffold in main.tsx
 import { ChakraProvider } from '@chakra-ui/react';
-import { theme } from './hailer/theme/theme';
+import hailerTheme from './hailer/theme/theme';   // default export named hailerTheme
 
-<ChakraProvider theme={theme}>
+<ChakraProvider theme={hailerTheme}>
   <App />
 </ChakraProvider>
 ```
 
+## Design System Location
+
+The theme ships with `@hailer/create-app` at `src/hailer/theme/` (theme + `icons/`) — nothing to copy. `main.tsx` already wires `<ChakraProvider theme={hailerTheme}>`.
+
 ---
 
 ## Colors
 
-**Let theme handle colors automatically.** Rarely specify manually.
+Let the theme handle colors automatically. Rarely specify manually.
 
 | Use | Color |
 |-----|-------|
@@ -116,42 +46,49 @@ import { theme } from './hailer/theme/theme';
 | Neutral | `colorScheme="gray"` |
 
 **Semantic tokens (auto light/dark):**
-- `subtleText` - Muted text
-- `bodyText` - Main text
-- `chakra-body-bg` - Page background
+- `subtleText` — muted text
+- `bodyText` — main text
+- `chakra-body-bg` — page background
+
+---
 
-**Background hierarchy:**
-- Page: `gray.50` or white
-- Card: white (with subtle shadow)
-- Hover: `gray.100`
-- Selected: `brand.50` or `blue.50`
-- Disabled: `gray.100` with `gray.400` text
+## Dark Mode
 
-**Contrast:** 4.5:1 minimum for text (WCAG AA), 3:1 for large text and UI components.
+`useSystemColorMode: true` — theme respects the user's OS setting automatically.
 
 ---
 
 ## Buttons
 
 **Variants:**
-- `solid` (default) - For 1-2 button groups
-- `outline` - For 3+ buttons in a series
-- `ghost` - Subtle secondary actions
+- `solid` (default) — for 1–2 button groups
+- `outline` — for 3+ buttons in a series (note: overrides `color` prop — text renders in theme color, not specified color)
+- `ghost` — subtle secondary actions
+- `unstyled` — full color control; requires explicit `display="flex"`, `alignItems="center"`, `border`, `bg`, `color`, `px`, `h`, `borderRadius` props
+
+**Automatic button styling (applied by theme, do not override):**
+- `textTransform: uppercase`, `letterSpacing: wider`, `fontWeight: bold`, `borderRadius: 30px` (pill), `lineHeight: 1`
+
+**Sizes:** `xs`, `sm`, `md`, `lg`
+
+```tsx
+<Button isLoading loadingText="Saving...">Save</Button>
+<Button isDisabled>Unavailable</Button>
+```
 
 **Critical rules:**
 - Max 2 color schemes per button group
 - Right-align button groups (`justify="flex-end"`)
-- Primary action on the RIGHT
-- Add Hailer icon to primary button
+- Primary action on the right; add a Hailer icon to the primary button
 
 ```tsx
-// Two buttons - correct
+// Two buttons
 <HStack spacing={3} justify="flex-end">
   <Button colorScheme="gray">Cancel</Button>
   <Button colorScheme="green">Save</Button>
 </HStack>
 
-// 3+ buttons - use outline
+// 3+ buttons — use outline
 <HStack spacing={3}>
   <Button variant="outline" colorScheme="green" leftIcon={<HailerPlus />}>Create</Button>
   <Button variant="outline" colorScheme="gray">Export</Button>
@@ -163,26 +100,34 @@ import { theme } from './hailer/theme/theme';
 
 ## Icons
 
-**CRITICAL: Only use Hailer icons. Never external libraries.**
+**Only use Hailer icons. Never external libraries.**
 
 ```tsx
-import { HailerPlus, HailerSettings } from './hailer/theme/icons';
+// Named exports, one file per icon — no barrel index, so import per-file:
+import { HailerPlus } from './hailer/theme/icons/HailerPlus';
+import { HailerSettings } from './hailer/theme/icons/HailerSettings';
 
 <HailerPlus boxSize={6} />
 <Button leftIcon={<HailerPlus />}>Add</Button>
 <IconButton icon={<HailerSettings />} aria-label="Settings" />
 ```
 
-**Common icons:**
+**Common UI icons:**
 - Actions: `HailerPlus`, `HailerEdit`, `HailerTrash`, `HailerSave`
 - Navigation: `HailerChevron`, `HailerMenu`, `HailerSearch`
 - Status: `HailerWarning`, `HailerInfo`, `HailerTick`
 - Objects: `HailerUser`, `HailerCalendar`, `HailerFile`, `HailerActivities`
 
+**Document icons** (all prefixed `HailerDoc*`; plain `HailerImage`/`HailerVideo` are general-purpose, not the file-type variants):
+- `HailerDocArchive`, `HailerDocCode`, `HailerDocDocument`, `HailerDocImage`, `HailerDocMusic`
+- `HailerDocPdf`, `HailerDocPresentation`, `HailerDocSpreadsheet`, `HailerDocVideo`
+
 ---
 
 ## Typography
 
+**Font family:** Nunito Sans for body text and headings.
+
 | Size | Use |
 |------|-----|
 | `2xl` | Page title |
@@ -196,15 +141,13 @@ import { HailerPlus, HailerSettings } from './hailer/theme/icons';
 <Text fontSize="sm" color="subtleText">Caption</Text>
 ```
 
-Text alignment: left-align body, center short headings/CTAs, right-align numbers in tables. Never justify body text.
-
 ---
 
 ## Spacing
 
 ```tsx
-<Box p={8} maxW="1400px" mx="auto">  // Page container
-  <VStack spacing={6} align="stretch">  // Section spacing
+<Box p={8} maxW="1400px" mx="auto">
+  <VStack spacing={6} align="stretch">
     {/* Content */}
   </VStack>
 </Box>
@@ -212,6 +155,17 @@ Text alignment: left-align body, center short headings/CTAs, right-align numbers
 
 ---
 
+## Component Sizes Reference
+
+| Component | Available sizes |
+|-----------|----------------|
+| Button | `xs`, `sm`, `md`, `lg` |
+| Avatar | `hailer-sm`, `hailer-md` (default), `hailer-lg` |
+| Table | `sm`, `md` (default), `lg` |
+| Modal | `md` (default), `7xl` (Hailer custom — full viewport) |
+
+---
+
 ## Forms
 
 ```tsx
@@ -223,43 +177,31 @@ Text alignment: left-align body, center short headings/CTAs, right-align numbers
 </FormControl>
 ```
 
-**Selection controls:** Only green colorScheme for Checkbox, Radio, Switch.
-
-Labels above inputs (mobile-friendly). Group related fields in sections.
+Checkbox, Radio, and Switch only work correctly with `colorScheme="green"`.
 
 ---
 
 ## Tables
 
-**CRITICAL: Use Chakra Table components, not HTML.**
+Use Chakra Table components, not HTML `<table>`:
 
 ```tsx
 <TableContainer>
   <Table variant="simple" size="md">
-    <Thead>
-      <Tr>
-        <Th>Name</Th>
-        <Th isNumeric>Count</Th>
-      </Tr>
-    </Thead>
+    <Thead><Tr><Th>Name</Th><Th isNumeric>Count</Th></Tr></Thead>
     <Tbody>
-      <Tr _hover={{ bg: 'gray.50' }}>
-        <Td>Item</Td>
-        <Td isNumeric>42</Td>
-      </Tr>
+      <Tr><Td>Item</Td><Td isNumeric>42</Td></Tr>
     </Tbody>
   </Table>
 </TableContainer>
 ```
 
-Responsive: hide secondary columns on mobile with `display={{ base: 'none', md: 'table-cell' }}`.
-
 ---
 
 ## Modals
 
 ```tsx
-<Modal isOpen={isOpen} onClose={onClose} size="md">
+<Modal isOpen={isOpen} onClose={onClose} size="md" trapFocus={false} autoFocus={false}>
   <ModalOverlay />
   <ModalContent>
     <ModalHeader>Title</ModalHeader>
@@ -273,18 +215,90 @@ Responsive: hide secondary columns on mobile with `display={{ base: 'none', md:
 </Modal>
 ```
 
+Use `size="7xl"` for full-viewport modals.
+
+**Iframe focus gotcha:** `trapFocus` defaults to `true` — steals focus from the Hailer sidebar when running in an iframe. Always add `trapFocus={false} autoFocus={false}` to every `Modal` and `AlertDialog`. Apply to `Drawer` too.
+
+---
+
+## Tabs
+
+```tsx
+<Tabs variant="hailer" isFitted>
+  <TabList>
+    <Tab>Overview</Tab>
+    <Tab>Details</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel>...</TabPanel>
+    <TabPanel>...</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+---
+
+## Tooltip
+
+```tsx
+<Tooltip variant="hailer" label="More info">
+  <Icon as={HailerInfo} />
+</Tooltip>
+```
+
+---
+
+## Stats
+
+Always use Stat components, not manual Box/Text:
+
+```tsx
+<Stat>
+  <StatLabel>Total Users</StatLabel>
+  <StatNumber>1,234</StatNumber>
+  <StatHelpText><StatArrow type="increase" />23%</StatHelpText>
+</Stat>
+```
+
+---
+
+## Badge / Tag
+
+```tsx
+<Badge colorScheme="green">Active</Badge>
+<Badge colorScheme="red">Overdue</Badge>
+<Badge colorScheme="gray">Draft</Badge>
+
+<Tag colorScheme="green">
+  <TagLabel>Category</TagLabel>
+  <TagCloseButton />
+</Tag>
+```
+
+| Status | Color |
+|--------|-------|
+| Success/Active | `green` |
+| Warning | `orange` |
+| Error/Overdue | `red` |
+| Neutral/Draft | `gray` |
+
+---
+
+## Skeleton (Loading States)
+
+```tsx
+<Skeleton height="20px" />
+<SkeletonText noOfLines={3} spacing={4} />
+<Skeleton isLoaded={dataReady}><Text>{data.name}</Text></Skeleton>
+```
+
 ---
 
 ## Feedback
 
-**Toast:**
+**Snackbar (preferred inside Hailer apps):**
 ```tsx
-toast({
-  description: "Your changes have been saved.",
-  status: "success",
-  duration: 3000,
-  isClosable: true
-});
+hailer.ui.snackbar.open('Your changes have been saved.', 'OK', 3000);
 ```
 
 **Alert:**
@@ -297,27 +311,66 @@ toast({
 
 ---
 
-## Stats
+## Topbar Convention
+
+If the app has a topbar, height should be **56px**.
+
+---
+
+## Theme Sync with Hailer
 
-**Always use Stat components, not manual Box/Text:**
+`HailerSettings` (`{ theme: 'light' | 'dark', preferredLanguages: string[] }`) arrives via the `settings` callback — it is NOT returned by `useHailer()` by default. Extend the store to expose it:
 
 ```tsx
-<Stat>
-  <StatLabel>Total Users</StatLabel>
-  <StatNumber>1,234</StatNumber>
-  <StatHelpText>
-    <StatArrow type="increase" />
-    23%
-  </StatHelpText>
-</Stat>
+// In HailerApi options:
+settings: (data) => {
+  window.__hailerStore!.setState({ hailerSettings: data });
+},
+
+// In components:
+const { hailerSettings } = useHailer();
+const { setColorMode } = useColorMode();
+useEffect(() => {
+  if (hailerSettings) setColorMode(hailerSettings.theme === 'dark' ? 'dark' : 'light');
+}, [hailerSettings, setColorMode]);
+```
+
+---
+
+## Beyond Chakra — Ready-Made Components
+
+| Need | Library | Type | Notes |
+|------|---------|------|-------|
+| Sortable/filterable tables | TanStack Table | Headless | Style with Chakra Table components |
+| Charts and dashboards | Recharts | Themeable | Pass `green.500`, `blue.500` etc. as colors |
+| Drag and drop / kanban | dnd-kit | Headless | Works in iframes |
+| Rich text editing | TipTap | CSS-based | Override fonts with Nunito Sans |
+| File upload with drag-drop | react-dropzone | Headless | Style drop zone with Chakra `Box` |
+| Calendar / scheduling views | react-big-calendar | CSS-based | CSS overrides for Hailer colors |
+
+Rules: prefer headless libraries; all overrides must support dark mode (`useColorModeValue`); still use Hailer icons, not library icons.
+
+---
+
+## Gotchas in Hailer Iframe
+
+### Recharts `XAxis interval={0}`
+
+Default `interval="preserveEnd"` drops the first label. Always set `interval={0}` for dashboards:
+
+```tsx
+<XAxis dataKey="label" interval={0} />
 ```
 
+### Modal focus trap conflicts with sidebar
+
+Always add `trapFocus={false} autoFocus={false}` to every `Modal` and `AlertDialog` — without it, the Modal steals focus from the Hailer sidebar on re-render.
+
 ---
 
 ## Content Tone
 
-- Clear, supportive, human
-- Use contractions ("you're", "we'll")
+- Clear, supportive, human; use contractions
 - Never blame the user
 - Warm success messages: "Your changes have been saved."
 - Helpful errors: "We couldn't save your changes. Please try again."