@1money/component-ui 0.0.1

package/.agents/skills/1money-component-dev/references/ComponentPatterns.md

@@ -0,0 +1,478 @@
+# Component Patterns Reference
+
+Annotated templates for all 8 files in a `@1money/components-ui` component directory. Based on the canonical `Button` component.
+
+Replace `{Name}` with PascalCase name (e.g., `Chip`) and `{kebab-name}` with kebab-case (e.g., `chip`).
+
+---
+
+## 1. `{Name}.tsx` — Main Component
+
+```tsx
+// ---- Imports ----
+import { memo } from 'react';
+// Import the PrimeReact base component directly from primereact/*
+import { PrimeComponent as PrimeBase } from 'primereact/{component}';
+// Import internal components if needed (e.g., Spinner for loading states)
+import Spinner from '@/components/Spinner';
+// Import classnames utility — default export is pre-configured with 'om-react-ui' prefix
+import { default as classnames, joinCls } from '@/utils/classnames';
+// Import types separately using `import type`
+import type { FC, PropsWithChildren } from 'react';
+import type { {Name}Props } from './interface';
+
+// ---- Constants ----
+// Extract magic strings/numbers as named constants
+const SOME_CONSTANT = '5';
+
+// ---- Component ----
+// Named export with explicit FC typing
+// Use PropsWithChildren<> if the component accepts children, otherwise just {Name}Props
+export const {Name}: FC<PropsWithChildren<{Name}Props>> = props => {
+  // Destructure with defaults
+  // - prefixCls defaults to kebab-case component name
+  // - Variant props get sensible defaults
+  // - ref is destructured but aliased to _ref (forwarded via PrimeReact's own ref handling)
+  // - ...rest captures all remaining PrimeReact props
+  const {
+    children,
+    className = '',
+    prefixCls = '{kebab-name}',
+    color = 'primary',
+    size = 'medium',
+    ref: _ref,
+    ...rest
+  } = props;
+
+  // Create class generator — returns a function: (suffix?, className?) => string
+  const classes = classnames(prefixCls);
+
+  return (
+    <PrimeBase
+      // Spread remaining props FIRST so our overrides take precedence
+      {...rest}
+      // Build root className:
+      // - classes(void 0, ...) generates the root class: `.om-react-ui-{kebab-name}`
+      // - joinCls combines variant classes and external className
+      className={classes(
+        void 0,
+        joinCls(classes(color), classes(size), className),
+      )}
+    >
+      {children}
+    </PrimeBase>
+  );
+};
+
+// Default export MUST be wrapped in memo()
+export default memo({Name});
+```
+
+### `classnames` Utility Explained
+
+```ts
+import { default as classnames, joinCls } from '@/utils/classnames';
+
+// classnames is a curried function:
+// classnames(prefix) returns a class generator
+
+const classes = classnames('button');
+// classes is now: (suffix?, className?) => string
+
+classes(void 0)           // → 'om-react-ui-button'
+classes('primary')        // → 'om-react-ui-button-primary'
+classes('icon-start')     // → 'om-react-ui-button-icon-start'
+classes(void 0, 'extra')  // → 'om-react-ui-button extra'
+classes('sm', 'extra')    // → 'om-react-ui-button-sm extra'
+
+// joinCls concatenates non-falsy class strings
+joinCls(classes('primary'), classes('large'), className)
+// → 'om-react-ui-button-primary om-react-ui-button-large my-custom'
+```
+
+---
+
+## 2. `interface.ts` — TypeScript Interfaces
+
+```ts
+import type { ReactNode, RefObject } from 'react';
+// Import PrimeReact component props
+import type { PrimeComponentProps } from 'primereact/{component}';
+
+// Use Omit<> to remove PrimeReact props that conflict with our custom API
+// Common removals: 'label', 'severity', 'size', 'icon', 'className'
+export interface {Name}Props extends Omit<PrimeComponentProps, 'label' | 'severity' | 'size'> {
+  // Ref prop with the correct HTML element type
+  ref?: RefObject<HTMLButtonElement | null>;
+
+  // Class name prefix — allows consumers to customize the BEM namespace
+  prefixCls?: string;
+
+  // Variant props as union types
+  color?: 'primary' | 'secondary' | 'grey' | 'black' | 'white' | 'danger' | 'warning';
+  size?: 'large' | 'medium' | 'small';
+
+  // Slot props for custom content
+  iconStart?: ReactNode;
+  iconEnd?: ReactNode;
+}
+```
+
+### Rules
+
+- Always use `interface` (not `type`) for object structures
+- Name: `{Name}Props`
+- Extend PrimeReact props with `Omit<>` to avoid conflicts
+- Use `ReactNode` for slot props, not `JSX.Element`
+- Use `RefObject<HTMLElement | null>` for ref props
+- Use literal union types for variant props (never `enum`)
+- If variant values are also used in stories, define them as `as const` arrays in the stories file, not here
+
+---
+
+## 3. `index.ts` — Barrel Export
+
+```ts
+import {Name} from './{Name}';
+
+export { {Name} } from './{Name}';
+
+export default {Name};
+
+export * from './interface';
+```
+
+### Rules
+
+- Import default + re-export named + re-export default + re-export types
+- This pattern ensures both `import {Name}` and `import { {Name} }` work
+- `export *` from interface re-exports all type definitions
+
+---
+
+## 4. `{Name}.stories.tsx` — Storybook Stories
+
+```tsx
+import React from 'react';
+import { fn } from '@storybook/test';
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { {Name} } from './index';
+
+// Import styles for Storybook rendering
+import './style';
+
+// Define variant constants as `as const` for type safety and reuse
+const COLORS = ['primary', 'secondary', 'grey', 'black', 'white', 'danger', 'warning'] as const;
+const SIZES = ['large', 'medium', 'small'] as const;
+
+const meta: Meta<typeof {Name}> = {
+  title: 'Components/{Name}',
+  component: {Name},
+  argTypes: {
+    // Boolean controls
+    disabled: { control: 'boolean' },
+    loading: { control: 'boolean' },
+    // Radio controls for variant props — spread the const array
+    size: { control: 'radio', options: [...SIZES] },
+    color: { control: 'radio', options: [...COLORS] },
+  },
+  args: {
+    // Sensible defaults for the controls panel
+    disabled: false,
+    loading: false,
+    size: 'medium',
+    color: 'primary',
+    onClick: fn(),
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof {Name}>;
+
+// ---- AllVariants ----
+// Matrix of ALL size x color combinations for visual QA
+// Tagged '!autodocs' to exclude from auto-generated docs
+// Tagged 'dev' for developer-only visibility
+export const AllVariants: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
+      {SIZES.map(size => (
+        <div key={size}>
+          <h3 style={{ marginBottom: 12 }}>{size}</h3>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }}>
+            {COLORS.map(color => (
+              <{Name} {...args} key={`${size}-${color}`} size={size} color={color}>
+                {color}
+              </{Name}>
+            ))}
+          </div>
+          {/* Disabled row */}
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center', marginTop: 8 }}>
+            {COLORS.map(color => (
+              <{Name} {...args} key={`${size}-${color}-disabled`} size={size} color={color} disabled>
+                {color}
+              </{Name}>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+  args: {
+    children: undefined,
+  },
+  tags: ['!autodocs', 'dev'],
+};
+
+// ---- Feature-specific stories ----
+export const Sizes: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      {SIZES.map(size => (
+        <{Name} {...args} key={size} size={size}>
+          {size}
+        </{Name}>
+      ))}
+    </div>
+  ),
+};
+```
+
+### Rules
+
+- Import `fn` from `@storybook/test` for action callbacks (not `action` from `@storybook/addon-actions`)
+- Meta title follows `Components/{Name}` convention
+- Meta must include `tags: ['autodocs']`
+- Variant constants are `as const` arrays spread into options
+- `AllVariants` story always has `tags: ['!autodocs', 'dev']`
+- At minimum: `AllVariants` + one feature story
+
+---
+
+## 5. `style/{Name}.scss` — Component Styles
+
+```scss
+@use '@/styles/api' as theme;
+@use '@/styles/recipes/variants' as variants;
+
+$component: '{kebab-name}';
+
+// ── Variant DSL ──
+// 1. Schema: auto-generate from component name + token key list
+// Expands to: (--om-{kebab-name}-text: text, --om-{kebab-name}-bg: bg, ...)
+$component-variant-schema: variants.om-variant-schema(
+  $component, text, bg, hover-bg, disabled-text, disabled-bg
+);
+
+// 2. Variants map: each variant defines all keys from the schema
+$component-variants: (
+  'primary': (
+    text: theme.palette(text, 'on-neutral'),
+    bg: theme.palette(bg, 'brand'),
+    hover-bg: theme.palette(bg, 'brand-hover'),
+    disabled-text: theme.palette(text, 'disabled-white'),
+    disabled-bg: theme.palette(bg, 'disabled-brand'),
+  ),
+  'secondary': (
+    text: theme.palette(text, 'brand'),
+    bg: theme.palette(bg, 'brand-secondary'),
+    hover-bg: theme.palette(bg, 'brand-secondary-hover'),
+    disabled-text: theme.palette(text, 'brand-secondary'),
+    disabled-bg: theme.palette(bg, 'brand-tertiary'),
+  ),
+  // ... more variants
+);
+
+// Root selector — generates: .om-react-ui-{kebab-name}
+.#{theme.$prefix}-#{$component} {
+  // 3. Apply default variant + validate all variants against schema
+  @include variants.om-variant-default($component-variants, 'primary', $component-variant-schema);
+
+  // ── Base styles — consume variant CSS custom properties ──
+  display: inline-flex;
+  gap: theme.spacing(gap, 200);
+  align-items: center;
+  justify-content: center;
+  padding: theme.spacing(component-padding, 400);
+  color: var(--om-{kebab-name}-text);
+  background-color: var(--om-{kebab-name}-bg);
+  border: none;
+  border-radius: theme.shape(300);
+  box-shadow: none;
+  cursor: pointer;
+
+  // Typography — emits font-family, font-size, line-height, etc.
+  @include theme.typography(label, lg);
+
+  // ── Disabled — reads variant custom properties ──
+  &.p-disabled {
+    color: var(--om-{kebab-name}-disabled-text);
+    background-color: var(--om-{kebab-name}-disabled-bg);
+    cursor: not-allowed;
+  }
+
+  // ── Hover — reads variant custom property ──
+  &:hover:not(.p-disabled) {
+    background-color: var(--om-{kebab-name}-hover-bg);
+  }
+
+  // ── Size variants ──
+  // Use &-{size} for variant classes
+  &-medium {
+    padding: theme.spacing(component-padding, 300);
+    border-radius: theme.shape(300);
+    @include theme.typography(label, md);
+  }
+
+  &-small {
+    padding: theme.spacing(component-padding, 200);
+    border-radius: theme.shape(200);
+    @include theme.typography(label, sm);
+  }
+
+  // ── Slot styles ──
+  &-icon-start,
+  &-icon-end {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  // ── Color variants (Variant DSL) ──
+  // Generate all modifier classes, skipping the default 'primary' variant
+  @include variants.om-variant-classes($component-variants, $component-variant-schema, $default: 'primary');
+
+  // ── Responsive ──
+  // @include theme.down(md) { ... }
+}
+```
+
+### SCSS Rules
+
+- First lines: `@use '@/styles/api' as theme;` and `@use '@/styles/recipes/variants' as variants;` (if using variants)
+- `$component` is always kebab-case
+- Root: `.#{theme.$prefix}-#{$component}` (do NOT hardcode `om-react-ui`)
+- **Color variants**: Use the Variant DSL (`variants.om-variant-schema` + `variants.om-variant-default` + `variants.om-variant-classes`) with CSS custom properties instead of manual `&-{variant}` blocks for each color
+- **Size variants**: Use `&-{size}` nesting (these remain manual since they change structural properties, not just colors)
+- Disabled: target `.p-disabled` class (PrimeReact adds this)
+- Hover: `&:hover:not(.p-disabled)` to skip disabled elements
+- All values use token functions — no raw hex, px (for tokens), or font-family
+- Exception: `!important` overrides on third-party (PrimeReact) styles are acceptable when necessary
+- Variant names must be quoted strings (e.g., `'white'`, `'black'`) to avoid Sass color literal issues
+
+---
+
+## 6. `style/index.ts` — Style Entry Point
+
+```ts
+import './{Name}.scss';
+```
+
+Single line. This file is imported in stories and by the build system.
+
+---
+
+## 7. `__test__/index.test.tsx` — Snapshot Test
+
+```tsx
+import 'jsdom-global/register';
+import * as React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { {Name} } from '../index';
+
+// Suppress known console errors from PrimeReact/JSDOM incompatibility
+const originalConsoleError = console.error;
+console.error = (message, ...optionalParams) => {
+  const errorMessage = typeof message === 'string' ? message : String(message);
+  if (
+    errorMessage.includes('Could not parse CSS stylesheet') ||
+    errorMessage.includes('findDOMNode is deprecated and will be removed')
+  ) {
+    return;
+  }
+  originalConsoleError(message, ...optionalParams);
+};
+
+// Mock lottie-web if any component in the dependency chain uses Loading/Spinner
+jest.mock('lottie-web', () => ({
+  loadAnimation: jest.fn(() => ({
+    play: jest.fn(),
+    pause: jest.fn(),
+    destroy: jest.fn(),
+  })),
+}));
+
+describe('{Name}', () => {
+  it('renders correctly', () => {
+    const wrapper = render(
+      <{Name}>Test</{Name}>
+    );
+    expect(wrapper).toMatchSnapshot();
+  });
+});
+```
+
+### Rules
+
+- Always import `jsdom-global/register` first
+- Always suppress the two known console errors
+- Always mock `lottie-web` (safe even if not needed)
+- At minimum: one `renders correctly` snapshot test
+- Optionally add tests for variants, events, disabled state
+
+---
+
+## 8. `README.md` — Component Documentation
+
+```md
+# {Name}
+
+Brief description of what the component does and when to use it.
+
+## Import
+
+\```tsx
+import { {Name} } from '@1money/components-ui';
+// or
+import { {Name} } from '@1money/components-ui/{Name}';
+\```
+
+## Usage
+
+\```tsx
+<{Name} color="primary" size="medium">
+  Click me
+</{Name}>
+\```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'primary' \| 'secondary' \| ...` | `'primary'` | Visual color variant |
+| `size` | `'large' \| 'medium' \| 'small'` | `'medium'` | Size variant |
+| `disabled` | `boolean` | `false` | Disables the component |
+| `loading` | `boolean` | `false` | Shows loading spinner |
+| `prefixCls` | `string` | `'{kebab-name}'` | CSS class prefix |
+| `className` | `string` | `''` | Additional CSS classes |
+```
+
+---
+
+## Library Registration (`src/index.ts`)
+
+After creating all component files, update the barrel export:
+
+```ts
+// Add re-export for the component (alphabetical order)
+export { {Name} } from './components/{Name}';
+
+// Add type re-export
+export type { {Name}Props } from './components/{Name}';
+```
+
+Note: The current `src/index.ts` uses only re-export statements — there is no import block and no default export object.

package/.agents/skills/1money-component-dev/references/FigmaExtractionChecklist.md

@@ -0,0 +1,144 @@
+# Figma Extraction Checklist
+
+Checklist for extracting design data from Figma when building new `@1money/components-ui` library components. Adapted for library-internal development where Figma tokens must map to the internal style system (not consumer-facing Foundation tokens).
+
+---
+
+## Pre-flight
+
+- [ ] Figma URL is a design or node link (not a prototype or FigJam board)
+- [ ] Node ID is known, or top-level frames have been listed and the user has selected one
+- [ ] Component name confirmed (PascalCase)
+
+## Extraction Steps
+
+### Step 1 — Get Design Context
+
+```
+mcp__figma__get_design_context(nodeId, fileKey)
+```
+
+- [ ] Call returned valid data (code + screenshot)
+- [ ] If MCP returned empty or errors, retried once before reporting failure
+- [ ] Noted the reference code structure (React+Tailwind hints) for mapping guidance
+
+### Step 2 — Get Screenshot
+
+```
+mcp__figma__get_screenshot(nodeId, fileKey)
+```
+
+- [ ] Called for any frame where layout, spacing, or alignment is ambiguous
+- [ ] Screenshot reviewed for: padding, gap, border-radius, shadow, alignment
+- [ ] Visual hierarchy and nesting structure understood
+
+### Step 3 — Get Variable Definitions
+
+```
+mcp__figma__get_variable_defs(nodeId, fileKey)
+```
+
+- [ ] Design tokens retrieved (colors, spacing, radii, typography)
+- [ ] Figma variable names noted for mapping to internal style system
+
+### Step 4 — Get Metadata (if no Node ID)
+
+```
+mcp__figma__get_metadata(nodeId, fileKey)
+```
+
+- [ ] Top-level frames listed
+- [ ] User selected the target frame
+- [ ] Re-run Steps 1-3 with the selected Node ID
+
+## Token Mapping Phase
+
+Map every Figma design value to the internal style system. Consult `StyleSystemAPI.md` and `SemanticColors.md`.
+
+### Colors
+
+- [ ] Background fills mapped to `theme.palette(bg, ...)` keys
+- [ ] Text colors mapped to `theme.palette(text, ...)` keys
+- [ ] Icon colors mapped to `theme.palette(icon, ...)` keys
+- [ ] Border colors mapped to `theme.palette(border, ...)` keys
+- [ ] No raw hex values remain unmapped
+
+### Spacing
+
+- [ ] Padding values mapped to `theme.spacing(component-padding, key)` or `theme.spacing(scale, key)`
+- [ ] Gap values mapped to `theme.spacing(gap, key)`
+- [ ] Margin values mapped to `theme.spacing(scale, key)`
+- [ ] No raw pixel values for spacing remain unmapped
+
+### Typography
+
+- [ ] Font family, size, weight, line-height identified per text layer
+- [ ] Mapped to `@include theme.typography(category, size)` — find the closest match from:
+  - `display`: xl/lg/md/sm/xs (Aeonik)
+  - `headline`: lg/md/sm/xs (Aeonik)
+  - `title`: lg/md/sm (Inter, strong=700)
+  - `body`: lg/md/sm (Inter, strong=500)
+  - `link`: md/sm (Inter)
+  - `label`: xl/lg/md/sm/xs (Inter, strong=600-700)
+- [ ] Any `$strong: true` variants identified
+
+### Visual Properties
+
+- [ ] Border-radius mapped to `theme.shape(key)` keys (0/100/200/300/400/600/full)
+- [ ] Box-shadow mapped to `theme.shadows(key)` keys (0/100/200)
+- [ ] Opacity mapped to `theme.opacity(key)` keys
+- [ ] Component heights mapped to `theme.sizing(component-height, key)` keys (xs/sm/md/lg/xl/2xl/3xl)
+
+## Variant Identification
+
+- [ ] All visual variants listed (e.g., color variants: primary, secondary, danger, etc.)
+- [ ] All size variants listed (e.g., large, medium, small)
+- [ ] Variant naming aligned with existing library conventions (check Button for reference)
+- [ ] Each variant's token mapping documented
+
+## Slot Identification
+
+- [ ] Content slots identified (e.g., `children`, `label`, `description`)
+- [ ] Icon slots identified (e.g., `iconStart`, `iconEnd`, `icon`)
+- [ ] Custom render slots identified (e.g., `header`, `footer`, `prefix`, `suffix`)
+- [ ] Each slot typed as `ReactNode` in the interface
+
+## State Coverage Assessment
+
+### Required States (implement even if not in Figma)
+
+- [ ] **Default**: Normal resting state
+- [ ] **Hover**: `:hover:not(.p-disabled)` interaction
+- [ ] **Focus**: `:focus-visible` interaction (if applicable)
+- [ ] **Active**: `:active` interaction (if applicable)
+- [ ] **Disabled**: `.p-disabled` class with `cursor: not-allowed` and muted colors
+- [ ] **Loading**: Spinner integration (if applicable)
+
+### Conditional States (implement if component type requires)
+
+- [ ] **Error/Danger**: Validation error state with danger colors
+- [ ] **Warning**: Warning state with warning colors
+- [ ] **Success/Positive**: Success state with positive colors
+- [ ] **Selected/Active**: Toggle or selection state
+- [ ] **Empty**: Empty/placeholder state
+
+## Unmapped Items
+
+- [ ] All Figma nodes that could not be mapped are listed explicitly
+- [ ] Blocking ambiguities escalated to the user before implementation
+- [ ] Asset placeholders documented for images/icons without a component match
+
+## Summary Table Template
+
+Use this table format to document the mapping:
+
+```markdown
+| Figma Element | Figma Value | Style System Function | Key |
+|---------------|-------------|----------------------|-----|
+| Background | #1D4ED8 | `theme.palette(bg, ...)` | `brand` |
+| Text | #FFFFFF | `theme.palette(text, ...)` | `on-neutral` |
+| Padding | 16px | `theme.spacing(component-padding, ...)` | `400` |
+| Border radius | 12px | `theme.shape(...)` | `300` |
+| Height | 52px | `theme.sizing(component-height, ...)` | `2xl` |
+| Typography | Inter 14/500 | `theme.typography(...)` | `label, md` |
+```