chi-recommendations

name	chi-recommendations
description	Recommend the best Chi implementation approach based on project context. Use when the user asks which Chi approach to use (Vue, Web Components, or HTML/CSS), when starting a new project with Chi, or when migrating between approaches. Provides framework-specific guidance and code examples.

Chi Implementation Recommendations

Decision Tree

Use this decision tree to recommend the best approach:

Step 1: Check Framework

Framework	Recommended Approach	Reasoning
Vue 3	chi-vue	Full Vue reactivity, composition API, TypeScript support
React	Custom Elements	Works with React; note: use ref callbacks for event listeners since React synthetic events don't fire on CEs
Angular	Custom Elements	Excellent support via CUSTOM_ELEMENTS_SCHEMA in module declarations
Svelte	Custom Elements	Seamless Custom Elements support
Vanilla JS	Custom Elements	Best DX, no framework overhead
Unknown	Custom Elements	Safe default for any framework

Step 2: Check Constraints

Constraint	Override To	Reasoning
Legacy browser support (IE11)	HTML/CSS	Custom Elements need polyfills
User explicitly wants CSS	HTML/CSS	Respect explicit preference
User wants Web Components	Custom Elements	Respect explicit preference
Static HTML site (no JS)	HTML/CSS	No JS runtime needed
SSR without hydration	HTML/CSS	Custom Elements need JS to initialize

Step 3: Determine Confidence

Scenario	Confidence
Framework detected + no conflicts	High
Existing code matches recommendation	High
No framework info, using default	Low
Existing code uses different approach	Medium (suggest gradual migration)

Code Examples

Vue Approach

<script setup>
import { ChiButton } from '@aspect/chi-vue';
</script>
<template>
  <ChiButton color="primary" size="lg" @click="handleClick">Click me</ChiButton>
</template>

Custom Elements Approach

<chi-button color="primary" size="lg">Click me</chi-button>
<script>
  document.querySelector('chi-button').addEventListener('chiClick', handleClick);
</script>

HTML/CSS Approach

<button class="chi-button -primary -lg" type="button" onclick="handleClick()">Click me</button>

Note: Requires manual event handling, ARIA attributes, and keyboard support.

Approach Detection

To detect which approach existing code uses:

Pattern	Approach
<Chi[A-Z] (PascalCase tags)	Vue
<chi- (kebab-case custom elements)	Custom Elements
class="chi- (CSS classes on native elements)	HTML/CSS

Count occurrences of each pattern. The most frequent one is the existing approach.

Edge case: <chi-icon> inside a <button class="chi-button"> is mixed usage -- recommend migrating the button to <chi-button> too.

Migration Paths

HTML/CSS → Custom Elements

1. Replace CSS base classes with Web Component tags: <button class="chi-button"> → <chi-button>
2. Convert CSS modifiers to properties: -primary → color="primary"
3. Convert boolean modifiers to attributes: -disabled → disabled
4. Keep utility classes for spacing: class="-p--4" stays
5. Remove manual ARIA -- Web Components handle it automatically

HTML/CSS → Vue

1. Install @aspect/chi-vue package
2. Import components: import { ChiButton } from '@aspect/chi-vue'
3. Replace HTML with Vue component syntax
4. Use v-bind for dynamic props, v-on for events

Custom Elements → Vue

1. Replace <chi-*> tags with <Chi*> components
2. Convert attributes to Vue props syntax
3. Migrate events from addEventListener to v-on

Vue → Custom Elements

1. Replace <Chi*> with <chi-*> Web Components
2. Convert Vue props to attributes
3. Replace v-on events with addEventListener
4. Handle reactivity manually if needed

Priority Order

1. chi-vue (priority 1) -- Vue 3 components for Vue projects
2. chi-web-components (priority 2) -- Custom Elements for any framework
3. chi-html-css (priority 3) -- CSS classes for static HTML or legacy support