| name | chameleon-controls-library |
| description | Builds UIs with Chameleon web components (ch-*). Use when the user mentions Chameleon, ch- components, or needs enterprise UI patterns like grids, trees, chat, sidebars, accordions, combos, tabs, dialogs, or forms. Also use for: implementing a UI from Figma or images, vibe coding a UI, migrating an existing UI to Chameleon, or auditing Chameleon usage in an application. |
| metadata | {"version":"0.3.0"} |
Chameleon Controls Library
Build UIs with Chameleon web components. This skill covers component selection, structure, wiring, usage, and styling of individual components. For Design System-level patterns (tokens, class naming, theme architecture), use the design-system-builder skill
Workflow
The workflow is a sequence of phases. Depending on the task, you can enter at any phase, skip phases that don't apply, and jump back to earlier phases to fix issues. Phases A and B always run in parallel at the start
┌─────────────────────────────────────────────────────────────┐
│ [Entry Point] │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ▼ ▼ │
│ A: Gain Context B: Installation │
│ └─────────────┬─────────────┘ │
│ ▼ │
│ C: Understand the UI │
│ ┌──────┬───────┬───────┬──────┐ │
│ C1 C2 C3 C4 C5 │
│ Figma Image Text Migration Audit─────┐ │
│ └──────┴───────┴───────┘ │ │
│ │ │ │
│ ▼ │ │
│ D: Component Selection │ │
│ │ │ │
│ ▼ │ │
│ E: Understand Component APIs │ │
│ │ │ │
│ ▼ │ │
│ F: Styling Strategy │ │
│ │ │ │
│ ▼ │ │
│ G: Code Implementation │ │
│ │ │ │
│ ▼ │ │
│ H: Audit ◄──────────────────────┘ │
│ │ ▲ │
│ │ │ fix issues │
│ │ └──────┘ │
│ ▼ │
│ [Done] │
└─────────────────────────────────────────────────────────────┘
Phase A — Gain Context (parallel with B)
Detect before writing any code:
- Framework — What framework is the project using? (e.g., Angular, React, Stencil, vanilla JS/TS, Lit/Kasstor, etc.)
- Existing code — What components, structure, and patterns are already in place?
- Design System — Is there a DS built on Chameleon? Check for
ch-theme, getBundles, DS CSS files
This is observational — no reference files needed
Phase B — Installation Check (parallel with A)
Read Installation guide. Verify Chameleon is installed and configured for the detected framework. If not installed, follow the guide
Do not proceed to Phase C until installation is confirmed
Phase C — Understand the UI
Choose the sub-entry that matches the task. All sub-entries converge on the same output: a semantic understanding of each UI element — what it is, how it's used, how keyboard users reach it, and how elements interact
C1: From Figma
Analyze Figma frames. Identify visual elements and their semantic roles (navigation, data entry, data display, action triggers, feedback, etc.)
C2: From an image
Analyze the visual. Map each visible element to its semantic purpose. Identify layout structure, component boundaries, and interactive elements
C3: From text, audio, or description
Parse the user's description. Identify the UI elements described, their relationships, and the interactions expected
C4: Migration from existing UI
Analyze the current implementation. Map existing HTML elements and third-party components to Chameleon equivalents. Identify what can be replaced 1:1 and what requires restructuring
C5: Audit only
Skip directly to Phase H
Phase D — Component Selection
Read Components index. For every UI element identified in Phase C, look up the matching component:
- Read its "When to use" and "When NOT to use" columns
- Never pick a component from memory — always verify against the index
- If a native HTML element (
<select>, <input>, etc.) is chosen instead of a Chameleon component, state the explicit reason before proceeding
When a component does not exist in Chameleon:
- Chameleon does not wrap
<button> or <a> — use native HTML elements for buttons and links. When a Design System is active, apply its CSS classes
- For more complex missing components, compose from existing Chameleon components and/or build a custom component using the kasstor skill (if available) for cross-framework web components
Icons and images:
- Read Icons & Images guide to choose the right technique: semantic (
<img> with alt) vs decorative (CSS, ch-image), mask-image for themeable icons, startImgSrc/endImgSrc for component item models
- For global icon resolution, Read Registry to register
getImagePathCallback once instead of per-instance
Phase E — Understand Component APIs
For each selected component, Read its documentation in order:
references/components/{component}/README.md — Properties, events, methods, slots, dependenciesreferences/components/{component}/usage.md — Usage examples, patterns, do's and don'ts
For TypeScript types used in properties and events, consult the Types index
Phase F — Styling Strategy
Follow this decision tree to determine how to style each component:
Has a Design System built on Chameleon?
├─ YES → Check the DS component guide for this component
│ ├─ Guide exists → Use it (DS handles classes, tokens, ::part())
│ └─ Guide missing → Is design-system-builder skill available?
│ ├─ YES → Use it to create the component's DS styles
│ └─ NO → Read the component's styling.md (see below)
│
└─ NO → Is design-system-builder skill available?
├─ YES → Use it to scaffold a Design System
└─ NO → Read the component's styling.md (see below)
When using component styling directly:
- Read
references/components/{component}/styling.md — Shadow parts, CSS custom properties, shadow DOM layout, styling recipes, anti-patterns
- Read CSS Shadow Parts Guide — General
::part() rules, state parts pattern, exportparts, limitations
- To understand the shadow DOM layout diagrams, consult Layout Syntax
Phase G — Code Implementation
Build the UI with Chameleon components (ch-*), applying the properties, events, styles, icons, and patterns determined in prior phases
- Use
<button> and <a> for buttons and links — Chameleon does not wrap these
- Follow the frontend-best-practices skill if active
Phase H — Audit
Verify the implementation against this checklist. This phase is also the direct entry point from C5 (audit-only mode)
- Tags exist — Every
ch-* tag used exists in the library (cross-reference Components index)
- No invented APIs — All properties, events, and methods used are documented in the component's
README.md. No guessed or assumed API names
- Valid slots — All slot names used are valid according to the component docs and the context of use
- Valid styles — All
::part() selectors reference parts that exist in the component's styling.md. All CSS custom properties used are documented. If a DS is active, verify classes match the DS documentation
- Best practices — The implementation follows Accessibility, Performance, and SEO guidelines. The frontend-best-practices skill was consulted for general code quality
- No anti-patterns — The implementation does not violate any "When NOT to use", "Do not use when", or anti-patterns listed in the component's
usage.md and styling.md
- Fix and re-audit — If any check fails, fix the issue (returning to phases D-G as needed) and re-audit until all checks pass
Component catalog
Chameleon provides 58 components across 11 categories. It intentionally does not wrap every HTML element — buttons (<button>) and links (<a>) use native HTML with Design System CSS classes
For the complete catalog with descriptions, use cases, and anti-patterns for every component, consult the Components index
Categories at a glance:
| Category | Count | Key components |
|---|
| Layout | 4 | ch-theme, ch-flexible-layout-render, ch-layout-splitter, ch-sidebar |
| Forms | 9 | ch-edit, ch-checkbox, ch-combo-box-render, ch-radio-group-render, ch-slider, ch-switch, ch-color-picker, ch-color-field, ch-rating |
| Data Display | 8 | ch-accordion-render, ch-action-list-render, ch-action-menu-render, ch-tree-view-render, ch-tab-render, ch-segmented-control-render, ch-navigation-list-render, ch-action-group-render |
| Overlays | 3 | ch-dialog, ch-tooltip, ch-popover |
| Content | 5 | ch-markdown-viewer, ch-code, ch-math-viewer, ch-image, ch-textblock |
| Grid / Tabular | 18 | ch-tabular-grid + 14 subcomponents, ch-smart-grid, ch-virtual-scroller, ch-tabular-grid-render |
| Editors | 2 | ch-code-editor, ch-code-diff-editor |
| Feedback & Loading | 2 | ch-progress, ch-status |
| Chat & Real-time | 2 | ch-chat, ch-live-kit-room |
| Pagination | 1 | ch-paginator-render |
| Utilities | 4 | ch-qr, ch-barcode-scanner, ch-intersection-observer, ch-shortcuts |
Best practices
- Accessibility: Prefer visible
<label> elements linked via for/id over the accessible-name property — labels are visible and provide better UX. Chameleon form components support ElementInternals, so a <label for="X"> with a matching id="X" on the component works natively. Use accessible-name only when a visible label is not possible (e.g., icon-only controls). Use close-button-accessible-name on dialogs. See Accessibility
- Performance: Use virtualization for long lists (
ch-virtual-scroller, ch-tabular-grid-virtual-scroller). Lazy-load heavy components (ch-code-editor, ch-code-diff-editor, ch-math-viewer, ch-chat). See Performance
- SEO: Keep critical content in static HTML. Use semantic elements. See SEO
Critical rules
- Never pick components from memory — always consult Components index
- Native HTML over Chameleon requires a stated reason — if
<select>, <input>, or another native element is chosen instead of a Chameleon component, explain why before proceeding
ch-theme is always hidden — never place children inside it. Use it as a sibling element- Use
<button> and <a> for buttons and links — Chameleon intentionally does not wrap these elements
- Read component docs before writing code — never assume API shapes. Properties, events, slots, and parts must be verified
Installation
Framework-specific setup:
References
