@hiver/skills 1.0.1 → 1.0.3

package/collections/extension/skills/write-test-cases/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: write-test-cases
+description: Writes structured behavioural test cases for a milestone into a progress-sheet markdown file. Invoked by build-milestone before any implementation begins (Normal Mode) or once per feedback round (Fix Mode). Never writes source code.
+---
+
+# Write Test Cases
+
+Generates a complete set of structured behavioural test cases for a milestone and saves them as a progress sheet that `build-milestone` uses to drive its TDD loop.
+
+## When to Use
+
+- Invoked by `build-milestone` at the start of **Normal Mode** — before any implementation begins
+- Invoked by `build-milestone` at the start of **Fix Mode** — once per feedback round, scoped to the feedback
+
+## Inputs
+
+- Path to the milestone document (always required)
+- Mode: `normal` or `feedback`
+- If `feedback` mode: path to the feedback file
+
+## Instructions
+
+### Normal Mode
+
+1. Read the milestone document thoroughly. Extract:
+   - Goal
+   - Acceptance criteria (2–3 product-level "done" conditions)
+   - Architectural approach and high-level areas affected
+
+2. Explore the codebase **scoped strictly to the "High-level areas affected" section of the milestone doc**. Read only the files and directories explicitly named there. Do NOT fan out to unrelated modules. Limit reads to what is minimally needed to understand current state — what exists, what doesn't, what will change.
+
+3. If the milestone doc contains Figma design links, load them using the Figma MCP tool. Analyze the designs to identify UI-specific behaviours and edge cases. Load only the specific nodes linked — do not traverse the full Figma file.
+
+4. Derive test cases from the acceptance criteria and your codebase exploration. For each observable behaviour the milestone introduces or changes, write one test case. Aim for full coverage across:
+   - Happy path (primary user flows)
+   - Edge cases (boundary conditions, empty states, large data)
+   - Error states (API failures, invalid input, permission issues)
+   - Regressions (existing behaviours that must not break)
+
+5. Write ALL test cases to `milestone-tests/<milestone-name>-tests.md` — create the file if it doesn't exist. All test cases start with `⬜ Pending` status.
+
+6. Use this format for every test case:
+
+```markdown
+## TC-001 | Category: happy-path | ⬜ Pending
+Given: <system or state precondition>
+When:  <user action or system trigger>
+Then:  <observable outcome — what the user sees or what changes in state>
+```
+
+7. After writing all test cases, exit. Do not write any source code.
+
+---
+
+### Feedback Mode
+
+1. Read the milestone document to understand the original scope.
+
+2. Read the feedback file. Identify the **active** (non-stale) feedback entry.
+
+3. Explore the codebase to understand the current state of the implementation for this milestone.
+
+4. Derive test cases scoped **only** to what the feedback describes. Write as many as needed to fully cover the feedback — happy path, edge cases, and regressions relevant to the fix.
+
+5. Append the new test cases to the existing `milestone-tests/<milestone-name>-tests.md` under a new section:
+
+```markdown
+## Feedback Round N
+
+### FTC-001 | Category: regression | ⬜ Pending
+Given: <precondition>
+When:  <action>
+Then:  <expected outcome>
+```
+
+Where `N` is incremented from the last existing Feedback Round number in the file.
+
+6. After appending, exit. Do not write any source code.
+
+---
+
+## Output
+
+A `milestone-tests/<milestone-name>-tests.md` file (created or appended) with all new test cases set to `⬜ Pending`.
+
+The `milestone-tests/` directory lives alongside the `milestones/` directory under the same parent.
+
+## Rules
+
+- NEVER write source code
+- NEVER mark any test case as passing — all new TCs start as `⬜ Pending`
+- NEVER modify existing test case entries — only append new ones
+- In Feedback Mode, only write TCs scoped to the active feedback — do not add unrelated cases

package/collections/web/skills/build-component/references/icons.md

@@ -1,8 +1,81 @@
 # Icons
 
