Ds Create Component

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

/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). Determines where the component is scaffolded: components/<category>/<name>/.
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:

• ✅ <component>.tsx — Stencil component with all props/events, basic render with <slot>
• ✅ <component>.interfaces.ts — TypeScript types and enums for props
• ✅ <component>.host.scss — Shadow DOM styles with design token structure and variants
• ✅ <component>.visual.html — Visual test file with sections for each variant
• ✅ Subcomponents (if specified) — Same structure inside <component>/<subcomponent>/

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-<component>-*) — 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/<category>/<name>/; 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 <slot> 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/<category>/<name>/, 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)