tomevault-io 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" 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
- Replace CSS base classes with Web Component tags:
<button class="chi-button">→<chi-button> - Convert CSS modifiers to properties:
-primary→color="primary" - Convert boolean modifiers to attributes:
-disabled→disabled - Keep utility classes for spacing:
class="-p--4"stays - Remove manual ARIA -- Web Components handle it automatically
HTML/CSS → Vue
- Install
@aspect/chi-vuepackage - Import components:
import { ChiButton } from '@aspect/chi-vue' - Replace HTML with Vue component syntax
- Use
v-bindfor dynamic props,v-onfor events
Custom Elements → Vue
- Replace
<chi-*>tags with<Chi*>components - Convert attributes to Vue props syntax
- Migrate events from addEventListener to
v-on
Vue → Custom Elements
- Replace
<Chi*>with<chi-*>Web Components - Convert Vue props to attributes
- Replace
v-onevents withaddEventListener - Handle reactivity manually if needed
Priority Order
- chi-vue (priority 1) -- Vue 3 components for Vue projects
- chi-web-components (priority 2) -- Custom Elements for any framework
- chi-html-css (priority 3) -- CSS classes for static HTML or legacy support
Converted and distributed by TomeVault — claim your Tome and manage your conversions.