-- **Use MUI icons only** - import from `@mui/icons-material` or `@hiver/hiver-ui-kit` icons
-- **For SVG icons**: Import SVG files directly and use them in `<img>` tags
-  - Import SVG files: `import iconName from 'path/to/icon.svg'`
-  - Use in component: `<img src={iconName} alt="description" />`
-  - Example: `import AILogo from '../assets/ai_logo.svg'` then `<img src={AILogo} alt="AI Copilot" />`
-- **Do not import icons from other packages** (no FontAwesome, Heroicons, etc.)
+How to import from `@hiver/hiver-ui-kit`:
+
+```js
+import { brandIcons, icons } from '@hiver/hiver-ui-kit';
+// <brandIcons.Star />
+// <icons.AccountCircle />
+```
+
+## Resolution priority
+
+When a Figma design contains an icon, resolve it in this order:
+
+1. **User-provided SVG asset** — if the user supplied an `.svg` file, import it directly:
+   ```js
+   import iconName from 'path/to/icon.svg';
+   <img src={iconName} alt="description" />
+   ```
+2. **`brandIcons`** — Hiver-designed icons (see "Brand icon catalog" below).
+3. **`icons`** — curated MUI icons re-exported from hui-kit (see "MUI icon catalog" below).
+4. **`@mui/icons-material`** — **last resort only**, when the icon is not in the design system **and** the user has not provided an asset.
+5. **Never** import icons from FontAwesome, Heroicons, or any other third-party icon library.
+
+## How to match a Figma icon to a code name
+
+1. **Prefer the Figma layer/component name** if the design exposes one (e.g. a layer named `Brand/Star` → `brandIcons.Star`).
+2. **Otherwise, match visually** against the catalog sheets embedded below. Each icon is rendered with its exact export name underneath.
+3. The export name is what you use in code — including any typos preserved from the design system (see Notes).
+
+## Brand icon catalog (`brandIcons`)
+
+![Brand icons catalog](./icons/brand-icons.png)
+
+**Hiver Logo**
+- `Logo`
+
+**Brand icons** (box 20×20, live area 18×18, stroke 1.4)
+- `SharedMailbox`, `Analytics`, `EmailTemplates`, `Settings`, `HiverAlerts`, `Activity`, `AutoAssignment`, `Workload`, `Lable`, `Permalink`
+- `Star`, `Edit`, `Filters`, `HiverChat`, `AircallPhone`, `Aavatar`, `Unassigned`, `Mine`, `Team`, `Pending`
+- `Closed`, `Tags`, `Crown`, `Dashboard`, `DashboardInactive`, `SharedInboxNav`, `SharedInboxNavInactive`, `SharedLabel`, `SharedLabelInactive`, `KnowledgeBase`
+- `KnowledgeBaseInactive`, `Connector`, `ConnectorInactive`, `SettingsNav`, `SettingsNavInactive`, `UserRole`, `UserRoleInactive`
+
+**Activity icons** (box 20×20, live area 16×16, stroke 1.4)
+- `Status`, `Tag`, `Inbox`, `AlertTriangle`, `EnvelopeDownload`, `ActivityStar`, `EnvelopeUpload`, `Envelope`, `ActivityEdit`, `CloseCircle`, `CheckAction`, `UserCheck`
+
+**Settings icons** (box 24×24, live area 22×22, stroke 1.4)
+- `AdminPanel`, `Sliders`, `Compass`, `SwitchAccount`, `Gift`, `MessageCircle`, `LifeBuoy`
+
+## MUI icon catalog (`icons`)
+
+![MUI icons catalog](./icons/mui-icons.png)
+
+- `AccountCircle`, `Add`, `Alarm`, `Close`, `Phone`, `ArchiveOutlined`, `ArrowBack`, `ArrowBackIos`, `ArrowDropDown`, `ArrowDropUp`, `ArrowForward`
+- `ArrowOutward`, `CalendarToday`, `CalendarTodayOutlined`, `CalendarTodayOutlinedIcon`, `Cancel`, `CancelOutlined`, `CheckCircle`, `ChevronRightOutlined`, `CodeSharp`, `DeleteOutline`, `DownloadOutlined`
+- `DragIndicator`, `EditOutlined`, `Error`, `ErrorOutline`, `GroupsOutlined`, `InfoOutlined`, `LabelOutlined`, `Link`, `LockOutlined`, `MailOutlined`, `MicNone`
+- `MoreVert`, `NotificationsOutlined`, `OpenInNew`, `Pause`, `PersonOutline`, `PersonOutlined`, `PlayArrow`, `Public`, `Search`, `Settings`, `SettingsOutlined`
+- `StickyNote2Outlined`, `ThumbDownAlt`, `ThumbDownOffAlt`, `ThumbUpAlt`, `ThumbUpOffAlt`, `TimerOutlined`, `TrackChanges`, `UnarchiveOutlined`, `Voicemail`, `Warning`, `WarningAmber`
+- `ArrowRightAlt`, `Delete`, `Email`, `Favorite`
+
+## Notes — Figma → code gotchas
+
+- **Typos preserved in exports** — these match the Figma names, so map literally; do not auto-correct:
+  - `Lable` (not `Label`)
+  - `Aavatar` (not `Avatar`)
+- **`Edit` collision** — three similar icons:
+  - `brandIcons.Edit` — pen-on-paper brand icon (yellow accent)
+  - `brandIcons.ActivityEdit` — green envelope with a pen, activity style
+  - `icons.EditOutlined` — plain MUI outlined pencil
+- **`Settings` collision** — five similar names:
+  - `brandIcons.Settings`, `brandIcons.SettingsNav`, `brandIcons.SettingsNavInactive`
+  - `icons.Settings`, `icons.SettingsOutlined`
+  Pick by Figma category section and visual.
+- **`Star` collision**:
+  - `brandIcons.Star` — yellow filled brand star
+  - `brandIcons.ActivityStar` — purple activity star
+- **`Tag` vs `Tags`**:
+  - `brandIcons.Tags` — brand (plural, box 20×20 live 18×18)
+  - `brandIcons.Tag` — activity (singular, box 20×20 live 16×16)
+- **Inactive variants** — many brand icons have `*Inactive` siblings (`DashboardInactive`, `SharedInboxNavInactive`, `SharedLabelInactive`, `KnowledgeBaseInactive`, `ConnectorInactive`, `SettingsNavInactive`, `UserRoleInactive`). Use the inactive variant for the unselected/disabled state of a nav item.
+- **`UserCheck`** — present in `brandIcons` exports but not visible on the current Figma sheet. Use it if a design clearly needs it; otherwise prefer the activity-style icons documented above.

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

