@1money/component-ui 0.0.23 → 0.0.25

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

@@ -1,224 +0,0 @@
----
-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

@@ -1,159 +0,0 @@
-# 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)