Coherence UI Skill

Build UIs using the Coherence Design System — Microsoft's component library for C+AI products.

Default output: React. Always generate React components using the @charm-ux/cui/react wrappers unless the user explicitly asks for plain HTML web components or another format.

Quick Reference

• •Package: @charm-ux/cui
• •React import (preferred): import { CuiButton } from '@charm-ux/cui/react'
• •Web component import (alternate): import '@charm-ux/cui/dist/components/<name>/index.js'
• •Tag prefix (web components): cui- (e.g. cui-button, cui-dialog)
• •React naming convention: Cui + PascalCase component name (e.g. CuiButton, CuiCard, CuiDialog)
• •Design system site: https://coherence-ftekb0dcfpcjb3gv.b02.azurefd.net

Data Sources

Three complementary sources provide a complete picture of every component and the design system. Consult the relevant source(s) for the task at hand.

1. Live API Manifest (primary — source of truth for API)

URL: https://coherence-ftekb0dcfpcjb3gv.b02.azurefd.net/cdn/latest/custom-elements.json

Fetch this URL to get the machine-readable API for any component. It follows the Custom Elements Manifest schema. For each component it provides:

• •Attributes — exact names, types, defaults, descriptions
• •Events — names, detail types
• •Slots — names, descriptions
• •CSS Custom Properties — all themeable hooks
• •CSS Parts — all styleable internal parts
• •Dependencies — which sub-components are auto-registered
• •Class hierarchy — superclass and inherited members

How to look up a component: Find the module whose path matches src/components/<slug>/<slug>.ts, then read its declarations array for the entry with customElement: true.

Example: to look up cui-button, find the module with path: "src/components/button/button.ts" → its declaration is CuiButton.

2. Theme CSS — Design Tokens (source of truth for theming, colors, spacing, typography)

URL: https://coherence-ftekb0dcfpcjb3gv.b02.azurefd.net/cdn/latest/themes/cui/theme.css

Fetch this URL when answering questions about design tokens, theming, colors, spacing, typography, shadows, borders, animation timing, or component-level CSS variables. This auto-generated CSS file defines all CSS custom properties on :root / :host and is the single source of truth for token names and values.

What it contains:

How the theme CSS relates to component reference docs:

The theme CSS defines global defaults for ~578 tokens. Of those, about 51 are also documented in component reference files (mainly --button-*, --form-control-*, and --default-border). Component reference docs additionally list component-specific CSS custom properties (e.g. --accordion-item-*, --card-*, --dialog-*, --checkbox-*) that are not in the theme CSS — those are defined inside individual component stylesheets and can still be overridden. Use both sources together: the theme CSS for token values/names and the component refs for per-component override hooks.

When to fetch: Any time the user asks about available colors, spacing values, font sizes, shadow levels, how to theme a component, what CSS variables exist, or when you need the exact token name/value for a style.

3. Design Guidance References (supplementary — design, UX, and examples)

The reference docs below contain information the manifest does not have:

• •When to use / when not to use a component
• •Anatomy diagrams and layout rules
• •Dos and don'ts
• •Accessibility guidance specific to the component
• •Code examples showing composition patterns
• •Content/writing guidelines

Workflow

When the user asks to build UI or use a Coherence component:

1. •Identify the component(s) needed from the index below or the manifest
2. •Fetch the manifest to get the precise API (attributes, types, defaults, slots, events, CSS properties, dependencies)
3. •Read the component reference file (if one exists) for design guidance, dos/don'ts, accessibility rules, and code examples
4. •Combine both — use guidance to decide how to compose the UI; use the manifest as the source of truth for exact attribute names, types, and values
5. •If no reference file exists, the manifest alone is sufficient for API usage — apply general Coherence accessibility and layout rules from the guides below
6. •For theming, colors, spacing, typography, or shadows — fetch the theme CSS to get the exact token names and values
7. •Output React by default — generate a React component (.tsx) using @charm-ux/cui/react wrappers. Only output plain HTML web components (<cui-*>) if the user explicitly requests it.

When composing a full page or layout, also read the relevant template and task flow references.

Component Index

Reference files contain design guidance and code examples only — not API details. Always fetch the manifest for API data.

Components with a reference file (66 — guidance available):

Components in the manifest only (API-only — no design guidance doc yet):

Templates

Page-level layout patterns. Read before composing full pages.

Task Flows

Multi-step interaction patterns. Read when implementing these specific user flows.

UX Guides

Cross-cutting design guidance. Read when the topic is relevant.

Common Patterns

React Component Usage (default)

import { CuiButton } from '@charm-ux/cui/react';

export function SaveButton() {
  return <CuiButton appearance="primary">Save</CuiButton>;
}