@@ -1,6 +1,10 @@
 # Typography reference (`@hiver/hiver-ui-kit`)
 
-Map Figma text styles to `<Typography variant="...">`. Font family is **Open Sans**. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
+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**.
 
 ## Heading variants
 
@@ -68,12 +72,68 @@ Map Figma text styles to `<Typography variant="...">`. Font family is **Open San
 | `buttonSmall` | 12 | 500 | 20px | 0.4px |
 | `chip` | 12 | 500 | 12px | 0.4px |
 
+## Typography 2026 tokens (Inter)
+
+Canonical 2026 design tokens. Use these for new UI built against the 2026 design system. Font family is **Inter**.
+
+### Display
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `display_lg_semiBold` | 28 | 600 | 36px | 0.01em |
+| `display_lg_bold` | 28 | 700 | 36px | 0.01em |
+| `display_md_semiBold` | 24 | 600 | 32px | 0.01em |
+| `display_md_bold` | 24 | 700 | 32px | 0.01em |
+
+### Heading
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `heading_lg_medium` | 20 | 500 | 28px | -0.005em |
+| `heading_lg_semiBold` | 20 | 600 | 28px | -0.005em |
+| `heading_md_medium` | 18 | 500 | 28px | -0.005em |
+| `heading_md_semiBold` | 18 | 600 | 28px | -0.005em |
+| `heading_sm_medium` | 16 | 500 | 22px | -0.005em |
+| `heading_sm_semiBold` | 16 | 600 | 22px | -0.005em |
+
+### Body
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `body_lg_regular` | 16 | 400 | 24px | -0.005em |
+| `body_lg_medium` | 16 | 500 | 24px | -0.005em |
+| `body_lg_semiBold` | 16 | 600 | 24px | -0.005em |
+| `body_md_regular` | 14 | 400 | 20px | -0.005em |
+| `body_md_medium` | 14 | 500 | 20px | -0.005em |
+| `body_md_semiBold` | 14 | 600 | 20px | -0.005em |
+| `body_sm_regular` | 13 | 400 | 19px | -0.005em |
+| `body_sm_medium` | 13 | 500 | 19px | -0.005em |
+| `body_sm_semiBold` | 13 | 600 | 19px | -0.005em |
+| `body_xs_regular` | 12 | 400 | 18px | -0.005em |
+| `body_xs_medium` | 12 | 500 | 18px | -0.005em |
+| `body_xs_semiBold` | 12 | 600 | 18px | -0.005em |
+
+### Caption & overline (2026)
+
+| 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 |
+
+> 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
 
 ```jsx
 <Typography variant="h2_medium">Section title</Typography>
 <Typography variant="body1_regular">Body text</Typography>
 <Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+
+// 2026 tokens
+<Typography variant="heading_lg_semiBold">Page title</Typography>
+<Typography variant="body_md_regular">Body text</Typography>
+<Typography variant="display_lg_bold">Hero</Typography>
 ```
 
-**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match.
+**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.

package/package.json

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