|
| 1 | +--- |
| 2 | +name: component-scaffold |
| 3 | +description: Scaffold a new design system component with all required files, Ark UI integration, stories with play tests, and barrel export wiring. Use when the user asks to create, scaffold, or add a new component. |
| 4 | +--- |
| 5 | + |
| 6 | +# Component Scaffold Skill |
| 7 | + |
| 8 | +Scaffold a new design system component following all project conventions. |
| 9 | + |
| 10 | +## Input |
| 11 | + |
| 12 | +The user provides a component name (e.g., "tooltip", "progress-bar"). Normalize it to kebab-case for file names and PascalCase for code identifiers. |
| 13 | + |
| 14 | +- File prefix: `ds-{name}` (e.g., `ds-tooltip`) |
| 15 | +- Component name: `Ds{Name}` (e.g., `DsTooltip`) |
| 16 | +- Directory: `packages/design-system/src/components/ds-{name}/` |
| 17 | + |
| 18 | +## Steps |
| 19 | + |
| 20 | +### Step 1: Check Ark UI for an existing primitive |
| 21 | + |
| 22 | +Before writing any code, check if Ark UI already provides this component: |
| 23 | + |
| 24 | +1. Call the Ark UI MCP `list_components` tool with `framework: "react"`. |
| 25 | +2. If a matching component exists: |
| 26 | + - Call `get_component_props` with `framework: "react"` and the component name to get the full API. |
| 27 | + - Call `get_example` with `framework: "react"`, the component name, and `exampleId: "basic"` to get reference code. |
| 28 | + - Call `styling_guide` with the component name to get data attributes for SCSS. |
| 29 | + - Use the Ark primitive as the base. Do NOT expose all Ark props -- create an own props layer. |
| 30 | + - Do NOT duplicate Ark internal state with `useState`. |
| 31 | +3. If no matching component exists, build a custom implementation. |
| 32 | + |
| 33 | +### Step 2: Create the 5 component files |
| 34 | + |
| 35 | +All files go in `packages/design-system/src/components/ds-{name}/`. |
| 36 | + |
| 37 | +#### `ds-{name}.types.ts` |
| 38 | + |
| 39 | +```typescript |
| 40 | +import type { CSSProperties, ReactNode, Ref } from 'react'; |
| 41 | + |
| 42 | +export const ds{Name}Variants = ['...'] as const; |
| 43 | +export type Ds{Name}Variant = (typeof ds{Name}Variants)[number]; |
| 44 | + |
| 45 | +export interface Ds{Name}Props { |
| 46 | + // Value props first |
| 47 | + ref?: Ref<HTMLElement>; |
| 48 | + className?: string; |
| 49 | + style?: CSSProperties; |
| 50 | + children?: ReactNode; |
| 51 | + |
| 52 | + // Slot props |
| 53 | + locale?: { /* any hardcoded strings */ }; |
| 54 | + |
| 55 | + // Callbacks last |
| 56 | + onChange?: (value: unknown) => void; |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +Follow these rules: |
| 61 | + |
| 62 | +- Value/config props first, then slot/render props, then callbacks last. |
| 63 | +- Export variant arrays as `as const` for storybook argTypes. |
| 64 | +- Use `Ref<HTMLElement>` for the ref type. |
| 65 | +- Add `locale` prop if the component has any hardcoded user-facing text. |
| 66 | + |
| 67 | +#### `ds-{name}.tsx` |
| 68 | + |
| 69 | +```tsx |
| 70 | +import classNames from 'classnames'; |
| 71 | +import styles from './ds-{name}.module.scss'; |
| 72 | +import type { Ds{Name}Props } from './ds-{name}.types'; |
| 73 | + |
| 74 | +const Ds{Name} = ({ |
| 75 | + ref, |
| 76 | + className, |
| 77 | + style, |
| 78 | + children, |
| 79 | + ...rest |
| 80 | +}: Ds{Name}Props) => { |
| 81 | + return ( |
| 82 | + <div |
| 83 | + ref={ref} |
| 84 | + className={classNames(styles.root, className)} |
| 85 | + style={style} |
| 86 | + {...rest} |
| 87 | + > |
| 88 | + {children} |
| 89 | + </div> |
| 90 | + ); |
| 91 | +}; |
| 92 | + |
| 93 | +export default Ds{Name}; |
| 94 | +``` |
| 95 | + |
| 96 | +Follow these rules: |
| 97 | + |
| 98 | +- No `forwardRef` -- pass `ref` as a regular prop. |
| 99 | +- Use `classNames` for conditional classes, not template literals. |
| 100 | +- No unnecessary `useMemo` or `useCallback`. |
| 101 | +- If wrapping an Ark UI primitive, hook into its callbacks to forward to own props. Do not mirror its internal state. |
| 102 | + |
| 103 | +#### `ds-{name}.module.scss` |
| 104 | + |
| 105 | +```scss |
| 106 | +.root { |
| 107 | + display: flex; |
| 108 | + align-items: center; |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +Follow these rules: |
| 113 | + |
| 114 | +- Use design tokens: `--color-*`, `--spacing-*`, `--font-size-*`. |
| 115 | +- No hardcoded colors or spacing. |
| 116 | +- No `!important`. |
| 117 | +- No comments (unless genuinely complex). |
| 118 | +- Use `0.2s` for transitions. |
| 119 | +- Use `[data-focus-visible]` for focus states, `[data-disabled]` or `&:disabled` for disabled. |
| 120 | +- Keep component-specific CSS variables in this file, not in `_root.scss`. |
| 121 | +- Use `@mixin` for repeated patterns. |
| 122 | + |
| 123 | +#### `ds-{name}.stories.tsx` |
| 124 | + |
| 125 | +```tsx |
| 126 | +import type { Meta, StoryObj } from '@storybook/react-vite'; |
| 127 | +import { expect, fn, userEvent, within } from 'storybook/test'; |
| 128 | +import Ds{Name} from './ds-{name}'; |
| 129 | +import { ds{Name}Variants } from './ds-{name}.types'; |
| 130 | + |
| 131 | +const meta: Meta<typeof Ds{Name}> = { |
| 132 | + title: 'Design System/{Name}', |
| 133 | + component: Ds{Name}, |
| 134 | + parameters: { |
| 135 | + layout: 'centered', |
| 136 | + }, |
| 137 | + tags: ['autodocs'], |
| 138 | + argTypes: { |
| 139 | + variant: { control: 'select', options: ds{Name}Variants }, |
| 140 | + className: { table: { disable: true } }, |
| 141 | + style: { table: { disable: true } }, |
| 142 | + ref: { table: { disable: true } }, |
| 143 | + }, |
| 144 | +}; |
| 145 | + |
| 146 | +export default meta; |
| 147 | + |
| 148 | +type Story = StoryObj<typeof Ds{Name}>; |
| 149 | + |
| 150 | +export const Default: Story = { |
| 151 | + args: { |
| 152 | + onChange: fn(), |
| 153 | + }, |
| 154 | + play: async ({ canvasElement, args }) => { |
| 155 | + const canvas = within(canvasElement); |
| 156 | + // Add assertions using getByRole, getByText, getByLabelText |
| 157 | + // Use semantic assertions: toBeChecked, toBeDisabled, toBeVisible |
| 158 | + // Await all interactions |
| 159 | + }, |
| 160 | +}; |
| 161 | +``` |
| 162 | + |
| 163 | +Follow these rules: |
| 164 | + |
| 165 | +- Every story MUST have a `play` function. |
| 166 | +- Use `fn()` for all callback args. |
| 167 | +- Use a11y queries: `getByRole`, `getByLabelText`, `getByText`. Never `getByTestId`. |
| 168 | +- Import variant arrays from types for `argTypes.options`. |
| 169 | +- Hide internal args (`className`, `style`, `ref`) with `table: { disable: true }`. |
| 170 | +- No inline styles -- use `*.stories.module.scss` if needed. |
| 171 | +- Add stories for: Default, each variant, Disabled, Controlled (if applicable), Localized (if has `locale` prop). |
| 172 | + |
| 173 | +#### `index.ts` |
| 174 | + |
| 175 | +```typescript |
| 176 | +export { default as Ds{Name} } from './ds-{name}'; |
| 177 | +export type { Ds{Name}Props } from './ds-{name}.types'; |
| 178 | +``` |
| 179 | + |
| 180 | +Note: the barrel file uses `.ts` extension, not `.tsx`. |
| 181 | + |
| 182 | +### Step 3: Wire the barrel export |
| 183 | + |
| 184 | +Add the new component to `packages/design-system/src/index.ts` in **alphabetical order**: |
| 185 | + |
| 186 | +```typescript |
| 187 | +export * from './components/ds-{name}'; |
| 188 | +``` |
| 189 | + |
| 190 | +### Step 4: Validate |
| 191 | + |
| 192 | +Run the following commands from the workspace root: |
| 193 | + |
| 194 | +```bash |
| 195 | +pnpm eslint packages/design-system/src/components/ds-{name}/ |
| 196 | +pnpm --filter @drivenets/design-system typecheck |
| 197 | +``` |
| 198 | + |
| 199 | +Fix any errors before finishing. |
0 commit comments