--- name: ds-create-component description: Create new web components in the Helvetia Design System. Generates Stencil component files with shadow DOM, interfaces, SCSS with design tokens, and visual HTML. Use when building a new component, migrating from the old design system, or creating subcomponents. --- # ds-create-component Create new web components in the Helvetia Design System with a guided questionnaire. Generates all necessary files in one pass: `.tsx`, `.interfaces.ts`, `.host.scss`, and `.visual.html`. ## Quick Start ```bash /ds-create-component ``` The skill will ask you a series of questions to understand your component, then generate all files at once. ## Workflow ### 1. Answer the Questionnaire The skill asks: 1. **Component name** — e.g., `button`, `card`, `modal` 2. **Category** — one of `actions`, `forms`, `indicators`, `media`, `navigation`, `overlays`, `structure` (see the taxonomy in [packages/core/CONTEXT.md](../../packages/core/CONTEXT.md)). Determines where the component is scaffolded: `components///`. 3. **Component purpose** — What does it do? e.g., "Renders a clickable element with text and optional icon" 4. **Migration?** — Are you migrating from the old design system? If yes, provide the old component name - The skill auto-extracts props and events from the old component 5. **Props** — Define component properties (you can edit auto-extracted ones) - Format: `propName: PropType = defaultValue` (e.g., `label: string = ''`, `disabled: boolean = false`) 6. **Events** — Define custom events (you can edit auto-extracted ones) - Format: `dsEventName` (e.g., `dsClick`, `dsChange`) 7. **Subcomponents?** — Does this component have child components? (e.g., `tab` inside `tabs`) - If yes, list them (e.g., `tab, tab-content`) 8. **Variants** — List visual variants for your component (e.g., `primary, secondary, danger`) - The skill generates a visual HTML section for each variant ### 2. Skill Generates Files Once you answer all questions, the skill creates: - ✅ `.tsx` — Stencil component with all props/events, basic render with `` - ✅ `.interfaces.ts` — TypeScript types and enums for props - ✅ `.host.scss` — Shadow DOM styles with design token structure and variants - ✅ `.visual.html` — Visual test file with sections for each variant - ✅ **Subcomponents** (if specified) — Same structure inside `//` ### 3. Validation & Registration The skill: - ✅ **Pre-checks** — Warns if component already exists (you can overwrite) - ✅ **Validates tokens** — Scans generated SCSS for token usage: - ✅ Alias tokens (`--ds-alias-*`) — all good - ✅ Component tokens (`--ds--*`) — all good - ⚠️ Global tokens (`--ds-*` without alias prefix) — **warning** with recommendation to create an alias token - 🚫 Hardcoded values — flagged - ✅ **Registers component** — Adds to `packages/core/src/index.ts` - ✅ **Scaffolds the mirrored Storybook folder** — creates (empty) `apps/storybook/src/components///`; stories/MDX content is generated separately by `/ds-document-component` - ✅ **Migration handling** — If migrating from old design system: - Extracts props/events automatically - Flags a11y/SEO breaking changes - Generates accessible Shadow DOM structure (overrides old structure if needed) ### 4. Next Steps After generation, the skill prints: ``` ✅ Component created: packages/core/src/components/actions/button/ Storybook folder scaffolded: apps/storybook/src/components/actions/button/ Add stories/MDX with /ds-document-component. Next steps: 1. Review the generated component files 2. Refine render() logic and add your component-specific code 3. Update SCSS variants if needed 4. Run: pnpm play 5. Create tests with /ds-sync-component-tests ``` ## Rules Applied The skill enforces these design system rules: - ✅ **Web-only** — Creates Stencil components with shadow DOM (`.host.scss` only) - ✅ **Shadow DOM** — All components use `shadow: true` - ✅ **Accessibility** — Generates WCAG 2.2 AA compliant structure with `` for light DOM content - ✅ **Design tokens** — Uses alias tokens first, warns about globals - ✅ **Subcomponents** — Nested in parent folder (`tabs/tab.tsx`, not `tabs` and `tab` at same level) - ✅ **Category folder** — Scaffolded directly into `components///`, matching the folder's category taxonomy - ✅ **Component registration** — Automatically added to `packages/core/src/index.ts` - ✅ **Naming conventions** — `ds-` prefix, `ComponentInterface` + `Loggable` implementation (see STYLE_GUIDE.md) ## Examples ### Example 1: Simple Component (No Migration) ``` Q: Component name? A: badge Q: Category? A: indicators Q: Component purpose? A: Displays a small label with customizable color and size Q: Migration from old design system? A: no Q: Props? A: label: string = '', color: 'primary'|'secondary'|'danger' = '', size: 'sm'|'md'|'lg' = 'md' Q: Events? A: (none) Q: Subcomponents? A: no Q: Variants? A: primary, secondary, danger, small, medium, large ``` Result: Generated `badge.tsx`, `badge.interfaces.ts`, `badge.host.scss`, `badge.visual.html` ### Example 2: Component with Subcomponents (Migration) ``` Q: Component name? A: tabs Q: Category? A: navigation Q: Component purpose? A: Container for tab content with keyboard navigation and ARIA support Q: Migration from old design system? A: yes, old-tabs (skill auto-extracts props/events from old-tabs) Q: Props? (pre-filled from old-tabs, you review) A: (accept defaults) Q: Events? (pre-filled from old-tabs) A: (accept defaults) Q: Subcomponents? A: yes - tab - tab-panel Q: Variants? A: horizontal, vertical ``` Result: Generated: - `tabs.tsx`, `tabs.interfaces.ts`, `tabs.host.scss`, `tabs.visual.html` - `tabs/tab/tab.tsx`, `tabs/tab/tab.interfaces.ts`, `tabs/tab/tab.host.scss` - `tabs/tab-panel/tab-panel.tsx`, `tabs/tab-panel/tab-panel.interfaces.ts`, `tabs/tab-panel/tab-panel.host.scss` Plus warnings if old component used global tokens (e.g., _"⚠️ Using global token `--ds-color-primary`. Consider using alias token `--ds-alias-color-primary` or creating component token `--ds-tabs-color-primary`"_) ## What's NOT Included This skill **only generates components**. The following are handled by other skills: - ❌ **Tests** — Use `/ds-sync-component-tests` to create unit, interaction, visual, and a11y tests - ❌ **Storybook stories** — Create `.stories.ts` and `.mdx` files separately - ❌ **Type definitions** — Auto-generated when you run `pnpm build` ## Token Warnings When the skill validates tokens, it prints warnings like: ``` ⚠️ Token Issue: Global token used File: button.host.scss, line 25 Found: var(--ds-color-primary) Recommendation: 1. Use alias token instead: var(--ds-alias-color-primary) 2. Or create a component token: --ds-button-color-primary 3. Add to Base.tokens.json and re-run: pnpm tokens This is a warning only. You can proceed. See: docs/agents/domain.md (Design tokens section) ``` ## Troubleshooting **Q: "Component already exists" warning** A: The skill found an existing component. Review whether you should: - Use the existing component (check `/ds-find-component`) - Overwrite it (if intentional) - Create a subcomponent instead (nested in a parent) **Q: "No alias token available" warning** A: A design token (e.g., `--ds-alias-color-status`) doesn't exist yet. Either: - Use a different alias token that exists - Create a new alias token in `packages/tokens/tokens/Base.tokens.json` - Use a global token (with warning) as a temporary solution **Q: How do I refine the generated component?** A: The generated `.tsx` file has a basic `render()` with ``. Add: - Component logic in methods - Event handlers - State management if needed - Props validation (see STYLE_GUIDE.md) See [REFERENCE.md](REFERENCE.md) for template structure and patterns. ## See Also - [STYLE_GUIDE.md](../../docs/STYLE_GUIDE.md) — Code standards - [packages/core/CONTEXT.md](../../packages/core/CONTEXT.md) — Component patterns and lifecycle - [packages/tokens/CONTEXT.md](../../packages/tokens/CONTEXT.md) — Design tokens and naming - [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) — Component file structure and CSS variable cascade