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:

1. Framework — What framework is the project using? (e.g., Angular, React, Stencil, vanilla JS/TS, Lit/Kasstor, etc.)
2. Existing code — What components, structure, and patterns are already in place?
3. 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:

1. Read its "When to use" and "When NOT to use" columns
2. Never pick a component from memory — always verify against the index
3. 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:

1. references/components/{component}/README.md — Properties, events, methods, slots, dependencies
2. references/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)

1. Tags exist — Every ch-* tag used exists in the library (cross-reference Components index)
2. No invented APIs — All properties, events, and methods used are documented in the component's README.md. No guessed or assumed API names
3. Valid slots — All slot names used are valid according to the component docs and the context of use
4. 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
5. Best practices — The implementation follows Accessibility, Performance, and SEO guidelines. The frontend-best-practices skill was consulted for general code quality
6. 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
7. 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:

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:

• Installation index — React (Vite), Angular, Stencil, script tag

References