Slots in React

Web component slots map to React props with the same name. Use the slot attribute on child elements:

import { CuiButton, CuiIcon } from '@charm-ux/cui/react';

export function AddItemButton() {
  return (
    <CuiButton>
      <CuiIcon slot="start" name="add" />
      Add item
    </CuiButton>
  );
}

Event Handling in React

Coherence React wrappers expose events as camelCase callback props. Use the onEventName pattern:

import { CuiDialog, CuiButton } from '@charm-ux/cui/react';
import { useRef } from 'react';

export function ConfirmDialog() {
  const dialogRef = useRef<HTMLElement>(null);

  return (
    <CuiDialog
      ref={dialogRef}
      heading="Confirm"
      onDialogRequestClose={(e) => {
        // Optionally prevent close: e.preventDefault();
      }}
    >
      <p>Are you sure?</p>
      <CuiButton slot="footer" appearance="primary">Yes</CuiButton>
      <CuiButton slot="footer">Cancel</CuiButton>
    </CuiDialog>
  );
}

Show/Hide with Triggers

import { CuiButton, CuiDrawer } from '@charm-ux/cui/react';

export function SettingsDrawer() {
  return (
    <>
      <CuiButton shows="my-drawer">Open Drawer</CuiButton>
      <CuiDrawer id="my-drawer" heading="Settings">
        <p>Drawer content</p>
      </CuiDrawer>
    </>
  );
}

CSS Custom Properties

Override component styling via CSS custom properties (same in React and HTML):

cui-button {
  --button-bg-color: var(--colorBrandBackground);
  --button-fg-color: var(--colorNeutralForegroundOnBrand);
  --button-border-radius: 8px;
}

Web Component Usage (alternate — only when explicitly requested)

<script type="module">
  import '@charm-ux/cui/dist/components/button/index.js';
</script>
<cui-button appearance="primary">Save</cui-button>

Accessibility Rules

Every component meets the Microsoft Accessibility Standards (MAS). When composing UIs:

1. •Use cui-skip-to as the first tab stop on every page
2. •Assign landmarks (<main>, <nav>, <header>) for skip-to navigation
3. •Every interactive element must have a keyboard-accessible equivalent
4. •All button text must pass 4.5:1 contrast; icons must pass 3:1
5. •Labels cannot be substituted with placeholder text
6. •Use aria-label or heading text for dialogs and drawers
7. •Read references/guides/accessibility.md for comprehensive guidance

Previewing Components

A Vite + React preview app is set up at coherence-preview/. Use it to render any generated .tsx component in the browser.

Quick Start

1. •Import the component in coherence-preview/src/main.tsx:
   tsx

   import '@charm-ux/cui/dist/themes/cui/theme.css';
   import '@charm-ux/cui/dist/themes/cui/reset.css';
   import MyComponent from '../../MyComponent';
   

2. •Start the dev server: cd coherence-preview && npx vite
3. •Open the URL printed by Vite (usually http://localhost:5173)

The theme CSS imports provide all Coherence design tokens. The @charm-ux/cui/react wrappers auto-register their underlying web component definitions on first render.

Adding New Components to Preview

Edit coherence-preview/src/main.tsx — replace or add the component import and render it inside the root <div>. Vite HMR will update the browser automatically.

Icons & Fluent 2 Dependency

The cui-icon component relies on the Fluent 2 icon set. Icons referenced by name attribute must be registered first.

Critical: Import the Project Config

When generating code that uses <cui-icon name="..."> (or <CuiIcon name="..."> in React), you must ensure the project configuration is imported. Without it, icons will show a fallback question-mark and log a console warning.

For web components / plain HTML:

import '@charm-ux/cui/dist/project-config.js';
import '@charm-ux/cui/dist/components/icon/index.js';

For React: No extra import needed — the @charm-ux/cui/react wrappers auto-register icons.

For the preview app (coherence-preview/): Add this import to main.tsx:

import '@charm-ux/cui/dist/project-config.js';

Available Icon Names

After importing the project config, ~80 Fluent 2 icons are available. Common ones include: add, alert, attach, bookmark, bot, calendar, chat, checkmark, clock, comment, copy-filled, dismiss-circle, document-edit, error-circle, eye-off, filter-filled, like-filled, lock-closed, more-horizontal, pin-filled, star-filled, zoom-in, zoom-out.

See references/components/icon.md for the full list and custom icon registration.

Mapping to charm-pilot

When working in the local charm-pilot codebase (@charm-ux/core):

The design guidance, slots, attributes, events, and CSS properties documented in the Coherence references apply to both. The ch-* components in charm-pilot are built following the same Coherence specifications.