@1money/component-ui 0.0.1

package/.agents/skills/1money-component-dev/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: 1money-component-dev
+description: Scaffold and implement new components for @1money/components-ui. Wraps PrimeReact, uses the internal SCSS style system, and follows all library conventions. Use when building components that go INTO the library.
+metadata:
+  short-description: Build new @1money/components-ui library components from Figma designs
+  requires:
+    - spec-write-plan
+---
+
+# 1money-component-dev
+
+## Activation
+
+**Act when**: Building a new component (or major variant) that will be added to `@1money/components-ui`.
+**Goal**: Produce a complete, lint-clean, Storybook-ready component directory following every library convention.
+
+## Resources
+
+*Agent must utilize these references:*
+
+- **Checklist**: `checklist.md`
+- **Style System API**: `references/StyleSystemAPI.md`
+- **Semantic Colors**: `references/SemanticColors.md`
+- **Component Patterns**: `references/ComponentPatterns.md`
+- **Hooks Guide**: `references/HooksGuide.md`
+- **Figma Extraction**: `references/FigmaExtractionChecklist.md`
+- **Planning Skill**: `spec-write-plan` (Plan mode only)
+
+## Inputs
+
+- **Figma URL** (recommended): Design source URL for the component.
+- **Node ID** (optional): Specific Figma frame. If absent, auto-explore top-level frames.
+- **Component Name** (required): PascalCase name for the component (e.g., `Chip`, `ToggleGroup`).
+- **Output Mode** (optional, default=Code): `Code` (implement files) or `Plan` (spec-write-plan document).
+
+## Workflow
+
+### Phase 1 — Confirm & Extract
+
+1. **Confirm Output Mode** *(gate)*: If the user did not explicitly state `Plan` or `Code`, ask now. Default is `Code`.
+
+2. **Confirm Component Name** *(gate)*: Validate the name is PascalCase. Check if a component with the same name already exists in `src/components/` to avoid conflicts.
+
+3. **Extract Figma Design** (if URL provided): Follow `references/FigmaExtractionChecklist.md`.
+   - Call `mcp__figma__get_design_context` to retrieve node structure.
+   - Call `mcp__figma__get_screenshot` when layout or spacing is ambiguous.
+   - Call `mcp__figma__get_variable_defs` to retrieve design tokens.
+   - If no Node ID is provided, call `mcp__figma__get_metadata` to list top-level frames and present them to the user for selection.
+
+### Phase 2 — Analyze & Map
+
+4. **Identify PrimeReact Base**: Determine which `primereact/*` component to wrap. Check the [PrimeReact documentation](https://primereact.org/) for available components and their props. If no suitable PrimeReact base exists, build from scratch using native HTML elements (see `Flex`, `Grid`, `Space`, `Notification`, `Tag` as examples of non-PrimeReact components).
+
+5. **Identify Icons**: When the design includes icons, **always check the existing `Icons` component first** (`src/components/Icons/`):
+   - Read `src/components/Icons/SVGs.tsx` to browse all available icon names and their visual descriptions.
+   - Match Figma icon assets to existing `IconName` entries by comparing shape/purpose (e.g., a chevron-right in Figma → `chevronRight`, a trash icon → `remove`, a copy icon → `copy`).
+   - Use `<Icons name="..." />` with appropriate `size` and `color` props — do not create inline SVGs or import external icon libraries.
+   - If no matching icon exists, flag it to the user and propose either: (a) adding the new icon to `SVGs.tsx` following the existing pattern, or (b) using the closest available alternative.
+   - Import icons as: `import { Icons } from '@/components/Icons';` and the type as `import type { IconName } from '@/components/Icons';`.
+
+6. **Map Design Tokens**: Using `references/StyleSystemAPI.md` and `references/SemanticColors.md`, map every visual value from the Figma design to the internal style system:
+   - Colors -> `theme.palette(bg, ...)`, `theme.palette(text, ...)`, `theme.palette(icon, ...)`, `theme.palette(border, ...)` (semantic — preferred for all new components). When a component has multiple color variants, use the Variant DSL with `variants.om-variant-schema($component, $keys...)` to auto-generate the schema, then define a variants map. See `references/StyleSystemAPI.md` for the full Variant DSL reference and `src/styles/README.md` for semantic color token quick-reference tables.
+   - Spacing -> `theme.spacing(scale, key)`, `theme.spacing(gap, key)`, `theme.spacing(component-padding, key)`, `theme.spacing(section-padding, key)`
+   - Typography -> `@include theme.typography(category, size)` (emits `var()` references to `--om-{cat}-{size}-*` CSS custom properties)
+   - Heights -> `theme.sizing(component-height, key)`
+   - Radius -> `theme.shape(key)`
+   - Shadows -> `theme.shadows(key)` (keys: `0`, `100`, `200`)
+   - Opacity -> `theme.opacity(key)`
+   - **No raw hex, px, or font-family values in SCSS** (except `!important` overrides on third-party styles)
+
+7. **Identify Hooks**: Determine which library hooks the component needs — see `references/HooksGuide.md`:
+   - Controlled/uncontrolled value → `useControlledState`
+   - Event handlers passed to PrimeReact or memoized children → `useEventCallback` or `useMemoizedFn`
+   - Latest value in imperative handles or async callbacks → `useLatest`
+   - State set from async operations → `useSafeState`
+   - Skip-initial-mount effects → `useUpdateEffect`
+   - Import from `@1money/hooks` — never from `@1money/components-ui`.
+
+8. **Define Props Interface**: Design the TypeScript interface following `references/ComponentPatterns.md`:
+   - Extend PrimeReact props with `Omit<PrimeXProps, ...>` to remove conflicting props.
+   - Add `prefixCls?: string` for class name customization.
+   - Use union types for variant props (e.g., `color`, `size`, `variant`).
+   - Add `ref` prop with correct element type.
+   - If the component accepts an icon, type it as `IconName` (imported from `@/components/Icons`) rather than `string` or `ReactNode`.
+
+9. **Identify Missing States**: Proactively identify states not shown in the design but required:
+   - `disabled` — **must follow the Figma design exactly**. Extract disabled colors, opacity, and cursor styles from the Figma file. Do NOT invent or assume disabled styles (e.g., generic opacity or color dimming) — if the Figma design does not specify a disabled state, ask the user for guidance.
+   - `loading` — spinner integration
+   - `hover` / `focus` / `active` — interaction states
+   - `error` / `warning` / `success` — validation states (if applicable)
+
+### Phase 3 — Scaffold & Implement
+
+10. **Create All Component Files**: Generate the complete directory following `references/ComponentPatterns.md` and `checklist.md`. The 8 files are:
+
+   ```
+   src/components/{Name}/
+   ├── {Name}.tsx              # Main component
+   ├── interface.ts            # TypeScript interfaces
+   ├── index.ts                # Barrel export
+   ├── {Name}.stories.tsx      # Storybook stories
+   ├── README.md               # Component documentation
+   ├── style/
+   │   ├── {Name}.scss         # Component styles
+   │   └── index.ts            # Style import
+   └── __test__/
+       └── index.test.tsx      # Snapshot test
+   ```
+
+### Phase 4 — Register Exports
+
+11. **Update Library Barrel** (`src/index.ts`):
+   - Add `export { {Name} } from './components/{Name}';` to the named export block.
+   - Add `export type { {Name}Props } from './components/{Name}';` for the props type.
+
+### Phase 5 — Generate Plan (Plan mode only)
+
+12. **Write Plan**: If output mode is `Plan`, invoke `spec-write-plan` to generate a comprehensive implementation plan:
+    - Save to `docs/plans/YYYY-MM-DD-{name}-component.md`
+    - Include one task per file to create
+    - Include one task per state to implement
+    - Include token mapping table as a reference section
+
+### Phase 6 — Validate
+
+13. **Lint**: Run `pnpm lint` and fix all errors.
+
+14. **Test**: Run `pnpm test` and ensure snapshot tests pass.
+
+15. **Storybook**: Verify the component renders correctly in Storybook (`pnpm dev`).
+
+16. **Self-Review** *(mandatory)*: Walk through `checklist.md` item by item. For each section, verify the implementation against the corresponding reference document:
+    - SCSS values against `references/StyleSystemAPI.md` and `references/SemanticColors.md`
+    - File structure and code patterns against `references/ComponentPatterns.md`
+    - Token mapping completeness against `references/FigmaExtractionChecklist.md` (if Figma was used)
+    - Fix all violations before presenting output to the user.
+
+## Constraints
+
+### SCSS Rules
+
+- **Import**: Always use `@use '@/styles/api' as theme;` and `@use '@/styles/recipes/variants' as variants;` (if using variants).
+- **Architecture**: The API forwards three layers — tokens (raw primitives), theme (CSS var resolvers, typography mixin, breakpoint mixins), and system (`om-sx` — for business code only, not component SCSS).
+- **Component variable**: Define `$component: '{kebab-case-name}';` at the top.
+- **Root selector**: `.#{theme.$prefix}-#{$component}` where `theme.$prefix` is `om-react-ui`.
+- **Color variants**: Use the Variant DSL (`variants.om-variant-schema` + `variants.om-variant-default` + `variants.om-variant-classes` with `$default:` param) — see `references/StyleSystemAPI.md` Variant DSL section.
+- **Size variants**: Use `&-{size}` nesting (e.g., `&-medium`, `&-small`).
+- **Disabled state**: Target `.p-disabled` class (PrimeReact convention). Styles must match the Figma design — do not invent disabled styles. Extract exact colors, opacity, and cursor values from the design file.
+- **No raw values**: Every color, spacing, radius, shadow, font, and height must use a token function.
+- **Color functions**: Use `theme.palette(domain, token)` where domain is `bg`, `text`, `icon`, or `border`.
+
+### TypeScript Rules
+
+- **Interface over type**: Use `interface` for all object structures.
+- **No `any`**: Define types precisely.
+- **No `enum`**: Use `as const` arrays + derived union types.
+- **Props naming**: `{Name}Props` (e.g., `ButtonProps`).
+- **Component export**: Named export `export const {Name}` + `export default memo({Name})`.
+
+### Hooks Rules
+
+- **Use library hooks**: For controlled/uncontrolled state, stable callbacks, latest refs, and other common patterns — always use the library's custom hooks. See `references/HooksGuide.md` for the full list.
+- **Import path**: `import { useXxx } from '@1money/hooks'` — never from `@1money/components-ui` or external packages (e.g., `ahooks`).
+- **Controlled/uncontrolled**: Components with `value`/`defaultValue` must use `useControlledState`.
+- **Event handlers**: Use `useEventCallback` for simple handlers (onChange, onClick) or `useMemoizedFn` for render callbacks and complex handlers.
+- **No `useCallback` with stale closures**: Prefer `useEventCallback`/`useMemoizedFn` over manual `useCallback` with long dependency arrays.
+- **Async safety**: Use `useSafeState` instead of `useState` when state may be set after unmount.
+
+### Component Rules
+
+- **Wrap default export in `memo()`**: Every component's default export must be memoized.
+- **PrimeReact imports**: Import directly from `primereact/{component}` — never from `@1money/components-ui`.
+- **classnames utility**: Import `classnames` and `joinCls` from `@/utils/classnames`. The default export is pre-configured with `om-react-ui` prefix.
+- **`prefixCls` prop**: Every component must accept `prefixCls` with a sensible default.
+- **Spread remaining props**: Always `{...rest}` onto the PrimeReact base component.
+
+### Story Rules
+
+- **File**: `{Name}.stories.tsx` in the component directory.
+- **Meta title**: `Components/{Name}`.
+- **Tags**: Include `['autodocs']` on meta.
+- **Import style**: `import './style';` to load SCSS in Storybook.
+- **Variant constants**: Define as `as const` arrays, not inline.
+- **AllVariants story**: Matrix of all size x color/variant combinations with `tags: ['!autodocs', 'dev']`.
+
+### Test Rules
+
+- **Console suppression**: Suppress `Could not parse CSS stylesheet` and `findDOMNode is deprecated` errors.
+- **Lottie mock**: Always mock `lottie-web` if any component in the dependency chain uses it.
+- **Snapshot test**: At minimum, render the component and call `toMatchSnapshot()`.
+
+### Skill Rules
+
+- **Do NOT invoke** the `1money-components-ui` or `figma-1money-codegen` skills during this workflow. This skill is self-contained and already includes all necessary Figma extraction steps and component implementation patterns.
+
+### Icon Rules
+
+- **Reuse first**: Always check existing `Icons` component (`src/components/Icons/SVGs.tsx`) before creating inline SVGs or importing external icon libraries.
+- **Import**: `import { Icons } from '@/components/Icons';` and `import type { IconName } from '@/components/Icons';`.
+- **Usage**: `<Icons name="iconName" size={24} />` — never embed raw `<svg>` elements for icons that already exist.
+- **Icon props**: When a component accepts an icon, type it as `IconName` (not `string` or `ReactNode`). Use `<Icons name={iconProp} />` to render.
+- **Missing icons**: If a needed icon doesn't exist, flag it to the user before adding to `SVGs.tsx`.
+- **Color**: Use the `color` prop on `<Icons>` and bind it to a semantic token via CSS `var()` or pass a style-system value.
+
+## Anti-Patterns
+
+- Importing from `@1money/components-ui` inside the library itself
+- Using inline SVGs or external icon libraries (e.g., `react-icons`, `lucide-react`) when the icon already exists in the `Icons` component
+- Using `Foundation` tokens or consumer-facing SCSS imports
+- Using `om-sx` mixin in component SCSS (that's for business code layout, not component internals)
+- Using flat namespace `@use '@/styles/api' as *` — always use namespaced `@use '@/styles/api' as theme`
+- Using old function names like `om-bg()`, `om-text()`, `om-spacing()`, `om-radius()`, `om-shadow()`, `om-component-height()`, `om-gap()`, `om-component-padding()`, `om-opacity()` — always use `theme.palette()`, `theme.spacing()`, `theme.shape()`, `theme.shadows()`, `theme.sizing()`, `theme.opacity()` instead
+- Writing manual `&-{variant}` blocks for color variants instead of using the Variant DSL (`variants.om-variant-schema` + `variants.om-variant-default` + `variants.om-variant-classes`)
+- Hand-writing variant schema maps instead of using `variants.om-variant-schema($component, $keys...)`
+- Hardcoding colors, spacing, or fonts instead of using token functions
+- Using old shadow keys (`1`, `2`, `3`) instead of the current scale (`0`, `100`, `200`)
+- Creating `.css` files instead of `.scss`
+- Skipping the barrel export update in `src/index.ts`
+- Forgetting `memo()` on the default export
+- Using `useState` + manual `useCallback` when `useControlledState` + `useEventCallback` would suffice
+- Importing hooks from `@1money/components-ui` or external packages (`ahooks`, `react-use`) instead of `@1money/hooks`
+- Using raw `useState` for async-set state (use `useSafeState` to prevent unmount leaks)
+- Writing `useCallback` with long dependency arrays instead of `useEventCallback` / `useMemoizedFn`
+- Invoking `1money-components-ui` or `figma-1money-codegen` skills (this skill handles everything)

package/.agents/skills/1money-component-dev/checklist.md

@@ -0,0 +1,159 @@
+# Component Development Checklist
+
+Use this checklist to validate every new `@1money/components-ui` component. Walk through each section before considering the component complete.
+
+## Pre-Implementation
+
+- [ ] Component name is PascalCase
+- [ ] PrimeReact base component identified (or confirmed "from scratch")
+- [ ] Figma design extracted (if URL provided) — see `references/FigmaExtractionChecklist.md`
+- [ ] All Figma tokens mapped to style system functions — see `references/StyleSystemAPI.md`
+- [ ] All icons matched to existing `Icons` component names (check `src/components/Icons/SVGs.tsx` first)
+- [ ] Missing icons flagged to user (if any icon in the design has no match in `Icons`)
+- [ ] Props interface designed with variant union types
+- [ ] All required states identified (disabled, loading, hover, focus, error, etc.)
+- [ ] Output mode confirmed: `Code` or `Plan`
+
+## File Structure
+
+- [ ] `src/components/{Name}/{Name}.tsx` exists
+- [ ] `src/components/{Name}/interface.ts` exists
+- [ ] `src/components/{Name}/index.ts` exists
+- [ ] `src/components/{Name}/{Name}.stories.tsx` exists
+- [ ] `src/components/{Name}/README.md` exists
+- [ ] `src/components/{Name}/style/{Name}.scss` exists
+- [ ] `src/components/{Name}/style/index.ts` exists
+- [ ] `src/components/{Name}/__test__/index.test.tsx` exists
+
+## interface.ts
+
+- [ ] Uses `interface` (not `type`) for props definition
+- [ ] Named `{Name}Props`
+- [ ] Extends PrimeReact props via `Omit<PrimeXProps, ...>` (if wrapping PrimeReact)
+- [ ] Includes `prefixCls?: string`
+- [ ] Includes `ref?: RefObject<HTMLElement | null>` with correct element type
+- [ ] Variant props use union types (e.g., `'primary' | 'secondary'`)
+- [ ] No `any` types
+- [ ] No `enum` — uses `as const` arrays + derived union types for constants
+- [ ] All props documented with JSDoc comments for non-obvious fields
+
+## {Name}.tsx
+
+- [ ] Imports `memo` from `react`
+- [ ] Imports PrimeReact base from `primereact/{component}` (not from `@1money/components-ui`)
+- [ ] Imports `classnames` (default) and `joinCls` from `@/utils/classnames`
+- [ ] Imports type `{Name}Props` from `./interface`
+- [ ] Component is typed as `FC<PropsWithChildren<{Name}Props>>` (or without `PropsWithChildren` if no children)
+- [ ] Destructures props with defaults: `prefixCls = '{kebab-name}'`, variant defaults
+- [ ] Creates `classes` via `classnames(prefixCls)`
+- [ ] Root element uses `classes(void 0, joinCls(classes(variant), classes(size), className))`
+- [ ] Spreads `{...rest}` onto PrimeReact base component
+- [ ] Named export: `export const {Name}: FC<...> = props => { ... }`
+- [ ] Default export: `export default memo({Name})`
+- [ ] Icons use `<Icons name="..." />` from `@/components/Icons` (no inline SVGs or external icon libs)
+- [ ] Icon props typed as `IconName` (from `@/components/Icons`) — not `string` or `ReactNode`
+- [ ] No direct DOM manipulation
+- [ ] Constants extracted (no magic strings)
+
+## Hooks Usage — see `references/HooksGuide.md`
+
+- [ ] Controlled/uncontrolled components use `useControlledState` from `@1money/hooks`
+- [ ] Event handlers use `useEventCallback` or `useMemoizedFn` (not manual `useCallback` with long deps)
+- [ ] Async state updates use `useSafeState` (not raw `useState`)
+- [ ] All hooks imported from `@1money/hooks` (not from `@1money/components-ui` or external packages like `ahooks`)
+- [ ] No `useCallback` with stale closures — `useEventCallback` / `useMemoizedFn` preferred
+- [ ] `useLatest` used when accessing current state in imperative handles or async callbacks
+- [ ] `useUpdateEffect` used when effects should skip initial mount
+
+## SCSS (`style/{Name}.scss`)
+
+- [ ] First line: `@use '@/styles/api' as theme;`
+- [ ] Second line (if using variants): `@use '@/styles/recipes/variants' as variants;`
+- [ ] `$component: '{kebab-name}';` defined
+- [ ] Root selector: `.#{theme.$prefix}-#{$component}`
+- [ ] All colors use `theme.palette(bg, ...)`, `theme.palette(text, ...)`, `theme.palette(icon, ...)`, `theme.palette(border, ...)`
+- [ ] All spacing uses `theme.spacing(scale, key)`, `theme.spacing(gap, key)`, `theme.spacing(component-padding, key)`, or `theme.spacing(section-padding, key)`
+- [ ] All border-radius uses `theme.shape(key)`
+- [ ] All box-shadow uses `theme.shadows(key)` (keys: 0/100/200)
+- [ ] All heights use `theme.sizing(component-height, key)`
+- [ ] All opacity uses `theme.opacity(key)`
+- [ ] Typography uses `@include theme.typography(category, size)` (emits `var(--om-{cat}-{size}-*)` references)
+- [ ] No raw hex values (e.g., `#073387`)
+- [ ] No raw pixel values for design tokens (e.g., `16px` for spacing)
+- [ ] No raw font-family declarations
+- [ ] No old function names (`om-bg`, `om-text`, `om-spacing`, `om-radius`, etc.) — use `theme.*` namespaced functions
+- [ ] Color variants use the Variant DSL (`variants.om-variant-schema` + `variants.om-variant-default` + `variants.om-variant-classes`)
+- [ ] Variant schema generated via `variants.om-variant-schema($component, $keys...)` (not hand-written)
+- [ ] Variant schema variable named `$component-variant-schema`
+- [ ] Variants map variable named `$component-variants`
+- [ ] All variant names are quoted strings (e.g., `'primary'`, `'white'`)
+- [ ] `variants.om-variant-default` called with default variant name
+- [ ] `variants.om-variant-classes` called with `$default:` param to skip the default variant
+- [ ] Base styles consume variant values via `var(--om-{component}-{key})`
+- [ ] Size variants use `&-{size}` nesting (not the Variant DSL)
+- [ ] Disabled state targets `.p-disabled` (PrimeReact convention)
+- [ ] Hover states use `&:hover:not(.p-disabled)`
+- [ ] Responsive styles use `@include theme.down()` (if needed)
+
+## style/index.ts
+
+- [ ] Single line: `import './{Name}.scss';`
+
+## index.ts
+
+- [ ] Imports default export: `import {Name} from './{Name}';`
+- [ ] Re-exports named: `export { {Name} } from './{Name}';`
+- [ ] Re-exports default: `export default {Name};`
+- [ ] Re-exports types: `export * from './interface';`
+
+## Stories (`{Name}.stories.tsx`)
+
+- [ ] Imports from `@storybook/react` (`Meta`, `StoryObj`)
+- [ ] Imports `fn` from `@storybook/test` for action handlers
+- [ ] Imports component from `./index`
+- [ ] Imports styles: `import './style';`
+- [ ] Variant constants defined as `as const` arrays
+- [ ] Meta has `title: 'Components/{Name}'`
+- [ ] Meta has `component: {Name}`
+- [ ] Meta has `tags: ['autodocs']`
+- [ ] Meta has `argTypes` with controls for all variant props
+- [ ] Meta has `args` with sensible defaults
+- [ ] `AllVariants` story exists with `tags: ['!autodocs', 'dev']` — shows matrix of all variants
+- [ ] At least one additional story demonstrating key features (e.g., `WithIcons`, `Sizes`)
+- [ ] Type alias: `type Story = StoryObj<typeof {Name}>;`
+
+## Tests (`__test__/index.test.tsx`)
+
+- [ ] Imports `jsdom-global/register`
+- [ ] Imports `render` from `@testing-library/react`
+- [ ] Imports `@testing-library/jest-dom`
+- [ ] Console error suppression for `Could not parse CSS stylesheet` and `findDOMNode is deprecated`
+- [ ] Mocks `lottie-web` (if component dependency chain includes it)
+- [ ] `describe('{Name}')` block
+- [ ] At least one `it('renders correctly')` with `toMatchSnapshot()`
+
+## README.md
+
+- [ ] Component name as heading
+- [ ] Brief description of purpose
+- [ ] Import example
+- [ ] Basic usage example
+- [ ] Props table with name, type, default, and description columns
+
+## Library Registration
+
+- [ ] `export { {Name} } from './components/{Name}';` added to `src/index.ts`
+- [ ] `export type { {Name}Props } from './components/{Name}';` added to `src/index.ts`
+
+## Validation
+
+- [ ] `pnpm lint` passes with no errors
+- [ ] `pnpm test` passes (snapshots created/updated)
+- [ ] Component renders in Storybook (`pnpm dev`)
+- [ ] All variant combinations visually verified in Storybook
+- [ ] Self-review: every SCSS value cross-checked against `StyleSystemAPI.md` / `SemanticColors.md`
+- [ ] Self-review: file structure and code patterns cross-checked against `ComponentPatterns.md`
+- [ ] Self-review: no raw hex, px (for tokens), or font-family values in SCSS
+- [ ] Self-review: no inline SVGs or external icon libraries — all icons use `<Icons name="..." />`
+- [ ] Self-review: hooks usage cross-checked against `HooksGuide.md` (correct hook for each pattern)
+- [ ] Self-review: no anti-patterns present (see SKILL.md Anti-Patterns section)