@hiver/skills 1.0.8 → 1.0.9

package/collections/web/skills/build-component/palette/colors.md

@@ -85,3 +85,79 @@ Use these when wiring to MUI theme (e.g. `color="primary"`, `color="text.seconda
 - **Info**: blue
 - **Warning**: orange
 - **Divider**: `gray.gray6`
+
+---
+
+## Additional tokens
+
+More tokens available on the same `theme.palette` object (in addition to the tables above). Reference these paths — not `theme.v2.primitives.*` or `theme.v2.tokens.*` (raw layers, not for application code).
+
+### Primitive ramps (accessed as `theme.palette.<name>.<shade>`)
+
+The following ramps land directly on `theme.palette`:
+
+- **Neutral**: `white`, `black`, `gray`
+- **Brand/status**: `yellow`, `red`, `green`, `orange`, `blue`
+- **Accents**: `royal`, `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`
+
+Each ramp has shades `25`, `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`, plus `alpha-*` variants (e.g. `alpha-10`, `alpha-20`, `alpha-30`).
+
+Example: `theme.palette.royal[500]`, `theme.palette.gray[950]`, `theme.palette.blue['alpha-18']`.
+
+### Semantic groups (accessed as `theme.palette.<group>.*`)
+
+Values differ between light and dark modes — the same path resolves to the right hex for the active mode.
+
+**`theme.palette.text.*`** — extends MUI's built-in `primary` / `secondary` / `disabled` with:
+- `text.primary` → strong neutral text (light: `gray.900`)
+- `text.secondary` → soft neutral text (light: `gray.500`)
+- `text.disabled` → `gray.400`
+- `text.inverse` → `gray.25`
+- `text.neutral.{subtle,soft,default,strong,intense}`
+- `text.brand.{subtle,soft,default,strong,intense}`
+- `text.royal.{...}` / `text.success.{...}` / `text.warning.{...}` / `text.error.{...}` / `text.info.{...}`
+- `text.accents.<tone>.{subtle,soft,default,strong,intense}` where `<tone>` is one of `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`, `green`, `blue`, `orange`, `red`, `gray`
+- `text.on.{brand,success,warning,error,info,royal}` — foreground when placed on a solid tone-fill
+- `text.on.accents.<tone>` — same, for accent surfaces
+
+**`theme.palette.background.*`** — extends MUI's built-in `default` / `paper` with:
+- `background.default` → `background.neutral.subtle` (light: `gray.25`)
+- `background.paper` → `background.neutral.default` (light: `gray.100`)
+- `background.disabled` / `background.inverse` / `background.overlay` / `background['selected-hover']`
+- `background.alpha.{5}` / `background.static.{white,black}`
+- `background.neutral.{white,subtle,soft,default,strong,intense,extreme,maximum}`
+- `background['neutral-bold'].{soft,default,strong,intense,black}`
+- `background.brand.{subtle,soft,default,strong,intense}`
+- `background.royal.{...}` / `background.success.{...}` / `background.warning.{...}` / `background.error.{...}` / `background.info.{...}`
+- `background.accents.<tone>.{subtle,soft,default,strong,intense}`
+
+**`theme.palette.foreground.*`** — icon/glyph foreground colors:
+- `foreground.inverse` / `foreground.disabled`
+- `foreground.static.{white,black}` / `foreground.alpha.{30,40}`
+- `foreground.neutral.{subtle,soft,default,strong,intense}`
+- `foreground['neutral-bold'].{subtle,soft,default,strong,intense}`
+- `foreground.brand.{...}` / `foreground.royal.{...}` / `foreground.success.{...}` / `foreground.warning.{...}` / `foreground.error.{...}` / `foreground.info.{...}`
+- `foreground.accents.<tone>.{subtle,soft,default,strong,intense}`
+- `foreground.on.{brand,success,warning,error,info,royal}` / `foreground.on.accents.<tone>`
+
+**`theme.palette.border.*`** — stroke colors:
+- `border.disabled`
+- `border.neutral.{subtle,soft,default,strong,intense,extreme,maximum}`
+- `border['neutral-bold'].{subtle,soft,default,strong,intense}`
+- `border.brand.{subtle,soft,default,strong,intense,solid}`
+- `border.royal.{subtle,soft,default,strong,intense,solid}`
+- `border.success.{subtle,soft,default,strong,intense}` / `border.warning.{...}` / `border.error.{...}` / `border.info.{subtle,soft,default,strong,intense,solid}`
+- `border.accents.<tone>.{subtle,soft,default,strong,intense}`
+
+**`theme.palette.charts.*`** — chart series palette:
+- `charts['1']` through `charts['8']`
+  - `1` blue, `2` teal, `3` orange, `4` violet, `5` pink, `6` green, `7` red, `8` cyan
+
+**`theme.palette.effect.*`** — focus-ring / effect layers:
+- `effect.focus.{brand,neutral,royal,error}`
+
+### Access rules
+
+- Reference tokens as `theme.palette.<group>.<slot>` (e.g. `theme.palette.text.neutral.strong`, `theme.palette.royal[500]`) — same shape across light/dark, resolved by the provider.
+- Do **not** reference `theme.v2.primitives.*` or `theme.v2.tokens.*` in application code. Those are raw/escape layers, kept for cases like module-scope style composition without theme access.
+- Do **not** hard-code hex values — always go through `theme.palette.*`.

package/collections/web/skills/build-component/references/v2-components.md

@@ -0,0 +1,100 @@
+# v2 components (`@hiver/hiver-ui-kit/v2`)
+
+Load this only after the design has been identified as v2 (see `SKILL.md` → "v2 detection rules"). This file is an **index**. Per-component detail — variants, prop matrix, slot list, Figma-variable → `theme.palette.*` reconciliation, caveats — lives in each component's `.figma-spec.md` inside the `hiver-ui-kit` repo. Read the spec on demand; do not read all of them up front.
+
+## Consumption
+
+- **Import**: `import { <Component> } from '@hiver/hiver-ui-kit/v2';`
+- **Provider**: v2 requires a v2-enabled theme. In existing code that already uses `HiverThemeProvider`, pass `v2` (and optionally `mode="light" | "dark"`) to enable v2 on top of v1. In v2-only trees use `HiverThemeProviderV2` (also exported from `/v2`).
+- **Colours**: reference `theme.palette.*` (see `palette/colors.md` v2 section). **Never** reference `theme.v2.primitives.*` or `theme.v2.tokens.*` for colour tokens in application code.
+- **Non-colour primitives** (spacing, radius, border-width, iconSize, font-family/size/weight, line-height): `theme.v2.primitives.*` is the correct access path — do **not** try to route these through `theme.palette`.
+- **Typography**: v2 variants (`body_<sz>_<w>`, `heading_<sz>_<w>`, `display_<sz>_<w>`, `caption_<w>`, `overline_<w>`) via the same `<Typography>` component (see `typography/variants.md` v2 section).
+- **Do not mix** v1 and v2 components in the same visual composition unless the design explicitly calls for it. It IS common to compose a v1 chrome primitive (`Popover`, `Modal`, `Popper`, `Tooltip`, `Stack`, `Box`) around v2 content — see `references/v2-usage-examples.md`.
+
+## Component index
+
+Cross-repo pointer format: `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` (relative to the web repo root). If `hiver-ui-kit` is not checked out at that path, the index below still gives import paths and one-line purposes — the token reconciliation is what's lost.
+
+| Component | Import | Ui-kit spec (full detail) | Purpose |
+|---|---|---|---|
+| `Avatar` | `Avatar` | `../hiver-ui-kit/src/v2/components/Avatar/.figma-spec.md` | User/entity avatar — `type="picture" \| "initials" \| "icon"`, sizes, status ring |
+| `Badge` | `Badge` | `../hiver-ui-kit/src/v2/components/Badge/.figma-spec.md` | Status/tone chips (`variant` × `tone` × `size` × `shape`) |
+| `Breadcrumbs` | `Breadcrumbs` | (spec pending — see inline block below) | Root → leaf breadcrumb list |
+| `Button` | `Button` | `../hiver-ui-kit/src/v2/components/Button/.figma-spec.md` | Filled / outlined / link buttons; 9+ variants × 5 sizes × 5 states |
+| `Checkbox` | `Checkbox` | `../hiver-ui-kit/src/v2/components/Checkbox/.figma-spec.md` | Tri-state (`-1 / 0 / 1`) with label + description |
+| `Dropdown` (compound: `Dropdown.Menu`, `Dropdown.ListItem`) | `Dropdown` | (spec pending — see inline block below) | Visual container only — anchoring / open state is caller's job (compose inside MUI `Popover` / `Popper`) |
+| `IconButton` | `IconButton` | `../hiver-ui-kit/src/v2/components/IconButton/.figma-spec.md` | Icon-only button; sizes, tones, variants aligned with `Button` |
+| `InlineSelectLabel` | `InlineSelectLabel` | `../hiver-ui-kit/src/v2/components/InlineSelectLabel/.figma-spec.md` | Inline selection summary — icon/status/avatar + label + trailing `+N` badge |
+| `Input.Text` | `Input` (namespace) | (spec pending — inline block below) | Single-line text input |
+| `Input.TextArea` | `Input` | `../hiver-ui-kit/src/v2/components/Input/TextArea/.figma-spec.md` | Multi-line text input |
+| `Input.Search` | `Input` | `../hiver-ui-kit/src/v2/components/Input/Search/.figma-spec.md` | Search-styled input |
+| `Input.Tags` | `Input` | `../hiver-ui-kit/src/v2/components/Input/Tags/.figma-spec.md` | Tag-entry input |
+| `Radio` | `Radio` | `../hiver-ui-kit/src/v2/components/Radio/.figma-spec.md` | Radio with label + description |
+| `Switch` | `Switch` | `../hiver-ui-kit/src/v2/components/Switch/.figma-spec.md` | Toggle switch, `xs` / `sm` / `md` |
+| `Tab.Item` | `Tab` | `../hiver-ui-kit/src/v2/components/Tab/Item/.figma-spec.md` | Tab item |
+| `Table.Header` / `HeaderCell` / `HeaderLabel` / `BodyCell` | `Table` | `../hiver-ui-kit/src/v2/components/Table/{Header,HeaderCell,HeaderLabel,BodyCell}/.figma-spec.md` | Table primitives (compose your own row layout) |
+| `Tag` | `Tag` | `../hiver-ui-kit/src/v2/components/Tag/.figma-spec.md` | Removable label with tone options |
+| `Toast` | `Toast` | `../hiver-ui-kit/src/v2/components/Toast/.figma-spec.md` | Toast notification |
+
+## General patterns
+
+- All v2 components accept a `slotProps` prop for fine-grained overrides on internal DOM regions. Prefer top-level props first; fall back to `slotProps` for edge cases.
+- v2 components generally accept `sx` on the root (either explicitly or via extended MUI props).
+- Icon glyphs are consumer-supplied ReactNodes (usually MUI icons or SVG). Icon slots typically expect the glyph to inherit `currentColor`.
+- Every v2 component is designed to render under a v2-enabled theme provider — behaviour outside a v2 theme is not defined.
+- When a design needs anchoring, portalling, or click-away (Dropdown, tooltip-like overlays), wrap the v2 content inside an MUI `Popover` / `Popper` / `Modal`. See `references/v2-usage-examples.md`.
+
+## Inline detail (spec pending)
+
+The following v2 components don't yet have a `.figma-spec.md` in `hiver-ui-kit`. The blocks below carry just enough prop / slot detail to compose them. When the spec ships, replace the block with the cross-repo pointer.
+
+### `Dropdown` (container + compound sub-exports)
+
+Visual container only — does **not** manage open/close state, anchoring, portalling, or focus. Wire it inside an MUI `<Popover>` / `<Popper>` and drive open state yourself.
+
+`Dropdown` (or `Dropdown.Menu`) — the paper surface:
+- `title?: ReactNode` — header title (mutually exclusive with `showSearch`; `showSearch` wins).
+- `endAction?: ReactNode` — trailing icon in the title row (ignored when `showSearch` is set).
+- `showSearch?: boolean` — replaces title with an internal v2 `<Input size="sm">` search field; configure via `slotProps.search`.
+- `children: ReactNode` — body slot (typically a stack of `<Dropdown.ListItem>`).
+- `showFooter?: boolean` — footer with internally-mounted Cancel + Confirm buttons; configure via `slotProps.cancelButton` / `slotProps.confirmButton`.
+- `elevation?: 'md' | 'none'` — default `'md'`.
+- `minWidth?: number | string` — floor for container width.
+- `maxHeight?: number | string` — caps the body slot; header + footer stay fixed.
+- `sx?: SxProps<Theme>` — escape hatch on the root paper.
+- `slotProps?: { header, title, search, slot, footer, cancelButton, confirmButton }`.
+
+`Dropdown.ListItem` — single clickable row with up to 8 optional slots + a label:
+- DOM order (fixed, left → right): `startCheckbox` · `startRadio` · `startAppsIcon` · `startAvatar` · `startIcon` · label · `endStatusIcon` · `endIcon` · `endCheckbox`.
+- Boolean toggles: `startCheckbox?`, `startRadio?`, `startAppsIcon?`, `startAvatar?`, `startIcon?`, `endStatusIcon?`, `endIcon?`, `endCheckbox?`.
+- `children: ReactNode` — label rendered inside `<Typography variant="body_sm_medium">` (single-line ellipsis).
+- `slotProps?: { root, startCheckbox, startRadio, startAppsIcon, startAvatar, startIcon, label, endStatusIcon, endIcon, endCheckbox }`.
+- Checkbox / Radio slots mount v2 `<Checkbox size="sm">` / `<Radio size="sm">` internally — pass `{ checked, onChange }` via the corresponding `slotProps.*Checkbox` / `slotProps.startRadio`.
+- Icon-hosting slots (`startAppsIcon`, `startIcon`, `endStatusIcon`, `endIcon`) render a 20 × 20 wrapper — pass the glyph via `slotProps.<slot>.icon`.
+
+### `Breadcrumbs`
+
+- `items: BreadcrumbItem[]` — ordered root → leaf; last entry rendered as "current" (`aria-current="page"`, semibold, `text.neutral.strong`).
+- `BreadcrumbItem = { label: ReactNode; href?: string; onClick?: (e) => void; key?: string | number }` — `href` → `<a>`, `onClick` (no `href`) → `<button>`, neither → static `<span>`.
+- `maxItems?: number` — collapse middle items into an overflow indicator when `items.length > maxItems`.
+- `itemsBeforeCollapse?: number` — default `1`.
+- `itemsAfterCollapse?: number` — default `2`.
+- `onOverflowClick?: (e: MouseEvent<HTMLButtonElement>) => void` — when set, overflow renders as a focusable `<button>`.
+- `separator?: ReactNode` — default 14px slash SVG in `foreground['neutral-bold'].strong`.
+- `slotProps?: { root, list, item, currentItem, separator, overflow }`.
+
+### `Input.Text`
+
+- `size?: 'sm' | 'md' | 'lg'`.
+- `label?: ReactNode` — sibling above the field (not a notched legend).
+- `helperText?: ReactNode` — bottom-row left side.
+- `error?: boolean`, `required?: boolean`.
+- `prefix?: ReactNode` — left adornment; string values render Inter Regular 14/20 in `text.neutral.soft`, ReactNode renders as-is.
+- `suffix?: ReactNode` — right adornment; same rendering rules as `prefix`.
+- `showCounter?: boolean` / `counterText?: string` — bottom-row right side (e.g. `"0/100"`).
+- `slotProps?: { root, label, field, input, prefix, suffix, helper, counter }`.
+- Single-line only — `multiline`, `rows`, `select` are stripped from the v2 API.
+
+## Missing a spec? Extract one.
+
+If you're implementing a v2 design against a component whose spec is marked "pending" above, run the `v2-figma-extract` skill inside the `hiver-ui-kit` repo on the corresponding Figma selection. That produces the `.figma-spec.md` and lets you delete the inline block.

package/collections/web/skills/build-component/references/v2-usage-examples.md

@@ -0,0 +1,23 @@
+# v2 usage examples
+
+Load this before composing common v2 shapes. It captures repo-agnostic patterns for combining v1 chrome primitives (Popover / Modal / Popper / Tooltip / Stack / Box) with v2 content components (Dropdown, Button, IconButton, InlineSelectLabel, Avatar, Input, Tag).
+
+## Patterns to internalise
+
+- **v1 chrome, v2 content.** For modals, popovers, portalled surfaces — v1 primitives (`Modal`, `Popover`, `Popper`, `Tooltip`, `Stack`, `Box`) provide behaviour (anchoring, focus trap, click-away, layout). v2 provides the visible surface + interactive content (`Dropdown`, `Button`, `IconButton`, `InlineSelectLabel`, `Avatar`, `Input`, `Tag`).
+- **Neutralise v1 `Popover` chrome when placing a v2 Dropdown inside it.** Pass `PaperProps={{ elevation: 0, sx: { backgroundColor: 'transparent', boxShadow: 'none', overflow: 'visible' } }}` so the v2 Dropdown's shadow is the only visible surface.
+- **Icon inputs to v2 components.** v2 icon-hosting components (`IconButton`, `Dropdown.ListItem`'s icon slots, `Avatar type="icon"`) accept raw SVG components, MUI icons, or `<img>` tags as children / `slotProps.<slot>.icon`. Icon slots typically expect the glyph to inherit `currentColor`.
+- **Disabled / loading gate.** Composers gate the primary CTA via `disabled`; secondary controls stay interactive.
+- **Inline field trigger + Popover.** Use v2 `InlineSelectLabel` as the trigger (icon / avatar + label + `+N`) and open a searchable popover with v2 `Dropdown` inside a v1 `Popover`. Render v2 `Avatar` (`type="picture" \| "initials" \| "icon"`, `size="2xs"`) for each user row.
+- **Modal shell.** v1 `Modal` chrome around v2 `Button` (destructive) + v2 `IconButton` (close X). v1 `Stack` / `Typography` / `icons` handle layout + copy. Backdrop click / X / Esc all route through the same cancel handler.
+- **Toolbar / composer row.** Horizontal toolbar: v1 `Stack` + `Tooltip` + `Box` around v2 `IconButton` (SVG glyph passed as child) + v2 `Button` for the primary CTA. Left cluster stays enabled; right primary reflects a disabled gate.
+
+## Discoverable examples
+
+TODO: fill in with real file references from the web repo as v2 consumers land.
+
+Until then, grep the web repo for `@hiver/hiver-ui-kit/v2` to find live examples:
+
+```sh
+grep -rl "@hiver/hiver-ui-kit/v2" src/
+```

package/collections/web/skills/build-component/typography/variants.md

@@ -2,9 +2,11 @@
 
 Map Figma text styles to `<Typography variant="...">`. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
 
-**Font families:**
-- Legacy variants (`h1_*`–`h5_*`, `body0_5_*`–`body4_*`, `caption1_*`, `caption2_*`, `overline_medium`, `overline_semiBold`, `buttonLarge`/`buttonMedium`/`buttonSmall`, `chip`) use **Open Sans**.
-- 2026 tokens (`body_lg_*`–`body_xs_*`, `heading_lg_*`–`heading_sm_*`, `display_lg_*`/`display_md_*`, `caption_regular`/`caption_medium`, `overline_regular`) use **Inter**.
+Two variant sets live in the theme:
+- **v1 variants** (below) — font family **Open Sans**, names like `h2_medium`, `body1_regular`.
+- **v2 variants** (bottom of file) — font family **Inter**, names like `heading_md_semiBold`, `body_md_regular`.
+
+Match the Figma text style against both sets; use the variant whose fontSize/weight matches. When the match lands on a v2 variant, the design is v2 — pair it with v2 components (`@hiver/hiver-ui-kit/v2`).
 
 ## Heading variants
 
@@ -72,9 +74,21 @@ Map Figma text styles to `<Typography variant="...">`. Match by fontSize + fontW
 | `buttonSmall` | 12 | 500 | 20px | 0.4px |
 | `chip` | 12 | 500 | 12px | 0.4px |
 
-## Typography 2026 tokens (Inter)
+## Usage
+
+```jsx
+<Typography variant="h2_medium">Section title</Typography>
+<Typography variant="body1_regular">Body text</Typography>
+<Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+```
 
-Canonical 2026 design tokens. Use these for new UI built against the 2026 design system. Font family is **Inter**.
+**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match.
+
+---
+
+## v2 variants
+
+Font family **Inter**. Naming: `body_<size>_<weight>`, `heading_<size>_<weight>`, `display_<size>_<weight>`, `caption_<weight>`, `overline_<weight>`. Weight suffix → numeric weight: `regular` = 400, `medium` = 500, `semiBold` = 600, `bold` = 700.
 
 ### Display
 
@@ -113,27 +127,26 @@ Canonical 2026 design tokens. Use these for new UI built against the 2026 design
 | `body_xs_medium` | 12 | 500 | 18px | -0.005em |
 | `body_xs_semiBold` | 12 | 600 | 18px | -0.005em |
 
-### Caption & overline (2026)
+### Caption & overline
 
 | Variant | fontSize | fontWeight | lineHeight | letterSpacing | Notes |
 |---------|----------|------------|------------|---------------|-------|
 | `caption_regular` | 12 | 400 | 14px | 0.01em | |
 | `caption_medium` | 12 | 500 | 14px | 0.01em | |
 | `overline_regular` | 12 | 400 | 14px | 0.01em | UPPERCASE |
+| `overline_medium` | 12 | 500 | 14px | 0.01em | UPPERCASE |
 
 > Note: a 2026 `overline_medium` token also exists in the theme (Inter, 12 / 500 / 14px / 0.01em / UPPERCASE) and shares its name with the legacy Open Sans `overline_medium` (11 / 500 / 18px). The 2026 spread is applied after the legacy block, so the Inter version wins at runtime — use accordingly.
 
-## Usage
+### Usage (v2)
 
 ```jsx
-<Typography variant="h2_medium">Section title</Typography>
-<Typography variant="body1_regular">Body text</Typography>
-<Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+// Consumer must import v2 components from '@hiver/hiver-ui-kit/v2' and mount under a v2-enabled provider.
+import { Typography } from '@hiver/hiver-ui-kit/v2';
 
-// 2026 tokens
-<Typography variant="heading_lg_semiBold">Page title</Typography>
+<Typography variant="heading_md_semiBold">Section title</Typography>
 <Typography variant="body_md_regular">Body text</Typography>
-<Typography variant="display_lg_bold">Hero</Typography>
+<Typography variant="caption_medium" color="text.neutral.soft">Caption</Typography>
 ```
 
-**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match. For new 2026 designs, prefer the Inter tokens.
+**Figma → variant (v2):** Match Figma text style fontSize and weight to the tables above. Prefer the exact match; if fontSize matches but weight doesn't, pick the closest weight variant in the same row group.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiver/skills",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Shared Claude Code skills & agents for Hiver teams",
   "type": "module",
   "bin": {